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