man2/pidfd_send_signal.2

   1 .\" Copyright (c) 2019 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH PIDFD_SEND_SIGNAL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pidfd_send_signal \- send a signal to a process specified by a file descriptor
  28 .SH SYNOPSIS
  29 .nf
  30 .BR "#include <linux/signal.h>" "     /* Definition of " SIG* " constants */"
  31 .BR "#include <signal.h>" "           /* Definition of " SI_* " constants */"
  32 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  33 .B #include <unistd.h>
  34 .PP
  35 .BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig \
  36 ", siginfo_t *" info ,
  37 .BI "                      unsigned int " flags );
  38 .fi
  39 .PP
  40 .IR Note :
  41 glibc provides no wrapper for
  42 .BR pidfd_send_signal (),
  43 necessitating the use of
  44 .BR syscall (2).
  45 .SH DESCRIPTION
  46 The
  47 .BR pidfd_send_signal ()
  48 system call sends the signal
  49 .I sig
  50 to the target process referred to by
  51 .IR pidfd ,
  52 a PID file descriptor that refers to a process.
  53 .\" See the very detailed commit message for kernel commit
  54 .\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad
  55 .PP
  56 If the
  57 .I info
  58 argument points to a
  59 .I siginfo_t
  60 buffer, that buffer should be populated as described in
  61 .BR rt_sigqueueinfo (2).
  62 .PP
  63 If the
  64 .I info
  65 argument is a NULL pointer,
  66 this is equivalent to specifying a pointer to a
  67 .I siginfo_t
  68 buffer whose fields match the values that are
  69 implicitly supplied when a signal is sent using
  70 .BR kill (2):
  71 .PP
  72 .PD 0
  73 .IP * 3
  74 .I si_signo
  75 is set to the signal number;
  76 .IP *
  77 .I si_errno
  78 is set to 0;
  79 .IP *
  80 .I si_code
  81 is set to
  82 .BR SI_USER ;
  83 .IP *
  84 .I si_pid
  85 is set to the caller's PID; and
  86 .IP *
  87 .I si_uid
  88 is set to the caller's real user ID.
  89 .PD
  90 .PP
  91 The calling process must either be in the same PID namespace as the
  92 process referred to by
  93 .IR pidfd ,
  94 or be in an ancestor of that namespace.
  95 .PP
  96 The
  97 .I flags
  98 argument is reserved for future use;
  99 currently, this argument must be specified as 0.
 100 .SH RETURN VALUE
 101 On success,
 102 .BR pidfd_send_signal ()
 103 returns 0.
 104 On error, \-1 is returned and
 105 .I errno
 106 is set to indicate the error.
 107 .SH ERRORS
 108 .TP
 109 .B EBADF
 110 .I pidfd
 111 is not a valid PID file descriptor.
 112 .TP
 113 .B EINVAL
 114 .I sig
 115 is not a valid signal.
 116 .TP
 117 .B EINVAL
 118 The calling process is not in a PID namespace from which it can
 119 send a signal to the target process.
 120 .TP
 121 .B EINVAL
 122 .I flags
 123 is not 0.
 124 .TP
 125 .B EPERM
 126 The calling process does not have permission to send the signal
 127 to the target process.
 128 .TP
 129 .B EPERM
 130 .I pidfd
 131 doesn't refer to the calling process, and
 132 .IR info.si_code
 133 is invalid (see
 134 .BR rt_sigqueueinfo (2)).
 135 .TP
 136 .B ESRCH
 137 The target process does not exist
 138 (i.e., it has terminated and been waited on).
 139 .SH VERSIONS
 140 .BR pidfd_send_signal ()
 141 first appeared in Linux 5.1.
 142 .SH CONFORMING TO
 143 .BR pidfd_send_signal ()
 144 is Linux specific.
 145 .SH NOTES
 146 .SS PID file descriptors
 147 The
 148 .I pidfd
 149 argument is a PID file descriptor,
 150 a file descriptor that refers to  process.
 151 Such a file descriptor can be obtained in any of the following ways:
 152 .IP * 3
 153 by opening a
 154 .IR /proc/[pid]
 155 directory;
 156 .IP *
 157 using
 158 .BR pidfd_open (2);
 159 or
 160 .IP *
 161 via the PID file descriptor that is returned by a call to
 162 .BR clone (2)
 163 or
 164 .BR clone3 (2)
 165 that specifies the
 166 .BR CLONE_PIDFD
 167 flag.
 168 .PP
 169 The
 170 .BR pidfd_send_signal ()
 171 system call allows the avoidance of race conditions that occur
 172 when using traditional interfaces (such as
 173 .BR kill (2))
 174 to signal a process.
 175 The problem is that the traditional interfaces specify the target process
 176 via a process ID (PID),
 177 with the result that the sender may accidentally send a signal to
 178 the wrong process if the originally intended target process
 179 has terminated and its PID has been recycled for another process.
 180 By contrast,
 181 a PID file descriptor is a stable reference to a specific process;
 182 if that process terminates,
 183 .BR pidfd_send_signal ()
 184 fails with the error
 185 .BR ESRCH .
 186 .SH EXAMPLES
 187 .EX
 188 #define _GNU_SOURCE
 189 #include <limits.h>
 190 #include <signal.h>
 191 #include <fcntl.h>
 192 #include <stdio.h>
 193 #include <string.h>
 194 #include <stdlib.h>
 195 #include <unistd.h>
 196 #include <sys/syscall.h>
 197
 198 #ifndef __NR_pidfd_send_signal
 199 #define __NR_pidfd_send_signal 424
 200 #endif
 201
 202 static int
 203 pidfd_send_signal(int pidfd, int sig, siginfo_t *info,
 204         unsigned int flags)
 205 {
 206     return syscall(__NR_pidfd_send_signal, pidfd, sig, info, flags);
 207 }
 208
 209 int
 210 main(int argc, char *argv[])
 211 {
 212     siginfo_t info;
 213     char path[PATH_MAX];
 214     int pidfd, sig;
 215
 216     if (argc != 3) {
 217         fprintf(stderr, "Usage: %s <pid> <signal>\en", argv[0]);
 218         exit(EXIT_FAILURE);
 219     }
 220
 221     sig = atoi(argv[2]);
 222
 223     /* Obtain a PID file descriptor by opening the /proc/PID directory
 224        of the target process. */
 225
 226     snprintf(path, sizeof(path), "/proc/%s", argv[1]);
 227
 228     pidfd = open(path, O_RDONLY);
 229     if (pidfd == \-1) {
 230         perror("open");
 231         exit(EXIT_FAILURE);
 232     }
 233
 234     /* Populate a \(aqsiginfo_t\(aq structure for use with
 235        pidfd_send_signal(). */
 236
 237     memset(&info, 0, sizeof(info));
 238     info.si_code = SI_QUEUE;
 239     info.si_signo = sig;
 240     info.si_errno = 0;
 241     info.si_uid = getuid();
 242     info.si_pid = getpid();
 243     info.si_value.sival_int = 1234;
 244
 245     /* Send the signal. */
 246
 247     if (pidfd_send_signal(pidfd, sig, &info, 0) == \-1) {
 248         perror("pidfd_send_signal");
 249         exit(EXIT_FAILURE);
 250     }
 251
 252     exit(EXIT_SUCCESS);
 253 }
 254 .EE
 255 .SH SEE ALSO
 256 .BR clone (2),
 257 .BR kill (2),
 258 .BR pidfd_open (2),
 259 .BR rt_sigqueueinfo (2),
 260 .BR sigaction (2),
 261 .BR pid_namespaces (7),
 262 .BR signal (7)