pidfd_send_signal(2) — Linux manual pages

Linux manual pages	Section 2

Name

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

Synopsis

#include <signal.h>

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

	Note
	There is no glibc wrapper for this system call; see NOTES.

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

VERSIONS

pidfd_send_signal() first appeared in Linux 5.1.

CONFORMING TO

pidfd_send_signal() is Linux specific.

NOTES

Glibc does not provide a 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.

EXAMPLES

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

COLOPHON

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

  Copyright (c) 2019 by Michael Kerrisk <mtk.manpagesgmail.com>

%%%LICENSE_START(VERBATIM)
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Since the Linux kernel and libraries are constantly changing, this
manual page may be incorrect or out-of-date.  The author(s) assume no
responsibility for errors or omissions, or for damages resulting from
the use of the information contained herein.  The author(s) may not
have taken the same level of care in the production of this manual,
which is licensed free of charge, as they might when working
professionally.

Formatted or processed versions of this manual, if unaccompanied by
the source, must acknowledge the copyright and authors of this work.
%%%LICENSE_END