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