[PATCH 1/5] Manual pages: kill.1: various language, spelling, and formatting fixes

[PATCH 1/5] Manual pages: kill.1: various language, spelling, and formatting fixes

[Michael Kerrisk (man-pages)]

These seem all "obviously correct", so I'm rolling them up into
one patch.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 misc-utils/kill.1 | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/misc-utils/kill.1 b/misc-utils/kill.1
index 6fd50036d..1c12f8a14 100644
--- a/misc-utils/kill.1
+++ b/misc-utils/kill.1
@@ -34,7 +34,9 @@ then the KILL signal may be used; be aware that the latter signal
 cannot be caught, and so does not give the target process the opportunity
 to perform any clean-up before terminating.
 .PP
-Most modern shells have a builtin kill command, with a usage rather similar to
+Most modern shells have a builtin
+.B kill
+command, with a usage rather similar to
 that of the command described here.  The
 .BR \-\-all ,
 .BR \-\-pid ", and"
@@ -49,7 +51,7 @@ The list of processes to be signaled can be a mixture of names and PIDs.
 .I pid
 Each
 .I pid
-can be one of four things:
+can be expressed in one of the following ways:
 .RS
 .TP
 .I n
@@ -87,7 +89,7 @@ The signal to send.  It may be given as a name or a number.
 \fB\-l\fR, \fB\-\-list\fR [\fInumber\fR]
 Print a list of signal names, or convert the given signal number to a name.
 The signals can be found in
-.I /usr/\:include/\:linux/\:signal.h
+.IR /usr/\:include/\:linux/\:signal.h .
 .TP
 \fB\-L\fR, \fB\-\-table\fR
 Similar to \fB\-l\fR, but it will print signal names and their corresponding
@@ -102,10 +104,12 @@ Only print the process ID (PID) of the named processes, do not send any
 signals.
 .TP
 \fB\-\-verbose\fR
-Print PID(s) that will be signaled with kill along with the signal.
+Print PID(s) that will be signaled with
+.B kill
+along with the signal.
 .TP
 \fB\-q\fR, \fB\-\-queue\fR \fIvalue\fR
-Use
+Send the signal using
 .BR sigqueue (3)
 rather than
 .BR kill (2).
@@ -132,7 +136,7 @@ to wait for a period defined in
 before sending follow-up
 .I signal
 to process.
-This feature is implemented by PID file-descriptor and guaranties that
+This feature is implemented by PID file-descriptor and guarantees that
 follow-up signals are sent to the same process or not sent if the process no
 more exist.  Note that the operating system may re-use PIDs and implement the
 same feature in a shell by kill and sleep commands sequence may introduce a
@@ -182,11 +186,14 @@ and the description of
 in
 .BR clone (2).
 .P
-Various shells have provide an internal kill implementation that is
+Various shells provide a builtin
+.B kill
+command that is
 preferred in relation to the
 .BR kill (1)
-executable described by this manual.  Easiest way to ensure one is executing
-the executable is to use full path when calling the command, for example:
+executable described by this manual.
+The easiest way to ensure one is executing the command described in this page
+is to use the full path when calling the command, for example:
 .B "/bin/kill \-\-version"
 .SH AUTHORS
 .MT svalente@mit.edu
-- 
2.26.2

[PATCH 2/5] Manual pages: kill.1: improve the description of the --timout option

[Michael Kerrisk (man-pages)]

The text describing this option is a little hard to understand.
Improve it.

Cc: Sami Kerola <kerolasa@iki.fi>
Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 misc-utils/kill.1 | 48 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 15 deletions(-)

diff --git a/misc-utils/kill.1 b/misc-utils/kill.1
index 1c12f8a14..6ca318a6a 100644
--- a/misc-utils/kill.1
+++ b/misc-utils/kill.1
@@ -127,30 +127,48 @@ field of the
 structure.
 .TP
 \fB\-\-timeout\fR \fImilliseconds signal\fR
-Send a signal defined the usual way to a process.
+Send a signal defined in the usual way to a process,
+followed by an additional signal after a specified delay.
+The
 .B \-\-timeout
-will make
+option causes
 .B kill
 to wait for a period defined in
 .I milliseconds
-before sending follow-up
+before sending a follow-up
 .I signal
-to process.
-This feature is implemented by PID file-descriptor and guarantees that
-follow-up signals are sent to the same process or not sent if the process no
-more exist.  Note that the operating system may re-use PIDs and implement the
-same feature in a shell by kill and sleep commands sequence may introduce a
-race.  This option can be specified more than once than signals are sent
-sequentially in defined timeouts.  The
+to the process.
+This feature is implemented using the Linux kernel
+PID file descriptor feature in order to guarantee that the follow-up signal
+is sent to the same process or not sent if the process no longer exists.
+.IP
+Note that the operating system may re-use PIDs and implementing an
+equivalent feature in a shell using
+.B kill
+and
+.B sleep
+would be subject to races whereby the follow-up signal might be sent
+to a different process that used a recycled PID.
+.IP
+The
+.B \-\-timeout
+option can be specified multiple times: the signals are sent
+sequentially with the specified timeouts.  The
 .B \-\-timeout
-option can be combined with
+option can be combined with the
 .B \-\-queue
 option.
 .IP
-Example.  Send signals QUIT, TERM and KILL in sequence and wait for 1000
-milliseconds between the signals
-.br
-kill \-\-verbose \-\-timeout 1000 TERM \-\-timeout 1000 KILL \-\-signal QUIT 12345
+As an example, the following command sends
+the signals QUIT, TERM and KILL in sequence and waits for 1000
+milliseconds between sending the signals:
+.IP
+.in +4n
+.EE
+kill \-\-verbose \-\-timeout 1000 TERM \-\-timeout 1000 KILL \e
+        \-\-signal QUIT 12345
+.EE
+.in
 .SH EXIT STATUS
 .B kill
 has the following exit status values:
-- 
2.26.2

[PATCH 3/5] Manual pages: ipcmk.1, ipcrm.1, ipcs.1, lsipc.1: SEE ALSO: add sysvipc(7)

[Michael Kerrisk (man-pages)]

These commands all relate to System V IPC, so point the reader
at the relevant Section 7 page provided by the Linux man-pages
project.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 sys-utils/ipcmk.1 | 3 ++-
 sys-utils/ipcrm.1 | 3 ++-
 sys-utils/ipcs.1  | 3 ++-
 sys-utils/lsipc.1 | 3 ++-
 4 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/sys-utils/ipcmk.1 b/sys-utils/ipcmk.1
index 6102693ca..6de6d819d 100644
--- a/sys-utils/ipcmk.1
+++ b/sys-utils/ipcmk.1
@@ -46,7 +46,8 @@ Hayden A. James
 .ME
 .SH SEE ALSO
 .BR ipcrm (1),
-.BR ipcs (1)
+.BR ipcs (1),
+.BR sysvipc (7)
 .SH AVAILABILITY
 The ipcmk command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
diff --git a/sys-utils/ipcrm.1 b/sys-utils/ipcrm.1
index 6bb93f6bc..fc851352d 100644
--- a/sys-utils/ipcrm.1
+++ b/sys-utils/ipcrm.1
@@ -109,7 +109,8 @@ compatibility the previous syntax is still supported.
 .BR shmctl (2),
 .BR shmdt (2),
 .BR shmget (2),
-.BR ftok (3)
+.BR ftok (3),
+.BR sysvipc (7)
 .SH AVAILABILITY
 The ipcrm command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
diff --git a/sys-utils/ipcs.1 b/sys-utils/ipcs.1
index 8fd1a33ef..e0662302d 100644
--- a/sys-utils/ipcs.1
+++ b/sys-utils/ipcs.1
@@ -126,7 +126,8 @@ Krishna Balasubramanian
 .BR semop (2),
 .BR shmat (2),
 .BR shmdt (2),
-.BR shmget (2)
+.BR shmget (2),
+.BR sysvipc (7)
 .SH AVAILABILITY
 The ipcs command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
diff --git a/sys-utils/lsipc.1 b/sys-utils/lsipc.1
index 71cf0cf74..e5ae55bbd 100644
--- a/sys-utils/lsipc.1
+++ b/sys-utils/lsipc.1
@@ -131,7 +131,8 @@ Karel Zak
 .BR semop (2),
 .BR shmat (2),
 .BR shmdt (2),
-.BR shmget (2)
+.BR shmget (2),
+.BR sysvipc (7)
 .SH AVAILABILITY
 The lsipc command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
-- 
2.26.2

[PATCH 4/5] Man pages: ipcmk.1, ipcs.1, lsipc.1: explicitly mention "System V"

[Michael Kerrisk (man-pages)]

Explicitly mention "System V" in the description, so that readers do not
get confused with the POSIX IPC mechanisms.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 sys-utils/ipcmk.1 | 3 ++-
 sys-utils/ipcs.1  | 2 +-
 sys-utils/lsipc.1 | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/sys-utils/ipcmk.1 b/sys-utils/ipcmk.1
index 6de6d819d..c40222014 100644
--- a/sys-utils/ipcmk.1
+++ b/sys-utils/ipcmk.1
@@ -8,7 +8,8 @@ ipcmk \- make various IPC resources
 [options]
 .SH DESCRIPTION
 .B ipcmk
-allows you to create shared memory segments, message queues,
+allows you to create System V inter-process communication (IPC) objects:
+shared memory segments, message queues,
 and semaphore arrays.
 .SH OPTIONS
 .TP
diff --git a/sys-utils/ipcs.1 b/sys-utils/ipcs.1
index e0662302d..d259a7df6 100644
--- a/sys-utils/ipcs.1
+++ b/sys-utils/ipcs.1
@@ -8,7 +8,7 @@ ipcs \- show information on IPC facilities
 [options]
 .SH DESCRIPTION
 .B ipcs
-shows information on inter-process communication facilities.
+shows information on System V inter-process communication facilities.
 By default it shows information about all three resources:
 shared memory segments, message queues, and semaphore arrays.
 .SH OPTIONS
diff --git a/sys-utils/lsipc.1 b/sys-utils/lsipc.1
index e5ae55bbd..b58b4cdf4 100644
--- a/sys-utils/lsipc.1
+++ b/sys-utils/lsipc.1
@@ -8,7 +8,7 @@ lsipc \- show information on IPC facilities currently employed in the system
 [options]
 .SH DESCRIPTION
 .B lsipc
-shows information on the inter-process communication facilities
+shows information on the System V inter-process communication facilities
 for which the calling process has read access.
 .SH OPTIONS
 .TP
-- 
2.26.2

[PATCH 5/5] Manual pages: rename EXAMPLE section to EXAMPLES

[Michael Kerrisk (man-pages)]

Earlier, I patched various pages to consistently use EXAMPLE as a
section heading, rather than EXAMPLES.  (At that time, both headings
occurred in util-linux, with roughly equal frequency.)

Since then, I've observed that EXAMPLES is the more common usage
across a large corpus of manual pages. So, in Linux the man-pages
project, I switched to using EXAMPLES also. This patch makes the same
change for util-linux.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 misc-utils/logger.1       | 2 +-
 misc-utils/look.1         | 2 +-
 misc-utils/rename.1       | 2 +-
 misc-utils/uuidgen.1      | 2 +-
 misc-utils/whereis.1      | 2 +-
 schedutils/ionice.1       | 2 +-
 sys-utils/flock.1         | 2 +-
 sys-utils/prlimit.1       | 2 +-
 sys-utils/renice.1        | 2 +-
 sys-utils/setpriv.1       | 2 +-
 sys-utils/unshare.1       | 4 ++--
 term-utils/scriptlive.1   | 2 +-
 term-utils/scriptreplay.1 | 2 +-
 text-utils/colcrt.1       | 2 +-
 text-utils/column.1       | 2 +-
 text-utils/hexdump.1      | 2 +-
 16 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/misc-utils/logger.1 b/misc-utils/logger.1
index 6dd53705d..3cf6b0b1e 100644
--- a/misc-utils/logger.1
+++ b/misc-utils/logger.1
@@ -349,7 +349,7 @@ For the priority order and intended purposes of these facilities and levels, see
 The
 .B logger
 command is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
-.SH EXAMPLE
+.SH EXAMPLES
 .B logger System rebooted
 .br
 .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
diff --git a/misc-utils/look.1 b/misc-utils/look.1
index d33139e98..4367fa5eb 100644
--- a/misc-utils/look.1
+++ b/misc-utils/look.1
@@ -108,7 +108,7 @@ the alternative dictionary
 The
 .B look
 utility appeared in Version 7 AT&T Unix.
-.SH EXAMPLE
+.SH EXAMPLES
 .RS
 .nf
 sort \-d /etc/passwd \-o /tmp/look.dict
diff --git a/misc-utils/rename.1 b/misc-utils/rename.1
index 64c70f7e4..701bc4f18 100644
--- a/misc-utils/rename.1
+++ b/misc-utils/rename.1
@@ -84,7 +84,7 @@ nothing was renamed
 unanticipated error occurred
 .PD
 .RE
-.SH EXAMPLE
+.SH EXAMPLES
 Given the files
 .IR foo1 ", ..., " foo9 ", " foo10 ", ..., " foo278 ,
 the commands
diff --git a/misc-utils/uuidgen.1 b/misc-utils/uuidgen.1
index 07d646104..0189587a3 100644
--- a/misc-utils/uuidgen.1
+++ b/misc-utils/uuidgen.1
@@ -89,7 +89,7 @@ Generate the hash of the \fIname\fR.
 Interpret name \fIname\fR as a hexadecimal string.
 .SH CONFORMING TO
 OSF DCE 1.1
-.SH EXAMPLE
+.SH EXAMPLES
 uuidgen \-\-sha1 \-\-namespace @dns \-\-name "www.example.com"
 .SH AUTHORS
 .B uuidgen
diff --git a/misc-utils/whereis.1 b/misc-utils/whereis.1
index 8da51d8e9..1b8c3be7c 100644
--- a/misc-utils/whereis.1
+++ b/misc-utils/whereis.1
@@ -153,7 +153,7 @@ are displayed with
 .SH ENVIRONMENT
 .IP WHEREIS_DEBUG=all
 enables debug output.
-.SH EXAMPLE
+.SH EXAMPLES
 To find all files in
 .I /usr/\:bin
 which are not documented
diff --git a/schedutils/ionice.1 b/schedutils/ionice.1
index 415def55a..72dbae6af 100644
--- a/schedutils/ionice.1
+++ b/schedutils/ionice.1
@@ -116,7 +116,7 @@ Display version information and exit.
 .SH NOTES
 Linux supports I/O scheduling priorities and classes since 2.6.13 with the CFQ
 I/O scheduler.
-.SH EXAMPLE
+.SH EXAMPLES
 .LP
 .TP 7
 # \fBionice\fP \-c 3 \-p 89
diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index bea70c6be..def273dbd 100644
--- a/sys-utils/flock.1
+++ b/sys-utils/flock.1
@@ -137,7 +137,7 @@ option, or 1 by default.
 .PP
 When using the \fIcommand\fR variant, and executing the child worked, then
 the exit status is that of the child command.
-.SH EXAMPLE
+.SH EXAMPLES
 Note that "shell> " in examples is a command line prompt.
 .TP
 shell1> flock /tmp \-c cat
diff --git a/sys-utils/prlimit.1 b/sys-utils/prlimit.1
index 89933d90a..0bf2db008 100644
--- a/sys-utils/prlimit.1
+++ b/sys-utils/prlimit.1
@@ -93,7 +93,7 @@ Timeout for real-time tasks.
 The prlimit system call is supported since Linux 2.6.36, older kernels will
 break this program.
 
-.SH EXAMPLE
+.SH EXAMPLES
 .IP "\fBprlimit \-\-pid 13134\fP"
 Display limit values for all current resources.
 .IP "\fBprlimit \-\-pid 13134 \-\-rss \-\-nofile=1024:4095\fP"
diff --git a/sys-utils/renice.1 b/sys-utils/renice.1
index 99cc61f21..cb9863143 100644
--- a/sys-utils/renice.1
+++ b/sys-utils/renice.1
@@ -101,7 +101,7 @@ negative (to make things go very fast).
 The
 .B renice
 command appeared in 4.0BSD.
-.SH EXAMPLE
+.SH EXAMPLES
 The following command would change the priority of the processes with
 PIDs 987 and 32, plus all processes owned by the users daemon and root:
 .TP
diff --git a/sys-utils/setpriv.1 b/sys-utils/setpriv.1
index 222fa6388..d1bd5efda 100644
--- a/sys-utils/setpriv.1
+++ b/sys-utils/setpriv.1
@@ -190,7 +190,7 @@ Be careful with this tool \-\- it may have unexpected security consequences.
 For example, setting no_new_privs and then execing a program that is
 SELinux\-confined (as this tool would do) may prevent the SELinux
 restrictions from taking effect.
-.SH EXAMPLE
+.SH EXAMPLES
 If you're looking for behaviour similar to
 .BR su (1)/ runuser "(1), or " sudo (8)
 (without the
diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 679f93715..ea170b13a 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -28,7 +28,7 @@ Once a persistent \%namespace is no longer needed,
 it can be unpersisted by using
 .BR umount (8)
 to remove the bind mount.
-See the \fBEXAMPLE\fR section for more details.
+See the \fBEXAMPLES\fR section for more details.
 .PP
 .B unshare
 since util-linux version 2.36 uses /\fIproc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP
@@ -243,7 +243,7 @@ The proc and sysfs filesystems mounting as root in a user namespace have to be
 restricted so that a less privileged user can not get more access to sensitive
 files that a more privileged user made unavailable. In short the rule for proc
 and sysfs is as close to a bind mount as possible.
-.SH EXAMPLE
+.SH EXAMPLES
 .PP
 The following command creates a PID namespace, using
 .B \-\-fork
diff --git a/term-utils/scriptlive.1 b/term-utils/scriptlive.1
index 6639c73d1..78694dcbb 100644
--- a/term-utils/scriptlive.1
+++ b/term-utils/scriptlive.1
@@ -65,7 +65,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLE
+.SH EXAMPLES
 .nf
 % script --log-timing file.tm --log-in script.in
 Script started, file is script.out
diff --git a/term-utils/scriptreplay.1 b/term-utils/scriptreplay.1
index 4505ef836..a93b8a790 100644
--- a/term-utils/scriptreplay.1
+++ b/term-utils/scriptreplay.1
@@ -110,7 +110,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLE
+.SH EXAMPLES
 .nf
 % script --log-timing file.tm --log-out script.out
 Script started, file is script.out
diff --git a/text-utils/colcrt.1 b/text-utils/colcrt.1
index 90ded9577..46c612bb7 100644
--- a/text-utils/colcrt.1
+++ b/text-utils/colcrt.1
@@ -84,7 +84,7 @@ Lines are trimmed to 132 characters.
 .PP
 Some provision should be made for processing superscripts and subscripts in
 documents which are already double-spaced.
-.SH EXAMPLE
+.SH EXAMPLES
 A typical use of
 .B colcrt
 would be:
diff --git a/text-utils/column.1 b/text-utils/column.1
index e43d6fee4..5e4e29e68 100644
--- a/text-utils/column.1
+++ b/text-utils/column.1
@@ -157,7 +157,7 @@ has since been corrected (see above). Other implementations of
 .B column
 may continue to use the older documentation, but the behavior should be
 identical in any case.
-.SH EXAMPLE
+.SH EXAMPLES
 Print fstab with header line and align number to the right:
 .EX
 \fBsed 's/#.*//' /etc/fstab | column \-\-table \-\-table-columns SOURCE,TARGET,TYPE,OPTIONS,PASS,FREQ \-\-table-right PASS,FREQ\fR
diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
index f5728f939..abf1b8370 100644
--- a/text-utils/hexdump.1
+++ b/text-utils/hexdump.1
@@ -347,7 +347,7 @@ exits 0 on success and >0 if an error occurred.
 The
 .B hexdump
 utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
-.SH EXAMPLE
+.SH EXAMPLES
 Display the input in perusal format:
 .nf
    "%06.6_ao "  12/1 "%3_u "
-- 
2.26.2

Re: [PATCH 1/5] Manual pages: kill.1: various language, spelling, and formatting fixes

[Karel Zak]

On Mon, May 25, 2020 at 02:59:08PM +0200, Michael Kerrisk (man-pages) wrote:
>  misc-utils/kill.1 | 25 ++++++++++++++++---------
>  1 file changed, 16 insertions(+), 9 deletions(-)

All 5 patches applied.

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com