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 February 25, 2012
  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 identically 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.
 105 If the owner read, write, and execute bits are set then the
 106 process represented by the process descriptor is still alive.
 107 .Pp
 108 .Xr poll 2
 109 and
 110 .Xr select 2
 111 allow waiting for process state transitions; currently only
 112 .Dv POLLHUP
 113 is defined, and will be raised when the process dies.
 114 .Pp
 115 .Xr close 2
 116 will close the process descriptor unless
 117 .Dv PD_DAEMON
 118 is set; if the process is still alive and this is
 119 the last reference to the process descriptor, the process will be terminated
 120 with the signal
 121 .Dv SIGKILL .
 122 .Sh RETURN VALUES
 123 .Fn pdfork
 124 returns a PID, 0 or -1, as
 125 .Xr fork 2
 126 does.
 127 .Pp
 128 .Fn pdgetpid
 129 and
 130 .Fn pdkill
 131 return 0 on success and -1 on failure.
 132 .Pp
 133 .Fn pdwait4
 134 returns a PID on success and -1 on failure.
 135 .Sh ERRORS
 136 These functions may return the same error numbers as their PID-based equivalents
 137 (e.g.
 138 .Fn pdfork
 139 may return the same error numbers as
 140 .Xr fork 2 ) ,
 141 with the following additions:
 142 .Bl -tag -width Er
 143 .It Bq Er EINVAL
 144 The signal number given to
 145 .Fn pdkill
 146 is invalid.
 147 .It Bq Er ENOTCAPABLE
 148 The process descriptor being operated on has insufficient rights (e.g.
 149 .Dv CAP_PDKILL
 150 for
 151 .Fn pdkill ) .
 152 .El
 153 .Sh SEE ALSO
 154 .Xr close 2 ,
 155 .Xr fork 2 ,
 156 .Xr fstat 2 ,
 157 .Xr kill 2 ,
 158 .Xr poll 2 ,
 159 .Xr wait4 2
 160 .Sh HISTORY
 161 The
 162 .Fn pdfork ,
 163 .Fn pdgetpid ,
 164 .Fn pdkill
 165 and
 166 .Fn pdwait4
 167 system calls first appeared in
 168 .Fx 9.0 .
 169 .Pp
 170 Support for process descriptors mode was developed as part of the
 171 .Tn TrustedBSD
 172 Project.
 173 .Sh AUTHORS
 174 .An -nosplit
 175 These functions and the capability facility were created by
 176 .An "Robert N. M. Watson" Aq rwatson@FreeBSD.org
 177 and
 178 .An "Jonathan Anderson" Aq jonathan@FreeBSD.org
 179 at the University of Cambridge Computer Laboratory with support from a grant
 180 from Google, Inc.
 181 .Sh BUGS
 182 .Fn pdwait4
 183 has not yet been implemented.