1fork(2)                          System Calls                          fork(2)
2
3
4

NAME

6       fork, fork1, forkall, forkx, forkallx - create a new process
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <unistd.h>
11
12       pid_t fork(void);
13
14
15       pid_t fork1(void);
16
17
18       pid_t forkall(void);
19
20
21       #include <sys/fork.h>
22
23       pid_t forkx(int flags);
24
25
26       pid_t forkallx(int flags);
27
28

DESCRIPTION

30       The  fork(), fork1(), forkall(), forkx(), and forkallx() functions cre‐
31       ate a new process. The address space of the new process (child process)
32       is  an  exact  copy of the address space of the calling process (parent
33       process). The child process inherits the following attributes from  the
34       parent process:
35
36           o      real  user  ID,  real group ID, effective user ID, effective
37                  group ID
38
39           o      environment
40
41           o      open file descriptors
42
43           o      close-on-exec flags (see exec(2))
44
45           o      signal  handling  settings  (that  is,   SIG_DFL,   SIG_IGN,
46                  SIG_HOLD, function address)
47
48           o      supplementary group IDs
49
50           o      set-user-ID mode bit
51
52           o      set-group-ID mode bit
53
54           o      profiling on/off status
55
56           o      nice value (see  nice(2))
57
58           o      scheduler class (see priocntl(2))
59
60           o      all attached shared memory segments (see shmop(2))
61
62           o      process group ID -- memory mappings (see mmap(2))
63
64           o      session ID (see exit(2))
65
66           o      current working directory
67
68           o      root directory
69
70           o      file mode creation mask (see umask(2))
71
72           o      resource limits (see  getrlimit(2))
73
74           o      controlling terminal
75
76           o      saved user ID and group ID
77
78           o      task ID and project ID
79
80           o      processor bindings (see processor_bind(2))
81
82           o      processor set bindings (see pset_bind(2))
83
84           o      process privilege sets (see getppriv(2))
85
86           o      process flags (see getpflags(2))
87
88           o      active contract templates (see contract(4))
89
90
91       Scheduling  priority and any per-process scheduling parameters that are
92       specific to a given scheduling class might or might  not  be  inherited
93       according to the policy of that particular class (see priocntl(2)). The
94       child process might or might not be in the same process contract as the
95       parent  (see  process(4)).  The  child  process differs from the parent
96       process in the following ways:
97
98           o      The child process has a unique process  ID  which  does  not
99                  match any active process group ID.
100
101           o      The  child  process  has a different parent process ID (that
102                  is, the process ID of the parent process).
103
104           o      The child process has its own  copy  of  the  parent's  file
105                  descriptors  and directory streams. Each of the child's file
106                  descriptors shares a common file  pointer  with  the  corre‐
107                  sponding file descriptor of the parent.
108
109           o      Each shared memory segment remains attached and the value of
110                  shm_nattach is incremented by 1.
111
112           o      All semadj values are cleared (see semop(2)).
113
114           o      Process locks, text locks,  data  locks,  and  other  memory
115                  locks are not inherited by the child (see plock(3C) and mem‐
116                  cntl(2)).
117
118           o      The child process's tms  structure  is  cleared:  tms_utime,
119                  stime, cutime, and cstime are set to 0 (see times(2)).
120
121           o      The  child processes resource utilizations are set to 0; see
122                  getrlimit(2). The it_value and it_interval  values  for  the
123                  ITIMER_REAL timer are reset to 0; see getitimer(2).
124
125           o      The set of signals pending for the child process is initial‐
126                  ized to the empty set.
127
128           o      Timers created by timer_create(3C) are not inherited by  the
129                  child process.
130
131           o      No  asynchronous input or asynchronous output operations are
132                  inherited by the child.
133
134           o      Any preferred hardware address tranlsation sizes (see  memc‐
135                  ntl(2)) are inherited by the child.
136
137           o      The child process holds no contracts (see contract(4)).
138
139
140       Record  locks  set by the parent process are not inherited by the child
141       process (see fcntl(2)).
142
143
144       Although any open door descriptors in the  parent  are  shared  by  the
145       child, only the parent will receive a door invocation from clients even
146       if the door descriptor is open in the child. If a descriptor is  closed
147       in  the  parent,  attempts  to operate on the door descriptor will fail
148       even if it is still open in the child.
149
150   Threads
151       A call to forkall() or forkallx() replicates in the child  process  all
152       of  the threads (see thr_create(3C) and pthread_create(3C)) in the par‐
153       ent process. A call to fork1() or forkx() replicates only  the  calling
154       thread in the child process.
155
156
157       A  call  to  fork() is identical to a call to fork1(); only the calling
158       thread is replicated in the child process. This is the  POSIX-specified
159       behavior for fork().
160
161
162       In  releases  of  Solaris  prior  to Solaris 10, the behavior of fork()
163       depended on whether or not the application was linked  with  the  POSIX
164       threads  library.  When  linked with -lthread (Solaris Threads) but not
165       linked  with  -lpthread  (POSIX  Threads),  fork()  was  the  same   as
166       forkall().  When linked with -lpthread, whether or not also linked with
167       -lthread, fork() was the same as fork1().
168
169
170       Prior to Solaris 10, either -lthread or -lpthread was required for mul‐
171       tithreaded  applications.  This  is  no longer the case. The standard C
172       library provides all threading support for  both  sets  of  application
173       programming  interfaces.   Applications that require replicate-all fork
174       semantics must call forkall() or forkallx().
175
176   Fork Extensions
177       The forkx() and forkallx() functions accept a flags argument consisting
178       of a bitwise inclusive-OR of zero or more of the following flags, which
179       are defined in the header <sys/fork.h>:
180
181       FORK_NOSIGCHLD
182
183           Do not post a SIGCHLD signal to the parent process when  the  child
184           process  terminates,  regardless  of the disposition of the SIGCHLD
185           signal in the parent. SIGCHLD signals are still  possible  for  job
186           control stop and continue actions if the parent has requested them.
187
188
189       FORK_WAITPID
190
191           Do  not  allow  wait-for-multiple-pids by the parent, as in wait(),
192           waitid(P_ALL), or waitid(P_PGID), to reap  the  child  and  do  not
193           allow  the  child to be reaped automatically due the disposition of
194           the SIGCHLD signal being set to be ignored in the parent.   Only  a
195           specific  wait  for the child, as in waitid(P_PID, pid), is allowed
196           and it is required, else when the child exits it will remain a zom‐
197           bie until the parent exits.
198
199
200
201       If  the  flags  argument  is  0  forkx()  is  identical  to  fork() and
202       forkallx() is identical to forkall().
203
204   fork() Safety
205       If a multithreaded application calls fork(), fork1(), or  forkx(),  and
206       the  child  does  more  than  simply call one of the exec(2) functions,
207       there is a possibility of deadlock occurring in the child. The applica‐
208       tion  should  use  pthread_atfork(3C)  to ensure safety with respect to
209       this deadlock. Should there be any outstanding mutexes  throughout  the
210       process,  the  application should call pthread_atfork() to wait for and
211       acquire those mutexes prior to calling fork(), fork1(), or forkx(). See
212       "MT-Level of Libraries" on the attributes(5) manual page.
213
214
215       The  pthread_atfork()  mechanism  is  used  to  protect  the locks that
216       libc(3LIB) uses to implement interfaces such as malloc(3C).  All inter‐
217       faces  provided  by libc are safe to use in a child process following a
218       fork(), except when fork() is executed within a signal handler.
219
220
221       The POSIX standard (see standards(5)) requires fork to be Async-Signal-
222       Safe  (see attributes(5)). This cannot be made to happen with fork han‐
223       dlers in place, because they acquire locks. To be  in  nominal  compli‐
224       ance, no fork handlers are called when fork() is executed within a sig‐
225       nal context.  This leaves the child process  in  a  questionable  state
226       with  respect  to  its  locks, but at least the calling thread will not
227       deadlock itself attempting to acquire a lock that it already owns.   In
228       this  situation,  the  application should strictly adhere to the advice
229       given in the POSIX specification: "To avoid errors, the  child  process
230       may only execute Async-Signal-Safe operations until such time as one of
231       the exec(2) functions is called."
232

RETURN VALUES

234       Upon successful completion, fork(), fork1(),  forkall(),  forkx(),  and
235       forkallx()  return  0 to the child process and return the process ID of
236       the child process  to  the  parent  process.  Otherwise,  (pid_t)−1  is
237       returned  to the parent process, no child process is created, and errno
238       is set to indicate the error.
239

ERRORS

241       The fork(), fork1(), forkall(), forkx(), and forkallx() functions  will
242       fail if:
243
244       EAGAIN    A  resource  control  or   limit  on the total number of pro‐
245                 cesses, tasks or LWPs under execution by a single user, task,
246                 project,  or  zone  has been exceeded, or the total amount of
247                 system memory available is temporarily insufficient to dupli‐
248                 cate this process.
249
250
251       ENOMEM    There is not enough swap space.
252
253
254       EPERM     The  {PRIV_PROC_FORK} privilege is not asserted in the effec‐
255                 tive set of the calling process.
256
257
258
259       The forkx() and forkallx() functions will fail if:
260
261       EINVAL    The flags argument is invalid.
262
263

ATTRIBUTES

265       See attributes(5) for descriptions of the following attributes:
266
267
268
269
270       ┌─────────────────────────────┬─────────────────────────────┐
271       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
272       ├─────────────────────────────┼─────────────────────────────┤
273       │Interface Stability          │Committed                    │
274       ├─────────────────────────────┼─────────────────────────────┤
275       │MT-Level                     │Async-Signal-Safe.           │
276       ├─────────────────────────────┼─────────────────────────────┤
277       │Standard                     │See below.                   │
278       └─────────────────────────────┴─────────────────────────────┘
279
280
281       For fork(), see standards(5).
282

SEE ALSO

284       alarm(2), exec(2), exit(2), fcntl(2), getitimer(2), getrlimit(2), memc‐
285       ntl(2),  mmap(2),  nice(2),  priocntl(2), semop(2), shmop(2), times(2),
286       umask(2),    waitid(2),    door_create(3C),    exit(3C),     plock(3C),
287       pthread_atfork(3C),    pthread_create(3C),    signal(3C),   system(3C),
288       thr_create(3C)  timer_create(3C),  wait(3C),  contract(4),  process(4),
289       attributes(5), privileges(5), standards(5)
290

NOTES

292       An  application  should  call _exit() rather than exit(3C) if it cannot
293       execve(), since exit() will flush and close standard I/O  channels  and
294       thereby  corrupt  the  parent  process's  standard I/O data structures.
295       Using exit(3C) will flush buffered data twice. See exit(2).
296
297
298       The thread in the child that calls fork(), fork1(),  or  fork1x()  must
299       not depend on any resources held by threads that no longer exist in the
300       child. In particular, locks held by these threads will not be released.
301
302
303       In a multithreaded process, forkall() in one thread can cause  blocking
304       system calls to be interrupted and return with an EINTR error.
305
306
307
308SunOS 5.11                        28 Oct 2008                          fork(2)
Impressum