1.\" $OpenBSD: rfork.2,v 1.22 2004/12/31 21:05:47 jaredy Exp $ 2.\" 3.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd June 17, 2003 18.Dt RFORK 2 19.Os 20.Sh NAME 21.Nm rfork 22.Nd control new processes 23.Sh SYNOPSIS 24.Fd #include <sys/param.h> 25.Fd #include <unistd.h> 26.Ft int 27.Fn rfork "int flags" 28.Sh DESCRIPTION 29The fork functions 30.Po 31.Xr fork 2 , 32.Xr vfork 2 , 33and 34.Fn rfork 35.Pc 36create new processes. 37The new process 38.Pq child process 39is an exact copy of the calling process 40.Pq parent process , 41except as outlined in the 42.Xr fork 2 43manual page. 44.Fn rfork 45is used to manipulate the resources of the parent process and the 46child process. 47.Pp 48Operations currently supported include whether to copy or share the file 49descriptor table between the two processes, whether to share the address 50space, and whether the parent should 51.Xr wait 2 52for the child process to 53.Xr _exit 2 . 54.Fn rfork 55takes a single argument, 56.Fa flags , 57which controls which of these resources should be manipulated. 58They are defined in the header file 59.Aq Pa sys/param.h 60and are the logical OR of one or more of the following: 61.Bl -tag -width "RFNOWAIT" 62.\" .It Dv RFNAMEG 63.\" New Plan 9 64.\" .Sq name space . 65.\" This is a Plan 9 specific flag, and is not implemented. 66.\" .It Dv RFENVG 67.\" Copy Plan 9 68.\" .Sq env space . 69.\" This is a Plan 9 specific flag, and is not implemented. 70.It Dv RFFDG 71Copy the parent's file descriptor table. 72If this flag is unset, the parent and child will share the parent's 73file descriptor table. 74Descriptors will remain in existence until they are closed by all 75child processes using the table copies as well as by the parent process. 76May not be used in conjunction with 77.Dv RFCFDG . 78.\" .It Dv RFNOTEG 79.\" Create new Plan 9 80.\" .Sq note group . 81.\" This is a Plan 9 specific flag, and is not implemented. 82.It Dv RFPROC 83Create a new process. 84The current implementation requires this flag to always be set. 85.It Dv RFMEM 86Force sharing of the entire address space between the parent and child 87processes. 88The child will then inherit all the shared segments the parent process owns. 89Subsequent forks by the parent will then propagate the shared 90data and BSS segments among children. 91.It Dv RFNOWAIT 92Child processes will have their resources reaped immediately and 93implicitly when they terminate instead of turning into zombies, 94so the parent process may not call 95.Xr wait 2 96to collect their exit statuses and have their resources released 97explicitly. 98.\" .It Dv RFCNAMEG 99.\" Zero Plan 9 100.\" .Sq name space . 101.\" This is a Plan 9 specific flag, and is not implemented. 102.\" .It Dv RFCENVG 103.\" Zero Plan 9 104.\" .Sq env space . 105.\" This is a Plan 9 specific flag, and is not implemented. 106.It Dv RFCFDG 107Zero the child's file descriptor table 108.Pq i.e. start with a blank file descriptor table . 109May not be used in conjunction with 110.Dv RFFDG . 111.El 112.Pp 113.Xr fork 2 114can be implemented as a call to 115.Fn rfork 116using "RFFDG|RFPROC", but isn't for backwards compatibility. 117If a process has file descriptor table sharing active, setuid or setgid 118programs will not 119.Xr execve 2 120with extra privileges. 121.Sh RETURN VALUES 122The parent process returns the process ID 123.Pq PID 124of the child process. 125The child process returns 0. 126The range of the process ID is defined in 127.Aq Pa sys/proc.h 128and is currently between 1 and 32766, inclusive. 129.Sh ERRORS 130.Fn rfork 131will fail and no child process will be created if: 132.Bl -tag -width Er 133.It Bq Er ENOMEM 134Cannot allocate memory. 135The new process image required more memory than was allowed by the hardware or 136by system-imposed memory management constraints. 137A lack of swap space is normally temporary; however, a lack of core is not. 138Soft limits may be increased to their corresponding hard limits. 139.It Bq Er EINVAL 140Invalid argument. 141Some invalid argument was supplied. 142.It Bq Er EAGAIN 143Resource temporarily unavailable. 144The system-imposed limit on the total 145number of processes under execution would be exceeded. 146This limit is configuration-dependent. 147.It Bq Er EAGAIN 148Resource temporarily unavailable. 149The system-imposed limit 150.Dv MAXUPRC 151on the total number of processes under execution by a single user would be 152exceeded. 153.Dv MAXUPRC 154is currently defined in 155.Aq Pa sys/param.h 156as 157.Dv CHILD_MAX , 158which is currently defined as 80 in 159.Aq Pa sys/syslimits.h . 160.El 161.Sh SEE ALSO 162.Xr _exit 2 , 163.Xr execve 2 , 164.Xr fork 2 , 165.Xr intro 2 , 166.Xr vfork 2 167.Sh HISTORY 168The 169.Fn rfork 170function first appeared in Plan 9. 171