1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH TRUSS 1 "Jul 31, 2004"
   8 .SH NAME
   9 truss \- trace system calls and signals
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBtruss\fR [\fB-fcaeildDE\fR] [\fB-\fR [tTvx] [!] \fIsyscall\fR ,...]
  14      [\fB-\fR [sS] [!] \fIsignal\fR ,...] [\fB-\fR [mM] [!] \fIfault\fR ,...]
  15      [\fB-\fR [rw] [!] \fIfd\fR ,...]
  16      [\fB-\fR [uU] [!] \fIlib\fR ,... : [:] [!] \fIfunc\fR ,...]
  17      [\fB-o\fR \fIoutfile\fR] \fIcommand\fR | \fB-p\fR \fIpid\fR[\fI/lwps\fR]...
  18 .fi
  19 
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBtruss\fR utility executes the specified command and produces a trace of
  24 the system calls it performs, the signals it receives, and the machine faults
  25 it incurs. Each line of the trace output reports either the fault or signal
  26 name or the system call name with its arguments and return value(s). System
  27 call arguments are displayed symbolically when possible using defines from
  28 relevant system headers. For any path name pointer argument, the pointed-to
  29 string is displayed. Error returns are reported using the error code names
  30 described in \fBIntro\fR(3). If, in the case of an error, the kernel reports a
  31 missing privilege, a privilege name as described in \fBprivileges\fR(5) is
  32 reported in square brackets (\fB[ ]\fR) after the error code name.
  33 .sp
  34 .LP
  35 Optionally (see the \fB-u\fR option), \fBtruss\fR also produce an entry/exit
  36 trace of user-level function calls executed by the traced process, indented to
  37 indicate nesting.
  38 .SH OPTIONS
  39 .sp
  40 .LP
  41 For those options that take a list argument, the name \fBall\fR can be used as
  42 a shorthand to specify all possible members of the list. If the list begins
  43 with a \fB!\fR, the meaning of the option is negated (for example, exclude
  44 rather than trace). Multiple occurrences of the same option can be specified.
  45 For the same name in a list, subsequent options (those to the right) override
  46 previous ones (those to the left).
  47 .sp
  48 .LP
  49 The following options are supported:
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fB-a\fR\fR
  54 .ad
  55 .sp .6
  56 .RS 4n
  57 Shows the argument strings that are passed in each \fBexec()\fR system call.
  58 .RE
  59 
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fB-c\fR\fR
  64 .ad
  65 .sp .6
  66 .RS 4n
  67 Counts traced system calls, faults, and signals rather than displaying the
  68 trace line-by-line. A summary report is produced after the traced command
  69 terminates or when \fBtruss\fR is interrupted. If \fB-f\fR is also specified,
  70 the counts include all traced system calls, faults, and signals for child
  71 processes.
  72 .RE
  73 
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fB-d\fR\fR
  78 .ad
  79 .sp .6
  80 .RS 4n
  81 Includes a time stamp on each line of trace output. The time stamp appears as a
  82 field containing \fIseconds\fR\|.\|\fIfraction\fR at the start of the line.
  83 This represents a time in seconds relative to the beginning of the trace. The
  84 first line of the trace output shows the base time from which the individual
  85 time stamps are measured, both as seconds since the epoch (see \fBtime\fR(2))
  86 and as a date string (see \fBctime\fR(3C) and \fBdate\fR(1)). The times that
  87 are reported are the times that the event in question occurred. For all system
  88 calls, the event is the completion of the system call, not the start of the
  89 system call.
  90 .RE
  91 
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB-D\fR\fR
  96 .ad
  97 .sp .6
  98 .RS 4n
  99 Includes a time delta on each line of trace output. The value appears as a
 100 field containing \fIseconds\fR\|.\|\fIfraction\fR and represents the elapsed
 101 time for the \fBLWP\fR that incurred the event since the last reported event
 102 incurred by that \fBLWP.\fR Specifically, for system calls, this is not the
 103 time spent within the system call.
 104 .RE
 105 
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fB-e\fR\fR
 110 .ad
 111 .sp .6
 112 .RS 4n
 113 Shows the environment strings that are passed in each \fBexec()\fR system call.
 114 .RE
 115 
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fB-E\fR\fR
 120 .ad
 121 .sp .6
 122 .RS 4n
 123 Includes a time delta on each line of trace output. The value appears as a
 124 field containing \fIseconds\fR\fB\&.\fR\fIfraction\fR and represents the
 125 difference in time elapsed between the beginning and end of a system call.
 126 .sp
 127 In contrast to  the \fB-D\fR option, this is the amount of time spent within
 128 the system call.
 129 .RE
 130 
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fB-f\fR\fR
 135 .ad
 136 .sp .6
 137 .RS 4n
 138 Follows all children created by \fBfork()\fR or \fBvfork()\fR and includes
 139 their signals, faults, and system calls in the trace output. Normally, only the
 140 first-level command or process is traced. When \fB-f\fR is specified, the
 141 process-id is included with each line of trace output to indicate which process
 142 executed the system call or received the signal.
 143 .RE
 144 
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fB-i\fR\fR
 149 .ad
 150 .sp .6
 151 .RS 4n
 152 Does not display interruptible sleeping system calls. Certain system calls,
 153 such as \fBopen()\fR and \fBread()\fR on terminal devices or pipes, can sleep
 154 for indefinite periods and are interruptible. Normally, \fBtruss\fR reports
 155 such sleeping system calls if they remain asleep for more than one second. The
 156 system call is reported again a second time when it completes. The \fB-i\fR
 157 option causes such system calls to be reported only once, when they complete.
 158 .RE
 159 
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fB-l\fR\fR
 164 .ad
 165 .sp .6
 166 .RS 4n
 167 Includes the id of the responsible lightweight process (\fILWP\fR) with each
 168 line of trace output. If \fB-f\fR is also specified, both the process-id and
 169 the LWP-id are included.
 170 .RE
 171 
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB-m\fR [\fB!\fR]\fIfault\fR,...\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 Machine faults to trace or exclude. Those faults specified in the
 180 comma-separated list are traced. Faults can be specified by name or number (see
 181 \fB<sys/fault.h>\fR). If the list begins with a \fB!\fR, the specified faults
 182 are excluded from the trace output. Default is \fB-mall\fR \fB-m\fR
 183 \fB!fltpage\fR.
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fB-M\fR [\fB!\fR]\fIfault\fR,...\fR
 190 .ad
 191 .sp .6
 192 .RS 4n
 193 Machine faults that stop the process. The specified faults are added to the set
 194 specified by \fB-m\fR. If one of the specified faults is incurred, \fBtruss\fR
 195 leaves the process stopped and abandoned (see the \fB-T\fR option). Default is
 196 \fB\fR\fB-M\fR\fB!all\fR.
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fB-o\fR \fIoutfile\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 File to be used for the trace output. By default, the output goes to standard
 207 error.
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fB-p\fR\fR
 214 .ad
 215 .sp .6
 216 .RS 4n
 217 Interprets the \fIcommand\fR arguments to \fBtruss\fR as a list of process-ids
 218 for existing processes (see \fBps\fR(1)) rather than as a command to be
 219 executed. \fBtruss\fR takes control of each process and begins tracing it
 220 provided that the userid and groupid of the process match those of the user or
 221 that the user is a privileged user. Users can trace only selected threads by
 222 appending \fB/\fR\fIthread-id\fR to the process-id. Mutiple threads can be
 223 selected using the \fB-\fR and \fB,\fR delimiters. For example \fB/1,2,7-9\fR
 224 traces threads \fB1\fR, \fB2\fR, \fB7\fR, \fB8\fR, and \fB9\fR. Processes can
 225 also be specified by their names in the \fB/proc\fR directory, for example,
 226 \fB/proc/12345\fR.
 227 .RE
 228 
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fB-r\fR [\fB!\fR]\fIfd\fR,...\fR
 233 .ad
 234 .sp .6
 235 .RS 4n
 236 Shows the full contents of the \fBI/O\fR buffer for each \fBread()\fR on any of
 237 the specified file descriptors. The output is formatted 32 bytes per line and
 238 shows each byte as an \fBASCII\fR character (preceded by one blank) or as a
 239 2-character C language escape sequence for control characters such as
 240 horizontal tab (\|\e\|t) and newline (\|\e\|n). If \fBASCII\fR interpretation
 241 is not possible, the byte is shown in 2-character hexadecimal representation.
 242 (The first 12 bytes of the \fBI/O\fR buffer for each traced \fBprint >read()\fR
 243 are shown even in the absence of \fB-r\fR.) Default is
 244 \fB\fR\fB-r\fR\fB!all\fR.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fB-s\fR [\fB!\fR]\fIsignal\fR,...\fR
 251 .ad
 252 .sp .6
 253 .RS 4n
 254 Signals to trace or exclude. Those signals specified in the comma-separated
 255 list are traced. The trace output reports the receipt of each specified signal,
 256 even if the signal is being ignored (not blocked). (Blocked signals are not
 257 received until they are unblocked.) Signals can be specified by name or number
 258 (see \fB<sys/signal.h>\fR). If the list begins with a \fB!\fR, the specified
 259 signals are excluded from the trace output. Default is \fB-sall\fR.
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fB-S\fR [\fB!\fR]\fIsignal\fR,...\fR
 266 .ad
 267 .sp .6
 268 .RS 4n
 269 Signals that stop the process. The specified signals are added to the set
 270 specified by \fB-s\fR. If one of the specified signals is received, \fBtruss\fR
 271 leaves the process stopped and abandoned (see the \fB-T\fR option). Default is
 272 \fB\fR\fB-S\fR\fB!all\fR.
 273 .RE
 274 
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fB-t\fR [\fB!\fR]\fIsyscall\fR,...\fR
 279 .ad
 280 .sp .6
 281 .RS 4n
 282 System calls to trace or exclude. Those system calls specified in the
 283 comma-separated list are traced. If the list begins with a \fB!\fR, the
 284 specified system calls are excluded from the trace output. Default is
 285 \fB-tall\fR.
 286 .RE
 287 
 288 .sp
 289 .ne 2
 290 .na
 291 \fB\fB-T\fR [\fB!\fR]\fIsyscall\fR,...\fR
 292 .ad
 293 .sp .6
 294 .RS 4n
 295 Specifies system calls that stop the process. The specified system calls are
 296 added to the set specified by \fB-t\fR. If one of the specified system calls is
 297 encountered, \fBtruss\fR leaves the process stopped and abandoned. That is,
 298 \fBtruss\fR releases the process and exits but leaves the process in the
 299 stopped state at completion of the system call in question. A debugger or other
 300 process inspection tool (see \fBproc\fR(1)) can then be applied to the stopped
 301 process. \fBtruss\fR can be reapplied to the stopped process with the same or
 302 different options to continue tracing. Default is \fB\fR\fB-T\fR\fB!all\fR.
 303 .sp
 304 A process left stopped in this manner cannot be restarted by the application of
 305 \fBkill\fR \fB-CONT\fR because it is stopped on an event of interest via
 306 \fB/proc\fR, not by the default action of a stopping signal (see
 307 \fBsignal.h\fR(3HEAD)). The \fBprun\fR(1) command described in \fBproc\fR(1)
 308 can be used to set the stopped process running again.
 309 .RE
 310 
 311 .sp
 312 .ne 2
 313 .na
 314 \fB\fB-u\fR
 315 [\fB!\fR]\fIlib\fR,...\fB:\fR[\fB:\fR][\fB!\fR]\fIfunc\fR,\|.\|.\|.\fR
 316 .ad
 317 .sp .6
 318 .RS 4n
 319 User-level function call tracing. \fIlib\fR,\|.\|.\|. is a comma-separated list
 320 of dynamic library names, excluding the ``\fB\&.so.\fR\fIn\fR'' suffix.
 321 \fIfunc\fR,\|.\|.\|. is a comma-separated list of function names. In both cases
 322 the names can include name-matching metacharacters \fB*\fR,\fB?\fR,\fB[]\fR
 323 with the same meanings as those of \fBsh\fR(1) but as applied to the
 324 library/function name spaces, not to files. An empty library or function list
 325 defaults to \fB*\fR, trace all libraries or functions in a library. A leading
 326 \fB!\fR on either list specifies an exclusion list, names of libraries or
 327 functions not to be traced. Excluding a library excludes all functions in that
 328 library; any function list following a library exclusion list is ignored.
 329 .sp
 330 A single \fB:\fR separating the library list from the function list means to
 331 trace calls into the libraries from outside the libraries, but omit calls made
 332 to functions in a library from other functions in the same library. A double
 333 \fB:\|:\fR means to trace all calls, regardless of origin.
 334 .sp
 335 Library patterns do not match either the executable file or the dynamic linker
 336 unless there is an exact match (\fBl*\fR does not match \fBld.so.1\fR). To
 337 trace functions in either of these objects, the names must be specified
 338 exactly, as in:
 339 .sp
 340 .in +2
 341 .nf
 342 \fBtruss -u a.out -u ld ...\fR
 343 .fi
 344 .in -2
 345 .sp
 346 
 347 \fBa.out\fR is the literal name to be used for this purpose; it does not stand
 348 for the name of the executable file. Tracing \fBa.out\fR function calls implies
 349 all calls (default is \fB::\fR).
 350 .sp
 351 Multiple \fB-u\fR options can be specified and they are honored left-to-right.
 352 The id of the thread that performed the function call is included in the trace
 353 output for the call. \fBtruss\fR searches the dynamic symbol table in each
 354 library to find function names and also searches the standard symbol table if
 355 it has not been stripped.
 356 .RE
 357 
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fB-U\fR
 362 [\fB!\fR]\fIlib\fR,\|.\|.\|.\|\fB:\fR[\fB:\fR][\fB!\fR]\fIfunc\fR,\|.\|.\|.\fR
 363 .ad
 364 .sp .6
 365 .RS 4n
 366 User-level function calls that stop the process. The specified functions are
 367 added to the set specified by \fB-u\fR. If one of the specified functions is
 368 called, \fBtruss\fR leaves the process stopped and abandoned (see the \fB-T\fR
 369 option).
 370 .RE
 371 
 372 .sp
 373 .ne 2
 374 .na
 375 \fB\fB-v\fR [\fB!\fR]\fIsyscall\fR,...\fR
 376 .ad
 377 .sp .6
 378 .RS 4n
 379 Verbose. Displays the contents of any structures passed by address to the
 380 specified system calls (if traced by \fB-t\fR). Input values as well as values
 381 returned by the operating system are shown. For any field used as both input
 382 and output, only the output value is shown. Default is
 383 \fB\fR\fB-v\fR\fB!all\fR.
 384 .RE
 385 
 386 .sp
 387 .ne 2
 388 .na
 389 \fB\fB-w\fR [\fB!\fR]\fIfd\fR,...\fR
 390 .ad
 391 .sp .6
 392 .RS 4n
 393 Shows the contents of the I/O buffer for each \fBwrite()\fR on any of the
 394 specified file descriptors (see the \fB-r\fR option). Default is
 395 \fB\fR\fB-w\fR\fB!all\fR.
 396 .RE
 397 
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fB-x\fR [\fB!\fR]\fIsyscall\fR,...\fR
 402 .ad
 403 .sp .6
 404 .RS 4n
 405 Displays the arguments to the specified system calls (if traced by \fB-t\fR) in
 406 raw form, usually hexadecimal, rather than symbolically. This is for unredeemed
 407 hackers who must see the raw bits to be happy. Default is
 408 \fB\fR\fB-x\fR\fB!all\fR.
 409 .RE
 410 
 411 .sp
 412 .LP
 413 See \fIman pages section 2: System Calls\fR for system call names accepted by
 414 the \fB-t\fR, \fB-T\fR, \fB-v\fR, and \fB-x\fR options. System call numbers are
 415 also accepted.
 416 .sp
 417 .LP
 418 If \fBtruss\fR is used to initiate and trace a specified command and if the
 419 \fB-o\fR option is used or if standard error is redirected to a non-terminal
 420 file, then \fBtruss\fR runs with hangup, interrupt, and quit signals ignored.
 421 This facilitates tracing of interactive programs that catch interrupt and quit
 422 signals from the terminal.
 423 .sp
 424 .LP
 425 If the trace output remains directed to the terminal, or if existing processes
 426 are traced (the \fB-p\fR option), then \fBtruss\fR responds to hangup,
 427 interrupt, and quit signals by releasing all traced processes and exiting. This
 428 enables the user to terminate excessive trace output and to release
 429 previously-existing processes. Released processes continue normally, as though
 430 they had never been touched.
 431 .SH EXAMPLES
 432 .LP
 433 \fBExample 1 \fRTracing a Command
 434 .sp
 435 .LP
 436 The following example produces a trace of the \fBfind\fR(1) command on the
 437 terminal:
 438 
 439 .sp
 440 .in +2
 441 .nf
 442 example$ \fBtruss find . -print >find.out\fR
 443 .fi
 444 .in -2
 445 .sp
 446 
 447 .LP
 448 \fBExample 2 \fRTracing Common System Calls
 449 .sp
 450 .LP
 451 The following example shows only a trace of the open, close, read, and write
 452 system calls:
 453 
 454 .sp
 455 .in +2
 456 .nf
 457 example$ \fBtruss -t open,close,read,write find . -print >find.out\fR
 458 .fi
 459 .in -2
 460 .sp
 461 
 462 .LP
 463 \fBExample 3 \fRTracing a Shell Script
 464 .sp
 465 .LP
 466 The following example produces a trace of the \fBspell\fR(1) command on the
 467 file \fBtruss.out\fR:
 468 
 469 .sp
 470 .in +2
 471 .nf
 472 example$ \fBtruss -f -o truss.out spell \fIdocument\fR\fR
 473 .fi
 474 .in -2
 475 .sp
 476 
 477 .sp
 478 .LP
 479 \fBspell\fR is a shell script, so the \fB-f\fR flag is needed to trace not only
 480 the shell but also the processes created by the shell. (The spell script runs a
 481 pipeline of eight processes.)
 482 
 483 .LP
 484 \fBExample 4 \fRAbbreviating Output
 485 .sp
 486 .LP
 487 The following example abreviates output:
 488 
 489 .sp
 490 .in +2
 491 .nf
 492 example$ \fBtruss nroff -mm \fIdocument\fR >nroff.out\fR
 493 .fi
 494 .in -2
 495 .sp
 496 
 497 .sp
 498 .LP
 499 because 97% of the output reports \fBlseek()\fR, \fBread()\fR, and
 500 \fBwrite()\fR system calls. To abbreviate it:
 501 
 502 .sp
 503 .in +2
 504 .nf
 505 example$ \fBtruss -t !lseek,read,write nroff -mm \fIdocument\fR >nroff.out\fR
 506 .fi
 507 .in -2
 508 .sp
 509 
 510 .LP
 511 \fBExample 5 \fRTracing Library Calls From Outside the C Library
 512 .sp
 513 .LP
 514 The following example traces all user-level calls made to any function in the C
 515 library from outside the C library:
 516 
 517 .sp
 518 .in +2
 519 .nf
 520 example$ \fBtruss -u libc ...\fR
 521 .fi
 522 .in -2
 523 .sp
 524 
 525 .LP
 526 \fBExample 6 \fRTracing library calls from within the C library
 527 .sp
 528 .LP
 529 The following example includes calls made to functions in the C library from
 530 within the C library itself:
 531 
 532 .sp
 533 .in +2
 534 .nf
 535 example$ \fBtruss -u libc:: ...\fR
 536 .fi
 537 .in -2
 538 .sp
 539 
 540 .LP
 541 \fBExample 7 \fRTracing Library Calls Other Than the C Library
 542 .sp
 543 .LP
 544 The following example traces all user-level calls made to any library other
 545 than the C library:
 546 
 547 .sp
 548 .in +2
 549 .nf
 550 example$ \fBtruss -u '*' -u !libc ...\fR
 551 .fi
 552 .in -2
 553 .sp
 554 
 555 .LP
 556 \fBExample 8 \fRTracing \fBprintf\fR and \fBscanf\fR Function Calls
 557 .sp
 558 .LP
 559 The following example traces all user-level calls to functions in the printf
 560 and scanf family contained in the C library:
 561 
 562 .sp
 563 .in +2
 564 .nf
 565 example$ \fBtruss -u 'libc:*printf,*scanf' ...\fR
 566 .fi
 567 .in -2
 568 .sp
 569 
 570 .LP
 571 \fBExample 9 \fRTracing Every User-level Function Call
 572 .sp
 573 .LP
 574 The following example traces every user-level function call from anywhere to
 575 anywhere:
 576 
 577 .sp
 578 .in +2
 579 .nf
 580 example$ \fBtruss -u a.out -u ld:: -u :: ...\fR
 581 .fi
 582 .in -2
 583 .sp
 584 
 585 .LP
 586 \fBExample 10 \fRTracing a System Call Verbosely
 587 .sp
 588 .LP
 589 The following example verbosely traces the system call activity of process #1,
 590 \fBinit\fR(1M) (if you are a privileged user):
 591 
 592 .sp
 593 .in +2
 594 .nf
 595 example# \fBtruss -p -v all 1\fR
 596 .fi
 597 .in -2
 598 .sp
 599 
 600 .sp
 601 .LP
 602 Interrupting \fBtruss\fR returns \fBinit\fR to normal operation.
 603 
 604 .SH FILES
 605 .sp
 606 .ne 2
 607 .na
 608 \fB\fB/proc/*\fR\fR
 609 .ad
 610 .RS 11n
 611 Process files
 612 .RE
 613 
 614 .SH SEE ALSO
 615 .sp
 616 .LP
 617 \fBdate\fR(1), \fBfind\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBsh\fR(1),
 618 \fBspell\fR(1), \fBinit\fR(1M), \fBIntro\fR(3), \fBexec\fR(2), \fBfork\fR(2),
 619 \fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBtime\fR(2), \fBvfork\fR(2),
 620 \fBwrite\fR(2), \fBctime\fR(3C), \fBsignal.h\fR(3HEAD), \fBproc\fR(4),
 621 \fBattributes\fR(5), \fBprivileges\fR(5), \fBthreads\fR(5)
 622 .sp
 623 .LP
 624 \fIman pages section 2: System Calls\fR
 625 .SH NOTES
 626 .sp
 627 .LP
 628 Some of the system calls described in \fIman pages section 2: System Calls\fR
 629 differ from the actual operating system interfaces. Do not be surprised by
 630 minor deviations of the trace output from the descriptions in that document.
 631 .sp
 632 .LP
 633 Every machine fault (except a page fault) results in the posting of a signal to
 634 the \fBLWP\fR that incurred the fault. A report of a received signal
 635 immediately follows each report of a machine fault (except a page fault) unless
 636 that signal is being blocked.
 637 .sp
 638 .LP
 639 The operating system enforces certain security restrictions on the tracing of
 640 processes. In particular, any command whose object file (\fBa.out\fR) cannot be
 641 read by a user cannot be traced by that user; set-uid and set-gid commands can
 642 be traced only by a privileged user. Unless it is run by a privileged user,
 643 \fBtruss\fR loses control of any process that performs an \fBexec()\fR of a
 644 set-id or unreadable object file; such processes continue normally, though
 645 independently of \fBtruss\fR, from the point of the \fBexec()\fR.
 646 .sp
 647 .LP
 648 To avoid collisions with other controlling processes, \fBtruss\fR does not
 649 trace a process that it detects is being controlled by another process via the
 650 \fB/proc\fR interface. This allows \fBtruss\fR to be applied to
 651 \fBproc\fR(4)-based debuggers as well as to another instance of itself.
 652 .sp
 653 .LP
 654 The trace output contains tab characters under the assumption that standard tab
 655 stops are set (every eight positions).
 656 .sp
 657 .LP
 658 The trace output for multiple processes or for a multithreaded process (one
 659 that contains more than one \fBLWP)\fR is not produced in strict time order.
 660 For example, a \fBread()\fR on a pipe can be reported before the corresponding
 661 \fBwrite()\fR. For any one \fBLWP\fR (a traditional process contains only one),
 662 the output is strictly time-ordered.
 663 .sp
 664 .LP
 665 When tracing more than one process, \fBtruss\fR runs as one controlling process
 666 for each process being traced. For the example of the \fBspell\fR command shown
 667 above, \fBspell\fR itself uses 9 process slots, one for the shell and 8 for the
 668 8-member pipeline, while \fBtruss\fR adds another 9 processes, for a total of
 669 18.
 670 .sp
 671 .LP
 672 Not all possible structures passed in all possible system calls are displayed
 673 under the \fB-v\fR option.