Reformatting page.  Please Wait... done


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  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). If, in the case of an error, the ker-
     nel  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


Illumos             Last change: Jul 31, 2004                   1


User Commands                                            TRUSS(1)


         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 sig-
         nals 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 difference 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


Illumos             Last change: Jul 31, 2004                   2


User Commands                                            TRUSS(1)


         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 ter-
         minal 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 com-
         plete.


     -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  speci-
         fied  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  pro-
         cess  stopped and abandoned (see the -T option). Default
         is -M!all.


     -o outfile

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


Illumos             Last change: Jul 31, 2004                   3


User Commands                                            TRUSS(1)


         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.  Mutiple  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 speci-
         fied 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 (\t) and newline (\n).
         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  print
         >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 sig-
         nals 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 speci-
         fied signals  is  received,  truss  leaves  the  process
         stopped  and  abandoned  (see the -T option). Default is


Illumos             Last change: Jul 31, 2004                   4


User Commands                                            TRUSS(1)


         -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 speci-
         fied  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 pro-
         cess  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  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.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  mean-
         ings   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


Illumos             Last change: Jul 31, 2004                   5


User Commands                                            TRUSS(1)


         list  means  to trace calls into the libraries from out-
         side 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  ori-
         gin.

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


Illumos             Last change: Jul 31, 2004                   6


User Commands                                            TRUSS(1)


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


     The following example produces a trace of the  find(1)  com-
     mand 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


Illumos             Last change: Jul 31, 2004                   7


User Commands                                            TRUSS(1)


     Example 3 Tracing a Shell Script


     The following example produces a trace of the spell(1)  com-
     mand 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


Illumos             Last change: Jul 31, 2004                   8


User Commands                                            TRUSS(1)


     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  func-
     tions  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


Illumos             Last change: Jul 31, 2004                   9


User Commands                                            TRUSS(1)


     Interrupting truss returns init to normal operation.


FILES
     /proc/*
                Process files


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 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 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  assump-
     tion  that  standard  tab  stops  are set (every eight posi-
     tions).


Illumos             Last change: Jul 31, 2004                  10


User Commands                                            TRUSS(1)


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


Illumos             Last change: Jul 31, 2004                  11