]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
f5e74ede MK |
2 | .\" A few fragments remain from an earlier (1992) page by |
3 | .\" Drew Eckhardt (drew@cs.colorado.edu), | |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" Modified by Michael Haardt (michael@moria.de) | |
8 | .\" Modified Sat Jul 24 13:22:07 1993 by Rik Faith (faith@cs.unc.edu) | |
9 | .\" Modified 21 Aug 1994 by Michael Chastain (mec@shell.portal.com): | |
10 | .\" Referenced 'clone(2)'. | |
11 | .\" Modified 1995-06-10, 1996-04-18, 1999-11-01, 2000-12-24 | |
12 | .\" by Andries Brouwer (aeb@cwi.nl) | |
c11b1abf | 13 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 14 | .\" Added notes on capability requirements |
a99426d3 MK |
15 | .\" 2006-09-04, Michael Kerrisk |
16 | .\" Greatly expanded, to describe all attributes that differ | |
17 | .\" parent and child. | |
fea681da | 18 | .\" |
4c1c5274 | 19 | .TH fork 2 (date) "Linux man-pages (unreleased)" |
fea681da MK |
20 | .SH NAME |
21 | fork \- create a child process | |
643ff518 AC |
22 | .SH LIBRARY |
23 | Standard C library | |
8fc3b2cf | 24 | .RI ( libc ", " \-lc ) |
fea681da | 25 | .SH SYNOPSIS |
c7db92b9 | 26 | .nf |
fea681da | 27 | .B #include <unistd.h> |
68e4db0a | 28 | .PP |
fea681da | 29 | .B pid_t fork(void); |
c7db92b9 | 30 | .fi |
fea681da | 31 | .SH DESCRIPTION |
e511ffb6 | 32 | .BR fork () |
a99426d3 | 33 | creates a new process by duplicating the calling process. |
7f810a61 HS |
34 | The new process is referred to as the |
35 | .I child | |
36 | process. | |
37 | The calling process is referred to as the | |
38 | .I parent | |
39 | process. | |
efeece04 | 40 | .PP |
7f810a61 HS |
41 | The child process and the parent process run in separate memory spaces. |
42 | At the time of | |
43 | .BR fork () | |
44 | both memory spaces have the same content. | |
45 | Memory writes, file mappings | |
46 | .RB ( mmap (2)), | |
47 | and unmappings | |
48 | .RB ( munmap (2)) | |
49 | performed by one of the processes do not affect the other. | |
efeece04 | 50 | .PP |
7f810a61 HS |
51 | The child process is an exact duplicate of the parent |
52 | process except for the following points: | |
22356d97 | 53 | .IP \(bu 3 |
a99426d3 MK |
54 | The child has its own unique process ID, |
55 | and this PID does not match the ID of any existing process group | |
5a1fa66f MK |
56 | .RB ( setpgid (2)) |
57 | or session. | |
22356d97 | 58 | .IP \(bu |
a99426d3 | 59 | The child's parent process ID is the same as the parent's process ID. |
22356d97 | 60 | .IP \(bu |
a99426d3 MK |
61 | The child does not inherit its parent's memory locks |
62 | .RB ( mlock (2), | |
63 | .BR mlockall (2)). | |
22356d97 | 64 | .IP \(bu |
d9bfdb9c | 65 | Process resource utilizations |
a99426d3 MK |
66 | .RB ( getrusage (2)) |
67 | and CPU time counters | |
68 | .RB ( times (2)) | |
69 | are reset to zero in the child. | |
22356d97 | 70 | .IP \(bu |
65e7dad2 | 71 | The child's set of pending signals is initially empty |
a99426d3 | 72 | .RB ( sigpending (2)). |
22356d97 | 73 | .IP \(bu |
a99426d3 MK |
74 | The child does not inherit semaphore adjustments from its parent |
75 | .RB ( semop (2)). | |
22356d97 | 76 | .IP \(bu |
5879ccc0 | 77 | The child does not inherit process-associated record locks from its parent |
a99426d3 | 78 | .RB ( fcntl (2)). |
5879ccc0 MK |
79 | (On the other hand, it does inherit |
80 | .BR fcntl (2) | |
81 | open file description locks and | |
82 | .BR flock (2) | |
83 | locks from its parent.) | |
22356d97 | 84 | .IP \(bu |
0fb58b28 | 85 | The child does not inherit timers from its parent |
f5e74ede | 86 | .RB ( setitimer (2), |
76375bc6 | 87 | .BR alarm (2), |
804f03e6 | 88 | .BR timer_create (2)). |
22356d97 | 89 | .IP \(bu |
c13182ef | 90 | The child does not inherit outstanding asynchronous I/O operations |
a99426d3 MK |
91 | from its parent |
92 | .RB ( aio_read (3), | |
cb6a78e6 | 93 | .BR aio_write (3)), |
f75ad1f3 YK |
94 | nor does it inherit any asynchronous I/O contexts from its parent (see |
95 | .BR io_setup (2)). | |
c13182ef MK |
96 | .PP |
97 | The process attributes in the preceding list are all specified | |
9b612e3c | 98 | in POSIX.1. |
a99426d3 MK |
99 | The parent and child also differ with respect to the following |
100 | Linux-specific process attributes: | |
22356d97 | 101 | .IP \(bu 3 |
c13182ef | 102 | The child does not inherit directory change notifications (dnotify) |
a99426d3 MK |
103 | from its parent |
104 | (see the description of | |
c13182ef MK |
105 | .B F_NOTIFY |
106 | in | |
a99426d3 | 107 | .BR fcntl (2)). |
22356d97 | 108 | .IP \(bu |
a99426d3 MK |
109 | The |
110 | .BR prctl (2) | |
111 | .B PR_SET_PDEATHSIG | |
c13182ef | 112 | setting is reset so that the child does not receive a signal |
a99426d3 | 113 | when its parent terminates. |
22356d97 | 114 | .IP \(bu |
e089cba1 MK |
115 | The default timer slack value is set to the parent's |
116 | current timer slack value. | |
117 | See the description of | |
1ae6b2c7 | 118 | .B PR_SET_TIMERSLACK |
e089cba1 MK |
119 | in |
120 | .BR prctl (2). | |
22356d97 | 121 | .IP \(bu |
c13182ef | 122 | Memory mappings that have been marked with the |
78cb5911 MK |
123 | .BR madvise (2) |
124 | .B MADV_DONTFORK | |
125 | flag are not inherited across a | |
2777b1ca | 126 | .BR fork (). |
22356d97 | 127 | .IP \(bu |
64f89da8 | 128 | Memory in address ranges that have been marked with the |
399f3e39 RR |
129 | .BR madvise (2) |
130 | .B MADV_WIPEONFORK | |
131 | flag is zeroed in the child after a | |
132 | .BR fork (). | |
292e6c07 MK |
133 | (The |
134 | .B MADV_WIPEONFORK | |
135 | setting remains in place for those address ranges in the child.) | |
22356d97 | 136 | .IP \(bu |
8bd58774 MK |
137 | The termination signal of the child is always |
138 | .B SIGCHLD | |
a99426d3 MK |
139 | (see |
140 | .BR clone (2)). | |
22356d97 | 141 | .IP \(bu |
acfd9925 MK |
142 | The port access permission bits set by |
143 | .BR ioperm (2) | |
144 | are not inherited by the child; | |
145 | the child must turn on any bits that it requires using | |
146 | .BR ioperm (2). | |
fea681da | 147 | .PP |
a99426d3 | 148 | Note the following further points: |
22356d97 | 149 | .IP \(bu 3 |
5503c85e | 150 | The child process is created with a single thread\(emthe |
c13182ef | 151 | one that called |
2777b1ca | 152 | .BR fork (). |
a99426d3 | 153 | The entire virtual address space of the parent is replicated in the child, |
c13182ef | 154 | including the states of mutexes, condition variables, |
a99426d3 MK |
155 | and other pthreads objects; the use of |
156 | .BR pthread_atfork (3) | |
157 | may be helpful for dealing with problems that this can cause. | |
22356d97 | 158 | .IP \(bu |
2c7c50cd | 159 | After a |
bf7bc8b8 | 160 | .BR fork () |
2c7c50cd MK |
161 | in a multithreaded program, |
162 | the child can safely call only async-signal-safe functions (see | |
28a4c58c | 163 | .BR signal\-safety (7)) |
2c7c50cd MK |
164 | until such time as it calls |
165 | .BR execve (2). | |
22356d97 | 166 | .IP \(bu |
a99426d3 | 167 | The child inherits copies of the parent's set of open file descriptors. |
c13182ef | 168 | Each file descriptor in the child refers to the same |
a99426d3 MK |
169 | open file description (see |
170 | .BR open (2)) | |
171 | as the corresponding file descriptor in the parent. | |
d9cb0d7d | 172 | This means that the two file descriptors share open file status flags, |
c72249c5 | 173 | file offset, |
a99426d3 MK |
174 | and signal-driven I/O attributes (see the description of |
175 | .B F_SETOWN | |
c13182ef | 176 | and |
a99426d3 | 177 | .B F_SETSIG |
c13182ef | 178 | in |
a99426d3 | 179 | .BR fcntl (2)). |
22356d97 | 180 | .IP \(bu |
c13182ef | 181 | The child inherits copies of the parent's set of open message |
a99426d3 MK |
182 | queue descriptors (see |
183 | .BR mq_overview (7)). | |
d9cb0d7d | 184 | Each file descriptor in the child refers to the same |
a99426d3 | 185 | open message queue description |
d9cb0d7d MK |
186 | as the corresponding file descriptor in the parent. |
187 | This means that the two file descriptors share the same flags | |
a99426d3 | 188 | .RI ( mq_flags ). |
22356d97 | 189 | .IP \(bu |
f5e74ede MK |
190 | The child inherits copies of the parent's set of open directory streams (see |
191 | .BR opendir (3)). | |
9b612e3c | 192 | POSIX.1 says that the corresponding directory streams |
f5e74ede MK |
193 | in the parent and child |
194 | .I may | |
195 | share the directory stream positioning; | |
196 | on Linux/glibc they do not. | |
47297adb | 197 | .SH RETURN VALUE |
f5e74ede MK |
198 | On success, the PID of the child process is returned in the parent, |
199 | and 0 is returned in the child. | |
200 | On failure, \-1 is returned in the parent, | |
201 | no child process is created, and | |
fea681da | 202 | .I errno |
f6a4078b | 203 | is set to indicate the error. |
fea681da MK |
204 | .SH ERRORS |
205 | .TP | |
206 | .B EAGAIN | |
a9eb4a80 | 207 | .\" NOTE! The following should match the description in pthread_create(3) |
41dfc98f | 208 | A system-imposed limit on the number of threads was encountered. |
bf54cc86 MK |
209 | There are a number of limits that may trigger this error: |
210 | .RS | |
22356d97 | 211 | .IP \(bu 3 |
bf54cc86 | 212 | the |
1ae6b2c7 | 213 | .B RLIMIT_NPROC |
41dfc98f MK |
214 | soft resource limit (set via |
215 | .BR setrlimit (2)), | |
216 | which limits the number of processes and threads for a real user ID, | |
217 | was reached; | |
22356d97 | 218 | .IP \(bu |
41dfc98f | 219 | the kernel's system-wide limit on the number of processes and threads, |
b49c2acb | 220 | .IR /proc/sys/kernel/threads\-max , |
41dfc98f MK |
221 | was reached (see |
222 | .BR proc (5)); | |
22356d97 | 223 | .IP \(bu |
91551f10 | 224 | the maximum number of PIDs, |
41dfc98f MK |
225 | .IR /proc/sys/kernel/pid_max , |
226 | was reached (see | |
91551f10 | 227 | .BR proc (5)); |
bf54cc86 | 228 | or |
22356d97 | 229 | .IP \(bu |
bf54cc86 MK |
230 | the PID limit |
231 | .RI ( pids.max ) | |
91551f10 | 232 | imposed by the cgroup "process number" (PIDs) controller was reached. |
bf54cc86 | 233 | .RE |
fea681da | 234 | .TP |
75becc94 MK |
235 | .B EAGAIN |
236 | The caller is operating under the | |
1ae6b2c7 | 237 | .B SCHED_DEADLINE |
75becc94 MK |
238 | scheduling policy and does not have the reset-on-fork flag set. |
239 | See | |
240 | .BR sched (7). | |
241 | .TP | |
fea681da | 242 | .B ENOMEM |
e511ffb6 | 243 | .BR fork () |
fea681da | 244 | failed to allocate the necessary kernel structures because memory is tight. |
aed1f3b9 | 245 | .TP |
f516d6d9 MK |
246 | .B ENOMEM |
247 | An attempt was made to create a child process in a PID namespace | |
248 | whose "init" process has terminated. | |
249 | See | |
250 | .BR pid_namespaces (7). | |
251 | .TP | |
aed1f3b9 MF |
252 | .B ENOSYS |
253 | .BR fork () | |
254 | is not supported on this platform (for example, | |
255 | .\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa | |
256 | hardware without a Memory-Management Unit). | |
10e46057 NF |
257 | .TP |
258 | .BR ERESTARTNOINTR " (since Linux 2.6.17)" | |
11a6d050 | 259 | .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 |
10e46057 NF |
260 | System call was interrupted by a signal and will be restarted. |
261 | (This can be seen only during a trace.) | |
3113c7f3 | 262 | .SH STANDARDS |
9b612e3c | 263 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
a99426d3 | 264 | .SH NOTES |
a99426d3 MK |
265 | Under Linux, |
266 | .BR fork () | |
267 | is implemented using copy-on-write pages, so the only penalty that it incurs | |
268 | is the time and memory required to duplicate the parent's page tables, | |
269 | and to create a unique task structure for the child. | |
0722a578 | 270 | .SS C library/kernel differences |
429e9867 MK |
271 | Since version 2.3.3, |
272 | .\" nptl/sysdeps/unix/sysv/linux/fork.c | |
273 | rather than invoking the kernel's | |
274 | .BR fork () | |
275 | system call, | |
276 | the glibc | |
277 | .BR fork () | |
278 | wrapper that is provided as part of the | |
279 | NPTL threading implementation invokes | |
280 | .BR clone (2) | |
281 | with flags that provide the same effect as the traditional system call. | |
6de06bb8 MK |
282 | (A call to |
283 | .BR fork () | |
284 | is equivalent to a call to | |
285 | .BR clone (2) | |
286 | specifying | |
287 | .I flags | |
288 | as just | |
289 | .BR SIGCHLD .) | |
429e9867 | 290 | The glibc wrapper invokes any fork handlers that have been |
7364dea6 | 291 | established using |
429e9867 MK |
292 | .BR pthread_atfork (3). |
293 | .\" and does some magic to ensure that getpid(2) returns the right value. | |
a14af333 | 294 | .SH EXAMPLES |
2b2581ee MK |
295 | See |
296 | .BR pipe (2) | |
297 | and | |
94b639c1 AC |
298 | .BR wait (2) |
299 | for more examples. | |
300 | .PP | |
301 | .\" SRC BEGIN (fork.c) | |
302 | .EX | |
303 | #include <signal.h> | |
94b639c1 | 304 | #include <stdint.h> |
76ee15b1 | 305 | #include <stdio.h> |
94b639c1 AC |
306 | #include <stdlib.h> |
307 | #include <unistd.h> | |
308 | ||
309 | int | |
310 | main(void) | |
311 | { | |
312 | pid_t pid; | |
313 | ||
314 | if (signal(SIGCHLD, SIG_IGN) == SIG_ERR) { | |
315 | perror("signal"); | |
316 | exit(EXIT_FAILURE); | |
317 | } | |
318 | pid = fork(); | |
319 | switch (pid) { | |
529027f0 | 320 | case \-1: |
94b639c1 AC |
321 | perror("fork"); |
322 | exit(EXIT_FAILURE); | |
323 | case 0: | |
324 | puts("Child exiting."); | |
325 | exit(EXIT_SUCCESS); | |
326 | default: | |
327 | printf("Child is PID %jd\en", (intmax_t) pid); | |
328 | puts("Parent exiting."); | |
329 | exit(EXIT_SUCCESS); | |
330 | } | |
331 | } | |
332 | .EE | |
333 | .\" SRC END | |
47297adb | 334 | .SH SEE ALSO |
fea681da MK |
335 | .BR clone (2), |
336 | .BR execve (2), | |
a44dc571 | 337 | .BR exit (2), |
fea681da | 338 | .BR setrlimit (2), |
5cc01e9c | 339 | .BR unshare (2), |
fea681da MK |
340 | .BR vfork (2), |
341 | .BR wait (2), | |
baf17bc4 | 342 | .BR daemon (3), |
c5cd305d | 343 | .BR pthread_atfork (3), |
53a1443c MK |
344 | .BR capabilities (7), |
345 | .BR credentials (7) |