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