path: root/usr/src/man/man1/kill.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\"
.TH KILL 1 "Aug 11, 2009"
.SH NAME
kill \- terminate or signal processes
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/kill\fR \fB-s\fR \fIsignal_name\fR \fIpid\fR...
.fi

.LP
.nf
\fB/usr/bin/kill\fR \fB-l\fR [\fIexit_status\fR]
.fi

.LP
.nf
\fB/usr/bin/kill\fR [\fB-\fIsignal_name\fR\fR] \fIpid\fR...
.fi

.LP
.nf
\fB/usr/bin/kill\fR [\fB-\fIsignal_number\fR\fR] \fIpid\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBkill\fR utility sends a signal to the process or processes specified by
each \fIpid\fR operand.
.sp
.LP
For each \fIpid\fR operand, the \fBkill\fR utility performs actions equivalent
to the \fBkill\fR(2) function called with the following arguments:
.RS +4
.TP
1.
The value of the \fIpid\fR operand is used as the \fIpid\fR argument.
.RE
.RS +4
.TP
2.
The \fIsig\fR argument is the value specified by the \fB-s\fR option, the
\fB-\fR\fIsignal_name\fR option, or the \fB-\fR\fIsignal_number\fR option, or,
if none of these options is specified, by \fBSIGTERM\fR.
.RE
.sp
.LP
The signaled process must belong to the current user unless the user is the
super-user.
.sp
.LP
See NOTES for descriptions of the shell built-in versions of \fBkill\fR.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 18n
(The letter ell.) Writes all values of \fIsignal_name\fR supported by the
implementation, if no operand is specified. If an \fIexit_status\fR operand is
specified and it is a value of the \fB?\fR shell special parameter and
\fBwait\fR corresponding to a process that was terminated by a signal, the
\fIsignal_name\fR corresponding to the signal that terminated the process is
written. If an \fIexit_status\fR operand is specified and it is the unsigned
decimal integer value of a signal number, the \fIsignal_name\fR corresponding
to that signal is written. Otherwise, the results are unspecified.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsignal_name\fR\fR
.ad
.RS 18n
Specifies the signal to send, using one of the symbolic names defined in the
\fB<signal.h>\fR description. Values of \fIsignal_name\fR is recognized in a
case-independent fashion, without the \fBSIG\fR prefix. In addition, the
symbolic name \fB0\fR is recognized, representing the signal value zero. The
corresponding signal is sent instead of \fBSIGTERM\fR.
.RE

.sp
.ne 2
.na
\fB\fB-\fR\fIsignal_name\fR\fR
.ad
.RS 18n
Equivalent to \fB-s\fR \fIsignal_name\fR.
.RE

.sp
.ne 2
.na
\fB\fB-\fR\fIsignal_number\fR\fR
.ad
.RS 18n
Specifies a non-negative decimal integer, \fIsignal_number\fR, representing the
signal to be used instead of \fBSIGTERM\fR, as the \fIsig\fR argument in the
effective call to \fBkill\fR(2).
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIpid\fR\fR
.ad
.RS 15n
One of the following:
.RS +4
.TP
1.
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\fR operand is as described for the kill function. If process number 0 is
specified, all processes in the process group are signaled. If the first
\fIpid\fR operand is negative, it should be preceded by \fB\(mi\(mi\fR to keep
it from being interpreted as an option.
.RE
.RS +4
.TP
2.
A job control job \fBID\fR that identifies a background process group to be
signaled. The job control job \fBID\fR notation is applicable only for
invocations of \fBkill\fR in the current shell execution environment.
.RE
The job control job \fBID\fR type of \fIpid\fR is available only on systems
supporting the job control option.
.RE

.sp
.ne 2
.na
\fB\fIexit_status\fR\fR
.ad
.RS 15n
A decimal integer specifying a signal number or the exit status of a process
terminated by a signal.
.RE

.SH USAGE
.sp
.LP
Process numbers can be found by using \fBps\fR(1).
.sp
.LP
The job control job \fBID\fR notation is not required to work as expected when
\fBkill\fR is operating in its own utility execution environment. In either of
the following examples:
.sp
.in +2
.nf
example% \fBnohup kill %1 &\fR
example% \fBsystem( "kill %1");\fR
.fi
.in -2
.sp

.sp
.LP
\fBkill\fR operates in a different environment and does not share the shell's
understanding of job numbers.
.SH OUTPUT
.sp
.LP
When the \fB-l\fR option is not specified, the standard output is not be used.
.sp
.LP
When the \fB-l\fR option is specified, the symbolic name of each signal is
written in the following format:
.sp
.in +2
.nf
"%s%c", <\fIsignal_name\fR>, <\fIseparator\fR>
.fi
.in -2

.sp
.LP
where the \fB<\fR\fIsignal_name\fR\fB>\fR is in upper-case, without the
\fBSIG\fR prefix, and the \fB<\fR\fIseparator\fR\fB>\fR is either a newline
character or a space character. For the last signal written,
\fB<\fR\fIseparator\fR\fB>\fR is a newline character.
.sp
.LP
When both the \fB-l\fR option and \fIexit_status\fR operand are specified, the
symbolic name of the corresponding signal is written in the following format:
.sp
.in +2
.nf
"%s\en", <\fIsignal_name\fR>
.fi
.in -2

.SH EXAMPLES
.LP
\fBExample 1 \fRSending the kill signal
.sp
.LP
Any of the commands:

.sp
.in +2
.nf
example% \fBkill -9 100 -165\fR
example% \fBkill -s kill 100 -165\fR
example% \fBkill -s KILL 100 -165\fR
.fi
.in -2
.sp

.sp
.LP
sends the \fBSIGKILL\fR signal to the process whose process \fBID\fR is
\fB100\fR and to all processes whose process group \fBID\fR is \fB165\fR,
assuming the sending process has permission to send that signal to the
specified processes, and that they exist.

.LP
\fBExample 2 \fRAvoiding ambiguity with an initial negative number
.sp
.LP
To avoid an ambiguity of an initial negative number argument specifying either
a signal number or a process group, the former is always be the case.
Therefore, to send the default signal to a process group (for example,
\fB123\fR), an application should use a command similar to one of the
following:

.sp
.in +2
.nf
example% \fBkill -TERM -123\fR
example% \fBkill -- -123\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBkill\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
At least one matching process was found for each \fIpid\fR operand, and the
specified signal was successfully processed for at least one matching process.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "/usr/bin/kill, csh, ksh, sh"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SS "ksh93"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Uncommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBcsh\fR(1), \fBgetconf\fR(1), \fBjobs\fR(1), \fBksh\fR(1), \fBksh93\fR(1),
\fBps\fR(1), \fBsh\fR(1), \fBshell_builtins\fR(1), \fBwait\fR(1),
\fBkill\fR(2), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5),
\fBenviron\fR(5), \fBstandards\fR(5)
.SH NOTES
.SS "/usr/bin/kill"
.sp
.LP
The number of realtime signals supported is defined by the \fBgetconf\fR(1)
value \fB_POSIX_RTSIG_MAX\fR.
.SS "sh"
.sp
.LP
The Bourne shell, \fBsh\fR, has a built-in version of \fBkill\fR to provide the
functionality of the \fBkill\fR command for processes identified with a
\fIjobid\fR. The \fBsh\fR syntax is:
.sp
.in +2
.nf
kill [ -sig ] [ pid ] [ %job ]...
kill -l
.fi
.in -2
.sp

.SS "csh"
.sp
.LP
The C-shell, \fBcsh\fR, also has a built-in \fBkill\fR command, whose syntax
is:
.sp
.in +2
.nf
kill [-sig][pid][%job]...
kill -l
.fi
.in -2
.sp

.sp
.LP
The \fBcsh\fR \fBkill\fR built-in sends the \fBTERM\fR (terminate) signal, by
default, or the signal specified, to the specified process \fBID\fR, the
\fIjob\fR indicated, or the current \fIjob\fR. Signals are either specified by
number or by name. There is no default. Typing \fBkill\fR does not send a
signal to the current job. If the signal being sent is \fBTERM\fR (terminate)
or \fBHUP\fR (hangup), then the job or process is sent a \fBCONT\fR (continue)
signal as well.
.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 6n
Lists the signal names that can be sent.
.RE

.SS "ksh"
.sp
.LP
The syntax of the \fBksh\fR \fBkill\fR is:
.sp
.in +2
.nf
kill [-sig][pid][%job]...
kill -l
.fi
.in -2
.sp

.sp
.LP
The \fBksh\fR \fBkill\fR sends either the \fBTERM\fR (terminate) signal or the
specified signal to the specified jobs or processes. Signals are either
specified by number or by names (as specified in \fBsignal.h\fR(3HEAD) stripped
of the \fBSIG\fR prefix). If the signal being sent is \fBTERM\fR (terminate) or
\fBHUP\fR (hangup), then the job or process is sent a \fBCONT\fR (continue)
signal if it is stopped. The argument \fIjob\fR can be the process id of a
process that is not a member of one of the active jobs. In the second form,
\fBkill\fR \fB-l\fR, the signal numbers and names are listed.
.SS "ksh93"
.sp
.LP
The syntax of the \fBksh93\fR \fBkill\fR is:
.sp
.in +2
.nf
kill [-n signum] [-s signame] job ...
kill [-n signum] [-s signame] -l [arg ...]
.fi
.in -2
.sp

.sp
.LP
With the first form in which \fB-l\fR is not specified, \fBkill\fR sends a
signal to one or more processes specified by \fIjob\fR. This normally
terminates the processes unless the signal is being caught or ignored.
.sp
.LP
Specify \fIjob\fR as one of the following:
.sp
.ne 2
.na
\fB\fInumber\fR\fR
.ad
.RS 12n
The process id of \fIjob\fR.
.RE

.sp
.ne 2
.na
\fB\fB-\fR\fInumber\fR\fR
.ad
.RS 12n
The process group id of \fIjob\fR.
.RE

.sp
.ne 2
.na
\fB\fB%\fR\fInumber\fR\fR
.ad
.RS 12n
The job number.
.RE

.sp
.ne 2
.na
\fB\fB%\fR\fIstring\fR\fR
.ad
.RS 12n
The job whose name begins with \fIstring\fR.
.RE

.sp
.ne 2
.na
\fB\fB%?\fR\fIstring\fR\fR
.ad
.RS 12n
The job whose name contains \fIstring\fR.
.RE

.sp
.ne 2
.na
\fB\fB%+\fR\fR
.ad
.br
.na
\fB\fB%%\fR\fR
.ad
.RS 12n
The current job.
.RE

.sp
.ne 2
.na
\fB\fB%-\fR\fR
.ad
.RS 12n
The previous job.
.RE

.sp
.LP
If the signal is not specified with either the \fB-n\fR or the \fB-s\fR option,
the \fBSIGTERM\fR signal is used.
.sp
.LP
If \fB-l\fR is specified, and no \fIarg\fR is specified, then \fBkill\fR writes
the list of signals to standard output. Otherwise, \fIarg\fR can be either a
signal name, or a number representing either a signal number or exit status for
a process that was terminated due to a signal. If a name is specified  the
corresponding signal number is written to standard output. If a number is
specified the corresponding signal name is written to standard output.
.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 14n
List signal names or signal numbers rather than sending signals as described
above. The \fB-n\fR and \fB-s\fR options cannot be specified.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIsignum\fR\fR
.ad
.RS 14n
Specify a signal number to send. Signal numbers are not portable across
platforms, except for the following:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
No signal.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 6n
\fBHUP\fR
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 6n
\fBINT\fR
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 6n
\fBQUIT\fR
.RE

.sp
.ne 2
.na
\fB\fB6\fR\fR
.ad
.RS 6n
\fBABRT\fR
.RE

.sp
.ne 2
.na
\fB\fB9\fR\fR
.ad
.RS 6n
\fBKILL\fR
.RE

.sp
.ne 2
.na
\fB\fB14\fR\fR
.ad
.RS 6n
\fBALRM\fR
.RE

.sp
.ne 2
.na
\fB\fB15\fR\fR
.ad
.RS 6n
\fBTERM\fR
.RE

.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsigname\fR\fR
.ad
.RS 14n
Specify a signal name to send. The signal names are derived from their names in
\fB<signal.h>\fR without the \fBSIG\fR prefix and are case insensitive.
\fBkill\fR \fB-l\fR generates the list of signals on the current platform.
.RE

.sp
.LP
\fBkill\fR in \fBksh93\fR exits with one of the following values:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
At least one matching process was found for each job operand, and the specified
signal was successfully sent to at least one matching process.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE