Re: clone(2) should be clone(3)

[Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1: Type: Text/Plain, Size: 2418 bytes --]

On Sunday 07 April 2013 06:15:18 Michael Kerrisk (man-pages) wrote:
> On Fri, Apr 5, 2013 at 6:01 PM, Peter Schiffer wrote:
> > 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.)
> 
> 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.

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 :)
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]