Debian Codegraph @

upstream/debian-trixie/man2/kill.2

raw
1 .\" Copyright (c) 1992 Drew Eckhardt ([email protected]), March 28, 1992
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Modified by Michael Haardt <[email protected]>
6 .\" Modified by Thomas Koenig <[email protected]>
7 .\" Modified 1993-07-23 by Rik Faith <[email protected]>
8 .\" Modified 1993-07-25 by Rik Faith <[email protected]>
9 .\" Modified 1995-11-01 by Michael Haardt
10 .\" <[email protected]>
11 .\" Modified 1996-04-14 by Andries Brouwer <[email protected]>
12 .\" [added some polishing contributed by Mike Battersby <[email protected]>]
13 .\" Modified 1996-07-21 by Andries Brouwer <[email protected]>
14 .\" Modified 1997-01-17 by Andries Brouwer <[email protected]>
15 .\" Modified 2001-12-18 by Andries Brouwer <[email protected]>
16 .\" Modified 2002-07-24 by Michael Kerrisk <[email protected]>
17 .\" Added note on historical rules enforced when an unprivileged process
18 .\" sends a signal.
19 .\" Modified 2004-06-16 by Michael Kerrisk <[email protected]>
20 .\" Added note on CAP_KILL
21 .\" Modified 2004-06-24 by aeb
22 .\" Modified, 2004-11-30, after idea from [email protected]
23 .\"
24 .TH kill 2 2024-05-02 "Linux man-pages 6.9.1"
25 .SH NAME
26 kill \- send signal to a process
27 .SH LIBRARY
28 Standard C library
29 .RI ( libc ", " \-lc )
30 .SH SYNOPSIS
31 .nf
32 .B #include <signal.h>
33 .P
34 .BI "int kill(pid_t " pid ", int " sig );
35 .fi
36 .P
37 .RS -4
38 Feature Test Macro Requirements for glibc (see
39 .BR feature_test_macros (7)):
40 .RE
41 .P
42 .BR kill ():
43 .nf
44 _POSIX_C_SOURCE
45 .fi
46 .SH DESCRIPTION
47 The
48 .BR kill ()
49 system call
50 can be used to send any signal to any process group or process.
51 .P
52 If \fIpid\fP is positive, then signal \fIsig\fP is sent to the
53 process with the ID specified by \fIpid\fP.
54 .P
55 If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the
56 process group of the calling process.
57 .P
58 If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process
59 for which the calling process has permission to send signals,
60 except for process 1 (\fIinit\fP), but see below.
61 .P
62 If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process
63 in the process group whose ID is \fI\-pid\fP.
64 .P
65 If \fIsig\fP is 0, then no signal is sent,
66 but existence and permission checks are still performed;
67 this can be used to check for the existence of a process ID or
68 process group ID that the caller is permitted to signal.
69 .P
70 For a process to have permission to send a signal,
71 it must either be privileged (under Linux: have the
72 .B CAP_KILL
73 capability in the user namespace of the target process),
74 or the real or effective user ID of the sending process must equal
75 the real or saved set-user-ID of the target process.
76 In the case of
77 .BR SIGCONT ,
78 it suffices when the sending and receiving
79 processes belong to the same session.
80 (Historically, the rules were different; see NOTES.)
81 .SH RETURN VALUE
82 On success (at least one signal was sent), zero is returned.
83 On error, \-1 is returned, and
84 .I errno
85 is set to indicate the error.
86 .SH ERRORS
87 .TP
88 .B EINVAL
89 An invalid signal was specified.
90 .TP
91 .B EPERM
92 The calling process does not have permission to send the signal
93 to any of the target processes.
94 .TP
95 .B ESRCH
96 The target process or process group does not exist.
97 Note that an existing process might be a zombie,
98 a process that has terminated execution, but
99 has not yet been
100 .BR wait (2)ed
101 for.
102 .SH STANDARDS
103 POSIX.1-2008.
104 .SH HISTORY
105 POSIX.1-2001, SVr4, 4.3BSD.
106 .SS Linux notes
107 Across different kernel versions, Linux has enforced different rules
108 for the permissions required for an unprivileged process
109 to send a signal to another process.
110 .\" In the 0.* kernels things chopped and changed quite
111 .\" a bit - MTK, 24 Jul 02
112 In Linux 1.0 to 1.2.2, a signal could be sent if the
113 effective user ID of the sender matched effective user ID of the target,
114 or the real user ID of the sender matched the real user ID of the target.
115 From Linux 1.2.3 until 1.3.77, a signal could be sent if the
116 effective user ID of the sender matched either the real or effective
117 user ID of the target.
118 The current rules, which conform to POSIX.1, were adopted
119 in Linux 1.3.78.
120 .SH NOTES
121 The only signals that can be sent to process ID 1, the
122 .I init
123 process, are those for which
124 .I init
125 has explicitly installed signal handlers.
126 This is done to assure the
127 system is not brought down accidentally.
128 .P
129 POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP
130 to all processes that the calling process may send signals to,
131 except possibly for some implementation-defined system processes.
132 Linux allows a process to signal itself, but on Linux the call
133 \fIkill(\-1,sig)\fP does not signal the calling process.
134 .P
135 POSIX.1 requires that if a process sends a signal to itself,
136 and the sending thread does not have the signal blocked,
137 and no other thread
138 has it unblocked or is waiting for it in
139 .BR sigwait (3),
140 at least one
141 unblocked signal must be delivered to the sending thread before the
142 .BR kill ()
143 returns.
144 .SH BUGS
145 In Linux 2.6 up to and including Linux 2.6.7,
146 there was a bug that meant that when sending signals to a process group,
147 .BR kill ()
148 failed with the error
149 .B EPERM
150 if the caller did not have permission to send the signal to \fIany\fP (rather
151 than \fIall\fP) of the members of the process group.
152 Notwithstanding this error return, the signal was still delivered
153 to all of the processes for which the caller had permission to signal.
154 .SH SEE ALSO
155 .BR kill (1),
156 .BR _exit (2),
157 .BR pidfd_send_signal (2),
158 .BR signal (2),
159 .BR tkill (2),
160 .BR exit (3),
161 .BR killpg (3),
162 .BR sigqueue (3),
163 .BR capabilities (7),
164 .BR credentials (7),
165 .BR signal (7)