lib/libc/sys/pdfork.2

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