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