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)