Blob


1 .TH RFORK 3
2 .SH NAME
3 rfork \- manipulate process state
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .nf
10 .B
11 int rfork(int flags)
12 .fi
13 .SH DESCRIPTION
14 .I Rfork
15 is a partial implementation of the Plan 9 system call.
16 It can be used to manipulate some process state and to create
17 new processes a la
18 .MR fork (2) .
19 It cannot be used to create shared-memory processes
20 (Plan 9's
21 .B RFMEM
22 flag); for that functionality use
23 .I proccreate
24 (see
25 .MR thread (3) ).
26 .PP
27 The
28 .I flags
29 argument to
30 .I rfork
31 selects which resources of the
32 invoking process (parent) are shared
33 by the new process (child) or initialized to
34 their default values.
35 .I Flags
36 is the logical OR of some subset of
37 .TF RFCNAMEG
38 .TP
39 .B RFPROC
40 If set a new process is created; otherwise changes affect the
41 current process.
42 .TP
43 .B RFNOWAIT
44 If set, the child process will be dissociated from the parent. Upon
45 exit the child will leave no
46 .B Waitmsg
47 (see
48 .MR wait (3) )
49 for the parent to collect.
50 .\" .TP
51 .\" .B RFNAMEG
52 .\" If set, the new process inherits a copy of the parent's name space;
53 .\" otherwise the new process shares the parent's name space.
54 .\" Is mutually exclusive with
55 .\" .BR RFCNAMEG .
56 .\" .TP
57 .\" .B RFCNAMEG
58 .\" If set, the new process starts with a clean name space. A new
59 .\" name space must be built from a mount of an open file descriptor.
60 .\" Is mutually exclusive with
61 .\" .BR RFNAMEG .
62 .\" .TP
63 .\" .B RFNOMNT
64 .\" If set, subsequent mounts into the new name space and dereferencing
65 .\" of pathnames starting with
66 .\" .B #
67 .\" are disallowed.
68 .\" .TP
69 .\" .B RFENVG
70 .\" If set, the environment variables are copied;
71 .\" otherwise the two processes share environment variables.
72 .\" Is mutually exclusive with
73 .\" .BR RFCENVG .
74 .\" .TP
75 .\" .B RFCENVG
76 .\" If set, the new process starts with an empty environment.
77 .\" Is mutually exclusive with
78 .\" .BR RFENVG .
79 .TP
80 .B RFNOTEG
81 Each process is a member of a group of processes that all
82 receive notes when a note is sent to the group
83 (see
84 .MR postnote (3)
85 and
86 .MR signal (2) ).
87 The group of a new process is by default the same as its parent, but if
88 .B RFNOTEG
89 is set (regardless of
90 .BR RFPROC ),
91 the process becomes the first in a new group, isolated from
92 previous processes.
93 In Plan 9, a process can call
94 .B rfork(RFNOTEG)
95 and then be sure that it will no longer receive console interrupts
96 or other notes.
97 Unix job-control shells put each command in its own process group
98 and then relay notes to the current foreground command, making
99 the idiom less useful.
100 .TP
101 .B RFFDG
102 If set, the invoker's file descriptor table (see
103 .IR intro ( ))
104 is copied; otherwise the two processes share a
105 single table.
106 .\" .TP
107 .\" .B RFCFDG
108 .\" If set, the new process starts with a clean file descriptor table.
109 .\" Is mutually exclusive with
110 .\" .BR RFFDG .
111 .\" .TP
112 .\" .B RFREND
113 .\" If set, the process will be unable to
114 .\" .IR rendezvous (3)
115 .\" with any of its ancestors; its children will, however, be able to
116 .\" .B rendezvous
117 .\" with it. In effect,
118 .\" .B RFREND
119 .\" makes the process the first in a group of processes that share a space for
120 .\" .B rendezvous
121 .\" tags.
122 .\" .TP
123 .\" .B RFMEM
124 .\" If set, the child and the parent will share
125 .\" .B data
126 .\" and
127 .\" .B bss
128 .\" segments.
129 .\" Otherwise, the child inherits a copy of those segments.
130 .\" Other segment types, in particular stack segments, will be unaffected.
131 .\" May be set only with
132 .\" .BR RFPROC .
133 .PD
134 .PP
135 File descriptors in a shared file descriptor table are kept
136 open until either they are explicitly closed
137 or all processes sharing the table exit.
138 .PP
139 If
140 .B RFPROC
141 is set, the
142 value returned in the parent process
143 is the process id
144 of the child process; the value returned in the child is zero.
145 Without
146 .BR RFPROC ,
147 the return value is zero.
148 Process ids range from 1 to the maximum integer
149 .RB ( int )
150 value.
151 .I Rfork
152 will sleep, if necessary, until required process resources are available.
153 .PP
154 Calling
155 .B rfork(RFFDG|RFPROC)
156 is equivalent to calling
157 .MR fork (2) .
158 .SH SOURCE
159 .B \*9/src/lib9/rfork.c
160 .SH DIAGNOSTICS
161 .I Rfork
162 sets
163 .IR errstr .