1.\" 2.\" This manual page is taken directly from Plan 9, 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/libc/sys/rfork.2,v 1.7 2007/12/08 23:20:29 swildner 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 22Forking, vforking or rforking are the only ways new processes are created. 23The 24.Fa flags 25argument to 26.Fn rfork 27selects which resources of the 28invoking process (parent) are shared 29by the new process (child) or initialized to 30their default values. 31The resources include 32the open file descriptor table (which, when shared, permits processes 33to open and close files for other processes), 34and open files. 35.Fa Flags 36is the logical OR of some subset of: 37.Bl -tag -width ".Dv RFLINUXTHPN" -compact -offset indent 38.It Dv RFPROC 39If set a new process is created; otherwise changes affect the 40current process. 41The current implementation requires this flag to always be set. 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 67.Dv RFMEM 68flag may not generally be called directly from high level 69languages including C. 70May be set only with 71.Dv RFPROC . 72A helper function is provided to assist with this problem and will cause 73the new process to run on the provided stack. 74See 75.Fn rfork_thread 3 76for information. 77.It Dv RFSIGSHARE 78If set, the kernel will force sharing the sigacts structure between the 79child and the parent. 80.It Dv RFLINUXTHPN 81If set, the kernel will return 82.Dv SIGUSR1 83instead of SIGCHILD upon thread exit for the child. 84This is intended to mimic certain Linux clone behaviour. 85.El 86.Pp 87File descriptors in a shared file descriptor table are kept 88open until either they are explicitly closed 89or all processes sharing the table exit. 90.Pp 91If 92.Dv RFPROC 93is set, the 94value returned in the parent process 95is the process id 96of the child process; the value returned in the child is zero. 97Without 98.Dv RFPROC , 99the return value is zero. 100Process id's range from 1 to the maximum integer 101.Ft ( int ) 102value. 103.Fn Rfork 104will sleep, if necessary, until required process resources are available. 105.Pp 106.Fn Fork 107can be implemented as a call to 108.Fn rfork "RFFDG | RFPROC" 109but isn't for backwards compatibility. 110.Sh RETURN VALUES 111Upon successful completion, 112.Fn rfork 113returns a value 114of 0 to the child process and returns the process ID of the child 115process to the parent process. 116Otherwise, a value of -1 is returned to the parent process, no 117child process is created, and the global variable 118.Va errno 119is set to indicate the error. 120.Sh ERRORS 121.Fn Rfork 122will fail and no child process will be created if: 123.Bl -tag -width Er 124.It Bq Er EAGAIN 125The system-imposed limit on the total 126number of processes under execution would be exceeded. 127The limit is given by the 128.Xr sysctl 3 129MIB variable 130.Dv KERN_MAXPROC . 131(The limit is actually ten less than this 132except for the super user). 133.It Bq Er EAGAIN 134The user is not the super user, and 135the system-imposed limit 136on the total number of 137processes under execution by a single user would be exceeded. 138The limit is given by the 139.Xr sysctl 3 140MIB variable 141.Dv KERN_MAXPROCPERUID . 142.It Bq Er EAGAIN 143The user is not the super user, and 144the soft resource limit corresponding to the resource parameter 145.Dv RLIMIT_NOFILE 146would be exceeded (see 147.Xr getrlimit 2 ) . 148.It Bq Er EINVAL 149The 150.Dv RFPROC 151flag was not specified. 152.It Bq Er EINVAL 153Both the 154.Dv RFFDG 155and the 156.Dv RFCFDG 157flags 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 lwp_create 2 , 165.Xr minherit 2 , 166.Xr vfork 2 , 167.Xr rfork_thread 3 168.Sh HISTORY 169The 170.Fn rfork 171function call first appeared in Plan 9. 172.Sh BUGS 173.Dx 174does not yet implement a native 175.Fn clone 176library call, and the current pthreads implementation does not use 177.Fn rfork 178with 179.Dv RFMEM . 180A native port of the linux threads library, 181.Pa /usr/ports/devel/linuxthreads , 182contains a working 183.Fn clone 184call that utilizes 185.Dv RFMEM . 186The 187.Fn rfork_thread 188library call can often be used instead of 189.Fn clone . 190