xref: /titanic_41/usr/src/man/man2/vfork.2 (revision c888b1c3835492216ff6c65b22767dc4d7f187ab)
1*c888b1c3SGarrett D'Amore.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2c10c16deSRichard Lowe.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
3c10c16deSRichard Lowe.\" Copyright 1989 AT&T.
4*c888b1c3SGarrett D'Amore.\" Copyright (c) 1980 Regents of the University of California.
5*c888b1c3SGarrett D'Amore.\" All rights reserved.  The Berkeley software License Agreement
6*c888b1c3SGarrett D'Amore.\" specifies the terms and conditions for redistribution.
7*c888b1c3SGarrett D'Amore.Dd Aug 20, 2014
8*c888b1c3SGarrett D'Amore.Dt VFORK 2
9*c888b1c3SGarrett D'Amore.Os
10*c888b1c3SGarrett D'Amore.Sh NAME
11*c888b1c3SGarrett D'Amore.Nm vfork ,
12*c888b1c3SGarrett D'Amore.Nm vforkx
13*c888b1c3SGarrett D'Amore.Nd spawn new process in a virtual memory efficient way
14*c888b1c3SGarrett D'Amore.Sh SYNOPSIS
15*c888b1c3SGarrett D'Amore.In unistd.h
16*c888b1c3SGarrett D'Amore.Ft pid_t
17*c888b1c3SGarrett D'Amore.Fn vfork void
18*c888b1c3SGarrett D'Amore.
19*c888b1c3SGarrett D'Amore.In sys/fork.h
20*c888b1c3SGarrett D'Amore.Ft pid_t
21*c888b1c3SGarrett D'Amore.Fn vforkx "int flags"
22*c888b1c3SGarrett D'Amore.Sh DESCRIPTION
23*c888b1c3SGarrett D'AmoreThe
24*c888b1c3SGarrett D'Amore.Fn vfork
25*c888b1c3SGarrett D'Amoreand
26*c888b1c3SGarrett D'Amore.Fn vforkx
27*c888b1c3SGarrett D'Amorefunctions create a new process without
28c10c16deSRichard Lowefully copying the address space of the old process. These functions are useful
29*c888b1c3SGarrett D'Amorein instances where the purpose of a
30*c888b1c3SGarrett D'Amore.Xr fork 2
31*c888b1c3SGarrett D'Amoreoperation is to create a new
32*c888b1c3SGarrett D'Amoresystem context for an
33*c888b1c3SGarrett D'Amore.Xr exec 2
34*c888b1c3SGarrett D'Amoreoperation.
35*c888b1c3SGarrett D'Amore.Lp
36*c888b1c3SGarrett D'AmoreUnlike with the
37*c888b1c3SGarrett D'Amore.Fn fork
38*c888b1c3SGarrett D'Amorefunction, the child process borrows the parent's
39*c888b1c3SGarrett D'Amorememory and thread of control until a call to
40*c888b1c3SGarrett D'Amore.Fn execve
41*c888b1c3SGarrett D'Amoreor an exit
42*c888b1c3SGarrett D'Amore.Pq either abnormally or by a call to Xr _exit 2 .
43*c888b1c3SGarrett D'AmoreAny modification
44c10c16deSRichard Lowemade during this time to any part of memory in the child process is reflected
45*c888b1c3SGarrett D'Amorein the parent process on return from
46*c888b1c3SGarrett D'Amore.Fn vfork
47*c888b1c3SGarrett D'Amoreor
48*c888b1c3SGarrett D'Amore.Fn vforkx .
49*c888b1c3SGarrett D'AmoreThe parent process is suspended while the child is using its resources.
50*c888b1c3SGarrett D'Amore.Lp
51*c888b1c3SGarrett D'AmoreIn a multithreaded application,
52*c888b1c3SGarrett D'Amore.Fn vfork
53*c888b1c3SGarrett D'Amoreand
54*c888b1c3SGarrett D'Amore.Fn vforkx
55*c888b1c3SGarrett D'Amoreborrow only the thread of control that called
56*c888b1c3SGarrett D'Amore.Fn vfork
57*c888b1c3SGarrett D'Amoreor
58*c888b1c3SGarrett D'Amore.Fn vforkx
59*c888b1c3SGarrett D'Amorein the parent; that is, the child contains only one thread. The use of
60*c888b1c3SGarrett D'Amore.Fn vfork
61*c888b1c3SGarrett D'Amoreor
62*c888b1c3SGarrett D'Amore.Fn vforkx
63*c888b1c3SGarrett D'Amorein multithreaded applications, however, is unsafe due to race
64c10c16deSRichard Loweconditions that can cause the child process to become deadlocked and
65c10c16deSRichard Loweconsequently block both the child and parent process from execution
66c10c16deSRichard Loweindefinitely.
67*c888b1c3SGarrett D'Amore.Lp
68*c888b1c3SGarrett D'AmoreThe
69*c888b1c3SGarrett D'Amore.Fn vfork
70*c888b1c3SGarrett D'Amoreand
71*c888b1c3SGarrett D'Amore.Fn vforkx
72*c888b1c3SGarrett D'Amorefunctions can normally be used the same way as
73*c888b1c3SGarrett D'Amore.Fn fork
74*c888b1c3SGarrett D'Amoreand
75*c888b1c3SGarrett D'Amore.Fn forkx ,
76*c888b1c3SGarrett D'Amorerespectively. The calling procedure,
77c10c16deSRichard Lowehowever, should not return while running in the child's context, since the
78*c888b1c3SGarrett D'Amoreeventual return from
79*c888b1c3SGarrett D'Amore.Fn vfork
80*c888b1c3SGarrett D'Amoreor
81*c888b1c3SGarrett D'Amore.Fn vforkx
82*c888b1c3SGarrett D'Amorein the parent would be to
83*c888b1c3SGarrett D'Amorea stack frame that no longer exists. The
84*c888b1c3SGarrett D'Amore.Fn _exit
85*c888b1c3SGarrett D'Amorefunction should be used
86*c888b1c3SGarrett D'Amorein favor of
87*c888b1c3SGarrett D'Amore.Xr exit 3C
88*c888b1c3SGarrett D'Amoreif unable to perform an
89*c888b1c3SGarrett D'Amore.Fn execve
90*c888b1c3SGarrett D'Amoreoperation, since
91*c888b1c3SGarrett D'Amore.Fn exit
92*c888b1c3SGarrett D'Amorewill invoke all functions registered by
93*c888b1c3SGarrett D'Amore.Xr atexit 3C
94*c888b1c3SGarrett D'Amoreand will flush and close standard I/O channels, thereby corrupting the parent
95c10c16deSRichard Loweprocess's standard I/O data structures. Care must be taken in the child process
96c10c16deSRichard Lowenot to modify any global or local data that affects the behavior of the parent
97*c888b1c3SGarrett D'Amoreprocess on return from
98*c888b1c3SGarrett D'Amore.Fn vfork
99*c888b1c3SGarrett D'Amoreor
100*c888b1c3SGarrett D'Amore.Fn vforkx ,
101*c888b1c3SGarrett D'Amoreunless such an effect
102c10c16deSRichard Loweis intentional.
103*c888b1c3SGarrett D'Amore.Lp
104*c888b1c3SGarrett D'AmoreUnlike
105*c888b1c3SGarrett D'Amore.Fn fork
106*c888b1c3SGarrett D'Amoreand
107*c888b1c3SGarrett D'Amore.Fn forkx ,
108*c888b1c3SGarrett D'Amorefork handlers are not run when
109*c888b1c3SGarrett D'Amore.Fn vfork
110*c888b1c3SGarrett D'Amoreand
111*c888b1c3SGarrett D'Amore.Fn vforkx
112*c888b1c3SGarrett D'Amoreare called.
113*c888b1c3SGarrett D'Amore.Lp
114*c888b1c3SGarrett D'AmoreThe
115*c888b1c3SGarrett D'Amore.Fn vfork
116*c888b1c3SGarrett D'Amoreand
117*c888b1c3SGarrett D'Amore.Fn vforkx
118*c888b1c3SGarrett D'Amorefunctions are deprecated. Their sole
119c10c16deSRichard Lowelegitimate use as a prelude to an immediate call to a function from the
120*c888b1c3SGarrett D'Amore.Xr exec 2
121*c888b1c3SGarrett D'Amorefamily can be achieved safely by
122*c888b1c3SGarrett D'Amore.Xr posix_spawn 3C
123*c888b1c3SGarrett D'Amoreor
124*c888b1c3SGarrett D'Amore.Xr posix_spawnp 3C .
125*c888b1c3SGarrett D'Amore.Ss "Fork Extensions"
126*c888b1c3SGarrett D'AmoreThe
127*c888b1c3SGarrett D'Amore.Fn vforkx
128*c888b1c3SGarrett D'Amorefunction accepts a
129*c888b1c3SGarrett D'Amore.Fa flags
130*c888b1c3SGarrett D'Amoreargument consisting of a
131c10c16deSRichard Lowebitwise inclusive-OR of zero or more of the following flags, which are defined
132*c888b1c3SGarrett D'Amorein the header
133*c888b1c3SGarrett D'Amore.In sys/fork.h :
134*c888b1c3SGarrett D'Amore.Lp
135*c888b1c3SGarrett D'Amore.Bl -item -compact -offset indent
136*c888b1c3SGarrett D'Amore.It
137*c888b1c3SGarrett D'Amore.Dv FORK_NOSIGCHLD
138*c888b1c3SGarrett D'Amore.It
139*c888b1c3SGarrett D'Amore.Dv FORK_WAITPID
140*c888b1c3SGarrett D'Amore.El
141*c888b1c3SGarrett D'Amore.Lp
142*c888b1c3SGarrett D'AmoreSee
143*c888b1c3SGarrett D'Amore.Xr fork 2
144*c888b1c3SGarrett D'Amorefor descriptions of these flags. If the
145*c888b1c3SGarrett D'Amore.Fa flags
146*c888b1c3SGarrett D'Amoreargument is 0,
147*c888b1c3SGarrett D'Amore.Fn vforkx
148*c888b1c3SGarrett D'Amoreis identical to
149*c888b1c3SGarrett D'Amore.Fn vfork .
150*c888b1c3SGarrett D'Amore.Sh RETURN VALUES
151*c888b1c3SGarrett D'AmoreUpon successful completion,
152*c888b1c3SGarrett D'Amore.Fn vfork
153*c888b1c3SGarrett D'Amoreand
154*c888b1c3SGarrett D'Amore.Fn vforkx
155*c888b1c3SGarrett D'Amorereturn 0 to
156*c888b1c3SGarrett D'Amorethe child process and return the process ID of the child process to the parent
157*c888b1c3SGarrett D'Amoreprocess. Otherwise, \(mi1 is returned to the parent process, no child
158*c888b1c3SGarrett D'Amoreprocess is created, and
159*c888b1c3SGarrett D'Amore.Va errno
160*c888b1c3SGarrett D'Amoreis set to indicate the error.
161*c888b1c3SGarrett D'Amore.Sh ERRORS
162*c888b1c3SGarrett D'AmoreThe
163*c888b1c3SGarrett D'Amore.Fn vfork
164*c888b1c3SGarrett D'Amoreand
165*c888b1c3SGarrett D'Amore.Fn vforkx
166*c888b1c3SGarrett D'Amorefunctions will fail if:
167*c888b1c3SGarrett D'Amore.Bl -tag -width Er
168*c888b1c3SGarrett D'Amore.It Er EAGAIN
169c10c16deSRichard LoweThe system-imposed limit on the total number of processes under execution
170c10c16deSRichard Lowe(either system-quality or by a single user) would be exceeded. This limit is
171c10c16deSRichard Lowedetermined when the system is generated.
172*c888b1c3SGarrett D'Amore.
173*c888b1c3SGarrett D'Amore.It Er ENOMEM
174c10c16deSRichard LoweThere is insufficient swap space for the new process.
175*c888b1c3SGarrett D'Amore.El
176*c888b1c3SGarrett D'Amore.Lp
177*c888b1c3SGarrett D'AmoreThe
178*c888b1c3SGarrett D'Amore.Fn vforkx
179*c888b1c3SGarrett D'Amorefunction will fail if:
180*c888b1c3SGarrett D'Amore.Bl -tag -width Er
181*c888b1c3SGarrett D'Amore.It Er EINVAL
182*c888b1c3SGarrett D'AmoreThe
183*c888b1c3SGarrett D'Amore.Va flags
184*c888b1c3SGarrett D'Amoreargument is invalid.
185*c888b1c3SGarrett D'Amore.El
186*c888b1c3SGarrett D'Amore.Sh INTERFACE STABILITY
187*c888b1c3SGarrett D'AmoreThe
188*c888b1c3SGarrett D'Amore.Fn vfork
189*c888b1c3SGarrett D'Amorefunction is
190*c888b1c3SGarrett D'Amore.Sy Obsolete Standard .
191*c888b1c3SGarrett D'Amore.Lp
192*c888b1c3SGarrett D'AmoreThe
193*c888b1c3SGarrett D'Amore.Fn vforkx
194*c888b1c3SGarrett D'Amorefunction is
195*c888b1c3SGarrett D'Amore.Sy Obsolete Uncommitted .
196*c888b1c3SGarrett D'Amore.Sh MT-LEVEL
197*c888b1c3SGarrett D'Amore.Sy Unsafe .
198*c888b1c3SGarrett D'Amore.Sh SEE ALSO
199*c888b1c3SGarrett D'Amore.Xr exec 2 ,
200*c888b1c3SGarrett D'Amore.Xr exit 2 ,
201*c888b1c3SGarrett D'Amore.Xr fork 2 ,
202*c888b1c3SGarrett D'Amore.Xr ioctl 2 ,
203*c888b1c3SGarrett D'Amore.Xr atexit 3C ,
204*c888b1c3SGarrett D'Amore.Xr exit 3C ,
205*c888b1c3SGarrett D'Amore.Xr posix_spawn 3C ,
206*c888b1c3SGarrett D'Amore.Xr posix_spawnp 3C ,
207*c888b1c3SGarrett D'Amore.Xr signal.h 3HEAD ,
208*c888b1c3SGarrett D'Amore.Xr wait 3C ,
209*c888b1c3SGarrett D'Amore.Xr standards 5
210*c888b1c3SGarrett D'Amore.Sh NOTES
211c10c16deSRichard LoweTo avoid a possible deadlock situation, processes that are children in the
212*c888b1c3SGarrett D'Amoremiddle of a
213*c888b1c3SGarrett D'Amore.Fn vfork
214*c888b1c3SGarrett D'Amoreor
215*c888b1c3SGarrett D'Amore.Fn vforkx
216*c888b1c3SGarrett D'Amoreare never sent
217*c888b1c3SGarrett D'Amore.Dv SIGTTOU
218*c888b1c3SGarrett D'Amoreor
219*c888b1c3SGarrett D'Amore.Dv SIGTTIN
220*c888b1c3SGarrett D'Amoresignals; rather, output or ioctls are allowed and input attempts
221*c888b1c3SGarrett D'Amoreresult in an
222*c888b1c3SGarrett D'Amore.Dv EOF
223*c888b1c3SGarrett D'Amoreindication.
224*c888b1c3SGarrett D'Amore.Lp
225c10c16deSRichard LoweTo forestall parent memory corruption due to race conditions with signal
226*c888b1c3SGarrett D'Amorehandling,
227*c888b1c3SGarrett D'Amore.Fn vfork
228*c888b1c3SGarrett D'Amoreand
229*c888b1c3SGarrett D'Amore.Fn vforkx
230*c888b1c3SGarrett D'Amoretreat signal handlers in the child
231*c888b1c3SGarrett D'Amoreprocess in the same manner as the
232*c888b1c3SGarrett D'Amore.Xr exec 2
233*c888b1c3SGarrett D'Amorefunctions: signals set to be
234*c888b1c3SGarrett D'Amorecaught by the parent process are set to the default action
235*c888b1c3SGarrett D'Amore.Pq Dv SIG_DFL
236*c888b1c3SGarrett D'Amorein the child process
237*c888b1c3SGarrett D'Amore.Pq see Xr signal.h 3HEAD .
238*c888b1c3SGarrett D'AmoreAny attempt to set a signal
239*c888b1c3SGarrett D'Amorehandler in the child before
240*c888b1c3SGarrett D'Amore.Fn execve
241*c888b1c3SGarrett D'Amoreto anything other than
242*c888b1c3SGarrett D'Amore.Dv SIG_DFL
243*c888b1c3SGarrett D'Amoreor
244*c888b1c3SGarrett D'Amore.Dv SIG_IGN
245*c888b1c3SGarrett D'Amoreis disallowed and results in setting the handler to
246*c888b1c3SGarrett D'Amore.Dv SIG_DFL .
247*c888b1c3SGarrett D'Amore.Lp
248*c888b1c3SGarrett D'AmoreOn some systems, the implementation of
249*c888b1c3SGarrett D'Amore.Fn vfork
250*c888b1c3SGarrett D'Amoreand
251*c888b1c3SGarrett D'Amore.Fn vforkx
252*c888b1c3SGarrett D'Amorecause
253c10c16deSRichard Lowethe parent to inherit register values from the child. This can create problems
254*c888b1c3SGarrett D'Amorefor certain optimizing compilers if
255*c888b1c3SGarrett D'Amore.In unistd.h
256*c888b1c3SGarrett D'Amoreis not included in the source calling
257*c888b1c3SGarrett D'Amore.Fn vfork
258*c888b1c3SGarrett D'Amoreor if
259*c888b1c3SGarrett D'Amore.In sys/fork.h
260*c888b1c3SGarrett D'Amoreis not included in the
261*c888b1c3SGarrett D'Amoresource calling
262*c888b1c3SGarrett D'Amore.Fn vforkx .
263*c888b1c3SGarrett D'Amore.Sh STANDARDS
264*c888b1c3SGarrett D'AmoreThe
265*c888b1c3SGarrett D'Amore.Fn vfork
266*c888b1c3SGarrett D'Amorefunction is available in the following compilation environments.  See
267*c888b1c3SGarrett D'Amore.Xr standards 5 .
268*c888b1c3SGarrett D'Amore.Lp
269*c888b1c3SGarrett D'Amore.Bl -bullet -compact
270*c888b1c3SGarrett D'Amore.It
271*c888b1c3SGarrett D'Amore.St -xpg4.2
272*c888b1c3SGarrett D'Amore.It
273*c888b1c3SGarrett D'Amore.St -susv2
274*c888b1c3SGarrett D'Amore.It
275*c888b1c3SGarrett D'Amore.St -susv3
276*c888b1c3SGarrett D'Amore.El
277*c888b1c3SGarrett D'Amore.Lp
278*c888b1c3SGarrett D'AmoreIt was marked obsolete in
279*c888b1c3SGarrett D'Amore.St -susv3
280*c888b1c3SGarrett D'Amoreand removed from
281*c888b1c3SGarrett D'Amore.St -p1003.1-2008 .
282*c888b1c3SGarrett D'Amore.Lp
283*c888b1c3SGarrett D'AmoreThe
284*c888b1c3SGarrett D'Amore.Fn vforkx
285*c888b1c3SGarrett D'Amorefunction is a local extension and not available in any strictly
286*c888b1c3SGarrett D'Amorestandards-compliant compilation environment.
287