.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH pidfd_getfd 2 2023-02-05 "Linux man-pages 6.03"
.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 VERSIONS
.BR pidfd_getfd ()
first appeared in Linux 5.6.
.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
.SH STANDARDS
.BR pidfd_getfd ()
is Linux specific.
.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)