Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for clone (redhat section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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

       clone - create a child process

       #include <sched.h>

       int clone(int (*fn)(void *), void *child_stack, int flags, void *arg);

       _syscall2(int, clone, int, flags, void *, child_stack);

       clone  creates  a  new process, just like fork(2).  clone is a library function layered on
       top of the underlying clone system call, hereinafter referred to as sys_clone.  A descrip-
       tion of sys_clone is given towards the end of this page.

       Unlike  fork(2),  these calls allow the child process to share parts of its execution con-
       text with the calling process, such as the memory space, the table  of  file  descriptors,
       and  the table of signal handlers.  (Note that on this manual page, "calling process" nor-
       mally corresponds to "parent process".  But see the description of CLONE_PARENT below.)

       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  with  clone,  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

       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  termi-
       nate explicitly by calling exit(2) 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 calling process may share memory, it is not	possible  for  the  child
       process	to  execute  in  the same stack as the calling process.  The calling 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 proces-
       sors), 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.  If this signal is specified as anything other than SIGCHLD, then the parent process
       must  specify  the __WALL or __WCLONE options when waiting for the child with wait(2).  If
       no signal is specified, then the parent process is not signaled when the child terminates.

       flags may also be bitwise-or'ed with one or several of the following constants,	in  order
       to specify what is shared between the calling process and the child process:

	      (Linux  2.4  onwards)  If CLONE_PARENT is set, then the parent of the new child (as
	      returned by getppid(2)) will be the same as that of the calling process.

	      If CLONE_PARENT is not set, then (as with fork(2)) the child's parent is the  call-
	      ing process.

	      Note  that  it  is the parent process, as returned by getppid(2), which is signaled
	      when the child terminates, so that if CLONE_PARENT is set, then the parent  of  the
	      calling process, rather than the calling process itself, will be signaled.

	      If  CLONE_FS  is set, the caller 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
	      calling process or the 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 infor-
	      mation  of  the calling process at the time of the clone call.  Calls to chroot(2),
	      chdir(2), umask(2) performed later by one of the processes do not affect the  other

	      If  CLONE_FILES  is set, the calling process and the child processes share the same
	      file descriptor table.  File descriptors always refer to	the  same  files  in  the
	      calling process and in the child process.  Any file descriptor created by the call-
	      ing 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 inherits a copy of all  file  descrip-
	      tors  opened  in	the  calling  process  at  the time of clone.  Operations on file
	      descriptors performed later by either the calling process or the child  process  do
	      not affect the other process.

	      If CLONE_SIGHAND is set, the calling process and the child processes share the same
	      table of signal handlers.  If the calling process or  child  process  calls  sigac-
	      tion(2) to change the behavior associated with a signal, the behavior is changed in
	      the other process as well.  However, the calling process 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  han-
	      dlers  of  the  calling process 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_PTRACE is specified, and the calling process is being traced,  then  trace
	      the child also (see ptrace(2)).

	      If  CLONE_VFORK is set, the execution of the calling process is suspended until the
	      child releases its virtual memory resources via a call to execve(2) or _exit(2) (as
	      with vfork(2)).

	      If CLONE_VFORK is not set then both the calling process and the child are schedula-
	      ble after the call, and an application should not rely on  execution  occurring  in
	      any particular order.

	      If  CLONE_VM  is	set,  the calling process and the child processes run in the same
	      memory space.  In particular, memory writes performed by the calling process or  by
	      the child process are also visible in the other process.	Moreover, any memory map-
	      ping or unmapping performed with mmap(2) or  munmap(2)  by  the  child  or  calling
	      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 calling process at the time of clone.   Memory  writes  or  file  map-
	      pings/unmappings performed by one of the processes do not affect the other, as with

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

	      If  CLONE_PID is not set, the child process possesses a unique process ID, distinct
	      from that of the calling process.

	      This flag can only be specified by the system boot process (PID 0).

	      (Linux 2.4 onwards) If CLONE_THREAD is set, the child is placed in the same  thread
	      group as the calling process.

	      If CLONE_THREAD is not set, then the child is placed in its own (new) thread group,
	      whose ID is the same as the process ID.

	      (Thread groups are feature added in Linux 2.4 to support the POSIX  threads  notion
	      of  a set of threads sharing a single PID.  In Linux 2.4, calls to getpid(2) return
	      the thread group ID of the caller.)

	      If this flag is specified in Linux 2.4.7 onwards, the parent of the child  is  made
	      the  same  as  the  caller's  parent  (i.e.,  this  flag includes the effect of the
	      CLONE_PARENT flag).

       The sys_clone system call corresponds more closely to fork(2) in  that  execution  in  the
       child  continues  from the point of the call.  Thus, sys_clone only requires the flags and
       child_stack arguments, which have the same meaning as for clone.  (Note that the order  of
       these arguments differs from clone.)

       Another	difference  for  sys_clone is that the child_stack argument may be zero, in which
       case copy-on-write semantics ensure that the child gets separate  copies  of  stack  pages
       when either process modifies the stack.	In this case, for correct operation, the CLONE_VM
       option should not be specified.

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

       EAGAIN Too many processes are already running.

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

       EINVAL Returned by clone when a zero value is specified for child_stack.

       EPERM  CLONE_PID was specified by a process with a non-zero PID.

       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  and	sys_clone  calls  are  Linux-specific  and should not be used in programs
       intended to be portable.  For programming threaded applications (multiple threads of  con-
       trol  in  the  same  memory  space),  it is better to use a library implementing the POSIX
       1003.1c	thread	API,  such  as	the  LinuxThreads  library  (included  in  glibc2).   See

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

       fork(2), wait(2), pthread_create(3)

Linux 2.4				    2001-06-26					 CLONE(2)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 12:39 AM.