1.\" 2.\" Copyright (c) 2009-2010, 2012-2013 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" This software was developed at the University of Cambridge Computer 6.\" Laboratory with support from a grant from Google, Inc. 7.\" 8.\" This software was developed by SRI International and the University of 9.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) 10.\" ("CTSRD"), as part of the DARPA CRASH research programme. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.Dd January 20, 2026 34.Dt PDFORK 2 35.Os 36.Sh NAME 37.Nm pdfork , 38.Nm pdrfork , 39.Nm pdgetpid , 40.Nm pdkill , 41.Nm pdwait 42.Nd System calls to manage process descriptors 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In sys/procdesc.h 47.Ft pid_t 48.Fn pdfork "int *fdp" "int pdflags" 49.Ft pid_t 50.Fn pdrfork "int *fdp" "int pdflags" "int rfflags" 51.Ft int 52.Fn pdgetpid "int fd" "pid_t *pidp" 53.Ft int 54.Fn pdkill "int fd" "int signum" 55.Ft int 56.Fo pdwait 57.Fa "int fd" 58.Fa "int *status" 59.Fa "int options" 60.Fa "struct __wrusage *wrusage" 61.Fa "struct __siginfo *info" 62.Fc 63.Sh DESCRIPTION 64Process descriptors are special file descriptors that represent processes, 65and are created using 66.Fn pdfork , 67a variant of 68.Xr fork 2 , 69which, if successful, returns a process descriptor in the integer pointed to 70by 71.Fa fdp . 72Processes created via 73.Fn pdfork 74will not cause 75.Dv SIGCHLD 76on termination. 77.Fn pdfork 78can accept the 79.Fa pdflags: 80.Bl -tag -width PD_CLOEXEC 81.It Dv PD_DAEMON 82Instead of the default terminate-on-close behaviour, allow the process to 83live until it is explicitly killed with 84.Xr kill 2 . 85.Pp 86This option is not permitted in 87.Xr capsicum 4 88capability mode (see 89.Xr cap_enter 2 ) . 90.El 91.Bl -tag -width ".Dv PD_DAEMON" 92.It Dv PD_CLOEXEC 93Set close-on-exec on process descriptor. 94.El 95.Pp 96The 97.Fn pdrfork 98system call is a variant of 99.Fn pdfork 100that also takes the 101.Fa rfflags 102argument to control sharing of process resources between the caller 103and the new process. 104Like 105.Fn pdfork , 106the function writes the process descriptor referencing the created 107process into the location pointed to by the 108.Fa fdp 109argument. 110See 111.Xr rfork 2 112for a description of the possible 113.Fa rfflag 114flags. 115The 116.Fn pdrfork 117system call requires that both the 118.Va RFPROC 119and 120.Va RFPROCDESC 121flags, or 122.Va RFSPAWN 123flag are specified. 124.Pp 125.Fn pdgetpid 126queries the process ID (PID) in the process descriptor 127.Fa fd . 128.Pp 129.Fn pdkill 130is functionally identical to 131.Xr kill 2 , 132except that it accepts a process descriptor, 133.Fa fd , 134rather than a PID. 135.Pp 136The 137.Fn pdwait 138system call allows the calling thread to wait and retrieve 139the status information on the process referenced by the 140.Fa fd 141process descriptor. 142See the description of the 143.Xr wait6 144system call for the behavior specification. 145.Pp 146The following system calls also have effects specific to process descriptors: 147.Pp 148.Xr fstat 2 149queries status of a process descriptor; currently only the 150.Fa st_mode , 151.Fa st_birthtime , 152.Fa st_atime , 153.Fa st_ctime 154and 155.Fa st_mtime 156fields are defined. 157If the owner read, write, and execute bits are set then the 158process represented by the process descriptor is still alive. 159.Pp 160.Xr poll 2 161and 162.Xr select 2 163allow waiting for process state transitions; currently only 164.Dv POLLHUP 165is defined, and will be raised when the process dies. 166Process state transitions can also be monitored using 167.Xr kqueue 2 168filter 169.Dv EVFILT_PROCDESC ; 170currently only 171.Dv NOTE_EXIT 172is implemented. 173.Pp 174.Xr close 2 175will close the process descriptor unless 176.Dv PD_DAEMON 177is set; if the process is still alive and this is 178the last reference to the process descriptor, the process will be terminated 179with the signal 180.Dv SIGKILL . 181The PID of the referenced process is not reused until the process 182descriptor is closed, 183whether or not the zombie process is reaped by 184.Fn pdwait , 185.Xr wait6 , 186or similar system calls. 187.Sh RETURN VALUES 188.Fn pdfork 189and 190.Fn pdrfork 191return a PID, 0 or -1, as 192.Xr fork 2 193does. 194.Pp 195.Fn pdgetpid , 196.Fn pdkill , 197and 198.Fn pdwait 199return 0 on success and -1 on failure. 200.Sh ERRORS 201These functions may return the same error numbers as their PID-based equivalents 202(e.g. 203.Fn pdfork 204may return the same error numbers as 205.Xr fork 2 ) , 206with the following additions: 207.Bl -tag -width Er 208.It Bq Er EFAULT 209The copyout of the resulting file descriptor value to the memory pointed 210to by 211.Fa fdp 212failed. 213.Pp 214Note that the child process was already created when this condition 215is detected, 216and the child continues execution, same as the parent. 217If this error must be handled, it is advisable to memoize the 218.Fn getpid 219result before the call to 220.Fn pdfork 221or 222.Fn pdrfork , 223and compare it to the value returned by 224.Fn getpid 225after, to see if code is executing in parent or child. 226.It Bq Er EINVAL 227The signal number given to 228.Fn pdkill 229is invalid. 230.It Bq Er ENOTCAPABLE 231The process descriptor being operated on has insufficient rights (e.g. 232.Dv CAP_PDKILL 233for 234.Fn pdkill ) . 235.El 236.Sh SEE ALSO 237.Xr close 2 , 238.Xr fork 2 , 239.Xr fstat 2 , 240.Xr kill 2 , 241.Xr kqueue 2 , 242.Xr poll 2 , 243.Xr wait4 2 , 244.Xr capsicum 4 , 245.Xr procdesc 4 246.Sh HISTORY 247The 248.Fn pdfork , 249.Fn pdgetpid , 250and 251.Fn pdkill 252system calls first appeared in 253.Fx 9.0 . 254The 255.Fn pdrfork 256and 257.Fn pdwait 258system calls first appeared in 259.Fx 16.0 . 260.Pp 261Support for process descriptors mode was developed as part of the 262.Tn TrustedBSD 263Project. 264.Sh AUTHORS 265.An -nosplit 266These functions and the capability facility were created by 267.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org 268and 269.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org 270at the University of Cambridge Computer Laboratory with support from a grant 271from Google, Inc. 272The 273.Fn pdrfork 274and 275.Fn pdwait 276functions were developed by 277.An Konstantin Belousov Aq Mt kib@FreeBSD.org 278with input from 279.An Alan Somers Aq Mt asomers@FreeBSD.org . 280