.\" 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 "14 October 1994" "Linux Utilities" "Linux Programmer's Manual"
+.TH KILL 1 "November 2019" "util-linux" "User Commands"
.SH NAME
kill \- terminate a process
.SH SYNOPSIS
-.BI "kill [ \-s " signal " | \-p ] [ \-a ] [ \-\- ] " "pid ..."
+.B kill
+.RB [ \- \fIsignal\fR| \-s
+.IR signal | \fB\-p\fP ]
+.RB [ \-q
+.IR value ]
+.RB [ \-a ]
+\fR[\fB\-\-timeout \fImilliseconds signal\fR]
+.RB [ \-\- ]
+.IR pid | name ...
.br
-.BI "kill -l [ " signal " ]"
+.B kill \-l
+.RI [ number ]
+.RB "| " \-L
.SH DESCRIPTION
The command
.B kill
-sends the specified signal to the specified process or process group.
-If no signal is specified, the TERM signal is sent. The TERM signal
-will kill processes which do not catch this signal. For other processes,
-it may be necessary to use the KILL (9) signal, since this signal cannot
-be caught.
+sends the specified \fIsignal\fR to the specified processes or process groups.
.PP
-Most modern shells have a builtin kill function, with a usage rather similar
-to that of the command described here. The `-a' and `-p' options,
-and the possibility to specify pids by command name is a local extension.
+If no signal is specified, the TERM signal is sent.
+The default action for this signal is to terminate the process.
+This signal should be used in preference to the
+KILL signal (number 9), since a process may install a handler for the
+TERM signal in order to perform clean-up steps before terminating in
+an orderly fashion.
+If a process does not terminate after a TERM signal has been sent,
+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
-If sig is 0, then no signal is sent, but error checking is still performed.
-.SH OPTIONS
+Most modern shells have a builtin kill command, with a usage rather similar to
+that of the command described here. The
+.BR \-\-all ,
+.BR \-\-pid ", and"
+.B \-\-queue
+options, and the possibility to specify processes by command name, are local extensions.
+.PP
+If \fIsignal\fR is 0, then no actual signal is sent, but error checking is still performed.
+
+.SH ARGUMENTS
+The list of processes to be signaled can be a mixture of names and PIDs.
.TP
-.IR pid ...
-Specify the list of processes that
-.B kill
-should signal. Each
.I pid
-can be one of five things:
-
+Each
+.I pid
+can be one of four things:
.RS
.TP
.I n
where
.I n
-is larger than 0. The process with pid
+is larger than 0. The process with PID
.I n
-will be signaled.
+is signaled.
.TP
.B 0
All processes in the current process group are signaled.
.TP
-.B -1
-All processes with pid larger than 1 will be signaled.
+.B \-1
+All processes with a PID larger than 1 are signaled.
.TP
-.BI - n
-where
-.I n
-is larger than 1.
-All processes in process group
+.BI \- n
+where
.I n
-are signaled. When an argument of the form `-n' is given,
-and it is meant to denote a process group,
-either the signal must be specified first, or the argument must be preceded
-by a `--' option, otherwise it will be taken as the signal to send.
-.TP
-.I commandname
-All processes invoked using that name will be signaled.
+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
+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
+signal to send.
.RE
.TP
-.BI \-s " signal"
-Specify the signal to send.
-The signal may be given as a signal name or number.
+.I name
+All processes invoked using this \fIname\fR will be signaled.
+
+.SH OPTIONS
+.TP
+\fB\-s\fR, \fB\-\-signal\fR \fIsignal\fR
+The signal to send. It may be given as a name or a number.
+.TP
+\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
+.TP
+\fB\-L\fR, \fB\-\-table\fR
+Similar to \fB\-l\fR, but it will print signal names and their corresponding
+numbers.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+Do not restrict the command-name-to-PID conversion to processes with the same
+UID as the present process.
.TP
-.B \-l
-Print a list of signal names. These are found in
-.I /usr/include/linux/signal.h
+\fB\-p\fR, \fB\-\-pid\fR
+Only print the process ID (PID) of the named processes, do not send any
+signals.
.TP
-.B \-a
-Do not restrict the commandname-to-pid conversion to processes
-with the same uid as the present process.
+\fB\-\-verbose\fR
+Print PID(s) that will be signaled with kill along with the signal.
.TP
-.B \-p
-Specify that
+\fB\-q\fR, \fB\-\-queue\fR \fIvalue\fR
+Use
+.BR sigqueue (3)
+rather than
+.BR kill (2).
+The
+.I value
+argument is an integer that is sent along with the signal. If the
+receiving process has installed a handler for this signal using the
+.B SA_SIGINFO
+flag to
+.BR sigaction (2),
+then it can obtain this data via the
+.I si_sigval
+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
-should only print the process id (pid)
-of the named processes, and not send any signals.
-.SH "SEE ALSO"
+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))
+of one of the threads in a multithreaded process as the argument of
+.BR kill ,
+the signal is nevertheless directed to the process
+(i.e., the entire thread group).
+In other words, it is not possible to send a signal to an
+explicitly selected thread in a multithreaded process.
+The signal will be delivered to an arbitrarily selected thread
+in the target process that is not blocking the signal.
+For more details, see
+.BR signal (7)
+and the description of
+.B CLONE_THREAD
+in
+.BR clone (2).
+.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
+.ME
+.br
+.MT kzak@redhat.com
+Karel Zak
+.ME
+.br
+.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 sigvec (2),
+.BR sigqueue (3),
.BR signal (7)
-.SH AUTHOR
-Taken from BSD 4.4. The ability to translate process names to process
-ids was added by Salvatore Valente <svalente@mit.edu>.
+
.SH AVAILABILITY
-The kill command is part of the util-linux-ng package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
+The kill command is part of the util-linux package and is available from
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .
projects / thirdparty / util-linux.git / blobdiff