pidfd_getfd(2)

💖 pidfd_getfd — bestie edition 💖

okay so this is pidfd_getfd(2) from the System Calls Manual, and it's literally the "hey can I borrow that file descriptor" system call. no cap. 🫶

---

✨ 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);

quick heads up bestie: glibc provides no wrapper for pidfd_getfd(), which means you have to go through syscall(2). it's giving manual labour but make it ✨syscalls✨. 😭

🦋 DESCRIPTION 🦋

so pidfd_getfd() allocates a new file descriptor in the calling process. this shiny new fd is a duplicate of an existing file descriptor, targetfd, inside the process referred to by the PID file descriptor pidfd. it's basically cloning your friend's fd but it stays their friend's fd too. 💅

the duplicate file descriptor refers to the same open file description (peep open(2)) as the original file descriptor in the process referred to by pidfd. so the two file descriptors share file status flags and file offset — like, genuinely share them, not just vibe-share them. and 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. iconic behaviour honestly. ✨

the close-on-exec flag (FD_CLOEXEC; see fcntl(2)) is set on the file descriptor returned by pidfd_getfd(). it's default-on, no negotiation. 👑

the flags argument is reserved for future use. currently, it must be specified as 0. that's it. that's the whole flag situation. 💀

permission to duplicate another process's file descriptor is governed by a ptrace access mode PTRACE_MODE_ATTACH_REALCREDS check (see ptrace(2)). so like, you need the credentials, bestie. no sneaking in. 🚪

🌸 RETURN VALUE 🌸

on success, pidfd_getfd() returns a file descriptor (a nonnegative integer). slay. 🎉

on error, -1 is returned and errno is set to indicate the error. tragic but informative. 😭

💅 ERRORS 💅

• EBADF — pidfd is not a valid PID file descriptor. that's not a pidfd, that's a fake friend 💀
• EBADF — targetfd is not an open file descriptor in the process referred to by pidfd. nothing to copy, nothing to serve. 🙈
• EINVAL — flags is not 0. you tried to be creative with the reserved field. respect the reservation. ✋
• EMFILE — the per-process limit on the number of open file descriptors has been reached (see the description of RLIMIT_NOFILE in getrlimit(2)). your fd closet is full. 🚪
• ENFILE — the system-wide limit on the total number of open files has been reached. not just you — the WHOLE system is out of room. 🌍
• EPERM — the calling process did not have PTRACE_MODE_ATTACH_REALCREDS permissions (see ptrace(2)) over the process referred to by pidfd. permission check said no. 😤
• ESRCH — the process referred to by pidfd does not exist (i.e., it has terminated and been waited on). it's gone gone. 🪦

⭐ STANDARDS ⭐

Linux. that's the standard. 🐧

🕰️ HISTORY 🕰️

Linux 5.6. a relatively recent icon, honestly. ✨

📝 NOTES 📝

for a description of PID file descriptors, see pidfd_open(2). go read it, it's the prerequisite lore. 📖

the effect of pidfd_getfd() is similar to the use of SCM_RIGHTS messages described in unix(7), but it 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. so much setup. 😮‍💨
• 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(). sneaky? no, permitted. 😌
• the ability to use pidfd_getfd() is restricted by a PTRACE_MODE_ATTACH_REALCREDS ptrace access mode check. rules are rules. 🔒

---

👀 SEE ALSO 👀

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

---

aaaand that's the whole page, bestie. this came from Linux man-pages 6.20, dated 2026-02-08, and it's the pidfd_getfd(2) page from the System Calls Manual. now go duplicate some file descriptors responsibly, mwah 💖✨🎀