strace

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       strace - trace system calls and signals


SYNOPSIS

       strace  [ -dffhiqrtttTvxx ] [ -acolumn ] [ -eexpr ] ...  [
       -ofile ] [ -ppid ] ...  [ -sstrsize ] [ command [ arg  ...
       ] ]

       strace  -c  [  -eexpr ] ...  [ -Ooverhead ] [ -Ssortby ] [
       command [ arg ...  ] ]


DESCRIPTION

       In the simplest case strace  runs  the  specified  command
       until  it  exits.   It  intercepts  and records the system
       calls which are called by a process and the signals  which
       are  received by a process.  The name of each system call,
       its arguments and its return value are printed on standard
       error or to the file specified with the -o option.

       strace  is a useful diagnositic, instructional, and debug-
       ging tool.  System adminstrators, diagnosticians and trou-
       ble-shooters  will find it invaluable for solving problems
       with programs for which the source is not  readily  avail-
       able  since  they do not need to be recompiled in order to
       trace them.  Students, hackers and the overly-curious will
       find  that  a great deal can be learned about a system and
       its system calls by tracing even ordinary  programs.   And
       programmers  will find that since system calls and signals
       are events that happen at  the  user/kernel  interface,  a
       close  examination of this boundary is very useful for bug
       isolation, sanity checking and attempting to capture  race
       conditions.

       Each line in the trace contains the system call name, fol-
       lowed by its  arguments  in  parentheses  and  its  return
       value.    An  example  from  stracing  the  command  ``cat
       /dev/null'' is:

       open("/dev/null", O_RDONLY) = 3

       Errors (typically a return value of  -1)  have  the  errno
       symbol and error string appended.

       open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)

       Signals  are  printed  as  a  signal  symbol  and a signal
       string.  An excerpt from  stracing  and  interrupting  the
       command ``sleep 666'' is:

       sigsuspend([] <unfinished ...>
       --- SIGINT (Interrupt) ---
       +++ killed by SIGINT +++

       Arguments  are  printed  in  symbolic form with a passion.
       This example shows the shell peforming ``>>xyzzy''  output
       redirection:

       open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3

       Here  the three argument form of open is decoded by break-
       ing down the flag argument into its three bitwise-OR  con-
       stituents  and  printing the mode value in octal by tradi-
       tion.  Where traditional or native usage differs from ANSI
       or  POSIX, the latter forms are preferred.  In some cases,
       strace output has proven to  be  more  readable  than  the
       source.

       Structure  pointers  are  dereferenced and the members are
       displayed as appropriate.  In all cases arguments are for-
       matted  in the most C-like fashion possible.  For example,
       the essence of the command ``ls -l /dev/null'' is captured
       as:

       lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(1, 3), ...}) = 0

       Notice  how the `struct stat' argument is dereferenced and
       how each member is displayed symbolically.  In particular,
       observe how the st_mode member is carefully decoded into a
       bitwise-OR of symbolic and numeric values.  Also notice in
       this  example that the first argument to lstat is an input
       to the system call and the second argument is  an  output.
       Since  output  arguments  not  modified if the system call
       fails, arguments may  not  always  be  dereferenced.   For
       example,  retrying  the ``ls -l'' example with a non-exis-
       tent file produces the following line:

       lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)

       In this case the porch light is on but nobody is home.

       Character pointers  are  dereferenced  and  printed  as  C
       strings.   Non-printing characters in strings are normally
       represented by ordinary C escape codes.   Only  the  first
       strsize  (32  by  default)  bytes  of strings are printed;
       longer strings have an  ellipsis  appended  following  the
       closing  quote.   Here  is a line from ``ls -l'' where the
       getpwuid library routine is reading the password file:

       read(3, "root::0:0:System Administrator:/"..., 1024) = 422

       While structures are annotated using curly braces,  simple
       pointers and arrays are printed using square brackets with
       commas separating elements.  Here is an example  from  the
       command ``id'' on a system with supplementary group ids:

       getgroups(32, [100, 0]) = 2

       On  the  other  hand, bit-sets are also shown using square
       brackets but set elements are separated only by  a  space.
       Here  is  the  shell preparing to execute an external com-
       mand:

       sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0

       Here the second argument is  a  bit-set  of  two  signals,
       SIGCHLD and SIGTTOU.  In some cases the bit-set is so full
       that printing out the unset elements is more valuable.  In
       that case, the bit-set is prefixed by a tilde like this:

       sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0

       Here  the  second  argument represents the full set of all
       signals.


OPTIONS

       -c          Count time, calls, and errors for each  system
                   call and report a summary on program exit.

       -d          Show some debugging output of strace itself on
                   stderr .

       -f          Trace child processes as they are  created  by
                   currently  traced processes as a result of the
                   fork(2)  system  call.   The  new  process  is
                   attached  to  as  soon  as  its  pid  is known
                   (through the return value of  fork(2)  in  the
                   parent process). This means that such children
                   may run uncontrolled for a  while  (especially
                   in  the  case of a vfork(2)), until the parent
                   is scheduled again to complete its  (v)fork(2)
                   call.    If  the  parent  process  decides  to
                   wait(2) for a child that  is  currently  being
                   traced,  it  is suspended until an appropriate
                   child process either terminates  or  incurs  a
                   signal  that  would  cause it to terminate (as
                   determined from  the  child's  current  signal
                   disposition).

       -ff         If  the  -ofilename  option is in effect, each
                   processes trace  is  written  to  filename.pid
                   where  pid  is  the numeric process id of each
                   process.

       -F          On SunOS 4.x, this option has  the  effect  of
                   attempting to follow vforks by performing some
                   dynamic linking trickery.   Otherwise,  vforks
                   will  not  be  followed  even  if  -f has been
                   given.

       -h          Print the help summary.

       -i          Print the instruction pointer at the  time  of
                   the system call.

       -q          Suppress  messages  about attaching, detaching
                   etc.  This happens automatically  when  output
                   is redirected to a file and the command is run
                   directly instead of attaching.

       -r          Print a relative timestamp upon entry to  each
                   system call.  This records the time difference
                   between the  beginning  of  successive  system
                   calls.

       -t          Prefix each line of the trace with the time of
                   day.

       -tt         If given twice, the time printed will  include
                   the microseconds.

       -T          Show  the  time  spent  in  system calls. This
                   records the time difference between the begin-
                   ning and the end of each system call.

       -v          Print  unabbreviated  versions of environment,
                   stat, termios, etc.  calls.  These  structures
                   are  very  common  in calls and so the default
                   behavior  displays  a  reasonable  subset   of
                   structure members.  Use this option to get all
                   of the gory details.

       -V          Print the version number of strace.

       -x          Print all  non-ascii  strings  in  hexidecimal
                   string format.

       -xx         Print  all  strings in hexidecimal string for-
                   mat.

       -acolumn    Align  return  values  in  a  secific   column
                   (default column 40).

       -eexpr      A  qualifying  expression which modifies which
                   events to trace or how  to  trace  them.   The
                   format of the expression is:
                   [qualifier=][!]value1[,value2]...
                   where  qualifier is one of trace, abbrev, ver-
                   bose, raw, signal, read, or write and value is
                   a  qualifier-dependent  symbol or number.  The
                   default qualifier is trace.  Using an exclama-
                   tion  mark  negates  the  set  of values.  For
                   example -eopen means literally  -e  trace=open
                   which in turn means trace only the open system
                   call.  By  contrast,  -etrace=!open  means  to
                   trace every system call except open.  In addi-
                   tion the special values all and none have  the
                   obvious meanings.

       -etrace=set Trace  only the specified set of system calls.
                   The -c option is useful for determining  which
                   system  calls  might  be useful to trace.  For
                   example, trace=open,close,read,write means  to
                   only  trace those four system calls.  Be care-
                   ful when making inferences about the user/ker-
                   nel  boundary if only a subset of system calls
                   are   being   monitored.    The   default   is
                   trace=all.

       -eabbrev=set
                   Abbreviate  the output from printing each mem-
                   ber  of  large  structures.   The  default  is
                   abbrev=all.   The  -v option has the effect of
                   abbrev=none.

       -everbose=set
                   Dereference structures for the  specified  set
                   of  system calls.  The default is verbose=all.

       -eraw=set   Print  raw,  undecoded   arguments   for   the
                   specifed set of system calls.  This option has
                   the effect of  causing  all  arguments  to  be
                   printed in hexidecimal.  This is mostly useful
                   if you don't trust the decoding or you need to
                   know  the actual numeric value of an argument.

       -esignal=set
                   Trace only the specified  subset  of  signals.
                   The  default  is signal=all.  For example sig-
                   nal=!SIGIO (or signal=!io) causes  SIGIO  sig-
                   nals not to be traced.

       -eread=set  Perform  a  full hexidecimal and ascii dump of
                   all the data read from file descriptors listed
                   in the specified set.  For example, to see all
                   input activity on file descriptors 3 and 5 use
                   read=3,5.

       -ewrite=set Perform  a  full hexidecimal and ascii dump of
                   all  the  data  written  to  file  descriptors
                   listed  in the specified set.  For example, to
                   see all output activity on file descriptors  3
                   and 5 use read=3,5.

       -ofilename  Write  the  trace  output to the file filename
                   rather than to stderr.   Use  filename.pid  if
                   -ff is used.

       -Ooverhead  Set  the  overhead for tracing system calls to
                   overhead microseconds.   This  is  useful  for
                   overriding  the default heuristic for guessing
                   how much time is spent in mere measuring  when
                   timing  system calls using the -c option.  The
                   acuracy of the heuristic can be gauged by tim-
                   ing a given program run without tracing (using
                   time(1)) and comparing the accumulated  system
                   call time to the total produced using -c .

       -ppid       Attach  to the process with the process ID pid
                   and begin tracing.  The trace  may  be  termi-
                   nated at any time by a keyboard interrupt sig-
                   nal (CTRL-C).  strace will respond by  detach-
                   ing itself from the traced process(es) leaving
                   it (them) to continue  running.   Multiple  -p
                   options can be used to attach to up to MAXPROC
                   (currently 32) processes in addition  to  com-
                   mand  (which  is  optional  if at least one -p
                   option is given).

       -sstrsize   Specify the maximum string size to print  (the
                   default  is  32).  Note that filenames are not
                   considered strings and are always  printed  in
                   full.

       -Ssortby    Sort  the  output  of the histogram printed by
                   the -c  option  by  the  specified  critereon.
                   Legal  values are time, calls, name, and noth-
                   ing (default time).


SEE ALSO

       ptrace(2), time(1), trace(1)


NOTES

       It is a pity that so much tracing clutter is  produced  by
       systems  employing  shared libraries.  It is more reminis-
       cent of the Multics operating system than the one that was
       trying to ridicule it.

       It  is  instructive  to think about system call inputs and
       outputs as  data-flow  across  the  user/kernel  boundary.
       Because  user-space  and  kernel-space  are  separate  and
       address-protected, it is sometimes possible to make deduc-
       tive  inferences  about  process behavior using inputs and
       outputs as propositions.

       In some cases, a system call will differ  from  the  docu-
       mented behavior.  For example, on System V derived systems
       the true time(2) system call does not  take  an  argument.
       These  discrepancies  are normal but idiosyncratic charac-
       teristics of the system call interface and  are  accounted
       for by C library system call interface functions.

       On  some  platforms a process that has a system call trace
       applied to it with the -p option will receive  a  SIGSTOP.
       This  signal  may  interrupt  a  system  call  that is not
       restartable.  This may have an unpredictable effect on the
       process if the process takes no action to restart the sys-
       tem call.


BUGS

       Tracing a subset of calls can inhibit the ability to  fol-
       low  forks  if  certain  keys system calls are not traced,
       like fork and wait4.

       Programs that use the setuid bit  do  not  have  effective
       user ID privileges while being traced.

       A traced process ignores SIGSTOP.

       A traced process which tries to block SIGTRAP will be sent
       a SIGSTOP in an attempt to force continuation of  tracing.

       A traced process runs slowly.

       Traced  processes  which are descended from command may be
       left running after an interrupt signal (CTRL-C).


HISTORY

       strace was written by Paul  Kranenburg,  Branko  Lankester
       and Rick Sladkey.  The original strace was written by Paul
       Kranenburg for SunOS and was inspired by its  trace  util-
       ity.   The SunOS version of strace was ported to Linux and
       enhanced by Branko Lankester, who  also  wrote  the  Linux
       kernel  support.   Even though Paul released strace 2.5 in
       1992, Branko's work was based on Paul's strace 1.5 release
       from  1991.   In  1993, Rick Sladkey merged strace 2.5 for
       SunOS and the second release of strace  for  Linux,  added
       the  best  features  of  truss  from SVR4, and produced an
       strace that worked on both platforms.  In 1994 Rick ported
       strace to SVR4 and Solaris and wrote the automatic config-
       uration support.
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.