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 August 28, 2013
  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 int
  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 .Pp
 121 .Xr close 2
 122 will close the process descriptor unless
 123 .Dv PD_DAEMON
 124 is set; if the process is still alive and this is
 125 the last reference to the process descriptor, the process will be terminated
 126 with the signal
 127 .Dv SIGKILL .
 128 .Pp
 129 .Nm
 130 and associated functions depend on
 131 .Cd "options PROCDESC"
 132 described in
 133 .Xr procdesc 4 .
 134 .Sh RETURN VALUES
 135 .Fn pdfork
 136 returns a PID, 0 or -1, as
 137 .Xr fork 2
 138 does.
 139 .Pp
 140 .Fn pdgetpid
 141 and
 142 .Fn pdkill
 143 return 0 on success and -1 on failure.
 144 .Pp
 145 .Fn pdwait4
 146 returns a PID on success and -1 on failure.
 147 .Sh ERRORS
 148 These functions may return the same error numbers as their PID-based equivalents
 149 (e.g.
 150 .Fn pdfork
 151 may return the same error numbers as
 152 .Xr fork 2 ) ,
 153 with the following additions:
 154 .Bl -tag -width Er
 155 .It Bq Er EINVAL
 156 The signal number given to
 157 .Fn pdkill
 158 is invalid.
 159 .It Bq Er ENOTCAPABLE
 160 The process descriptor being operated on has insufficient rights (e.g.
 161 .Dv CAP_PDKILL
 162 for
 163 .Fn pdkill ) .
 164 .El
 165 .Sh SEE ALSO
 166 .Xr close 2 ,
 167 .Xr fork 2 ,
 168 .Xr fstat 2 ,
 169 .Xr kill 2 ,
 170 .Xr poll 2 ,
 171 .Xr wait4 2 ,
 172 .Xr capsicum 4 ,
 173 .Xr procdesc 4
 174 .Sh HISTORY
 175 The
 176 .Fn pdfork ,
 177 .Fn pdgetpid ,
 178 .Fn pdkill
 179 and
 180 .Fn pdwait4
 181 system calls first appeared in
 182 .Fx 9.0 .
 183 .Pp
 184 Support for process descriptors mode was developed as part of the
 185 .Tn TrustedBSD
 186 Project.
 187 .Sh AUTHORS
 188 .An -nosplit
 189 These functions and the capability facility were created by
 190 .An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
 191 and
 192 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
 193 at the University of Cambridge Computer Laboratory with support from a grant
 194 from Google, Inc.
 195 .Sh BUGS
 196 .Fn pdwait4
 197 has not yet been implemented.