__clone - create a child process


     #include <sched.h>

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


     __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 program that run
     concurrently in a shared memory space.

     When the child process is created, it executes the  function
     application  fn(arg).   The  fn  argument  is a pointer to a
     function that is called by the child process at  the  begin-
     ning  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 ter-
     minate  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 parent
     processes may share memory, it is not  possible  in  general
     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  processors
     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:

          If CLONE_VM is set, the parent and the child  processes
          run  in  the  same memory space.  In particular, memory
          writes performed by the parent process or by the  child
          process  are  also visible in the other process.  More-
          over, 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
          mapping/unmapping  performed  by  one  of the processes
          does not affect the other, as in the case of fork(2).

          If CLONE_FS is set, the parent and the child  processes
          share  the same file system information.  This includes
          the root of the file system, the current working direc-
          tory,  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.

          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

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

          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 pending 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 parent at the time
          __clone is called.   Calls  to  sigaction(2)  performed
          later  by  one  of  the processes have no effect on the
          other process.

          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 possesses  a
          unique process ID, distinct from that of its parent.


     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.


          Too many processes are already running.

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


     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.


     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 implementing the POSIX
     1003.1c thread API, such as the LinuxThreads  library.   See

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


     fork(2), pthread_create(3thr).