lib/libc/sys/rfork.2

   1 .\"
   2 .\" This manual page is taken directly from Plan9, and modified to
   3 .\" describe the actual BSD implementation. Permission for
   4 .\" use of this page comes from Rob Pike <rob@plan9.att.com>.
   5 .\"
   6 .\" $FreeBSD$
   7 .\"
   8 .Dd September 25, 2019
   9 .Dt RFORK 2
  10 .Os
  11 .Sh NAME
  12 .Nm rfork
  13 .Nd manipulate process resources
  14 .Sh LIBRARY
  15 .Lb libc
  16 .Sh SYNOPSIS
  17 .In unistd.h
  18 .Ft pid_t
  19 .Fn rfork "int flags"
  20 .Sh DESCRIPTION
  21 Forking, vforking or rforking are the only ways new processes are created.
  22 The
  23 .Fa flags
  24 argument to
  25 .Fn rfork
  26 selects which resources of the
  27 invoking process (parent) are shared
  28 by the new process (child) or initialized to
  29 their default values.
  30 The resources include
  31 the open file descriptor table (which, when shared, permits processes
  32 to open and close files for other processes),
  33 and open files.
  34 The
  35 .Fa flags
  36 argument
  37 is either
  38 .Dv RFSPAWN
  39 or the logical OR of some subset of:
  40 .Bl -tag -width ".Dv RFLINUXTHPN"
  41 .It Dv RFPROC
  42 If set a new process is created; otherwise changes affect the
  43 current process.
  44 .It Dv RFNOWAIT
  45 If set, the child process will be dissociated from the parent.
  46 Upon
  47 exit the child will not leave a status for the parent to collect.
  48 See
  49 .Xr wait 2 .
  50 .It Dv RFFDG
  51 If set, the invoker's file descriptor table (see
  52 .Xr intro 2 )
  53 is copied; otherwise the two processes share a
  54 single table.
  55 .It Dv RFCFDG
  56 If set, the new process starts with a clean file descriptor table.
  57 Is mutually exclusive with
  58 .Dv RFFDG .
  59 .It Dv RFTHREAD
  60 If set, the new process shares file descriptor to process leaders table
  61 with its parent.
  62 Only applies when neither
  63 .Dv RFFDG
  64 nor
  65 .Dv RFCFDG
  66 are set.
  67 .It Dv RFMEM
  68 If set, the kernel will force sharing of the entire address space,
  69 typically by sharing the hardware page table directly.
  70 The child
  71 will thus inherit and share all the segments the parent process owns,
  72 whether they are normally shareable or not.
  73 The stack segment is
  74 not split (both the parent and child return on the same stack) and thus
  75 .Fn rfork
  76 with the RFMEM flag may not generally be called directly from high level
  77 languages including C.
  78 May be set only with
  79 .Dv RFPROC .
  80 A helper function is provided to assist with this problem and will cause
  81 the new process to run on the provided stack.
  82 See
  83 .Xr rfork_thread 3
  84 for information.
  85 Note that a lot of code will not run correctly in such an environment.
  86 .It Dv RFSIGSHARE
  87 If set, the kernel will force sharing the sigacts structure between the
  88 child and the parent.
  89 .It Dv RFTSIGZMB
  90 If set, the kernel will deliver a specified signal to the parent
  91 upon the child exit, instead of default SIGCHLD.
  92 The signal number
  93 .Dv signum
  94 is specified by oring the
  95 .Dv RFTSIGFLAGS(signum)
  96 expression into
  97 .Fa flags .
  98 Specifying signal number 0 disables signal delivery upon the child exit.
  99 .It Dv RFLINUXTHPN
 100 If set, the kernel will deliver SIGUSR1 instead of SIGCHLD upon thread
 101 exit for the child.
 102 This is intended to mimic certain Linux clone behaviour.
 103 .El
 104 .Pp
 105 File descriptors in a shared file descriptor table are kept
 106 open until either they are explicitly closed
 107 or all processes sharing the table exit.
 108 .Pp
 109 If
 110 .Dv RFSPAWN
 111 is passed,
 112 .Nm
 113 will use
 114 .Xr vfork 2
 115 semantics but reset all signal actions in the child to default.
 116 This flag is used by the
 117 .Xr posix_spawn 3
 118 implementation in libc.
 119 .Pp
 120 If
 121 .Dv RFPROC
 122 is set, the
 123 value returned in the parent process
 124 is the process id
 125 of the child process; the value returned in the child is zero.
 126 Without
 127 .Dv RFPROC ,
 128 the return value is zero.
 129 Process id's range from 1 to the maximum integer
 130 .Ft ( int )
 131 value.
 132 The
 133 .Fn rfork
 134 system call
 135 will sleep, if necessary, until required process resources are available.
 136 .Pp
 137 The
 138 .Fn fork
 139 system call
 140 can be implemented as a call to
 141 .Fn rfork "RFFDG | RFPROC"
 142 but is not for backwards compatibility.
 143 .Sh RETURN VALUES
 144 Upon successful completion,
 145 .Fn rfork
 146 returns a value
 147 of 0 to the child process and returns the process ID of the child
 148 process to the parent process.
 149 Otherwise, a value of -1 is returned
 150 to the parent process, no child process is created, and the global
 151 variable
 152 .Va errno
 153 is set to indicate the error.
 154 .Sh ERRORS
 155 The
 156 .Fn rfork
 157 system call
 158 will fail and no child process will be created if:
 159 .Bl -tag -width Er
 160 .It Bq Er EAGAIN
 161 The system-imposed limit on the total
 162 number of processes under execution would be exceeded.
 163 The limit is given by the
 164 .Xr sysctl 3
 165 MIB variable
 166 .Dv KERN_MAXPROC .
 167 (The limit is actually ten less than this
 168 except for the super user).
 169 .It Bq Er EAGAIN
 170 The user is not the super user, and
 171 the system-imposed limit
 172 on the total number of
 173 processes under execution by a single user would be exceeded.
 174 The limit is given by the
 175 .Xr sysctl 3
 176 MIB variable
 177 .Dv KERN_MAXPROCPERUID .
 178 .It Bq Er EAGAIN
 179 The user is not the super user, and
 180 the soft resource limit corresponding to the
 181 .Fa resource
 182 argument
 183 .Dv RLIMIT_NOFILE
 184 would be exceeded (see
 185 .Xr getrlimit 2 ) .
 186 .It Bq Er EINVAL
 187 Both the RFFDG and the RFCFDG flags were specified.
 188 .It Bq Er EINVAL
 189 Any flags not listed above were specified.
 190 .It Bq Er EINVAL
 191 An invalid signal number was specified.
 192 .It Bq Er ENOMEM
 193 There is insufficient swap space for the new process.
 194 .El
 195 .Sh SEE ALSO
 196 .Xr fork 2 ,
 197 .Xr intro 2 ,
 198 .Xr minherit 2 ,
 199 .Xr vfork 2 ,
 200 .Xr pthread_create 3 ,
 201 .Xr rfork_thread 3
 202 .Sh HISTORY
 203 The
 204 .Fn rfork
 205 function first appeared in Plan9.