# pidfd_getfd

## NAME



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


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## 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_ : glibc provides no wrapper for **pidfd_getfd**(), necessitating
           the use of syscall(2).
    


## 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).
    


## STANDARDS



           Linux.
    


## 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.
    


* * *