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 May 14, 2007
   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 .It Dv RFSIGSHARE
  84 If set, the kernel will force sharing the sigacts structure between the
  85 child and the parent.
  86 .It Dv RFLINUXTHPN
  87 If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread
  88 exit for the child.
  89 This is intended to mimic certain Linux clone behaviour.
  90 .El
  91 .Pp
  92 File descriptors in a shared file descriptor table are kept
  93 open until either they are explicitly closed
  94 or all processes sharing the table exit.
  95 .Pp
  96 If
  97 .Dv RFPROC
  98 is set, the
  99 value returned in the parent process
 100 is the process id
 101 of the child process; the value returned in the child is zero.
 102 Without
 103 .Dv RFPROC ,
 104 the return value is zero.
 105 Process id's range from 1 to the maximum integer
 106 .Ft ( int )
 107 value.
 108 The
 109 .Fn rfork
 110 system call
 111 will sleep, if necessary, until required process resources are available.
 112 .Pp
 113 The
 114 .Fn fork
 115 system call
 116 can be implemented as a call to
 117 .Fn rfork "RFFDG | RFPROC"
 118 but is not for backwards compatibility.
 119 .Sh RETURN VALUES
 120 Upon successful completion,
 121 .Fn rfork
 122 returns a value
 123 of 0 to the child process and returns the process ID of the child
 124 process to the parent process.
 125 Otherwise, a value of -1 is returned
 126 to the parent process, no child process is created, and the global
 127 variable
 128 .Va errno
 129 is set to indicate the error.
 130 .Sh ERRORS
 131 The
 132 .Fn rfork
 133 system call
 134 will fail and no child process will be created if:
 135 .Bl -tag -width Er
 136 .It Bq Er EAGAIN
 137 The system-imposed limit on the total
 138 number of processes under execution would be exceeded.
 139 The limit is given by the
 140 .Xr sysctl 3
 141 MIB variable
 142 .Dv KERN_MAXPROC .
 143 (The limit is actually ten less than this
 144 except for the super user).
 145 .It Bq Er EAGAIN
 146 The user is not the super user, and
 147 the system-imposed limit
 148 on the total number of
 149 processes under execution by a single user would be exceeded.
 150 The limit is given by the
 151 .Xr sysctl 3
 152 MIB variable
 153 .Dv KERN_MAXPROCPERUID .
 154 .It Bq Er EAGAIN
 155 The user is not the super user, and
 156 the soft resource limit corresponding to the
 157 .Fa resource
 158 argument
 159 .Dv RLIMIT_NOFILE
 160 would be exceeded (see
 161 .Xr getrlimit 2 ) .
 162 .It Bq Er EINVAL
 163 Both the RFFDG and the RFCFDG flags were specified.
 164 .It Bq Er EINVAL
 165 Any flags not listed above were specified.
 166 .It Bq Er ENOMEM
 167 There is insufficient swap space for the new process.
 168 .El
 169 .Sh SEE ALSO
 170 .Xr fork 2 ,
 171 .Xr intro 2 ,
 172 .Xr minherit 2 ,
 173 .Xr vfork 2 ,
 174 .Xr rfork_thread 3
 175 .Sh HISTORY
 176 The
 177 .Fn rfork
 178 function first appeared in Plan9.
 179 .Sh BUGS
 180 .Fx
 181 does not yet implement a native
 182 .Fn clone
 183 library call, and the current pthreads implementation does not use
 184 .Fn rfork
 185 with RFMEM.
 186 A native port of the linux threads library,
 187 .Pa /usr/ports/devel/linuxthreads ,
 188 contains a working
 189 .Fn clone
 190 call that utilizes RFMEM.
 191 The
 192 .Xr rfork_thread 3
 193 function can often be used instead of
 194 .Fn clone .