.CE
Here, the second argument represents the full set of all signals.
.SH OPTIONS
-.SS Output format
-.TP 12
-.BI "\-a " column
-Align return values in a specific column (default column 40).
-.TP
-.B \-i
-Print the instruction pointer at the time of the system call.
-.if '@ENABLE_STACKTRACE_TRUE@'#' .ig end_unwind
-.TP
-.B \-k
-Print the execution stack trace of the traced processes after each system call.
-.end_unwind
-.TP
-.BI "\-o " filename
-Write the trace output to the file
-.I filename
-rather than to stderr.
-.IR filename . pid
-form is used if
-.B \-ff
-option is supplied.
-If the argument begins with '|' or '!', 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.
-The latter is not compatible with
-.B \-ff
-option currently.
-.TP
-.B \-A
-Open the file provided in the
-.B \-o
-option in append mode.
-.TP
-.B \-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.
-.TP
-.B \-qq
-If given twice, suppress messages about process exit status.
-.TP
-.B \-r
-Print a relative timestamp upon entry to each system call. This
-records the time difference between the beginning of successive
-system calls.
-Note that since
-.B \-r
-option uses the monotonic clock time for measuring time difference and not the
-wall clock time, its measurements can differ from the difference in time
-reported by the
-.B \-t
-option.
-.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 wall clock time.
-.TP
-.B \-tt
-If given twice, the time printed will include the microseconds.
-.TP
-.B \-ttt
-If given thrice, the time printed will include the microseconds
-and the leading portion will be printed as the number
-of seconds since the epoch.
-.TP
-.B \-T
-Show the time spent in system calls. This records the time
-difference between the beginning and the end of each system call.
-.TP
-.B \-x
-Print all non-ASCII strings in hexadecimal string format.
-.TP
-.B \-xx
-Print all strings in hexadecimal string format.
-.TP
-.BI "\-X " format
-Set the format for printing of named constants and flags.
-Supported
-.I format
-values are:
-.RS
-.TP 10
-.B raw
-Raw number output, without decoding.
-.TP
-.B abbrev
-Output a named constant or a set of flags instead of the raw number if they are
-found.
-This is the default
-.B strace
-behaviour.
-.TP
-.B verbose
-Output both the raw value and the decoded string (as a comment).
-.RE
-.TP
-.B \-y
-Print paths associated with file descriptor arguments.
-.TP
-.B \-yy
-Print protocol specific information associated with socket file descriptors,
-and block/character device number associated with device file descriptors.
-.SS Statistics
-.TP 12
-.B \-c
-Count time, calls, and errors for each system call and report a summary on
-program exit, suppressing the regular output.
-This attempts to show system time (CPU time spent running
-in the kernel) independent of wall clock time. If
-.B \-c
-is used with
-.BR \-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
+.SS General
.TP 12
.BI "\-e " expr
A qualifying expression which modifies which events to trace
Note that some shells use the exclamation point for history
expansion even inside quoted arguments. If so, you must escape
the exclamation point with a backslash.
+.SS Startup
+.TP 12
+\fB\-E\ \fIvar\fR=\,\fIval\fR
+Run command with
+.IR var = val
+in its list of environment variables.
+.TP
+.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
+.SM ID
+.I pid
+and begin tracing.
+The trace may be terminated
+at any time by a keyboard interrupt signal
+.RB ( CTRL\-C ).
+.B strace
+will respond by detaching itself from the traced process(es)
+leaving it (them) to continue running.
+Multiple
+.B \-p
+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
+supplementary groups of
+.IR username .
+This option is only useful when running as root and enables the
+correct execution of setuid and/or setgid binaries.
+Unless this option is used setuid and setgid programs are executed
+without effective privileges.
+.SS Tracing
+.TP 12
+.BI "\-b " syscall
+If specified syscall is reached, detach from traced process.
+Currently, only
+.BR execve (2)
+syscall is supported. This option is useful if you want to trace
+multi-threaded process and therefore require
+.BR \-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
+.I PID
+if it is multi-threaded, not only thread with
+.IR thread_id " = " PID .
+.TP
+.B \-ff
+If the
+.B \-o
+.I filename
+option is in effect, each processes trace is written to
+.IR filename . pid
+where
+.I pid
+is the numeric process id of each process.
+This is incompatible with
+.BR \-c ,
+since no per-process counts are kept.
+
+One might want to consider using
+.BR strace-log-merge (1)
+to obtain a combined strace log view.
.TP
+.BI "\-I " interruptible
+When
+.B strace
+can be interrupted by signals (such as pressing
+.BR CTRL\-C ).
+.RS
+.TP 4
+.B 1
+no signals are blocked;
+.TQ
+.B 2
+fatal signals are blocked while decoding syscall (default);
+.TQ
+.B 3
+fatal signals are always blocked (default if
+.BR -o " " \fIFILE\fR " " \fIPROG\fR );
+.TQ
+.B 4
+fatal signals and
+.BR SIGTSTP " (" CTRL\-Z )
+are always blocked (useful to make
+.BI "strace -o " "FILE PROG"
+not stop on
+.BR CTRL\-Z ,
+default if
+.BR \-D ).
+.RE
+.SS Filtering
+.TP 12
\fB\-e\ trace\fR=\,\fIset\fR
Trace only the specified set of system calls. The
.B \-c
.BR metag_get_tls "(2)"
syscalls.
.TP
+\fB\-e\ signal\fR=\,\fIset\fR
+Trace only the specified subset of signals. The default is
+.BR signal = all .
+For example,
+.BR signal "=!" SIGIO
+(or
+.BR signal "=!" io )
+causes
+.B SIGIO
+signals not to be traced.
+.TP
+\fB\-e\ status\fR=\,\fIset\fR
+Print only system calls with the specified return status. The default is
+.BR status = all .
+When using the
+.B status
+qualifier, because
+.B strace
+waits for system calls to return before deciding whether they should be printed
+or not, the traditional order of events may not be preserved anymore. If two
+system calls are executed by concurrent threads,
+.B strace
+will first print both the entry and exit of the first system call to exit,
+regardless of their respective entry time. The entry and exit of the second
+system call to exit will be printed afterwards. Here is an example when
+.BR select (2)
+is called, but a different thread calls
+.BR clock_gettime (2)
+before
+.BR select (2)
+finishes:
+.CW
+[pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
+[pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
+.CE
+.TP
+.BR "\-e\ status" = successful
+Trace system calls that returned without an error code. The
+.B -z
+option has the effect of
+.BR status=successful .
+.TP
+.BR "\-e\ status" = failed
+Trace system calls that returned with an error code. The
+.B -Z
+option has the effect of
+.BR status=failed .
+.TP
+.BR "\-e\ status" = unfinished
+Trace system calls that did not return. This might happen, for example, due to
+an execve call in a neighbour thread.
+.TP
+.BR "\-e\ status" = unavailable
+Trace system calls that returned but strace failed to fetch the error status.
+.TP
+.BR "\-e\ status" = detached
+Trace system calls for which strace detached before the return.
+.TP
+.BI "\-P " path
+Trace only system calls accessing
+.IR path .
+Multiple
+.B \-P
+options can be used to specify several paths.
+.TP
+.B \-z
+Print only syscalls that returned without an error code.
+.TP
+.B \-Z
+Print only syscalls that returned with an error code.
+.SS Output format
+.TP 12
+.BI "\-a " column
+Align return values in a specific column (default column 40).
+.TP
\fB\-e\ abbrev\fR=\,\fIset\fR
Abbreviate the output from printing each member of large structures.
The default is
.B \-X raw
option.
.TP
-\fB\-e\ signal\fR=\,\fIset\fR
-Trace only the specified subset of signals. The default is
-.BR signal = all .
-For example,
-.BR signal "=!" SIGIO
-(or
-.BR signal "=!" io )
-causes
-.B SIGIO
-signals not to be traced.
-.TP
\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
system call which is controlled by the option
.BR -e "\ " trace = write .
.TP
-\fB\-e\ status\fR=\,\fIset\fR
-Print only system calls with the specified return status. The default is
-.BR status = all .
-When using the
-.B status
-qualifier, because
-.B strace
-waits for system calls to return before deciding whether they should be printed
-or not, the traditional order of events may not be preserved anymore. If two
-system calls are executed by concurrent threads,
+.BR "\-e\ kvm" = vcpu
+Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
+or higher.
+
+.TP
+.B \-i
+Print the instruction pointer at the time of the system call.
+.if '@ENABLE_STACKTRACE_TRUE@'#' .ig end_unwind
+.TP
+.B \-k
+Print the execution stack trace of the traced processes after each system call.
+.end_unwind
+.TP
+.BI "\-o " filename
+Write the trace output to the file
+.I filename
+rather than to stderr.
+.IR filename . pid
+form is used if
+.B \-ff
+option is supplied.
+If the argument begins with '|' or '!', 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.
+The latter is not compatible with
+.B \-ff
+option currently.
+.TP
+.B \-A
+Open the file provided in the
+.B \-o
+option in append mode.
+.TP
+.B \-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.
+.TP
+.B \-qq
+If given twice, suppress messages about process exit status.
+.TP
+.B \-r
+Print a relative timestamp upon entry to each system call. This
+records the time difference between the beginning of successive
+system calls.
+Note that since
+.B \-r
+option uses the monotonic clock time for measuring time difference and not the
+wall clock time, its measurements can differ from the difference in time
+reported by the
+.B \-t
+option.
+.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 wall clock time.
+.TP
+.B \-tt
+If given twice, the time printed will include the microseconds.
+.TP
+.B \-ttt
+If given thrice, the time printed will include the microseconds
+and the leading portion will be printed as the number
+of seconds since the epoch.
+.TP
+.B \-T
+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 \-x
+Print all non-ASCII strings in hexadecimal string format.
+.TP
+.B \-xx
+Print all strings in hexadecimal string format.
+.TP
+.BI "\-X " format
+Set the format for printing of named constants and flags.
+Supported
+.I format
+values are:
+.RS
+.TP 10
+.B raw
+Raw number output, without decoding.
+.TP
+.B abbrev
+Output a named constant or a set of flags instead of the raw number if they are
+found.
+This is the default
.B strace
-will first print both the entry and exit of the first system call to exit,
-regardless of their respective entry time. The entry and exit of the second
-system call to exit will be printed afterwards. Here is an example when
-.BR select (2)
-is called, but a different thread calls
-.BR clock_gettime (2)
-before
-.BR select (2)
-finishes:
-.CW
-[pid 28779] 1130322148.939977 clock_gettime(CLOCK_REALTIME, {1130322148, 939977000}) = 0
-[pid 28772] 1130322148.438139 select(4, [3], NULL, NULL, NULL) = 1 (in [3])
-.CE
+behaviour.
.TP
-.BR "\-e\ status" = successful
-Trace system calls that returned without an error code. The
-.B -z
-option has the effect of
-.BR status=successful .
+.B verbose
+Output both the raw value and the decoded string (as a comment).
+.RE
.TP
-.BR "\-e\ status" = failed
-Trace system calls that returned with an error code. The
-.B -Z
-option has the effect of
-.BR status=failed .
+.B \-y
+Print paths associated with file descriptor arguments.
.TP
-.BR "\-e\ status" = unfinished
-Trace system calls that did not return. This might happen, for example, due to
-an execve call in a neighbour thread.
+.B \-yy
+Print protocol specific information associated with socket file descriptors,
+and block/character device number associated with device file descriptors.
+.SS Statistics
+.TP 12
+.B \-c
+Count time, calls, and errors for each system call and report a summary on
+program exit, suppressing the regular output.
+This attempts to show system time (CPU time spent running
+in the kernel) independent of wall clock time. If
+.B \-c
+is used with
+.BR \-f ,
+only aggregate totals for all traced processes are kept.
.TP
-.BR "\-e\ status" = unavailable
-Trace system calls that returned but strace failed to fetch the error status.
+.B \-C
+Like
+.B \-c
+but also print regular output while processes are running.
.TP
-.BR "\-e\ status" = detached
-Trace system calls for which strace detached before the return.
+.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 Tampering
.TP
\fB\-e\ inject\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\fIsyscall\fR][:\fBdelay_enter\fR=\,\fIusecs\/\fR][:\fBdelay_exit\fR=\,\fIusecs\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
Perform syscall tampering for the specified set of syscalls.
.I errno
option set to
.BR ENOSYS .
-.TP
-.BR "\-e\ kvm" = vcpu
-Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
-or higher.
-
-.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.
-.TP
-.B \-z
-Print only syscalls that returned without an error code.
-.TP
-.B \-Z
-Print only syscalls that returned with an error code.
-.SS Tracing
-.TP 12
-.BI "\-b " syscall
-If specified syscall is reached, detach from traced process.
-Currently, only
-.BR execve (2)
-syscall is supported. This option is useful if you want to trace
-multi-threaded process and therefore require
-.BR \-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
-.I PID
-if it is multi-threaded, not only thread with
-.IR thread_id " = " PID .
-.TP
-.B \-ff
-If the
-.B \-o
-.I filename
-option is in effect, each processes trace is written to
-.IR filename . pid
-where
-.I pid
-is the numeric process id of each process.
-This is incompatible with
-.BR \-c ,
-since no per-process counts are kept.
-
-One might want to consider using
-.BR strace-log-merge (1)
-to obtain a combined strace log view.
-.TP
-.BI "\-I " interruptible
-When
-.B strace
-can be interrupted by signals (such as pressing
-.BR CTRL\-C ).
-.RS
-.TP 4
-.B 1
-no signals are blocked;
-.TQ
-.B 2
-fatal signals are blocked while decoding syscall (default);
-.TQ
-.B 3
-fatal signals are always blocked (default if
-.BR -o " " \fIFILE\fR " " \fIPROG\fR );
-.TQ
-.B 4
-fatal signals and
-.BR SIGTSTP " (" CTRL\-Z )
-are always blocked (useful to make
-.BI "strace -o " "FILE PROG"
-not stop on
-.BR CTRL\-Z ,
-default if
-.BR \-D ).
-.RE
-.SS Startup
-.TP 12
-\fB\-E\ \fIvar\fR=\,\fIval\fR
-Run command with
-.IR var = val
-in its list of environment variables.
-.TP
-.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
-.SM ID
-.I pid
-and begin tracing.
-The trace may be terminated
-at any time by a keyboard interrupt signal
-.RB ( CTRL\-C ).
-.B strace
-will respond by detaching itself from the traced process(es)
-leaving it (them) to continue running.
-Multiple
-.B \-p
-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
-supplementary groups of
-.IR username .
-This option is only useful when running as root and enables the
-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
.B \-d
projects / strace / commitdiff