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$ 34.\" 35.Dd June 8, 2016 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 pid_t 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.Bl -tag -width ".Dv PD_DAEMON" 84.It Dv PD_CLOEXEC 85Set close-on-exec on process descriptor. 86.El 87.Pp 88.Fn pdgetpid 89queries the process ID (PID) in the process descriptor 90.Fa fd . 91.Pp 92.Fn pdkill 93is functionally identical to 94.Xr kill 2 , 95except that it accepts a process descriptor, 96.Fa fd , 97rather than a PID. 98.Pp 99.Fn pdwait4 100behaves identically to 101.Xr wait4 2 , 102but operates with respect to a process descriptor argument rather than a PID. 103.Pp 104The following system calls also have effects specific to process descriptors: 105.Pp 106.Xr fstat 2 107queries status of a process descriptor; currently only the 108.Fa st_mode , 109.Fa st_birthtime , 110.Fa st_atime , 111.Fa st_ctime 112and 113.Fa st_mtime 114fields are defined. 115If the owner read, write, and execute bits are set then the 116process represented by the process descriptor is still alive. 117.Pp 118.Xr poll 2 119and 120.Xr select 2 121allow waiting for process state transitions; currently only 122.Dv POLLHUP 123is defined, and will be raised when the process dies. 124Process state transitions can also be monitored using 125.Xr kqueue 2 126filter 127.Dv EVFILT_PROCDESC ; 128currently only 129.Dv NOTE_EXIT 130is implemented. 131.Pp 132.Xr close 2 133will close the process descriptor unless 134.Dv PD_DAEMON 135is set; if the process is still alive and this is 136the last reference to the process descriptor, the process will be terminated 137with the signal 138.Dv SIGKILL . 139.Sh RETURN VALUES 140.Fn pdfork 141returns a PID, 0 or -1, as 142.Xr fork 2 143does. 144.Pp 145.Fn pdgetpid 146and 147.Fn pdkill 148return 0 on success and -1 on failure. 149.Pp 150.Fn pdwait4 151returns a PID on success and -1 on failure. 152.Sh ERRORS 153These functions may return the same error numbers as their PID-based equivalents 154(e.g. 155.Fn pdfork 156may return the same error numbers as 157.Xr fork 2 ) , 158with the following additions: 159.Bl -tag -width Er 160.It Bq Er EINVAL 161The signal number given to 162.Fn pdkill 163is invalid. 164.It Bq Er ENOTCAPABLE 165The process descriptor being operated on has insufficient rights (e.g. 166.Dv CAP_PDKILL 167for 168.Fn pdkill ) . 169.El 170.Sh SEE ALSO 171.Xr close 2 , 172.Xr fork 2 , 173.Xr fstat 2 , 174.Xr kill 2 , 175.Xr poll 2 , 176.Xr wait4 2 , 177.Xr capsicum 4 , 178.Xr procdesc 4 179.Sh HISTORY 180The 181.Fn pdfork , 182.Fn pdgetpid , 183.Fn pdkill 184and 185.Fn pdwait4 186system calls first appeared in 187.Fx 9.0 . 188.Pp 189Support for process descriptors mode was developed as part of the 190.Tn TrustedBSD 191Project. 192.Sh AUTHORS 193.An -nosplit 194These functions and the capability facility were created by 195.An Robert N. M. Watson Aq Mt [email protected] 196and 197.An Jonathan Anderson Aq Mt [email protected] 198at the University of Cambridge Computer Laboratory with support from a grant 199from Google, Inc. 200.Sh BUGS 201.Fn pdwait4 202has not yet been implemented. 203