truss(1)




NAME

     truss - trace system calls and signals


SYNOPSIS

     truss [-fcaeildD] [ - [tTvx] [!] syscall ,...] [ - [sS]  [!]
     signal  ,...] [ - [mM] [!] fault ,...] [ - [rw] [!] fd ,...]
     [ - [uU] [!] lib ,... : [:] [!] func ,...] [-o outfile] com-
     mand | -p pid...


DESCRIPTION

     The truss utility executes the specified  command  and  pro-
     duces  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 possi-
     ble 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).

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


OPTIONS

     The following options are recognized. For those options that
     take  a  list argument, the name all can be used as a short-
     hand 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 may be specified. For the
     same name in a list, subsequent options (those to the right)
     override previous ones (those to the left).

     -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.
           Processes may also be specified by their names in  the
           /proc directory, for example, /proc/12345.

     -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  com-
           mand  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.

     -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.

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

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

     -i    Do 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.

     -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  will
           show  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.

     -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,...
           System calls that stop the process. The specified sys-
           tem 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 sys-
           tem 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  res-
           tarted  by the application of kill -CONT because it is
           stopped on an event of interest via /proc, not by  the
           default    action    of   a   stopping   signal   (see
           signal(3HEAD)).   The  prun(1)  command  described  in
           proc(1) can be used to set the stopped process running
           again.

     -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.

     -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 hack-
           ers  who must see the raw bits to be happy. Default is
           -x!all.

     -s [!]signal,...
           Signals to trace or exclude. Those  signals  specified
           in the comma-separated list are traced. The trace out-
           put 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  may  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  pro-
           cess  stopped  and  abandoned  (see  the  -T  option).
           Default is -S!all.

     -m [!]fault,...
           Machine faults  to  trace  or  exclude.  Those  faults
           specified  in  the  comma-separated  list  are traced.
           Faults  may  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.

     -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  con-
           trol  characters  such as horizontal tab (\t) and new-
           line (\n). If ASCII interpretation  is  not  possible,
           the byte is shown in 2-character hexadecimal represen-
           tation. (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.

     -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.

     -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  func-
           tion list means to trace calls into the libraries from
           outside the libraries, but omit calls  made  to  func-
           tions  in  a  library from other functions in the same
           library. A double :: means to trace all calls, regard-
           less of origin.

           Library patterns do not match  either  the  executable
           file  or  the  dynamic linker unless there is an exact
           match (l* will not match ld.so.1). To trace  functions
           in  either  of these objects, the names must be speci-
           fied 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 may  be  specified  and  they  are
           honored  left-to-right.  If the process is linked with
           -lthread, 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 will also search
           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).

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

     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-terminal  file,  then  truss  runs  with
     hangup,  interrupt,  and  quit signals ignored. This facili-
     tates 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

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

     example$ truss find . -print >find.out

     Example 2: Tracing common system calls

     To see only a trace of the open, close, read, and write sys-
     tem calls:

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

     Example 3: Tracing a shell script

     This 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

     A particularly boring example is:

     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

     This example traces all user-level calls made to  any  func-
     tion in the C library from outside the C library:

     example$ truss -u libc ...

     Example 6: Tracing library calls from within the C library

     This 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

     This 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

     This 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 any user-level function call

     This example traces every user-level function call from any-
     where to anywhere:

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

     Example 10: Tracing a system call verbosely

     This 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  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWtoo (32-bit)            |
    |_____________________________|_____________________________|
    |                             | SUNWtoox (64-bit)           |
    |_____________________________|_____________________________|


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),
     threads(3THR), proc(4), attributes(5), signal(3HEAD)

     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 inter-
     faces. Do not be surprised 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  will  immediately  follow  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
     will 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  assump-
     tion  that  standard  tab  stops  are set (every eight posi-
     tions).

     The trace output  for  multiple  processes  or  for  a  mul-
     tithreaded  process (one that contains more than one LWP) is
     not produced in strict time order. For example, a read()  on
     a pipe may 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  con-
     trolling  process  for  each  process  being traced. For the
     example of the spell command shown above, spell itself  uses
     9  process  slots,  one for the shell and 8 for the 8-member
     pipeline, while truss adds another 9 processes, for a  total
     of 18.

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


Man(1) output converted with man2html