.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH pidfd_getfd 2 2023-03-30 "Linux man-pages 6.04"
.SH NAME
pidfd_getfd \- obtain a duplicate of another process's file descriptor
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
.BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
.BI "            unsigned int " flags );
.fi
.PP
.IR Note :
glibc provides no wrapper for
.BR pidfd_getfd (),
necessitating the use of
.BR syscall (2).
.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
.B 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 STANDARDS
Linux.
.SH HISTORY
Linux 5.6.
.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
.SH NOTES
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
.B SCM_RIGHTS
messages described in
.BR unix (7),
but differs in the following respects:
.IP \[bu] 3
In order to pass a file descriptor using an
.B SCM_RIGHTS
message,
the two processes must first establish a UNIX domain socket connection.
.IP \[bu]
The use of
.B 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
.B PTRACE_MODE_ATTACH_REALCREDS
ptrace  access  mode check.
.SH SEE ALSO
.BR clone3 (2),
.BR dup (2),
.BR kcmp (2),
.BR pidfd_open (2)