| blob | 8430ec63062d596d146d69e378225e77c47a3d84 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1994, X/Open Company Limited. All Rights Reserved.
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .TH FORK 2 "Nov 26, 2017"
13 .SH NAME
14 fork, fork1, forkall, forkx, forkallx \- create a new process
15 .SH SYNOPSIS
16 .LP
17 .nf
18 #include <sys/types.h>
19 #include <unistd.h>
21 \fBpid_t\fR \fBfork\fR(\fBvoid\fR);
22 .fi
24 .LP
25 .nf
26 \fBpid_t\fR \fBfork1\fR(\fBvoid\fR);
27 .fi
29 .LP
30 .nf
31 \fBpid_t\fR \fBforkall\fR(\fBvoid\fR);
32 .fi
34 .LP
35 .nf
36 #include <sys/fork.h>
38 \fBpid_t\fR \fBforkx\fR(\fBint\fR \fIflags\fR);
39 .fi
41 .LP
42 .nf
43 \fBpid_t\fR \fBforkallx\fR(\fBint\fR \fIflags\fR);
44 .fi
46 .SH DESCRIPTION
47 .LP
48 The \fBfork()\fR, \fBfork1()\fR, \fBforkall()\fR, \fBforkx()\fR, and
49 \fBforkallx()\fR functions create a new process. The address space of the new
50 process (child process) is an exact copy of the address space of the calling
51 process (parent process). The child process inherits the following attributes
52 from the parent process:
53 .RS +4
54 .TP
55 .ie t \(bu
56 .el o
57 real user ID, real group ID, effective user ID, effective group ID
58 .RE
59 .RS +4
60 .TP
61 .ie t \(bu
62 .el o
63 environment
64 .RE
65 .RS +4
66 .TP
67 .ie t \(bu
68 .el o
69 open file descriptors
70 .RE
71 .RS +4
72 .TP
73 .ie t \(bu
74 .el o
75 close-on-exec flags (see \fBexec\fR(2))
76 .RE
77 .RS +4
78 .TP
79 .ie t \(bu
80 .el o
81 signal handling settings (that is, \fBSIG_DFL\fR, \fBSIG_IGN\fR,
82 \fBSIG_HOLD\fR, function address)
83 .RE
84 .RS +4
85 .TP
86 .ie t \(bu
87 .el o
88 supplementary group IDs
89 .RE
90 .RS +4
91 .TP
92 .ie t \(bu
93 .el o
94 set-user-ID mode bit
95 .RE
96 .RS +4
97 .TP
98 .ie t \(bu
99 .el o
100 set-group-ID mode bit
101 .RE
102 .RS +4
103 .TP
104 .ie t \(bu
105 .el o
106 profiling on/off status
107 .RE
108 .RS +4
109 .TP
110 .ie t \(bu
111 .el o
112 nice value (see \fBnice\fR(2))
113 .RE
114 .RS +4
115 .TP
116 .ie t \(bu
117 .el o
118 scheduler class (see \fBpriocntl\fR(2))
119 .RE
120 .RS +4
121 .TP
122 .ie t \(bu
123 .el o
124 all attached shared memory segments (see \fBshmop\fR(2))
125 .RE
126 .RS +4
127 .TP
128 .ie t \(bu
129 .el o
130 process group \fBID\fR -- memory mappings (see \fBmmap\fR(2))
131 .RE
132 .RS +4
133 .TP
134 .ie t \(bu
135 .el o
136 session \fBID\fR (see \fBexit\fR(2))
137 .RE
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 current working directory
143 .RE
144 .RS +4
145 .TP
146 .ie t \(bu
147 .el o
148 root directory
149 .RE
150 .RS +4
151 .TP
152 .ie t \(bu
153 .el o
154 file mode creation mask (see \fBumask\fR(2))
155 .RE
156 .RS +4
157 .TP
158 .ie t \(bu
159 .el o
160 resource limits (see \fBgetrlimit\fR(2))
161 .RE
162 .RS +4
163 .TP
164 .ie t \(bu
165 .el o
166 controlling terminal
167 .RE
168 .RS +4
169 .TP
170 .ie t \(bu
171 .el o
172 saved user \fBID\fR and group \fBID\fR
173 .RE
174 .RS +4
175 .TP
176 .ie t \(bu
177 .el o
178 task ID and project ID
179 .RE
180 .RS +4
181 .TP
182 .ie t \(bu
183 .el o
184 processor bindings (see \fBprocessor_bind\fR(2))
185 .RE
186 .RS +4
187 .TP
188 .ie t \(bu
189 .el o
190 processor set bindings (see \fBpset_bind\fR(2))
191 .RE
192 .RS +4
193 .TP
194 .ie t \(bu
195 .el o
196 process privilege sets (see \fBgetppriv\fR(2))
197 .RE
198 .RS +4
199 .TP
200 .ie t \(bu
201 .el o
202 process flags (see \fBgetpflags\fR(2))
203 .RE
204 .RS +4
205 .TP
206 .ie t \(bu
207 .el o
208 active contract templates (see \fBcontract\fR(4))
209 .RE
210 .sp
211 .LP
212 Scheduling priority and any per-process scheduling parameters that are specific
213 to a given scheduling class might or might not be inherited according to the
214 policy of that particular class (see \fBpriocntl\fR(2)). The child process
215 might or might not be in the same process contract as the parent (see
216 \fBprocess\fR(4)). The child process differs from the parent process in the
217 following ways:
218 .RS +4
219 .TP
220 .ie t \(bu
221 .el o
222 The child process has a unique process \fBID\fR which does not match any active
223 process group \fBID\fR.
224 .RE
225 .RS +4
226 .TP
227 .ie t \(bu
228 .el o
229 The child process has a different parent process \fBID\fR (that is, the process
230 \fBID\fR of the parent process).
231 .RE
232 .RS +4
233 .TP
234 .ie t \(bu
235 .el o
236 The child process has its own copy of the parent's file descriptors and
237 directory streams. Each of the child's file descriptors shares a common file
238 pointer with the corresponding file descriptor of the parent.
239 .RE
240 .RS +4
241 .TP
242 .ie t \(bu
243 .el o
244 Each shared memory segment remains attached and the value of \fBshm_nattach\fR
245 is incremented by 1.
246 .RE
247 .RS +4
248 .TP
249 .ie t \(bu
250 .el o
251 All \fBsemadj\fR values are cleared (see \fBsemop\fR(2)).
252 .RE
253 .RS +4
254 .TP
255 .ie t \(bu
256 .el o
257 Process locks, text locks, data locks, and other memory locks are not inherited
258 by the child (see \fBplock\fR(3C) and \fBmemcntl\fR(2)).
259 .RE
260 .RS +4
261 .TP
262 .ie t \(bu
263 .el o
264 The child process's \fBtms\fR structure is cleared: \fBtms_utime\fR,
265 \fBstime\fR, \fBcutime\fR, and \fBcstime\fR are set to 0 (see \fBtimes\fR(2)).
266 .RE
267 .RS +4
268 .TP
269 .ie t \(bu
270 .el o
271 The child processes resource utilizations are set to 0; see \fBgetrlimit\fR(2).
272 The \fBit_value\fR and \fBit_interval\fR values for the \fBITIMER_REAL\fR timer
273 are reset to 0; see \fBgetitimer\fR(2).
274 .RE
275 .RS +4
276 .TP
277 .ie t \(bu
278 .el o
279 The set of signals pending for the child process is initialized to the empty
280 set.
281 .RE
282 .RS +4
283 .TP
284 .ie t \(bu
285 .el o
286 Timers created by \fBtimer_create\fR(3C) are not inherited by the child
287 process.
288 .RE
289 .RS +4
290 .TP
291 .ie t \(bu
292 .el o
293 No asynchronous input or asynchronous output operations are inherited by the
294 child.
295 .RE
296 .RS +4
297 .TP
298 .ie t \(bu
299 .el o
300 Any preferred hardware address translation sizes (see \fBmemcntl\fR(2)) are
301 inherited by the child.
302 .RE
303 .RS +4
304 .TP
305 .ie t \(bu
306 .el o
307 The child process holds no contracts (see \fBcontract\fR(4)).
308 .RE
309 .sp
310 .LP
311 Record locks set by the parent process are not inherited by the child process
312 (see \fBfcntl\fR(2)).
313 .sp
314 .LP
315 Although any open door descriptors in the parent are shared by the child, only
316 the parent will receive a door invocation from clients even if the door
317 descriptor is open in the child. If a descriptor is closed in the parent,
318 attempts to operate on the door descriptor will fail even if it is still open
319 in the child.
320 .SS "Threads"
321 .LP
322 A call to \fBforkall()\fR or \fBforkallx()\fR replicates in the child process
323 all of the threads (see \fBthr_create\fR(3C) and \fBpthread_create\fR(3C)) in
324 the parent process. A call to \fBfork1()\fR or \fBforkx()\fR replicates only
325 the calling thread in the child process.
326 .sp
327 .LP
328 A call to \fBfork()\fR is identical to a call to \fBfork1()\fR; only the
329 calling thread is replicated in the child process. This is the POSIX-specified
330 behavior for \fBfork()\fR.
331 .sp
332 .LP
333 In releases of Solaris prior to Solaris 10, the behavior of \fBfork()\fR
334 depended on whether or not the application was linked with the POSIX threads
335 library. When linked with \fB-lthread\fR (Solaris Threads) but not linked with
336 \fB-lpthread\fR (POSIX Threads), \fBfork()\fR was the same as \fBforkall()\fR.
337 When linked with \fB-lpthread\fR, whether or not also linked with
338 \fB-lthread\fR, \fBfork()\fR was the same as \fBfork1()\fR.
339 .sp
340 .LP
341 Prior to Solaris 10, either \fB-lthread\fR or \fB-lpthread\fR was required for
342 multithreaded applications. This is no longer the case. The standard C library
343 provides all threading support for both sets of application programming
344 interfaces. Applications that require replicate-all fork semantics must call
345 \fBforkall()\fR or \fBforkallx()\fR.
346 .SS "Fork Extensions"
347 .LP
348 The \fBforkx()\fR and \fBforkallx()\fR functions accept a \fIflags\fR argument
349 consisting of a bitwise inclusive-OR of zero or more of the following flags,
350 which are defined in the header \fB<sys/fork.h>\fR:
351 .sp
352 .ne 2
353 .na
354 \fB\fBFORK_NOSIGCHLD\fR\fR
355 .ad
356 .sp .6
357 .RS 4n
358 Do not post a \fBSIGCHLD\fR signal to the parent process when the child process
359 terminates, regardless of the disposition of the \fBSIGCHLD\fR signal in the
360 parent. \fBSIGCHLD\fR signals are still possible for job control stop and
361 continue actions if the parent has requested them.
362 .RE
364 .sp
365 .ne 2
366 .na
367 \fB\fBFORK_WAITPID\fR\fR
368 .ad
369 .sp .6
370 .RS 4n
371 Do not allow wait-for-multiple-pids by the parent, as in \fBwait()\fR,
372 \fBwaitid\fR(\fBP_ALL\fR), or \fBwaitid\fR(\fBP_PGID\fR), to reap the child and
373 do not allow the child to be reaped automatically due the disposition of the
374 SIGCHLD signal being set to be ignored in the parent. Only a specific wait for
375 the child, as in \fBwaitid\fR(\fBP_PID\fR, \fBpid\fR), is allowed and it is
376 required, else when the child exits it will remain a zombie until the parent
377 exits.
378 .RE
380 .sp
381 .LP
382 If the \fIflags\fR argument is 0 \fBforkx()\fR is identical to \fBfork()\fR and
383 \fBforkallx()\fR is identical to \fBforkall()\fR.
384 .SS "\fBfork()\fR Safety"
385 .LP
386 If a multithreaded application calls \fBfork()\fR, \fBfork1()\fR, or
387 \fBforkx()\fR, and the child does more than simply call one of the
388 \fBexec\fR(2) functions, there is a possibility of deadlock occurring in the
389 child. The application should use \fBpthread_atfork\fR(3C) to ensure safety
390 with respect to this deadlock. Should there be any outstanding mutexes
391 throughout the process, the application should call \fBpthread_atfork()\fR to
392 wait for and acquire those mutexes prior to calling \fBfork()\fR,
393 \fBfork1()\fR, or \fBforkx()\fR. See "MT-Level of Libraries" on the
394 \fBattributes\fR(5) manual page.
395 .sp
396 .LP
397 The \fBpthread_atfork()\fR mechanism is used to protect the locks that
398 \fBlibc\fR(3LIB) uses to implement interfaces such as \fBmalloc\fR(3C). All
399 interfaces provided by \fBlibc\fR are safe to use in a child process following
400 a \fBfork()\fR, except when \fBfork()\fR is executed within a signal handler.
401 .sp
402 .LP
403 The POSIX standard (see \fBstandards\fR(5)) requires fork to be
404 Async-Signal-Safe (see \fBattributes\fR(5)). This cannot be made to happen with
405 fork handlers in place, because they acquire locks. To be in nominal
406 compliance, no fork handlers are called when \fBfork()\fR is executed within a
407 signal context. This leaves the child process in a questionable state with
408 respect to its locks, but at least the calling thread will not deadlock itself
409 attempting to acquire a lock that it already owns. In this situation, the
410 application should strictly adhere to the advice given in the POSIX
411 specification: "To avoid errors, the child process may only execute
412 Async-Signal-Safe operations until such time as one of the \fBexec\fR(2)
413 functions is called."
414 .SH RETURN VALUES
415 .LP
416 Upon successful completion, \fBfork()\fR, \fBfork1()\fR, \fBforkall()\fR,
417 \fBforkx()\fR, and \fBforkallx()\fR return \fB0\fR to the child process and
418 return the process \fBID\fR of the child process to the parent process.
419 Otherwise, \fB(pid_t)\(mi1\fR is returned to the parent process, no child
420 process is created, and \fBerrno\fR is set to indicate the error.
421 .SH ERRORS
422 .LP
423 The \fBfork()\fR, \fBfork1()\fR, \fBforkall()\fR, \fBforkx()\fR, and
424 \fBforkallx()\fR functions will fail if:
425 .sp
426 .ne 2
427 .na
428 \fB\fBEAGAIN\fR\fR
429 .ad
430 .RS 10n
431 A resource control or limit on the total number of processes, tasks or LWPs
432 under execution by a single user, task, project, or zone has been exceeded, or
433 the total amount of system memory available is temporarily insufficient to
434 duplicate this process.
435 .RE
437 .sp
438 .ne 2
439 .na
440 \fB\fBENOMEM\fR\fR
441 .ad
442 .RS 10n
443 There is not enough swap space.
444 .RE
446 .sp
447 .ne 2
448 .na
449 \fB\fBEPERM\fR\fR
450 .ad
451 .RS 10n
452 The {\fBPRIV_PROC_FORK\fR} privilege is not asserted in the effective set of
453 the calling process.
454 .RE
456 .sp
457 .LP
458 The \fBforkx()\fR and \fBforkallx()\fR functions will fail if:
459 .sp
460 .ne 2
461 .na
462 \fB\fBEINVAL\fR\fR
463 .ad
464 .RS 10n
465 The \fIflags\fR argument is invalid.
466 .RE
468 .SH ATTRIBUTES
469 .LP
470 See \fBattributes\fR(5) for descriptions of the following attributes:
471 .sp
473 .sp
474 .TS
475 box;
476 c | c
477 l | l .
478 ATTRIBUTE TYPE ATTRIBUTE VALUE
479 _
480 Interface Stability Committed
481 _
482 MT-Level Async-Signal-Safe.
483 _
484 Standard See below.
485 .TE
487 .sp
488 .LP
489 For \fBfork()\fR, see \fBstandards\fR(5).
490 .SH SEE ALSO
491 .LP
492 \fBalarm\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfcntl\fR(2),
493 \fBgetitimer\fR(2), \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2),
494 \fBnice\fR(2), \fBpriocntl\fR(2), \fBsemop\fR(2), \fBshmop\fR(2),
495 \fBtimes\fR(2), \fBumask\fR(2), \fBwaitid\fR(2), \fBdoor_create\fR(3C),
496 \fBexit\fR(3C), \fBplock\fR(3C), \fBpthread_atfork\fR(3C),
497 \fBpthread_create\fR(3C), \fBsignal\fR(3C), \fBsystem\fR(3C),
498 \fBthr_create\fR(3C) \fBtimer_create\fR(3C), \fBwait\fR(3C), \fBcontract\fR(4),
499 \fBprocess\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5)
500 .SH NOTES
501 .LP
502 An application should call \fB_exit()\fR rather than \fBexit\fR(3C) if it
503 cannot \fBexecve()\fR, since \fBexit()\fR will flush and close standard I/O
504 channels and thereby corrupt the parent process's standard I/O data structures.
505 Using \fBexit\fR(3C) will flush buffered data twice. See \fBexit\fR(2).
506 .sp
507 .LP
508 The thread in the child that calls \fBfork()\fR, \fBfork1()\fR, or
509 \fBfork1x()\fR must not depend on any resources held by threads that no longer
510 exist in the child. In particular, locks held by these threads will not be
511 released.
512 .sp
513 .LP
514 In a multithreaded process, \fBforkall()\fR in one thread can cause blocking
515 system calls to be interrupted and return with an \fBEINTR\fR error.