Linux pidfd Race-Free Process Lifecycle Playbook

Date: 2026-03-30
Category: knowledge
Scope: Practical guidance for replacing PID-based process supervision (kill(pid), PID files, /proc/<pid> polling) with pidfd-based lifecycle control that is robust to PID reuse races.

1) Why this matters

Classic process control APIs identify targets by integer PID. That creates a long-standing hazard:

• target exits,
• PID is recycled,
• later signal/wait action can hit the wrong process.

pidfd turns a process reference into a file descriptor-like capability with stable identity semantics for that task lifetime. In operations terms, it means:

• safer terminate/restart paths,
• cleaner event-loop integration (poll/epoll),
• fewer “killed the wrong thing” edge-case incidents.

2) Kernel feature matrix (minimums)

A practical baseline from Linux man-pages + runtime checks in modern ecosystems:

• 5.1: pidfd_send_signal(2)
• 5.2: CLONE_PIDFD support in clone(2)
• 5.3: pidfd_open(2), clone3(2)
• 5.4: waitid() with P_PIDFD
• 5.6: pidfd_getfd(2)
• 5.10: PIDFD_NONBLOCK for pidfd_open
• 6.9: PIDFD_THREAD (pidfd_open) and PIDFD_SIGNAL_* scope flags (pidfd_send_signal)

If your fleet spans kernel generations, gate features explicitly (not just one syscall probe).

3) Core pidfd primitives and what they buy you

3.1 pidfd_open(pid, flags)

• Opens a process handle FD for an existing task.
• FD is CLOEXEC.
• poll/select/epoll can watch it for lifecycle transitions.

Important nuance:

• For child lifecycle tracking, creating child with CLONE_PIDFD is the strongest race-avoidance pattern.
• pidfd_open(child_pid) can still be valid, but the man page documents conditions around zombie reaping and SIGCHLD behavior that can break assumptions if not controlled.

3.2 pidfd_send_signal(pidfd, sig, info, flags)

• Signal by stable process reference.
• If target is gone/reaped, returns ESRCH instead of silently hitting a reused PID.
• For thread/process-group scope control, Linux 6.9+ adds PIDFD_SIGNAL_THREAD, PIDFD_SIGNAL_THREAD_GROUP, PIDFD_SIGNAL_PROCESS_GROUP.

3.3 waitid(P_PIDFD, ...)

• Wait/reap using pidfd identity (Linux 5.4+).
• Supports WEXITED, WNOHANG, WNOWAIT patterns.
• With nonblocking pidfd, may return EAGAIN if target hasn’t exited.

3.4 pidfd_getfd(pidfd, targetfd, 0)

• Duplicates a target process FD into caller without prior UNIX socket choreography.
• Permission is controlled by ptrace access checks (PTRACE_MODE_ATTACH_REALCREDS).

Use sparingly; this is powerful and should be auditable.

4) Event-loop pattern that scales

For supervisors/agents handling many workers:

1. spawn child and obtain pidfd early (clone3 + CLONE_PIDFD preferred);
2. register pidfd in epoll;
3. on readability (EPOLLIN), treat as process-state-change signal;
4. for child processes, call waitid(P_PIDFD, ..., WEXITED | WNOHANG) to collect status;
5. close pidfd only after ownership/state machine transition is complete.

Notes from man-pages behavior:

• pidfd itself is not readable payload (read(pidfd) => EINVAL);
• readiness is a lifecycle notification mechanism, not a data stream.

5) Migration strategy from PID integers to pidfd handles

Phase A — dual-path compatibility

• Keep legacy PID paths, but attach pidfd alongside.
• Log both identifiers (pid, pidfd) in debug metadata.
• Compare outcomes of terminate/wait paths under chaos testing.

Phase B — API boundary shift

• Internal process API should pass opaque ProcessHandle (contains pidfd), not raw PID.
• Restrict direct kill(pid) calls to compatibility adapters.

Phase C — policy hardening

• Make pidfd mandatory for new spawn flows.
• Deny restart/stop actions if only stale PID metadata is present.

6) Failure modes and how to design for them

• ENOSYS / syscall blocked by seccomp: fallback to PID path with reduced guarantees and explicit warnings.
• ECHILD on waitid(P_PIDFD, ...): pidfd may refer to non-child process; use poll semantics for liveness, not wait/reap.
• FD lifecycle bugs: pidfd number reuse in caller process can cause logic mistakes if ownership tracking is sloppy.
• Permission surprises (EPERM): especially for pidfd_getfd and cross-namespace signaling.

Operationally, label metrics by control path:

• process_control_path = pidfd|legacy_pid
• signal_result = ok|esrch|eperm|fallback
• wait_result = exited|eagain|echild|error

7) Language/runtime reality check

• Low-level C paths still commonly use direct syscall() for pidfd_* operations.
• Modern runtimes (e.g., Go stdlib internals) perform capability probes and require multiple pidfd-related primitives to behave correctly, not just pidfd_open alone.
• Mixed environments (containers, seccomp, emulation layers) can expose partial pidfd availability—treat that as first-class in tests.

8) Rollout checklist

• Kernel baseline and seccomp profile audited for required syscalls.
• Spawn path can return/retain pidfd from creation time.
• Supervisor state machine keyed by handle lifecycle, not PID.
• epoll integration validated under high churn.
• Exit-status collection semantics tested (WNOHANG, WNOWAIT, reaping order).
• Incident runbook updated (distinguish ESRCH expected vs abnormal).
• Metrics and logs include control-path labels.

9) Practical takeaway

pidfd is not just “new syscall trivia”; it is a reliability primitive for process orchestration. The biggest gain is correctness under churn: when processes die/restart quickly, pidfd-based control makes your lifecycle automation deterministic where PID-only flows remain probabilistic.

References

1. pidfd_open(2) — Linux man-pages
   https://man7.org/linux/man-pages/man2/pidfd_open.2.html

2. pidfd_send_signal(2) — Linux man-pages
   https://man7.org/linux/man-pages/man2/pidfd_send_signal.2.html

3. pidfd_getfd(2) — Linux man-pages
   https://man7.org/linux/man-pages/man2/pidfd_getfd.2.html

4. wait(2) / waitid() (P_PIDFD) — Linux man-pages
   https://man7.org/linux/man-pages/man2/waitid.2.html

5. clone(2) (CLONE_PIDFD, clone3) — Linux man-pages
   https://man7.org/linux/man-pages/man2/clone.2.html

6. Go source (os/pidfd_linux.go) capability checks and version notes
   https://go.dev/src/os/pidfd_linux.go?m=text