MAN page from Mandrake Other man-pages-gz-1.21-2.noarch.rpm

CLONE

Section: Linux Programmer's Manual (2)
Updated: 25 april 1998
Index

NAME

__clone - create a child process

SYNOPSIS

#include <sched.h>

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

DESCRIPTION

__clonecreates a new process likefork(2)does. Unlikefork(2),__cloneallows the child process to share parts of its execution context withits parent process, such as the memory space, the table of filedescriptors, and the table of signal handlers. The main use of__cloneis to implement threads: multiple threads of control in a program thatrun concurrently in a shared memory space.

When the child process is created, it executes the functionapplicationfn(arg).Thefnargument is a pointer to a function that is called by the childprocess at the beginning of its execution.Theargargument is passed back to thefnfunction.

When the fn(arg)function application returns, the child process terminates. Theinteger returned byfnis the exit code for the child process. The child process may alsoterminate explicitely by callingexit(1)or after receiving a fatal signal.

Thechild_stackargument specifies the location of the stack used by the childprocess. Since the child and parent processes may share memory,it is not possible in general for the child process to execute in thesame stack as the parent process. The parent process must thereforeset up memory space for the child stack and pass a pointer to thisspace to__clone.Stacks grow downwards on all processors that run Linux(except the HP PA processors), sochild_stackusually points to the topmost address of the memory space set up forthe child stack.

The low byte offlagscontains the number of the signal sent to the parent when the childdies.flagsmay also be bitwise-or'ed with one or several of the followingconstants, in order to specify what is shared between the parent andchild processes:

CLONE_VM

IfCLONE_VMis set, the parent and the child processes run in the same memoryspace. In particular, memory writes performed by the parent processor by the child process are also visible in the other process.Moreover, any memory mapping or unmapping performed withmmap(2)ormunmap(2)by the child or parent process also affects the other process.

IfCLONE_VMis not set, the child process runs in a separate copy of the memoryspace of the parent at the time of__clone.Memory writes or file mapping/unmapping performed by one of theprocesses does not affect the other, as in the case offork(2).

CLONE_FS

IfCLONE_FSis set, the parent and the child processes share the same file systeminformation. This includes the root of the file system, the currentworking directory, and the umask. Any call tochroot(2),chdir(2),orumask(2)performed by the parent or child process also takes effect in theother process.

If CLONE_FSis not set, the child process works on a copy of the file systeminformation of the parent at the time of__clone.Calls tochroot(2),chdir(2),umask(2)performed later by one of the processes does not affect the other.

CLONE_FILES

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

IfCLONE_FILESis not set, the child process inherits a copy of all file descriptorsopened in the parent process at the time of__clone.Operations on file descriptors performed later by one of the parent orchild processes do not affect the other.

CLONE_SIGHAND

IfCLONE_SIGHANDis set, the parent and the child processes share the same table ofsignal handlers. If the parent or child process callssigaction(2)to change the behavior associated with a signal, the behavior is alsochanged in the other process as well. However, the parent and childprocesses still have distinct signal masks and sets of pendingsignals. So, one of them may block or unblock some signals usingsigprocmask(2)without affecting the other process.

IfCLONE_SIGHANDis not set, the child process inherits a copy of the signal handlersof its parent at the time__cloneis called. Calls tosigaction(2)performed later by one of the processes have no effect on the otherprocess.

CLONE_PID

IfCLONE_PIDis set, the child process is created with the same process ID as itsparent process.

IfCLONE_PIDis not set, the child process possesses a unique process ID, distinctfrom that of its parent.

RETURN VALUE

On success, the PID of the child process is returned in the parent's threadof execution. On failure, a -1 will be returned in the parent'scontext, no child process will be created, anderrnowill be set appropriately.

ERRORS

EAGAIN: Too many processes are already running.
ENOMEM: __clonecannot allocate sufficient memory to allocate a task structure for thechild, or to copy those parts of the parent's context that need to becopied.

BUGS

As of version 2.1.97 of the kernel,theCLONE_PIDflag should not be used, since other parts of the kernel and most systemsoftware still assume that process IDs are unique.

There is no entry for__clonein libc version 5. libc 6 (a.k.a. glibc 2) provides__cloneas described in this manual page.

CONFORMING TO

The__clonecall is Linux-specific and should not be used in programsintended to be portable. For programming threaded applications(multiple threads of control in the same memory space), it is betterto use a library implementing the POSIX 1003.1c thread API, such asthe LinuxThreads library. Seepthread_create(3thr).

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

This document was created byman2html,using the manual pages.