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.Dd September 25, 2019 7.Dt RFORK 2 8.Os 9.Sh NAME 10.Nm rfork 11.Nd manipulate process resources 12.Sh LIBRARY 13.Lb libc 14.Sh SYNOPSIS 15.In unistd.h 16.Ft pid_t 17.Fn rfork "int flags" 18.Sh DESCRIPTION 19Forking, vforking or rforking are the only ways new processes are created. 20The 21.Fa flags 22argument to 23.Fn rfork 24selects which resources of the 25invoking process (parent) are shared 26by the new process (child) or initialized to 27their default values. 28The resources include 29the open file descriptor table (which, when shared, permits processes 30to open and close files for other processes), 31and open files. 32The 33.Fa flags 34argument 35is either 36.Dv RFSPAWN 37or the logical OR of some subset of: 38.Bl -tag -width ".Dv RFLINUXTHPN" 39.It Dv RFPROC 40If set a new process is created; otherwise changes affect the 41current process. 42.It Dv RFNOWAIT 43If set, the child process will be dissociated from the parent. 44Upon 45exit the child will not leave a status for the parent to collect. 46See 47.Xr wait 2 . 48.It Dv RFFDG 49If set, the invoker's file descriptor table (see 50.Xr intro 2 ) 51is copied; otherwise the two processes share a 52single table. 53.It Dv RFCFDG 54If set, the new process starts with a clean file descriptor table. 55Is mutually exclusive with 56.Dv RFFDG . 57.It Dv RFTHREAD 58If set, the new process shares file descriptor to process leaders table 59with its parent. 60Only applies when neither 61.Dv RFFDG 62nor 63.Dv RFCFDG 64are set. 65.It Dv RFMEM 66If set, the kernel will force sharing of the entire address space, 67typically by sharing the hardware page table directly. 68The child 69will thus inherit and share all the segments the parent process owns, 70whether they are normally shareable or not. 71The stack segment is 72not split (both the parent and child return on the same stack) and thus 73.Fn rfork 74with the RFMEM flag may not generally be called directly from high level 75languages including C. 76May be set only with 77.Dv RFPROC . 78A helper function is provided to assist with this problem and will cause 79the new process to run on the provided stack. 80See 81.Xr rfork_thread 3 82for information. 83Note that a lot of code will not run correctly in such an environment. 84.It Dv RFSIGSHARE 85If set, the kernel will force sharing the sigacts structure between the 86child and the parent. 87.It Dv RFTSIGZMB 88If set, the kernel will deliver a specified signal to the parent 89upon the child exit, instead of default SIGCHLD. 90The signal number 91.Dv signum 92is specified by oring the 93.Dv RFTSIGFLAGS(signum) 94expression into 95.Fa flags . 96Specifying signal number 0 disables signal delivery upon the child exit. 97.It Dv RFLINUXTHPN 98If set, the kernel will deliver SIGUSR1 instead of SIGCHLD upon thread 99exit for the child. 100This is intended to mimic certain Linux clone behaviour. 101.El 102.Pp 103File descriptors in a shared file descriptor table are kept 104open until either they are explicitly closed 105or all processes sharing the table exit. 106.Pp 107If 108.Dv RFSPAWN 109is passed, 110.Nm 111will use 112.Xr vfork 2 113semantics but reset all signal actions in the child to default. 114This flag is used by the 115.Xr posix_spawn 3 116implementation in libc. 117.Pp 118If 119.Dv RFPROC 120is set, the 121value returned in the parent process 122is the process id 123of the child process; the value returned in the child is zero. 124Without 125.Dv RFPROC , 126the return value is zero. 127Process id's range from 1 to the maximum integer 128.Ft ( int ) 129value. 130The 131.Fn rfork 132system call 133will sleep, if necessary, until required process resources are available. 134.Pp 135The 136.Fn fork 137system call 138can be implemented as a call to 139.Fn rfork "RFFDG | RFPROC" 140but is not for backwards compatibility. 141.Sh RETURN VALUES 142Upon successful completion, 143.Fn rfork 144returns a value 145of 0 to the child process and returns the process ID of the child 146process to the parent process. 147Otherwise, a value of -1 is returned 148to the parent process, no child process is created, and the global 149variable 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153The 154.Fn rfork 155system call 156will fail and no child process will be created if: 157.Bl -tag -width Er 158.It Bq Er EAGAIN 159The system-imposed limit on the total 160number of processes under execution would be exceeded. 161The limit is given by the 162.Xr sysctl 3 163MIB variable 164.Dv KERN_MAXPROC . 165(The limit is actually ten less than this 166except for the super user). 167.It Bq Er EAGAIN 168The user is not the super user, and 169the system-imposed limit 170on the total number of 171processes under execution by a single user would be exceeded. 172The limit is given by the 173.Xr sysctl 3 174MIB variable 175.Dv KERN_MAXPROCPERUID . 176.It Bq Er EAGAIN 177The user is not the super user, and 178the soft resource limit corresponding to the 179.Fa resource 180argument 181.Dv RLIMIT_NOFILE 182would be exceeded (see 183.Xr getrlimit 2 ) . 184.It Bq Er EINVAL 185Both the RFFDG and the RFCFDG flags were specified. 186.It Bq Er EINVAL 187Any flags not listed above were specified. 188.It Bq Er EINVAL 189An invalid signal number was specified. 190.It Bq Er ENOMEM 191There is insufficient swap space for the new process. 192.El 193.Sh SEE ALSO 194.Xr fork 2 , 195.Xr intro 2 , 196.Xr minherit 2 , 197.Xr vfork 2 , 198.Xr pthread_create 3 , 199.Xr rfork_thread 3 200.Sh HISTORY 201The 202.Fn rfork 203function first appeared in Plan9. 204