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