man2/fork.2

   1 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" A few fragments remain from an earlier (1992) page by
   3 .\" Drew Eckhardt (drew@cs.colorado.edu),
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   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)
  13 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  14 .\"     Added notes on capability requirements
  15 .\" 2006-09-04, Michael Kerrisk
  16 .\"     Greatly expanded, to describe all attributes that differ
  17 .\"     parent and child.
  18 .\"
  19 .TH fork 2 (date) "Linux man-pages (unreleased)"
  20 .SH NAME
  21 fork \- create a child process
  22 .SH LIBRARY
  23 Standard C library
  24 .RI ( libc ", " \-lc )
  25 .SH SYNOPSIS
  26 .nf
  27 .B #include <unistd.h>
  28 .PP
  29 .B pid_t fork(void);
  30 .fi
  31 .SH DESCRIPTION
  32 .BR fork ()
  33 creates a new process by duplicating the calling process.
  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.
  40 .PP
  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.
  50 .PP
  51 The child process is an exact duplicate of the parent
  52 process except for the following points:
  53 .IP \[bu] 3
  54 The child has its own unique process ID,
  55 and this PID does not match the ID of any existing process group
  56 .RB ( setpgid (2))
  57 or session.
  58 .IP \[bu]
  59 The child's parent process ID is the same as the parent's process ID.
  60 .IP \[bu]
  61 The child does not inherit its parent's memory locks
  62 .RB ( mlock (2),
  63 .BR mlockall (2)).
  64 .IP \[bu]
  65 Process resource utilizations
  66 .RB ( getrusage (2))
  67 and CPU time counters
  68 .RB ( times (2))
  69 are reset to zero in the child.
  70 .IP \[bu]
  71 The child's set of pending signals is initially empty
  72 .RB ( sigpending (2)).
  73 .IP \[bu]
  74 The child does not inherit semaphore adjustments from its parent
  75 .RB ( semop (2)).
  76 .IP \[bu]
  77 The child does not inherit process-associated record locks from its parent
  78 .RB ( fcntl (2)).
  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.)
  84 .IP \[bu]
  85 The child does not inherit timers from its parent
  86 .RB ( setitimer (2),
  87 .BR alarm (2),
  88 .BR timer_create (2)).
  89 .IP \[bu]
  90 The child does not inherit outstanding asynchronous I/O operations
  91 from its parent
  92 .RB ( aio_read (3),
  93 .BR aio_write (3)),
  94 nor does it inherit any asynchronous I/O contexts from its parent (see
  95 .BR io_setup (2)).
  96 .PP
  97 The process attributes in the preceding list are all specified
  98 in POSIX.1.
  99 The parent and child also differ with respect to the following
 100 Linux-specific process attributes:
 101 .IP \[bu] 3
 102 The child does not inherit directory change notifications (dnotify)
 103 from its parent
 104 (see the description of
 105 .B F_NOTIFY
 106 in
 107 .BR fcntl (2)).
 108 .IP \[bu]
 109 The
 110 .BR prctl (2)
 111 .B PR_SET_PDEATHSIG
 112 setting is reset so that the child does not receive a signal
 113 when its parent terminates.
 114 .IP \[bu]
 115 The default timer slack value is set to the parent's
 116 current timer slack value.
 117 See the description of
 118 .B PR_SET_TIMERSLACK
 119 in
 120 .BR prctl (2).
 121 .IP \[bu]
 122 Memory mappings that have been marked with the
 123 .BR madvise (2)
 124 .B MADV_DONTFORK
 125 flag are not inherited across a
 126 .BR fork ().
 127 .IP \[bu]
 128 Memory in address ranges that have been marked with the
 129 .BR madvise (2)
 130 .B MADV_WIPEONFORK
 131 flag is zeroed in the child after a
 132 .BR fork ().
 133 (The
 134 .B MADV_WIPEONFORK
 135 setting remains in place for those address ranges in the child.)
 136 .IP \[bu]
 137 The termination signal of the child is always
 138 .B SIGCHLD
 139 (see
 140 .BR clone (2)).
 141 .IP \[bu]
 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).
 147 .PP
 148 Note the following further points:
 149 .IP \[bu] 3
 150 The child process is created with a single thread\[em]the
 151 one that called
 152 .BR fork ().
 153 The entire virtual address space of the parent is replicated in the child,
 154 including the states of mutexes, condition variables,
 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.
 158 .IP \[bu]
 159 After a
 160 .BR fork ()
 161 in a multithreaded program,
 162 the child can safely call only async-signal-safe functions (see
 163 .BR signal\-safety (7))
 164 until such time as it calls
 165 .BR execve (2).
 166 .IP \[bu]
 167 The child inherits copies of the parent's set of open file descriptors.
 168 Each file descriptor in the child refers to the same
 169 open file description (see
 170 .BR open (2))
 171 as the corresponding file descriptor in the parent.
 172 This means that the two file descriptors share open file status flags,
 173 file offset,
 174 and signal-driven I/O attributes (see the description of
 175 .B F_SETOWN
 176 and
 177 .B F_SETSIG
 178 in
 179 .BR fcntl (2)).
 180 .IP \[bu]
 181 The child inherits copies of the parent's set of open message
 182 queue descriptors (see
 183 .BR mq_overview (7)).
 184 Each file descriptor in the child refers to the same
 185 open message queue description
 186 as the corresponding file descriptor in the parent.
 187 This means that the two file descriptors share the same flags
 188 .RI ( mq_flags ).
 189 .IP \[bu]
 190 The child inherits copies of the parent's set of open directory streams (see
 191 .BR opendir (3)).
 192 POSIX.1 says that the corresponding directory streams
 193 in the parent and child
 194 .I may
 195 share the directory stream positioning;
 196 on Linux/glibc they do not.
 197 .SH RETURN VALUE
 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
 202 .I errno
 203 is set to indicate the error.
 204 .SH ERRORS
 205 .TP
 206 .B EAGAIN
 207 .\" NOTE! The following should match the description in pthread_create(3)
 208 A system-imposed limit on the number of threads was encountered.
 209 There are a number of limits that may trigger this error:
 210 .RS
 211 .IP \[bu] 3
 212 the
 213 .B RLIMIT_NPROC
 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;
 218 .IP \[bu]
 219 the kernel's system-wide limit on the number of processes and threads,
 220 .IR /proc/sys/kernel/threads\-max ,
 221 was reached (see
 222 .BR proc (5));
 223 .IP \[bu]
 224 the maximum number of PIDs,
 225 .IR /proc/sys/kernel/pid_max ,
 226 was reached (see
 227 .BR proc (5));
 228 or
 229 .IP \[bu]
 230 the PID limit
 231 .RI ( pids.max )
 232 imposed by the cgroup "process number" (PIDs) controller was reached.
 233 .RE
 234 .TP
 235 .B EAGAIN
 236 The caller is operating under the
 237 .B SCHED_DEADLINE
 238 scheduling policy and does not have the reset-on-fork flag set.
 239 See
 240 .BR sched (7).
 241 .TP
 242 .B ENOMEM
 243 .BR fork ()
 244 failed to allocate the necessary kernel structures because memory is tight.
 245 .TP
 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
 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).
 257 .TP
 258 .BR ERESTARTNOINTR " (since Linux 2.6.17)"
 259 .\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
 260 System call was interrupted by a signal and will be restarted.
 261 (This can be seen only during a trace.)
 262 .SH STANDARDS
 263 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 264 .SH NOTES
 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.
 270 .SS C library/kernel differences
 271 Since glibc 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.
 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 .)
 290 The glibc wrapper invokes any fork handlers that have been
 291 established using
 292 .BR pthread_atfork (3).
 293 .\" and does some magic to ensure that getpid(2) returns the right value.
 294 .SH EXAMPLES
 295 See
 296 .BR pipe (2)
 297 and
 298 .BR wait (2)
 299 for more examples.
 300 .PP
 301 .\" SRC BEGIN (fork.c)
 302 .EX
 303 #include <signal.h>
 304 #include <stdint.h>
 305 #include <stdio.h>
 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) {
 320     case \-1:
 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
 334 .SH SEE ALSO
 335 .BR clone (2),
 336 .BR execve (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 pthread_atfork (3),
 344 .BR capabilities (7),
 345 .BR credentials (7)