1KILL(3P)                   POSIX Programmer's Manual                  KILL(3P)
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 - send a signal to a process or a group of processes
13

SYNOPSIS

15       #include <signal.h>
16
17       int kill(pid_t pid, int sig);
18
19

DESCRIPTION

21       The kill() function shall send a signal to a process or a group of pro‐
22       cesses  specified by pid. The signal to be sent is specified by sig and
23       is either one from the list given in <signal.h> or 0. If sig is 0  (the
24       null  signal),  error  checking  is performed but no signal is actually
25       sent. The null signal can be used to check the validity of pid.
26
27       For a process to have permission to send a signal to a  process  desig‐
28       nated  by  pid,  unless the sending process has appropriate privileges,
29       the real or effective user ID of the sending process  shall  match  the
30       real or saved set-user-ID of the receiving process.
31
32       If  pid  is  greater  than  0,  sig  shall be sent to the process whose
33       process ID is equal to pid.
34
35       If pid is 0, sig shall be sent to all processes (excluding an  unspeci‐
36       fied  set  of  system processes) whose process group ID is equal to the
37       process group ID of the sender, and for which the process  has  permis‐
38       sion to send a signal.
39
40       If pid is -1, sig shall be sent to all processes (excluding an unspeci‐
41       fied set of system processes) for which the process has  permission  to
42       send that signal.
43
44       If  pid  is  negative,  but  not -1, sig shall be sent to all processes
45       (excluding an unspecified set of system processes) whose process  group
46       ID is equal to the absolute value of pid, and for which the process has
47       permission to send a signal.
48
49       If the value of pid causes sig to be generated for the sending process,
50       and if sig is not blocked for the calling thread and if no other thread
51       has sig unblocked or is waiting in a sigwait() function for sig, either
52       sig  or at least one pending unblocked signal shall be delivered to the
53       sending thread before kill() returns.
54
55       The user ID tests described above shall not  be  applied  when  sending
56       SIGCONT  to a process that is a member of the same session as the send‐
57       ing process.
58
59       An implementation that provides extended security controls  may  impose
60       further  implementation-defined restrictions on the sending of signals,
61       including the null signal. In particular, the system may deny the exis‐
62       tence of some or all of the processes specified by pid.
63
64       The kill() function is successful if the process has permission to send
65       sig to any of the processes specified by pid. If kill() fails, no  sig‐
66       nal shall be sent.
67

RETURN VALUE

69       Upon successful completion, 0 shall be returned. Otherwise, -1 shall be
70       returned and errno set to indicate the error.
71

ERRORS

73       The kill() function shall fail if:
74
75       EINVAL The value of the sig argument is an invalid or unsupported  sig‐
76              nal number.
77
78       EPERM  The  process  does not have permission to send the signal to any
79              receiving process.
80
81       ESRCH  No process or process group can be found corresponding  to  that
82              specified by pid.
83
84
85       The following sections are informative.
86

EXAMPLES

88       None.
89

APPLICATION USAGE

91       None.
92

RATIONALE

94       The  semantics for permission checking for kill() differed between Sys‐
95       tem V and most other implementations, such as Version 7 or 4.3 BSD. The
96       semantics  chosen  for  this  volume of IEEE Std 1003.1-2001 agree with
97       System V. Specifically, a set-user-ID  process  cannot  protect  itself
98       against signals (or at least not against SIGKILL) unless it changes its
99       real user ID.  This choice allows the user who starts an application to
100       send  it  signals  even  if it changes its effective user ID. The other
101       semantics give more power to  an  application  that  wants  to  protect
102       itself from the user who ran it.
103
104       Some implementations provide semantic extensions to the kill() function
105       when the absolute value of pid is greater than some maximum, or  other‐
106       wise  special,  value. Negative values are a flag to kill(). Since most
107       implementations return [ESRCH] in  this  case,  this  behavior  is  not
108       included  in this volume of IEEE Std 1003.1-2001, although a conforming
109       implementation could provide such an extension.
110
111       The implementation-defined processes to which a signal cannot  be  sent
112       may include the scheduler or init.
113
114       There  was initially strong sentiment to specify that, if pid specifies
115       that a signal be sent to the calling process and  that  signal  is  not
116       blocked,  that  signal  would  be delivered before kill() returns. This
117       would permit a process to call kill() and be guaranteed that  the  call
118       never return. However, historical implementations that provide only the
119       signal() function make only the weaker  guarantee  in  this  volume  of
120       IEEE Std 1003.1-2001,  because they only deliver one signal each time a
121       process enters the kernel. Modifications  to  such  implementations  to
122       support  the sigaction() function generally require entry to the kernel
123       following return from a signal-catching function, in order  to  restore
124       the  signal  mask. Such modifications have the effect of satisfying the
125       stronger requirement, at least when sigaction() is used, but not neces‐
126       sarily  when  signal()  is  used.  The  developers  of  this  volume of
127       IEEE Std 1003.1-2001 considered making the stronger requirement  except
128       when  signal()  is  used, but felt this would be unnecessarily complex.
129       Implementors are encouraged to meet the stronger  requirement  whenever
130       possible.  In  practice,  the weaker requirement is the same, except in
131       the rare case when two signals arrive during a very short window.  This
132       reasoning also applies to a similar requirement for sigprocmask().
133
134       In  4.2  BSD,  the SIGCONT signal can be sent to any descendant process
135       regardless of user-ID security checks. This allows a job control  shell
136       to  continue a job even if processes in the job have altered their user
137       IDs (as in the su command). In keeping with the addition of the concept
138       of  sessions, similar functionality is provided by allowing the SIGCONT
139       signal to be sent to any process in the same session regardless of user
140       ID  security  checks.   This  is less restrictive than BSD in the sense
141       that ancestor processes (in the same session) can now be the recipient.
142       It  is more restrictive than BSD in the sense that descendant processes
143       that form new sessions are now subject to the user ID checks. A similar
144       relaxation  of security is not necessary for the other job control sig‐
145       nals since those signals are typically sent by the terminal  driver  in
146       recognition  of  special  characters  being  typed; the terminal driver
147       bypasses all security checks.
148
149       In secure implementations, a process may be restricted from  sending  a
150       signal to a process having a different security label. In order to pre‐
151       vent the existence or nonexistence of a process from being  used  as  a
152       covert channel, such processes should appear nonexistent to the sender;
153       that is, [ESRCH] should be returned, rather than [EPERM], if pid refers
154       only to such processes.
155
156       Existing  implementations vary on the result of a kill() with pid indi‐
157       cating an inactive process (a terminated  process  that  has  not  been
158       waited  for  by its parent). Some indicate success on such a call (sub‐
159       ject to permission checking), while others give an  error  of  [ESRCH].
160       Since   the   definition   of   process  lifetime  in  this  volume  of
161       IEEE Std 1003.1-2001 covers inactive processes, the  [ESRCH]  error  as
162       described is inappropriate in this case. In particular, this means that
163       an application cannot have a parent process check for termination of  a
164       particular  child with kill(). (Usually this is done with the null sig‐
165       nal; this can be done reliably with waitpid().)
166
167       There is some belief that the name  kill()  is  misleading,  since  the
168       function  is not always intended to cause process termination. However,
169       the name is common to all historical implementations,  and  any  change
170       would  be  in  conflict  with  the  goal of minimal changes to existing
171       application code.
172

FUTURE DIRECTIONS

174       None.
175

SEE ALSO

177       getpid(), raise(), setsid(), sigaction(), sigqueue(), the Base  Defini‐
178       tions volume of IEEE Std 1003.1-2001, <signal.h>, <sys/types.h>
179
181       Portions  of  this text are reprinted and reproduced in electronic form
182       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
183       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
184       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
185       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
186       event of any discrepancy between this version and the original IEEE and
187       The  Open Group Standard, the original IEEE and The Open Group Standard
188       is the referee document. The original Standard can be  obtained  online
189       at http://www.opengroup.org/unix/online.html .
190
191
192
193IEEE/The Open Group                  2003                             KILL(3P)
Impressum