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 .Sh RETURN VALUES
 129 .Fn pdfork
 130 returns a PID, 0 or -1, as
 131 .Xr fork 2
 132 does.
 133 .Pp
 134 .Fn pdgetpid
 135 and
 136 .Fn pdkill
 137 return 0 on success and -1 on failure.
 138 .Pp
 139 .Fn pdwait4
 140 returns a PID 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 poll 2 ,
 165 .Xr wait4 2 ,
 166 .Xr capsicum 4 ,
 167 .Xr procdesc 4
 168 .Sh HISTORY
 169 The
 170 .Fn pdfork ,
 171 .Fn pdgetpid ,
 172 .Fn pdkill
 173 and
 174 .Fn pdwait4
 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 rwatson@FreeBSD.org
 185 and
 186 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
 187 at the University of Cambridge Computer Laboratory with support from a grant
 188 from Google, Inc.
 189 .Sh BUGS
 190 .Fn pdwait4
 191 has not yet been implemented.