]>
Commit | Line | Data |
---|---|---|
13aa2b30 MK |
1 | .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
13aa2b30 | 4 | .\" |
45186a5d | 5 | .TH PIDFD_GETFD 2 2021-03-22 "Linux man-pages (unreleased)" |
13aa2b30 MK |
6 | .SH NAME |
7 | pidfd_getfd \- obtain a duplicate of another process's file descriptor | |
faffb5db AC |
8 | .SH LIBRARY |
9 | Standard C library | |
8fc3b2cf | 10 | .RI ( libc ", " \-lc ) |
13aa2b30 MK |
11 | .SH SYNOPSIS |
12 | .nf | |
13cf4fc7 AC |
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 ); | |
13aa2b30 | 18 | .fi |
632d1152 GC |
19 | .PP |
20 | .IR Note : | |
13cf4fc7 AC |
21 | glibc provides no wrapper for |
22 | .BR pidfd_getfd (), | |
23 | necessitating the use of | |
24 | .BR syscall (2). | |
13aa2b30 MK |
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)) | |
8b4baee7 | 42 | can equally be performed via the duplicate file descriptor. |
13aa2b30 MK |
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 () | |
8b4baee7 | 64 | returns a file descriptor (a nonnegative integer). |
13aa2b30 MK |
65 | On error, \-1 is returned and |
66 | .I errno | |
855d489a | 67 | is set to indicate the error. |
13aa2b30 MK |
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 . | |
13aa2b30 MK |
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 | |
1ae6b2c7 | 86 | .B RLIMIT_NOFILE |
13aa2b30 MK |
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 | |
8b4baee7 MK |
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 | |
13aa2b30 MK |
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 | |
3113c7f3 | 110 | .SH STANDARDS |
13aa2b30 MK |
111 | .BR pidfd_getfd () |
112 | is Linux specific. | |
113 | .SH NOTES | |
13aa2b30 MK |
114 | For a description of PID file descriptors, see |
115 | .BR pidfd_open (2). | |
be04cb50 MK |
116 | .PP |
117 | The effect of | |
118 | .BR pidfd_getfd () | |
119 | is similar to the use of | |
1ae6b2c7 | 120 | .B SCM_RIGHTS |
be04cb50 MK |
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 | |
1ae6b2c7 | 126 | .B SCM_RIGHTS |
be04cb50 MK |
127 | message, |
128 | the two processes must first establish a UNIX domain socket connection. | |
129 | .IP \(bu | |
130 | The use of | |
1ae6b2c7 | 131 | .B SCM_RIGHTS |
be04cb50 MK |
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 | |
1ae6b2c7 | 140 | .B PTRACE_MODE_ATTACH_REALCREDS |
be04cb50 | 141 | ptrace access mode check. |
13aa2b30 MK |
142 | .SH SEE ALSO |
143 | .BR clone3 (2), | |
144 | .BR dup (2), | |
145 | .BR kcmp (2), | |
146 | .BR pidfd_open (2) |