mirror of https://github.com/mkerrisk/man-pages
394 lines
12 KiB
Groff
394 lines
12 KiB
Groff
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "KILL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" kill
|
||
|
.SH NAME
|
||
|
kill \- terminate or signal processes
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fBkill -s\fP \fIsignal_name pid\fP \fB...
|
||
|
.br
|
||
|
.sp
|
||
|
kill -l\fP \fB[\fP\fIexit_status\fP\fB]\fP\fB
|
||
|
.br
|
||
|
.sp
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBkill\fP \fB[\fP\fB-\fP\fIsignal_name\fP\fB]\fP \fIpid\fP \fB...
|
||
|
.br
|
||
|
.sp
|
||
|
kill\fP \fB[\fP\fB-\fP\fIsignal_number\fP\fB]\fP \fIpid\fP \fB...
|
||
|
\fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIkill\fP utility shall send a signal to the process or processes
|
||
|
specified by each \fIpid\fP operand.
|
||
|
.LP
|
||
|
For each \fIpid\fP operand, the \fIkill\fP utility shall perform actions
|
||
|
equivalent to the \fIkill\fP() function defined in the System Interfaces
|
||
|
volume of IEEE\ Std\ 1003.1-2001
|
||
|
called with the following arguments:
|
||
|
.IP " *" 3
|
||
|
The value of the \fIpid\fP operand shall be used as the \fIpid\fP
|
||
|
argument.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
The \fIsig\fP argument is the value specified by the \fB-s\fP option,
|
||
|
\fB-\fP \fIsignal_number\fP option, or the \fB-\fP
|
||
|
\fIsignal_name\fP option, or by SIGTERM, if none of these options
|
||
|
is specified.
|
||
|
.LP
|
||
|
.SH OPTIONS
|
||
|
.LP
|
||
|
The \fIkill\fP utility shall conform to the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines,
|
||
|
\ except that
|
||
|
in the last two SYNOPSIS forms, the \fB-\fP \fIsignal_number\fP and
|
||
|
\fB-\fP \fIsignal_name\fP options are usually more than a
|
||
|
single character.
|
||
|
.LP
|
||
|
The following options shall be supported:
|
||
|
.TP 7
|
||
|
\fB-l\fP
|
||
|
(The letter ell.) Write all values of \fIsignal_name\fP supported
|
||
|
by the implementation, if no operand is given. If an
|
||
|
\fIexit_status\fP operand is given and it is a value of the \fB'?'\fP
|
||
|
shell special parameter (see \fISpecial Parameters\fP and \fIwait\fP()
|
||
|
) corresponding to a process
|
||
|
that was terminated by a signal, the \fIsignal_name\fP corresponding
|
||
|
to the signal that terminated the process shall be written.
|
||
|
If an \fIexit_status\fP operand is given and it is the unsigned decimal
|
||
|
integer value of a signal number, the \fIsignal_name\fP
|
||
|
(the symbolic constant name without the \fBSIG\fP prefix defined in
|
||
|
the Base Definitions volume of IEEE\ Std\ 1003.1-2001)
|
||
|
corresponding to that signal shall be written. Otherwise, the results
|
||
|
are unspecified.
|
||
|
.TP 7
|
||
|
\fB-s\ \fP \fIsignal_name\fP
|
||
|
.sp
|
||
|
Specify the signal to send, using one of the symbolic names defined
|
||
|
in the \fI<signal.h>\fP header. Values of \fIsignal_name\fP shall
|
||
|
be recognized in a
|
||
|
case-independent fashion, without the \fBSIG\fP prefix. In addition,
|
||
|
the symbolic name 0 shall be recognized, representing the
|
||
|
signal value zero. The corresponding signal shall be sent instead
|
||
|
of SIGTERM.
|
||
|
.TP 7
|
||
|
\fB-\fP\fIsignal_name\fP
|
||
|
.sp
|
||
|
Equivalent to \fB-s\fP \fIsignal_name\fP.
|
||
|
.TP 7
|
||
|
\fB-\fP\fIsignal_number\fP
|
||
|
.sp
|
||
|
Specify a non-negative decimal integer, \fIsignal_number\fP, representing
|
||
|
the signal to be used instead of SIGTERM, as the
|
||
|
\fIsig\fP argument in the effective call to \fIkill\fP(). The correspondence
|
||
|
between integer
|
||
|
values and the \fIsig\fP value used is shown in the following table.
|
||
|
.LP
|
||
|
The effects of specifying any \fIsignal_number\fP other than those
|
||
|
listed in the table are undefined.
|
||
|
.sp
|
||
|
.sp
|
||
|
.TS C
|
||
|
center; l l.
|
||
|
\fIsignal_number\fP \fB\fIsig\fP Value\fP
|
||
|
0 0
|
||
|
1 SIGHUP
|
||
|
2 SIGINT
|
||
|
3 SIGQUIT
|
||
|
6 SIGABRT
|
||
|
9 SIGKILL
|
||
|
14 SIGALRM
|
||
|
15 SIGTERM
|
||
|
.TE
|
||
|
.LP
|
||
|
If the first argument is a negative integer, it shall be interpreted
|
||
|
as a \fB-\fP \fIsignal_number\fP option, not as a
|
||
|
negative \fIpid\fP operand specifying a process group.
|
||
|
.SH OPERANDS
|
||
|
.LP
|
||
|
The following operands shall be supported:
|
||
|
.TP 7
|
||
|
\fIpid\fP
|
||
|
One of the following:
|
||
|
.RS
|
||
|
.IP " 1." 4
|
||
|
A decimal integer specifying a process or process group to be signaled.
|
||
|
The process or processes selected by positive, negative,
|
||
|
and zero values of the \fIpid\fP operand shall be as described for
|
||
|
the \fIkill\fP()
|
||
|
function. If process number 0 is specified, all processes in the current
|
||
|
process group shall be signaled. For the effects of
|
||
|
negative \fIpid\fP numbers, see the \fIkill\fP() function defined
|
||
|
in the System Interfaces
|
||
|
volume of IEEE\ Std\ 1003.1-2001. If the first \fIpid\fP operand is
|
||
|
negative, it should be preceded by \fB"--"\fP to
|
||
|
keep it from being interpreted as an option.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
A job control job ID (see the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
Section 3.203, Job Control Job ID) that identifies a background process
|
||
|
group to be
|
||
|
signaled. The job control job ID notation is applicable only for invocations
|
||
|
of \fIkill\fP in the current shell execution
|
||
|
environment; see \fIShell Execution Environment\fP .
|
||
|
.LP
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fIexit_status\fP
|
||
|
A decimal integer specifying a signal number or the exit status of
|
||
|
a process terminated by a signal.
|
||
|
.sp
|
||
|
.SH STDIN
|
||
|
.LP
|
||
|
Not used.
|
||
|
.SH INPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH ENVIRONMENT VARIABLES
|
||
|
.LP
|
||
|
The following environment variables shall affect the execution of
|
||
|
\fIkill\fP:
|
||
|
.TP 7
|
||
|
\fILANG\fP
|
||
|
Provide a default value for the internationalization variables that
|
||
|
are unset or null. (See the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
||
|
for
|
||
|
the precedence of internationalization variables used to determine
|
||
|
the values of locale categories.)
|
||
|
.TP 7
|
||
|
\fILC_ALL\fP
|
||
|
If set to a non-empty string value, override the values of all the
|
||
|
other internationalization variables.
|
||
|
.TP 7
|
||
|
\fILC_CTYPE\fP
|
||
|
Determine the locale for the interpretation of sequences of bytes
|
||
|
of text data as characters (for example, single-byte as
|
||
|
opposed to multi-byte characters in arguments).
|
||
|
.TP 7
|
||
|
\fILC_MESSAGES\fP
|
||
|
Determine the locale that should be used to affect the format and
|
||
|
contents of diagnostic messages written to standard
|
||
|
error.
|
||
|
.TP 7
|
||
|
\fINLSPATH\fP
|
||
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
||
|
\&.\fP
|
||
|
.sp
|
||
|
.SH ASYNCHRONOUS EVENTS
|
||
|
.LP
|
||
|
Default.
|
||
|
.SH STDOUT
|
||
|
.LP
|
||
|
When the \fB-l\fP option is not specified, the standard output shall
|
||
|
not be used.
|
||
|
.LP
|
||
|
When the \fB-l\fP option is specified, the symbolic name of each signal
|
||
|
shall be written in the following format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s%c", <\fP\fIsignal_name\fP\fB>, <\fP\fIseparator\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where the <\fIsignal_name\fP> is in uppercase, without the \fBSIG\fP
|
||
|
prefix, and the <\fIseparator\fP> shall be
|
||
|
either a <newline> or a <space>. For the last signal written, <\fIseparator\fP>
|
||
|
shall be a <newline>.
|
||
|
.LP
|
||
|
When both the \fB-l\fP option and \fIexit_status\fP operand are specified,
|
||
|
the symbolic name of the corresponding signal shall
|
||
|
be written in the following format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s\\n", <\fP\fIsignal_name\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.SH STDERR
|
||
|
.LP
|
||
|
The standard error shall be used only for diagnostic messages.
|
||
|
.SH OUTPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXTENDED DESCRIPTION
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXIT STATUS
|
||
|
.LP
|
||
|
The following exit values shall be returned:
|
||
|
.TP 7
|
||
|
\ 0
|
||
|
At least one matching process was found for each \fIpid\fP operand,
|
||
|
and the specified signal was successfully processed for at
|
||
|
least one matching process.
|
||
|
.TP 7
|
||
|
>0
|
||
|
An error occurred.
|
||
|
.sp
|
||
|
.SH CONSEQUENCES OF ERRORS
|
||
|
.LP
|
||
|
Default.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
Process numbers can be found by using \fIps\fP.
|
||
|
.LP
|
||
|
The job control job ID notation is not required to work as expected
|
||
|
when \fIkill\fP is operating in its own utility execution
|
||
|
environment. In either of the following examples:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBnohup kill %1 &
|
||
|
system("kill %1");
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
the \fIkill\fP operates in a different environment and does not share
|
||
|
the shell's understanding of job numbers.
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
Any of the commands:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBkill -9 100 -165
|
||
|
kill -s kill 100 -165
|
||
|
kill -s KILL 100 -165
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
sends the SIGKILL signal to the process whose process ID is 100 and
|
||
|
to all processes whose process group ID is 165, assuming the
|
||
|
sending process has permission to send that signal to the specified
|
||
|
processes, and that they exist.
|
||
|
.LP
|
||
|
The System Interfaces volume of IEEE\ Std\ 1003.1-2001 and this volume
|
||
|
of IEEE\ Std\ 1003.1-2001 do not require
|
||
|
specific signal numbers for any \fIsignal_names\fP. Even the \fB-\fP
|
||
|
\fIsignal_number\fP option provides symbolic (although
|
||
|
numeric) names for signals. If a process is terminated by a signal,
|
||
|
its exit status indicates the signal that killed it, but the
|
||
|
exact values are not specified. The \fIkill\fP \fB-l\fP option, however,
|
||
|
can be used to map decimal signal numbers and exit
|
||
|
status values into the name of a signal. The following example reports
|
||
|
the status of a terminated job:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBjob
|
||
|
stat=$?
|
||
|
if [ $stat -eq 0 ]
|
||
|
then
|
||
|
echo job completed successfully.
|
||
|
elif [ $stat -gt 128 ]
|
||
|
then
|
||
|
echo job terminated by signal SIG$(kill -l $stat).
|
||
|
else
|
||
|
echo job terminated with error code $stat.
|
||
|
fi
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
To send the default signal to a process group (say 123), an application
|
||
|
should use a command similar to one of the
|
||
|
following:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBkill -TERM -123
|
||
|
kill -- -123
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
The \fB-l\fP option originated from the C shell, and is also implemented
|
||
|
in the KornShell. The C shell output can consist of
|
||
|
multiple output lines because the signal names do not always fit on
|
||
|
a single line on some terminal screens. The KornShell output
|
||
|
also included the implementation-defined signal numbers and was considered
|
||
|
by the standard developers to be too difficult for
|
||
|
scripts to parse conveniently. The specified output format is intended
|
||
|
not only to accommodate the historical C shell output, but
|
||
|
also to permit an entirely vertical or entirely horizontal listing
|
||
|
on systems for which this is appropriate.
|
||
|
.LP
|
||
|
An early proposal invented the name SIGNULL as a \fIsignal_name\fP
|
||
|
for signal 0 (used by the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001 to test for the existence of a process without
|
||
|
sending it a signal). Since the \fIsignal_name\fP 0
|
||
|
can be used in this case unambiguously, SIGNULL has been removed.
|
||
|
.LP
|
||
|
An early proposal also required symbolic \fIsignal_name\fPs to be
|
||
|
recognized with or without the \fBSIG\fP prefix. Historical
|
||
|
versions of \fIkill\fP have not written the \fBSIG\fP prefix for the
|
||
|
\fB-l\fP option and have not recognized the \fBSIG\fP
|
||
|
prefix on \fIsignal_name\fPs. Since neither applications portability
|
||
|
nor ease-of-use would be improved by requiring this
|
||
|
extension, it is no longer required.
|
||
|
.LP
|
||
|
To avoid an ambiguity of an initial negative number argument specifying
|
||
|
either a signal number or a process group,
|
||
|
IEEE\ Std\ 1003.1-2001 mandates that it is always considered the former
|
||
|
by implementations that support the XSI option. It
|
||
|
also requires that conforming applications always use the \fB"--"\fP
|
||
|
options terminator argument when specifying a process
|
||
|
group, unless an option is also specified.
|
||
|
.LP
|
||
|
The \fB-s\fP option was added in response to international interest
|
||
|
in providing some form of \fIkill\fP that meets the
|
||
|
Utility Syntax Guidelines.
|
||
|
.LP
|
||
|
The job control job ID notation is not required to work as expected
|
||
|
when \fIkill\fP is operating in its own utility execution
|
||
|
environment. In either of the following examples:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBnohup kill %1 &
|
||
|
system("kill %1");
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
the \fIkill\fP operates in a different environment and does not understand
|
||
|
how the shell has managed its job numbers.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIShell Command Language\fP , \fIps\fP , \fIwait\fP() , the System
|
||
|
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIkill\fP(), the Base
|
||
|
Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<signal.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|