clone(2) should be clone(3)

clone(2) should be clone(3)

[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.

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.)

peter
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

Hi Peter,


On Fri, Apr 5, 2013 at 6:01 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> 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.)

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.

Thanks,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

[-- 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 --]

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

[Peter Schiffer]

Hello Michael,

On 04/07/2013 12:15 PM, Michael Kerrisk (man-pages) wrote:
> Hi Peter,
>
> On Fri, Apr 5, 2013 at 6:01 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> 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.)
>
> 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.
>

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.

peter
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

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

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

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

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

[Peter Schiffer]

On 04/09/2013 08:11 PM, Mike Frysinger wrote:
> 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
>

Yeah, I know. But you have to read the description to know that.
Problem is, that if you are familiar with the call, you won't read the
description (for example, if you just forgot the signature).

Another real world example: we work with many experienced developers
used to other Unices, so, you can try to imagine how unfortunate for
them this can be.

Also, we are afraid that this doesn't have to complain with the Common
Criteria. Every syscall has to be documented, so when I'm looking for
the documentation of clone(2) syscall in the clone(2) man page, I'm
expecting that it will be the main topic in the page, and in the
synopsis.

I'm just trying to prevent possible misunderstandings, and if possible,
make the page little bit more clearer..

peter
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

Hi Peter,

On Tue, Apr 9, 2013 at 8:08 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> Hello Michael,
>
>
> On 04/07/2013 12:15 PM, Michael Kerrisk (man-pages) wrote:
>>
>> Hi Peter,
>>
>> On Fri, Apr 5, 2013 at 6:01 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> wrote:
>>>
>>> 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.)
>>
>>
>> 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.
>>
>
> 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.

> (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 ;-).

> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Michael Kerrisk (man-pages)]

On Sun, Apr 7, 2013 at 9:03 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> 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.

Yes, I've tried to claify this.

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

And I've also tried to clarify that.

> 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)
> ...

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

> 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?

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

Okay.

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mike Frysinger]

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

On Tuesday 16 April 2013 01:42:56 Michael Kerrisk (man-pages) wrote:
> On Sun, Apr 7, 2013 at 9:03 PM, Mike Frysinger wrote:
> > 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)
> > ...
> 
> I've worked in some of the above detail; see the Git copy of the page.
> 
> > 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?

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.
-mike

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

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

[Michael Kerrisk (man-pages)]

On Tue, Apr 16, 2013 at 5:37 PM, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Tuesday 16 April 2013 01:42:56 Michael Kerrisk (man-pages) wrote:
>> On Sun, Apr 7, 2013 at 9:03 PM, Mike Frysinger wrote:
>> > 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)
>> > ...
>>
>> I've worked in some of the above detail; see the Git copy of the page.
>>
>> > 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?
>
> 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.


Thanks Mike. I'll add a short subsection noting that these
architectures are different.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Peter Schiffer]

Hi Michael,

Revised man page looks great! Thanks.

peter

On 04/16/2013 07:27 AM, Michael Kerrisk (man-pages) wrote:
> Hi Peter,
>
> On Tue, Apr 9, 2013 at 8:08 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> Hello Michael,
>>
>>
>> On 04/07/2013 12:15 PM, Michael Kerrisk (man-pages) wrote:
>>>
>>> Hi Peter,
>>>
>>> On Fri, Apr 5, 2013 at 6:01 PM, Peter Schiffer <pschiffe-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> wrote:
>>>>
>>>> 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.)
>>>
>>>
>>> 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.
>>>
>>
>> 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.
>
>> (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 ;-).
>
>> 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
>

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html