Author: bob

CLONE3(2)                   System Programmer's Manual                 CLONE3(2)



NAME
       clone3 - create a child process

SYNOPSIS
       #include <clone.h>

       int clone3(pid_t parent, pid_t co_parent,
                 int (*fn)(void *), void *child_stack,
                 int flags, void *arg, ... );

DESCRIPTION
       clone3()  creates  a new process, in a manner similar to fork(2).

       Unlike fork(2), these calls allow the child process to share  parts  of
       its  execution  context  with  the  parent and co-parent processes,
       such as their home, food, and approximately half of their genetic
       material.

       The main use of clone3() is to implement offspring: sentient beings
       that run concurrently with the parents in a shared environment.

       When  the  child  process  is  created  with  clone3(),  it executes the
       function  application  fn(arg).   (This  differs  from  fork(2),  where
       execution  continues  in the child from the point of the fork(2) call.)
       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
       to the fn function.  Although the parent processes may supply a suitable
       fn function, the child process has a mind of its own and may deviate
       from its execution at will.

       Executing clone3 will randomly select half of the genes from each
       parent, resulting in a selection of phenotypes according to
       Mendelian inheritance.  By design this process increases the
       number of bits in the global entropy pool, making recovery of the
       random state impractical.

       The  child_stack  argument  specifies the location of the pile of
       diapers used by the child process.  After the child process leaves
       the EMBRYO state and until it acquires the CAP_POTTY capability,
       it may frequently dump core.  The calling process must therefore
       set up a large store of waste disposal units and pass a pointer to
       this store to clone3().  After a successful core dump it is necessary
       for a parent to handle the condition as soon as possible.

       The flags parameter may  be  bitwise-or'ed  with zero or more of the
       following constants, in order to specify  the behavior of the system
       call:

        CLONE_XY
              Setting CLONE_XY indicates to the system that a child of the
              male gender is requested.  This is only a hint to the system
              and may not be honored.

        CLONE_XX
              Setting CLONE_XX indicates to the system that a child of the
              female gender is requested.  This is only a hint to the system
              and may not be honored.

              If both CLONE_XY and CLONE_XX are set, results are undefined.

RETURN VALUE
       On  completion,  the  thread  ID  of  the child process is returned in
       both parents' thread of execution.  During execution, the child process
       may signal an error condition by raising any of the following signals.

SIGNALS
       HUNGRY  The stomach monitor process has detected an empty condition.
               The parent may correct the condition by supplying food.

       TIRED   The process has executed too many cycles and must enter
               sleep(3).

       GRUMPY  The process is raising signals at full volume for unknown
               reasons.  The parent process should attach pacifier(2) to
               the child process and attempt to cause it to enter sleep(3).

       HAPPY   The process is in a suitable state for taking pictures for
               grandparents.

CONFORMING TO
       Biology 101.

BUGS
       Child process may spit-up on your new shirt; a burping cloth is
       recommended.

EXAMPLE
       The following psuedo-code illustrates the intended usage:

       #include <clone.h>

       int main(int argc, char *argv[])
       {
            pid_t ange = /* ... */
            pid_t bob =  /* ... */
            pid_t alex;

            alex = clone3(ange, bob, fn, stack, CLONE_XY, NULL);
            sleep(86400 * 30 * 9);

            take_snapshot(alex);
       }

       This yields the following:

       
       Alexander Yit-Keung Copeland
       Born 26 June, 2010
       Weight 7 lbs 12 oz

SEE ALSO
       fork(2),    futex(2),    getpid(2),    gettid(2),   set_thread_area(2),
       set_tid_address(2),  tkill(2),  unshare(2),  wait(2),  capabilities(7),
       pthreads(7)


CLONE3(2)                         2010-06-26                          CLONE3(2)