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