pidfd_send_signal(2)

1PIDFD_SEND_SIGNAL(2)       Linux Programmer's Manual      PIDFD_SEND_SIGNAL(2)
2
3
4

NAME

6       pidfd_send_signal  - send a signal to a process specified by a file de‐
7       scriptor
8

SYNOPSIS

10       #include <signal.h>
11
12       int pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
13                             unsigned int flags);
14

DESCRIPTION

16       The pidfd_send_signal() system call sends the signal sig to the  target
17       process  referred  to  by pidfd, a PID file descriptor that refers to a
18       process.
19
20       If the info argument points to a siginfo_t buffer, that  buffer  should
21       be populated as described in rt_sigqueueinfo(2).
22
23       If  the info argument is a NULL pointer, this is equivalent to specify‐
24       ing a pointer to a siginfo_t buffer whose fields match the values  that
25       are implicitly supplied when a signal is sent using kill(2):
26
27       *  si_signo is set to the signal number;
28       *  si_errno is set to 0;
29       *  si_code is set to SI_USER;
30       *  si_pid is set to the caller's PID; and
31       *  si_uid is set to the caller's real user ID.
32
33       The  calling  process  must  either be in the same PID namespace as the
34       process referred to by pidfd, or be in an ancestor of that namespace.
35
36       The flags argument is reserved for future use; currently, this argument
37       must be specified as 0.
38

RETURN VALUE

40       On  success,  pidfd_send_signal()  returns 0.  On error, -1 is returned
41       and errno is set to indicate the cause of the error.
42

ERRORS

44       EBADF  pidfd is not a valid PID file descriptor.
45
46       EINVAL sig is not a valid signal.
47
48       EINVAL The calling process is not in a PID namespace from which it  can
49              send a signal to the target process.
50
51       EINVAL flags is not 0.
52
53       EPERM  The  calling process does not have permission to send the signal
54              to the target process.
55
56       EPERM  pidfd doesn't refer to the calling process, and info.si_code  is
57              invalid (see rt_sigqueueinfo(2)).
58
59       ESRCH  The  target  process does not exist (i.e., it has terminated and
60              been waited on).
61

VERSIONS

63       pidfd_send_signal() first appeared in Linux 5.1.
64

CONFORMING TO

66       pidfd_send_signal() is Linux specific.
67

NOTES

69       Currently, there is no glibc wrapper for this system call; call it  us‐
70       ing syscall(2).
71
72   PID file descriptors
73       The  pidfd  argument  is  a PID file descriptor, a file descriptor that
74       refers to  process.  Such a file descriptor can be obtained in  any  of
75       the following ways:
76
77       *  by opening a /proc/[pid] directory;
78
79       *  using pidfd_open(2); or
80
81       *  via  the  PID file descriptor that is returned by a call to clone(2)
82          or clone3(2) that specifies the CLONE_PIDFD flag.
83
84       The pidfd_send_signal() system call allows the avoidance of race condi‐
85       tions that occur when using traditional interfaces (such as kill(2)) to
86       signal a process.  The problem is that the traditional interfaces spec‐
87       ify the target process via a process ID (PID), with the result that the
88       sender may accidentally send a signal to the wrong process if the orig‐
89       inally  intended target process has terminated and its PID has been re‐
90       cycled for another process.  By contrast, a PID file  descriptor  is  a
91       stable  reference  to  a  specific process; if that process terminates,
92       pidfd_send_signal() fails with the error ESRCH.
93

EXAMPLES

95       #define _GNU_SOURCE
96       #include <limits.h>
97       #include <signal.h>
98       #include <fcntl.h>
99       #include <stdio.h>
100       #include <string.h>
101       #include <stdlib.h>
102       #include <unistd.h>
103       #include <sys/syscall.h>
104
105       #ifndef __NR_pidfd_send_signal
106       #define __NR_pidfd_send_signal 424
107       #endif
108
109       static int
110       pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
111               unsigned int flags)
112       {
113           return syscall(__NR_pidfd_send_signal, pidfd, sig, info, flags);
114       }
115
116       int
117       main(int argc, char *argv[])
118       {
119           siginfo_t info;
120           char path[PATH_MAX];
121           int pidfd, sig;
122
123           if (argc != 3) {
124               fprintf(stderr, "Usage: %s <pid> <signal>\n", argv[0]);
125               exit(EXIT_FAILURE);
126           }
127
128           sig = atoi(argv[2]);
129
130           /* Obtain a PID file descriptor by opening the /proc/PID directory
131              of the target process */
132
133           snprintf(path, sizeof(path), "/proc/%s", argv[1]);
134
135           pidfd = open(path, O_RDONLY);
136           if (pidfd == -1) {
137               perror("open");
138               exit(EXIT_FAILURE);
139           }
140
141           /* Populate a 'siginfo_t' structure for use with
142              pidfd_send_signal() */
143
144           memset(&info, 0, sizeof(info));
145           info.si_code = SI_QUEUE;
146           info.si_signo = sig;
147           info.si_errno = 0;
148           info.si_uid = getuid();
149           info.si_pid = getpid();
150           info.si_value.sival_int = 1234;
151
152           /* Send the signal */
153
154           if (pidfd_send_signal(pidfd, sig, &info, 0) == -1) {
155               perror("pidfd_send_signal");
156               exit(EXIT_FAILURE);
157           }
158
159           exit(EXIT_SUCCESS);
160       }
161

COLOPHON

167       This  page  is  part of release 5.10 of the Linux man-pages project.  A
168       description of the project, information about reporting bugs,  and  the
169       latest     version     of     this    page,    can    be    found    at
170       https://www.kernel.org/doc/man-pages/.
171
172
173
174Linux                             2020-06-09              PIDFD_SEND_SIGNAL(2)