Go Back    


Recursive Search Engine for Linux and Unix Man Pages by Neo
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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  pos-
       sible  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 privi-
       lege, 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 func-
       tion 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  sec-
	   onds  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  con-
	   taining 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 con-
	   taining 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

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

       -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 speci-
	   fied 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 pro-
	   cesses (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 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 (\t) and newline (\n). If ASCII interpreta-
	   tion 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 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 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  meanings as those of sh(1) but as applied to the library/function name spa-
	   ces, 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 operat-
	   ing 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-terminal  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  out-
       put 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 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 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 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.

SunOS 5.11				   31 Jul 2004					 truss(1)
The UNIX and Linux Forums Man Pages : 2014 The UNIX and Linux Forums


All times are GMT -4. The time now is 11:54 PM.