]> granicus.if.org Git - strace/commitdiff
strace.1.in: reorder options
authorEugene Syromyatnikov <evgsyr@gmail.com>
Tue, 23 Jul 2019 18:37:24 +0000 (20:37 +0200)
committerDmitry V. Levin <ldv@altlinux.org>
Sun, 4 Aug 2019 22:33:09 +0000 (22:33 +0000)
In an attempt to make the order more sensible.

* strace.1.in (.SH OPTIONS): Insert ".SS General" at the beginning of
the section; move ".SS Startup" after ".SS General"; move ".SS Tracing"
after ".SS Startup"; move ".SS Filtering" after ".SS Startup"; insert
".SS Tampering" after ".SS Statistics"; move "-e expr" from ".SS
Filtering" to ".SS General"; move "-e abbrev", "-e verbose", "-e raw",
"-e read", "-e write", "-e kvm=vcpu" and "-v" from ".SS Filtering"
to ".SS Output format"; move "-e inject" and "-e fault" from
".SS Filtering" to ".SS Tampering".

strace.1.in

index 4100427e5b85a15cddc5f6c709e29a681514ce9b..1e82ce00418d09494f68b4e0ae5f7be567e4641c 100644 (file)
@@ -233,161 +233,7 @@ sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
 .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
@@ -441,7 +287,127 @@ have the obvious meanings.
 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
@@ -551,6 +517,81 @@ Currently, this list includes
 .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
@@ -575,17 +616,6 @@ See also
 .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
@@ -614,52 +644,167 @@ Note that this is independent from the normal tracing of the
 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.
@@ -801,149 +946,6 @@ This is equivalent to more generic
 .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