Debian Codegraph @

upstream/debian-unstable/man2/fork.2

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