PDFORK(2)

💖 PDFORK(2) 💖 — the pdfork, pdgetpid, pdkill girlies (system calls to manage process descriptors)

okay bestie, sit down, hydrate, because we're about to talk about process descriptors and honestly? they're iconic. this is PDFORK(2) from the System Calls Manual and it's giving "I manage processes but make it fashion" 💅

---

📚 LIBRARY

Standard C Library (libc, -lc) — she's in libc, she's always been in libc, we love her for that 🫶

---

✨ SYNOPSIS ✨

#include <sys/procdesc.h>

pid_t
pdfork(int *fdp, int flags);

int
pdgetpid(int fd, pid_t *pidp);

int
pdkill(int fd, int signum);

---

🌸 DESCRIPTION 🌸

okay so process descriptors?? they're special file descriptors that literally represent processes. main character energy fr fr. you make them with pdfork(), which is basically fork(2) but with ✨aura✨ — and if it works, it hands you back a process descriptor in the integer that fdp points to.

lowkey important: processes made with pdfork() will not cause SIGCHLD when they terminate. no drama, no signal, she just leaves. 💀

and pdfork() takes these flags, bestie:

• PD_DAEMON — instead of the default "terminate when you close me" behaviour, this lets the process just live, chilling, until someone explicitly kills it with kill(2).

not permitted in capsicum(4) capability mode (go read cap_enter(2), iykyk).

• PD_CLOEXEC — sets close-on-exec on the process descriptor. classic, iconic, hygienic. 🎀

then there's pdgetpid() which queries the process ID (PID) inside the process descriptor fd. it's the "hey girl what's your PID" of system calls.

and pdkill() is functionally identical to kill(2), except instead of a PID she accepts a process descriptor, fd. same energy, different handle. periodt.

---

🦋 the other system calls that also act different around process descriptors 🦋

• fstat(2) — queries the status of a process descriptor. rn only the st_mode, st_birthtime, st_atime, st_ctime and st_mtime fields are defined. and here's the vibe check: if the owner read, write, and execute bits are set, the process represented by the process descriptor is still alive. 🌈
• poll(2) and select(2) — let you wait for process state transitions. rn only POLLHUP is defined, and it gets raised when the process dies. 😭 you can also monitor process state transitions with the kqueue(2) filter EVFILT_PROCDESC; rn only NOTE_EXIT is implemented.
• close(2) — will close the process descriptor unless PD_DAEMON is set. and if the process is still alive and this is the last reference to the process descriptor, the process gets terminated with the signal SIGKILL. 💀 no cap. that's the default terminate-on-close behaviour and she does not play.

---

🔥 RETURN VALUES 🔥

• pdfork() returns a PID, 0 or -1, exactly as fork(2) does. same rules, same numbers.
• pdgetpid() and pdkill() return 0 on success and -1 on failure.

---

🙈 ERRORS 🙈

these functions may return the same error numbers as their PID-based equivalents (like, pdfork() may return the same error numbers as fork(2)), plus these additions:

• [EINVAL] — the signal number you gave to pdkill() is invalid. bestie. that's not a real signal. 🫠
• [ENOTCAPABLE] — the process descriptor being operated on has insufficient rights (e.g. CAP_PDKILL for pdkill()). she doesn't have the clearance, hun. 💅

---

👀 SEE ALSO 👀

close(2), fork(2), fstat(2), kill(2), poll(2), kqueue(2), wait4(2), capsicum(4), procdesc(4)

go read them, they're all part of the lore. 📖

---

⭐ HISTORY ⭐

the pdfork(), pdgetpid(), and pdkill() system calls first appeared in FreeBSD 9.0. 💫

support for process descriptors mode was developed as part of the TrustedBSD Project.

---

👑 AUTHORS 👑

these functions and the capability facility were created by Robert N. M. Watson <rwatson@FreeBSD.org> and Jonathan Anderson <jonathan@FreeBSD.org> at the University of Cambridge Computer Laboratory, with support from a grant from Google, Inc. absolute legends, we stan. 🫶✨

---

and that's the whole page, bestie!! this came from the Debian build, dated October 14, 2018 — so yeah, throwback era, but the lore still hits. 💖🦋 mwah, go manage some processes. 🎀