Debian Codegraph @

upstream/debian-unstable/man2/pidfd_send_signal.2

raw
1 .\" Copyright 2019, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pidfd_send_signal 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pidfd_send_signal \- send a signal to a process specified by a file descriptor
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/signal.h>" " /* Definition of " SIG* " constants */"
15 .BR "#include <signal.h>" " /* Definition of " SI_* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig ,
20 .BI " siginfo_t *_Nullable " info ", unsigned int " flags );
21 .fi
22 .P
23 .IR Note :
24 glibc provides no wrapper for
25 .BR pidfd_send_signal (),
26 necessitating the use of
27 .BR syscall (2).
28 .SH DESCRIPTION
29 The
30 .BR pidfd_send_signal ()
31 system call sends the signal
32 .I sig
33 to the target process referred to by
34 .IR pidfd ,
35 a PID file descriptor that refers to a process.
36 .\" See the very detailed commit message for kernel commit
37 .\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad
38 .P
39 If the
40 .I info
41 argument points to a
42 .I siginfo_t
43 buffer, that buffer should be populated as described in
44 .BR rt_sigqueueinfo (2).
45 .P
46 If the
47 .I info
48 argument is a null pointer,
49 this is equivalent to specifying a pointer to a
50 .I siginfo_t
51 buffer whose fields match the values that are
52 implicitly supplied when a signal is sent using
53 .BR kill (2):
54 .P
55 .PD 0
56 .IP \[bu] 3
57 .I si_signo
58 is set to the signal number;
59 .IP \[bu]
60 .I si_errno
61 is set to 0;
62 .IP \[bu]
63 .I si_code
64 is set to
65 .BR SI_USER ;
66 .IP \[bu]
67 .I si_pid
68 is set to the caller's PID;
69 and
70 .IP \[bu]
71 .I si_uid
72 is set to the caller's real user ID.
73 .PD
74 .P
75 The calling process must either be in the same PID namespace as the
76 process referred to by
77 .IR pidfd ,
78 or be in an ancestor of that namespace.
79 .P
80 The
81 .I flags
82 argument allows to modify the scope of the signal.
83 By default,
84 the scope of the signal will be inferred from the
85 .I pidfd
86 argument.
87 For example,
88 if
89 .I pidfd
90 refers to a specific thread
91 \[em]i.e.,
92 the
93 .I pidfd
94 was created through
95 .BR pidfd_open (2)
96 using the
97 .B PIDFD_THREAD
98 flag
99 or through
100 .BR clone3 (2)
101 using the
102 .B CLONE_PIDFD
103 flag together with the
104 .B CLONE_THREAD
105 flag\[em]
106 then passing
107 .I pidfd
108 to
109 .BR pidfd_send_signal (2)
110 and leaving the
111 .I flags
112 argument as
113 .B 0
114 will cause the signal to be sent to the specific thread referenced by the
115 .IR pidfd .
116 .TP
117 .BR PIDFD_SIGNAL_THREAD " (since Linux 6.9)"
118 .\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
119 Ensure that the signal is sent to the specific thread referenced by
120 .IR pidfd .
121 .TP
122 .BR PIDFD_SIGNAL_THREAD_GROUP " (since Linux 6.9)"
123 .\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
124 If
125 .I pidfd
126 refers to a thread-group leader,
127 ensure that the signal is sent to the thread-group,
128 even if
129 .I pidfd
130 was created to refer to a specific thread.
131 .TP
132 .BR PIDFD_SIGNAL_PROCESS_GROUP " (since Linux 6.9)"
133 .\" commit e1fb1dc08e73466830612bcf2f9f72180965c9ba
134 If
135 .I pidfd
136 refers to a process-group leader,
137 ensure that the signal is sent to the process-group,
138 even if
139 .I pidfd
140 was created to refer to a specific thread or to a thread-group leader.
141 .SH RETURN VALUE
142 On success,
143 .BR pidfd_send_signal ()
144 returns 0.
145 On error, \-1 is returned and
146 .I errno
147 is set to indicate the error.
148 .SH ERRORS
149 .TP
150 .B EBADF
151 .I pidfd
152 is not a valid PID file descriptor.
153 .TP
154 .B EINVAL
155 .I sig
156 is not a valid signal.
157 .TP
158 .B EINVAL
159 The calling process is not in a PID namespace from which it can
160 send a signal to the target process.
161 .TP
162 .B EINVAL
163 .I flags
164 is not valid.
165 .TP
166 .B EPERM
167 The calling process does not have permission to send the signal
168 to the target process.
169 .TP
170 .B EPERM
171 .I pidfd
172 doesn't refer to the calling process, and
173 .I info.si_code
174 is invalid (see
175 .BR rt_sigqueueinfo (2)).
176 .TP
177 .B ESRCH
178 The target process does not exist
179 (i.e., it has terminated and been waited on).
180 .SH STANDARDS
181 Linux.
182 .SH HISTORY
183 Linux 5.1.
184 .SH NOTES
185 .SS PID file descriptors
186 The
187 .I pidfd
188 argument is a PID file descriptor,
189 a file descriptor that refers to process.
190 Such a file descriptor can be obtained in any of the following ways:
191 .IP \[bu] 3
192 by opening a
193 .IR /proc/ pid
194 directory;
195 .IP \[bu]
196 using
197 .BR pidfd_open (2);
198 or
199 .IP \[bu]
200 via the PID file descriptor that is returned by a call to
201 .BR clone (2)
202 or
203 .BR clone3 (2)
204 that specifies the
205 .B CLONE_PIDFD
206 flag.
207 .P
208 The
209 .BR pidfd_send_signal ()
210 system call allows the avoidance of race conditions that occur
211 when using traditional interfaces (such as
212 .BR kill (2))
213 to signal a process.
214 The problem is that the traditional interfaces specify the target process
215 via a process ID (PID),
216 with the result that the sender may accidentally send a signal to
217 the wrong process if the originally intended target process
218 has terminated and its PID has been recycled for another process.
219 By contrast,
220 a PID file descriptor is a stable reference to a specific process;
221 if that process terminates,
222 .BR pidfd_send_signal ()
223 fails with the error
224 .BR ESRCH .
225 .SH EXAMPLES
226 .\" SRC BEGIN (pidfd_send_signal.c)
227 .EX
228 #define _GNU_SOURCE
229 #include <fcntl.h>
230 #include <limits.h>
231 #include <signal.h>
232 #include <stdio.h>
233 #include <stdlib.h>
234 #include <string.h>
235 #include <sys/syscall.h>
236 #include <unistd.h>
237 \&
238 static int
239 pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
240 unsigned int flags)
241 {
242 return syscall(SYS_pidfd_send_signal, pidfd, sig, info, flags);
243 }
244 \&
245 int
246 main(int argc, char *argv[])
247 {
248 int pidfd, sig;
249 char path[PATH_MAX];
250 siginfo_t info;
251 \&
252 if (argc != 3) {
253 fprintf(stderr, "Usage: %s <pid> <signal>\[rs]n", argv[0]);
254 exit(EXIT_FAILURE);
255 }
256 \&
257 sig = atoi(argv[2]);
258 \&
259 /* Obtain a PID file descriptor by opening the /proc/PID directory
260 of the target process. */
261 \&
262 snprintf(path, sizeof(path), "/proc/%s", argv[1]);
263 \&
264 pidfd = open(path, O_RDONLY);
265 if (pidfd == \-1) {
266 perror("open");
267 exit(EXIT_FAILURE);
268 }
269 \&
270 /* Populate a \[aq]siginfo_t\[aq] structure for use with
271 pidfd_send_signal(). */
272 \&
273 memset(&info, 0, sizeof(info));
274 info.si_code = SI_QUEUE;
275 info.si_signo = sig;
276 info.si_errno = 0;
277 info.si_uid = getuid();
278 info.si_pid = getpid();
279 info.si_value.sival_int = 1234;
280 \&
281 /* Send the signal. */
282 \&
283 if (pidfd_send_signal(pidfd, sig, &info, 0) == \-1) {
284 perror("pidfd_send_signal");
285 exit(EXIT_FAILURE);
286 }
287 \&
288 exit(EXIT_SUCCESS);
289 }
290 .EE
291 .\" SRC END
292 .SH SEE ALSO
293 .BR clone (2),
294 .BR kill (2),
295 .BR pidfd_open (2),
296 .BR rt_sigqueueinfo (2),
297 .BR sigaction (2),
298 .BR pid_namespaces (7),
299 .BR signal (7)