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