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