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 April 7, 2014 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.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. 120Process state transitions can also be monitored using 121.Xr kqueue 2 122filter 123.Dv EVFILT_PROCDESC ; 124currently only 125.Dv NOTE_EXIT 126is implemented. 127.Pp 128.Xr close 2 129will close the process descriptor unless 130.Dv PD_DAEMON 131is set; if the process is still alive and this is 132the last reference to the process descriptor, the process will be terminated 133with the signal 134.Dv SIGKILL . 135.Sh RETURN VALUES 136.Fn pdfork 137returns a PID, 0 or -1, as 138.Xr fork 2 139does. 140.Pp 141.Fn pdgetpid 142and 143.Fn pdkill 144return 0 on success and -1 on failure. 145.Pp 146.Fn pdwait4 147returns a PID on success and -1 on failure. 148.Sh ERRORS 149These functions may return the same error numbers as their PID-based equivalents 150(e.g. 151.Fn pdfork 152may return the same error numbers as 153.Xr fork 2 ) , 154with the following additions: 155.Bl -tag -width Er 156.It Bq Er EINVAL 157The signal number given to 158.Fn pdkill 159is invalid. 160.It Bq Er ENOTCAPABLE 161The process descriptor being operated on has insufficient rights (e.g. 162.Dv CAP_PDKILL 163for 164.Fn pdkill ) . 165.El 166.Sh SEE ALSO 167.Xr close 2 , 168.Xr fork 2 , 169.Xr fstat 2 , 170.Xr kill 2 , 171.Xr poll 2 , 172.Xr wait4 2 , 173.Xr capsicum 4 , 174.Xr procdesc 4 175.Sh HISTORY 176The 177.Fn pdfork , 178.Fn pdgetpid , 179.Fn pdkill 180and 181.Fn pdwait4 182system calls first appeared in 183.Fx 9.0 . 184.Pp 185Support for process descriptors mode was developed as part of the 186.Tn TrustedBSD 187Project. 188.Sh AUTHORS 189.An -nosplit 190These functions and the capability facility were created by 191.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org 192and 193.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org 194at the University of Cambridge Computer Laboratory with support from a grant 195from Google, Inc. 196.Sh BUGS 197.Fn pdwait4 198has not yet been implemented. 199