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