1 .\" Copyright (c) 1980, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)fork.2 8.1 (Berkeley) 6/4/93
36 .Nd create a new process
48 function causes creation of a new process.
49 The new process (child process) is an exact copy of the
50 calling process (parent process) except for the following:
51 .Bl -bullet -offset indent
53 The child process has a unique process ID.
55 The child process has a different parent
56 process ID (i.e., the process ID of the parent process).
58 The child process has its own copy of the parent's descriptors,
59 except for descriptors returned by
61 which are not inherited from the parent process.
62 These descriptors reference the same underlying objects, so that,
63 for instance, file pointers in file objects are shared between
64 the child and the parent, so that an
66 on a descriptor in the child process can affect a subsequent
71 This descriptor copying is also used by the shell to
72 establish standard input and output for newly created processes
73 as well as to set up pipes.
75 The child process' resource utilizations
79 All interval timers are cleared; see
82 The robust mutexes list (see
83 .Xr pthread_mutexattr_setrobust 3 )
84 is cleared for the child.
86 The atfork handlers established with the
88 function are called as appropriate before fork in the parent process,
89 and after the child is created, in parent and child.
91 The child process has only one thread,
92 corresponding to the calling thread in the parent process.
93 If the process has more than one thread,
94 locks and other resources held by the other threads are not released
95 and therefore only async-signal-safe functions
98 are guaranteed to work in the child process until a call to
100 or a similar function.
109 services in the child process.
114 function is not async-signal safe and creates a cancellation point
115 in the parent process.
116 It cannot be safely used from signal handlers, and the atfork handlers
119 do not need to be async-signal safe either.
123 function creates a new process, similarly to
125 but it is async-signal safe.
127 does not call atfork handlers, and does not create a cancellation point.
128 It can be used safely from signal handlers, but then no userspace
133 are available in the child if forked from multi-threaded parent.
134 In particular, if using dynamic linking, all dynamic symbols used by the
137 must be pre-resolved.
138 Note: resolving can be done globally by specifying the
140 environment variable to the dynamic linker, or per-binary by passing the
142 option to the static linker
144 or by using each symbol before the
146 call to force the binding.
148 Upon successful completion,
153 of 0 to the child process and return the process ID of the child
154 process to the parent process.
155 Otherwise, a value of -1 is returned
156 to the parent process, no child process is created, and the global
159 is set to indicate the error.
161 The following example shows a common pattern of how
164 .Bd -literal -offset indent
176 * If child is expected to use stdio(3), state of
177 * the reused io streams must be synchronized between
178 * parent and child, to avoid double output and other
183 switch (pid = fork()) {
185 err(1, "Failed to fork");
187 printf("Hello from child process!\en");
190 * Since we wrote into stdout, child needs to use
191 * exit(3) and not _exit(2). This causes handlers
192 * registered with atexit(3) to be called twice,
193 * once in parent, and once in the child. If such
194 * behavior is undesirable, consider
195 * terminating child with _exit(2) or _Exit(3).
202 printf("Hello from parent process (child's PID: %d)!\en", pid);
208 The output of such a program is along the lines of:
209 .Bd -literal -offset indent
210 Hello from parent process (child's PID: 27804)!
211 Hello from child process!
216 system call will fail and no child process will be created if:
219 The system-imposed limit on the total
220 number of processes under execution would be exceeded.
221 The limit is given by the
225 (The limit is actually ten less than this
226 except for the super user).
228 The user is not the super user, and
229 the system-imposed limit
230 on the total number of
231 processes under execution by a single user would be exceeded.
232 The limit is given by the
235 .Dv KERN_MAXPROCPERUID .
237 The user is not the super user, and
238 the soft resource limit corresponding to the
242 would be exceeded (see
245 There is insufficient swap space for the new process.
264 function was defined by Austin Group together with the removal
265 of a requirement that the
267 implementation must be async-signal safe.