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.\" $FreeBSD: stable/10/lib/libc/sys/pdfork.2 255002 2013-08-28 20:00:25Z rwatson $
34.\"
35.Dd August 28, 2013
36.Dt PDFORK 2
37.Os
38.Sh NAME
39.Nm pdfork ,
40.Nm pdgetpid ,
41.Nm pdkill ,
42.Nm pdwait4
43.Nd System calls to manage process descriptors
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In sys/procdesc.h
48.Ft int
49.Fn pdfork "int *fdp" "int flags"
50.Ft int
51.Fn pdgetpid "int fd" "pid_t *pidp"
52.Ft int
53.Fn pdkill "int fd" "int signum"
54.Ft int
55.Fn pdwait4 "int fd" "int *status" "int options" "struct rusage *rusage"
56.Sh DESCRIPTION
57Process descriptors are special file descriptors that represent processes,
58and are created using
59.Fn pdfork ,
60a variant of
61.Xr fork 2 ,
62which, if successful, returns a process descriptor in the integer pointed to
63by
64.Fa fdp .
65Processes created via
66.Fn pdfork
67will not cause
68.Dv SIGCHLD
69on termination.
70.Fn pdfork
71can accept the flags:
72.Bl -tag -width ".Dv PD_DAEMON"
73.It Dv PD_DAEMON
74Instead of the default terminate-on-close behaviour, allow the process to
75live until it is explicitly killed with
76.Xr kill 2 .
77.Pp
78This option is not permitted in
79.Xr capsicum 4
80capability mode (see
81.Xr cap_enter 2 ) .
82.El
83.Pp
84.Fn pdgetpid
85queries the process ID (PID) in the process descriptor
86.Fa fd .
87.Pp
88.Fn pdkill
89is functionally identical to
90.Xr kill 2 ,
91except that it accepts a process descriptor,
92.Fa fd ,
93rather than a PID.
94.Pp
95.Fn pdwait4
96behaves identically to
97.Xr wait4 2 ,
98but operates with respect to a process descriptor argument rather than a PID.
99.Pp
100The following system calls also have effects specific to process descriptors:
101.Pp
102.Xr fstat 2
103queries status of a process descriptor; currently only the
104.Fa st_mode ,
105.Fa st_birthtime ,
106.Fa st_atime ,
107.Fa st_ctime
108and
109.Fa st_mtime
110fields are defined.
111If the owner read, write, and execute bits are set then the
112process represented by the process descriptor is still alive.
113.Pp
114.Xr poll 2
115and
116.Xr select 2
117allow waiting for process state transitions; currently only
118.Dv POLLHUP
119is defined, and will be raised when the process dies.
120.Pp
121.Xr close 2
122will close the process descriptor unless
123.Dv PD_DAEMON
124is set; if the process is still alive and this is
125the last reference to the process descriptor, the process will be terminated
126with the signal
127.Dv SIGKILL .
128.Pp
129.Nm
130and associated functions depend on
131.Cd "options PROCDESC"
132described in
133.Xr procdesc 4 .
134.Sh RETURN VALUES
135.Fn pdfork
136returns a PID, 0 or -1, as
137.Xr fork 2
138does.
139.Pp
140.Fn pdgetpid
141and
142.Fn pdkill
143return 0 on success and -1 on failure.
144.Pp
145.Fn pdwait4
146returns a PID on success and -1 on failure.
147.Sh ERRORS
148These functions may return the same error numbers as their PID-based equivalents
149(e.g.
150.Fn pdfork
151may return the same error numbers as
152.Xr fork 2 ) ,
153with the following additions:
154.Bl -tag -width Er
155.It Bq Er EINVAL
156The signal number given to
157.Fn pdkill
158is invalid.
159.It Bq Er ENOTCAPABLE
160The process descriptor being operated on has insufficient rights (e.g.
161.Dv CAP_PDKILL
162for
163.Fn pdkill ) .
164.El
165.Sh SEE ALSO
166.Xr close 2 ,
167.Xr fork 2 ,
168.Xr fstat 2 ,
169.Xr kill 2 ,
170.Xr poll 2 ,
171.Xr wait4 2 ,
172.Xr capsicum 4 ,
173.Xr procdesc 4
174.Sh HISTORY
175The
176.Fn pdfork ,
177.Fn pdgetpid ,
178.Fn pdkill
179and
180.Fn pdwait4
181system calls first appeared in
182.Fx 9.0 .
183.Pp
184Support for process descriptors mode was developed as part of the
185.Tn TrustedBSD
186Project.
187.Sh AUTHORS
188.An -nosplit
189These functions and the capability facility were created by
190.An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
191and
192.An "Jonathan Anderson" Aq jonathan@FreeBSD.org
193at the University of Cambridge Computer Laboratory with support from a grant
194from Google, Inc.
195.Sh BUGS
196.Fn pdwait4
197has not yet been implemented.
198