man2/pidfd_getfd.2

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