1 files changed, 144 insertions, 0 deletions
diff --git a/man/man2/pidfd_getfd.2 b/man/man2/pidfd_getfd.2
new file mode 100644
index 000000000..ba92823cb
--- /dev/null
+++ b/man/man2/pidfd_getfd.2
@@ -0,0 +1,144 @@
+.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pidfd_getfd 2 (date) "Linux man-pages (unreleased)"
+.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>
+.P
+.BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
+.BI "            unsigned int " flags );
+.fi
+.P
+.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 .
+.P
+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.
+.P
+The close-on-exec flag
+.RB ( FD_CLOEXEC ;
+see
+.BR fcntl (2))
+is set on the file descriptor returned by
+.BR pidfd_getfd ().
+.P
+The
+.I flags
+argument is reserved for future use.
+Currently, it must be specified as 0.
+.P
+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).
+.P
+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)