]>
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 | .\" |
6d322d5f | 39 | .TH FORK 2 2015-02-21 "Linux" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | fork \- create a child process | |
42 | .SH SYNOPSIS | |
fea681da MK |
43 | .B #include <unistd.h> |
44 | .sp | |
45 | .B pid_t fork(void); | |
46 | .SH DESCRIPTION | |
e511ffb6 | 47 | .BR fork () |
a99426d3 | 48 | creates a new process by duplicating the calling process. |
7f810a61 HS |
49 | The new process is referred to as the |
50 | .I child | |
51 | process. | |
52 | The calling process is referred to as the | |
53 | .I parent | |
54 | process. | |
55 | ||
56 | The child process and the parent process run in separate memory spaces. | |
57 | At the time of | |
58 | .BR fork () | |
59 | both memory spaces have the same content. | |
60 | Memory writes, file mappings | |
61 | .RB ( mmap (2)), | |
62 | and unmappings | |
63 | .RB ( munmap (2)) | |
64 | performed by one of the processes do not affect the other. | |
65 | ||
66 | The child process is an exact duplicate of the parent | |
67 | process except for the following points: | |
222ad5f1 | 68 | .IP * 3 |
a99426d3 MK |
69 | The child has its own unique process ID, |
70 | and this PID does not match the ID of any existing process group | |
71 | .RB ( setpgid (2)). | |
222ad5f1 | 72 | .IP * |
a99426d3 | 73 | The child's parent process ID is the same as the parent's process ID. |
222ad5f1 | 74 | .IP * |
a99426d3 MK |
75 | The child does not inherit its parent's memory locks |
76 | .RB ( mlock (2), | |
77 | .BR mlockall (2)). | |
222ad5f1 | 78 | .IP * |
d9bfdb9c | 79 | Process resource utilizations |
a99426d3 MK |
80 | .RB ( getrusage (2)) |
81 | and CPU time counters | |
82 | .RB ( times (2)) | |
83 | are reset to zero in the child. | |
222ad5f1 | 84 | .IP * |
65e7dad2 | 85 | The child's set of pending signals is initially empty |
a99426d3 | 86 | .RB ( sigpending (2)). |
222ad5f1 | 87 | .IP * |
a99426d3 MK |
88 | The child does not inherit semaphore adjustments from its parent |
89 | .RB ( semop (2)). | |
222ad5f1 | 90 | .IP * |
5879ccc0 | 91 | The child does not inherit process-associated record locks from its parent |
a99426d3 | 92 | .RB ( fcntl (2)). |
5879ccc0 MK |
93 | (On the other hand, it does inherit |
94 | .BR fcntl (2) | |
95 | open file description locks and | |
96 | .BR flock (2) | |
97 | locks from its parent.) | |
222ad5f1 | 98 | .IP * |
0fb58b28 | 99 | The child does not inherit timers from its parent |
f5e74ede | 100 | .RB ( setitimer (2), |
76375bc6 | 101 | .BR alarm (2), |
804f03e6 | 102 | .BR timer_create (2)). |
222ad5f1 | 103 | .IP * |
c13182ef | 104 | The child does not inherit outstanding asynchronous I/O operations |
a99426d3 MK |
105 | from its parent |
106 | .RB ( aio_read (3), | |
cb6a78e6 | 107 | .BR aio_write (3)), |
f75ad1f3 YK |
108 | nor does it inherit any asynchronous I/O contexts from its parent (see |
109 | .BR io_setup (2)). | |
c13182ef MK |
110 | .PP |
111 | The process attributes in the preceding list are all specified | |
a99426d3 MK |
112 | in POSIX.1-2001. |
113 | The parent and child also differ with respect to the following | |
114 | Linux-specific process attributes: | |
222ad5f1 | 115 | .IP * 3 |
c13182ef | 116 | The child does not inherit directory change notifications (dnotify) |
a99426d3 MK |
117 | from its parent |
118 | (see the description of | |
c13182ef MK |
119 | .B F_NOTIFY |
120 | in | |
a99426d3 | 121 | .BR fcntl (2)). |
222ad5f1 | 122 | .IP * |
a99426d3 MK |
123 | The |
124 | .BR prctl (2) | |
125 | .B PR_SET_PDEATHSIG | |
c13182ef | 126 | setting is reset so that the child does not receive a signal |
a99426d3 | 127 | when its parent terminates. |
222ad5f1 | 128 | .IP * |
e089cba1 MK |
129 | The default timer slack value is set to the parent's |
130 | current timer slack value. | |
131 | See the description of | |
132 | .BR PR_SET_TIMERSLACK | |
133 | in | |
134 | .BR prctl (2). | |
135 | .IP * | |
c13182ef | 136 | Memory mappings that have been marked with the |
78cb5911 MK |
137 | .BR madvise (2) |
138 | .B MADV_DONTFORK | |
139 | flag are not inherited across a | |
2777b1ca | 140 | .BR fork (). |
222ad5f1 | 141 | .IP * |
8bd58774 MK |
142 | The termination signal of the child is always |
143 | .B SIGCHLD | |
a99426d3 MK |
144 | (see |
145 | .BR clone (2)). | |
acfd9925 MK |
146 | .IP * |
147 | The port access permission bits set by | |
148 | .BR ioperm (2) | |
149 | are not inherited by the child; | |
150 | the child must turn on any bits that it requires using | |
151 | .BR ioperm (2). | |
fea681da | 152 | .PP |
a99426d3 | 153 | Note the following further points: |
222ad5f1 | 154 | .IP * 3 |
5503c85e | 155 | The child process is created with a single thread\(emthe |
c13182ef | 156 | one that called |
2777b1ca | 157 | .BR fork (). |
a99426d3 | 158 | The entire virtual address space of the parent is replicated in the child, |
c13182ef | 159 | including the states of mutexes, condition variables, |
a99426d3 MK |
160 | and other pthreads objects; the use of |
161 | .BR pthread_atfork (3) | |
162 | may be helpful for dealing with problems that this can cause. | |
222ad5f1 | 163 | .IP * |
a99426d3 | 164 | The child inherits copies of the parent's set of open file descriptors. |
c13182ef | 165 | Each file descriptor in the child refers to the same |
a99426d3 MK |
166 | open file description (see |
167 | .BR open (2)) | |
168 | as the corresponding file descriptor in the parent. | |
c13182ef MK |
169 | This means that the two descriptors share open file status flags, |
170 | current file offset, | |
a99426d3 MK |
171 | and signal-driven I/O attributes (see the description of |
172 | .B F_SETOWN | |
c13182ef | 173 | and |
a99426d3 | 174 | .B F_SETSIG |
c13182ef | 175 | in |
a99426d3 | 176 | .BR fcntl (2)). |
222ad5f1 | 177 | .IP * |
c13182ef | 178 | The child inherits copies of the parent's set of open message |
a99426d3 MK |
179 | queue descriptors (see |
180 | .BR mq_overview (7)). | |
c13182ef | 181 | Each descriptor in the child refers to the same |
a99426d3 MK |
182 | open message queue description |
183 | as the corresponding descriptor in the parent. | |
184 | This means that the two descriptors share the same flags | |
185 | .RI ( mq_flags ). | |
f5e74ede MK |
186 | .IP * |
187 | The child inherits copies of the parent's set of open directory streams (see | |
188 | .BR opendir (3)). | |
0f5546a1 | 189 | POSIX.1-2001 says that the corresponding directory streams |
f5e74ede MK |
190 | in the parent and child |
191 | .I may | |
192 | share the directory stream positioning; | |
193 | on Linux/glibc they do not. | |
47297adb | 194 | .SH RETURN VALUE |
f5e74ede MK |
195 | On success, the PID of the child process is returned in the parent, |
196 | and 0 is returned in the child. | |
197 | On failure, \-1 is returned in the parent, | |
198 | no child process is created, and | |
fea681da | 199 | .I errno |
f5e74ede | 200 | is set appropriately. |
fea681da MK |
201 | .SH ERRORS |
202 | .TP | |
203 | .B EAGAIN | |
41dfc98f MK |
204 | \" NOTE! The following should match the description in pthread_create(3) |
205 | A system-imposed limit on the number of threads was encountered. | |
206 | There are a number of limits that may trigger this error: the | |
207 | .BR RLIMIT_NPROC | |
208 | soft resource limit (set via | |
209 | .BR setrlimit (2)), | |
210 | which limits the number of processes and threads for a real user ID, | |
211 | was reached; | |
212 | the kernel's system-wide limit on the number of processes and threads, | |
213 | .IR /proc/sys/kernel/threads-max , | |
214 | was reached (see | |
215 | .BR proc (5)); | |
216 | or the maximum number of PIDs, | |
217 | .IR /proc/sys/kernel/pid_max , | |
218 | was reached (see | |
219 | .BR proc (5)). | |
fea681da | 220 | .TP |
75becc94 MK |
221 | .B EAGAIN |
222 | The caller is operating under the | |
223 | .BR SCHED_DEADLINE | |
224 | scheduling policy and does not have the reset-on-fork flag set. | |
225 | See | |
226 | .BR sched (7). | |
227 | .TP | |
fea681da | 228 | .B ENOMEM |
e511ffb6 | 229 | .BR fork () |
fea681da | 230 | failed to allocate the necessary kernel structures because memory is tight. |
aed1f3b9 MF |
231 | .TP |
232 | .B ENOSYS | |
233 | .BR fork () | |
234 | is not supported on this platform (for example, | |
235 | .\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa | |
236 | hardware without a Memory-Management Unit). | |
47297adb | 237 | .SH CONFORMING TO |
97c1eac8 | 238 | SVr4, 4.3BSD, POSIX.1-2001. |
a99426d3 MK |
239 | .SH NOTES |
240 | .PP | |
241 | Under Linux, | |
242 | .BR fork () | |
243 | is implemented using copy-on-write pages, so the only penalty that it incurs | |
244 | is the time and memory required to duplicate the parent's page tables, | |
245 | and to create a unique task structure for the child. | |
0722a578 | 246 | .SS C library/kernel differences |
429e9867 MK |
247 | Since version 2.3.3, |
248 | .\" nptl/sysdeps/unix/sysv/linux/fork.c | |
249 | rather than invoking the kernel's | |
250 | .BR fork () | |
251 | system call, | |
252 | the glibc | |
253 | .BR fork () | |
254 | wrapper that is provided as part of the | |
255 | NPTL threading implementation invokes | |
256 | .BR clone (2) | |
257 | with flags that provide the same effect as the traditional system call. | |
6de06bb8 MK |
258 | (A call to |
259 | .BR fork () | |
260 | is equivalent to a call to | |
261 | .BR clone (2) | |
262 | specifying | |
263 | .I flags | |
264 | as just | |
265 | .BR SIGCHLD .) | |
429e9867 | 266 | The glibc wrapper invokes any fork handlers that have been |
7364dea6 | 267 | established using |
429e9867 MK |
268 | .BR pthread_atfork (3). |
269 | .\" and does some magic to ensure that getpid(2) returns the right value. | |
2b2581ee MK |
270 | .SH EXAMPLE |
271 | See | |
272 | .BR pipe (2) | |
273 | and | |
274 | .BR wait (2). | |
47297adb | 275 | .SH SEE ALSO |
fea681da MK |
276 | .BR clone (2), |
277 | .BR execve (2), | |
a44dc571 | 278 | .BR exit (2), |
fea681da | 279 | .BR setrlimit (2), |
5cc01e9c | 280 | .BR unshare (2), |
fea681da MK |
281 | .BR vfork (2), |
282 | .BR wait (2), | |
baf17bc4 | 283 | .BR daemon (3), |
53a1443c MK |
284 | .BR capabilities (7), |
285 | .BR credentials (7) |