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