truss(1)                                                           User Commands                                                          truss(1)

NAME

       truss - trace system calls and signals

SYNOPSIS

       truss  [-fcaeildDE]  [ - [tTvx] [!] syscall ,...] [ - [sS] [!] signal ,...] [ - [mM] [!] fault ,...] [ - [rw] [!] fd ,...] [ - [uU] [!] lib
       ,... : [:] [!] func ,...] [-o outfile] command | -p pid[/lwps]...

DESCRIPTION

       The truss utility executes the specified command and produces a trace of the system calls it performs, the signals  it  receives,  and  the
       machine  faults it incurs. Each line of the trace output reports either the fault or signal name or the system call name with its arguments
       and return value(s). System call arguments are displayed symbolically when possible using defines from relevant  system  headers.  For  any
       path  name  pointer  argument,  the  pointed-to  string  is  displayed.  Error returns are reported using the error code names described in
       intro(3). If, in the case of an error, the kernel reports a missing privilege, a privilege name as described in privileges(5)  is  reported
       in square brackets ([ ]) after the error code name.

       Optionally  (see  the  -u  option),  truss  also  produce  an entry/exit trace of user-level function calls executed by the traced process,
       indented to indicate nesting.

OPTIONS

       For those options that take a list argument, the name all can be used as a shorthand to specify all possible members of the  list.  If  the
       list  begins  with  a  !,  the  meaning of the option is negated (for example, exclude rather than trace). Multiple occurrences of the same
       option can be specified. For the same name in a list, subsequent options (those to the right) override previous ones (those to the left).

       The following options are supported:

       -a

           Shows the argument strings that are passed in each exec() system call.

       -c

           Counts traced system calls, faults, and signals rather than displaying the trace line-by-line. A summary report is produced  after  the
           traced  command  terminates  or when truss is interrupted. If -f is also specified, the counts include all traced system calls, faults,
           and signals for child processes.

       -d

           Includes a time stamp on each line of trace output. The time stamp appears as a field containing seconds.fraction at the start  of  the
           line.  This represents a time in seconds relative to the beginning of the trace. The first line of the trace output shows the base time
           from which the individual time stamps are measured, both as seconds since the epoch (see time(2)) and as a date string  (see  ctime(3C)
           and  date(1)).  The  times  that are reported are the times that the event in question occurred. For all system calls, the event is the
           completion of the system call, not the start of the system call.

       -D

           Includes a time delta on each line of trace output. The value appears as a field containing seconds.fraction and represents the elapsed
           time  for  the  LWP that incurred the event since the last reported event incurred by that LWP. Specifically, for system calls, this is
           not the time spent within the system call.

       -e

           Shows the environment strings that are passed in each exec() system call.

       -E

           Includes a time delta on each line of trace output. The value appears as a field containing seconds.fraction and represents the differ-
           ence in time elapsed between the beginning and end of a system call.

           In contrast to  the -D option, this is the amount of time spent within the system call.

       -f

           Follows  all  children created by fork() or vfork() and includes their signals, faults, and system calls in the trace output. Normally,
           only the first-level command or process is traced. When -f is specified, the process-id is included with each line of trace  output  to
           indicate which process executed the system call or received the signal.

       -i

           Does not display interruptible sleeping system calls. Certain system calls, such as open() and read() on terminal devices or pipes, can
           sleep for indefinite periods and are interruptible. Normally, truss reports such sleeping system calls if they remain asleep  for  more
           than  one  second.  The  system  call  is  reported again a second time when it completes. The -i option causes such system calls to be
           reported only once, when they complete.

       -l

           Includes the id of the responsible lightweight process (LWP) with each line of trace output. If -f is also specified, both the process-
           id and the LWP-id are included.

       -m [!]fault,...

           Machine  faults  to trace or exclude. Those faults specified in the comma-separated list are traced. Faults can be specified by name or
           number (see <sys/fault.h>).  If the list begins with a !, the specified faults are excluded from the trace  output.  Default  is  -mall
           -m!fltpage.

       -M [!]fault,...

           Machine  faults  that  stop  the  process. The specified faults are added to the set specified by -m. If one of the specified faults is
           incurred, truss leaves the process stopped and abandoned (see the -T option). Default is -M!all.

       -o outfile

           File to be used for the trace output. By default, the output goes to standard error.

       -p

           Interprets the command arguments to truss as a list of process-ids for existing processes (see ps(1)) rather than as a  command  to  be
           executed.  truss takes control of each process and begins tracing it provided that the userid and groupid of the process match those of
           the user or that the user is a privileged user. Users can trace only selected threads by appending /thread-id to the process-id.  Muti-
           ple  threads can be selected using the - and , delimiters. For example /1,2,7-9 traces threads 1, 2, 7, 8, and 9. Processes can also be
           specified by their names in the /proc directory, for example, /proc/12345.

       -r [!]fd,...

           Shows the full contents of the I/O buffer for each read() on any of the specified file descriptors. The output is  formatted  32  bytes
           per  line  and shows each byte as an ASCII character (preceded by one blank) or as a 2-character C language escape sequence for control
           characters such as horizontal tab (	) and newline (
). If ASCII interpretation is not possible, the  byte  is  shown  in  2-character
           hexadecimal representation. (The first 12 bytes of the I/O buffer for each traced  read() are shown even in the absence of -r.) Default
           is -r!all.

       -s [!]signal,...

           Signals to trace or exclude. Those signals specified in the comma-separated list are traced. The trace output reports  the  receipt  of
           each  specified signal, even if the signal is being ignored (not blocked). (Blocked signals are not received until they are unblocked.)
           Signals can be specified by name or number (see <sys/signal.h>). If the list begins with a !, the specified signals are  excluded  from
           the trace output. Default is -sall.

       -S [!]signal,...

           Signals that stop the process. The specified signals are added to the set specified by -s. If one of the specified signals is received,
           truss leaves the process stopped and abandoned (see the -T option). Default is -S!all.

       -t [!]syscall,...

           System calls to trace or exclude. Those system calls specified in the comma-separated list are traced. If the list begins with a !, the
           specified system calls are excluded from the trace output. Default is -tall.

       -T [!]syscall,...

           Specifies  system calls that stop the process. The specified system calls are added to the set specified by -t. If one of the specified
           system calls is encountered, truss leaves the process stopped and abandoned. That is, truss releases the process and exits  but  leaves
           the  process  in  the  stopped  state  at  completion  of the system call in question. A debugger or other process inspection tool (see
           proc(1)) can then be applied to the stopped process. truss can be reapplied to the stopped process with the same or  different  options
           to continue tracing. Default is -T!all.

           A  process left stopped in this manner cannot be restarted by the application of kill -CONT because it is stopped on an event of inter-
           est via /proc, not by the default action of a stopping signal (see signal.h(3HEAD)). The prun(1) command described in  proc(1)  can  be
           used to set the stopped process running again.

       -u [!]lib,...:[:][!]func,...

           User-level function call tracing. lib,...  is a comma-separated list of dynamic library names, excluding the ``.so.n'' suffix. func,...
           is a comma-separated list of function names. In both cases the names can include name-matching  metacharacters  *,?,[]  with  the  same
           meanings  as  those  of   sh(1)  but  as  applied  to the library/function name spaces, not to files. An empty library or function list
           defaults to *, trace all libraries or functions in a library. A leading !  on  either  list  specifies  an  exclusion  list,  names  of
           libraries  or  functions  not  to  be traced. Excluding a library excludes all functions in that library; any function list following a
           library exclusion list is ignored.

           A single : separating the library list from the function list means to trace calls into the libraries from outside the  libraries,  but
           omit calls made to functions in a library from other functions in the same library. A double :: means to trace all calls, regardless of
           origin.

           Library patterns do not match either the executable file or the dynamic linker unless there is  an  exact  match  (l*  does  not  match
           ld.so.1). To trace functions in either of these objects, the names must be specified exactly, as in:

           truss -u a.out -u ld ...

           a.out  is  the  literal name to be used for this purpose; it does not stand for the name of the executable file. Tracing a.out function
           calls implies all calls (default is ::).

           Multiple -u options can be specified and they are honored left-to-right. The id of the thread  that  performed  the  function  call  is
           included  in  the  trace  output  for the call. truss searches the dynamic symbol table in each library to find function names and also
           searches the standard symbol table if it has not been stripped.

       -U [!]lib,...:[:][!]func,...

           User-level function calls that stop the process. The specified functions are added to the set specified by -u. If one of the  specified
           functions is called, truss leaves the process stopped and abandoned (see the -T option).

       -v [!]syscall,...

           Verbose.  Displays  the  contents  of any structures passed by address to the specified system calls (if traced by -t). Input values as
           well as values returned by the operating system are shown. For any field used as both input and output, only the output value is shown.
           Default is -v!all.

       -w [!]fd,...

           Shows the contents of the I/O buffer for each write() on any of the specified file descriptors (see the -r option). Default is -w!all.

       -x [!]syscall,...

           Displays the arguments to the specified system calls (if traced by -t) in raw form, usually hexadecimal, rather than symbolically. This
           is for unredeemed hackers who must see the raw bits to be happy. Default is -x!all.

       See man pages section 2: System Calls for system call names accepted by the -t, -T, -v, and  -x  options.  System  call  numbers  are  also
       accepted.

       If  truss is used to initiate and trace a specified command and if the -o option is used or if standard error is redirected to a non-termi-
       nal file, then truss runs with hangup, interrupt, and quit signals ignored. This facilitates tracing of  interactive  programs  that  catch
       interrupt and quit signals from the terminal.

       If  the  trace output remains directed to the terminal, or if existing processes are traced (the -p option), then truss responds to hangup,
       interrupt, and quit signals by releasing all traced processes and exiting. This enables the user to terminate excessive trace output and to
       release previously-existing processes. Released processes continue normally, as though they had never been touched.

EXAMPLES

       Example 1: Tracing a Command

       The following example produces a trace of the find(1) command on the terminal:

       example$ truss find . -print >find.out

       Example 2: Tracing Common System Calls

       The following example shows only a trace of the open, close, read, and write system calls:

       example$ truss -t open,close,read,write find . -print >find.out

       Example 3: Tracing a Shell Script

       The following example produces a trace of the spell(1) command on the file truss.out:

       example$ truss -f -o truss.out spell document

       spell  is  a  shell  script,  so  the -f flag is needed to trace not only the shell but also the processes created by the shell. (The spell
       script runs a pipeline of eight processes.)

       Example 4: Abbreviating Output

       The following example abreviates output:

       example$ truss nroff -mm document >nroff.out

       because 97% of the output reports lseek(), read(), and write() system calls. To abbreviate it:

       example$ truss -t !lseek,read,write nroff -mm document >nroff.out

       Example 5: Tracing Library Calls From Outside the C Library

       The following example traces all user-level calls made to any function in the C library from outside the C library:

       example$ truss -u libc ...

       Example 6: Tracing library calls from within the C library

       The following example includes calls made to functions in the C library from within the C library itself:

       example$ truss -u libc:: ...

       Example 7: Tracing Library Calls Other Than the C Library

       The following example traces all user-level calls made to any library other than the C library:

       example$ truss -u '*' -u !libc ...

       Example 8: Tracing printf and scanf Function Calls

       The following example traces all user-level calls to functions in the printf and scanf family contained in the C library:

       example$ truss -u 'libc:*printf,*scanf' ...

       Example 9: Tracing Every User-level Function Call

       The following example traces every user-level function call from anywhere to anywhere:

       example$ truss -u a.out -u ld:: -u :: ...

       Example 10: Tracing a System Call Verbosely

       The following example verbosely traces the system call activity of process #1, init(1M) (if you are a privileged user):

       example# truss -p -v all 1

       Interrupting truss returns init to normal operation.

FILES

       /proc/*         Process files

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWtoo                      |
       +-----------------------------+-----------------------------+

SEE ALSO

       date(1), find(1), proc(1), ps(1), sh(1), spell(1), init(1M), intro(3), exec(2), fork(2), lseek(2),  open(2),  read(2),  time(2),  vfork(2),
       write(2), ctime(3C), signal.h(3HEAD), proc(4), attributes(5), privileges(5), threads(5)

       man pages section 2: System Calls

NOTES

       Some  of the system calls described in man pages section 2: System Calls differ from the actual operating system interfaces. Do not be sur-
       prised by minor deviations of the trace output from the descriptions in that document.

       Every machine fault (except a page fault) results in the posting of a signal to the LWP that incurred the fault. A  report  of  a  received
       signal immediately follows each report of a machine fault (except a page fault) unless that signal is being blocked.

       The  operating  system  enforces  certain  security  restrictions on the tracing of processes. In particular, any command whose object file
       (a.out) cannot be read by a user cannot be traced by that user; set-uid and set-gid commands can be  traced  only  by  a  privileged  user.
       Unless  it  is  run by a privileged user, truss loses control of any process that performs an exec() of a set-id or unreadable object file;
       such processes continue normally, though independently of truss, from the point of the exec().

       To avoid collisions with other controlling processes, truss does not trace a process that it detects is being controlled by another process
       via the /proc interface. This allows truss to be applied to proc(4)-based debuggers as well as to another instance of itself.

       The trace output contains tab characters under the assumption that standard tab stops are set (every eight positions).

       The trace output for multiple processes or for a multithreaded process (one that contains more than one LWP) is not produced in strict time
       order. For example, a read() on a pipe can be reported before the corresponding write().  For any one LWP (a traditional  process  contains
       only one), the output is strictly time-ordered.

       When  tracing more than one process, truss runs as one controlling process for each process being traced. For the example of the spell com-
       mand shown above, spell itself uses 9 process slots, one for the shell and 8 for the 8-member pipeline, while truss  adds  another  9  pro-
       cesses, for a total of 18.

       Not all possible structures passed in all possible system calls are displayed under the -v option.

SunOS 5.10                                                          31 Jul 2004                                                           truss(1)