1 .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH PIDFD_GETFD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
27 pidfd_getfd \- obtain a duplicate of another process's file descriptor
30 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
31 .B #include <unistd.h>
33 .BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
34 .BI " unsigned int " flags );
38 glibc provides no wrapper for
40 necessitating the use of
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,
48 in the process referred to by the PID file descriptor
51 The duplicate file descriptor refers to the same open file description (see
53 as the original file descriptor in the process referred to by
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
59 can equally be performed via the duplicate file descriptor.
61 The close-on-exec flag
65 is set on the file descriptor returned by
70 argument is reserved for future use.
71 Currently, it must be specified as 0.
73 Permission to duplicate another process's file descriptor
74 is governed by a ptrace access mode
75 .B PTRACE_MODE_ATTACH_REALCREDS
81 returns a file descriptor (a nonnegative integer).
82 On error, \-1 is returned and
84 is set to indicate the error.
89 is not a valid PID file descriptor.
93 is not an open file descriptor in the process referred to by
101 The per-process limit on the number of open file descriptors has been reached
102 (see the description of
108 The system-wide limit on the total number of open files has been reached.
111 The calling process did not have
112 .B PTRACE_MODE_ATTACH_REALCREDS
115 over the process referred to by
119 The process referred to by
122 (i.e., it has terminated and been waited on).
125 first appeared in Linux 5.6.
126 .\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
131 For a description of PID file descriptors, see
136 is similar to the use of
138 messages described in
140 but differs in the following respects:
142 In order to pass a file descriptor using an
145 the two processes must first establish a UNIX domain socket connection.
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
157 .BR PTRACE_MODE_ATTACH_REALCREDS
158 ptrace access mode check.