CLONE(2)            Linux Programmer's Manual            CLONE(2)

NAME
       __clone - create a child process

SYNOPSIS
       #include <sched.h>

       int  __clone(int (*fn) (void *arg), void *child_stack, int
       flags, void *arg)

DESCRIPTION
       __clone creates a new process like fork(2)  does.   Unlike
       fork(2),  __clone  allows the child process to share parts
       of its execution context with its parent process, such  as
       the  memory  space, the table of file descriptors, and the
       table of signal handlers.  The main use of __clone  is  to
       implement  threads:  multiple threads of control in a pro-
       gram that run concurrently in a shared memory space.

       When the child process is created, it executes  the  func-
       tion application fn(arg).  The fn argument is a pointer to
       a function that is called by  the  child  process  at  the
       beginning  of  its  execution.  The arg argument is passed
       back to the fn function.

       When the fn(arg) function application returns,  the  child
       process  terminates.   The  integer  returned by fn is the
       exit code for the child process.  The  child  process  may
       also  terminate  explicitely  by  calling exit(1) or after
       receiving a fatal signal.

       The child_stack argument specifies  the  location  of  the
       stack used by the child process.  Since the child and par-
       ent processes may share memory, it is not possible in gen-
       eral for the child process to execute in the same stack as
       the parent process.  The parent process must therefore set
       up  memory space for the child stack and pass a pointer to
       this space to __clone.  Stacks grow downwards on all  pro-
       cessors  that  run Linux (except the HP PA processors), so
       child_stack usually points to the topmost address  of  the
       memory space set up for the child stack.

       The  low  byte  of flags contains the number of the signal
       sent to the parent when the child dies.  flags may also be
       bitwise-or'ed  with  one  or several of the following con-
       stants, in order to specify what  is  shared  between  the
       parent and child processes:

       CLONE_VM
              If  CLONE_VM  is set, the parent and the child pro-
              cesses run in the same memory space.   In  particu-
              lar,  memory writes performed by the parent process
              or by the child process are  also  visible  in  the
              other  process.   Moreover,  any  memory mapping or
              unmapping performed with mmap(2)  or  munmap(2)  by
              the  child or parent process also affects the other
              process.

              If CLONE_VM is not set, the child process runs in a
              separate  copy of the memory space of the parent at
              the time of __clone.  Memory writes  or  file  map-
              ping/unmapping  performed  by  one of the processes
              does not affect  the  other,  as  in  the  case  of
              fork(2).

       CLONE_FS
              If  CLONE_FS  is set, the parent and the child pro-
              cesses share  the  same  file  system  information.
              This includes the root of the file system, the cur-
              rent working directory, and the umask.  Any call to
              chroot(2),  chdir(2),  or umask(2) performed by the
              parent or child process also takes  effect  in  the
              other process.

              If  CLONE_FS is not set, the child process works on
              a copy of the file system information of the parent
              at    the    time    of    __clone.     Calls    to
              chroot(2),chdir(2),umask(2) performed later by  one
              of the processes does not affect the other.

       CLONE_FILES
              If  CLONE_FILES  is  set,  the parent and the child
              processes share the  same  file  descriptor  table.
              File  descriptors always refer to the same files in
              the parent and in  the  child  process.   Any  file
              descriptor  created by the parent process or by the
              child process is also valid in the  other  process.
              Similarly,  if  one  of the processes closes a file
              descriptor, or changes its  associated  flags,  the
              other process is also affected.

              If CLONE_FILES is not set, the child process inher-
              its a copy of all file descriptors  opened  in  the
              parent  process at the time of __clone.  Operations
              on file descriptors performed later by one  of  the
              parent  or child processes do not affect the other.

       CLONE_SIGHAND
              If CLONE_SIGHAND is set, the parent and  the  child
              processes  share the same table of signal handlers.
              If the parent or child process  calls  sigaction(2)
              to  change  the  behavior associated with a signal,
              the behavior is also changed in the  other  process
              as  well.   However, the parent and child processes
              still have distinct signal masks and sets of  pend-
              ing  signals.  So, one of them may block or unblock
              some signals using sigprocmask(2) without affecting
              the other process.

              If  CLONE_SIGHAND  is  not  set,  the child process
              inherits a copy of the signal handlers of its  par-
              ent at the time __clone is called.  Calls to sigac-
              tion(2) performed later by  one  of  the  processes
              have no effect on the other process.

       CLONE_PID
              If  CLONE_PID  is set, the child process is created
              with the same process ID as its parent process.

              If CLONE_PID is not set,  the  child  process  pos-
              sesses  a  unique process ID, distinct from that of
              its parent.

RETURN VALUE
       On success, the PID of the child process  is  returned  in
       the  parent's  thread of execution.  On failure, a -1 will
       be returned in the parent's context, no child process will
       be created, and errno will be set appropriately.

ERRORS
       EAGAIN Too many processes are already running.

       ENOMEM __clone  cannot allocate sufficient memory to allo-
              cate a task structure for the  child,  or  to  copy
              those parts of the parent's context that need to be
              copied.

BUGS
       As of version 2.1.97 of the  kernel,  the  CLONE_PID  flag
       should  not  be  used, since other parts of the kernel and
       most system software still assume  that  process  IDs  are
       unique.

       There  is  no entry for __clone in libc version 5.  libc 6
       (a.k.a. glibc 2) provides __clone  as  described  in  this
       manual page.

CONFORMING TO
       The  __clone call is Linux-specific and should not be used
       in programs intended  to  be  portable.   For  programming
       threaded  applications (multiple threads of control in the
       same memory space), it is better to use a  library  imple-
       menting  the  POSIX 1003.1c thread API, such as the Linux-
       Threads library.  See pthread_create(3thr).

       This manual page corresponds to kernels 2.0.x  and  2.1.x,
       and to glibc 2.0.x.

SEE ALSO
       fork(2), pthread_create(3thr).

Linux 2.0.33              25 april 1998                         1