pidfd_send_signal - send a signal to a process specified by a file descriptor
Standard C library (
libc,
-lc)
#include <linux/signal.h> /* Definition of SIG* constants */
#include <signal.h> /* Definition of SI_* constants */
#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_pidfd_send_signal, int pidfd, int sig,
siginfo_t *_Nullable info, unsigned int flags);
Note: glibc provides no wrapper for
pidfd_send_signal(),
necessitating the use of
syscall(2).
The
pidfd_send_signal() system call sends the signal
sig to the
target process referred to by
pidfd, a PID file descriptor that refers
to a process.
If the
info argument points to a
siginfo_t buffer, that buffer
should be populated as described in
rt_sigqueueinfo(2).
If the
info argument is a NULL pointer, this is equivalent to specifying
a pointer to a
siginfo_t buffer whose fields match the values that are
implicitly supplied when a signal is sent using
kill(2):
- •
-
si_signo is set to the signal number;
- •
-
si_errno is set to 0;
- •
-
si_code is set to SI_USER;
- •
-
si_pid is set to the caller's PID; and
- •
-
si_uid is set to the caller's real user ID.
The calling process must either be in the same PID namespace as the process
referred to by
pidfd, or be in an ancestor of that namespace.
The
flags argument is reserved for future use; currently, this argument
must be specified as 0.
On success,
pidfd_send_signal() returns 0. On error, -1 is returned and
errno is set to indicate the error.
- EBADF
-
pidfd is not a valid PID file descriptor.
- EINVAL
-
sig is not a valid signal.
- EINVAL
- The calling process is not in a PID namespace from which it
can send a signal to the target process.
- EINVAL
-
flags is not 0.
- EPERM
- The calling process does not have permission to send the
signal to the target process.
- EPERM
-
pidfd doesn't refer to the calling process, and
info.si_code is invalid (see rt_sigqueueinfo(2)).
- ESRCH
- The target process does not exist (i.e., it has terminated
and been waited on).
pidfd_send_signal() first appeared in Linux 5.1.
pidfd_send_signal() is Linux specific.
The
pidfd argument is a PID file descriptor, a file descriptor that
refers to process. Such a file descriptor can be obtained in any of the
following ways:
- •
- by opening a /proc/pid directory;
- •
- using pidfd_open(2); or
- •
- via the PID file descriptor that is returned by a call to
clone(2) or clone3(2) that specifies the CLONE_PIDFD
flag.
The
pidfd_send_signal() system call allows the avoidance of race
conditions that occur when using traditional interfaces (such as
kill(2)) to signal a process. The problem is that the traditional
interfaces specify the target process via a process ID (PID), with the result
that the sender may accidentally send a signal to the wrong process if the
originally intended target process has terminated and its PID has been
recycled for another process. By contrast, a PID file descriptor is a stable
reference to a specific process; if that process terminates,
pidfd_send_signal() fails with the error
ESRCH.
#define _GNU_SOURCE
#include <fcntl.h>
#include <limits.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/syscall.h>
#include <unistd.h>
static int
pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
unsigned int flags)
{
return syscall(SYS_pidfd_send_signal, pidfd, sig, info, flags);
}
int
main(int argc, char *argv[])
{
int pidfd, sig;
char path[PATH_MAX];
siginfo_t info;
if (argc != 3) {
fprintf(stderr, "Usage: %s <pid> <signal>\n", argv[0]);
exit(EXIT_FAILURE);
}
sig = atoi(argv[2]);
/* Obtain a PID file descriptor by opening the /proc/PID directory
of the target process. */
snprintf(path, sizeof(path), "/proc/%s", argv[1]);
pidfd = open(path, O_RDONLY);
if (pidfd == -1) {
perror("open");
exit(EXIT_FAILURE);
}
/* Populate a 'siginfo_t' structure for use with
pidfd_send_signal(). */
memset(&info, 0, sizeof(info));
info.si_code = SI_QUEUE;
info.si_signo = sig;
info.si_errno = 0;
info.si_uid = getuid();
info.si_pid = getpid();
info.si_value.sival_int = 1234;
/* Send the signal. */
if (pidfd_send_signal(pidfd, sig, &info, 0) == -1) {
perror("pidfd_send_signal");
exit(EXIT_FAILURE);
}
exit(EXIT_SUCCESS);
}
clone(2),
kill(2),
pidfd_open(2),
rt_sigqueueinfo(2),
sigaction(2),
pid_namespaces(7),
signal(7)