Bug 118241
| Summary: | clone(2) gives wrong prototype for raw system call | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Ruslan (b7.10110111) |
| Component: | man-pages | Assignee: | documentation_man-pages (documentation_man-pages) |
| Status: | RESOLVED CODE_FIX | ||
| Severity: | normal | CC: | mtk.manpages |
| Priority: | P1 | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Kernel Version: | Subsystem: | ||
| Regression: | No | Bisected commit-id: | |
man-pages-4.08 made many changes to this page, especially to improve the discussion of the system call prototype. I believe these changes include addressing this report (see patch below), so am closing this report. Please reopen if you still see a problem. Cheers, Michael diff --git a/man2/clone.2 b/man2/clone.2 index ed60cf6..0aeed5b 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -51,14 +51,10 @@ clone, __clone2 \- create a child process .BI "int clone(int (*" "fn" ")(void *), void *" child_stack , .BI " int " flags ", void *" "arg" ", ... " -.BI " /* pid_t *" ptid ", struct user_desc *" tls \ +.BI " /* pid_t *" ptid ", void *" newtls \ ", pid_t *" ctid " */ );" -/* Prototype for the raw system call */ - -.BI "long clone(unsigned long " flags ", void *" child_stack , -.BI " void *" ptid ", void *" ctid , -.BI " struct pt_regs *" regs ); +/* For the prototype of the raw system call, see NOTES */ .fi .SH DESCRIPTION .BR clone () @@ -192,14 +188,15 @@ If 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. +Note, however, +that the duplicated file descriptors in the child refer to the same open file +descriptions as the corresponding file descriptors in the calling process, +and thus share file offsets and files status flags (see +.BR open (2)). .TP .BR CLONE_FS " (since Linux 2.0)" If @@ -543,11 +540,25 @@ then trace the child also (see .BR ptrace (2)). .TP .BR CLONE_SETTLS " (since Linux 2.5.32)" -The +The TLS (Thread Local Storage) descriptor is set to +.I newtls. + +The interpretation of +.I newtls +and the resulting effect is architecture dependent. +On x86, .I newtls -argument is the new TLS (Thread Local Storage) descriptor. +is interpreted as a +.IR "struct user_desc *" (See -.BR set_thread_area (2).) +.BR set_thread_area (2)). +On x86_64 it is the new value to be set for the %fs base register +(See the +.I ARCH_SET_FS +argument to +.BR arch_prctl (2)). +On architectures with a dedicated TLS register, it is the new value +of that register. .TP .BR CLONE_SIGHAND " (since Linux 2.0)" If @@ -806,16 +817,58 @@ arguments of the .BR clone () wrapper function are omitted. Furthermore, the argument order changes. -The raw system call interface on x86 and many other architectures is roughly: +In addition, there are variations across architectures. + +The raw system call interface on x86-64 and some other architectures +(including sh, tile, and alpha) is roughly: + .in +4 .nf +.BI "long clone(unsigned long " flags ", void *" child_stack , +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); +.fi +.in +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: + +.in +4 +.nf .BI "long clone(unsigned long " flags ", void *" child_stack , -.BI " void *" ptid ", void *" ctid , -.BI " struct pt_regs *" regs ); +.BI " int *" ptid ", unsigned long " newtls , +.BI " int *" ctid ); +.fi +.in + +On the cris and s390 architectures, +.\" CONFIG_CLONE_BACKWARDS2 +the order of the first two arguments is reversed: + +.in +4 +.nf +.BI "long clone(void *" child_stack ", unsigned long " flags , +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); +.fi +.in + +On the microblaze architecture, +.\" CONFIG_CLONE_BACKWARDS3 +an additional argument is supplied: +.in +4 +.nf +.BI "long clone(unsigned long " flags ", void *" child_stack , +.BI " int " stack_size , "\fR /* Size of stack */" +.BI " int *" ptid ", int *" ctid , +.BI " unsigned long " newtls ); .fi .in + Another difference for the raw system call is that the .I child_stack argument may be zero, in which case copy-on-write semantics ensure that the @@ -824,15 +877,11 @@ the stack. In this case, for correct operation, the .B CLONE_VM option should not be specified. - -For some architectures, the order of the arguments for the system call -differs from that shown above. -On the score, microblaze, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, -and MIPS architectures, -the order of the fourth and fifth arguments is reversed. -On the cris and s390 architectures, -the order of the first and second arguments is reversed. +.\" .SS blackfin, m68k, and sparc +.\" Mike Frysinger noted in a 2013 mail: +.\" these arches don't define __ARCH_WANT_SYS_CLONE: +.\" blackfin ia64 m68k sparc The argument-passing conventions on blackfin, m68k, and sparc are different from the descriptions above. For details, see the kernel (and glibc) source. @@ -951,10 +1000,13 @@ were specified in .IR flags . .TP .B EINVAL -Returned by +Returned by the glibc .BR clone () -when a zero value is specified for -.IR child_stack . +wrapper function when +.IR fn +or +.IR child_stack +is specified as NULL. .TP .B EINVAL .BR CLONE_NEWIPC @@ -1033,6 +1085,11 @@ and the caller is in a chroot environment (i.e., the caller's root directory does not match the root directory of the mount namespace in which it resides). .TP +.BR ERESTARTNOINTR " (since Linux 2.6.17)" +.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 +System call was interrupted by a signal and will be restarted. +(This can be seen only during a trace.) +.TP .BR EUSERS " (since Linux 3.11)" .B CLONE_NEWUSER was specified in @@ -1041,11 +1098,6 @@ and the call would cause the limit on the number of nested user namespaces to be exceeded. See .BR user_namespaces (7). -.TP -.BR ERESTARTNOINTR " (since Linux 2.6.17)" -.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 -System call was interrupted by a signal and will be restarted. -(This can be seen only during a trace.) .SH VERSIONS There is no entry for .BR clone () @@ -1058,6 +1110,12 @@ as described in this manual page. is Linux-specific and should not be used in programs intended to be portable. .SH NOTES +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. + In the kernel 2.4.x series, .B CLONE_THREAD generally does not make the parent of the new thread the same @@ -1072,8 +1130,7 @@ 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 +In Linux 2.6.2, the need to give this flag together with .B CLONE_THREAD disappeared. This flag is still defined, but has no effect. |
clone(2) man gives the following prototype for the raw system call: long clone(unsigned long flags, void *child_stack, void *ptid, void *ctid, struct pt_regs *regs); But actual kernel never seems to take `struct pt_regs* regs` as an argument. Instead it takes `struct user_desc* tls`. See the definitions of clone in kernel/fork.c. None of the #if branches have anything resembling `struct pt_regs`, but all do have `tls`. You can see another evidence of this in arch/x86/entry/entry_64_compat.S: * The 32-bit clone ABI is: clone(..., int tls_val, int *child_tidptr). * The 64-bit clone ABI is: clone(..., int *child_tidptr, int tls_val).