truss(C)

truss -- trace process execution

Syntax

truss [ -o outfile ] [ -p pid ] [ -t syscall ] [ -n ] [ -b size ] [ program [args...] ]

Description

The truss command traces a process, displaying the system calls it makes and the signals it receives. truss is similar in purpose and behavior to trace(CP), but produces a different output format and decodes system calls differently.

truss can start the process that you want to trace, or it can attach to an existing process that is already running.

Once truss and the process to be traced are both running, truss reports system calls made by the process, including any arguments and results. It also reports signals received by the process, and the process's final exit status.

If the traced process forks, truss follows both the parent and the child, unless the -n option was specified. When multiple processes are traced, each line representing a system call is prefixed by the process ID of the process that made it.

truss takes the following options:

-b size

Controls the number of bytes of data that are displayed for system calls that transfer data to or from process buffers (for example, read(S) and writev(S)). The default is 50.

-n

Do not trace the execution of child processes that are forked by the traced process.

-o outfile

Writes the results of the trace to outfile instead of to standard error.

-p pid

Traces the existing process with pid, the given process ID. The specified process must be owned by the user running truss or by root. truss needs access to the executable binary from which the process is running. If the process is not started with an explicit path (/path/binary_name), and if the correct binary cannot be located in one of the directories specified by $PATH, it must be specified on the truss command line.

For example:

truss testprog: ---- start a new process running testprog
truss -p 1234: ---- attach to existing process ID 1234
truss -p 1234 /tmp/testprog: ---- attach to existing process ID 1234, which is running /tmp/testprog

-t syscall

Limits the trace to the syscall system call. This option can be specified multiple times on the command line. For example:

truss -t open -t close ./myprog test.in test.out

program [args...]

Executes the specified program with the given arguments. When used with the -p option, the arguments are ignored and program is only used to find the binary being executed by the process.

Notes

truss searches $PATH to find the executable binary. Thus, if ``.'' is not in $PATH, you must enter ./program to trace a program in the current directory.
truss requires read and execute permission on the binary and on any shared libraries used by the binary. Many operating system utilities are shipped with execute-only permissions. To trace these as a non-root user, it is best to have root make a new, world-readable copy of the utility in a different directory.
truss is implemented with ptrace(S) and is subject to the its permission rules. truss will not trace the execution of a setuid or setgid process except when run by root.
truss supports 80386 COFF and ELF binaries. It can be used to trace 8086 or 80286 OMF (Microsoft a.out) binaries by explicitly invoking x286emul:

truss /bin/x286emul omfprog

You can trace 80286 COFF binaries by explicitly invoking i286emul and shell scripts by explicitly invoking the shell. 80386 OMF binaries are not supported.
Unlike trace(CP), truss does not require unstripped binaries.
Some system calls and library functions may display differently than you expect. truss shows the true system calls made, which in some cases are different from the documented library interfaces offered to the application programmer. There may also be some system calls that truss does not decode (these are displayed in hexadecimal), or that it does not fully decode the arguments.

Examples

   $ truss cat /dev/null
   fxstat(51, 1, 0x80478f8) = 0
   open("/dev/null", 0x0, 0x1b6) = 3
   fxstat(51, 3, 0x804796c) = 0
   read(3, "NULL, 16384) = 0
   close(3) = 0
   Process 22710 terminated normally with 0
   Child process has exited

   $ truss sleep 3
   alarm(0) = 0
   sigprocmask(1, 0x8047998, 0x8047990) = 0
   alarm(3) = 0
   sigsuspend(0x8047994) = ... (sleeping)
   Process 22496 got signal SIGALRM (Alarm clock) at eip=0x80032650
   sigsuspend(0x8047994) = EINTR
   alarm(0) = 0
   sigprocmask(2, 0x8047998, 0x0) = 0
   Process 22496 terminated normally with 0
   Child process has exited

Copyright

truss(C) is based on scotruss, by Troy DeJongh and Eric Sybesma.