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 pid_t
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.
34The
35.Fa flags
36argument
37is the logical OR of some subset of:
38.Bl -tag -width ".Dv RFLINUXTHPN"
39.It Dv RFPROC
40If set a new process is created; otherwise changes affect the
41current process.
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 .
| 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 pid_t
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.
34The
35.Fa flags
36argument
37is the logical OR of some subset of:
38.Bl -tag -width ".Dv RFLINUXTHPN"
39.It Dv RFPROC
40If set a new process is created; otherwise changes affect the
41current process.
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 RFMEM flag may not generally be called directly from high level
67languages including C.
68May be set only with
69.Dv RFPROC .
70A helper function is provided to assist with this problem and will cause
71the new process to run on the provided stack.
72See
73.Xr rfork_thread 3
74for information.
75.It Dv RFSIGSHARE
76If set, the kernel will force sharing the sigacts structure between the
77child and the parent.
78.It Dv RFLINUXTHPN
79If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread
80exit for the child.
81This is intended to mimic certain Linux clone behaviour.
82.El
83.Pp
84File descriptors in a shared file descriptor table are kept
85open until either they are explicitly closed
86or all processes sharing the table exit.
87.Pp
88If
89.Dv RFPROC
90is set, the
91value returned in the parent process
92is the process id
93of the child process; the value returned in the child is zero.
94Without
95.Dv RFPROC ,
96the return value is zero.
97Process id's range from 1 to the maximum integer
98.Ft ( int )
99value.
100The
101.Fn rfork
102system call
103will sleep, if necessary, until required process resources are available.
104.Pp
105The
106.Fn fork
107system call
108can be implemented as a call to
109.Fn rfork "RFFDG | RFPROC"
110but is not for backwards compatibility.
111.Sh RETURN VALUES
112Upon successful completion,
113.Fn rfork
114returns a value
115of 0 to the child process and returns the process ID of the child
116process to the parent process.
117Otherwise, a value of -1 is returned
118to the parent process, no child process is created, and the global
119variable
120.Va errno
121is set to indicate the error.
122.Sh ERRORS
123The
124.Fn rfork
125system call
126will fail and no child process will be created if:
127.Bl -tag -width Er
128.It Bq Er EAGAIN
129The system-imposed limit on the total
130number of processes under execution would be exceeded.
131The limit is given by the
132.Xr sysctl 3
133MIB variable
134.Dv KERN_MAXPROC .
135(The limit is actually ten less than this
136except for the super user).
137.It Bq Er EAGAIN
138The user is not the super user, and
139the system-imposed limit
140on the total number of
141processes under execution by a single user would be exceeded.
142The limit is given by the
143.Xr sysctl 3
144MIB variable
145.Dv KERN_MAXPROCPERUID .
146.It Bq Er EAGAIN
147The user is not the super user, and
148the soft resource limit corresponding to the
149.Fa resource
150argument
151.Dv RLIMIT_NOFILE
152would be exceeded (see
153.Xr getrlimit 2 ) .
154.It Bq Er EINVAL
155Both the RFFDG and the RFCFDG flags were specified.
156.It Bq Er EINVAL
157Any flags not listed above 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 minherit 2 ,
165.Xr vfork 2 ,
166.Xr rfork_thread 3
167.Sh HISTORY
168The
169.Fn rfork
170function first appeared in Plan9.
171.Sh BUGS
172.Fx
173does not yet implement a native
174.Fn clone
175library call, and the current pthreads implementation does not use
176.Fn rfork
177with RFMEM.
178A native port of the linux threads library,
179.Pa /usr/ports/devel/linuxthreads ,
180contains a working
181.Fn clone
182call that utilizes RFMEM.
183The
184.Xr rfork_thread 3
185function can often be used instead of
186.Fn clone .
| 65.It Dv RFMEM
66If set, the kernel will force sharing of the entire address space,
67typically by sharing the hardware page table directly.
68The child
69will thus inherit and share all the segments the parent process owns,
70whether they are normally shareable or not.
71The stack segment is
72not split (both the parent and child return on the same stack) and thus
73.Fn rfork
74with the RFMEM flag may not generally be called directly from high level
75languages including C.
76May be set only with
77.Dv RFPROC .
78A helper function is provided to assist with this problem and will cause
79the new process to run on the provided stack.
80See
81.Xr rfork_thread 3
82for information.
83.It Dv RFSIGSHARE
84If set, the kernel will force sharing the sigacts structure between the
85child and the parent.
86.It Dv RFLINUXTHPN
87If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread
88exit for the child.
89This is intended to mimic certain Linux clone behaviour.
90.El
91.Pp
92File descriptors in a shared file descriptor table are kept
93open until either they are explicitly closed
94or all processes sharing the table exit.
95.Pp
96If
97.Dv RFPROC
98is set, the
99value returned in the parent process
100is the process id
101of the child process; the value returned in the child is zero.
102Without
103.Dv RFPROC ,
104the return value is zero.
105Process id's range from 1 to the maximum integer
106.Ft ( int )
107value.
108The
109.Fn rfork
110system call
111will sleep, if necessary, until required process resources are available.
112.Pp
113The
114.Fn fork
115system call
116can be implemented as a call to
117.Fn rfork "RFFDG | RFPROC"
118but is not for backwards compatibility.
119.Sh RETURN VALUES
120Upon successful completion,
121.Fn rfork
122returns a value
123of 0 to the child process and returns the process ID of the child
124process to the parent process.
125Otherwise, a value of -1 is returned
126to the parent process, no child process is created, and the global
127variable
128.Va errno
129is set to indicate the error.
130.Sh ERRORS
131The
132.Fn rfork
133system call
134will fail and no child process will be created if:
135.Bl -tag -width Er
136.It Bq Er EAGAIN
137The system-imposed limit on the total
138number of processes under execution would be exceeded.
139The limit is given by the
140.Xr sysctl 3
141MIB variable
142.Dv KERN_MAXPROC .
143(The limit is actually ten less than this
144except for the super user).
145.It Bq Er EAGAIN
146The user is not the super user, and
147the system-imposed limit
148on the total number of
149processes under execution by a single user would be exceeded.
150The limit is given by the
151.Xr sysctl 3
152MIB variable
153.Dv KERN_MAXPROCPERUID .
154.It Bq Er EAGAIN
155The user is not the super user, and
156the soft resource limit corresponding to the
157.Fa resource
158argument
159.Dv RLIMIT_NOFILE
160would be exceeded (see
161.Xr getrlimit 2 ) .
162.It Bq Er EINVAL
163Both the RFFDG and the RFCFDG flags were specified.
164.It Bq Er EINVAL
165Any flags not listed above were specified.
166.It Bq Er ENOMEM
167There is insufficient swap space for the new process.
168.El
169.Sh SEE ALSO
170.Xr fork 2 ,
171.Xr intro 2 ,
172.Xr minherit 2 ,
173.Xr vfork 2 ,
174.Xr rfork_thread 3
175.Sh HISTORY
176The
177.Fn rfork
178function first appeared in Plan9.
179.Sh BUGS
180.Fx
181does not yet implement a native
182.Fn clone
183library call, and the current pthreads implementation does not use
184.Fn rfork
185with RFMEM.
186A native port of the linux threads library,
187.Pa /usr/ports/devel/linuxthreads ,
188contains a working
189.Fn clone
190call that utilizes RFMEM.
191The
192.Xr rfork_thread 3
193function can often be used instead of
194.Fn clone .
|