Creates a new process, in a manner similar to sys_fork. But unlike sys_fork, it allows 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 CLONE_PARENT below.)
The main use of sys_clone is to implement threads: multiple threads of control in a program that run concurrently in a shared memory space.
Arguments
eax |
120 |
ebx |
Clone flags:
CLONE_VM |
If 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 sys_mmap or sys_munmap by the child or calling process also affects the other process.
If 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 mappings/unmappings performed by one of the processes do not affect the other, as with sys_fork. |
CLONE_FS |
If 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 sys_chroot, sys_chdir, or sys_umask 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 information of the calling process at the time of the clone call. Calls to sys_chroot, sys_chdir, sys_umask performed later by one of the processes do not affect the other process. |
CLONE_FILES |
If 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 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, the other process is also affected.
If not set, the child process inherits a copy of all file descriptors 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. |
CLONE_SIGHAND |
If set, the calling process and the child processes share the same table of signal handlers. If the calling process or child process calls sys_sigaction 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 sys_sigprocmask without affecting the other process.
If not set, the child process inherits a copy of the signal handlers of the calling process at the time clone is called. Calls to sys_sigaction performed later by one of the processes have no effect on the other process. |
CLONE_PTRACE |
If CLONE_PTRACE is specified, and the calling process is being traced, then trace the child also (see sys_ptrace). |
CLONE_VFORK |
If set, the execution of the calling process is suspended until the child releases its virtual memory resources via a call to sys_execve or sys_exit (as with sys_vfork).
If 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. |
CLONE_PARENT |
If set, then the parent of the new child (as returned by sys_getppid) will be the same as that of the calling process.
If not set, then (as with sys_fork) the child's parent is the calling process.
Note that it is the parent process, as returned by sys_getppid, 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. |
CLONE_THREAD |
If set, the child is placed in the same thread group as the calling process. To make the remainder of the discussion of 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. Calls to sys_getpid 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 sys_clone, and a thread can obtain its own TID using sys_gettid.
When a call is made to sys_clone without specifying 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 leader of the new thread group.
A new thread created with CLONE_THREAD has the same parent process as the caller of sys_clone (i.e., like CLONE_PARENT), so that calls to sys_getppid return the same value for all of the threads in a thread group. When a CLONE_THREAD thread terminates, the thread that created it using sys_clone is not sent a SIGCHLD (or other termination) signal; nor can the status of such a thread be obtained using sys_wait*. (The thread is said to be detached.)
After all of the threads in a thread group terminate the parent process of the thread group is sent a SIGCHLD (or other termination) signal.
If any of the threads in a thread group performs an sys_execve, 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 sys_fork, then any thread in the group can sys_wait* for that child.
If CLONE_THREAD is specified then CLONE_SIGHAND must be specified as well.
Signals may be sent to a thread group as a whole (i.e., a TGID) using sys_kill, or to a specific thread (i.e., TID) using sys_tgkill.
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 sys_sigprocmask, but signals can be pending either for the whole process (i.e., deliverable to any member of the thread group), when sent with sys_kill or for an individual thread, when sent with sys_tgkill. A call to sys_sigpending 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 sys_kill 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. |
CLONE_NEWNS |
Start the child in a new namespace.
Every process lives in a namespace. The namespace of a process is the data (the set of mounts) describing the file hierarchy as seen by that process. After a sys_fork or sys_clone where the CLONE_NEWNS flag is not set, the child lives in the same namespace as the parent. The system calls sys_mount and sys_umount change the names- pace 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 sys_clone where the 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 may specify the CLONE_NEWNS flag. It is not permitted to specify both CLONE_NEWNS and CLONE_FS in the same clone call. |
CLONE_SYSVSEM |
If set, then the child and the calling process share a single list of System V semaphore undo values. If this flag is not set, then the child has a separate undo list, which is initially empty.
|
CLONE_SETTLS |
The value pointed by esi is the new TLS (Thread Local Storage) descriptor. (See sys_set_thread_area.) |
CLONE_PARENT_SETTID |
Store child thread ID at location poined by edx in parent and child memory. |
CLONE_CHILD_CLEARTID |
Erase child thread ID at location pointed by edi 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 sys_set_tid_address system call. This is used by threading libraries. |
CLONE_DETACHED |
*to be documented* |
CLONE_UNTRACED |
If specified, then a tracing process cannot force CLONE_PTRACE on this child process.
|
CLONE_CHILD_SETTID |
Store child thread ID at location pointed by edi in child memory. |
CLONE_STOPPED |
If set, then the child is initially stopped (as though it was sent a SIGSTOP signal), and must be resumed by sending it a SIGCONT signal. |
|
|
ecx |
Pointer to a top of a new stack space for the clone. |
edx |
This parameter is depends on particular flags set in ebx and ignored otherwise. |
esi |
This parameter is depends on particular flags set in ebx and ignored otherwise. |
edi |
This parameter is depends on particular flags set in ebx and ignored otherwise. |
Return values
If the system call succeeds the return value is 0.
If the system call fails the return value is one of the following errno values:
-EAGAIN |
Too many processes are already running. |
-EINVAL |
CLONE_SIGHAND was specified, but CLONE_VM was not.
-or-
CLONE_THREAD was specified, but CLONE_SIGHAND was not.
-or-
Precisely one of CLONE_DETACHED and CLONE_THREAD was specified.
-or-
Both CLONE_FS and CLONE_NEWNS were specified in flags.
-or-
Returned by sys_clone when a zero value is specified for child stack address. |
-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. |
-EPERM |
CLONE_NEWNS was specified by a non-root process (process without CAP_SYS_ADMIN). |
-EPERM |
CLONE_PID was specified by a process other than process 0. |
|
Remarks
n/a
Compatibility
n/a |