System Calls                                              fork(2)


NAME

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


SYNOPSIS

     #include <sys/types.h>
     #include <unistd.h>

     pid_t fork(void);

     pid_t fork1(void);

     pid_t forkall(void);

     #include <sys/fork.h>

     pid_t forkx(int flags);

     pid_t forkallx(int flags);


DESCRIPTION

     The fork(),  fork1(),  forkall(),  forkx(),  and  forkallx()
     functions create a new process. The address space of the new
     process (child process) is an  exact  copy  of  the  address
     space  of  the  calling  process (parent process). The child
     process inherits the following attributes  from  the  parent
     process:

         o    real user ID, real group  ID,  effective  user  ID,
              effective group ID

         o    environment

         o    open file descriptors

         o    close-on-exec flags (see exec(2))

         o    signal  handling  settings   (that   is,   SIG_DFL,
              SIG_IGN, SIG_HOLD, function address)

         o    supplementary group IDs

         o    set-user-ID mode bit

         o    set-group-ID mode bit

         o    profiling on/off status

SunOS 5.11          Last change: 28 Oct 2008                    1


System Calls                                              fork(2)

         o    nice value (see nice(2))

         o    scheduler class (see priocntl(2))

         o    all attached shared memory segments (see shmop(2))

         o    process group ID -- memory mappings (see mmap(2))

         o    session ID (see exit(2))

         o    current working directory

         o    root directory

         o    file mode creation mask (see umask(2))

         o    resource limits (see getrlimit(2))

         o    controlling terminal

         o    saved user ID and group ID

         o    task ID and project ID

         o    processor bindings (see processor_bind(2))

         o    processor set bindings (see pset_bind(2))

         o    process privilege sets (see getppriv(2))

         o    process flags (see getpflags(2))

         o    active contract templates (see contract(4))

     Scheduling priority and any per-process  scheduling  parame-
     ters  that are specific to a given scheduling class might or
     might not be inherited according to the policy of that  par-
     ticular class (see priocntl(2)).  The child process might or
     might not be in the same process contract as the parent (see
     process(4)).  The child process differs from the parent pro-
     cess in the following ways:

         o    The child process has a  unique  process  ID  which
              does not match any active process group ID.

         o    The child process has a different parent process ID
              (that is, the process ID of the parent process).

         o    The child process has its own copy of the  parent's
              file descriptors and directory streams. Each of the
              child's  file  descriptors  shares  a  common  file

SunOS 5.11          Last change: 28 Oct 2008                    2


System Calls                                              fork(2)

              pointer  with  the corresponding file descriptor of
              the parent.

         o    Each shared memory segment remains attached and the
              value of shm_nattach is incremented by 1.

         o    All semadj values are cleared (see semop(2)).

         o    Process locks, text locks, data  locks,  and  other
              memory  locks  are  not inherited by the child (see
              plock(3C) and memcntl(2)).

         o    The  child  process's  tms  structure  is  cleared:
              tms_utime,  stime,  cutime, and cstime are set to 0
              (see times(2)).

         o    The child processes resource utilizations  are  set
              to   0;   see   getrlimit(2).    The  it_value  and
              it_interval values for the  ITIMER_REAL  timer  are
              reset to 0; see getitimer(2).

         o    The set of signals pending for the child process is
              initialized to the empty set.

         o    Timers created by timer_create(3C) are  not  inher-
              ited by the child process.

         o    No asynchronous input or asynchronous output opera-
              tions are inherited by the child.

         o    Any preferred hardware  address  tranlsation  sizes
              (see memcntl(2)) are inherited by the child.

         o    The child process  holds  no  contracts  (see  con-
              tract(4)).

     Record locks set by the parent process are not inherited  by
     the child process (see fcntl(2)).

     Although any open door descriptors in the parent are  shared
     by the child, only the parent will receive a door invocation
     from clients even if the door  descriptor  is  open  in  the
     child.  If a descriptor is closed in the parent, attempts to
     operate on the door descriptor will fail even if it is still
     open in the child.

  Threads
     A call to forkall() or forkallx() replicates  in  the  child
     process   all   of   the  threads  (see  thr_create(3C)  and
     pthread_create(3C)) in the parent process. A call to fork1()

SunOS 5.11          Last change: 28 Oct 2008                    3


System Calls                                              fork(2)

     or  forkx()  replicates only the calling thread in the child
     process.

     A call to fork() is identical to a call to fork1(); only the
     calling  thread  is replicated in the child process. This is
     the POSIX-specified behavior for fork().

     In releases of Solaris prior to Solaris 10, the behavior  of
     fork() depended on whether or not the application was linked
     with the POSIX threads library. When  linked  with  -lthread
     (Solaris  Threads)  but  not  linked  with  -lpthread (POSIX
     Threads), fork() was the same  as  forkall().   When  linked
     with  -lpthread,  whether  or not also linked with -lthread,
     fork() was the same as fork1().

     Prior to  Solaris  10,  either  -lthread  or  -lpthread  was
     required  for  multithreaded applications. This is no longer
     the case. The standard C library provides all threading sup-
     port  for  both  sets of application programming interfaces.
     Applications that require replicate-all fork semantics  must
     call forkall() or forkallx().

  Fork Extensions
     The forkx() and forkallx() functions accept a flags argument
     consisting  of a bitwise inclusive-OR of zero or more of the
     following  flags,  which   are   defined   in   the   header
     <sys/fork.h>:

     FORK_NOSIGCHLD

         Do not post a SIGCHLD signal to the parent process  when
         the child process terminates, regardless of the disposi-
         tion of the SIGCHLD signal in the parent.  SIGCHLD  sig-
         nals  are  still  possible for job control stop and con-
         tinue actions if the parent has requested them.

     FORK_WAITPID

         Do not allow wait-for-multiple-pids by the parent, as in
         wait(),  waitid(P_ALL),  or  waitid(P_PGID), to reap the
         child and do not allow the child to be reaped  automati-
         cally  due  the  disposition of the SIGCHLD signal being
         set to be ignored in the parent.  Only a  specific  wait
         for  the child, as in waitid(P_PID, pid), is allowed and
         it is required, else when the child exits it will remain
         a zombie until the parent exits.

SunOS 5.11          Last change: 28 Oct 2008                    4


System Calls                                              fork(2)

     If the flags argument is 0 forkx() is  identical  to  fork()
     and forkallx() is identical to forkall().

  fork() Safety
     If a multithreaded application  calls  fork(),  fork1(),  or
     forkx(), and the child does more than simply call one of the
     exec(2) functions, there is a possibility of deadlock occur-
     ring    in   the   child.   The   application   should   use
     pthread_atfork(3C) to ensure safety  with  respect  to  this
     deadlock. Should there be any outstanding mutexes throughout
     the process, the application should call pthread_atfork() to
     wait  for and acquire those mutexes prior to calling fork(),
     fork1(), or forkx(). See  "MT-Level  of  Libraries"  on  the
     attributes(5) manual page.

     The pthread_atfork() mechanism is used to protect the  locks
     that   libc(3LIB)  uses  to  implement  interfaces  such  as
     malloc(3C).  All interfaces provided by libc are safe to use
     in a child process following a fork(), except when fork() is
     executed within a signal handler.

     The POSIX standard (see standards(5)) requires  fork  to  be
     Async-Signal-Safe  (see attributes(5)).  This cannot be made
     to happen with fork handlers in place, because they  acquire
     locks.  To  be  in  nominal compliance, no fork handlers are
     called when fork() is  executed  within  a  signal  context.
     This  leaves  the child process in a questionable state with
     respect to its locks, but at least the calling  thread  will
     not  deadlock  itself  attempting  to acquire a lock that it
     already owns.  In this  situation,  the  application  should
     strictly  adhere to the advice given in the POSIX specifica-
     tion: "To avoid errors, the child process may  only  execute
     Async-Signal-Safe  operations  until such time as one of the
     exec(2) functions is called."


RETURN VALUES

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


ERRORS

     The fork(),  fork1(),  forkall(),  forkx(),  and  forkallx()
     functions will fail if:

     EAGAIN    A resource control or  limit on the  total  number
               of  processes,  tasks or LWPs under execution by a
               single user,  task,  project,  or  zone  has  been

SunOS 5.11          Last change: 28 Oct 2008                    5


System Calls                                              fork(2)

               exceeded,  or  the  total  amount of system memory
               available is temporarily insufficient to duplicate
               this process.

     ENOMEM    There is not enough swap space.

     EPERM     The {PRIV_PROC_FORK} privilege is not asserted  in
               the effective set of the calling process.

     The forkx() and forkallx() functions will fail if:

     EINVAL    The flags argument is invalid.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe.          |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|

     For fork(), see standards(5).


SEE ALSO

     alarm(2),   exec(2),   exit(2),   fcntl(2),    getitimer(2),
     getrlimit(2),  memcntl(2),  mmap(2),  nice(2),  priocntl(2),
     semop(2),   shmop(2),   times(2),    umask(2),    waitid(2),
     door_create(3C),  exit(3C),  plock(3C),  pthread_atfork(3C),
     pthread_create(3C), signal(3C),  system(3C),  thr_create(3C)
     timer_create(3C),  wait(3C), contract(4), process(4), attri-
     butes(5), privileges(5), standards(5)


NOTES

     An application should call _exit() rather than  exit(3C)  if
     it  cannot execve(), since exit() will flush and close stan-
     dard I/O channels and thereby corrupt the  parent  process's
     standard  I/O  data  structures.  Using  exit(3C) will flush

SunOS 5.11          Last change: 28 Oct 2008                    6


System Calls                                              fork(2)

     buffered data twice. See exit(2).

     The thread in the  child  that  calls  fork(),  fork1(),  or
     fork1x()  must  not  depend on any resources held by threads
     that no longer exist in the child. In particular, locks held
     by these threads will not be released.

     In a multithreaded process,  forkall()  in  one  thread  can
     cause  blocking  system  calls  to be interrupted and return
     with an EINTR error.

SunOS 5.11          Last change: 28 Oct 2008                    7


Man(1) output converted with man2html


FhG Schily's Home VED powered