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
35 .Nd create a new process
47 function causes creation of a new process.
48 The new process (child process) is an exact copy of the
49 calling process (parent process) except for the following:
50 .Bl -bullet -offset indent
52 The child process has a unique process ID.
54 The child process has a different parent
55 process ID (i.e., the process ID of the parent process).
57 The child process has its own copy of the parent's descriptors,
58 except for descriptors returned by
60 which are not inherited from the parent process.
61 These descriptors reference the same underlying objects, so that,
62 for instance, file pointers in file objects are shared between
63 the child and the parent, so that an
65 on a descriptor in the child process can affect a subsequent
70 This descriptor copying is also used by the shell to
71 establish standard input and output for newly created processes
72 as well as to set up pipes.
74 The child process' resource utilizations
78 All interval timers are cleared; see
81 The robust mutexes list (see
82 .Xr pthread_mutexattr_setrobust 3 )
83 is cleared for the child.
85 The atfork handlers established with the
87 function are called as appropriate before fork in the parent process,
88 and after the child is created, in parent and child.
90 The child process has only one thread,
91 corresponding to the calling thread in the parent process.
92 If the process has more than one thread,
93 locks and other resources held by the other threads are not released
94 and therefore only async-signal-safe functions
97 are guaranteed to work in the child process until a call to
99 or a similar function.
108 services in the child process.
113 function is not async-signal safe and creates a cancellation point
114 in the parent process.
115 It cannot be safely used from signal handlers, and the atfork handlers
118 do not need to be async-signal safe either.
122 function creates a new process, similarly to
124 but it is async-signal safe.
126 does not call atfork handlers, and does not create a cancellation point.
127 It can be used safely from signal handlers, but then no userspace
132 are available in the child if forked from multi-threaded parent.
133 In particular, if using dynamic linking, all dynamic symbols used by the
136 must be pre-resolved.
137 Note: resolving can be done globally by specifying the
139 environment variable to the dynamic linker, or per-binary by passing the
141 option to the static linker
143 or by using each symbol before the
145 call to force the binding.
147 Upon successful completion,
152 of 0 to the child process and return the process ID of the child
153 process to the parent process.
154 Otherwise, a value of -1 is returned
155 to the parent process, no child process is created, and the global
158 is set to indicate the error.
160 The following example shows a common pattern of how
163 .Bd -literal -offset indent
175 * If child is expected to use stdio(3), state of
176 * the reused io streams must be synchronized between
177 * parent and child, to avoid double output and other
182 switch (pid = fork()) {
184 err(1, "Failed to fork");
186 printf("Hello from child process!\en");
189 * Since we wrote into stdout, child needs to use
190 * exit(3) and not _exit(2). This causes handlers
191 * registered with atexit(3) to be called twice,
192 * once in parent, and once in the child. If such
193 * behavior is undesirable, consider
194 * terminating child with _exit(2) or _Exit(3).
201 printf("Hello from parent process (child's PID: %d)!\en", pid);
207 The output of such a program is along the lines of:
208 .Bd -literal -offset indent
209 Hello from parent process (child's PID: 27804)!
210 Hello from child process!
215 system call will fail and no child process will be created if:
218 The system-imposed limit on the total
219 number of processes under execution would be exceeded.
220 The limit is given by the
224 (The limit is actually ten less than this
225 except for the super user).
227 The user is not the super user, and
228 the system-imposed limit
229 on the total number of
230 processes under execution by a single user would be exceeded.
231 The limit is given by the
234 .Dv KERN_MAXPROCPERUID .
236 The user is not the super user, and
237 the soft resource limit corresponding to the
241 would be exceeded (see
244 There is insufficient swap space for the new process.
263 function was defined by Austin Group together with the removal
264 of a requirement that the
266 implementation must be async-signal safe.