HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |NOTES |EXAMPLES |SEE ALSO |COLOPHON | |
pidfd_send_signal(2) System Calls Manualpidfd_send_signal(2)pidfd_send_signal - send a signal to a process specified by a file descriptor
Standard C library (libc,-lc)
#include <linux/signal.h>/* Definition ofSIG*constants */#include <signal.h>/* Definition ofSI_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>int syscall(SYS_pidfd_send_signal, intpidfd, intsig,siginfo_t *_Nullableinfo, unsigned intflags);Note: glibc provides no wrapper forpidfd_send_signal(), necessitating the use ofsyscall(2).
Thepidfd_send_signal() system call sends the signalsig to the target process referred to bypidfd, a PID file descriptor that refers to a process. If theinfo argument points to asiginfo_t buffer, that buffer should be populated as described inrt_sigqueueinfo(2). If theinfo argument is a null pointer, this is equivalent to specifying a pointer to asiginfo_t buffer whose fields match the values that are implicitly supplied when a signal is sent usingkill(2): •si_signo is set to the signal number; •si_errno is set to 0; •si_code is set toSI_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 bypidfd, or be in an ancestor of that namespace. Theflags 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 anderrno is set to indicate the error.
EBADFpidfd is not a valid PID file descriptor.EINVALsig is not a valid signal.EINVALThe calling process is not in a PID namespace from which it can send a signal to the target process.EINVALflags is not 0.EPERMThe calling process does not have permission to send the signal to the target process.EPERMpidfd doesn't refer to the calling process, andinfo.si_code is invalid (seert_sigqueueinfo(2)).ESRCHThe target process does not exist (i.e., it has terminated and been waited on).
Linux.
Linux 5.1.
PID file descriptors Thepidfd 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; • usingpidfd_open(2); or • via the PID file descriptor that is returned by a call toclone(2) orclone3(2) that specifies theCLONE_PIDFDflag. Thepidfd_send_signal() system call allows the avoidance of race conditions that occur when using traditional interfaces (such askill(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 errorESRCH.
#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)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17pidfd_send_signal(2)Pages that refer to this page:pgrep(1), kill(2), pidfd_open(2), rt_sigqueueinfo(2), sigaction(2), syscalls(2), sd_event_add_child(3), signal(7), system_data_types(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |