Manual pages: kill.1: various language, spelling, and formatting fixes
PATCH 1/5 Manual pages: kill.1: various language, spelling, and formatting fixes
These seem all "obviously correct", so I'm rolling them up into one patch.
--- misc-utils/kill.1 | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-)
misc-utils/kill.1 +16 -9
@@ -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 [email protected]
Signature · 1 line
2.26.2
PATCH 2/5 Manual pages: kill.1: improve the description of the --timout option
The text describing this option is a little hard to understand. Improve it.
--- misc-utils/kill.1 | 48 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 15 deletions(-)
misc-utils/kill.1 +33 -15
@@ -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:
Signature · 1 line
2.26.2
PATCH 3/5 Manual pages: ipcmk.1, ipcrm.1, ipcs.1, lsipc.1: SEE ALSO: add sysvipc(7)
In reply to 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.
--- 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(-)
sys-utils/ipcmk.1 +2 -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/
sys-utils/ipcrm.1 +2 -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/
sys-utils/ipcs.1 +2 -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/
sys-utils/lsipc.1 +2 -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/
Signature · 1 line
2.26.2
PATCH 4/5 Man pages: ipcmk.1, ipcs.1, lsipc.1: explicitly mention "System V"
In reply to Michael Kerrisk (man-pages)Explicitly mention "System V" in the description, so that readers do not get confused with the POSIX IPC mechanisms.
--- sys-utils/ipcmk.1 | 3 ++- sys-utils/ipcs.1 | 2 +- sys-utils/lsipc.1 | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-)
sys-utils/ipcmk.1 +2 -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
sys-utils/ipcs.1 +1 -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
sys-utils/lsipc.1 +1 -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
Signature · 1 line
2.26.2
PATCH 5/5 Manual pages: rename EXAMPLE section to EXAMPLES
In reply to 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.
--- 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(-)
misc-utils/logger.1 +1 -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
misc-utils/look.1 +1 -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
misc-utils/rename.1 +1 -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
misc-utils/uuidgen.1 +1 -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
misc-utils/whereis.1 +1 -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
schedutils/ionice.1 +1 -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
sys-utils/flock.1 +1 -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
sys-utils/prlimit.1 +1 -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"
sys-utils/renice.1 +1 -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
sys-utils/setpriv.1 +1 -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
sys-utils/unshare.1 +2 -2
@@ -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
term-utils/scriptlive.1 +1 -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
term-utils/scriptreplay.1 +1 -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
text-utils/colcrt.1 +1 -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:
text-utils/column.1 +1 -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
text-utils/hexdump.1 +1 -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 "
Signature · 1 line
2.26.2
Karel Zak
maintainerQuoted 2 lines · Michael Kerrisk (man-pages)
misc-utils/kill.1 | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-)
All 5 patches applied.
Signature · 2 lines
Karel Zak <[email protected]> http://karelzak.blogspot.com