1 files changed, 279 insertions, 0 deletions
diff --git a/static/freebsd/man2/pdfork.2 b/static/freebsd/man2/pdfork.2
new file mode 100644
index 00000000..3997570d
--- /dev/null
+++ b/static/freebsd/man2/pdfork.2
@@ -0,0 +1,279 @@
+.\"
+.\" Copyright (c) 2009-2010, 2012-2013 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" This software was developed at the University of Cambridge Computer
+.\" Laboratory with support from a grant from Google, Inc.
+.\"
+.\" This software was developed by SRI International and the University of
+.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
+.\" ("CTSRD"), as part of the DARPA CRASH research programme.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd April 19, 2026
+.Dt PDFORK 2
+.Os
+.Sh NAME
+.Nm pdfork ,
+.Nm pdrfork ,
+.Nm pdgetpid ,
+.Nm pdkill ,
+.Nm pdwait
+.Nd System calls to manage process descriptors
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/procdesc.h
+.Ft pid_t
+.Fn pdfork "int *fdp" "int pdflags"
+.Ft pid_t
+.Fn pdrfork "int *fdp" "int pdflags" "int rfflags"
+.Ft int
+.Fn pdgetpid "int fd" "pid_t *pidp"
+.Ft int
+.Fn pdkill "int fd" "int signum"
+.Ft int
+.Fo pdwait
+.Fa "int fd"
+.Fa "int *status"
+.Fa "int options"
+.Fa "struct __wrusage *wrusage"
+.Fa "struct __siginfo *info"
+.Fc
+.Sh DESCRIPTION
+Process descriptors are special file descriptors that represent processes,
+and are created using
+.Fn pdfork ,
+a variant of
+.Xr fork 2 ,
+which, if successful, returns a process descriptor in the integer pointed to
+by
+.Fa fdp .
+Processes created via
+.Fn pdfork
+will not cause
+.Dv SIGCHLD
+on termination.
+.Fn pdfork
+can accept the
+.Fa pdflags:
+.Bl -tag -width PD_CLOEXEC
+.It Dv PD_DAEMON
+Instead of the default terminate-on-close behaviour, allow the process to
+live until it is explicitly killed with
+.Xr kill 2 .
+.Pp
+This option is not permitted in
+.Xr capsicum 4
+capability mode (see
+.Xr cap_enter 2 ) .
+.El
+.Bl -tag -width ".Dv PD_DAEMON"
+.It Dv PD_CLOEXEC
+Set close-on-exec on process descriptor.
+.El
+.Pp
+The
+.Fn pdrfork
+system call is a variant of
+.Fn pdfork
+that also takes the
+.Fa rfflags
+argument to control sharing of process resources between the caller
+and the new process.
+Like
+.Fn pdfork ,
+the function writes the process descriptor referencing the created
+process into the location pointed to by the
+.Fa fdp
+argument.
+See
+.Xr rfork 2
+for a description of the possible
+.Fa rfflag
+flags.
+The
+.Fn pdrfork
+system call requires that both the
+.Va RFPROC
+and
+.Va RFPROCDESC
+flags, or
+.Va RFSPAWN
+flag are specified.
+.Pp
+.Fn pdgetpid
+queries the process ID (PID) in the process descriptor
+.Fa fd .
+.Pp
+.Fn pdkill
+is functionally identical to
+.Xr kill 2 ,
+except that it accepts a process descriptor,
+.Fa fd ,
+rather than a PID.
+.Pp
+The
+.Fn pdwait
+system call allows the calling thread to wait and retrieve
+the status information on the process referenced by the
+.Fa fd
+process descriptor.
+See the description of the
+.Xr wait6
+system call for the behavior specification.
+.Pp
+The following system calls also have effects specific to process descriptors:
+.Pp
+.Xr fstat 2
+queries status of a process descriptor; currently only the
+.Fa st_mode ,
+.Fa st_birthtime ,
+.Fa st_atime ,
+.Fa st_ctime
+and
+.Fa 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.
+.Pp
+.Xr poll 2
+and
+.Xr select 2
+allow waiting for process state transitions; currently only
+.Dv POLLHUP
+is defined, and will be raised when the process dies.
+Process state transitions can also be monitored using
+.Xr kqueue 2
+filter
+.Dv EVFILT_PROCDESC ;
+currently only
+.Dv NOTE_EXIT
+is implemented.
+.Pp
+.Xr close 2
+will close the process descriptor unless
+.Dv 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
+.Dv 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
+.Fn pdwait ,
+.Xr wait6 ,
+or similar system calls.
+.Sh RETURN VALUES
+.Fn pdfork
+and
+.Fn pdrfork
+return a PID, 0 or -1, as
+.Xr fork 2
+does.
+.Pp
+.Fn pdgetpid ,
+.Fn pdkill ,
+and
+.Fn pdwait
+return 0 on success and -1 on failure.
+.Sh ERRORS
+These functions may return the same error numbers as their PID-based equivalents
+(e.g.
+.Fn pdfork
+may return the same error numbers as
+.Xr fork 2 ) ,
+with the following additions:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+The copyout of the resulting file descriptor value to the memory pointed
+to by
+.Fa fdp
+failed.
+.Pp
+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
+.Fn getpid
+result before the call to
+.Fn pdfork
+or
+.Fn pdrfork ,
+and compare it to the value returned by
+.Fn getpid
+after, to see if code is executing in parent or child.
+.It Bq Er EINVAL
+The signal number given to
+.Fn pdkill
+is invalid.
+.It Bq Er ENOTCAPABLE
+The process descriptor being operated on has insufficient rights (e.g.
+.Dv CAP_PDKILL
+for
+.Fn pdkill ) .
+.El
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr fork 2 ,
+.Xr fstat 2 ,
+.Xr kill 2 ,
+.Xr kqueue 2 ,
+.Xr poll 2 ,
+.Xr wait4 2 ,
+.Xr capsicum 4 ,
+.Xr procdesc 4
+.Sh HISTORY
+The
+.Fn pdfork ,
+.Fn pdgetpid ,
+and
+.Fn pdkill
+system calls first appeared in
+.Fx 9.0 .
+The
+.Fn pdrfork
+and
+.Fn pdwait
+system calls first appeared in
+.Fx 15.1 .
+.Pp
+Support for process descriptors mode was developed as part of the
+.Tn TrustedBSD
+Project.
+.Sh AUTHORS
+.An -nosplit
+These functions and the capability facility were created by
+.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org
+and
+.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org
+at the University of Cambridge Computer Laboratory with support from a grant
+from Google, Inc.
+The
+.Fn pdrfork
+and
+.Fn pdwait
+functions were developed by
+.An Konstantin Belousov Aq Mt kib@FreeBSD.org
+with input from
+.An Alan Somers Aq Mt asomers@FreeBSD.org .