diff --git a/man2/__clone.2 b/man2/__clone.2 deleted file mode 100644 index 954c87edf..000000000 --- a/man2/__clone.2 +++ /dev/null @@ -1,717 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" -.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 -.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005 -.\" May be distributed under the GNU General Public License. -.\" Modified by Michael Haardt -.\" Modified 24 Jul 1993 by Rik Faith -.\" Modified 21 Aug 1994 by Michael Chastain : -.\" New man page (copied from 'fork.2'). -.\" Modified 10 June 1995 by Andries Brouwer -.\" Modified 25 April 1998 by Xavier Leroy -.\" Modified 26 Jun 2001 by Michael Kerrisk -.\" Mostly upgraded to 2.4.x -.\" Added prototype for sys_clone() plus description -.\" Added CLONE_THREAD with a brief description of thread groups -.\" Added CLONE_PARENT and revised entire page remove ambiguity -.\" between "calling process" and "parent process" -.\" Added CLONE_PTRACE and CLONE_VFORK -.\" Added EPERM and EINVAL error codes -.\" Renamed "__clone" to "clone" (which is the prototype in ) -.\" various other minor tidy ups and clarifications. -.\" Modified 26 Jun 2001 by Michael Kerrisk -.\" Updated notes for 2.4.7+ behavior of CLONE_THREAD -.\" Modified 15 Oct 2002 by Michael Kerrisk -.\" Added description for CLONE_NEWNS, which was added in 2.4.19 -.\" Slightly rephrased, aeb. -.\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. -.\" Modified 1 Jan 2004 - various updates, aeb -.\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc - aeb. -.\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() -.\" wrapper under BUGS. -.\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. -.\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. -.\" -.TH CLONE 2 2007-06-01 "Linux" "Linux Programmer's Manual" -.SH NAME -clone, __clone2 \- create a child process -.SH SYNOPSIS -.nf -.B #include - -.BI "int clone(int (*" "fn" ")(void *), void *" child_stack , -.BI " int " flags ", void *" "arg" ", ... " -.BI " /* pid_t *" pid ", struct user_desc *" tls \ -", pid_t *" ctid " */ );" -.fi -.SH DESCRIPTION -.BR clone () -creates a new process, in a manner similar to -.BR fork (2). -It is actually a library function layered on top of the underlying -.BR clone () -system call, hereinafter referred to as -.BR sys_clone . -A description of -.BR sys_clone -is given towards the end of this page. - -Unlike -.BR fork (2), -these calls -allow the child process to share parts of its execution context 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" normally corresponds to "parent process". -But see the description of -.B CLONE_PARENT -below.) - -The main use of -.BR 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 -.BR clone (), -it executes the function -application -.IR fn ( arg ). -(This differs from -.BR fork (2), -where execution continues in the child from the point -of the -.BR fork (2) -call.) -The -.I fn -argument is a pointer to a function that is called by the child -process at the beginning of its execution. -The -.I arg -argument is passed to the -.I fn -function. - -When the -.IR fn ( arg ) -function application returns, the child process terminates. -The integer returned by -.I fn -is the exit code for the child process. -The child process may also terminate explicitly by calling -.BR exit (2) -or after receiving a fatal signal. - -The -.I 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 -.BR clone (). -Stacks grow downwards on all processors that run Linux -(except the HP PA processors), so -.I child_stack -usually points to the topmost address of the memory space set up for -the child stack. - -The low byte of -.I flags -contains the number of the -.I "termination signal" -sent to the parent when the child dies. -If this signal is specified as anything other than -.BR SIGCHLD , -then the parent process must specify the -.B __WALL -or -.B __WCLONE -options when waiting for the child with -.BR wait (2). -If no signal is specified, then the parent process is not signaled -when the child terminates. - -.I flags -may also be bitwise-or'ed with zero or more of the following constants, -in order to specify what is shared between the calling process -and the child process: -.TP -.BR CLONE_PARENT " (since Linux 2.3.12)" -If -.B CLONE_PARENT -is set, then the parent of the new child (as returned by -.BR getppid (2)) -will be the same as that of the calling process. - -If -.B CLONE_PARENT -is not set, then (as with -.BR fork (2)) -the child's parent is the calling process. - -Note that it is the parent process, as returned by -.BR getppid (2), -which is signaled when the child terminates, so that -if -.B CLONE_PARENT -is set, then the parent of the calling process, rather than the -calling process itself, will be signaled. -.TP -.B CLONE_FS -If -.B 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 directory, and the umask. -Any call to -.BR chroot (2), -.BR chdir (2), -or -.BR umask (2) -performed by the calling process or the child process also affects the -other process. - -If -.B CLONE_FS -is not set, the child process works on a copy of the file system -information of the calling process at the time of the -.BR clone () -call. -Calls to -.BR chroot (2), -.BR chdir (2), -.BR umask (2) -performed later by one of the processes do not affect the other process. -.TP -.B CLONE_FILES -If -.B CLONE_FILES -is set, the calling process and the child processes share the same file -descriptor table. -Any file descriptor created by the calling 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 (using the -.BR fcntl (2) -.B F_SETFD -operation), the other process is also affected. - -If -.B CLONE_FILES -is not set, the child process inherits a copy of all file descriptors -opened in the calling process at the time of -.BR clone (). -(The duplicated file descriptors in the child refer to the -same open file descriptions (see -.BR open (2)) -as the corresponding file descriptors in the calling process.) -Subsequent operations that open or close file descriptors, -or change file descriptor flags, -performed by either the calling -process or the child process do not affect the other process. -.TP -.BR CLONE_NEWNS " (since Linux 2.4.19)" -Start the child in a new namespace. - -Every process lives in a namespace. -The -.I namespace -of a process is the data (the set of mounts) describing the file hierarchy -as seen by that process. -After a -.BR fork (2) -or -.BR clone (2) -where the -.B CLONE_NEWNS -flag is not set, the child lives in the same namespace as the parent. -The system calls -.BR mount (2) -and -.BR umount (2) -change the namespace of the calling process, and hence affect -all processes that live in the same namespace, but do not affect -processes in a different namespace. - -After a -.BR clone (2) -where the -.B CLONE_NEWNS -flag is set, the cloned child is started in a new namespace, -initialized with a copy of the namespace of the parent. - -Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability) -may specify the -.B CLONE_NEWNS -flag. -It is not permitted to specify both -.B CLONE_NEWNS -and -.B CLONE_FS -in the same -.BR clone () -call. -.TP -.B CLONE_SIGHAND -If -.B 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 -.BR sigaction (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 -.BR sigprocmask (2) -without affecting the other process. - -If -.B CLONE_SIGHAND -is not set, the child process inherits a copy of the signal handlers -of the calling process at the time -.BR clone () -is called. -Calls to -.BR sigaction (2) -performed later by one of the processes have no effect on the other -process. - -Since Linux 2.6.0-test6, -.I flags -must also include -.B CLONE_VM -if -.B CLONE_SIGHAND -is specified -.TP -.B CLONE_PTRACE -If -.B CLONE_PTRACE -is specified, and the calling process is being traced, -then trace the child also (see -.BR ptrace (2)). -.TP -.BR CLONE_UNTRACED " (since Linux 2.5.46)" -If -.B CLONE_UNTRACED -is specified, then a tracing process cannot force -.B CLONE_PTRACE -on this child process. -.TP -.BR CLONE_STOPPED " (since Linux 2.6.0-test2)" -If -.B CLONE_STOPPED -is set, then the child is initially stopped (as though it was sent a -.B SIGSTOP -signal), and must be resumed by sending it a -.B SIGCONT -signal. -.TP -.B CLONE_VFORK -If -.B CLONE_VFORK -is set, the execution of the calling process is suspended -until the child releases its virtual memory -resources via a call to -.BR execve (2) -or -.BR _exit (2) -(as with -.BR vfork (2)). - -If -.B CLONE_VFORK -is not set then both the calling process and the child are schedulable -after the call, and an application should not rely on execution occurring -in any particular order. -.TP -.B CLONE_VM -If -.B 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 mapping or unmapping performed with -.BR mmap (2) -or -.BR munmap (2) -by the child or calling process also affects the other process. - -If -.B 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 -.BR clone (). -Memory writes or file mappings/unmappings performed by one of the -processes do not affect the other, as with -.BR fork (2). -.TP -.BR CLONE_PID " (obsolete)" -If -.B CLONE_PID -is set, the child process is created with the same process ID as -the calling process. -This is good for hacking the system, but otherwise -of not much use. -Since 2.3.21 this flag can be -specified only by the system boot process (PID 0). -It disappeared in Linux 2.5.16. -.TP -.BR CLONE_THREAD " (since Linux 2.4.0-test8)" -If -.B CLONE_THREAD -is set, the child is placed in the same thread group as the calling process. -To make the remainder of the discussion of -.B CLONE_THREAD -more readable, the term "thread" is used to refer to the -processes within a thread group. - -Thread groups were a feature added in Linux 2.4 to support the -POSIX threads notion of a set of threads that share a single PID. -Internally, this shared PID is the so-called -thread group identifier (TGID) for the thread group. -Since Linux 2.4, calls to -.BR getpid (2) -return the TGID of the caller. - -The threads within a group can be distinguished by their (system-wide) -unique thread IDs (TID). -A new thread's TID is available as the function result -returned to the caller of -.BR clone (), -and a thread can obtain -its own TID using -.BR gettid (2). - -When a call is made to -.BR clone () -without specifying -.BR CLONE_THREAD , -then the resulting thread is placed in a new thread group -whose TGID is the same as the thread's TID. -This thread is the -.I leader -of the new thread group. - -A new thread created with -.B CLONE_THREAD -has the same parent process as the caller of -.BR clone () -(i.e., like -.BR CLONE_PARENT ), -so that calls to -.BR getppid (2) -return the same value for all of the threads in a thread group. -When a -.B CLONE_THREAD -thread terminates, the thread that created it using -.BR clone () -is not sent a -.B SIGCHLD -(or other termination) signal; -nor can the status of such a thread be obtained -using -.BR wait (2). -(The thread is said to be -.IR detached .) - -After all of the threads in a thread group terminate -the parent process of the thread group is sent a -.B SIGCHLD -(or other termination) signal. - -If any of the threads in a thread group performs an -.BR execve (2), -then all threads other than the thread group leader are terminated, -and the new program is executed in the thread group leader. - -If one of the threads in a thread group creates a child using -.BR fork (2), -then any thread in the group can -.BR wait (2) -for that child. - -Since Linux 2.5.35, -.I flags -must also include -.B CLONE_SIGHAND -if -.B CLONE_THREAD -is specified. - -Signals may be sent to a thread group as a whole (i.e., a TGID) using -.BR kill (2), -or to a specific thread (i.e., TID) using -.BR tgkill (2). - -Signal dispositions and actions are process-wide: -if an unhandled signal is delivered to a thread, then -it will affect (terminate, stop, continue, be ignored in) -all members of the thread group. - -Each thread has its own signal mask, as set by -.BR sigprocmask (2), -but signals can be pending either: for the whole process -(i.e., deliverable to any member of the thread group), -when sent with -.BR kill (2); -or for an individual thread, when sent with -.BR tgkill (2). -A call to -.BR sigpending (2) -returns a signal set that is the union of the signals pending for the -whole process and the signals that are pending for the calling thread. - -If -.BR kill (2) -is used to send a signal to a thread group, -and the thread group has installed a handler for the signal, then -the handler will be invoked in exactly one, arbitrarily selected -member of the thread group that has not blocked the signal. -If multiple threads in a group are waiting to accept the same signal using -.BR sigwaitinfo (2), -the kernel will arbitrarily select one of these threads -to receive a signal sent using -.BR kill (2). -.TP -.BR CLONE_SYSVSEM " (since Linux 2.5.10)" -If -.B CLONE_SYSVSEM -is set, then the child and the calling process share -a single list of System V semaphore undo values (see -.BR semop (2)). -If this flag is not set, then the child has a separate undo list, -which is initially empty. -.TP -.BR CLONE_SETTLS " (since Linux 2.5.32)" -The -.I newtls -parameter is the new TLS (Thread Local Storage) descriptor. -(See -.BR set_thread_area (2).) -.TP -.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" -Store child thread ID at location -.I parent_tidptr -in parent and child memory. -(In Linux 2.5.32-2.5.48 there was a flag -.BR CLONE_SETTID -that did this.) -.TP -.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" -Store child thread ID at location -.I child_tidptr -in child memory. -.TP -.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" -Erase child thread ID at location -.I child_tidptr -in child memory when the child exits, and do a wakeup on the futex -at that address. -The address involved may be changed by the -.BR set_tid_address (2) -system call. -This is used by threading libraries. -.SS "sys_clone" -The -.B sys_clone -system call corresponds more closely to -.BR fork (2) -in that execution in the child continues from the point of the -call. -Thus, -.B sys_clone -only requires the -.I flags -and -.I child_stack -arguments, which have the same meaning as for -.BR clone (). -(Note that the order of these arguments differs from -.BR clone ().) - -Another difference for -.B sys_clone -is that the -.I 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 -.B CLONE_VM -option should not be specified. - -Since Linux 2.5.49 the system call has five parameters. -The two new parameters are -.I parent_tidptr -which points to the location (in parent and child memory) where -the child thread ID will be written in case -.B CLONE_PARENT_SETTID -was specified, and -.I child_tidptr -which points to the location (in child memory) where the child thread ID -will be written in case -.B CLONE_CHILD_SETTID -was specified. -.SH "RETURN VALUE" -.\" gettid(2) returns current->pid; -.\" getpid(2) returns current->tgid; -On success, the thread ID 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 created, and -.I errno -will be set appropriately. -.SH ERRORS -.TP -.B EAGAIN -Too many processes are already running. -.TP -.B EINVAL -.B CLONE_SIGHAND -was specified, but -.B CLONE_VM -was not. -(Since Linux 2.6.0-test6.) -.TP -.B EINVAL -.B CLONE_THREAD -was specified, but -.B CLONE_SIGHAND -was not. (Since Linux 2.5.35.) -.\" .TP -.\" .B EINVAL -.\" Precisely one of -.\" .B CLONE_DETACHED -.\" and -.\" .B CLONE_THREAD -.\" was specified. (Since Linux 2.6.0-test6.) -.TP -.B EINVAL -Both -.B CLONE_FS -and -.B CLONE_NEWNS -were specified in -.IR flags . -.TP -.B EINVAL -Returned by -.BR clone () -when a zero value is specified for -.IR child_stack . -.TP -.B 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. -.TP -.B EPERM -.B CLONE_NEWNS -was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). -.TP -.B EPERM -.B CLONE_PID -was specified by a process other than process 0. -.SH VERSIONS -There is no entry for -.BR clone () -in libc5. -glibc2 provides -.BR clone () -as described in this manual page. -.SH "CONFORMING TO" -The -.BR clone () -and -.B sys_clone -calls are Linux specific and should not be used in programs -intended to be portable. -.SH NOTES -In the kernel 2.4.x series, -.B CLONE_THREAD -generally does not make the parent of the new thread the same -as the parent of the calling process. -However, for kernel versions 2.4.7 to 2.4.18 the -.B CLONE_THREAD -flag implied the -.B CLONE_PARENT -flag (as in kernel 2.6). - -For a while there was -.B CLONE_DETACHED -(introduced in 2.5.32): -parent wants no child-exit signal. -In 2.6.2 the need to give this -together with -.B CLONE_THREAD -disappeared. -This flag is still defined, but has no effect. - -On x86, -.BR clone () -should not be called through vsyscall, but directly through -.IR "int $0x80" . - -On IA-64, a different system call is used: -.nf - -.BI "int __clone2(int (*" "fn" ")(void *), " -.BI " void *" child_stack_base ", size_t " stack_size , -.BI " int " flags ", void *" "arg" ", ... " -.BI " /* pid_t *" pid ", struct user_desc *" tls \ -", pid_t *" ctid " */ );" -.fi -.PP -The -.BR __clone2 () -system call operates in the same way as -.BR clone (), -except that -.I child_stack_base -points to the lowest address of the child's stack area, -and -.I stack_size -specifies the size of the stack pointed to by -.IR child_stack_base . -.SH BUGS -Versions of the GNU C library that include the NPTL threading library -contain a wrapper function for -.BR getpid (2) -that performs caching of PIDs. -In programs linked against such libraries, calls to -.BR getpid (2) -may return the same value, even when the threads were not created using -.B CLONE_THREAD -(and thus are not in the same thread group). -To get the truth, it may be necessary to use code such as the following -.nf - - #include - - pid_t mypid; - - mypid = syscall(SYS_getpid); -.fi -.SH "SEE ALSO" -.BR fork (2), -.BR futex (2), -.BR getpid (2), -.BR gettid (2), -.BR set_thread_area (2), -.BR set_tid_address (2), -.BR tkill (2), -.BR unshare (2), -.BR wait (2), -.BR capabilities (7), -.BR pthreads (7)