2020-03-31 12:01:58 +00:00
|
|
|
.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
|
|
.\"
|
|
|
|
.\" %%%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))
|
2020-04-08 08:27:32 +00:00
|
|
|
can equally be performed via the duplicate file descriptor.
|
2020-03-31 12:01:58 +00:00
|
|
|
.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 ()
|
2020-04-08 08:27:32 +00:00
|
|
|
returns a file descriptor (a nonnegative integer).
|
2020-03-31 12:01:58 +00:00
|
|
|
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 .
|
2020-04-11 20:32:33 +00:00
|
|
|
.BR
|
2020-03-31 12:01:58 +00:00
|
|
|
.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
|
2020-04-08 08:27:32 +00:00
|
|
|
.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
|
2020-03-31 12:01:58 +00:00
|
|
|
.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).
|
2020-04-01 05:30:48 +00:00
|
|
|
.PP
|
|
|
|
The effect of
|
|
|
|
.BR pidfd_getfd ()
|
|
|
|
is similar to the use of
|
|
|
|
.BR SCM_RIGHTS
|
|
|
|
messages described in
|
|
|
|
.BR unix (7),
|
|
|
|
but differs in the following respects:
|
|
|
|
.IP \(bu 2
|
|
|
|
In order to pass a file descriptor using an
|
|
|
|
.BR SCM_RIGHTS
|
|
|
|
message,
|
|
|
|
the two processes must first establish a UNIX domain socket connection.
|
|
|
|
.IP \(bu
|
|
|
|
The use of
|
|
|
|
.BR 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
|
|
|
|
.BR PTRACE_MODE_ATTACH_REALCREDS
|
|
|
|
ptrace access mode check.
|
2020-03-31 12:01:58 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR clone3 (2),
|
|
|
|
.BR dup (2),
|
|
|
|
.BR kcmp (2),
|
|
|
|
.BR pidfd_open (2)
|