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