man2/pidfd_open.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_OPEN 2 2020-04-11 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pidfd_open \- obtain a file descriptor that refers to a process
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/types.h>
  31 .PP
  32 .BI "int pidfd_open(pid_t " pid ", unsigned int " flags );
  33 .fi
  34 .SH DESCRIPTION
  35 The
  36 .BR pidfd_open ()
  37 system call creates a file descriptor that refers to
  38 the process whose PID is specified in
  39 .IR pid .
  40 The file descriptor is returned as the function result;
  41 the close-on-exec flag is set on the file descriptor.
  42 .PP
  43 The
  44 .I flags
  45 argument is reserved for future use;
  46 currently, this argument must be specified as 0.
  47 .SH RETURN VALUE
  48 On success,
  49 .BR pidfd_open ()
  50 returns a file descriptor (a nonnegative integer).
  51 On error, \-1 is returned and
  52 .I errno
  53 is set to indicate the cause of the error.
  54 .SH ERRORS
  55 .TP
  56 .B EINVAL
  57 .I flags
  58 is not 0.
  59 .TP
  60 .B EINVAL
  61 .I pid
  62 is not valid.
  63 .TP
  64 .B EMFILE
  65 The per-process limit on the number of open file descriptors has been reached
  66 (see the description of
  67 .BR RLIMIT_NOFILE
  68 in
  69 .BR getrlimit (2)).
  70 .TP
  71 .B ENFILE
  72 The system-wide limit on the total number of open files has been reached.
  73 .TP
  74 .B ENODEV
  75 The anonymous inode filesystem is not available in this kernel.
  76 .TP
  77 .B ENOMEM
  78 Insufficient kernel memory was available.
  79 .TP
  80 .B ESRCH
  81 The process specified by
  82 .I pid
  83 does not exist.
  84 .SH VERSIONS
  85 .BR pidfd_open ()
  86 first appeared in Linux 5.3.
  87 .SH CONFORMING TO
  88 .BR pidfd_open ()
  89 is Linux specific.
  90 .SH NOTES
  91 Currently, there is no glibc wrapper for this system call; call it using
  92 .BR syscall (2).
  93 .PP
  94 The following code sequence can be used to obtain a file descriptor
  95 for the child of
  96 .BR fork (2):
  97 .PP
  98 .in +4n
  99 .EX
 100 pid = fork();
 101 if (pid > 0) {     /* If parent */
 102     pidfd = pidfd_open(pid, 0);
 103     ...
 104 }
 105 .EE
 106 .in
 107 .PP
 108 Even if the child has already terminated by the time of the
 109 .BR pidfd_open ()
 110 call, its PID will not have been recycled and the returned
 111 file descriptor will refer to the resulting zombie process.
 112 Note, however, that this is guaranteed only if the following
 113 conditions hold true:
 114 .IP * 3
 115 the disposition of
 116 .BR SIGCHLD
 117 has not been explicitly set to
 118 .BR SIG_IGN
 119 (see
 120 .BR sigaction (2));
 121 .IP *
 122 the
 123 .BR SA_NOCLDWAIT
 124 flag was not specified while establishing a handler for
 125 .BR SIGCHLD
 126 or while setting the disposition of that signal to
 127 .BR SIG_DFL
 128 (see
 129 .BR sigaction (2));
 130 and
 131 .IP *
 132 the zombie process was not reaped elsewhere in the program
 133 (e.g., either by an asynchronously executed signal handler or by
 134 .BR wait (2)
 135 or similar in another thread).
 136 .PP
 137 If any of these conditions does not hold,
 138 then the child process (along with a PID file descriptor that refers to it)
 139 should instead be created using
 140 .BR clone (2)
 141 with the
 142 .BR CLONE_PIDFD
 143 flag.
 144 .\"
 145 .SS Use cases for PID file descriptors
 146 .PP
 147 A PID file descriptor returned by
 148 .BR pidfd_open ()
 149 (or by
 150 .BR clone (2)
 151 with the
 152 .BR CLONE_PID
 153 flag) can be used for the following purposes:
 154 .IP * 3
 155 The
 156 .BR pidfd_send_signal (2)
 157 system call can be used to send a signal to the process referred to by
 158 a PID file descriptor.
 159 .IP *
 160 A PID file descriptor can be monitored using
 161 .BR poll (2),
 162 .BR select (2),
 163 and
 164 .BR epoll (7).
 165 When the process that it refers to terminates,
 166 these interfaces indicate the file descriptor as readable.
 167 Note, however, that in the current implementation,
 168 nothing can be read from the file descriptor
 169 .RB ( read (2)
 170 on the file descriptor fails with the error
 171 .BR EINVAL ).
 172 .IP *
 173 If the PID file descriptor refers to a child of the calling process,
 174 then it can be waited on using
 175 .BR waitid (2).
 176 .IP *
 177 The
 178 .BR pidfd_getfd (2)
 179 system call can be used to obtain a duplicate of a file descriptor
 180 of another process referred to by a PID file descriptor.
 181 .PP
 182 The
 183 .BR pidfd_open ()
 184 system call is the preferred way of obtaining a PID file descriptor
 185 for an already existing process.
 186 The alternative is to obtain a file descriptor by opening a
 187 .I /proc/[pid]
 188 directory.
 189 However, the latter technique is possible only if the
 190 .BR proc (5)
 191 filesystem is mounted;
 192 furthermore, the file descriptor obtained in this way is
 193 .I not
 194 pollable and can't be waited on with
 195 .BR waitid (2).
 196 .SH EXAMPLE
 197 The program below opens a PID file descriptor for the
 198 process whose PID is specified as its command-line argument.
 199 It then uses
 200 .BR poll (2)
 201 to monitor the file descriptor for process exit, as indicated by an
 202 .BR EPOLLIN
 203 event.
 204 .\"
 205 .SS Program source
 206 \&
 207 .nf
 208 #define _GNU_SOURCE
 209 #include <sys/types.h>
 210 #include <sys/syscall.h>
 211 #include <unistd.h>
 212 #include <poll.h>
 213 #include <stdlib.h>
 214 #include <stdio.h>
 215
 216 #ifndef __NR_pidfd_open
 217 #define __NR_pidfd_open 434   /* System call # on most architectures */
 218 #endif
 219
 220 static int
 221 pidfd_open(pid_t pid, unsigned int flags)
 222 {
 223     return syscall(__NR_pidfd_open, pid, flags);
 224 }
 225
 226 int
 227 main(int argc, char *argv[])
 228 {
 229     struct pollfd pollfd;
 230     int pidfd, ready;
 231
 232     if (argc != 2) {
 233         fprintf(stderr, "Usage: %s <pid>\en", argv[0]);
 234         exit(EXIT_SUCCESS);
 235     }
 236
 237     pidfd = pidfd_open(atoi(argv[1]), 0);
 238     if (pidfd == \-1) {
 239         perror("pidfd_open");
 240         exit(EXIT_FAILURE);
 241     }
 242
 243     pollfd.fd = pidfd;
 244     pollfd.events = POLLIN;
 245
 246     ready = poll(&pollfd, 1, \-1);
 247     if (ready == \-1) {
 248         perror("poll");
 249         exit(EXIT_FAILURE);
 250     }
 251
 252     printf("Events (0x%x): POLLIN is %sset\en", pollfd.revents,
 253             (pollfd.revents & POLLIN) ? "" : "not ");
 254
 255     exit(EXIT_SUCCESS);
 256 }
 257 .fi
 258 .SH SEE ALSO
 259 .BR clone (2),
 260 .BR kill (2),
 261 .BR pidfd_getfd (2),
 262 .BR pidfd_send_signal (2),
 263 .BR poll (2),
 264 .BR select (2),
 265 .BR waitid (2),
 266 .BR epoll (7)