1.Dd November 2, 2014 2.Dt TRACE 1 3.Os 4.Sh NAME 5.Nm trace 6.Nd print process system calls and signals 7.Sh SYNOPSIS 8.Nm 9.Op Fl fgNsVv 10.Op Fl o Ar file 11.Op Fl p Ar pid 12.Op Ar command 13.Sh DESCRIPTION 14The 15.Nm 16utility shows one or more processes to be traced. 17For each traced process, 18.Nm 19prints the system calls the process makes and the signals 20it receives. 21The user can let 22.Nm 23start a 24.Ar command 25to be traced, and/or attach to one or more existing processes. 26.Pp 27The utility will run until no processes are left to trace, or until the user 28presses the interrupt key (typically Ctrl-C). 29Pressing this key once will cause all attached processes to be detached, with 30the hope that the command that was started will also terminate cleanly from the 31interruption. 32Pressing the interrupt key once more kills the command that was started. 33.Pp 34The following options are available: 35.Bl -tag -width XoXfileXX 36.It Fl f 37Follow forks. 38Attach automatically to forked child processes. 39Child processes of the started command will be treated as attached processes, 40in that upon Ctrl-C presses they will be detached rather than killed. 41.It Fl g 42Enable call grouping. 43With this option, the tracing engine tries to reduce noise from call preemption 44by first polling the process that was active last. 45This should reduce in cleaner output, but may also cause a single process to be 46scheduled repeatedly and thus cause starvation. 47.It Fl N 48Print all names. 49By default, the most structure fields are printed with their name. 50This option enables printing of all available names, which also includes 51system call parameter names. 52This flag may be useful to figure out the meaning of a parameter, and for 53automatic processing of the output. 54.It Fl s 55Print stack traces. 56Each system call, and each signal arriving outside a system call, will be 57preceded by a line showing the process's current stack trace. 58For signals blocked by the target process, the stack trace may not be 59meaningful. 60Stack traces may not be supported on all platforms. 61.It Fl V 62Print values only. 63If this flag is given once, numerical values will be printed instead of 64string constants. 65In addition, if it is given twice, the addresses of structures will be printed 66instead of their contents. 67.It Fl v 68Increase verbosity. 69By default, the output will be terse, in that not all structure fields are 70shown, and strings and arrays are not always printed in full. 71If this flag is provided once, more and longer output will be printed. 72If it is provided twice, the tracer will print as much as possible. 73.It Fl o Ar file 74Redirect output. 75By default, the output is sent to standard error. 76With this option, the output is written to the given 77.Ar file 78instead. 79.It Fl p Ar pid 80Attach to a process. 81This option makes 82.Nm 83attach to an existing process with process ID 84.Ar pid . 85This option may be used multiple times. 86When attaching to one or more processes this way, starting a command becomes 87optional. 88.El 89.Pp 90If the user presses the information key (typically Ctrl-T), the list of traced 91process along with their current status will be printed. 92.Sh OUTPUT FORMAT 93System calls are printed with the following general output format: 94.Bd -literal -offset indent 95.Sy name Ns ( Ns Sy parameters Ns ) = Sy result 96.Ed 97.Pp 98Other informational lines may be printed about the status of the process. 99These lines typically start with an uppercase letter, while system calls 100always start with a lowercase letter or an underscore. 101The following example shows the tracer output for a program that prints its 102own user ID: 103.Bd -literal -offset indent 104Tracing printuid (pid 12685) 105minix_getinfo() = 0 106getuid() = 0 (euid=1) 107write(1, "My uid: 0\en", 10) = 10 108exit(0) 109Process exited normally with code 0 110.Ed 111.Pp 112The first and last lines of the output provide status information about the 113traced process. 114Some calls return multiple results; extended results are printed in parentheses 115after the primary call result, typically in 116.Va name Ns = Ns Va value 117format for clarity. 118System calls that do not return on success, such as 119.Fn exit , 120are printed without the equals sign and result, unless they fail. 121System call failure is printed according to POSIX conventions; that is, the 122call is assumed to return -1 with the value of 123.Va errno 124printed in square brackets after it: 125.Bd -literal -offset indent 126setuid(0) = -1 [EPERM] 127.Ed 128.Pp 129If a system call ends up in an IPC-level failure, the -1 value will be preceded 130by an 131.Dq Li <ipc> 132string. 133However, this string will be omitted if the system call itself is printed at 134the IPC level (that is, as an 135.Fn ipc_sendrec 136call), generally because 137.Nm 138has no handler to print the actual system call. 139.Pp 140Signals are printed as they arrive at the traced process, using two asterisks 141on both side of the signal name. 142Signals may arrive both during and outside the execution of a system call: 143.Bd -literal -offset indent 144read(3, ** SIGUSR1 ** &0xeffff867, 4096) = -1 [EINTR] 145** SIGUSR2 ** 146getpid() = 5278 (ppid=5277) 147kill(5278, SIGTERM) = ** SIGTERM ** <..> 148Process terminated from signal SIGTERM 149.Ed 150.Pp 151Multiple signals may be printed consecutively. 152The above example illustrates a few other important aspects of output 153formatting. 154Some call parameters may be printed only after the system call returns, in 155order to show their actual value. 156For the 157.Fn read 158call, this would be the bytes that were read. 159Upon failure, no bytes were read, so the buffer pointer is printed instead. 160Finally, if a call that is expected to return (here, 161.Fn kill ) 162does not return before the process terminates, the line ends with a 163.Dq Li <..> 164marker. 165This is an instance of call preemption; more about that later. 166.Pp 167Pointers are printed with a 168.Sq Li & 169prefix, except for NULL, which is printed using its own name. 170In general, named constants are used instead of numerical constants wherever 171that makes sense. 172For pointers of which the address is not available, typically because its 173contents are passed by value, 174.Dq Li &.. 175is shown instead. 176.Pp 177Data buffers are printed as double-quoted strings, using C-style character 178escaping for nontextual bytes. 179If either the verbosity level or a copy error prevents the whole data buffer 180from being printed, two dots will be printed after the closing quote. 181The same is done when printing a string buffer which does not have a null 182termination byte within its range. 183Path names are shown in full regardless of the verbosity level. 184.Pp 185Structures are printed as a set of structure fields enclosed in curly brackets. 186The 187.Va name Ns = Ns Va value 188format is used, unless printing names for that structure type would introduce 189too much noise and the 190.Dq print all names 191option is not given. 192For many structures, by default only a subset of their fields are printed. 193In this case, a 194.Dq Li .. 195entry is added at the end. 196In some cases, an attempt is made to print only the most useful fields: 197.Bd -literal -offset indent 198stat("/etc/motd", {st_mode=S_IFREG|0755, st_size=747, ..}) = 0 199stat("/dev/tty", {st_mode=S_IFCHR|0666, st_rdev=<5,0>, ..}) = 0 200.Ed 201.Pp 202As shown in the above example, flag fields are printed as a combination of 203named constants, separated by a 204.Sq Li | 205pipe symbol. 206Any leftover numerical bits are printed at the end. 207The example also shows the format in which major/minor pairs are printed for 208device numbers. 209This is a custom format; there are a few other custom formats throughout the 210.Nm 211output which are supposed to be sufficiently self-explanatory (and rare). 212.Pp 213Arrays are printed using square brackets. 214.Bd -literal -offset indent 215pipe2([3, 4], 0) = 0 216getdents(3, [..(45)], 4096) = 1824 217getdents(3, [{d_name="."}, ..(+44)], 4096) = 1824 218getdents(3, [], 4096) = 0 219.Ed 220.Pp 221If the array contents are not printed as per the settings for the verbosity 222level, a single pseudo-element shows how many actual elements were in the array 223(the second line in the example). 224If the number of printed elements is limited, a final pseudo-element shows how 225many additional elements were not printed (the third line in the example). 226If a copy error occurs while part of the array has been printed already, a 227last 228.Dq Li ..(?) 229pseudo-element is printed; for immediate failure, the array's pointer is shown. 230Empty arrays will be printed as 231.Dq Li [] . 232.Pp 233Bit sets are printed as arrays except with just a space and no comma as 234bit separator, closely following the output format of 235.Nm Ns 's 236original inspiration 237.Sy strace . 238For signal sets in particular, an inverted bit set may be shown, thus printing 239only the bits which are not set; such sets are prefixed with a 240.Sq Li ~ 241to the opening bracket: 242.Bd -literal -offset indent 243sigprocmask(SIG_SETMASK, ~[USR1 USR2], []) = 0 244.Ed 245.Pp 246Note how the 247.Dq Li SIG 248prefixes are omitted for brevity in this case. 249.Pp 250When multiple processes are traced at once, each line will have a prefix that 251shows the PID of the corresponding process. 252When the number of processes drops to one again, one more line is prefixed with 253the PID of the remaining process, but using a 254.Sq Li ' 255instead of a 256.Sq Li | 257symbol: 258.Bd -literal -offset indent 259fork() = 25813 26025813| Tracing test*F (pid 25813) 26125813| fork() = 0 26225812| waitpid(-1, &.., WNOHANG) = 0 26325813| exit(1) 26425813| Process exited normally with code 1 26525812' waitpid(-1, W_EXITED(1), WNOHANG) = 25813 266exit(0) 267Process exited normally with code 0 268.Ed 269.Pp 270If a process is preempted while making a system call, the system call will 271be shown as suspended with the 272.Dq Li <..> 273suffix. 274Later, when the system call is resumed, the output so far will be repeated, 275either in full or (due to memory limitations) with 276.Dq Li <..> 277in its body, before the remaining part of the system call is printed. 278This time, the line will have a 279.Sq Li * 280asterisk in its prefix, to indicate that this is not a new system call: 281.Bd -literal -offset indent 28225812| write(1, "test\en", 5) = <..> 28325813| setuid(0) = 0 28425812|*write(1, "test\en", 5) = 5 285.Ed 286.Pp 287Finally, 288.Nm 289prints three dashes on their own line whenever the process context (program 290counter and/or stack pointer) is changed during a system call. 291This feature intends to help identify blocks of code run from signal handlers. 292The following example shows a SIGALRM signal handler being invoked. 293.Bd -literal -offset indent 294sigsuspend([]) = ** SIGALRM ** -1 [EINTR] 295--- 296sigprocmask(SIG_SETMASK, ~[], [ALRM]) = 0 297sigreturn({sc_mask=[], ..}) 298--- 299exit(0) 300.Ed 301.Pp 302However, the three dashes are not printed when a signal handler is invoked 303while the program is not in a system call, because the tracer does not see such 304invocations. 305It is however also printed for successful 306.Fn execve 307calls. 308.Sh DIAGNOSTICS 309.Ex 310.Sh SEE ALSO 311.Xr ptrace 2 312.Sh AUTHORS 313The 314.Nm 315utility was written by 316.An David van Moolenbroek 317.Aq david@minix3.org . 318.Sh BUGS 319While the utility aims to provide output for all system calls that can possibly 320be made by user programs, output printers for a small number of rarely-used 321structures and IOCTLs are still missing. In such cases, plain pointers will be 322printed instead of actual contents. 323.Pp 324A signal arrives at the tracing process when sent to the target process, even 325when the target process is blocking the signal and will thus receive it later. 326This is a limitation of the ptrace infrastructure, although it does ensure that 327a target process is not able to block signals generated for tracing purposes. 328The result is that signals are not always shown at the time that they are 329taken in by the target process, and that stack traces for signals may be off. 330.Pp 331Attaching to system services is currently not supported, due to limitations of 332the ptrace infrastructure. The 333.Nm 334utility will detect and safely detach from system services, though. 335