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