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,
90 behaves identically to
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
105 If the owner read, write, and execute bits are set then the
106 process represented by the process descriptor is still alive.
111 allow waiting for process state transitions; currently only
113 is defined, and will be raised when the process dies.
116 will close the process descriptor unless
118 is set; if the process is still alive and this is
119 the last reference to the process descriptor, the process will be terminated
124 returns a PID, 0 or -1, as
131 return 0 on success and -1 on failure.
134 returns a PID on success and -1 on failure.
136 These functions may return the same error numbers as their PID-based equivalents
139 may return the same error numbers as
141 with the following additions:
144 The signal number given to
147 .It Bq Er ENOTCAPABLE
148 The process descriptor being operated on has insufficient rights (e.g.
167 system calls first appeared in
170 Support for process descriptors mode was developed as part of the
175 These functions and the capability facility were created by
176 .An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
178 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
179 at the University of Cambridge Computer Laboratory with support from a grant
183 has not yet been implemented.