Manual pages: order NOTES / HISTORY / BUGS / EXAMPLE consistently

[thirdparty/util-linux.git] / misc-utils / kill.1

diff --git a/misc-utils/kill.1 b/misc-utils/kill.1
index 24c32a24921fd4e99c9330b379f1402a861ed1a3..6fd50036d9a513fb84c7136f93acbb9838ef6c54 100644 (file)
--- a/misc-utils/kill.1
+++ b/misc-utils/kill.1
@@ -1,16 +1,17 @@
 .\" Copyright 1994 Salvatore Valente (svalente@mit.edu)
 .\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)
 .\" May be distributed under the GNU General Public License
-.TH KILL 1 "July 2014" "util-linux" "User Commands"
+.TH KILL 1 "November 2019" "util-linux" "User Commands"
 .SH NAME
 kill \- terminate a process
 .SH SYNOPSIS
 .B kill
 .RB [ \- \fIsignal\fR| \-s
-.IR signal | \fB-p\fP ]
+.IR signal | \fB\-p\fP ]
 .RB [ \-q
 .IR value ]
 .RB [ \-a ]
+\fR[\fB\-\-timeout \fImilliseconds signal\fR]
 .RB [ \-\- ]
 .IR pid | name ...
 .br
@@ -61,17 +62,17 @@ is signaled.
 .B 0
 All processes in the current process group are signaled.
 .TP
-.B -1
+.B \-1
 All processes with a PID larger than 1 are signaled.
 .TP
-.BI - n
+.BI \- n
 where
 .I n
 is larger than 1.  All processes in process group
 .I n
-are signaled.  When an argument of the form '-n' is given, and it is meant to
+are signaled.  When an argument of the form '\-n' is given, and it is meant to
 denote a process group, either a signal must be specified first, or the
-argument must be preceded by a '--' option, otherwise it will be taken as the
+argument must be preceded by a '\-\-' option, otherwise it will be taken as the
 signal to send.
 .RE
 .TP
@@ -120,7 +121,49 @@ then it can obtain this data via the
 field of the
 .I siginfo_t
 structure.
-
+.TP
+\fB\-\-timeout\fR \fImilliseconds signal\fR
+Send a signal defined the usual way to a process.
+.B \-\-timeout
+will make
+.B kill
+to wait for a period defined in
+.I milliseconds
+before sending follow-up
+.I signal
+to process.
+This feature is implemented by PID file-descriptor and guaranties 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
+.B \-\-timeout
+option can be combined with
+.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
+.SH EXIT STATUS
+.B kill
+has the following exit status values:
+.PP
+.RS
+.PD 0
+.TP
+.B 0
+success
+.TP
+.B 1
+failure
+.TP
+.B 64
+partial success (when more than one process specified)
+.PD
+.RE
 .SH NOTES
 Although it is possible to specify the TID (thread ID, see
 .BR gettid (2))
@@ -138,28 +181,13 @@ and the description of
 .B CLONE_THREAD
 in
 .BR clone (2).
-
-.SH RETURN CODES
-.B kill
-has the following return codes:
-.TP
-.B 0
-success
-.TP
-.B 1
-failure
-.TP
-.B 64
-partial success (when more than one process specified)
-
-.SH SEE ALSO
-.BR bash (1),
-.BR tcsh (1),
-.BR sigaction (2),
-.BR kill (2),
-.BR sigqueue (3),
-.BR signal (7)
-
+.P
+Various shells have provide an internal kill implementation 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:
+.B "/bin/kill \-\-version"
 .SH AUTHORS
 .MT svalente@mit.edu
 Salvatore Valente
@@ -172,6 +200,14 @@ Karel Zak
 .PP
 The original version was taken from BSD 4.4.
 
+.SH SEE ALSO
+.BR bash (1),
+.BR tcsh (1),
+.BR sigaction (2),
+.BR kill (2),
+.BR sigqueue (3),
+.BR signal (7)
+
 .SH AVAILABILITY
 The kill command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/