pidfd_send_signal(2) System Calls Manual pidfd_send_signal(2)
NAME
pidfd_send_signal - send a signal to a process specified by a file de-
scriptor
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#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).
DESCRIPTION
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 specify-
ing 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.
RETURN VALUE
On success, pidfd_send_signal() returns 0. On error, -1 is returned
and errno is set to indicate the error.
ERRORS
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).
VERSIONS
pidfd_send_signal() first appeared in Linux 5.1.
STANDARDS
pidfd_send_signal() is Linux specific.
NOTES
PID file descriptors
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 condi-
tions that occur when using traditional interfaces (such as kill(2)) to
signal a process. The problem is that the traditional interfaces spec-
ify 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 orig-
inally intended target process has terminated and its PID has been re-
cycled 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.
EXAMPLES
#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);
}
SEE ALSO
clone(2), kill(2), pidfd_open(2), rt_sigqueueinfo(2), sigaction(2),
pid_namespaces(7), signal(7)
Linux man-pages 6.03 2023-02-05 pidfd_send_signal(2)
Generated by dwww version 1.15 on Thu Jun 27 09:35:33 CEST 2024.