pidfd_send_signal(2)

1pidfd_send_signal(2)          System Calls 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

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <linux/signal.h>     /* Definition of SIG* constants */
14       #include <signal.h>           /* Definition of SI_* constants */
15       #include <sys/syscall.h>      /* Definition of SYS_* constants */
16       #include <unistd.h>
17
18       int syscall(SYS_pidfd_send_signal, int pidfd, int sig,
19                   siginfo_t *_Nullable info, unsigned int flags);
20
21       Note: glibc provides no wrapper for pidfd_send_signal(),  necessitating
22       the use of syscall(2).
23

DESCRIPTION

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

RETURN VALUE

49       On success, pidfd_send_signal() returns 0.  On error,  -1  is  returned
50       and errno is set to indicate the error.
51

ERRORS

53       EBADF  pidfd is not a valid PID file descriptor.
54
55       EINVAL sig is not a valid signal.
56
57       EINVAL The  calling process is not in a PID namespace from which it can
58              send a signal to the target process.
59
60       EINVAL flags is not 0.
61
62       EPERM  The calling process does not have permission to send the  signal
63              to the target process.
64
65       EPERM  pidfd  doesn't refer to the calling process, and info.si_code is
66              invalid (see rt_sigqueueinfo(2)).
67
68       ESRCH  The target process does not exist (i.e., it has  terminated  and
69              been waited on).
70

STANDARDS

72       Linux.
73

HISTORY

75       Linux 5.1.
76

NOTES

78   PID file descriptors
79       The  pidfd  argument  is  a PID file descriptor, a file descriptor that
80       refers to  process.  Such a file descriptor can be obtained in  any  of
81       the following ways:
82
83       •  by opening a /proc/pid directory;
84
85       •  using pidfd_open(2); or
86
87       •  via  the  PID file descriptor that is returned by a call to clone(2)
88          or clone3(2) that specifies the CLONE_PIDFD flag.
89
90       The pidfd_send_signal() system call allows the avoidance of race condi‐
91       tions that occur when using traditional interfaces (such as kill(2)) to
92       signal a process.  The problem is that the traditional interfaces spec‐
93       ify the target process via a process ID (PID), with the result that the
94       sender may accidentally send a signal to the wrong process if the orig‐
95       inally  intended target process has terminated and its PID has been re‐
96       cycled for another process.  By contrast, a PID file  descriptor  is  a
97       stable  reference  to  a  specific process; if that process terminates,
98       pidfd_send_signal() fails with the error ESRCH.
99

EXAMPLES

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