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