lib/libc/sys/rfork.2

   1 .\"
   2 .\" This manual page is taken directly from Plan 9, 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: src/lib/libc/sys/rfork.2,v 1.11.2.11 2002/07/30 19:04:25 silby Exp $
   7 .\" $DragonFly: src/lib/libc/sys/rfork.2,v 1.7 2007/12/08 23:20:29 swildner Exp $
   8 .\"
   9 .Dd January 12, 1996
  10 .Dt RFORK 2
  11 .Os
  12 .Sh NAME
  13 .Nm rfork
  14 .Nd manipulate process resources
  15 .Sh LIBRARY
  16 .Lb libc
  17 .Sh SYNOPSIS
  18 .In unistd.h
  19 .Ft int
  20 .Fn rfork "int flags"
  21 .Sh DESCRIPTION
  22 Forking, vforking or rforking are the only ways new processes are created.
  23 The
  24 .Fa flags
  25 argument to
  26 .Fn rfork
  27 selects which resources of the
  28 invoking process (parent) are shared
  29 by the new process (child) or initialized to
  30 their default values.
  31 The resources include
  32 the open file descriptor table (which, when shared, permits processes
  33 to open and close files for other processes),
  34 and open files.
  35 .Fa Flags
  36 is the logical OR of some subset of:
  37 .Bl -tag -width ".Dv RFLINUXTHPN" -compact -offset indent
  38 .It Dv RFPROC
  39 If set a new process is created; otherwise changes affect the
  40 current process.
  41 The current implementation requires this flag to always be set.
  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
  67 .Dv RFMEM
  68 flag may not generally be called directly from high level
  69 languages including C.
  70 May be set only with
  71 .Dv RFPROC .
  72 A helper function is provided to assist with this problem and will cause
  73 the new process to run on the provided stack.
  74 See
  75 .Fn rfork_thread 3
  76 for information.
  77 .It Dv RFSIGSHARE
  78 If set, the kernel will force sharing the sigacts structure between the
  79 child and the parent.
  80 .It Dv RFLINUXTHPN
  81 If set, the kernel will return
  82 .Dv SIGUSR1
  83 instead of SIGCHILD upon thread exit for the child.
  84 This is intended to mimic certain Linux clone behaviour.
  85 .El
  86 .Pp
  87 File descriptors in a shared file descriptor table are kept
  88 open until either they are explicitly closed
  89 or all processes sharing the table exit.
  90 .Pp
  91 If
  92 .Dv RFPROC
  93 is set, the
  94 value returned in the parent process
  95 is the process id
  96 of the child process; the value returned in the child is zero.
  97 Without
  98 .Dv RFPROC ,
  99 the return value is zero.
 100 Process id's range from 1 to the maximum integer
 101 .Ft ( int )
 102 value.
 103 .Fn Rfork
 104 will sleep, if necessary, until required process resources are available.
 105 .Pp
 106 .Fn Fork
 107 can be implemented as a call to
 108 .Fn rfork "RFFDG | RFPROC"
 109 but isn't for backwards compatibility.
 110 .Sh RETURN VALUES
 111 Upon successful completion,
 112 .Fn rfork
 113 returns a value
 114 of 0 to the child process and returns the process ID of the child
 115 process to the parent process.
 116 Otherwise, a value of -1 is returned to the parent process, no
 117 child process is created, and the global variable
 118 .Va errno
 119 is set to indicate the error.
 120 .Sh ERRORS
 121 .Fn Rfork
 122 will fail and no child process will be created if:
 123 .Bl -tag -width Er
 124 .It Bq Er EAGAIN
 125 The system-imposed limit on the total
 126 number of processes under execution would be exceeded.
 127 The limit is given by the
 128 .Xr sysctl 3
 129 MIB variable
 130 .Dv KERN_MAXPROC .
 131 (The limit is actually ten less than this
 132 except for the super user).
 133 .It Bq Er EAGAIN
 134 The user is not the super user, and
 135 the system-imposed limit
 136 on the total number of
 137 processes under execution by a single user would be exceeded.
 138 The limit is given by the
 139 .Xr sysctl 3
 140 MIB variable
 141 .Dv KERN_MAXPROCPERUID .
 142 .It Bq Er EAGAIN
 143 The user is not the super user, and
 144 the soft resource limit corresponding to the resource parameter
 145 .Dv RLIMIT_NOFILE
 146 would be exceeded (see
 147 .Xr getrlimit 2 ) .
 148 .It Bq Er EINVAL
 149 The
 150 .Dv RFPROC
 151 flag was not specified.
 152 .It Bq Er EINVAL
 153 Both the
 154 .Dv RFFDG
 155 and the
 156 .Dv RFCFDG
 157 flags 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 lwp_create 2 ,
 165 .Xr minherit 2 ,
 166 .Xr vfork 2 ,
 167 .Xr rfork_thread 3
 168 .Sh HISTORY
 169 The
 170 .Fn rfork
 171 function call first appeared in Plan 9.
 172 .Sh BUGS
 173 .Dx
 174 does not yet implement a native
 175 .Fn clone
 176 library call, and the current pthreads implementation does not use
 177 .Fn rfork
 178 with
 179 .Dv RFMEM .
 180 A native port of the linux threads library,
 181 .Pa /usr/ports/devel/linuxthreads ,
 182 contains a working
 183 .Fn clone
 184 call that utilizes
 185 .Dv RFMEM .
 186 The
 187 .Fn rfork_thread
 188 library call can often be used instead of
 189 .Fn clone .