PDFORK(2)                 FreeBSD System Calls Manual                PDFORK(2)

NAME

     pdfork, pdrfork, pdgetpid, pdkill, pdwait - System calls to manage
     process descriptors

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <sys/procdesc.h>

     pid_t
     pdfork(int *fdp, int pdflags);

     pid_t
     pdrfork(int *fdp, int pdflags, int rfflags);

     int
     pdgetpid(int fd, pid_t *pidp);

     int
     pdkill(int fd, int signum);

     int
     pdwait(int fd, int *status, int options, struct __wrusage *wrusage,
         struct __siginfo *info);

DESCRIPTION

     Process descriptors are special file descriptors that represent
     processes, and are created using pdfork(), a variant of fork(2), which,
     if successful, returns a process descriptor in the integer pointed to by
     fdp.  Processes created via pdfork() will not cause SIGCHLD on
     termination.  pdfork() can accept the pdflags:

     PD_DAEMON   Instead of the default terminate-on-close behaviour, allow
                 the process to live until it is explicitly killed with
                 kill(2).

                 This option is not permitted in capsicum(4) capability mode
                 (see cap_enter(2)).

     PD_CLOEXEC
                Set close-on-exec on process descriptor.

     The pdrfork() system call is a variant of pdfork() that also takes the
     rfflags argument to control sharing of process resources between the
     caller and the new process.  Like pdfork(), the function writes the
     process descriptor referencing the created process into the location
     pointed to by the fdp argument.  See rfork(2) for a description of the
     possible rfflag flags.  The pdrfork() system call requires that both the
     RFPROC and RFPROCDESC flags, or RFSPAWN flag are specified.

     pdgetpid() queries the process ID (PID) in the process descriptor fd.

     pdkill() is functionally identical to kill(2), except that it accepts a
     process descriptor, fd, rather than a PID.

     The pdwait() system call allows the calling thread to wait and retrieve
     the status information on the process referenced by the fd process
     descriptor.  See the description of the wait6 system call for the
     behavior specification.

     The following system calls also have effects specific to process
     descriptors:

     fstat(2) queries status of a process descriptor; currently only the
     st_mode, st_birthtime, st_atime, st_ctime and st_mtime fields are
     defined.  If the owner read, write, and execute bits are set then the
     process represented by the process descriptor is still alive.

     poll(2) and select(2) allow waiting for process state transitions;
     currently only POLLHUP is defined, and will be raised when the process
     dies.  Process state transitions can also be monitored using kqueue(2)
     filter EVFILT_PROCDESC; currently only NOTE_EXIT is implemented.

     close(2) will close the process descriptor unless PD_DAEMON is set; if
     the process is still alive and this is the last reference to the process
     descriptor, the process will be terminated with the signal SIGKILL.  The
     PID of the referenced process is not reused until the process descriptor
     is closed, whether or not the zombie process is reaped by pdwait(),
     wait6, or similar system calls.

RETURN VALUES

     pdfork() and pdrfork() return a PID, 0 or -1, as fork(2) does.

     pdgetpid(), pdkill(), and pdwait() return 0 on success and -1 on failure.

ERRORS

     These functions may return the same error numbers as their PID-based
     equivalents (e.g.  pdfork() may return the same error numbers as
     fork(2)), with the following additions:

     [EFAULT]           The copyout of the resulting file descriptor value to
                        the memory pointed to by fdp failed.

                        Note that the child process was already created when
                        this condition is detected, and the child continues
                        execution, same as the parent.  If this error must be
                        handled, it is advisable to memoize the getpid()
                        result before the call to pdfork() or pdrfork(), and
                        compare it to the value returned by getpid() after, to
                        see if code is executing in parent or child.

     [EINVAL]           The signal number given to pdkill() is invalid.

     [ENOTCAPABLE]      The process descriptor being operated on has
                        insufficient rights (e.g.  CAP_PDKILL for pdkill()).

SEE ALSO

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

HISTORY

     The pdfork(), pdgetpid(), and pdkill() system calls first appeared in
     FreeBSD 9.0.  The pdrfork() and pdwait() system calls first appeared in
     FreeBSD 15.1.

     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.  The pdrfork() and pdwait() functions were
     developed by Konstantin Belousov <kib@FreeBSD.org> with input from Alan
     Somers <asomers@FreeBSD.org>.

FreeBSD 15.1-STABLE-HBSD        April 19, 2026                       PDFORK(2)