2 .\" Copyright (c) 2009-2010 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" This software was developed at the University of Cambridge Computer
6 .\" Laboratory with support from a grant from Google, Inc.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nd System calls to manage process descriptors
45 .Fn pdfork "int *fdp" "int flags"
47 .Fn pdgetpid "int fd" "pid_t *pidp"
49 .Fn pdkill "int fd" "int signum"
51 .Fn pdwait4 "int fd" "int *status" "int options" "struct rusage *rusage"
53 Process descriptors are special file descriptors that represent processes,
58 which, if successful, returns a process descriptor in the integer pointed to
68 .Bl -tag -width ".Dv PD_DAEMON"
70 Instead of the default terminate-on-close behaviour, allow the process to
71 live until it is explicitly killed with
74 This option is not permitted in Capsicum capability mode (see
79 queries the process ID (PID) if the process descriptor
83 is functionally identical to
85 except that it accepts a process descriptor,
92 but operates with respect to a process descriptor argument rather than a PID.
94 The following system calls also have effects specific to process descriptors:
97 queries status of a process descriptor; currently only the
104 fields are defined. If the owner read, write, and execute bits are set then the
105 process represented by the process descriptor is still alive.
110 allow waiting for process state transitions; currently only
112 is defined, and will be raised when the process dies.
115 will close the process descriptor unless
117 is set; if the process is still alive and this is
118 the last reference to the process descriptor, the process will be terminated
123 returns a PID, 0 or -1, as
130 return 0 on success and -1 on failure.
133 returns a PID on success and -1 on failure.
135 These functions may return the same error numbers as their PID-based equivalents
138 may return the same error numbers as
140 with the following additions:
143 The signal number given to
146 .It Bq Er ENOTCAPABLE
147 The process descriptor being operated on has insufficient rights (e.g.
166 system calls first appeared in
169 Support for process descriptors mode was developed as part of the
174 These functions and the capability facility were created by
175 .An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
177 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
178 at the University of Cambridge Computer Laboratory with support from a grant
182 has not yet been implemented.