Debian Codegraph @

upstream/debian-trixie/man2/pidfd_getfd.2

raw
1 .\" Copyright (c) 2020 by Michael Kerrisk <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH pidfd_getfd 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
16 .BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
17 .BI " unsigned int " flags );
18 .fi
19 .P
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 .P
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 .P
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 .P
51 The
52 .I flags
53 argument is reserved for future use.
54 Currently, it must be specified as 0.
55 .P
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 STANDARDS
107 Linux.
108 .SH HISTORY
109 Linux 5.6.
110 .\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
111 .SH NOTES
112 For a description of PID file descriptors, see
113 .BR pidfd_open (2).
114 .P
115 The effect of
116 .BR pidfd_getfd ()
117 is similar to the use of
118 .B SCM_RIGHTS
119 messages described in
120 .BR unix (7),
121 but differs in the following respects:
122 .IP \[bu] 3
123 In order to pass a file descriptor using an
124 .B SCM_RIGHTS
125 message,
126 the two processes must first establish a UNIX domain socket connection.
127 .IP \[bu]
128 The use of
129 .B SCM_RIGHTS
130 requires cooperation on the part of the process whose
131 file descriptor is being copied.
132 By contrast, no such cooperation is necessary when using
133 .BR pidfd_getfd ().
134 .IP \[bu]
135 The ability to use
136 .BR pidfd_getfd ()
137 is restricted by a
138 .B PTRACE_MODE_ATTACH_REALCREDS
139 ptrace access mode check.
140 .SH SEE ALSO
141 .BR clone3 (2),
142 .BR dup (2),
143 .BR kcmp (2),
144 .BR pidfd_open (2)