clone(2) should be clone(3)

Hi Michael,

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

Quoted 4 lines · Peter Schiffer

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

Quoted 8 lines

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

The general tendency is to document all system calls in section 2, and if there are some differences caused by wrapper functions, then they are noted on the page.

I admint that clone(2) is an unusual case. The signature given at the top of the page is for the wrapper (and later the difference to the syscall raw interface are described). However, the details are primarily about the underlying kernel interface, so I'm inclined to leave the page where it is.

Quoted 18 lines · On Sunday 07 April 2013 06:15:18 Michael Kerrisk (man-pages) wrote:

Quoted 4 lines · Peter Schiffer

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

Quoted 8 lines

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

The general tendency is to document all system calls in section 2, and if there are some differences caused by wrapper functions, then they are noted on the page.

Quoted 5 lines

I admint that clone(2) is an unusual case. The signature given at the top of the page is for the wrapper (and later the difference to the syscall raw interface are described). However, the details are primarily about the underlying kernel interface, so I'm inclined to leave the page where it is.

i think his point is that the syscall doesn't take a func pointer. it is userspace (the C lib) that takes care of making the clone syscall and then calling the function. the man page doesn't mention this anywhere that i see.

the notes section does refer to this as being a "system call" instead of a "system call wrapper" when discussing ia64.

also, the quoted syscall signature isn't the whole story. there's actually more variants:
#ifdef __ARCH_WANT_SYS_CLONE
#ifdef CONFIG_CLONE_BACKWARDS
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int, tls_val,
int __user *, child_tidptr)
#elif defined(CONFIG_CLONE_BACKWARDS2)
SYSCALL_DEFINE5(clone, unsigned long, newsp, unsigned long, clone_flags,
int __user *, parent_tidptr,

int __user *, child_tidptr,
int, tls_val)
#else
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)
...

these arches don't define __ARCH_WANT_SYS_CLONE:
blackfin ia64 m68k sparc

and i gave up enumerating all the other edge cases :)

Quoted 11 lines · Mike Frysinger

also, the quoted syscall signature isn't the whole story. there's actually more variants:
#ifdef __ARCH_WANT_SYS_CLONE
#ifdef CONFIG_CLONE_BACKWARDS
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int, tls_val,
int __user *, child_tidptr)
#elif defined(CONFIG_CLONE_BACKWARDS2) SYSCALL_DEFINE5(clone, unsigned long, newsp, unsigned long, clone_flags,
int __user *, parent_tidptr,

Quoted 8 lines

int __user *, child_tidptr,
int, tls_val)
#else
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)
...

I've worked in some of the above detail; see the Git copy of the page.

Quoted 2 lines

these arches don't define __ARCH_WANT_SYS_CLONE:
blackfin ia64 m68k sparc

I'm not sure of the significance of the above; can you explain?

Quoted 26 lines · On Tuesday 16 April 2013 01:42:56 Michael Kerrisk (man-pages) wrote:

Quoted 11 lines · Mike Frysinger

also, the quoted syscall signature isn't the whole story. there's actually more variants:
#ifdef __ARCH_WANT_SYS_CLONE
#ifdef CONFIG_CLONE_BACKWARDS
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int, tls_val,
int __user *, child_tidptr)
#elif defined(CONFIG_CLONE_BACKWARDS2) SYSCALL_DEFINE5(clone, unsigned long, newsp, unsigned long, clone_flags,
int __user *, parent_tidptr,

Quoted 8 lines

int __user *, child_tidptr,
int, tls_val)
#else
SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)
...

I've worked in some of the above detail; see the Git copy of the page.

Quoted 2 lines

these arches don't define __ARCH_WANT_SYS_CLONE:
blackfin ia64 m68k sparc

Quoted 1 line

I'm not sure of the significance of the above; can you explain?

the three clone variants i posted above are bracketed by the define __ARCH_WANT_SYS_CLONE. so if the arch doesn't define that, it means it has its own implementation of clone() in its arch/$ARCH/ tree, so the exact prototype has to be tracked down from there.

Hi Peter,

Quoted 6 lines · Peter Schiffer

Hi Michael,

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

Quoted 8 lines

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

The general tendency is to document all system calls in section 2, and if there are some differences caused by wrapper functions, then they are noted on the page.

I admint that clone(2) is an unusual case. The signature given at the top of the page is for the wrapper (and later the difference to the syscall raw interface are described). However, the details are primarily about the underlying kernel interface, so I'm inclined to leave the page where it is.

My aim here is, that when I'm opening man page in section 2, the first thing I'm expecting to see is syscall signature. In clone(2), it's not even clear that this is a library call.

Quoted 3 lines · On Tuesday 09 April 2013 14:08:18 Peter Schiffer wrote:

My aim here is, that when I'm opening man page in section 2, the first thing I'm expecting to see is syscall signature. In clone(2), it's not even clear that this is a library call.

err, the very first sentence of the first paragraph says it's exactly this:
clone() creates a new process, in a manner similar to fork(2). It is actually a library function layered on top of the underlying clone() system call, hereinafter referred to as sys_clone. A description of sys_clone is given toward the end of this page.
-mike

Hello Michael,

Quoted 26 lines · Michael Kerrisk (man-pages)

Hi Peter,

Quoted 7 lines · Peter Schiffer

Hi Michael,

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

Quoted 8 lines

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

The general tendency is to document all system calls in section 2, and if there are some differences caused by wrapper functions, then they are noted on the page.

Quoted 6 lines

I admint that clone(2) is an unusual case. The signature given at the top of the page is for the wrapper (and later the difference to the syscall raw interface are described). However, the details are primarily about the underlying kernel interface, so I'm inclined to leave the page where it is.

Ah, I see now. So, basically there are 2 problems:
* it's not clear that in the synopsis is library call
* system call is buried down in the page

Would it be viable to somehow have both signatures in the synopsis?

(I've checked some random man pages in section 2, but didn't find anything similar..)

My aim here is, that when I'm opening man page in section 2, the first thing I'm expecting to see is syscall signature. In clone(2), it's not even clear that this is a library call.

Hi Peter,

Quoted 37 lines · Peter Schiffer

Hello Michael,

Quoted 26 lines · Michael Kerrisk (man-pages)

Hi Peter,

Quoted 7 lines · Peter Schiffer

Hi Michael,

it looks like the clone(2) man page is describing glibc implementation and not the system call. So I guess it should be moved to the section 3 and a new man page for clone(2) syscall should be created in section 2.

Quoted 8 lines

The clone(2) syscall is defined like this:

SYSCALL_DEFINE5(clone, unsigned long, clone_flags, unsigned long, newsp,
int __user *, parent_tidptr,
int __user *, child_tidptr,
int, tls_val)

(I'm sorry, but I don't have a patch this time.)

The general tendency is to document all system calls in section 2, and if there are some differences caused by wrapper functions, then they are noted on the page.

Quoted 6 lines

I admint that clone(2) is an unusual case. The signature given at the top of the page is for the wrapper (and later the difference to the syscall raw interface are described). However, the details are primarily about the underlying kernel interface, so I'm inclined to leave the page where it is.

Quoted 5 lines

Ah, I see now. So, basically there are 2 problems:
* it's not clear that in the synopsis is library call
* system call is buried down in the page

Would it be viable to somehow have both signatures in the synopsis?

Yes; done.

Quoted 2 lines

(I've checked some random man pages in section 2, but didn't find anything similar..)

Like I said, the clone(2) page is a bit different from most ;-).

Quoted 3 lines

My aim here is, that when I'm opening man page in section 2, the first thing I'm expecting to see is syscall signature. In clone(2), it's not even clear that this is a library call.

Fair enough.

You can find the revised page in the upstream Git.

Thanks,

Michael