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