diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 new file mode 100644 index 000000000..3fc9c441b --- /dev/null +++ b/man2/pidfd_getfd.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2020 by Michael Kerrisk +.\" +.\" %%%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 2020-03-31 "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 +.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 be 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 nonnegative file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the cause of 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 . +.BR +.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 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 +Currently, there is no glibc wrapper for this system call; call it using +.BR syscall (2). +.PP +For a description of PID file descriptors, see +.BR pidfd_open (2). +.SH SEE ALSO +.BR clone3 (2), +.BR dup (2), +.BR kcmp (2), +.BR pidfd_open (2)