system_cmds-643.30.1.tar.gz

[apple/system_cmds.git] / msa / msa.1

.Dd 3/7/14\r
.Dt msa 1\r
.Os Darwin\r
.Sh NAME\r
.Nm msa\r
.Nd Mach spy agency. Shows mach ipc, vouchers, importance boosts, etc.\r
.Sh SYNOPSIS             \" Section Header - required - don't modify\r
.Nm\r
.Op Fl ho\r
.Op Fl -help\r
.Op Fl -verbose\r
.Op Fl -version\r
.Op Fl -lifecycle Ar all | user | none\r
.Op Fl -mach-msg Ar all | user | voucher | none\r
.Op Fl -ouput Ar file\r
.Op Fl -raw-timestamps\r
.Op Fl -mach-absolute-time\r
.Op Fl -event-index\r
.Op Ar\r
.Sh DESCRIPTION\r
The\r
.Nm\r
command is used to observe voucher and importance propagation.\r
.Nm\r
displays mach message senders and receivers, message state (voucher, importance, reply expected, etc.) and receiver behavior such as refusing a voucher.\r
.Nm\r
shows process & thread lifecycle events, adoption & clearing of vouchers by threads, process importance count changes, and process DarwinBG state.\r
.Nm\r
uses the kernel trace facility and can be run live or against saved trace files.\r
.Pp\r
Options are as follows:\r
.Pp\r
\r
.Bl -tag -width -indent\r
.It Fl h, -help\r
Print help.\r
.It Fl -verbose\r
Print additional details and output.\r
.It Fl -version\r
Print version info.\r
.It Fl -lifecycle Ar all | user | none\r
Set the process and thread lifecycle filter level. The default is "user".\r
.Bl -tag -width -indent\r
.It all\r
Show kernel & userspace process and thread events\r
.It user\r
Show userspace process and thread events\r
.It none\r
Show no process and thread events\r
.El\r
.It Fl -mach-msg Ar all | user | voucher | none\r
Set the mach message sender/receiver filter level. The default is "voucher".\r
.Bl -tag -width -indent\r
.It all\r
Show all mach message senders/receivers\r
.It user\r
Show mach message senders/receivers where both the sender and receiver are in userspace\r
.It voucher\r
Show "interesting" mach message senders/receivers. An "interesting" message is any message containing a voucher, any message not containing a voucher if the sending thread has adopted a voucher, and any message carrying importance.\r
.It none\r
Show no mach message senders/receivers\r
.El\r
.It Fl o, -output Ar file\r
Write output to \r
.Ar file\r
.It Fl -raw-timestamps\r
Do not show time as a delta from the first trace event, print the actual time offsets.\r
.It Fl -mach-absolute-time\r
Do not translate time from mach absolute units to nanoseconds.\r
.It Fl -event-index\r
Print the index of each event.\r
.El\r
.Sh OUTPUT\r
.Nm\r
displays columns of data, the first five columns are fixed. The data after the fifth column depends on the type of event. Example output below (your terminal will need to be at least 200 characters wide to display this correctly):\r
\r
        Time(uS)          Type      Thread     ThreadVoucher                   Process  ;;  Message-From/To                  MsgID        MsgVoucher   DeliveryTime  FLAGS\r
         9304.56          send         8C2                 -          coreaudiod (236)  ;;  -> coreaudiod (236)                  2                 -              -  ONEWAY \r
         9346.52       impdelv         8A6                 -          coreaudiod (236)  ;;  linked to coreaudiod (236)'s live importance chain\r
         9349.02          recv         8A6                 -          coreaudiod (236)  ;;  <- coreaudiod (236)                  2  5EBD6CB68FF6401F          44.46  \r
         9361.50         adopt         8A6  5EBD6CB68FF6401F          coreaudiod (236)  ;;\r
\r
.Bl -tag -width -indent\r
.It The column headers have the following meanings:\r
.Bl -tag -width -indent\r
.It Time\r
The Time column displays the number of microseconds elapsed since\r
.Nm\r
started, or since the first event in the trace file. This value may be modified by\r
.Fl -raw-timestamps\r
or\r
.Fl -mach-absolute-time.\r
You might set these flags in order to correlate timestamps with output from another process that was printing mach_absolute_time() based timestamps.\r
.It Type\r
This describes the type of event being reported. Information to the right of the ';;' will vary based on this type.\r
.It Thread\r
The Thread column shows the thread id of the thread that generated the event. This is the thread id as displayed by\r
.Xr trace 1\r
and\r
.Xr kdprof 1\r
and may be cross correlated with trace events shown by either. Note that in some cases a thread in process A may cause changes in process B, for example a thread in Safari might raise the importance of a daemon.\r
.It ThreadVoucher\r
The ThreadVoucher column shows the id of any voucher currently adopted by the thread. This voucher id is the same identifier as shown by\r
.Xr lsmp 1 .\r
A '-' means that\r
.Nm\r
has not yet seen a voucher adopt for the thread. A NULL voucher is displayed as '0'.\r
.It Process\r
The Process column shows the name and pid of the process executing. The name is limited to 16 characters and may appear truncated.\r
.El\r
.It Mach message send/recv have the following additional column headers:\r
.Bl -tag -width -indent\r
.It Message-From/To\r
This field shows either the sender or the recipient of the message. The arrow at the beginning will indicate the direction the message is flowing. A '->' means sent to, a '<-' means received from. The name of the sender or recipient is limited to 16 characters and may appear truncated. Rarely, you may see '???' as the name, which means\r
.Nm\r
was unable to determine the source or destination of the message.\r
.It MsgID\r
The MsgID is a unique identifier for each mach message. A mach message has exactly one sender, and one receiver. However, a sending process may send several messages to a receiver before any are received. The MsgID allows disambiguation of exact message send and receipt time.\r
.It MsgVoucher\r
If this field is set, it shows the id of the voucher being carried by the mach message. Note that in some cases, the sender will show no voucher, but the receiver will have a voucher. This is the kernel providing a voucher for a process sending "old style" importance to a process that wants to receive vouchers.\r
.It DeliveryTime\r
This is the time it took to deliver the message, in uS. If the time cannot be calculated, it will show as '-'.\r
.It FLAGS\r
The FLAGS field will indicate various mach message behaviors:\r
.Bl -tag -width -indent\r
.It ONEWAY\r
This message cannot be replied to\r
.It MSGH_BITS_RAISED_IMPORTANCE\r
This message carries "old style" importance\r
.It VOUCHER-REFUSED\r
The message carried a voucher, and the receiver refused to accept it\r
.El\r
.El\r
.El\r
.Sh EXAMPLES\r
.Bl -tag -width -indent\r
.It Here are several examples of usage:\r
.Bl -tag -width -indent\r
.It msa | grep BOOST\r
This will show live boost/unboost behavior. Useful for watching what UI interactions will cause boosting.\r
.It msa | grep -e APP-NAME -e DAEMON-NAME -e OTHER-DAEMON-NAME\r
This will restrict output to only events dealing with an app and targetted daemons. This is useful to reduce the amount of data you need to watch.\r
.It trace -L /tmp/temp.trace; msa /tmp/temp.trace\r
This uses trace to capture a trace file for later analysis by msa.\r
.El\r
.El\r
.Sh SEE ALSO \r
.\" List links in ascending order by section, alphabetically within a section.\r
.\" Please do not reference files that do not exist without filing a bug report\r
.Xr kdprof 1 ,\r
.Xr lsmp 1,\r
.Xr trace 1\r
.\" .Sh BUGS              \" Document known, unremedied bugs\r
.\" .Sh HISTORY           \" Document history if command behaves in a unique manner