man2/pidfd_open.2

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