1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
5 .TH VFORK 2 "Dec 13, 2006"
6 .SH NAME
7 vfork, vforkx \- spawn new process in a virtual memory efficient way
8 .SH SYNOPSIS
9 .LP
10 .nf
11 #include <unistd.h>
12
13 \fBpid_t\fR \fBvfork\fR(\fBvoid\fR);
14 .fi
15
16 .LP
17 .nf
18 #include <sys/fork.h>
19
20 \fBpid_t\fR \fBvforkx\fR(\fBint\fR \fIflags\fR);
21 .fi
22
23 .SH DESCRIPTION
24 .sp
25 .LP
26 The \fBvfork()\fR and \fBvforkx()\fR functions create a new process without
27 fully copying the address space of the old process. These functions are useful
28 in instances where the purpose of a \fBfork\fR(2) operation is to create a new
29 system context for an \fBexecve()\fR operation (see \fBexec\fR(2)).
30 .sp
31 .LP
32 Unlike with the \fBfork()\fR function, the child process borrows the parent's
33 memory and thread of control until a call to \fBexecve()\fR or an exit (either
34 abnormally or by a call to \fB_exit()\fR (see \fBexit\fR(2)). Any modification
35 made during this time to any part of memory in the child process is reflected
36 in the parent process on return from \fBvfork()\fR or \fBvforkx()\fR. The
37 parent process is suspended while the child is using its resources.
38 .sp
39 .LP
40 In a multithreaded application, \fBvfork()\fR and \fBvforkx()\fR borrow only
41 the thread of control that called \fBvfork()\fR or \fBvforkx()\fR in the
42 parent; that is, the child contains only one thread. The use of \fBvfork()\fR
43 or \fBvforkx()\fR in multithreaded applications, however, is unsafe due to race
44 conditions that can cause the child process to become deadlocked and
45 consequently block both the child and parent process from execution
46 indefinitely.
47 .sp
48 .LP
49 The \fBvfork()\fR and \fBvforkx()\fR functions can normally be used the same
50 way as \fBfork()\fR and \fBforkx()\fR, respectively. The calling procedure,
51 however, should not return while running in the child's context, since the
52 eventual return from \fBvfork()\fR or \fBvforkx()\fR in the parent would be to
53 a stack frame that no longer exists. The \fB_exit()\fR function should be used
54 in favor of \fBexit\fR(3C) if unable to perform an \fBexecve()\fR operation,
55 since \fBexit()\fR will invoke all functions registered by \fBatexit\fR(3C) and
56 will flush and close standard I/O channels, thereby corrupting the parent
57 process's standard I/O data structures. Care must be taken in the child process
58 not to modify any global or local data that affects the behavior of the parent
59 process on return from \fBvfork()\fR or \fBvforkx()\fR, unless such an effect
60 is intentional.
61 .sp
62 .LP
63 Unlike \fBfork()\fR and \fBforkx()\fR, fork handlers are not run when
64 \fBvfork()\fR and \fBvforkx()\fR are called.
65 .sp
66 .LP
67 The \fBvfork()\fR and \fBvforkx()\fR functions are deprecated. Their sole
68 legitimate use as a prelude to an immediate call to a function from the
69 \fBexec\fR family can be achieved safely by \fBposix_spawn\fR(3C) or
70 \fBposix_spawnp\fR(3C).
71 .SS "Fork Extensions"
72 .sp
73 .LP
74 The \fBvforkx()\fR function accepts a \fIflags\fR argument consisting of a
75 bitwise inclusive-OR of zero or more of the following flags, which are defined
76 in the header \fB<sys/fork.h>\fR:
77 .br
78 .in +2
79 \fBFORK_NOSIGCHLD\fR
80 .in -2
81 .br
82 .in +2
83 \fBFORK_WAITPID\fR
84 .in -2
85 .sp
86 .LP
87 See \fBfork\fR(2) for descriptions of these flags. If the \fIflags\fR argument
88 is 0, \fBvforkx()\fR is identical to \fBvfork()\fR.
89 .SH RETURN VALUES
90 .sp
91 .LP
92 Upon successful completion, \fBvfork()\fR and \fBvforkx()\fR return \fB0\fR to
93 the child process and returns the process ID of the child process to the parent
94 process. Otherwise, \fB\(mi1\fR is returned to the parent process, no child
95 process is created, and \fBerrno\fR is set to indicate the error.
96 .SH ERRORS
97 .sp
98 .LP
99 The \fBvfork()\fR and \fBvforkx()\fR functions will fail if:
100 .sp
101 .ne 2
102 .na
103 \fB\fBEAGAIN\fR\fR
104 .ad
105 .RS 10n
106 The system-imposed limit on the total number of processes under execution
107 (either system-quality or by a single user) would be exceeded. This limit is
108 determined when the system is generated.
109 .RE
110
111 .sp
112 .ne 2
113 .na
114 \fB\fBENOMEM\fR\fR
115 .ad
116 .RS 10n
117 There is insufficient swap space for the new process.
118 .RE
119
120 .sp
121 .LP
122 The \fBvforkx()\fR function will fail if:
123 .sp
124 .ne 2
125 .na
126 \fB\fBEINVAL\fR\fR
127 .ad
128 .RS 10n
129 The \fIflags\fR argument is invalid.
130 .RE
131
132 .SH ATTRIBUTES
133 .sp
134 .LP
135 See \fBattributes\fR(5) for descriptions of the following attributes:
136 .sp
137
138 .sp
139 .TS
140 box;
141 c | c
142 l | l .
143 ATTRIBUTE TYPE ATTRIBUTE VALUE
144 _
145 Interface Stability Obsolete
146 _
147 MT-Level Unsafe
148 .TE
149
150 .SH SEE ALSO
151 .sp
152 .LP
153 \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBioctl\fR(2), \fBatexit\fR(3C),
154 \fBexit\fR(3C), \fBposix_spawn\fR(3C), \fBposix_spawnp\fR(3C),
155 \fBsignal.h\fR(3HEAD), \fBwait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
156 .SH NOTES
157 .sp
158 .LP
159 To avoid a possible deadlock situation, processes that are children in the
160 middle of a \fBvfork()\fR or \fBvforkx()\fR are never sent \fBSIGTTOU\fR or
161 \fBSIGTTIN\fR signals; rather, output or ioctls are allowed and input attempts
162 result in an \fBEOF\fR indication.
163 .sp
164 .LP
165 To forestall parent memory corruption due to race conditions with signal
166 handling, \fBvfork()\fR and \fBvforkx()\fR treat signal handlers in the child
167 process in the same manner as the \fBexec\fR(2) functions: signals set to be
168 caught by the parent process are set to the default action (\fBSIG_DFL\fR) in
169 the child process (see \fBsignal.h\fR(3HEAD)). Any attempt to set a signal
170 handler in the child before \fBexecve()\fR to anything other than \fBSIG_DFL\fR
171 or \fBSIG_IGN\fR is disallowed and results in setting the handler to
172 \fBSIG_DFL\fR.
173 .sp
174 .LP
175 On some systems, the implementation of \fBvfork()\fR and \fBvforkx()\fR cause
176 the parent to inherit register values from the child. This can create problems
177 for certain optimizing compilers if \fB<unistd.h>\fR is not included in the
178 source calling \fBvfork()\fR or if \fB<sys/fork.h>\fR is not included in the
179 source calling \fBvforkx()\fR.
|
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Copyright (c) 1980 Regents of the University of California.
5 .\" All rights reserved. The Berkeley software License Agreement
6 .\" specifies the terms and conditions for redistribution.
7 .Dd Aug 20, 2014
8 .Dt VFORK 2
9 .Os
10 .Sh NAME
11 .Nm vfork ,
12 .Nm vforkx
13 .Nd spawn new process in a virtual memory efficient way
14 .Sh SYNOPSIS
15 .In unistd.h
16 .Ft pid_t
17 .Fn vfork void
18 .
19 .In sys/fork.h
20 .Ft pid_t
21 .Fn vforkx "int flags"
22 .Sh DESCRIPTION
23 The
24 .Fn vfork
25 and
26 .Fn vforkx
27 functions create a new process without
28 fully copying the address space of the old process. These functions are useful
29 in instances where the purpose of a
30 .Xr fork 2
31 operation is to create a new
32 system context for an
33 .Xr exec 2
34 operation.
35 .Lp
36 Unlike with the
37 .Fn fork
38 function, the child process borrows the parent's
39 memory and thread of control until a call to
40 .Fn execve
41 or an exit
42 .Pq either abnormally or by a call to Xr _exit 2 .
43 Any modification
44 made during this time to any part of memory in the child process is reflected
45 in the parent process on return from
46 .Fn vfork
47 or
48 .Fn vforkx .
49 The parent process is suspended while the child is using its resources.
50 .Lp
51 In a multithreaded application,
52 .Fn vfork
53 and
54 .Fn vforkx
55 borrow only the thread of control that called
56 .Fn vfork
57 or
58 .Fn vforkx
59 in the parent; that is, the child contains only one thread. The use of
60 .Fn vfork
61 or
62 .Fn vforkx
63 in multithreaded applications, however, is unsafe due to race
64 conditions that can cause the child process to become deadlocked and
65 consequently block both the child and parent process from execution
66 indefinitely.
67 .Lp
68 The
69 .Fn vfork
70 and
71 .Fn vforkx
72 functions can normally be used the same way as
73 .Fn fork
74 and
75 .Fn forkx ,
76 respectively. The calling procedure,
77 however, should not return while running in the child's context, since the
78 eventual return from
79 .Fn vfork
80 or
81 .Fn vforkx
82 in the parent would be to
83 a stack frame that no longer exists. The
84 .Fn _exit
85 function should be used
86 in favor of
87 .Xr exit 3C
88 if unable to perform an
89 .Fn execve
90 operation, since
91 .Fn exit
92 will invoke all functions registered by
93 .Xr atexit 3C
94 and will flush and close standard I/O channels, thereby corrupting the parent
95 process's standard I/O data structures. Care must be taken in the child process
96 not to modify any global or local data that affects the behavior of the parent
97 process on return from
98 .Fn vfork
99 or
100 .Fn vforkx ,
101 unless such an effect
102 is intentional.
103 .Lp
104 Unlike
105 .Fn fork
106 and
107 .Fn forkx ,
108 fork handlers are not run when
109 .Fn vfork
110 and
111 .Fn vforkx
112 are called.
113 .Lp
114 The
115 .Fn vfork
116 and
117 .Fn vforkx
118 functions are deprecated. Their sole
119 legitimate use as a prelude to an immediate call to a function from the
120 .Xr exec 2
121 family can be achieved safely by
122 .Xr posix_spawn 3C
123 or
124 .Xr posix_spawnp 3C .
125 .Ss "Fork Extensions"
126 The
127 .Fn vforkx
128 function accepts a
129 .Fa flags
130 argument consisting of a
131 bitwise inclusive-OR of zero or more of the following flags, which are defined
132 in the header
133 .In sys/fork.h :
134 .Lp
135 .Bl -item -compact -offset indent
136 .It
137 .Dv FORK_NOSIGCHLD
138 .It
139 .Dv FORK_WAITPID
140 .El
141 .Lp
142 See
143 .Xr fork 2
144 for descriptions of these flags. If the
145 .Fa flags
146 argument is 0,
147 .Fn vforkx
148 is identical to
149 .Fn vfork .
150 .Sh RETURN VALUES
151 Upon successful completion,
152 .Fn vfork
153 and
154 .Fn vforkx
155 return 0 to
156 the child process and return the process ID of the child process to the parent
157 process. Otherwise, \(mi1 is returned to the parent process, no child
158 process is created, and
159 .Va errno
160 is set to indicate the error.
161 .Sh ERRORS
162 The
163 .Fn vfork
164 and
165 .Fn vforkx
166 functions will fail if:
167 .Bl -tag -width Er
168 .It Er EAGAIN
169 The system-imposed limit on the total number of processes under execution
170 (either system-quality or by a single user) would be exceeded. This limit is
171 determined when the system is generated.
172 .
173 .It Er ENOMEM
174 There is insufficient swap space for the new process.
175 .El
176 .Lp
177 The
178 .Fn vforkx
179 function will fail if:
180 .Bl -tag -width Er
181 .It Er EINVAL
182 The
183 .Va flags
184 argument is invalid.
185 .El
186 .Sh INTERFACE STABILITY
187 The
188 .Fn vfork
189 function is
190 .Sy Obsolete Standard .
191 .Lp
192 The
193 .Fn vforkx
194 function is
195 .Sy Obsolete Uncommitted .
196 .Sh MT-LEVEL
197 .Sy Unsafe .
198 .Sh SEE ALSO
199 .Xr exec 2 ,
200 .Xr exit 2 ,
201 .Xr fork 2 ,
202 .Xr ioctl 2 ,
203 .Xr atexit 3C ,
204 .Xr exit 3C ,
205 .Xr posix_spawn 3C ,
206 .Xr posix_spawnp 3C ,
207 .Xr signal.h 3HEAD ,
208 .Xr wait 3C ,
209 .Xr standards 5
210 .Sh NOTES
211 To avoid a possible deadlock situation, processes that are children in the
212 middle of a
213 .Fn vfork
214 or
215 .Fn vforkx
216 are never sent
217 .Dv SIGTTOU
218 or
219 .Dv SIGTTIN
220 signals; rather, output or ioctls are allowed and input attempts
221 result in an
222 .Dv EOF
223 indication.
224 .Lp
225 To forestall parent memory corruption due to race conditions with signal
226 handling,
227 .Fn vfork
228 and
229 .Fn vforkx
230 treat signal handlers in the child
231 process in the same manner as the
232 .Xr exec 2
233 functions: signals set to be
234 caught by the parent process are set to the default action
235 .Pq Dv SIG_DFL
236 in the child process
237 .Pq see Xr signal.h 3HEAD .
238 Any attempt to set a signal
239 handler in the child before
240 .Fn execve
241 to anything other than
242 .Dv SIG_DFL
243 or
244 .Dv SIG_IGN
245 is disallowed and results in setting the handler to
246 .Dv SIG_DFL .
247 .Lp
248 On some systems, the implementation of
249 .Fn vfork
250 and
251 .Fn vforkx
252 cause
253 the parent to inherit register values from the child. This can create problems
254 for certain optimizing compilers if
255 .In unistd.h
256 is not included in the source calling
257 .Fn vfork
258 or if
259 .In sys/fork.h
260 is not included in the
261 source calling
262 .Fn vforkx .
263 .Sh STANDARDS
264 The
265 .Fn vfork
266 function is available in the following compilation environments. See
267 .Xr standards 5 .
268 .Lp
269 .Bl -bullet -compact
270 .It
271 .St -xpg4.2
272 .It
273 .St -susv2
274 .It
275 .St -susv3
276 .El
277 .Lp
278 It was marked obsolete in
279 .St -susv3
280 and removed from
281 .St -p1003.1-2008 .
282 .Lp
283 The
284 .Fn vforkx
285 function is a local extension and not available in any strictly
286 standards-compliant compilation environment.
|