pidfd_getfd(2)

Synopsis

#include <sys/syscall.h>
#include <unistd.h>

int syscall(SYS_pidfd_getfd, int pidfd, int targetfd,
            unsigned int flags);

Rod's take

The /proc/<pid>/fd/N trick is a path lookup keyed on a PID, so it inherits every reuse race PIDs have. pidfd_getfd goes through the stable handle and drops a duplicate of the target's descriptor into your table, sharing offset and flags exactly like dup(2). Unlike SCM_RIGHTS, the other process doesn't get a vote, which is precisely why it's gated on a ptrace attach check. Supervisors and container runtimes want this. Everyone else should be mildly alarmed that it exists.

Flags and arguments that matter

Errors you will actually hit

Example

int pfd = syscall(SYS_pidfd_open, pid, 0);
if (pfd < 0)
    err(1, "pidfd_open");

/* copy the target's fd 0; needs ptrace-attach rights over it */
int fd = syscall(SYS_pidfd_getfd, pfd, 0, 0);
if (fd < 0)
    err(1, "pidfd_getfd");   /* EPERM, EBADF, ESRCH */

/* fd shares the open file description; FD_CLOEXEC is set */
close(pfd);

Trimmed from the full walkthrough in pidfd: Unix finally has a handle on your processes (only took 50 years).

BSD equivalent

none; on FreeBSD and OpenBSD the closest is passing the descriptor with SCM_RIGHTS over a unix(4) socket, which needs the owner's cooperation.