Changes.old: Add missing entry in 5.13 changelog
[man-pages.git] / man2 / pidfd_getfd.2
blob71d7ae4db92881bd4c336abd017432c6cec829ba
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
105 .BR getrlimit (2)).
107 .B ENFILE
108 The system-wide limit on the total number of open files has been reached.
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 .
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).
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)