1 TRUSS(1) User Commands TRUSS(1) 2 3 4 5 NAME 6 truss - trace system calls and signals 7 8 SYNOPSIS 9 truss [-fcaeildDE] [- [tTvx] [!] syscall ,...] 10 [- [sS] [!] signal ,...] [- [mM] [!] fault ,...] 11 [- [rw] [!] fd ,...] 12 [- [uU] [!] lib ,... : [:] [!] func ,...] 13 [-o outfile] command | -p pid[/lwps]... 14 15 16 DESCRIPTION 17 The truss utility executes the specified command and produces a trace 18 of the system calls it performs, the signals it receives, and the 19 machine faults it incurs. Each line of the trace output reports either 20 the fault or signal name or the system call name with its arguments and 21 return value(s). System call arguments are displayed symbolically when 22 possible using defines from relevant system headers. For any path name 23 pointer argument, the pointed-to string is displayed. Error returns are 24 reported using the error code names described in Intro(3). If, in the 25 case of an error, the kernel reports a missing privilege, a privilege 26 name as described in privileges(5) is reported in square brackets ([ ]) 27 after the error code name. 28 29 30 Optionally (see the -u option), truss also produce an entry/exit trace 31 of user-level function calls executed by the traced process, indented 32 to indicate nesting. 33 34 OPTIONS 35 For those options that take a list argument, the name all can be used 36 as a shorthand to specify all possible members of the list. If the list 37 begins with a !, the meaning of the option is negated (for example, 38 exclude rather than trace). Multiple occurrences of the same option can 39 be specified. For the same name in a list, subsequent options (those 40 to the right) override previous ones (those to the left). 41 42 43 The following options are supported: 44 45 -a 46 47 Shows the argument strings that are passed in each exec() system 48 call. 49 50 51 -c 52 53 Counts traced system calls, faults, and signals rather than 54 displaying the trace line-by-line. A summary report is produced 55 after the traced command terminates or when truss is interrupted. 56 If -f is also specified, the counts include all traced system 57 calls, faults, and signals for child processes. 58 59 60 -d 61 62 Includes a time stamp on each line of trace output. The time stamp 63 appears as a field containing seconds.fraction at the start of the 64 line. This represents a time in seconds relative to the beginning 65 of the trace. The first line of the trace output shows the base 66 time from which the individual time stamps are measured, both as 67 seconds since the epoch (see time(2)) and as a date string (see 68 ctime(3C) and date(1)). The times that are reported are the times 69 that the event in question occurred. For all system calls, the 70 event is the completion of the system call, not the start of the 71 system call. 72 73 74 -D 75 76 Includes a time delta on each line of trace output. The value 77 appears as a field containing seconds.fraction and represents the 78 elapsed time for the LWP that incurred the event since the last 79 reported event incurred by that LWP. Specifically, for system 80 calls, this is not the time spent within the system call. 81 82 83 -e 84 85 Shows the environment strings that are passed in each exec() system 86 call. 87 88 89 -E 90 91 Includes a time delta on each line of trace output. The value 92 appears as a field containing seconds.fraction and represents the 93 difference in time elapsed between the beginning and end of a 94 system call. 95 96 In contrast to the -D option, this is the amount of time spent 97 within the system call. 98 99 100 -f 101 102 Follows all children created by fork() or vfork() and includes 103 their signals, faults, and system calls in the trace output. 104 Normally, only the first-level command or process is traced. When 105 -f is specified, the process-id is included with each line of trace 106 output to indicate which process executed the system call or 107 received the signal. 108 109 110 -i 111 112 Does not display interruptible sleeping system calls. Certain 113 system calls, such as open() and read() on terminal devices or 114 pipes, can sleep for indefinite periods and are interruptible. 115 Normally, truss reports such sleeping system calls if they remain 116 asleep for more than one second. The system call is reported again 117 a second time when it completes. The -i option causes such system 118 calls to be reported only once, when they complete. 119 120 121 -l 122 123 Includes the id of the responsible lightweight process (LWP) with 124 each line of trace output. If -f is also specified, both the 125 process-id and the LWP-id are included. 126 127 128 -m [!]fault,... 129 130 Machine faults to trace or exclude. Those faults specified in the 131 comma-separated list are traced. Faults can be specified by name or 132 number (see <sys/fault.h>). If the list begins with a !, the 133 specified faults are excluded from the trace output. Default is 134 -mall -m !fltpage. 135 136 137 -M [!]fault,... 138 139 Machine faults that stop the process. The specified faults are 140 added to the set specified by -m. If one of the specified faults is 141 incurred, truss leaves the process stopped and abandoned (see the 142 -T option). Default is -M!all. 143 144 145 -o outfile 146 147 File to be used for the trace output. By default, the output goes 148 to standard error. 149 150 151 -p 152 153 Interprets the command arguments to truss as a list of process-ids 154 for existing processes (see ps(1)) rather than as a command to be 155 executed. truss takes control of each process and begins tracing it 156 provided that the userid and groupid of the process match those of 157 the user or that the user is a privileged user. Users can trace 158 only selected threads by appending /thread-id to the process-id. 159 Mutiple threads can be selected using the - and , delimiters. For 160 example /1,2,7-9 traces threads 1, 2, 7, 8, and 9. Processes can 161 also be specified by their names in the /proc directory, for 162 example, /proc/12345. 163 164 165 -r [!]fd,... 166 167 Shows the full contents of the I/O buffer for each read() on any of 168 the specified file descriptors. The output is formatted 32 bytes 169 per line and shows each byte as an ASCII character (preceded by one 170 blank) or as a 2-character C language escape sequence for control 171 characters such as horizontal tab (\t) and newline (\n). If ASCII 172 interpretation is not possible, the byte is shown in 2-character 173 hexadecimal representation. (The first 12 bytes of the I/O buffer 174 for each traced print >read() are shown even in the absence of -r.) 175 Default is -r!all. 176 177 178 -s [!]signal,... 179 180 Signals to trace or exclude. Those signals specified in the comma- 181 separated list are traced. The trace output reports the receipt of 182 each specified signal, even if the signal is being ignored (not 183 blocked). (Blocked signals are not received until they are 184 unblocked.) Signals can be specified by name or number (see 185 <sys/signal.h>). If the list begins with a !, the specified signals 186 are excluded from the trace output. Default is -sall. 187 188 189 -S [!]signal,... 190 191 Signals that stop the process. The specified signals are added to 192 the set specified by -s. If one of the specified signals is 193 received, truss leaves the process stopped and abandoned (see the 194 -T option). Default is -S!all. 195 196 197 -t [!]syscall,... 198 199 System calls to trace or exclude. Those system calls specified in 200 the comma-separated list are traced. If the list begins with a !, 201 the specified system calls are excluded from the trace output. 202 Default is -tall. 203 204 205 -T [!]syscall,... 206 207 Specifies system calls that stop the process. The specified system 208 calls are added to the set specified by -t. If one of the specified 209 system calls is encountered, truss leaves the process stopped and 210 abandoned. That is, truss releases the process and exits but leaves 211 the process in the stopped state at completion of the system call 212 in question. A debugger or other process inspection tool (see 213 proc(1)) can then be applied to the stopped process. truss can be 214 reapplied to the stopped process with the same or different options 215 to continue tracing. Default is -T!all. 216 217 A process left stopped in this manner cannot be restarted by the 218 application of kill -CONT because it is stopped on an event of 219 interest via /proc, not by the default action of a stopping signal 220 (see signal.h(3HEAD)). The prun(1) command described in proc(1) can 221 be used to set the stopped process running again. 222 223 224 -u [!]lib,...:[:][!]func,... 225 226 User-level function call tracing. lib,... is a comma-separated list 227 of dynamic library names, excluding the ``.so.n'' suffix. func,... 228 is a comma-separated list of function names. In both cases the 229 names can include name-matching metacharacters *,?,[] with the same 230 meanings as those of sh(1) but as applied to the library/function 231 name spaces, not to files. An empty library or function list 232 defaults to *, trace all libraries or functions in a library. A 233 leading ! on either list specifies an exclusion list, names of 234 libraries or functions not to be traced. Excluding a library 235 excludes all functions in that library; any function list following 236 a library exclusion list is ignored. 237 238 A single : separating the library list from the function list means 239 to trace calls into the libraries from outside the libraries, but 240 omit calls made to functions in a library from other functions in 241 the same library. A double :: means to trace all calls, regardless 242 of origin. 243 244 Library patterns do not match either the executable file or the 245 dynamic linker unless there is an exact match (l* does not match 246 ld.so.1). To trace functions in either of these objects, the names 247 must be specified exactly, as in: 248 249 truss -u a.out -u ld ... 250 251 252 a.out is the literal name to be used for this purpose; it does not 253 stand for the name of the executable file. Tracing a.out function 254 calls implies all calls (default is ::). 255 256 Multiple -u options can be specified and they are honored left-to- 257 right. The id of the thread that performed the function call is 258 included in the trace output for the call. truss searches the 259 dynamic symbol table in each library to find function names and 260 also searches the standard symbol table if it has not been 261 stripped. 262 263 264 -U [!]lib,...:[:][!]func,... 265 266 User-level function calls that stop the process. The specified 267 functions are added to the set specified by -u. If one of the 268 specified functions is called, truss leaves the process stopped and 269 abandoned (see the -T option). 270 271 272 -v [!]syscall,... 273 274 Verbose. Displays the contents of any structures passed by address 275 to the specified system calls (if traced by -t). Input values as 276 well as values returned by the operating system are shown. For any 277 field used as both input and output, only the output value is 278 shown. Default is -v!all. 279 280 281 -w [!]fd,... 282 283 Shows the contents of the I/O buffer for each write() on any of the 284 specified file descriptors (see the -r option). Default is -w!all. 285 286 287 -x [!]syscall,... 288 289 Displays the arguments to the specified system calls (if traced by 290 -t) in raw form, usually hexadecimal, rather than symbolically. 291 This is for unredeemed hackers who must see the raw bits to be 292 happy. Default is -x!all. 293 294 295 296 See man pages section 2: System Calls for system call names accepted by 297 the -t, -T, -v, and -x options. System call numbers are also accepted. 298 299 300 If truss is used to initiate and trace a specified command and if the 301 -o option is used or if standard error is redirected to a non-terminal 302 file, then truss runs with hangup, interrupt, and quit signals ignored. 303 This facilitates tracing of interactive programs that catch interrupt 304 and quit signals from the terminal. 305 306 307 If the trace output remains directed to the terminal, or if existing 308 processes are traced (the -p option), then truss responds to hangup, 309 interrupt, and quit signals by releasing all traced processes and 310 exiting. This enables the user to terminate excessive trace output and 311 to release previously-existing processes. Released processes continue 312 normally, as though they had never been touched. 313 314 EXAMPLES 315 Example 1 Tracing a Command 316 317 318 The following example produces a trace of the find(1) command on the 319 terminal: 320 321 322 example$ truss find . -print >find.out 323 324 325 326 Example 2 Tracing Common System Calls 327 328 329 The following example shows only a trace of the open, close, read, and 330 write system calls: 331 332 333 example$ truss -t open,close,read,write find . -print >find.out 334 335 336 337 Example 3 Tracing a Shell Script 338 339 340 The following example produces a trace of the spell(1) command on the 341 file truss.out: 342 343 344 example$ truss -f -o truss.out spell document 345 346 347 348 349 spell is a shell script, so the -f flag is needed to trace not only the 350 shell but also the processes created by the shell. (The spell script 351 runs a pipeline of eight processes.) 352 353 354 Example 4 Abbreviating Output 355 356 357 The following example abbreviates output: 358 359 360 example$ truss nroff -mm document >nroff.out 361 362 363 364 365 because 97% of the output reports lseek(), read(), and write() system 366 calls. To abbreviate it: 367 368 369 example$ truss -t !lseek,read,write nroff -mm document >nroff.out 370 371 372 373 Example 5 Tracing Library Calls From Outside the C Library 374 375 376 The following example traces all user-level calls made to any function 377 in the C library from outside the C library: 378 379 380 example$ truss -u libc ... 381 382 383 384 Example 6 Tracing library calls from within the C library 385 386 387 The following example includes calls made to functions in the C library 388 from within the C library itself: 389 390 391 example$ truss -u libc:: ... 392 393 394 395 Example 7 Tracing Library Calls Other Than the C Library 396 397 398 The following example traces all user-level calls made to any library 399 other than the C library: 400 401 402 example$ truss -u '*' -u !libc ... 403 404 405 406 Example 8 Tracing printf and scanf Function Calls 407 408 409 The following example traces all user-level calls to functions in the 410 printf and scanf family contained in the C library: 411 412 413 example$ truss -u 'libc:*printf,*scanf' ... 414 415 416 417 Example 9 Tracing Every User-level Function Call 418 419 420 The following example traces every user-level function call from 421 anywhere to anywhere: 422 423 424 example$ truss -u a.out -u ld:: -u :: ... 425 426 427 428 Example 10 Tracing a System Call Verbosely 429 430 431 The following example verbosely traces the system call activity of 432 process #1, init(1M) (if you are a privileged user): 433 434 435 example# truss -p -v all 1 436 437 438 439 440 Interrupting truss returns init to normal operation. 441 442 443 FILES 444 /proc/* 445 Process files 446 447 448 SEE ALSO 449 date(1), find(1), proc(1), ps(1), sh(1), spell(1), init(1M), Intro(3), 450 exec(2), fork(2), lseek(2), open(2), read(2), time(2), vfork(2), 451 write(2), ctime(3C), signal.h(3HEAD), proc(4), attributes(5), 452 privileges(5), threads(5) 453 454 455 man pages section 2: System Calls 456 457 NOTES 458 Some of the system calls described in man pages section 2: System Calls 459 differ from the actual operating system interfaces. Do not be surprised 460 by minor deviations of the trace output from the descriptions in that 461 document. 462 463 464 Every machine fault (except a page fault) results in the posting of a 465 signal to the LWP that incurred the fault. A report of a received 466 signal immediately follows each report of a machine fault (except a 467 page fault) unless that signal is being blocked. 468 469 470 The operating system enforces certain security restrictions on the 471 tracing of processes. In particular, any command whose object file 472 (a.out) cannot be read by a user cannot be traced by that user; set-uid 473 and set-gid commands can be traced only by a privileged user. Unless it 474 is run by a privileged user, truss loses control of any process that 475 performs an exec() of a set-id or unreadable object file; such 476 processes continue normally, though independently of truss, from the 477 point of the exec(). 478 479 480 To avoid collisions with other controlling processes, truss does not 481 trace a process that it detects is being controlled by another process 482 via the /proc interface. This allows truss to be applied to 483 proc(4)-based debuggers as well as to another instance of itself. 484 485 486 The trace output contains tab characters under the assumption that 487 standard tab stops are set (every eight positions). 488 489 490 The trace output for multiple processes or for a multithreaded process 491 (one that contains more than one LWP) is not produced in strict time 492 order. For example, a read() on a pipe can be reported before the 493 corresponding write(). For any one LWP (a traditional process contains 494 only one), the output is strictly time-ordered. 495 496 497 When tracing more than one process, truss runs as one controlling 498 process for each process being traced. For the example of the spell 499 command shown above, spell itself uses 9 process slots, one for the 500 shell and 8 for the 8-member pipeline, while truss adds another 9 501 processes, for a total of 18. 502 503 504 Not all possible structures passed in all possible system calls are 505 displayed under the -v option. 506 507 508 509 July 31, 2004 TRUSS(1)