kill.1p (12314B)
- '\" et
- .TH KILL "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- kill
- \(em terminate or signal processes
- .SH SYNOPSIS
- .LP
- .nf
- kill -s \fIsignal_name pid\fR...
- .P
- kill -l \fB[\fIexit_status\fB]\fR
- .P
- kill \fB[\fR-\fIsignal_name\fB] \fIpid\fR...
- .P
- kill \fB[\fR-\fIsignal_number\fB] \fIpid\fR...
- .fi
- .SH DESCRIPTION
- The
- .IR kill
- utility shall send a signal to the process or processes specified by
- each
- .IR pid
- operand.
- .P
- For each
- .IR pid
- operand, the
- .IR kill
- utility shall perform actions equivalent to the
- \fIkill\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017 called with the following arguments:
- .IP " *" 4
- The value of the
- .IR pid
- operand shall be used as the
- .IR pid
- argument.
- .IP " *" 4
- The
- .IR sig
- argument is the value specified by the
- .BR \-s
- option,
- .BR \- \c
- .IR signal_number
- option, or the
- .BR \- \c
- .IR signal_name
- option, or by SIGTERM, if none of these options is specified.
- .SH OPTIONS
- The
- .IR kill
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines",
- except that in the last two SYNOPSIS forms, the
- .BR \- \c
- .IR signal_number
- and
- .BR \- \c
- .IR signal_name
- options are usually more than a single character.
- .P
- The following options shall be supported:
- .IP "\fB\-l\fP" 10
- (The letter ell.) Write all values of
- .IR signal_name
- supported by the implementation, if no operand is given. If an
- .IR exit_status
- operand is given and it is a value of the
- .BR '?'
- shell special parameter (see
- .IR "Section 2.5.2" ", " "Special Parameters"
- and
- .IR wait )
- corresponding to a process that was terminated by a signal, the
- .IR signal_name
- corresponding to the signal that terminated the process shall be
- written. If an
- .IR exit_status
- operand is given and it is the unsigned decimal integer value of a
- signal number, the
- .IR signal_name
- (the symbolic constant name without the
- .BR SIG
- prefix defined in the Base Definitions volume of POSIX.1\(hy2017) corresponding to that signal shall be
- written. Otherwise, the results are unspecified.
- .IP "\fB\-s\ \fIsignal_name\fR" 10
- .br
- Specify the signal to send, using one of the symbolic names defined in
- the
- .IR <signal.h>
- header. Values of
- .IR signal_name
- shall be recognized in a case-independent fashion, without the
- .BR SIG
- prefix. In addition, the symbolic name 0 shall be recognized,
- representing the signal value zero. The corresponding signal shall be
- sent instead of SIGTERM.
- .IP "\fB\-\fIsignal_name\fR" 10
- .br
- Equivalent to
- .BR \-s
- .IR signal_name .
- .IP "\fB\-\fIsignal_number\fR" 10
- .br
- Specify a non-negative decimal integer,
- .IR signal_number ,
- representing the signal to be used instead of SIGTERM, as the
- .IR sig
- argument in the effective call to
- \fIkill\fR().
- The correspondence between integer values and the
- .IR sig
- value used is shown in the following list.
- .RS 10
- .P
- The effects of specifying any
- .IR signal_number
- other than those listed below are undefined.
- .IP 0 6
- 0
- .IP 1 6
- SIGHUP
- .IP 2 6
- SIGINT
- .IP 3 6
- SIGQUIT
- .IP 6 6
- SIGABRT
- .IP 9 6
- SIGKILL
- .IP 14 6
- SIGALRM
- .IP 15 6
- SIGTERM
- .P
- If the first argument is a negative integer, it shall be interpreted as a
- .BR \- \c
- .IR signal_number
- option, not as a negative
- .IR pid
- operand specifying a process group.
- .RE
- .SH OPERANDS
- The following operands shall be supported:
- .IP "\fIpid\fR" 10
- One of the following:
- .RS 10
- .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
- .IR pid
- operand shall be as described for the
- \fIkill\fR()
- function. If process number 0 is specified, all processes in the
- current process group shall be signaled. For the effects of negative
- .IR pid
- numbers, see the
- \fIkill\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017. If the first
- .IR pid
- operand is negative, it should be preceded by
- .BR \(dq--\(dq
- to keep it from being interpreted as an option.
- .IP " 2." 4
- A job control job ID (see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 3.204" ", " "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
- .IR kill
- in the current shell execution environment; see
- .IR "Section 2.12" ", " "Shell Execution Environment".
- .RE
- .IP "\fIexit_status\fR" 10
- A decimal integer specifying a signal number or the exit status of a
- process terminated by a signal.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR kill :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- When the
- .BR \-l
- option is not specified, the standard output shall not be used.
- .P
- When the
- .BR \-l
- option is specified, the symbolic name of each signal shall be written
- in the following format:
- .sp
- .RS 4
- .nf
- "%s%c", <\fIsignal_name\fR>, <\fIseparator\fR>
- .fi
- .P
- .RE
- .P
- where the <\fIsignal_name\fP> is in uppercase, without the
- .BR SIG
- prefix, and the <\fIseparator\fP> shall be either a
- <newline>
- or a
- <space>.
- For the last signal written, <\fIseparator\fP> shall be a
- <newline>.
- .P
- When both the
- .BR \-l
- option and
- .IR exit_status
- operand are specified, the symbolic name of the corresponding signal
- shall be written in the following format:
- .sp
- .RS 4
- .nf
- "%s\en", <\fIsignal_name\fR>
- .fi
- .P
- .RE
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- At least one matching process was found for each
- .IR pid
- operand, and the specified signal was successfully processed for at
- least one matching process.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Process numbers can be found by using
- .IR ps .
- .P
- The job control job ID notation is not required to work as expected
- when
- .IR kill
- is operating in its own utility execution environment. In either of
- the following examples:
- .sp
- .RS 4
- .nf
- nohup kill %1 &
- system("kill %1");
- .fi
- .P
- .RE
- .P
- the
- .IR kill
- operates in a different environment and does not share the shell's
- understanding of job numbers.
- .SH EXAMPLES
- Any of the commands:
- .sp
- .RS 4
- .nf
- kill -9 100 -165
- kill -s kill 100 -165
- kill -s KILL 100 -165
- .fi
- .P
- .RE
- .P
- 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.
- .P
- The System Interfaces volume of POSIX.1\(hy2017 and this volume of POSIX.1\(hy2017 do not require specific signal numbers for any
- .IR signal_names .
- Even the
- .BR \- \c
- .IR signal_number
- 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
- .IR kill
- .BR \-l
- 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 4
- .nf
- job
- 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
- .fi
- .P
- .RE
- .P
- 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 4
- .nf
- kill -TERM -123
- kill -- -123
- .fi
- .P
- .RE
- .SH RATIONALE
- The
- .BR \-l
- 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.
- .P
- An early proposal invented the name SIGNULL as a
- .IR signal_name
- for signal 0 (used by the System Interfaces volume of POSIX.1\(hy2017 to test for the existence of a process
- without sending it a signal). Since the
- .IR signal_name
- 0 can be used in this case unambiguously, SIGNULL has been removed.
- .P
- An early proposal also required symbolic
- .IR signal_name s
- to be recognized with or without the
- .BR SIG
- prefix. Historical versions of
- .IR kill
- have not written the
- .BR SIG
- prefix for the
- .BR \-l
- option and have not recognized the
- .BR SIG
- prefix on
- .IR signal_name s.
- Since neither applications portability nor ease-of-use would be improved
- by requiring this extension, it is no longer required.
- .P
- To avoid an ambiguity of an initial negative number argument specifying
- either a signal number or a process group, POSIX.1\(hy2008 mandates that it is
- always considered the former by implementations that support the XSI
- option. It also requires that conforming applications always use the
- .BR \(dq--\(dq
- options terminator argument when specifying a process group, unless an
- option is also specified.
- .P
- The
- .BR \-s
- option was added in response to international interest in providing
- some form of
- .IR kill
- that meets the Utility Syntax Guidelines.
- .P
- The job control job ID notation is not required to work as expected
- when
- .IR kill
- is operating in its own utility execution environment. In either of
- the following examples:
- .sp
- .RS 4
- .nf
- nohup kill %1 &
- system("kill %1");
- .fi
- .P
- .RE
- .P
- the
- .IR kill
- operates in a different environment and does not understand how the
- shell has managed its job numbers.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Chapter 2" ", " "Shell Command Language",
- .IR "\fIps\fR\^",
- .IR "\fIwait\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 3.204" ", " "Job Control Job ID",
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines",
- .IR "\fB<signal.h>\fP"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIkill\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .