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