Debian Codegraph @

upstream/debian-unstable/man2/pidfd_getfd.2

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