Name
pidfd_getfd — obtain a duplicate of another process's file descriptor
Synopsis
int
pidfd_getfd( |
int pidfd, |
| int targetfd, | |
unsigned int flags); |
![[Note]](../stylesheet/note.png) |
Note |
|---|---|
| There is no glibc wrapper for this system call; see NOTES. |
DESCRIPTION
The 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, targetfd,
in the process referred to by the PID file descriptor
pidfd.
The duplicate file descriptor refers to the same open file
description (see open(2)) as the original
file descriptor in the process referred to by 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 bind(2)) can equally be
performed via the duplicate file descriptor.
The close-on-exec flag (FD_CLOEXEC; see fcntl(2)) is set on the
file descriptor returned by pidfd_getfd().
The flags argument
is reserved for future use. Currently, it must be specified
as 0.
Permission to duplicate another process's file descriptor
is governed by a ptrace access mode PTRACE_MODE_ATTACH_REALCREDS check (see
ptrace(2)).
RETURN VALUE
On success, pidfd_getfd()
returns a file descriptor (a nonnegative integer). On error,
−1 is returned and errno
is set to indicate the error.
ERRORS
- EBADF
-
pidfdis not a valid PID file descriptor. - EBADF
-
targetfdis not an open file descriptor in the process referred to bypidfd. - EINVAL
-
flagsis not 0. - EMFILE
-
The per-process limit on the number of open file descriptors has been reached (see the description of
RLIMIT_NOFILEin getrlimit(2)). - ENFILE
-
The system-wide limit on the total number of open files has been reached.
- EPERM
-
The calling process did not have
PTRACE_MODE_ATTACH_REALCREDSpermissions (see ptrace(2)) over the process referred to bypidfd. - ESRCH
-
The process referred to by
pidfddoes not exist (i.e., it has terminated and been waited on).
NOTES
Glibc does not provide a wrapper for this system call; call it using syscall(2).
For a description of PID file descriptors, see pidfd_open(2).
The effect of pidfd_getfd()
is similar to the use of SCM_RIGHTS messages described in unix(7), but differs in the
following respects:
-
In order to pass a file descriptor using an
SCM_RIGHTSmessage, the two processes must first establish a UNIX domain socket connection. -
The use of
SCM_RIGHTSrequires cooperation on the part of the process whose file descriptor is being copied. By contrast, no such cooperation is necessary when usingpidfd_getfd(). -
The ability to use
pidfd_getfd() is restricted by aPTRACE_MODE_ATTACH_REALCREDSptrace access mode check.
COLOPHON
This page is part of release 5.11 of the Linux man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
|
Copyright (c) 2020 by Michael Kerrisk <mtk.manpagesgmail.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 |