404 lines
13 KiB
Diff
404 lines
13 KiB
Diff
From ffc3e46d6ea23ba71eb49c8bc36eb3068968b691 Mon Sep 17 00:00:00 2001
|
|
From: Eugene Syromyatnikov <evgsyr@gmail.com>
|
|
Date: Tue, 4 Sep 2018 16:45:04 +0200
|
|
Subject: [PATCH 11/27] strace.1.in: print names of entities in bold, provide
|
|
man page sections
|
|
|
|
* strace.1.in (.SH DESCRIPTION, .SH OPTIONS): Add man page section
|
|
numbers. Make mentions of strace and other entities bold.
|
|
|
|
Additional changes:
|
|
Update auto-generated strace.1
|
|
|
|
---
|
|
strace.1.in | 89 ++++++++++++++++++++++++++++++++++++++++++-------------------
|
|
1 file changed, 61 insertions(+), 28 deletions(-)
|
|
|
|
Index: strace-4.24/strace.1.in
|
|
===================================================================
|
|
--- strace-4.24.orig/strace.1.in 2018-07-07 12:29:02.000000000 +0200
|
|
+++ strace-4.24/strace.1.in 2019-03-10 05:12:00.665873244 +0100
|
|
@@ -177,7 +177,7 @@
|
|
open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
|
|
.CE
|
|
Here, the third argument of
|
|
-.B open
|
|
+.BR open (2)
|
|
is decoded by breaking down the
|
|
flag argument into its three bitwise-OR constituents and printing the
|
|
mode value in octal by tradition. Where the traditional or native
|
|
@@ -198,7 +198,7 @@
|
|
.B st_mode
|
|
member is carefully decoded into a bitwise-OR of symbolic and numeric values.
|
|
Also notice in this example that the first argument to
|
|
-.B lstat
|
|
+.BR lstat (2)
|
|
is an input to the system call and the second argument is an output.
|
|
Since output arguments are not modified if the system call fails, arguments may
|
|
not always be dereferenced. For example, retrying the "ls \-l" example
|
|
@@ -224,15 +224,16 @@
|
|
(32 by default) bytes of strings are printed;
|
|
longer strings have an ellipsis appended following the closing quote.
|
|
Here is a line from "ls \-l" where the
|
|
-.B getpwuid
|
|
+.BR getpwuid (3)
|
|
library routine is reading the password file:
|
|
.CW
|
|
read(3, "root::0:0:System Administrator:/"..., 1024) = 422
|
|
.CE
|
|
While structures are annotated using curly braces, simple pointers
|
|
and arrays are printed using square brackets with commas separating
|
|
-elements. Here is an example from the command "id" on a system with
|
|
-supplementary group ids:
|
|
+elements. Here is an example from the command
|
|
+.BR id (1)
|
|
+on a system with supplementary group ids:
|
|
.CW
|
|
getgroups(32, [100, 0]) = 2
|
|
.CE
|
|
@@ -489,7 +490,7 @@
|
|
which is useful to seeing what files the process is referencing.
|
|
Furthermore, using the abbreviation will ensure that you don't
|
|
accidentally forget to include a call like
|
|
-.B lstat
|
|
+.BR lstat (2)
|
|
in the list. Betchya woulda forgot that one.
|
|
.TP
|
|
.BR "\-e\ trace" = %process
|
|
@@ -769,8 +770,7 @@
|
|
\fB\-e\ inject\fR= expression with default value of
|
|
.I errno
|
|
option set to
|
|
-.IR ENOSYS .
|
|
-
|
|
+.BR ENOSYS .
|
|
.TP
|
|
.BR "\-e\ kvm" = vcpu
|
|
Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
|
|
@@ -794,10 +794,11 @@
|
|
.BI "\-b " syscall
|
|
If specified syscall is reached, detach from traced process.
|
|
Currently, only
|
|
-.I execve
|
|
+.BR execve (2)
|
|
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.
|
|
+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
|
|
@@ -816,16 +817,20 @@
|
|
.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.
|
|
+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
|
|
-.I filename.pid
|
|
-where pid is the numeric process id of each process.
|
|
+.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.
|
|
@@ -835,11 +840,30 @@
|
|
to obtain a combined strace log view.
|
|
.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).
|
|
+When
|
|
+.B strace
|
|
+can be interrupted by signals (such as pressing
|
|
+.BR ^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 " (" ^Z )
|
|
+are always blocked (useful to make
|
|
+.BI "strace -o " "FILE PROG"
|
|
+not stop on
|
|
+.BR ^Z ).
|
|
+.RE
|
|
.SS Startup
|
|
.TP 12
|
|
\fB\-E\ \fIvar\fR=\,\fIval\fR
|
|
@@ -920,7 +944,8 @@
|
|
.B strace
|
|
can be used as a wrapper process transparent to the invoking parent process.
|
|
Note that parent-child relationship (signal stop notifications,
|
|
-getppid() value, etc) between traced process and its parent are not preserved
|
|
+.BR getppid (2)
|
|
+value, etc) between traced process and its parent are not preserved
|
|
unless
|
|
.B \-D
|
|
is used.
|
|
@@ -987,8 +1012,11 @@
|
|
definitions during the build time.
|
|
Please refer to the output of the
|
|
.B strace \-V
|
|
-command in order to figure out what support is available in your strace build
|
|
-("non-native" refers to an ABI that differs from the ABI strace has):
|
|
+command in order to figure out what support is available in your
|
|
+.B strace
|
|
+build ("non-native" refers to an ABI that differs from the ABI
|
|
+.B strace
|
|
+has):
|
|
.TP 15
|
|
.B m32-mpers
|
|
.B strace
|
|
@@ -1057,17 +1085,22 @@
|
|
.LP
|
|
On x32, syscalls that are intended to be used by 64-bit processes and not x32
|
|
ones (for example,
|
|
-.BR readv ,
|
|
+.BR readv (2),
|
|
that has syscall number 19 on x86_64, with its x32 counterpart has syscall
|
|
number 515), but called with
|
|
.B __X32_SYSCALL_BIT
|
|
-flag being set, are designated with "#64" suffix.
|
|
+flag being set, are designated with
|
|
+.B "#64"
|
|
+suffix.
|
|
.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
|
|
-should be restarted on strace attach, making the attach invisible
|
|
+option may observe a spurious
|
|
+.B EINTR
|
|
+return from the current system call that is not restartable.
|
|
+(Ideally, all system calls should be restarted on
|
|
+.B 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.)
|
|
This may have an unpredictable effect on the process
|
|
Index: strace-4.24/strace.1
|
|
===================================================================
|
|
--- strace-4.24.orig/strace.1 2018-08-14 02:44:59.000000000 +0200
|
|
+++ strace-4.24/strace.1 2019-03-10 05:15:15.101926224 +0100
|
|
@@ -53,7 +53,7 @@
|
|
. el \
|
|
. BR "\\$1"
|
|
..
|
|
-.TH STRACE 1 "2018-07-07" "strace 4.24"
|
|
+.TH STRACE 1 "2019-03-08" "strace 4.24"
|
|
.SH NAME
|
|
strace \- trace system calls and signals
|
|
.SH SYNOPSIS
|
|
@@ -177,7 +177,7 @@
|
|
open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
|
|
.CE
|
|
Here, the third argument of
|
|
-.B open
|
|
+.BR open (2)
|
|
is decoded by breaking down the
|
|
flag argument into its three bitwise-OR constituents and printing the
|
|
mode value in octal by tradition. Where the traditional or native
|
|
@@ -198,7 +198,7 @@
|
|
.B st_mode
|
|
member is carefully decoded into a bitwise-OR of symbolic and numeric values.
|
|
Also notice in this example that the first argument to
|
|
-.B lstat
|
|
+.BR lstat (2)
|
|
is an input to the system call and the second argument is an output.
|
|
Since output arguments are not modified if the system call fails, arguments may
|
|
not always be dereferenced. For example, retrying the "ls \-l" example
|
|
@@ -224,15 +224,16 @@
|
|
(32 by default) bytes of strings are printed;
|
|
longer strings have an ellipsis appended following the closing quote.
|
|
Here is a line from "ls \-l" where the
|
|
-.B getpwuid
|
|
+.BR getpwuid (3)
|
|
library routine is reading the password file:
|
|
.CW
|
|
read(3, "root::0:0:System Administrator:/"..., 1024) = 422
|
|
.CE
|
|
While structures are annotated using curly braces, simple pointers
|
|
and arrays are printed using square brackets with commas separating
|
|
-elements. Here is an example from the command "id" on a system with
|
|
-supplementary group ids:
|
|
+elements. Here is an example from the command
|
|
+.BR id (1)
|
|
+on a system with supplementary group ids:
|
|
.CW
|
|
getgroups(32, [100, 0]) = 2
|
|
.CE
|
|
@@ -489,7 +490,7 @@
|
|
which is useful to seeing what files the process is referencing.
|
|
Furthermore, using the abbreviation will ensure that you don't
|
|
accidentally forget to include a call like
|
|
-.B lstat
|
|
+.BR lstat (2)
|
|
in the list. Betchya woulda forgot that one.
|
|
.TP
|
|
.BR "\-e\ trace" = %process
|
|
@@ -769,8 +770,7 @@
|
|
\fB\-e\ inject\fR= expression with default value of
|
|
.I errno
|
|
option set to
|
|
-.IR ENOSYS .
|
|
-
|
|
+.BR ENOSYS .
|
|
.TP
|
|
.BR "\-e\ kvm" = vcpu
|
|
Print the exit reason of kvm vcpu. Requires Linux kernel version 4.16.0
|
|
@@ -794,10 +794,11 @@
|
|
.BI "\-b " syscall
|
|
If specified syscall is reached, detach from traced process.
|
|
Currently, only
|
|
-.I execve
|
|
+.BR execve (2)
|
|
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.
|
|
+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
|
|
@@ -816,16 +817,20 @@
|
|
.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.
|
|
+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
|
|
-.I filename.pid
|
|
-where pid is the numeric process id of each process.
|
|
+.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.
|
|
@@ -835,11 +840,30 @@
|
|
to obtain a combined strace log view.
|
|
.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).
|
|
+When
|
|
+.B strace
|
|
+can be interrupted by signals (such as pressing
|
|
+.BR ^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 " (" ^Z )
|
|
+are always blocked (useful to make
|
|
+.BI "strace -o " "FILE PROG"
|
|
+not stop on
|
|
+.BR ^Z ).
|
|
+.RE
|
|
.SS Startup
|
|
.TP 12
|
|
\fB\-E\ \fIvar\fR=\,\fIval\fR
|
|
@@ -920,7 +944,8 @@
|
|
.B strace
|
|
can be used as a wrapper process transparent to the invoking parent process.
|
|
Note that parent-child relationship (signal stop notifications,
|
|
-getppid() value, etc) between traced process and its parent are not preserved
|
|
+.BR getppid (2)
|
|
+value, etc) between traced process and its parent are not preserved
|
|
unless
|
|
.B \-D
|
|
is used.
|
|
@@ -987,8 +1012,11 @@
|
|
definitions during the build time.
|
|
Please refer to the output of the
|
|
.B strace \-V
|
|
-command in order to figure out what support is available in your strace build
|
|
-("non-native" refers to an ABI that differs from the ABI strace has):
|
|
+command in order to figure out what support is available in your
|
|
+.B strace
|
|
+build ("non-native" refers to an ABI that differs from the ABI
|
|
+.B strace
|
|
+has):
|
|
.TP 15
|
|
.B m32-mpers
|
|
.B strace
|
|
@@ -1057,17 +1085,22 @@
|
|
.LP
|
|
On x32, syscalls that are intended to be used by 64-bit processes and not x32
|
|
ones (for example,
|
|
-.BR readv ,
|
|
+.BR readv (2),
|
|
that has syscall number 19 on x86_64, with its x32 counterpart has syscall
|
|
number 515), but called with
|
|
.B __X32_SYSCALL_BIT
|
|
-flag being set, are designated with "#64" suffix.
|
|
+flag being set, are designated with
|
|
+.B "#64"
|
|
+suffix.
|
|
.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
|
|
-should be restarted on strace attach, making the attach invisible
|
|
+option may observe a spurious
|
|
+.B EINTR
|
|
+return from the current system call that is not restartable.
|
|
+(Ideally, all system calls should be restarted on
|
|
+.B 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.)
|
|
This may have an unpredictable effect on the process
|