Manpages - pidfd_send_signal.2

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

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

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

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

This page is part of release 5.13 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/.