diff options
Diffstat (limited to 'man1p/kill.1p')
| -rw-r--r-- | man1p/kill.1p | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/man1p/kill.1p b/man1p/kill.1p new file mode 100644 index 000000000..c494b742b --- /dev/null +++ b/man1p/kill.1p @@ -0,0 +1,393 @@ +.\" 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 . |