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