| .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PIDFD_GETFD 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| pidfd_getfd \- obtain a duplicate of another process's file descriptor |
| .SH SYNOPSIS |
| .nf |
| .BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags ); |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .SH DESCRIPTION |
| The |
| .BR pidfd_getfd () |
| system call allocates a new file descriptor in the calling process. |
| This new file descriptor is a duplicate of an existing file descriptor, |
| .IR targetfd , |
| in the process referred to by the PID file descriptor |
| .IR pidfd . |
| .PP |
| The duplicate file descriptor refers to the same open file description (see |
| .BR open (2)) |
| as the original file descriptor in the process referred to by |
| .IR pidfd . |
| The two file descriptors thus share file status flags and file offset. |
| Furthermore, operations on the underlying file object |
| (for example, assigning an address to a socket object using |
| .BR bind (2)) |
| can equally be performed via the duplicate file descriptor. |
| .PP |
| The close-on-exec flag |
| .RB ( FD_CLOEXEC ; |
| see |
| .BR fcntl (2)) |
| is set on the file descriptor returned by |
| .BR pidfd_getfd (). |
| .PP |
| The |
| .I flags |
| argument is reserved for future use. |
| Currently, it must be specified as 0. |
| .PP |
| Permission to duplicate another process's file descriptor |
| is governed by a ptrace access mode |
| .B PTRACE_MODE_ATTACH_REALCREDS |
| check (see |
| .BR ptrace (2)). |
| .SH RETURN VALUE |
| On success, |
| .BR pidfd_getfd () |
| returns a file descriptor (a nonnegative integer). |
| On error, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I pidfd |
| is not a valid PID file descriptor. |
| .TP |
| .B EBADF |
| .I targetfd |
| is not an open file descriptor in the process referred to by |
| .IR pidfd . |
| .TP |
| .B EINVAL |
| .I flags |
| is not 0. |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached |
| (see the description of |
| .BR RLIMIT_NOFILE |
| in |
| .BR getrlimit (2)). |
| .TP |
| .B ENFILE |
| The system-wide limit on the total number of open files has been reached. |
| .TP |
| .B EPERM |
| The calling process did not have |
| .B PTRACE_MODE_ATTACH_REALCREDS |
| permissions (see |
| .BR ptrace (2)) |
| over the process referred to by |
| .IR pidfd . |
| .TP |
| .B ESRCH |
| The process referred to by |
| .I pidfd |
| does not exist |
| (i.e., it has terminated and been waited on). |
| .SH VERSIONS |
| .BR pidfd_getfd () |
| first appeared in Linux 5.6. |
| .\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09 |
| .SH CONFORMING TO |
| .BR pidfd_getfd () |
| is Linux specific. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call; call it using |
| .BR syscall (2). |
| .PP |
| For a description of PID file descriptors, see |
| .BR pidfd_open (2). |
| .PP |
| The effect of |
| .BR pidfd_getfd () |
| is similar to the use of |
| .BR SCM_RIGHTS |
| messages described in |
| .BR unix (7), |
| but differs in the following respects: |
| .IP \(bu 2 |
| In order to pass a file descriptor using an |
| .BR SCM_RIGHTS |
| message, |
| the two processes must first establish a UNIX domain socket connection. |
| .IP \(bu |
| The use of |
| .BR SCM_RIGHTS |
| requires cooperation on the part of the process whose |
| file descriptor is being copied. |
| By contrast, no such cooperation is necessary when using |
| .BR pidfd_getfd (). |
| .IP \(bu |
| The ability to use |
| .BR pidfd_getfd () |
| is restricted by a |
| .BR PTRACE_MODE_ATTACH_REALCREDS |
| ptrace access mode check. |
| .SH SEE ALSO |
| .BR clone3 (2), |
| .BR dup (2), |
| .BR kcmp (2), |
| .BR pidfd_open (2) |