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 July 12, 2011 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 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 RFPROC 109is set, the 110value returned in the parent process 111is the process id 112of the child process; the value returned in the child is zero. 113Without 114.Dv RFPROC , 115the return value is zero. 116Process id's range from 1 to the maximum integer 117.Ft ( int ) 118value. 119The 120.Fn rfork 121system call 122will sleep, if necessary, until required process resources are available. 123.Pp 124The 125.Fn fork 126system call 127can be implemented as a call to 128.Fn rfork "RFFDG | RFPROC" 129but is not for backwards compatibility. 130.Sh RETURN VALUES 131Upon successful completion, 132.Fn rfork 133returns a value 134of 0 to the child process and returns the process ID of the child 135process to the parent process. 136Otherwise, a value of -1 is returned 137to the parent process, no child process is created, and the global 138variable 139.Va errno 140is set to indicate the error. 141.Sh ERRORS 142The 143.Fn rfork 144system call 145will fail and no child process will be created if: 146.Bl -tag -width Er 147.It Bq Er EAGAIN 148The system-imposed limit on the total 149number of processes under execution would be exceeded. 150The limit is given by the 151.Xr sysctl 3 152MIB variable 153.Dv KERN_MAXPROC . 154(The limit is actually ten less than this 155except for the super user). 156.It Bq Er EAGAIN 157The user is not the super user, and 158the system-imposed limit 159on the total number of 160processes under execution by a single user would be exceeded. 161The limit is given by the 162.Xr sysctl 3 163MIB variable 164.Dv KERN_MAXPROCPERUID . 165.It Bq Er EAGAIN 166The user is not the super user, and 167the soft resource limit corresponding to the 168.Fa resource 169argument 170.Dv RLIMIT_NOFILE 171would be exceeded (see 172.Xr getrlimit 2 ) . 173.It Bq Er EINVAL 174Both the RFFDG and the RFCFDG flags were specified. 175.It Bq Er EINVAL 176Any flags not listed above were specified. 177.It Bq Er EINVAL 178An invalid signal number was specified. 179.It Bq Er ENOMEM 180There is insufficient swap space for the new process. 181.El 182.Sh SEE ALSO 183.Xr fork 2 , 184.Xr intro 2 , 185.Xr minherit 2 , 186.Xr vfork 2 , 187.Xr pthread_create 3 , 188.Xr rfork_thread 3 189.Sh HISTORY 190The 191.Fn rfork 192function first appeared in Plan9. 193