fork(2) - f7

1FORK(2)                    Linux Programmer's Manual                   FORK(2)
2
3
4

NAME

6       fork - create a child process
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <unistd.h>
11
12       pid_t fork(void);
13

DESCRIPTION

15       fork()  creates  a new process by duplicating the calling process.  The
16       new process, referred to as the child, is an  exact  duplicate  of  the
17       calling  process,  referred  to as the parent, except for the following
18       points:
19
20       *   The child has its own unique process ID,  and  this  PID  does  not
21           match the ID of any existing process group (setpgid(2)).
22
23       *   The  child's  parent process ID is the same as the parent's process
24           ID.
25
26       *   The child does not inherit its  parent's  memory  locks  (mlock(2),
27           mlockall(2)).
28
29       *   Process  resource utilisations (getrusage(2)) and CPU time counters
30           (times(2)) are reset to zero in the child.
31
32       *   The child set of  pending  signals  is  initially  empty  (sigpend‐
33           ing(2)).
34
35       *   The  child  does  not inherit semaphore adjustments from its parent
36           (semop(2)).
37
38       *   The child does not inherit record locks from its parent (fcntl(2)).
39
40       *   The parent does not inherit timers from  its  parent  (setitimer(2)
41           alarm(3), timer_create(3)).
42
43       *   The  child does not inherit outstanding asynchronous I/O operations
44           from its parent (aio_read(3), aio_write(3)).
45
46       The process attributes in the  preceding  list  are  all  specified  in
47       POSIX.1-2001.   The  parent  and  child also differ with respect to the
48       following Linux-specific process attributes:
49
50       *   The child does not inherit directory change notifications (dnotify)
51           from its parent (see the description of F_NOTIFY in fcntl(2)).
52
53       *   The  prctl(2)  PR_SET_PDEATHSIG  setting is reset so that the child
54           does not receive a signal when its parent terminates.
55
56       *   Memory  mappings  that  have  been  marked  with   the   madvise(2)
57           MADV_DONTFORK flag are not inherited across a fork(2).
58
59       *   The  termination  signal  of  the  child  is  always  SIGCHLD  (see
60           clone(2)).
61
62       Note the following further points:
63
64       *   The child process is created with a single thread —  the  one  that
65           called  fork(2).  The entire virtual address space of the parent is
66           replicated in the child, including the states of mutexes, condition
67           variables, and other pthreads objects; the use of pthread_atfork(3)
68           may be helpful for dealing with problems that this can cause.
69
70       *   The child inherits copies of the parent's set of open file descrip‐
71           tors.   Each  file  descriptor in the child refers to the same open
72           file description (see open(2)) as the corresponding file descriptor
73           in the parent.  This means that the two descriptors share open file
74           status flags, current file offset, and signal-driven I/O attributes
75           (see the description of F_SETOWN and F_SETSIG in fcntl(2)).
76
77       *   The child inherits copies of the parent's set of open message queue
78           descriptors (see mq_overview(7)).  Each  descriptor  in  the  child
79           refers  to  the  same  open message queue description as the corre‐
80           sponding descriptor  in  the  parent.   This  means  that  the  two
81           descriptors share the same flags (mq_flags).
82

RETURN VALUE

84       On  success,  the  PID of the child process is returned in the parent's
85       thread of execution, and a 0 is returned in the child's thread of  exe‐
86       cution.   On failure, a -1 will be returned in the parent's context, no
87       child process will be created, and errno will be set appropriately.
88

ERRORS

90       EAGAIN fork() cannot allocate sufficient memory to  copy  the  parent's
91              page tables and allocate a task structure for the child.
92
93       EAGAIN It was not possible to create a new process because the caller's
94              RLIMIT_NPROC resource limit was  encountered.   To  exceed  this
95              limit,  the  process  must  have either the CAP_SYS_ADMIN or the
96              CAP_SYS_RESOURCE capability.
97
98       ENOMEM fork()  failed  to  allocate  the  necessary  kernel  structures
99              because memory is tight.
100

CONFORMING TO

102       SVr4, 4.3BSD, POSIX.1-2001.
103

EXAMPLE

105       See pipe(2) and wait(2).
106

NOTES

108       Under  Linux,  fork()  is implemented using copy-on-write pages, so the
109       only penalty that it incurs is the time and memory required  to  dupli‐
110       cate  the  parent's  page tables, and to create a unique task structure
111       for the child.
112