From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man2/pidfd_getfd.2 | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 man2/pidfd_getfd.2 (limited to 'man2/pidfd_getfd.2') diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 new file mode 100644 index 0000000..9e3af2a --- /dev/null +++ b/man2/pidfd_getfd.2 @@ -0,0 +1,144 @@ +.\" Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pidfd_getfd 2 2023-03-30 "Linux man-pages 6.05.01" +.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 " " /* Definition of " SYS_* " constants */" +.B #include +.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) -- cgit v1.2.3