1PIDFD_SEND_SIGNAL(2) Linux Programmer's Manual PIDFD_SEND_SIGNAL(2)
2
6 pidfd_send_signal - send a signal to a process specified by a file de‐
7 scriptor
8
10 #include <linux/signal.h> /* Definition of SIG* constants */
11 #include <signal.h> /* Definition of SI_* constants */
12 #include <sys/syscall.h> /* Definition of SYS_* constants */
13 #include <unistd.h>
14 int syscall(SYS_pidfd_send_signal, int pidfd, int sig, siginfo_t *info,
16 unsigned int flags);
17 Note: glibc provides no wrapper for pidfd_send_signal(), necessitating
19 the use of syscall(2).
20
22 The pidfd_send_signal() system call sends the signal sig to the target
23 process referred to by pidfd, a PID file descriptor that refers to a
24 process.
25 If the info argument points to a siginfo_t buffer, that buffer should
27 be populated as described in rt_sigqueueinfo(2).
28 If the info argument is a NULL pointer, this is equivalent to specify‐
30 ing a pointer to a siginfo_t buffer whose fields match the values that
31 are implicitly supplied when a signal is sent using kill(2):
32 * si_signo is set to the signal number;
34 * si_errno is set to 0;
35 * si_code is set to SI_USER;
36 * si_pid is set to the caller's PID; and
37 * si_uid is set to the caller's real user ID.
38 The calling process must either be in the same PID namespace as the
40 process referred to by pidfd, or be in an ancestor of that namespace.
41 The flags argument is reserved for future use; currently, this argument
43 must be specified as 0.
44
46 On success, pidfd_send_signal() returns 0. On error, -1 is returned
47 and errno is set to indicate the error.
48
50 EBADF pidfd is not a valid PID file descriptor.
51 EINVAL sig is not a valid signal.
53 EINVAL The calling process is not in a PID namespace from which it can
55 send a signal to the target process.
56 EINVAL flags is not 0.
58 EPERM The calling process does not have permission to send the signal
60 to the target process.
61 EPERM pidfd doesn't refer to the calling process, and info.si_code is
63 invalid (see rt_sigqueueinfo(2)).
64 ESRCH The target process does not exist (i.e., it has terminated and
66 been waited on).
67
69 pidfd_send_signal() first appeared in Linux 5.1.
70
72 pidfd_send_signal() is Linux specific.
73
75 PID file descriptors
76 The pidfd argument is a PID file descriptor, a file descriptor that
77 refers to process. Such a file descriptor can be obtained in any of
78 the following ways:
79 * by opening a /proc/[pid] directory;
81 * using pidfd_open(2); or
83 * via the PID file descriptor that is returned by a call to clone(2)
85 or clone3(2) that specifies the CLONE_PIDFD flag.
86 The pidfd_send_signal() system call allows the avoidance of race condi‐
88 tions that occur when using traditional interfaces (such as kill(2)) to
89 signal a process. The problem is that the traditional interfaces spec‐
90 ify the target process via a process ID (PID), with the result that the
91 sender may accidentally send a signal to the wrong process if the orig‐
92 inally intended target process has terminated and its PID has been re‐
93 cycled for another process. By contrast, a PID file descriptor is a
94 stable reference to a specific process; if that process terminates,
95 pidfd_send_signal() fails with the error ESRCH.
96
98 #define _GNU_SOURCE
99 #include <limits.h>
100 #include <signal.h>
101 #include <fcntl.h>
102 #include <stdio.h>
103 #include <string.h>
104 #include <stdlib.h>
105 #include <unistd.h>
106 #include <sys/syscall.h>
107 #ifndef __NR_pidfd_send_signal
109 #define __NR_pidfd_send_signal 424
110 #endif
111 static int
113 pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
114 unsigned int flags)
115 {
116 return syscall(__NR_pidfd_send_signal, pidfd, sig, info, flags);
117 }
118 int
120 main(int argc, char *argv[])
121 {
122 siginfo_t info;
123 char path[PATH_MAX];
124 int pidfd, sig;
125 if (argc != 3) {
127 fprintf(stderr, "Usage: %s <pid> <signal>\n", argv[0]);
128 exit(EXIT_FAILURE);
129 }
130 sig = atoi(argv[2]);
132 /* Obtain a PID file descriptor by opening the /proc/PID directory
134 of the target process. */
135 snprintf(path, sizeof(path), "/proc/%s", argv[1]);
137 pidfd = open(path, O_RDONLY);
139 if (pidfd == -1) {
140 perror("open");
141 exit(EXIT_FAILURE);
142 }
143 /* Populate a 'siginfo_t' structure for use with
145 pidfd_send_signal(). */
146 memset(&info, 0, sizeof(info));
148 info.si_code = SI_QUEUE;
149 info.si_signo = sig;
150 info.si_errno = 0;
151 info.si_uid = getuid();
152 info.si_pid = getpid();
153 info.si_value.sival_int = 1234;
154 /* Send the signal. */
156 if (pidfd_send_signal(pidfd, sig, &info, 0) == -1) {
158 perror("pidfd_send_signal");
159 exit(EXIT_FAILURE);
160 }
161 exit(EXIT_SUCCESS);
163 }
164
166 clone(2), kill(2), pidfd_open(2), rt_sigqueueinfo(2), sigaction(2),
167 pid_namespaces(7), signal(7)
168
170 This page is part of release 5.13 of the Linux man-pages project. A
171 description of the project, information about reporting bugs, and the
172 latest version of this page, can be found at
173 https://www.kernel.org/doc/man-pages/.
174Linux 2021-03-22 PIDFD_SEND_SIGNAL(2)