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.\" $FreeBSD: src/lib/libc/sys/rfork.2,v 1.11.2.11 2002/07/30 19:04:25 silby Exp $ 7.\" 8.Dd January 12, 1996 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 int 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. 34.Fa Flags 35is the logical OR of some subset of: 36.Bl -tag -width "RFCNAMEG" -compact -offset indent 37.It RFPROC 38If set a new process is created; otherwise changes affect the 39current process. 40The current implementation requires this flag to always be set. 41.It RFNOWAIT 42If set, the child process will be dissociated from the parent. 43Upon 44exit the child will not leave a status for the parent to collect. 45See 46.Xr wait 2 . 47.It RFFDG 48If set, the invoker's file descriptor table (see 49.Xr intro 2 ) 50is copied; otherwise the two processes share a 51single table. 52.It RFCFDG 53If set, the new process starts with a clean file descriptor table. 54Is mutually exclusive with 55.Dv RFFDG . 56.It RFMEM 57If set, the kernel will force sharing of the entire address space, 58typically by sharing the hardware page table directly. 59The child 60will thus inherit and share all the segments the parent process owns, 61whether they are normally shareable or not. The stack segment is 62not split (both the parent and child return on the same stack) and thus 63.Fn rfork 64with the RFMEM flag may not generally be called directly from high level 65languages including C. 66May be set only with 67.Dv RFPROC . 68A helper function is provided to assist with this problem and will cause 69the new process to run on the provided stack. See 70.Fn rfork_thread 3 71for information. 72.It RFSIGSHARE 73If set, the kernel will force sharing the sigacts structure between the 74child and the parent. 75.It RFLINUXTHPN 76If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread 77exit for the child. This is intended to mimic certain Linux clone behaviour. 78.El 79.Pp 80File descriptors in a shared file descriptor table are kept 81open until either they are explicitly closed 82or all processes sharing the table exit. 83.Pp 84If 85.Dv RFPROC 86is set, the 87value returned in the parent process 88is the process id 89of the child process; the value returned in the child is zero. 90Without 91.Dv RFPROC , 92the return value is zero. 93Process id's range from 1 to the maximum integer 94.Ft ( int ) 95value. 96.Fn Rfork 97will sleep, if necessary, until required process resources are available. 98.Pp 99.Fn Fork 100can be implemented as a call to 101.Fn rfork "RFFDG | RFPROC" 102but isn't for backwards compatibility. 103.Sh RETURN VALUES 104Upon successful completion, 105.Fn rfork 106returns a value 107of 0 to the child process and returns the process ID of the child 108process to the parent process. Otherwise, a value of -1 is returned 109to the parent process, no child process is created, and the global 110variable 111.Va errno 112is set to indicate the error. 113.Sh ERRORS 114.Fn Rfork 115will fail and no child process will be created if: 116.Bl -tag -width Er 117.It Bq Er EAGAIN 118The system-imposed limit on the total 119number of processes under execution would be exceeded. 120The limit is given by the 121.Xr sysctl 3 122MIB variable 123.Dv KERN_MAXPROC . 124(The limit is actually ten less than this 125except for the super user). 126.It Bq Er EAGAIN 127The user is not the super user, and 128the system-imposed limit 129on the total number of 130processes under execution by a single user would be exceeded. 131The limit is given by the 132.Xr sysctl 3 133MIB variable 134.Dv KERN_MAXPROCPERUID . 135.It Bq Er EAGAIN 136The user is not the super user, and 137the soft resource limit corresponding to the resource parameter 138.Dv RLIMIT_NOFILE 139would be exceeded (see 140.Xr getrlimit 2 ) . 141.It Bq Er EINVAL 142The RFPROC flag was not specified. 143.It Bq Er EINVAL 144Both the RFFDG and the RFCFDG flags were specified. 145.It Bq Er ENOMEM 146There is insufficient swap space for the new process. 147.El 148.Sh SEE ALSO 149.Xr fork 2 , 150.Xr intro 2 , 151.Xr minherit 2 , 152.Xr vfork 2 , 153.Xr rfork_thread 3 154.Sh BUGS 155.Fx 156does not yet implement a native 157.Fn clone 158library call, and the current pthreads implementation does not use 159.Fn rfork 160with RFMEM. A native port of the linux threads library, 161.Pa /usr/ports/devel/linuxthreads , 162contains a working 163.Fn clone 164call that utilizes RFMEM. 165The 166.Fn rfork_thread 167library call can often be used instead of 168.Fn clone . 169.Sh HISTORY 170The 171.Fn rfork 172function call first appeared in Plan9. 173