diff options
Diffstat (limited to 'man2/clone.2')
| -rw-r--r-- | man2/clone.2 | 127 |
1 files changed, 66 insertions, 61 deletions
diff --git a/man2/clone.2 b/man2/clone.2 index 38d2b90..69e4547 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -38,7 +38,7 @@ .\" 2008-11-19, mtk, document CLONE_NEWIPC .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO .\" -.TH clone 2 2023-05-03 "Linux man-pages 6.05.01" +.TH clone 2 2024-02-18 "Linux man-pages 6.7" .SH NAME clone, __clone2, clone3 \- create a child process .SH LIBRARY @@ -47,27 +47,27 @@ Standard C library .SH SYNOPSIS .nf /* Prototype for the glibc wrapper function */ -.PP +.P .B #define _GNU_SOURCE .B #include <sched.h> -.PP +.P .BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \ ", int " flags , .BI " void *_Nullable " "arg" ", ..." \ " \fR/*\fP" " pid_t *_Nullable " parent_tid , .BI " void *_Nullable " tls , .BI " pid_t *_Nullable " child_tid " \fR*/\fP );" -.PP +.P /* For the prototype of the raw clone() system call, see NOTES */ -.PP +.P .BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */" .BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR clone3 (), @@ -77,7 +77,7 @@ necessitating the use of These system calls create a new ("child") process, in a manner similar to .BR fork (2). -.PP +.P By contrast with .BR fork (2), these system calls provide more precise control over what pieces of execution @@ -88,7 +88,7 @@ the table of file descriptors, and the table of signal handlers. These system calls also allow the new child process to be placed in separate .BR namespaces (7). -.PP +.P Note that in this manual page, "calling process" normally corresponds to "parent process". But see the descriptions of @@ -96,7 +96,7 @@ But see the descriptions of and .B CLONE_THREAD below. -.PP +.P This page describes the following interfaces: .IP \[bu] 3 The glibc @@ -109,9 +109,9 @@ are described toward the end of this page. The newer .BR clone3 () system call. -.PP +.P In the remainder of this page, the terminology "the clone call" is used -when noting details that apply to all of these interfaces, +when noting details that apply to all of these interfaces. .\" .SS The clone() wrapper function When the child process is created with the @@ -129,7 +129,7 @@ The .I arg argument is passed as the argument of the function .IR fn . -.PP +.P When the .IR fn ( arg ) function returns, the child process terminates. @@ -139,7 +139,7 @@ is the exit status for the child process. The child process may also terminate explicitly by calling .BR exit (2) or after receiving a fatal signal. -.PP +.P The .I stack argument specifies the location of the stack used by the child process. @@ -159,7 +159,7 @@ Note that .BR clone () does not provide a means whereby the caller can inform the kernel of the size of the stack area. -.PP +.P The remaining arguments to .BR clone () are discussed below. @@ -174,20 +174,20 @@ It also provides a number of API improvements, including: space for additional flags bits; cleaner separation in the use of various arguments; and the ability to specify the size of the child's stack area. -.PP +.P As with .BR fork (2), .BR clone3 () returns in both the parent and the child. It returns 0 in the child process and returns the PID of the child in the parent. -.PP +.P The .I cl_args argument of .BR clone3 () is a structure of the following form: -.PP +.P .in +4n .EX struct clone_args { @@ -212,7 +212,7 @@ struct clone_args { }; .EE .in -.PP +.P The .I size argument that is supplied to @@ -223,7 +223,7 @@ should be initialized to the size of this structure. argument permits future extensions to the .I clone_args structure.) -.PP +.P The stack for the child process is specified via .IR cl_args.stack , which points to the lowest byte of the stack area, @@ -237,7 +237,7 @@ and specified. Otherwise, these two fields can be specified as NULL and 0, which causes the child to use the same stack area as the parent (in the child's own virtual address space). -.PP +.P The remaining fields in the .I cl_args argument are discussed below. @@ -253,7 +253,7 @@ structure shown above. This structure allows for a superset of the information passed via the .BR clone () arguments. -.PP +.P The following table shows the equivalence between the arguments of .BR clone () and the fields in the @@ -322,7 +322,7 @@ then the first element in the array has to be the desired PID and .I set_tid_size needs to be 1. -.PP +.P If the PID of the newly created process should have a certain value in multiple PID namespaces, then the .I set_tid @@ -335,7 +335,7 @@ The number of PID namespaces in which a PID should be set is defined by .I set_tid_size which cannot be larger than the number of currently nested PID namespaces. -.PP +.P To create a process with the following PIDs in a PID namespace hierarchy: .RS 4 .TS @@ -347,9 +347,9 @@ PID NS level Requested PID Notes 2 7 Innermost PID namespace .TE .RE -.PP +.P Set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -358,10 +358,10 @@ set_tid[2] = 31496; set_tid_size = 3; .EE .in -.PP +.P If only the PIDs in the two innermost PID namespaces need to be specified, set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -369,10 +369,10 @@ set_tid[1] = 42; set_tid_size = 2; .EE .in -.PP +.P The PID in the PID namespaces outside the two innermost PID namespaces is selected the same way as any other PID is selected. -.PP +.P The .I set_tid feature requires @@ -383,7 +383,7 @@ or .\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 .B CAP_CHECKPOINT_RESTORE in all owning user namespaces of the target PID namespaces. -.PP +.P Callers may only choose a PID greater than 1 in a given PID namespace if an .B init @@ -410,7 +410,7 @@ field passed to referred to as the .I flags mask in the remainder of this page. -.PP +.P The .I flags mask is specified as a bitwise OR of zero or more of @@ -456,6 +456,8 @@ By default, signal dispositions in the child thread are the same as in the parent. If this flag is specified, then all signals that are handled in the parent +(and not set to +.BR SIG_IGN ) are reset to their default dispositions .RB ( SIG_DFL ) in the child. @@ -736,9 +738,7 @@ Only a privileged process can employ .BR CLONE_NEWPID . This flag can't be specified in conjunction with -.B CLONE_THREAD -or -.BR CLONE_PARENT . +.BR CLONE_THREAD . .TP .B CLONE_NEWUSER (This flag first became meaningful for @@ -1317,10 +1317,7 @@ were specified in the mask. .TP .B EINVAL -One (or both) of .B CLONE_NEWPID -or -.B CLONE_NEWUSER and one (or both) of .B CLONE_THREAD or @@ -1329,6 +1326,14 @@ were specified in the .I flags mask. .TP +.B EINVAL +.B CLONE_NEWUSER +and +.B CLONE_THREAD +were specified in the +.I flags +mask. +.TP .BR EINVAL " (since Linux 2.6.32)" .\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c .B CLONE_PARENT @@ -1444,7 +1449,7 @@ or was specified in the .I flags mask, but a signal was specified in -.I exit_signal. +.IR exit_signal . .TP .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" .I stack @@ -1568,7 +1573,7 @@ So, in cases where is used to recursively create children, do not use the buffer employed for the parent's stack as the stack of the child. -.PP +.P On i386, .BR clone () should not be called through vsyscall, but directly through @@ -1587,7 +1592,7 @@ and arguments of the .BR clone () wrapper function are omitted. -.PP +.P In contrast to the glibc wrapper, the raw .BR clone () system call accepts NULL as a @@ -1609,14 +1614,14 @@ the parent's memory because of the use of the .B CLONE_VM flag, then no copy-on-write duplication occurs and chaos is likely to result.) -.PP +.P The order of the arguments also differs in the raw system call, and there are variations in the arguments across architectures, as detailed in the following paragraphs. -.PP +.P The raw system call interface on x86-64 and some other architectures (including sh, tile, and alpha) is: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1624,13 +1629,13 @@ The raw system call interface on x86-64 and some other architectures .BI " unsigned long " tls ); .EE .in -.PP +.P On x86-32, and several other common architectures (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, and MIPS), .\" CONFIG_CLONE_BACKWARDS the order of the last two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1638,11 +1643,11 @@ the order of the last two arguments is reversed: .BI " int *" child_tid ); .EE .in -.PP +.P On the cris and s390 architectures, .\" CONFIG_CLONE_BACKWARDS2 the order of the first two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(void *" stack ", unsigned long " flags , @@ -1650,11 +1655,11 @@ the order of the first two arguments is reversed: .BI " unsigned long " tls ); .EE .in -.PP +.P On the microblaze architecture, .\" CONFIG_CLONE_BACKWARDS3 an additional argument is supplied: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1673,7 +1678,7 @@ blackfin, m68k, and sparc are different from the descriptions above. For details, see the kernel (and glibc) source. .SS ia64 On ia64, a different interface is used: -.PP +.P .in +4n .EX .BI "int __clone2(int (*" "fn" ")(void *)," @@ -1683,13 +1688,13 @@ On ia64, a different interface is used: .BI " pid_t *" child_tid " */ );" .EE .in -.PP +.P The prototype shown above is for the glibc wrapper function; for the system call itself, the prototype can be described as follows (it is identical to the .BR clone () prototype on microblaze): -.PP +.P .in +4n .EX .BI "long clone2(unsigned long " flags ", void *" stack_base , @@ -1698,7 +1703,7 @@ prototype on microblaze): .BI " unsigned long " tls ); .EE .in -.PP +.P .BR __clone2 () operates in the same way as .BR clone (), @@ -1731,7 +1736,7 @@ However, from Linux 2.4.7 to Linux 2.4.18 the flag implied the .B CLONE_PARENT flag (as in Linux 2.6.0 and later). -.PP +.P In Linux 2.4 and earlier, .BR clone () does not take arguments @@ -1740,16 +1745,16 @@ does not take arguments and .IR child_tid . .SH NOTES -One use of these systems calls +One use of these system calls is to implement threads: multiple flows of control in a program that run concurrently in a shared address space. -.PP +.P The .BR kcmp (2) system call can be used to test whether two processes share various resources such as a file descriptor table, System V semaphore undo operations, or a virtual address space. -.PP +.P Handlers registered using .BR pthread_atfork (3) are not executed during a clone call. @@ -1784,7 +1789,7 @@ The stale-cache problem also does not occur if the argument includes .BR CLONE_VM .) To get the truth, it was sometimes necessary to use code such as the following: -.PP +.P .in +4n .EX #include <syscall.h> @@ -1797,7 +1802,7 @@ mypid = syscall(SYS_getpid); .\" See also the following bug reports .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 -.PP +.P Because of the stale-cache problem, as well as other problems noted in .BR getpid (2), the PID caching feature was removed in glibc 2.25. @@ -1811,7 +1816,7 @@ making it possible to see that the hostname differs in the UTS namespaces of the parent and child. For an example of the use of this program, see .BR setns (2). -.PP +.P Within the sample program, we allocate the memory that is to be used for the child's stack using .BR mmap (2) |