NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | CONFORMING TO | NOTES | EXAMPLE | SEE ALSO | COLOPHON

PIDFD_SEND_SIGNAL(2)      Linux Programmer's Manual     PIDFD_SEND_SIGNAL(2)

NAME         top

       pidfd_send_signal  -  send  a signal to a process specified by a file
       descriptor

SYNOPSIS         top

       #include <signal.h>

       int pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
                             unsigned int flags);

DESCRIPTION         top

       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.

RETURN VALUE         top

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

ERRORS         top

       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         top

       pidfd_send_signal() first appeared in Linux 5.1.

CONFORMING TO         top

       pidfd_send_signal() is Linux specific.

NOTES         top

       Currently, there is no glibc wrapper for this system call; call it
       using syscall(2).

   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
       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.

EXAMPLE         top

       #define _GNU_SOURCE
       #include <limits.h>
       #include <signal.h>
       #include <fcntl.h>
       #include <stdio.h>
       #include <string.h>
       #include <stdlib.h>
       #include <unistd.h>
       #include <sys/syscall.h>

       #ifndef __NR_pidfd_send_signal
       #define __NR_pidfd_send_signal 424
       #endif

       static int
       pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
               unsigned int flags)
       {
           return syscall(__NR_pidfd_send_signal, pidfd, sig, info, flags);
       }

       int
       main(int argc, char *argv[])
       {
           siginfo_t info;
           char path[PATH_MAX];
           int pidfd, sig;

           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         top

       clone(2), kill(2), pidfd_open(2), rt_sigqueueinfo(2), sigaction(2),
       pid_namespaces(7), signal(7)

COLOPHON         top

       This page is part of release 5.04 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at
       https://www.kernel.org/doc/man-pages/.

Linux                            2019-09-19             PIDFD_SEND_SIGNAL(2)

Pages that refer to this page: kill(2)pidfd_open(2)rt_sigqueueinfo(2)sigaction(2)syscalls(2)signal(7)