]>
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 | .\" |
4b72fb64 | 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 | .\" |
96d1766a | 39 | .TH FORK 2 2013-02-12 "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. |
c13182ef MK |
49 | The new process, referred to as the \fIchild\fP, |
50 | is an exact duplicate of the calling process, | |
a99426d3 | 51 | referred to as the \fIparent\fP, except for the following points: |
222ad5f1 | 52 | .IP * 3 |
a99426d3 MK |
53 | The child has its own unique process ID, |
54 | and this PID does not match the ID of any existing process group | |
55 | .RB ( setpgid (2)). | |
222ad5f1 | 56 | .IP * |
a99426d3 | 57 | The child's parent process ID is the same as the parent's process ID. |
222ad5f1 | 58 | .IP * |
a99426d3 MK |
59 | The child does not inherit its parent's memory locks |
60 | .RB ( mlock (2), | |
61 | .BR mlockall (2)). | |
222ad5f1 | 62 | .IP * |
d9bfdb9c | 63 | Process resource utilizations |
a99426d3 MK |
64 | .RB ( getrusage (2)) |
65 | and CPU time counters | |
66 | .RB ( times (2)) | |
67 | are reset to zero in the child. | |
222ad5f1 | 68 | .IP * |
65e7dad2 | 69 | The child's set of pending signals is initially empty |
a99426d3 | 70 | .RB ( sigpending (2)). |
222ad5f1 | 71 | .IP * |
a99426d3 MK |
72 | The child does not inherit semaphore adjustments from its parent |
73 | .RB ( semop (2)). | |
222ad5f1 | 74 | .IP * |
a99426d3 MK |
75 | The child does not inherit record locks from its parent |
76 | .RB ( fcntl (2)). | |
222ad5f1 | 77 | .IP * |
0fb58b28 | 78 | The child does not inherit timers from its parent |
f5e74ede | 79 | .RB ( setitimer (2), |
76375bc6 | 80 | .BR alarm (2), |
804f03e6 | 81 | .BR timer_create (2)). |
222ad5f1 | 82 | .IP * |
c13182ef | 83 | The child does not inherit outstanding asynchronous I/O operations |
a99426d3 MK |
84 | from its parent |
85 | .RB ( aio_read (3), | |
cb6a78e6 | 86 | .BR aio_write (3)), |
f75ad1f3 YK |
87 | nor does it inherit any asynchronous I/O contexts from its parent (see |
88 | .BR io_setup (2)). | |
c13182ef MK |
89 | .PP |
90 | The process attributes in the preceding list are all specified | |
a99426d3 MK |
91 | in POSIX.1-2001. |
92 | The parent and child also differ with respect to the following | |
93 | Linux-specific process attributes: | |
222ad5f1 | 94 | .IP * 3 |
c13182ef | 95 | The child does not inherit directory change notifications (dnotify) |
a99426d3 MK |
96 | from its parent |
97 | (see the description of | |
c13182ef MK |
98 | .B F_NOTIFY |
99 | in | |
a99426d3 | 100 | .BR fcntl (2)). |
222ad5f1 | 101 | .IP * |
a99426d3 MK |
102 | The |
103 | .BR prctl (2) | |
104 | .B PR_SET_PDEATHSIG | |
c13182ef | 105 | setting is reset so that the child does not receive a signal |
a99426d3 | 106 | when its parent terminates. |
222ad5f1 | 107 | .IP * |
e089cba1 MK |
108 | The default timer slack value is set to the parent's |
109 | current timer slack value. | |
110 | See the description of | |
111 | .BR PR_SET_TIMERSLACK | |
112 | in | |
113 | .BR prctl (2). | |
114 | .IP * | |
c13182ef | 115 | Memory mappings that have been marked with the |
78cb5911 MK |
116 | .BR madvise (2) |
117 | .B MADV_DONTFORK | |
118 | flag are not inherited across a | |
2777b1ca | 119 | .BR fork (). |
222ad5f1 | 120 | .IP * |
8bd58774 MK |
121 | The termination signal of the child is always |
122 | .B SIGCHLD | |
a99426d3 MK |
123 | (see |
124 | .BR clone (2)). | |
fea681da | 125 | .PP |
a99426d3 | 126 | Note the following further points: |
222ad5f1 | 127 | .IP * 3 |
5503c85e | 128 | The child process is created with a single thread\(emthe |
c13182ef | 129 | one that called |
2777b1ca | 130 | .BR fork (). |
a99426d3 | 131 | The entire virtual address space of the parent is replicated in the child, |
c13182ef | 132 | including the states of mutexes, condition variables, |
a99426d3 MK |
133 | and other pthreads objects; the use of |
134 | .BR pthread_atfork (3) | |
135 | may be helpful for dealing with problems that this can cause. | |
222ad5f1 | 136 | .IP * |
a99426d3 | 137 | The child inherits copies of the parent's set of open file descriptors. |
c13182ef | 138 | Each file descriptor in the child refers to the same |
a99426d3 MK |
139 | open file description (see |
140 | .BR open (2)) | |
141 | as the corresponding file descriptor in the parent. | |
c13182ef MK |
142 | This means that the two descriptors share open file status flags, |
143 | current file offset, | |
a99426d3 MK |
144 | and signal-driven I/O attributes (see the description of |
145 | .B F_SETOWN | |
c13182ef | 146 | and |
a99426d3 | 147 | .B F_SETSIG |
c13182ef | 148 | in |
a99426d3 | 149 | .BR fcntl (2)). |
222ad5f1 | 150 | .IP * |
c13182ef | 151 | The child inherits copies of the parent's set of open message |
a99426d3 MK |
152 | queue descriptors (see |
153 | .BR mq_overview (7)). | |
c13182ef | 154 | Each descriptor in the child refers to the same |
a99426d3 MK |
155 | open message queue description |
156 | as the corresponding descriptor in the parent. | |
157 | This means that the two descriptors share the same flags | |
158 | .RI ( mq_flags ). | |
f5e74ede MK |
159 | .IP * |
160 | The child inherits copies of the parent's set of open directory streams (see | |
161 | .BR opendir (3)). | |
0f5546a1 | 162 | POSIX.1-2001 says that the corresponding directory streams |
f5e74ede MK |
163 | in the parent and child |
164 | .I may | |
165 | share the directory stream positioning; | |
166 | on Linux/glibc they do not. | |
47297adb | 167 | .SH RETURN VALUE |
f5e74ede MK |
168 | On success, the PID of the child process is returned in the parent, |
169 | and 0 is returned in the child. | |
170 | On failure, \-1 is returned in the parent, | |
171 | no child process is created, and | |
fea681da | 172 | .I errno |
f5e74ede | 173 | is set appropriately. |
fea681da MK |
174 | .SH ERRORS |
175 | .TP | |
176 | .B EAGAIN | |
e511ffb6 | 177 | .BR fork () |
fea681da MK |
178 | cannot allocate sufficient memory to copy the parent's page tables and |
179 | allocate a task structure for the child. | |
180 | .TP | |
181 | .B EAGAIN | |
182 | It was not possible to create a new process because the caller's | |
183 | .B RLIMIT_NPROC | |
184 | resource limit was encountered. | |
185 | To exceed this limit, the process must have either the | |
0daa9e92 | 186 | .B CAP_SYS_ADMIN |
fea681da | 187 | or the |
0daa9e92 | 188 | .B CAP_SYS_RESOURCE |
fea681da MK |
189 | capability. |
190 | .TP | |
191 | .B ENOMEM | |
e511ffb6 | 192 | .BR fork () |
fea681da | 193 | failed to allocate the necessary kernel structures because memory is tight. |
aed1f3b9 MF |
194 | .TP |
195 | .B ENOSYS | |
196 | .BR fork () | |
197 | is not supported on this platform (for example, | |
198 | .\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa | |
199 | hardware without a Memory-Management Unit). | |
47297adb | 200 | .SH CONFORMING TO |
97c1eac8 | 201 | SVr4, 4.3BSD, POSIX.1-2001. |
a99426d3 MK |
202 | .SH NOTES |
203 | .PP | |
204 | Under Linux, | |
205 | .BR fork () | |
206 | is implemented using copy-on-write pages, so the only penalty that it incurs | |
207 | is the time and memory required to duplicate the parent's page tables, | |
208 | and to create a unique task structure for the child. | |
429e9867 MK |
209 | |
210 | Since version 2.3.3, | |
211 | .\" nptl/sysdeps/unix/sysv/linux/fork.c | |
212 | rather than invoking the kernel's | |
213 | .BR fork () | |
214 | system call, | |
215 | the glibc | |
216 | .BR fork () | |
217 | wrapper that is provided as part of the | |
218 | NPTL threading implementation invokes | |
219 | .BR clone (2) | |
220 | with flags that provide the same effect as the traditional system call. | |
6de06bb8 MK |
221 | (A call to |
222 | .BR fork () | |
223 | is equivalent to a call to | |
224 | .BR clone (2) | |
225 | specifying | |
226 | .I flags | |
227 | as just | |
228 | .BR SIGCHLD .) | |
429e9867 | 229 | The glibc wrapper invokes any fork handlers that have been |
7364dea6 | 230 | established using |
429e9867 MK |
231 | .BR pthread_atfork (3). |
232 | .\" and does some magic to ensure that getpid(2) returns the right value. | |
2b2581ee MK |
233 | .SH EXAMPLE |
234 | See | |
235 | .BR pipe (2) | |
236 | and | |
237 | .BR wait (2). | |
47297adb | 238 | .SH SEE ALSO |
fea681da MK |
239 | .BR clone (2), |
240 | .BR execve (2), | |
a44dc571 | 241 | .BR exit (2), |
fea681da | 242 | .BR setrlimit (2), |
5cc01e9c | 243 | .BR unshare (2), |
fea681da MK |
244 | .BR vfork (2), |
245 | .BR wait (2), | |
baf17bc4 | 246 | .BR daemon (3), |
53a1443c MK |
247 | .BR capabilities (7), |
248 | .BR credentials (7) |