Print this page
5776 vfork and getwd should not be exposed under XPG7
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/vfork.2
+++ new/usr/src/man/man2/vfork.2
1 -'\" te
1 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 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
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
27 28 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
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
35 44 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
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
44 64 conditions that can cause the child process to become deadlocked and
45 65 consequently block both the child and parent process from execution
46 66 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,
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,
51 77 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
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
57 95 process's standard I/O data structures. Care must be taken in the child process
58 96 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
97 +process on return from
98 +.Fn vfork
99 +or
100 +.Fn vforkx ,
101 +unless such an effect
60 102 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
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
68 119 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
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
75 131 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
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
106 169 The system-imposed limit on the total number of processes under execution
107 170 (either system-quality or by a single user) would be exceeded. This limit is
108 171 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
172 +.
173 +.It Er ENOMEM
117 174 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
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
159 211 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
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
165 225 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
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
176 253 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.
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.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX