Debian Codegraph @

upstream/debian-unstable/man2/vfork.2

raw
1 .\" Copyright 1999, Andries E. Brouwer <[email protected]>
2 .\" Copyright 2006-2017, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH vfork 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 vfork \- create a child process and block parent
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .B pid_t vfork(void);
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR vfork ():
26 .nf
27 Since glibc 2.12:
28 (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
29 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
30 || /* glibc <= 2.19: */ _BSD_SOURCE
31 Before glibc 2.12:
32 _BSD_SOURCE || _XOPEN_SOURCE >= 500
33 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
34 .fi
35 .SH DESCRIPTION
36 .SS Standard description
37 (From POSIX.1)
38 The
39 .BR vfork ()
40 function has the same effect as
41 .BR fork (2),
42 except that the behavior is undefined if the process created by
43 .BR vfork ()
44 either modifies any data other than a variable of type
45 .I pid_t
46 used to store the return value from
47 .BR vfork (),
48 or returns from the function in which
49 .BR vfork ()
50 was called, or calls any other function before successfully calling
51 .BR _exit (2)
52 or one of the
53 .BR exec (3)
54 family of functions.
55 .SS Linux description
56 .BR vfork (),
57 just like
58 .BR fork (2),
59 creates a child process of the calling process.
60 For details and return value and errors, see
61 .BR fork (2).
62 .P
63 .BR vfork ()
64 is a special case of
65 .BR clone (2).
66 It is used to create new processes without copying the page tables of
67 the parent process.
68 It may be useful in performance-sensitive applications
69 where a child is created which then immediately issues an
70 .BR execve (2).
71 .P
72 .BR vfork ()
73 differs from
74 .BR fork (2)
75 in that the calling thread is suspended until the child terminates
76 (either normally,
77 by calling
78 .BR _exit (2),
79 or abnormally, after delivery of a fatal signal),
80 or it makes a call to
81 .BR execve (2).
82 Until that point, the child shares all memory with its parent,
83 including the stack.
84 The child must not return from the current function or call
85 .BR exit (3)
86 (which would have the effect of calling exit handlers
87 established by the parent process and flushing the parent's
88 .BR stdio (3)
89 buffers), but may call
90 .BR _exit (2).
91 .P
92 As with
93 .BR fork (2),
94 the child process created by
95 .BR vfork ()
96 inherits copies of various of the caller's process attributes
97 (e.g., file descriptors, signal dispositions, and current working directory);
98 the
99 .BR vfork ()
100 call differs only in the treatment of the virtual address space,
101 as described above.
102 .P
103 Signals sent to the parent
104 arrive after the child releases the parent's memory
105 (i.e., after the child terminates
106 or calls
107 .BR execve (2)).
108 .SS Historic description
109 Under Linux,
110 .BR fork (2)
111 is implemented using copy-on-write pages, so the only penalty incurred by
112 .BR fork (2)
113 is the time and memory required to duplicate the parent's page tables,
114 and to create a unique task structure for the child.
115 However, in the bad old days a
116 .BR fork (2)
117 would require making a complete copy of the caller's data space,
118 often needlessly, since usually immediately afterward an
119 .BR exec (3)
120 is done.
121 Thus, for greater efficiency, BSD introduced the
122 .BR vfork ()
123 system call, which did not fully copy the address space of
124 the parent process, but borrowed the parent's memory and thread
125 of control until a call to
126 .BR execve (2)
127 or an exit occurred.
128 The parent process was suspended while the
129 child was using its resources.
130 The use of
131 .BR vfork ()
132 was tricky: for example, not modifying data
133 in the parent process depended on knowing which variables were
134 held in a register.
135 .SH VERSIONS
136 The requirements put on
137 .BR vfork ()
138 by the standards are weaker than those put on
139 .BR fork (2),
140 so an implementation where the two are synonymous is compliant.
141 In particular, the programmer cannot rely on the parent
142 remaining blocked until the child either terminates or calls
143 .BR execve (2),
144 and cannot rely on any specific behavior with respect to shared memory.
145 .\" In AIXv3.1 vfork is equivalent to fork.
146 .P
147 Some consider the semantics of
148 .BR vfork ()
149 to be an architectural blemish, and the 4.2BSD man page stated:
150 \[lq]This system call will be eliminated
151 when proper system sharing mechanisms are implemented.
152 Users should not depend on the memory sharing semantics of
153 .I vfork
154 as it will, in that case, be made synonymous to
155 .IR fork .\[rq]
156 However, even though modern memory management hardware
157 has decreased the performance difference between
158 .BR fork (2)
159 and
160 .BR vfork (),
161 there are various reasons why Linux and other systems have retained
162 .BR vfork ():
163 .IP \[bu] 3
164 Some performance-critical applications require the small performance
165 advantage conferred by
166 .BR vfork ().
167 .IP \[bu]
168 .BR vfork ()
169 can be implemented on systems that lack a memory-management unit (MMU), but
170 .BR fork (2)
171 can't be implemented on such systems.
172 (POSIX.1-2008 removed
173 .BR vfork ()
174 from the standard;
175 the POSIX rationale for the
176 .BR posix_spawn (3)
177 function notes that that function,
178 which provides functionality equivalent to
179 .BR fork (2)+\c
180 .BR exec (3),
181 is designed to be implementable on systems that lack an MMU.)
182 .\" http://stackoverflow.com/questions/4259629/what-is-the-difference-between-fork-and-vfork
183 .\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html
184 .\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html
185 .\"
186 .IP \[bu]
187 On systems where memory is constrained,
188 .BR vfork ()
189 avoids the need to temporarily commit memory (see the description of
190 .I /proc/sys/vm/overcommit_memory
191 in
192 .BR proc (5))
193 in order to execute a new program.
194 (This can be especially beneficial where a large parent process wishes
195 to execute a small helper program in a child process.)
196 By contrast, using
197 .BR fork (2)
198 in this scenario requires either committing an amount of memory equal
199 to the size of the parent process (if strict overcommitting is in force)
200 or overcommitting memory with the risk that a process is terminated
201 by the out-of-memory (OOM) killer.
202 .SS Linux notes
203 Fork handlers established using
204 .BR pthread_atfork (3)
205 are not called when a multithreaded program employing
206 the NPTL threading library calls
207 .BR vfork ().
208 Fork handlers are called in this case in a program using the
209 LinuxThreads threading library.
210 (See
211 .BR pthreads (7)
212 for a description of Linux threading libraries.)
213 .P
214 A call to
215 .BR vfork ()
216 is equivalent to calling
217 .BR clone (2)
218 with
219 .I flags
220 specified as:
221 .P
222 .in +4n
223 .EX
224 CLONE_VM | CLONE_VFORK | SIGCHLD
225 .EE
226 .in
227 .SH STANDARDS
228 None.
229 .SH HISTORY
230 4.3BSD;
231 POSIX.1-2001 (but marked OBSOLETE).
232 POSIX.1-2008 removes the specification of
233 .BR vfork ().
234 .P
235 The
236 .BR vfork ()
237 system call appeared in 3.0BSD.
238 .\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still
239 .\" present, but definitely on its way out'.
240 In 4.4BSD it was made synonymous to
241 .BR fork (2)
242 but NetBSD introduced it again;
243 see
244 .UR http:\://www.netbsd.org\:/Documentation\:/kernel\:/vfork.html
245 .UE .
246 In Linux, it has been equivalent to
247 .BR fork (2)
248 until Linux 2.2.0-pre6 or so.
249 Since Linux 2.2.0-pre9 (on i386, somewhat later on
250 other architectures) it is an independent system call.
251 Support was added in glibc 2.0.112.
252 .\"
253 .SH CAVEATS
254 The child process should take care not to modify the memory in unintended ways,
255 since such changes will be seen by the parent process once
256 the child terminates or executes another program.
257 In this regard, signal handlers can be especially problematic:
258 if a signal handler that is invoked in the child of
259 .BR vfork ()
260 changes memory, those changes may result in an inconsistent process state
261 from the perspective of the parent process
262 (e.g., memory changes would be visible in the parent,
263 but changes to the state of open file descriptors would not be visible).
264 .P
265 When
266 .BR vfork ()
267 is called in a multithreaded process,
268 only the calling thread is suspended until the child terminates
269 or executes a new program.
270 This means that the child is sharing an address space with other running code.
271 This can be dangerous if another thread in the parent process
272 changes credentials (using
273 .BR setuid (2)
274 or similar),
275 since there are now two processes with different privilege levels
276 running in the same address space.
277 As an example of the dangers,
278 suppose that a multithreaded program running as root creates a child using
279 .BR vfork ().
280 After the
281 .BR vfork (),
282 a thread in the parent process drops the process to an unprivileged user
283 in order to run some untrusted code
284 (e.g., perhaps via plug-in opened with
285 .BR dlopen (3)).
286 In this case, attacks are possible where the parent process uses
287 .BR mmap (2)
288 to map in code that will be executed by the privileged child process.
289 .\"
290 .SH BUGS
291 Details of the signal handling are obscure and differ between systems.
292 The BSD man page states:
293 "To avoid a possible deadlock situation, processes that are children
294 in the middle of a
295 .BR vfork ()
296 are never sent
297 .B SIGTTOU
298 or
299 .B SIGTTIN
300 signals;
301 rather, output or
302 .IR ioctl s
303 are allowed and input attempts result in an end-of-file indication."
304 .\"
305 .\" As far as I can tell, the following is not true in Linux 2.6.19:
306 .\" Currently (Linux 2.3.25),
307 .\" .BR strace (1)
308 .\" cannot follow
309 .\" .BR vfork ()
310 .\" and requires a kernel patch.
311 .SH SEE ALSO
312 .BR clone (2),
313 .BR execve (2),
314 .BR _exit (2),
315 .BR fork (2),
316 .BR _Fork (3),
317 .BR unshare (2),
318 .BR wait (2)