# pidfd_send_signal

## NAME



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


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



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


## STANDARDS



           Linux.
    


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


## 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);
           }
    


* * *