1KILL(1P)                   POSIX Programmer's Manual                  KILL(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       kill - terminate or signal processes
13

SYNOPSIS

15       kill -s signal_name pid ...
16
17       kill -l [exit_status]
18
19
20
21       kill [-signal_name] pid ...
22
23       kill [-signal_number] pid ...
24
25

DESCRIPTION

27       The kill utility shall send a signal to the process or processes speci‐
28       fied by each pid operand.
29
30       For each pid operand, the kill utility shall perform actions equivalent
31       to the kill() function defined  in  the  System  Interfaces  volume  of
32       IEEE Std 1003.1-2001 called with the following arguments:
33
34        * The value of the pid operand shall be used as the pid argument.
35
36        * The  sig  argument  is  the value specified by the -s option, - sig‐
37          nal_number option, or the - signal_name option, or  by  SIGTERM,  if
38          none of these options is specified.
39

OPTIONS

41       The  kill  utility  shall  conform  to  the  Base Definitions volume of
42       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines,   except
43       that  in  the  last  two SYNOPSIS forms, the - signal_number and - sig‐
44       nal_name options are usually more than a single character.
45
46       The following options shall be supported:
47
48       -l     (The letter ell.) Write all values of signal_name  supported  by
49              the  implementation,  if  no operand is given. If an exit_status
50              operand is given and it is a value of  the  '?'   shell  special
51              parameter  (see Special Parameters and wait() ) corresponding to
52              a process that was terminated by a signal, the signal_name  cor‐
53              responding  to  the  signal that terminated the process shall be
54              written.  If an exit_status operand  is  given  and  it  is  the
55              unsigned  decimal  integer  value  of  a signal number, the sig‐
56              nal_name (the symbolic constant  name  without  the  SIG  prefix
57              defined  in the Base Definitions volume of IEEE Std 1003.1-2001)
58              corresponding to that signal shall be  written.  Otherwise,  the
59              results are unspecified.
60
61       -s  signal_name
62
63              Specify  the  signal  to  send,  using one of the symbolic names
64              defined in the <signal.h> header. Values of signal_name shall be
65              recognized  in  a case-independent fashion, without the SIG pre‐
66              fix. In addition, the symbolic name 0 shall be recognized,  rep‐
67              resenting  the signal value zero. The corresponding signal shall
68              be sent instead of SIGTERM.
69
70       -signal_name
71
72              Equivalent to -s signal_name.
73
74       -signal_number
75
76              Specify a non-negative decimal  integer,  signal_number,  repre‐
77              senting  the  signal  to  be used instead of SIGTERM, as the sig
78              argument in the effective call  to  kill().  The  correspondence
79              between  integer  values  and the sig value used is shown in the
80              following table.
81
82       The effects of specifying any signal_number other than those listed  in
83       the table are undefined.
84
85
86
87                              signal_number   sig Value
88                              0               0
89                              1               SIGHUP
90                              2               SIGINT
91                              3               SIGQUIT
92                              6               SIGABRT
93                              9               SIGKILL
94                              14              SIGALRM
95                              15              SIGTERM
96
97       If the first argument is a negative integer, it shall be interpreted as
98       a - signal_number option, not as a negative pid  operand  specifying  a
99       process group.
100

OPERANDS

102       The following operands shall be supported:
103
104       pid    One of the following:
105
106               1. A  decimal  integer specifying a process or process group to
107                  be signaled.  The process or processes selected by positive,
108                  negative,  and  zero  values  of the pid operand shall be as
109                  described for the kill() function. If process  number  0  is
110                  specified,  all processes in the current process group shall
111                  be signaled. For the effects of negative  pid  numbers,  see
112                  the  kill() function defined in the System Interfaces volume
113                  of IEEE Std 1003.1-2001. If the first pid operand  is  nega‐
114                  tive,  it  should  be preceded by "--" to keep it from being
115                  interpreted as an option.
116
117               2. A job control job ID (see the  Base  Definitions  volume  of
118                  IEEE Std 1003.1-2001,  Section  3.203,  Job  Control Job ID)
119                  that identifies a background process group to  be  signaled.
120                  The job control job ID notation is applicable only for invo‐
121                  cations of kill in the current shell execution  environment;
122                  see Shell Execution Environment .
123
124       exit_status
125              A  decimal integer specifying a signal number or the exit status
126              of a process terminated by a signal.
127
128

STDIN

130       Not used.
131

INPUT FILES

133       None.
134

ENVIRONMENT VARIABLES

136       The following environment variables shall affect the execution of kill:
137
138       LANG   Provide a default value for the  internationalization  variables
139              that  are  unset  or  null.  (See the Base Definitions volume of
140              IEEE Std 1003.1-2001, Section  8.2,  Internationalization  Vari‐
141              ables  for the precedence of internationalization variables used
142              to determine the values of locale categories.)
143
144       LC_ALL If set to a non-empty string value, override the values  of  all
145              the other internationalization variables.
146
147       LC_CTYPE
148              Determine  the  locale  for  the  interpretation of sequences of
149              bytes of text data as characters (for  example,  single-byte  as
150              opposed to multi-byte characters in arguments).
151
152       LC_MESSAGES
153              Determine  the  locale  that should be used to affect the format
154              and contents of diagnostic messages written to standard error.
155
156       NLSPATH
157              Determine the location of message catalogs for the processing of
158              LC_MESSAGES .
159
160

ASYNCHRONOUS EVENTS

162       Default.
163

STDOUT

165       When  the  -l option is not specified, the standard output shall not be
166       used.
167
168       When the -l option is specified, the symbolic name of each signal shall
169       be written in the following format:
170
171
172              "%s%c", <signal_name>, <separator>
173
174       where  the  <signal_name>  is in uppercase, without the SIG prefix, and
175       the <separator> shall be either a <newline> or a <space>. For the  last
176       signal written, <separator> shall be a <newline>.
177
178       When both the -l option and exit_status operand are specified, the sym‐
179       bolic name of the corresponding signal shall be written in the  follow‐
180       ing format:
181
182
183              "%s\n", <signal_name>
184

STDERR

186       The standard error shall be used only for diagnostic messages.
187

OUTPUT FILES

189       None.
190

EXTENDED DESCRIPTION

192       None.
193

EXIT STATUS

195       The following exit values shall be returned:
196
197        0     At  least  one  matching process was found for each pid operand,
198              and the specified signal was successfully processed for at least
199              one matching process.
200
201       >0     An error occurred.
202
203

CONSEQUENCES OF ERRORS

205       Default.
206
207       The following sections are informative.
208

APPLICATION USAGE

210       Process numbers can be found by using ps.
211
212       The  job  control  job  ID notation is not required to work as expected
213       when kill is operating in its own  utility  execution  environment.  In
214       either of the following examples:
215
216
217              nohup kill %1 &
218              system("kill %1");
219
220       the  kill  operates  in  a different environment and does not share the
221       shell's understanding of job numbers.
222

EXAMPLES

224       Any of the commands:
225
226
227              kill -9 100 -165
228              kill -s kill 100 -165
229              kill -s KILL 100 -165
230
231       sends the SIGKILL signal to the process whose process ID is 100 and  to
232       all  processes  whose  process  group  ID  is 165, assuming the sending
233       process has permission to send that signal to the specified  processes,
234       and that they exist.
235
236       The System Interfaces volume of IEEE Std 1003.1-2001 and this volume of
237       IEEE Std 1003.1-2001 do not require specific  signal  numbers  for  any
238       signal_names.   Even  the  -  signal_number  option  provides  symbolic
239       (although numeric) names for signals. If a process is terminated  by  a
240       signal,  its  exit  status indicates the signal that killed it, but the
241       exact values are not specified. The kill -l  option,  however,  can  be
242       used to map decimal signal numbers and exit status values into the name
243       of a signal. The following example reports the status of  a  terminated
244       job:
245
246
247              job
248              stat=$?
249              if [ $stat -eq 0 ]
250              then
251                  echo job completed successfully.
252              elif [ $stat -gt 128 ]
253              then
254                  echo job terminated by signal SIG$(kill -l $stat).
255              else
256                  echo job terminated with error code $stat.
257              fi
258
259       To send the default signal to a process group (say 123), an application
260       should use a command similar to one of the following:
261
262
263              kill -TERM -123
264              kill -- -123
265

RATIONALE

267       The -l option originated from the C shell, and is also  implemented  in
268       the  KornShell. The C shell output can consist of multiple output lines
269       because the signal names do not always fit on a  single  line  on  some
270       terminal  screens.  The  KornShell output also included the implementa‐
271       tion-defined signal numbers and was considered by the standard develop‐
272       ers  to  be too difficult for scripts to parse conveniently. The speci‐
273       fied output format is intended not only to accommodate the historical C
274       shell output, but also to permit an entirely vertical or entirely hori‐
275       zontal listing on systems for which this is appropriate.
276
277       An early proposal invented the name SIGNULL as a signal_name for signal
278       0 (used by the System Interfaces volume of IEEE Std 1003.1-2001 to test
279       for the existence of a process without sending it a signal). Since  the
280       signal_name  0 can be used in this case unambiguously, SIGNULL has been
281       removed.
282
283       An early proposal also required symbolic signal_names to be  recognized
284       with  or  without  the SIG prefix. Historical versions of kill have not
285       written the SIG prefix for the -l option and have  not  recognized  the
286       SIG  prefix on signal_names. Since neither applications portability nor
287       ease-of-use would be improved by requiring this  extension,  it  is  no
288       longer required.
289
290       To avoid an ambiguity of an initial negative number argument specifying
291       either a signal number or a process  group,  IEEE Std 1003.1-2001  man‐
292       dates  that  it is always considered the former by implementations that
293       support the XSI option. It also requires that  conforming  applications
294       always  use  the  "--"  options  terminator  argument when specifying a
295       process group, unless an option is also specified.
296
297       The -s option was added in response to international interest  in  pro‐
298       viding some form of kill that meets the Utility Syntax Guidelines.
299
300       The  job  control  job  ID notation is not required to work as expected
301       when kill is operating in its own  utility  execution  environment.  In
302       either of the following examples:
303
304
305              nohup kill %1 &
306              system("kill %1");
307
308       the  kill  operates  in a different environment and does not understand
309       how the shell has managed its job numbers.
310

FUTURE DIRECTIONS

312       None.
313

SEE ALSO

315       Shell Command Language, ps, wait(), the  System  Interfaces  volume  of
316       IEEE Std 1003.1-2001,   kill(),   the   Base   Definitions   volume  of
317       IEEE Std 1003.1-2001, <signal.h>
318
320       Portions of this text are reprinted and reproduced in  electronic  form
321       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
322       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
323       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
324       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
325       event of any discrepancy between this version and the original IEEE and
326       The Open Group Standard, the original IEEE and The Open Group  Standard
327       is  the  referee document. The original Standard can be obtained online
328       at http://www.opengroup.org/unix/online.html .
329
330
331
332IEEE/The Open Group                  2003                             KILL(1P)
Impressum