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