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