man2/pidfd_getfd.2

   1 .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH PIDFD_GETFD 2 2022-09-09 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 pidfd_getfd \- obtain a duplicate of another process's file descriptor
   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_getfd, int " pidfd ", int " targetfd ,
  17 .BI "            unsigned int " flags );
  18 .fi
  19 .PP
  20 .IR Note :
  21 glibc provides no wrapper for
  22 .BR pidfd_getfd (),
  23 necessitating the use of
  24 .BR syscall (2).
  25 .SH DESCRIPTION
  26 The
  27 .BR pidfd_getfd ()
  28 system call allocates a new file descriptor in the calling process.
  29 This new file descriptor is a duplicate of an existing file descriptor,
  30 .IR targetfd ,
  31 in the process referred to by the PID file descriptor
  32 .IR pidfd .
  33 .PP
  34 The duplicate file descriptor refers to the same open file description (see
  35 .BR open (2))
  36 as the original file descriptor in the process referred to by
  37 .IR pidfd .
  38 The two file descriptors thus share file status flags and file offset.
  39 Furthermore, operations on the underlying file object
  40 (for example, assigning an address to a socket object using
  41 .BR bind (2))
  42 can equally be performed via the duplicate file descriptor.
  43 .PP
  44 The close-on-exec flag
  45 .RB ( FD_CLOEXEC ;
  46 see
  47 .BR fcntl (2))
  48 is set on the file descriptor returned by
  49 .BR pidfd_getfd ().
  50 .PP
  51 The
  52 .I flags
  53 argument is reserved for future use.
  54 Currently, it must be specified as 0.
  55 .PP
  56 Permission to duplicate another process's file descriptor
  57 is governed by a ptrace access mode
  58 .B PTRACE_MODE_ATTACH_REALCREDS
  59 check (see
  60 .BR ptrace (2)).
  61 .SH RETURN VALUE
  62 On success,
  63 .BR pidfd_getfd ()
  64 returns a file descriptor (a nonnegative integer).
  65 On error, \-1 is returned and
  66 .I errno
  67 is set to indicate the error.
  68 .SH ERRORS
  69 .TP
  70 .B EBADF
  71 .I pidfd
  72 is not a valid PID file descriptor.
  73 .TP
  74 .B EBADF
  75 .I targetfd
  76 is not an open file descriptor in the process referred to by
  77 .IR pidfd .
  78 .TP
  79 .B EINVAL
  80 .I flags
  81 is not 0.
  82 .TP
  83 .B EMFILE
  84 The per-process limit on the number of open file descriptors has been reached
  85 (see the description of
  86 .B RLIMIT_NOFILE
  87 in
  88 .BR getrlimit (2)).
  89 .TP
  90 .B ENFILE
  91 The system-wide limit on the total number of open files has been reached.
  92 .TP
  93 .B EPERM
  94 The calling process did not have
  95 .B PTRACE_MODE_ATTACH_REALCREDS
  96 permissions (see
  97 .BR ptrace (2))
  98 over the process referred to by
  99 .IR pidfd .
 100 .TP
 101 .B ESRCH
 102 The process referred to by
 103 .I pidfd
 104 does not exist
 105 (i.e., it has terminated and been waited on).
 106 .SH VERSIONS
 107 .BR pidfd_getfd ()
 108 first appeared in Linux 5.6.
 109 .\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
 110 .SH STANDARDS
 111 .BR pidfd_getfd ()
 112 is Linux specific.
 113 .SH NOTES
 114 For a description of PID file descriptors, see
 115 .BR pidfd_open (2).
 116 .PP
 117 The effect of
 118 .BR pidfd_getfd ()
 119 is similar to the use of
 120 .B SCM_RIGHTS
 121 messages described in
 122 .BR unix (7),
 123 but differs in the following respects:
 124 .IP \(bu 2
 125 In order to pass a file descriptor using an
 126 .B SCM_RIGHTS
 127 message,
 128 the two processes must first establish a UNIX domain socket connection.
 129 .IP \(bu
 130 The use of
 131 .B SCM_RIGHTS
 132 requires cooperation on the part of the process whose
 133 file descriptor is being copied.
 134 By contrast, no such cooperation is necessary when using
 135 .BR pidfd_getfd ().
 136 .IP \(bu
 137 The ability to use
 138 .BR pidfd_getfd ()
 139 is restricted by a
 140 .B PTRACE_MODE_ATTACH_REALCREDS
 141 ptrace  access  mode check.
 142 .SH SEE ALSO
 143 .BR clone3 (2),
 144 .BR dup (2),
 145 .BR kcmp (2),
 146 .BR pidfd_open (2)