Name

pidfd_getfd — obtain a duplicate of another process's file descriptor

Synopsis

#include <sys/syscall.h>       /* Definition of  SYS_*  constants */
#include <unistd.h>
int syscall( SYS_pidfd_getfd,
  int pidfd,
  int targetfd,
  unsigned int flags);
 
[Note] Note
glibc provides no wrapper for
.BR pidfd_getfd (),
necessitating the use of
  

DESCRIPTION

The 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, targetfd, in the process referred to by the PID file descriptor pidfd.

The duplicate file descriptor refers to the same open file description (see open(2)) as the original file descriptor in the process referred to by 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 bind(2)) can equally be performed via the duplicate file descriptor.

The close-on-exec flag (FD_CLOEXEC; see fcntl(2)) is set on the file descriptor returned by pidfd_getfd().

The flags argument is reserved for future use. Currently, it must be specified as 0.

Permission to duplicate another process's file descriptor is governed by a ptrace access mode PTRACE_MODE_ATTACH_REALCREDS check (see ptrace(2)).

RETURN VALUE

On success, pidfd_getfd() returns a file descriptor (a nonnegative integer). On error, −1 is returned and errno is set to indicate the error.

ERRORS

EBADF

pidfd is not a valid PID file descriptor.

EBADF

targetfd is not an open file descriptor in the process referred to by pidfd.

EINVAL

flags is not 0.

EMFILE

The per-process limit on the number of open file descriptors has been reached (see the description of RLIMIT_NOFILE in getrlimit(2)).

ENFILE

The system-wide limit on the total number of open files has been reached.

EPERM

The calling process did not have PTRACE_MODE_ATTACH_REALCREDS permissions (see ptrace(2)) over the process referred to by pidfd.

ESRCH

The process referred to by pidfd does not exist (i.e., it has terminated and been waited on).

VERSIONS

pidfd_getfd() first appeared in Linux 5.6.

CONFORMING TO

pidfd_getfd() is Linux specific.

NOTES

For a description of PID file descriptors, see pidfd_open(2).

The effect of pidfd_getfd() is similar to the use of SCM_RIGHTS messages described in unix(7), but differs in the following respects:

  • In order to pass a file descriptor using an SCM_RIGHTS message, the two processes must first establish a UNIX domain socket connection.

  • The use of 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 pidfd_getfd().

  • The ability to use pidfd_getfd() is restricted by a PTRACE_MODE_ATTACH_REALCREDS ptrace access mode check.

SEE ALSO

clone3(2), dup(2), kcmp(2), pidfd_open(2)

COLOPHON

This page is part of release 5.13 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man−pages/.


  Copyright (c) 2020 by Michael Kerrisk <mtk.manpagesgmail.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