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