.fi
.sp
..
+.\" Macro IX is not defined in the groff macros
+.if \n(.g \{\
+. de IX
+..
+.\}
.TH STRACE 1 "2010-03-30"
.SH NAME
strace \- trace system calls and signals
.SH SYNOPSIS
.B strace
-[\fB-CdffhiqrtttTvVxxy\fR]
+[\fB-CdffhikqrtttTvVxxy\fR]
[\fB-I\fIn\fR]
[\fB-b\fIexecve\fR]
[\fB-e\fIexpr\fR]...
Errors (typically a return value of \-1) have the errno symbol
and error string appended.
.CW
-open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
+open("/foo/bar", O_RDONLY) = \-1 ENOENT (No such file or directory)
.CE
Signals are printed as signal symbol and decoded siginfo structure.
An excerpt from stracing and interrupting the command "sleep 666" is:
always be dereferenced. For example, retrying the "ls \-l" example
with a non-existent file produces the following line:
.CW
-lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
+lstat("/foo/bar", 0xb004) = \-1 ENOENT (No such file or directory)
.CE
In this case the porch light is on but nobody is home.
.LP
.CE
Here the second argument represents the full set of all signals.
.SH OPTIONS
+.SS Output format
.TP 12
.TP
-.B \-c
-Count time, calls, and errors for each system call and report a summary on
-program exit. On Linux, this attempts to show system time (CPU time spent
-running in the kernel) independent of wall clock time. If
-.B \-c
-is used with
-.B \-f
-or
-.B \-F
-(below), only aggregate totals for all traced processes are kept.
-.TP
-.B \-C
-Like
-.B \-c
-but also print regular output while processes are running.
+.BI "\-a " column
+Align return values in a specific column (default column 40).
.TP
-.B \-D
-Run tracer process as a detached grandchild, not as parent of the
-tracee. This reduces the visible effect of
-.B strace
-by keeping the tracee a direct child of the calling process.
+.B \-i
+Print the instruction pointer at the time of the system call.
.TP
-.B \-d
-Show some debugging output of
+.B \-k
+Print the execution stack trace of the traced processes after each system call (experimental).
+This option is available only if
.B strace
-itself on the standard error.
+is built with libunwind.
.TP
-.B \-f
-Trace child processes as they are created by currently traced
-processes as a result of the
-.BR fork (2),
-.BR vfork (2)
-and
-.BR clone (2)
-system calls. Note that
-.B \-p
-.I PID
-.B \-f
-will attach all threads of process PID if it is multi-threaded,
-not only thread with thread_id = PID.
-.TP
-.B \-ff
-If the
-.B \-o
+.BI "\-o " filename
+Write the trace output to the file
.I filename
-option is in effect, each processes trace is written to
+rather than to stderr.
+Use
.I filename.pid
-where pid is the numeric process id of each process.
-This is incompatible with
-.BR \-c ,
-since no per-process counts are kept.
-.TP
-.B \-F
-This option is now obsolete and it has the same functionality as
-.BR \-f .
-.TP
-.B \-h
-Print the help summary.
-.TP
-.B \-i
-Print the instruction pointer at the time of the system call.
+if
+.B \-ff
+is used.
+If the argument begins with '|' or with '!' then the rest of the
+argument is treated as a command and all output is piped to it.
+This is convenient for piping the debugging output to a program
+without affecting the redirections of executed programs.
.TP
.B \-q
Suppress messages about attaching, detaching etc. This happens
records the time difference between the beginning of successive
system calls.
.TP
+.BI "\-s " strsize
+Specify the maximum string size to print (the default is 32). Note
+that filenames are not considered strings and are always printed in
+full.
+.TP
.B \-t
Prefix each line of the trace with the time of day.
.TP
of seconds since the epoch.
.TP
.B \-T
-Show the time spent in system calls. This records the time
+Show the time spent in system calls. This records the time
difference between the beginning and the end of each system call.
.TP
-.B \-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.
-.TP
-.B \-V
-Print the version number of
-.BR strace .
-.TP
.B \-x
Print all non-ASCII strings in hexadecimal string format.
.TP
.B \-y
Print paths associated with file descriptor arguments.
.TP
-.BI "\-a " column
-Align return values in a specific column (default column 40).
+.B \-yy
+Print protocol specific information associated with socket file descriptors.
+.SS Statistics
+.TP 12
.TP
-.BI "\-b " syscall
-If specified syscall is reached, detach from traced process.
-Currently, only
-.I execve
-syscall is supported. This option is useful if you want to trace
-multi-threaded process and therefore require -f, but don't want
-to trace its (potentially very complex) children.
+.B \-c
+Count time, calls, and errors for each system call and report a summary on
+program exit. On Linux, this attempts to show system time (CPU time spent
+running in the kernel) independent of wall clock time. If
+.B \-c
+is used with
+.B \-f
+or
+.B \-F
+, only aggregate totals for all traced processes are kept.
+.TP
+.B \-C
+Like
+.B \-c
+but also print regular output while processes are running.
+.TP
+.BI "\-O " overhead
+Set the overhead for tracing system calls to
+.I 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
+.B \-c
+option. The accuracy of the heuristic can be gauged by timing a given
+program run without tracing (using
+.BR time (1))
+and comparing the accumulated
+system call time to the total produced using
+.BR \-c .
+.TP
+.BI "\-S " sortby
+Sort the output of the histogram printed by the
+.B \-c
+option by the specified criterion. Legal values are
+.BR time ,
+.BR calls ,
+.BR name ,
+and
+.B nothing
+(default is
+.BR time ).
+.TP
+.B \-w
+Summarise the time difference between the beginning and end of
+each system call. The default is to summarise the system time.
+.SS Filtering
+.TP 12
.TP
.BI "\-e " expr
A qualifying expression which modifies which events to trace
or how to trace them. The format of the expression is:
.RS 15
.IP
-[\fIqualifier\fB=\fR][\fB!\fR]\fIvalue1\fR[\fB,\fIvalue2\fR]...
+[\,\fIqualifier\/\fB=\fR][\fB!\fR]\,\fIvalue1\/\fR[\fB,\,\fIvalue2\/\fR]...
.RE
.IP
where
.BR raw ,
.BR signal ,
.BR read ,
+.BR write ,
or
-.B write
+.B fault
and
.I value
is a qualifier-dependent symbol or number. The default
expansion even inside quoted arguments. If so, you must escape
the exclamation point with a backslash.
.TP
-\fB\-e\ trace\fR=\fIset\fR
+\fB\-e\ trace\fR=\,\fIset\fR
Trace only the specified set of system calls. The
.B \-c
option is useful for determining which system calls might be useful
.BR "\-e\ trace" = memory
Trace all memory mapping related system calls.
.TP
-\fB\-e\ abbrev\fR=\fIset\fR
+\fB\-e\ abbrev\fR=\,\fIset\fR
Abbreviate the output from printing each member of large structures.
The default is
.BR abbrev = all .
option has the effect of
.BR abbrev = none .
.TP
-\fB\-e\ verbose\fR=\fIset\fR
+\fB\-e\ verbose\fR=\,\fIset\fR
Dereference structures for the specified set of system calls. The
default is
.BR verbose = all .
.TP
-\fB\-e\ raw\fR=\fIset\fR
+\fB\-e\ raw\fR=\,\fIset\fR
Print raw, undecoded arguments for the specified set of system calls.
This option has the effect of causing all arguments to be printed
in hexadecimal. This is mostly useful if you don't trust the
decoding or you need to know the actual numeric value of an
argument.
.TP
-\fB\-e\ signal\fR=\fIset\fR
+\fB\-e\ signal\fR=\,\fIset\fR
Trace only the specified subset of signals. The default is
.BR signal = all .
For example,
.BR signal "=!" io )
causes SIGIO signals not to be traced.
.TP
-\fB\-e\ read\fR=\fIset\fR
+\fB\-e\ read\fR=\,\fIset\fR
Perform a full hexadecimal 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
and
.I 5
use
-\fB\-e\ read\fR=\fI3\fR,\fI5\fR.
+\fB\-e\ read\fR=\,\fI3\fR,\fI5\fR.
Note that this is independent from the normal tracing of the
.BR read (2)
system call which is controlled by the option
.BR -e "\ " trace = read .
.TP
-\fB\-e\ write\fR=\fIset\fR
+\fB\-e\ write\fR=\,\fIset\fR
Perform a full hexadecimal 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
and
.I 5
use
-\fB\-e\ write\fR=\fI3\fR,\fI5\fR.
+\fB\-e\ write\fR=\,\fI3\fR,\,\fI5\fR.
Note that this is independent from the normal tracing of the
.BR write (2)
system call which is controlled by the option
.BR -e "\ " trace = write .
.TP
+\fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
+Perform a syscall fault injection for the specified set of syscalls.
+When a fault is injected into a syscall invocation, the syscall number
+is replaced by -1 which corresponds to an invalid syscall.
+
+If an error code is specified using a symbolic
+.I errno
+value like
+.B ENOSYS
+or a numeric value within 1..4095 range, this error code overrides
+the default error code returned by the kernel, which is traditionally
+.B ENOSYS
+for invalid syscall numbers on most architectures.
+
+Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
+a fault is injected into every invocation of each syscall from the
+.IR set .
+
+The format of the subexpression is one of the following:
+.RS
+.IP "" 2
+.I first
+.RS 4
+For every syscall from the
+.IR set ,
+perform a syscall fault injection for the syscall invocation number
+.I first
+only.
+.RE
+.IP "" 2
+\fIfirst\/\fB+\fR
+.RS 4
+For every syscall from the
+.IR set ,
+perform syscall fault injections for the syscall invocation number
+.I first
+and all subsequent invocations.
+.RE
+.IP "" 2
+\fIfirst\/\fB+\fIstep\fR
+.RS 4
+For every syscall from the
+.IR set ,
+perform syscall fault injections for syscall invocations number
+.IR first ,
+.IR first + step ,
+.IR first + step + step ,
+and so on.
+.RE
+.RE
+.IP
+For example, to fail each third and subsequent chdir syscalls with
+.BR ENOENT ,
+use
+\fB\-e\ fault\fR=\,\fIchdir\/\fR:\fBerror\fR=\,\fIENOENT\/\fR:\fBwhen\fR=\,\fI3\/\fB+\fR.
+
+The valid range for numbers
+.I first
+and
+.I step
+is 1..65535.
+
+If a fault expression contains multiple
+.BR error =
+specifications, the last one takes precedence.
+Likewise, if a fault expression contains multiple
+.BR when =
+specifications, the last one takes precedence.
+
+Accounting of syscalls that are subject to fault injection
+is done per syscall and per tracee.
+
+Specification of syscall fault injection can be combined
+with other syscall filtering options, for example,
+\fB\-P \fI/dev/urandom \fB\-e fault\fR=\,\fIall\/\fR:\fBerror\fR=\,\fIENOENT\fR.
+.TP
+.BI "\-P " path
+Trace only system calls accessing
+.IR path .
+Multiple
+.B \-P
+options can be used to specify several paths.
+.TP
+.B \-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.
+.SS Tracing
+.TP 12
+.TP
+.BI "\-b " syscall
+If specified syscall is reached, detach from traced process.
+Currently, only
+.I execve
+syscall is supported. This option is useful if you want to trace
+multi-threaded process and therefore require -f, but don't want
+to trace its (potentially very complex) children.
+.TP
+.B \-D
+Run tracer process as a detached grandchild, not as parent of the
+tracee. This reduces the visible effect of
+.B strace
+by keeping the tracee a direct child of the calling process.
+.TP
+.B \-f
+Trace child processes as they are created by currently traced
+processes as a result of the
+.BR fork (2),
+.BR vfork (2)
+and
+.BR clone (2)
+system calls. Note that
+.B \-p
+.I PID
+.B \-f
+will attach all threads of process PID if it is multi-threaded,
+not only thread with thread_id = PID.
+.TP
+.B \-ff
+If the
+.B \-o
+.I filename
+option is in effect, each processes trace is written to
+.I filename.pid
+where pid is the numeric process id of each process.
+This is incompatible with
+.BR \-c ,
+since no per-process counts are kept.
+.TP
.BI "\-I " interruptible
When strace can be interrupted by signals (such as pressing ^C).
1: no signals are blocked; 2: fatal signals are blocked while decoding syscall
(default); 3: fatal signals are always blocked (default if '-o FILE PROG');
4: fatal signals and SIGTSTP (^Z) are always blocked (useful to make
strace -o FILE PROG not stop on ^Z).
+.SS Startup
+.TP 12
.TP
-.BI "\-o " filename
-Write the trace output to the file
-.I filename
-rather than to stderr.
-Use
-.I filename.pid
-if
-.B \-ff
-is used.
-If the argument begins with '|' or with '!' then the rest of the
-argument is treated as a command and all output is piped to it.
-This is convenient for piping the debugging output to a program
-without affecting the redirections of executed programs.
+\fB\-E\ \fIvar\fR=\,\fIval\fR
+Run command with
+.IR var = val
+in its list of environment variables.
.TP
-.BI "\-O " overhead
-Set the overhead for tracing system calls to
-.I 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
-.B \-c
-option. The accuracy of the heuristic can be gauged by timing a given
-program run without tracing (using
-.BR time (1))
-and comparing the accumulated
-system call time to the total produced using
-.BR \-c .
+.BI "\-E " var
+Remove
+.IR var
+from the inherited list of environment variables before passing it on to
+the command.
.TP
.BI "\-p " pid
Attach to the process with the process
leaving it (them) to continue running.
Multiple
.B \-p
-options can be used to attach to many processes.
--p "`pidof PROG`" syntax is supported.
-.TP
-.BI "\-P " path
-Trace only system calls accessing
-.I path.
-Multiple
-.B \-P
-options can be used to specify several paths.
-.TP
-.BI "\-s " strsize
-Specify the maximum string size to print (the default is 32). Note
-that filenames are not considered strings and are always printed in
-full.
-.TP
-.BI "\-S " sortby
-Sort the output of the histogram printed by the
-.B \-c
-option by the specified criterion. Legal values are
-.BR time ,
-.BR calls ,
-.BR name ,
-and
-.B nothing
-(default is
-.BR time ).
+options can be used to attach to many processes in addition to
+.I command
+(which is optional if at least one
+.B \-p
+option is given).
+.B \-p
+"`pidof PROG`" syntax is supported.
.TP
.BI "\-u " username
Run command with the user \s-1ID\s0, group \s-2ID\s0, and
correct execution of setuid and/or setgid binaries.
Unless this option is used setuid and setgid programs are executed
without effective privileges.
+.SS Miscellaneous
+.TP 12
.TP
-\fB\-E\ \fIvar\fR=\fIval\fR
-Run command with
-.IR var = val
-in its list of environment variables.
+.B \-d
+Show some debugging output of
+.B strace
+itself on the standard error.
.TP
-.BI "\-E " var
-Remove
-.IR var
-from the inherited list of environment variables before passing it on to
-the command.
+.B \-F
+This option is now obsolete and it has the same functionality as
+.BR \-f .
+.TP
+.B \-h
+Print the help summary.
+.TP
+.B \-V
+Print the version number of
+.BR strace .
.SH DIAGNOSTICS
When
.I command
is used.
.LP
When using
-.BR \-p ,
+.B \-p
+without a
+.IR command ,
the exit status of
.B strace
-is zero unless there was an unexpected error in doing the tracing.
+is zero unless no processes has been attached or there was an unexpected error
+in doing the tracing.
.SH "SETUID INSTALLATION"
If
.B strace
a non-setuid version of
.B strace
for ordinary lusers to use.
-.SH "SEE ALSO"
-.BR ltrace (1),
-.BR time (1),
-.BR ptrace (2),
-.BR proc (5)
.SH NOTES
It is a pity that so much tracing clutter is produced by systems
employing shared libraries.
system call interface and are accounted for by C library wrapper
functions.
.LP
+Some system calls have different names in different architectures and
+personalities. In these cases, system call filtering and printing
+uses the names that match corresponding
+.BR __NR_ *
+kernel macros of the tracee's architecture and personality.
+There are two exceptions from this general rule:
+.BR arm_fadvise64_64 (2)
+ARM syscall and
+.BR xtensa_fadvise64_64 (2)
+Xtensa syscall are filtered and printed as
+.BR fadvise64_64 (2).
+.LP
On some platforms a process that is attached to with the
.B \-p
option may observe a spurious EINTR return from the current
-system call that is not restartable. (Ideally, all system calls
+system call that is not restartable. (Ideally, all system calls
should be restarted on strace attach, making the attach invisible
to the traced process, but a few system calls aren't.
Arguably, every instance of such behavior is a kernel bug.)
.B strace
to Irix
and tired of writing about himself in the third person.
-.SH PROBLEMS
+.SH REPORTING BUGS
Problems with
.B strace
should be reported to the
.B strace
mailing list at <strace\-devel@lists.sourceforge.net>.
+.SH "SEE ALSO"
+.BR ltrace (1),
+.BR time (1),
+.BR ptrace (2),
+.BR proc (5)
projects / strace / blobdiff