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