lib/libc/sys/pdfork.2

   1 .\"
   2 .\" Copyright (c) 2009-2010 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 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd August 16, 2011
  32 .Dt PDFORK 2
  33 .Os
  34 .Sh NAME
  35 .Nm pdfork ,
  36 .Nm pdgetpid ,
  37 .Nm pdkill ,
  38 .Nm pdwait4
  39 .Nd System calls to manage process descriptors
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/procdesc.h
  44 .Ft int
  45 .Fn pdfork "int *fdp" "int flags"
  46 .Ft int
  47 .Fn pdgetpid "int fd" "pid_t *pidp"
  48 .Ft int
  49 .Fn pdkill "int fd" "int signum"
  50 .Ft int
  51 .Fn pdwait4 "int fd" "int *status" "int options" "struct rusage *rusage"
  52 .Sh DESCRIPTION
  53 Process descriptors are special file descriptors that represent processes,
  54 and are created using
  55 .Fn pdfork ,
  56 a variant of
  57 .Xr fork 2 ,
  58 which, if successful, returns a process descriptor in the integer pointed to
  59 by
  60 .Fa pidp .
  61 Processes created via
  62 .Fn pdfork
  63 will not cause
  64 .Dv SIGCHLD
  65 on termination.
  66 .Fn pdfork
  67 can accept the flags:
  68 .Bl -tag -width ".Dv PD_DAEMON"
  69 .It Dv PD_DAEMON
  70 Instead of the default terminate-on-close behaviour, allow the process to
  71 live until it is explicitly killed with
  72 .Xr kill 2 .
  73 .Pp
  74 This option is not permitted in Capsicum capability mode (see
  75 .Xr cap_enter 2 ) .
  76 .El
  77 .Pp
  78 .Fn pdgetpid
  79 queries the process ID (PID) if the process descriptor
  80 .Fa fd .
  81 .Pp
  82 .Fn pdkill
  83 is functionally identical to
  84 .Xr kill 2 ,
  85 except that it accepts a process descriptor,
  86 .Fa fd ,
  87 rather than a PID.
  88 .Pp
  89 .Fn pdwait4
  90 behaves identially to
  91 .Xr wait4 2 ,
  92 but operates with respect to a process descriptor argument 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. If the owner read, write, and execute bits are set then the
 105 process represented by the process descriptor is still alive.
 106 .Pp
 107 .Xr poll 2
 108 and
 109 .Xr select 2
 110 allow waiting for process state transitions; currently only
 111 .Dv POLLHUP
 112 is defined, and will be raised when the process dies.
 113 .Pp
 114 .Xr close 2
 115 will close the process descriptor unless
 116 .Dv PD_DAEMON
 117 is set; if the process is still alive and this is
 118 the last reference to the process descriptor, the process will be terminated
 119 with the signal
 120 .Dv SIGKILL .
 121 .Sh RETURN VALUES
 122 .Fn pdfork
 123 returns a PID, 0 or -1, as
 124 .Xr fork 2
 125 does.
 126 .Pp
 127 .Fn pdgetpid
 128 and
 129 .Fn pdkill
 130 return 0 on success and -1 on failure.
 131 .Pp
 132 .Fn pdwait4
 133 returns a PID on success and -1 on failure.
 134 .Sh ERRORS
 135 These functions may return the same error numbers as their PID-based equivalents
 136 (e.g.
 137 .Fn pdfork
 138 may return the same error numbers as
 139 .Xr fork 2 ) ,
 140 with the following additions:
 141 .Bl -tag -width Er
 142 .It Bq Er EINVAL
 143 The signal number given to
 144 .Fn pdkill
 145 is invalid.
 146 .It Bq Er ENOTCAPABLE
 147 The process descriptor being operated on has insufficient rights (e.g.
 148 .Dv CAP_PDKILL
 149 for
 150 .Fn pdkill ) .
 151 .El
 152 .Sh SEE ALSO
 153 .Xr close 2 ,
 154 .Xr fork 2 ,
 155 .Xr fstat 2 ,
 156 .Xr kill 2 ,
 157 .Xr poll 2 ,
 158 .Xr wait4 2
 159 .Sh HISTORY
 160 The
 161 .Fn pdfork ,
 162 .Fn pdgetpid ,
 163 .Fn pdkill
 164 and
 165 .Fn pdwait4
 166 system calls first appeared in
 167 .Fx 9.0 .
 168 .Pp
 169 Support for process descriptors mode was developed as part of the
 170 .Tn TrustedBSD
 171 Project.
 172 .Sh AUTHORS
 173 .An -nosplit
 174 These functions and the capability facility were created by
 175 .An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
 176 and
 177 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
 178 at the University of Cambridge Computer Laboratory with support from a grant
 179 from Google, Inc.
 180 .Sh BUGS
 181 .Fn pdwait4
 182 has not yet been implemented.