Re: Request for volunteers

Re: Request for volunteers

[Felix Janda]

Hello,

Rich Felker wrote:
> > >What might be better for the near future is to get the POSIX man pages
> > >project updated to match POSIX-2008+TC1 so that users of musl who want
> > >man pages for libc functions can install them and have them match the
> > >current version.
> > 
> > I note that the guy who did the posix man pages ten years ago was:
> > Michael Kerrisk.
>
> Maybe someone should contact him about all the stuff we're discussing.

I asked him some time ago about the posix man pages and offered help with the
conversion.

He has interest in creating new posix man pages for the SUSV4 TC1. The status
from beginning of June was that he had contacted The Open Group asking for
permission. Possibly, we might get troff sources.

(He also told me that the conversion for the previous posix man pages were done
before he had become their maintainer.)

I CC'ed him so that he knows about this discussion.


Felix

Re: Request for volunteers

[Michael Kerrisk (man-pages)]

Gidday,

On Mon, Jul 1, 2013 at 7:44 PM, Felix Janda <felix.janda@posteo.de> wrote:
> Hello,
>
> Rich Felker wrote:
>> > >What might be better for the near future is to get the POSIX man pages
>> > >project updated to match POSIX-2008+TC1 so that users of musl who want
>> > >man pages for libc functions can install them and have them match the
>> > >current version.
>> >
>> > I note that the guy who did the posix man pages ten years ago was:
>> > Michael Kerrisk.

(To be more precise, it was Andries Brouwer, the previous maintainer,
who carried out the task shortly before I took over.)

>> Maybe someone should contact him about all the stuff we're discussing.
>
> I asked him some time ago about the posix man pages and offered help with the
> conversion.
>
> He has interest in creating new posix man pages for the SUSV4 TC1. The status
> from beginning of June was that he had contacted The Open Group asking for
> permission. Possibly, we might get troff sources.

As of a few days ago, the necessary permissions are granted. I do not
yet have the source files (and so am unsure of the source format), but
I expect that they will become available to us in the next couple of
weeks.

> (He also told me that the conversion for the previous posix man pages were done
> before he had become their maintainer.)
>
> I CC'ed him so that he knows about this discussion.

Thank you, Felix.

Cheers,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Linux manpages (was Re: [musl] Request for volunteers)

[Isaac]

Hello,
On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages) wrote:
> Gidday,
> 
> On Mon, Jul 1, 2013 at 7:44 PM, Felix Janda <felix.janda@posteo.de> wrote:
> > Hello,
> >
> > Rich Felker wrote:

> >> Maybe someone should contact him about all the stuff we're discussing.
> >
> > I asked him some time ago about the posix man pages and offered help with the
> > conversion.
> >
> > He has interest in creating new posix man pages for the SUSV4 TC1. The status
> > from beginning of June was that he had contacted The Open Group asking for
> > permission. Possibly, we might get troff sources.
> 
> As of a few days ago, the necessary permissions are granted. I do not
> yet have the source files (and so am unsure of the source format), but
> I expect that they will become available to us in the next couple of
> weeks.
 
On a slightly related note, would you be interested in patches for the
Linux manpages briefly documenting places where musl differs from glibc
(in the NOTES section, along the same lines as the notes about libc4/libc5)?

> Cheers,
> 
> Michael

Thanks,
Isaac Dunham

Re: Linux manpages (was Re: [musl] Request for volunteers)

[Michael Kerrisk (man-pages)]

Hello Isaac,

On Sat, Jul 6, 2013 at 11:52 PM, Isaac <idunham@lavabit.com> wrote:
> Hello,
> On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages) wrote:
>> Gidday,
>>
>> On Mon, Jul 1, 2013 at 7:44 PM, Felix Janda <felix.janda@posteo.de> wrote:
>> > Hello,
>> >
>> > Rich Felker wrote:
>
>> >> Maybe someone should contact him about all the stuff we're discussing.
>> >
>> > I asked him some time ago about the posix man pages and offered help with the
>> > conversion.
>> >
>> > He has interest in creating new posix man pages for the SUSV4 TC1. The status
>> > from beginning of June was that he had contacted The Open Group asking for
>> > permission. Possibly, we might get troff sources.
>>
>> As of a few days ago, the necessary permissions are granted. I do not
>> yet have the source files (and so am unsure of the source format), but
>> I expect that they will become available to us in the next couple of
>> weeks.
>
> On a slightly related note, would you be interested in patches for the
> Linux manpages briefly documenting places where musl differs from glibc
> (in the NOTES section, along the same lines as the notes about libc4/libc5)?

Historically, man-pages has primarily documented glibc + syscalls, but
there's nothing firm about that. It's more been about limited time
resources and the fact that glibc is the most widely used libc. I'd
have no objection to musl-specific notes in the man-pages. Perhaps a
patch to libc(7) would be a good place to start.

Cheers,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Justin Cormack]

[-- Attachment #1: Type: text/plain, Size: 1995 bytes --]

On 6 Jul 2013 23:12, "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
wrote:
>
> Hello Isaac,
>
> On Sat, Jul 6, 2013 at 11:52 PM, Isaac <idunham@lavabit.com> wrote:
> > Hello,
> > On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages)
wrote:
> >> Gidday,
> >>
> >> On Mon, Jul 1, 2013 at 7:44 PM, Felix Janda <felix.janda@posteo.de>
wrote:
> >> > Hello,
> >> >
> >> > Rich Felker wrote:
> >
> >> >> Maybe someone should contact him about all the stuff we're
discussing.
> >> >
> >> > I asked him some time ago about the posix man pages and offered help
with the
> >> > conversion.
> >> >
> >> > He has interest in creating new posix man pages for the SUSV4 TC1.
The status
> >> > from beginning of June was that he had contacted The Open Group
asking for
> >> > permission. Possibly, we might get troff sources.
> >>
> >> As of a few days ago, the necessary permissions are granted. I do not
> >> yet have the source files (and so am unsure of the source format), but
> >> I expect that they will become available to us in the next couple of
> >> weeks.
> >
> > On a slightly related note, would you be interested in patches for the
> > Linux manpages briefly documenting places where musl differs from glibc
> > (in the NOTES section, along the same lines as the notes about
libc4/libc5)?
>
> Historically, man-pages has primarily documented glibc + syscalls, but
> there's nothing firm about that. It's more been about limited time
> resources and the fact that glibc is the most widely used libc. I'd
> have no objection to musl-specific notes in the man-pages. Perhaps a
> patch to libc(7) would be a good place to start.

The man(2) section is rather glibc specific and makes the syscall details
rather subsidiary. I will try to send some patches if these would be
welcome.

Justin

> Cheers,
>
> Michael
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Author of "The Linux Programming Interface"; http://man7.org/tlpi/

[-- Attachment #2: Type: text/html, Size: 2825 bytes --]

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rich Felker]

On Sun, Jul 07, 2013 at 12:04:04AM +0100, Justin Cormack wrote:
> > > On a slightly related note, would you be interested in patches for the
> > > Linux manpages briefly documenting places where musl differs from glibc
> > > (in the NOTES section, along the same lines as the notes about
> libc4/libc5)?
> >
> > Historically, man-pages has primarily documented glibc + syscalls, but
> > there's nothing firm about that. It's more been about limited time
> > resources and the fact that glibc is the most widely used libc. I'd
> > have no objection to musl-specific notes in the man-pages. Perhaps a
> > patch to libc(7) would be a good place to start.

I'm not sure how much effort would be involved. My ideal outcome would
be for the man pages to evolve to document what applications can
_portably_ expect from the interfaces, with appropriate notes on
caveats where certain libc versions or kernel versions give you
less-than-conforming behavior, and where nonstandard extensions are
available. However my feeling is that this would be a very big project
and I'm not sure if Michael would want to go in that direction. I do
think it would greatly improve the quality of Linux software
development, though.

> The man(2) section is rather glibc specific and makes the syscall details
> rather subsidiary. I will try to send some patches if these would be
> welcome.

I think it's an error to have anything glibc-specific in section 2 of
the manual, which should be documenting the kernel, not userspace.
What would be useful in the section 2 man pages is to document where
the syscall is insufficient to provide POSIX semantics, which are left
to userspace to provide. Such section 2 pages could then have
corresponding section 3 pages that document the library behavior.

Rich

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Michael Kerrisk]

Rich,

On 07/07/13 02:03, Rich Felker wrote:
> On Sun, Jul 07, 2013 at 12:04:04AM +0100, Justin Cormack wrote:
>>>> On a slightly related note, would you be interested in patches for the
>>>> Linux manpages briefly documenting places where musl differs from glibc
>>>> (in the NOTES section, along the same lines as the notes about
>> libc4/libc5)?
>>>
>>> Historically, man-pages has primarily documented glibc + syscalls, but
>>> there's nothing firm about that. It's more been about limited time
>>> resources and the fact that glibc is the most widely used libc. I'd
>>> have no objection to musl-specific notes in the man-pages. Perhaps a
>>> patch to libc(7) would be a good place to start.
> 
> I'm not sure how much effort would be involved. My ideal outcome would
> be for the man pages to evolve to document what applications can
> _portably_ expect from the interfaces, 

This is what the man pages endeavor to do. (I consider cases where 
non-portable behavior is not clearly indicated to be bugs.)

> with appropriate notes on
> caveats where certain libc versions or kernel versions give you
> less-than-conforming behavior, and where nonstandard extensions are
> available. 

That's more or less what the pages do, with the proviso that "certain
libc versions" currently means just glibc, and in a few odd cases, 
ancient Linux libc.

> However my feeling is that this would be a very big project
> and I'm not sure if Michael would want to go in that direction. I do
> think it would greatly improve the quality of Linux software
> development, though.
> 
>> The man(2) section is rather glibc specific and makes the syscall details
>> rather subsidiary. I will try to send some patches if these would be
>> welcome.
> 
> I think it's an error to have anything glibc-specific in section 2 of
> the manual, which should be documenting the kernel, not userspace.
> What would be useful in the section 2 man pages is to document where

("useful" to who? Few users care about the naked 
syscall behavior.)

> the syscall is insufficient to provide POSIX semantics, which are left
> to userspace to provide. Such section 2 pages could then have
> corresponding section 3 pages that document the library behavior.

See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
I think it would be a retrograde step to split syscall pages into 
Sections 2 and 3. Users want to get the documentation in one place.
Note that the approach in man-pages (consolidating info on the syscall 
plus any libc additions in one page) is not unique to Linux. From some
(offlist) discussions with the BSD man pages maintainers, it appears
that at least some (all?) of the BSDs do the same. 

Cheers,

Michael

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Kurt H Maier]

On Tue, Jul 09, 2013 at 02:18:21AM +0200, Michael Kerrisk wrote:
> ("useful" to who? Few users care about the naked 
> syscall behavior.)

If they don't care about syscall behavior, what are they doing reading
section 2?

khm

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rich Felker]

On Tue, Jul 09, 2013 at 02:18:21AM +0200, Michael Kerrisk wrote:
> > However my feeling is that this would be a very big project
> > and I'm not sure if Michael would want to go in that direction. I do
> > think it would greatly improve the quality of Linux software
> > development, though.
> > 
> >> The man(2) section is rather glibc specific and makes the syscall details
> >> rather subsidiary. I will try to send some patches if these would be
> >> welcome.
> > 
> > I think it's an error to have anything glibc-specific in section 2 of
> > the manual, which should be documenting the kernel, not userspace.
> > What would be useful in the section 2 man pages is to document where
> 
> ("useful" to who? Few users care about the naked 
> syscall behavior.)

Admittedly, part of the answer is "to me". However I can think of a
good number of others:

1. Anyone doing pure asm programming on Linux. I think this is a
   rather bad idea, but there are people who do it.

2. People reading strace output. (For instance, if the kernel returns
   a bogus error code and userspace has to translate it, that's
   relevant to someone who sees the strace output and errno value in
   their program mismatching.)

3. Implementors of any component that uses or provides the syscall.
   That includes not only libc, but also qemu app-level emulation, BSD
   Linux-syscall ABI emulation, Zvi's psxcalls layer (intended to
   eventually allow using musl as the first-ever conforming Windows
   libc that's actually deployable, unlike cygwin), ...

4. Anyone trying to understand what libc (musl, glibc, or otherwise)
   is doing munging the syscall inputs/results.

5. Kernel developers who want to know the actual contract their
   interfaces are supposed to satisfy and preserve.

I suspect there are others, but those are the ones that came to mind
right off.

> > the syscall is insufficient to provide POSIX semantics, which are left
> > to userspace to provide. Such section 2 pages could then have
> > corresponding section 3 pages that document the library behavior.
> 
> See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
> I think it would be a retrograde step to split syscall pages into 
> Sections 2 and 3.

Yes, that's understandable. I somewhat question why we even still have
a "section 2" in the manual, though...

Rich

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Michael Kerrisk (man-pages)]

Rich,

On Tue, Jul 9, 2013 at 4:53 AM, Rich Felker <dalias@aerifal.cx> wrote:
> On Tue, Jul 09, 2013 at 02:18:21AM +0200, Michael Kerrisk wrote:
>> > However my feeling is that this would be a very big project
>> > and I'm not sure if Michael would want to go in that direction. I do
>> > think it would greatly improve the quality of Linux software
>> > development, though.
>> >
>> >> The man(2) section is rather glibc specific and makes the syscall details
>> >> rather subsidiary. I will try to send some patches if these would be
>> >> welcome.
>> >
>> > I think it's an error to have anything glibc-specific in section 2 of
>> > the manual, which should be documenting the kernel, not userspace.
>> > What would be useful in the section 2 man pages is to document where
>>
>> ("useful" to who? Few users care about the naked
>> syscall behavior.)
>
> Admittedly, part of the answer is "to me". However I can think of a
> good number of others:
>
> 1. Anyone doing pure asm programming on Linux. I think this is a
>    rather bad idea, but there are people who do it.
>
> 2. People reading strace output. (For instance, if the kernel returns
>    a bogus error code and userspace has to translate it, that's
>    relevant to someone who sees the strace output and errno value in
>    their program mismatching.)
>
> 3. Implementors of any component that uses or provides the syscall.
>    That includes not only libc, but also qemu app-level emulation, BSD
>    Linux-syscall ABI emulation, Zvi's psxcalls layer (intended to
>    eventually allow using musl as the first-ever conforming Windows
>    libc that's actually deployable, unlike cygwin), ...
>
> 4. Anyone trying to understand what libc (musl, glibc, or otherwise)
>    is doing munging the syscall inputs/results.
>
> 5. Kernel developers who want to know the actual contract their
>    interfaces are supposed to satisfy and preserve.
>
> I suspect there are others, but those are the ones that came to mind
> right off.

That's a good, comprehensive list of valid, important users of course.
What I was meaning to say was that that set of users is a small subset
of the total users of the man pages. But, in any case, the goal is
also to satisfy those users by including notes about the bare syscalls
inside the pages.

>> > the syscall is insufficient to provide POSIX semantics, which are left
>> > to userspace to provide. Such section 2 pages could then have
>> > corresponding section 3 pages that document the library behavior.
>>
>> See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
>> I think it would be a retrograde step to split syscall pages into
>> Sections 2 and 3.
>
> Yes, that's understandable. I somewhat question why we even still have
> a "section 2" in the manual, though...

Well then, you'll be amused to hear that the discussion with the BSD
maintainers was about whether FreeBSD (and others) should simply merge
Sections 2 and 3. I can see arguments in favor of it, but they're not
(to my mind) compelling. See one piece from the thread below.

Cheers,

Michael




---------- Forwarded message ----------
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, Jun 10, 2013 at 11:14 AM
Subject: Re: Merging man page sections 2 and 3?
To: Matthew Dempsky <matthew@dempsky.org>
Cc: mckusick@mckusick.com, wiz@netbsd.org, Michael Kerrisk-manpages
<mtk.manpages@gmail.com>, schwarze@openbsd.org, Jason McIntyre
<jmc@openbsd.org>, Philip Guenther <guenther@openbsd.org>


Hello Matthew,

Thanks for including the Linux man-pages project in this discussion. I
appreciate that.

On 06/06/13 23:39, Matthew Dempsky wrote:
> Hello fellow OS man page maintainers!
>
> Within OpenBSD, I started a discussion recently about sections 2 and
> 3, and whether it makes sense to continue keeping them separate.

(Do you have a pointer to the archive of that discussion?)

> The
> biggest concern raised against merging them is being gratuitously
> different from other OSes and how it would affect Xr entries in
> third-party manuals, so I was curious in knowing how other OSes feel
> about this.
>
> My view is the distinction between "system call" and "library call" is
> very blurred nowadays,

I can certainly find some reasons to agree with you on that. I'm
assuming that the BSDs will be similar to Linux, where there are
various fuzzy cases. for example, we have system calls that have very
simple wrappers, "system calls" (e.g., getpid() where glibc actually
caches the result of the call, bypassing the system call itself in
most cases--yes, it is a sad, stupid idea, but so it is), system
calls that have rather thicker wrappers in libc, and  multiplexed
syscalls (e.g., on x86-32, one system call, socketcall() provides the
functionality of all the BSD sockets APIs--this came about because of
the history of how the APIs were added to the kernel, long ago). And,
as you noted in response to Kirk, there are cases where library functions
are more expensive than syscalls.

> and it doesn't make sense to continue putting
> them in different sections.  Certainly there's merit to documenting
> the userland<->kernel interface somehow (e.g., because it's exposed
> via syscall() and strace/ktrace and other tools), but I think that
> could be better achieved other ways.  E.g., Linux man-pages has
> syscalls.2 that lists all of the system calls and when they were
> added, and some of the man pages like stat.2 have implementation notes
> describing how glibc implements it using one of a few different actual
> system calls depending on the kernel.
>
> Do any of your respective projects have clear and unambiguous
> guidelines for which section a function should be documented in?  Do
> you think your users benefit from having function documentation split
> across two sections?

The decision for this is somewhat ad hoc on Linux. If there's
an underyling kernel interface, the documentation tends to end
up in a .2 page. But the line is fuzzy. The POSIX message queue
pages, for example, are in Section 3--even though they in part
document underlying system calls--because there are significant
parts that are in libc. On the other hand, Section 2 pages often
include documentation not just of the raw syscall interface, but
the pieces that glibc API adds on top. For example, the select.2
page includes this text:

   Linux Notes
       The Linux pselect() system call modifies its timeout  argument.
       However,  the  glibc  wrapper  function  hides this behavior by
       using a local variable for the timeout argument that is  passed
       to  the  system  call.  Thus, the glibc pselect() function does
       not modify its timeout argument; this is the behavior  required
       by POSIX.1-2001.

There are many other cases similar to that one. The following FAQ
addresses a point tangentially related to this:
https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source

> Assuming not, how feasible would it be for your project to move its
> manual pages from section 2 into section 3?  Are there reasons you
> could not or would not make that change?

Even if I thought it was a good idea, the biggest impediment would simply
be the effort (for me) and churn (for third part xrefs) that such a
change would cause. Without looking too closely, it's not clear to
me that the change would be just be some simple scripting.

> Certainly there's a significant initial effort to reorganize things,
> but I expect that to be a one-time cost largely solvable by sed.
> Also, third party manual pages might have inaccurate Xr entries
> initially, but overtime I expect upstream projects to adapt and we'll
> end up with more accurate cross-references everywhere.  (And in the
> interim, it's possible to workaround this by having "man 2 foo" also
> search section 3 or something.)
>
> For what it's worth, I did a quick non-scientific scan of the ~2000
> packages installed on my OpenBSD machine, and found only ~1% of the
> man pages contained cross-references to section 2 (which also included
> hilarious mistakes like "Xr strcat 2").  I'd be very interested if
> others tried to reproduce this experiment on different package sets
> and got differing results.
>
> Anyway, if you haven't had a knee-jerk "but that's how we've always
> done it!" reaction, I'm very interested in your thoughts on the
> matter. :)

So, I don't have a knee-jerk reaction ;-). I agree that the current
situation (at least on Linux, and I guess elsewhere) is imperfect.
Things are not nearly so clear cut as the .2/.3 distinction implies.
That said, I'm inclined to leave things be, for several reasons:

* Users expect the distinction. (This is not a compelling
  argument, I agree.)
* Making the change requires time and effort, and my time is
  sadly limited.
* The syscall / lib function distinction does (as you note) need to
  be made clear somehow. The current set up does that moderately
  (but not perfectly) well on Linux.
* I see no compelling reason to make the change you suggest (you
  didn't really make the case at the start of your mail).

Best regards,

Michael

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rob Landley]

On 07/08/2013 07:18:21 PM, Michael Kerrisk wrote:
> Rich,
> > I think it's an error to have anything glibc-specific in section 2  
> of
> > the manual, which should be documenting the kernel, not userspace.
> > What would be useful in the section 2 man pages is to document where
> 
> ("useful" to who? Few users care about the naked
> syscall behavior.)

We exist. :)

Speaking of which the data blob sent to sched_{get,set}affinity() is an  
array of longs, with each processor's bit living at:

   int x = 255 & (mask[cpu/sizeof(long)] >> (8*(cpu&(sizeof(long)-1))));

I know this because I implemented taskset against the raw system call,  
and read kernel code until I found the obscure corner where this is  
actually documented, namely:

   arch/powerpc/include/asm/bitops.h

(And yes, _only_ described in that architecture, not in any of the  
others. Go figure.)

(The toybox project is not a GNU program, and does not #define  
GNU_DAMMIT to access extra magic header bits. Where necessary, it  
provides its own header definitions.)

> > the syscall is insufficient to provide POSIX semantics, which are  
> left
> > to userspace to provide. Such section 2 pages could then have
> > corresponding section 3 pages that document the library behavior.
> 
> See  
> https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
> I think it would be a retrograde step to split syscall pages into
> Sections 2 and 3. Users want to get the documentation in one place.
> Note that the approach in man-pages (consolidating info on the syscall
> plus any libc additions in one page) is not unique to Linux. From some
> (offlist) discussions with the BSD man pages maintainers, it appears
> that at least some (all?) of the BSDs do the same.

Document what the syscall does, and then have wrapper behavior listed  
in the "deviant glibc-specific perversions" section?

Syscall wrappers in Section 2 make sense, it _is_ a syscall, and most  
wrappers should be NOPs. The objection is not documenting what the  
actual syscall does (when you can call it via syscall(), or get the raw  
behavior when using klibc).

Rob

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rich Felker]

On Tue, Jul 09, 2013 at 11:42:49AM -0500, Rob Landley wrote:
> >See https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
> >I think it would be a retrograde step to split syscall pages into
> >Sections 2 and 3. Users want to get the documentation in one place.
> >Note that the approach in man-pages (consolidating info on the syscall
> >plus any libc additions in one page) is not unique to Linux. From some
> >(offlist) discussions with the BSD man pages maintainers, it appears
> >that at least some (all?) of the BSDs do the same.
> 
> Document what the syscall does, and then have wrapper behavior
> listed in the "deviant glibc-specific perversions" section?

Usually the difference between sections 2 and 3 is not "deviant
glibc-specific perversions" but "workarounds for kernel bugs that
won't be fixed because of the policy of maintaining stable syscall
API/ABI".

> Syscall wrappers in Section 2 make sense, it _is_ a syscall, and
> most wrappers should be NOPs.

None of the ones that are cancellation points can be pure wrappers. If
nothing else, they must handle cancellation. That covers a big chunk
already.

> The objection is not documenting what
> the actual syscall does (when you can call it via syscall(), or get
> the raw behavior when using klibc).

I agree it would be useful to have this information, but with limited
resources and the issue of confusing developers who get section 2 by
default then have to look again in section 3 for the man page they
actually wanted, I can see where it's probably preferable to maintain
the status quo, leaving the 2/3 split based on the historical
expectation of whether the function was a "syscall" or "library
function", and documenting Linux syscall deviations from the public
interface as part of the combined man page.

Rich

Re: Re: Linux manpages (was Re: [musl] Request for volunteers)

[Rob Landley]

On 07/09/2013 12:28:17 AM, Michael Kerrisk (man-pages) wrote:
> >> > the syscall is insufficient to provide POSIX semantics, which  
> are left
> >> > to userspace to provide. Such section 2 pages could then have
> >> > corresponding section 3 pages that document the library behavior.
> >>
> >> See  
> https://www.kernel.org/doc/man-pages/todo.html#migrate_to_kernel_source
> >> I think it would be a retrograde step to split syscall pages into
> >> Sections 2 and 3.

I note that I'm nominally the kernel Documentation maintainer. If you'd  
like a Documentation/syscall directory handed over to you in  
MAINTAINERS, I can do that. (Or Documentation/DocBook/syscall, up to  
you...)

(I don't do nearly enough with it due to lack of time, and because  
every patch series in the world has a documentation bit I get cc'd on  
and How am _I_ supposed to judge the correct locking requirements for a  
Heterodyne Death Ray so half the time I just go "You need a comma in  
'Fools I shall destroy you all!'" and then ack it. Still eats up the  
time I have to devote to that topic, most weeks.)

At some point I'd like to completely reorganize that directory so (for  
example) all the architecture directories are under "arch". But this  
involves me setting up a git tree somewhere I can upload to and send  
pull requests about, and that's just icky enough to stay well below the  
surface of my todo list...

> > Yes, that's understandable. I somewhat question why we even still  
> have
> > a "section 2" in the manual, though...
> 
> Well then, you'll be amused to hear that the discussion with the BSD
> maintainers was about whether FreeBSD (and others) should simply merge
> Sections 2 and 3. I can see arguments in favor of it, but they're not
> (to my mind) compelling. See one piece from the thread below.

A system call is a different thing than a library call, even in libc.  
The fact glibc gets them confused is a problem with glibc.

In theory there is a "clean upstream" system call set in posix, and a  
"clean upstream" libc call set in c99 and/or posix. (In practice  
there's noting like subscribing to the austin group mailing list to  
rapidly erode your faith in the upcoming Posix standard. The sausage is  
made of people! And they're _INSANE_.)

Rob

Re: status of POSIX man pages? (was: [musl] Request for volunteers)

[Isaac]

On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages) wrote:
> Gidday,
> 
> On Mon, Jul 1, 2013 at 7:44 PM, Felix Janda <felix.janda@posteo.de> wrote:
> > Hello,
> >
> > Rich Felker wrote:
> >> > >What might be better for the near future is to get the POSIX man pages
> >> > >project updated to match POSIX-2008+TC1 so that users of musl who want
> >> > >man pages for libc functions can install them and have them match the
> >> > >current version.
> >> >
> >> > I note that the guy who did the posix man pages ten years ago was:
> >> > Michael Kerrisk.
> 
> (To be more precise, it was Andries Brouwer, the previous maintainer,
> who carried out the task shortly before I took over.)
> 
<snip>
> > He has interest in creating new posix man pages for the SUSV4 TC1. The status
> > from beginning of June was that he had contacted The Open Group asking for
> > permission. Possibly, we might get troff sources.
> 
> As of a few days ago, the necessary permissions are granted. I do not
> yet have the source files (and so am unsure of the source format), but
> I expect that they will become available to us in the next couple of
> weeks.
 
I'm curious what the status of this is. Do you have the sources yet?

(BTW, if you haven't got them yet, I noticed these:
http://austingroupbugs.net/view.php?id=694
http://austingroupbugs.net/view.php?id=715
and a few others that refer to use of groff with the mm macros.)

> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: Re: status of POSIX man pages?

[John Spencer]

On 07/26/2013 09:20 PM, Isaac wrote:
> On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages) wrote:
>> As of a few days ago, the necessary permissions are granted. I do not
>> yet have the source files (and so am unsure of the source format), but
>> I expect that they will become available to us in the next couple of
>> weeks.
>
> I'm curious what the status of this is. Do you have the sources yet?
>

i am very interested in a status update as well.
getting the posix 2008 manpages into my distro is a todo item since a 
long time
https://github.com/rofl0r/sabotage/issues/34

regards,
--JS

Re: Re: status of POSIX man pages?

[Michael Kerrisk (man-pages)]

On Fri, Sep 6, 2013 at 2:23 PM, John Spencer <maillist-musl@barfooze.de> wrote:
> On 07/26/2013 09:20 PM, Isaac wrote:
>>
>> On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages)
>> wrote:
>>>
>>> As of a few days ago, the necessary permissions are granted. I do not
>>> yet have the source files (and so am unsure of the source format), but
>>> I expect that they will become available to us in the next couple of
>>> weeks.
>>
>>
>> I'm curious what the status of this is. Do you have the sources yet?
>>
>
> i am very interested in a status update as well.
> getting the posix 2008 manpages into my distro is a todo item since a long
> time
> https://github.com/rofl0r/sabotage/issues/34

A while back we got permission from the IEEE and The Open Group to use
the POSIX.1-2013 pages (==POSIX.1-2008 + Technical Corrigendum 1,
published 2013).

However, the source text that has been provided to us needs massaging
in a number of ways before it can be published as a set of standalone
pages. Felix Janda kindly offered to take on that task, and has been
making very good progress. I expect that in a week or two, we'll have
a set of pages for public review (to see if there are any remaining
bugs in the "massaging process" that Felix or I did not spot).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: Re: status of POSIX man pages?

[John Spencer]

On 09/08/2013 08:05 AM, Michael Kerrisk (man-pages) wrote:
> On Fri, Sep 6, 2013 at 2:23 PM, John Spencer<maillist-musl@barfooze.de>  wrote:
>> On 07/26/2013 09:20 PM, Isaac wrote:
>>>
>>> On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages)
>>> wrote:
>>>>
>>>> As of a few days ago, the necessary permissions are granted. I do not
>>>> yet have the source files (and so am unsure of the source format), but
>>>> I expect that they will become available to us in the next couple of
>>>> weeks.
>>>
>>>
>>> I'm curious what the status of this is. Do you have the sources yet?
>>>
>>
>> i am very interested in a status update as well.
>> getting the posix 2008 manpages into my distro is a todo item since a long
>> time
>> https://github.com/rofl0r/sabotage/issues/34
>
> A while back we got permission from the IEEE and The Open Group to use
> the POSIX.1-2013 pages (==POSIX.1-2008 + Technical Corrigendum 1,
> published 2013).
>
> However, the source text that has been provided to us needs massaging
> in a number of ways before it can be published as a set of standalone
> pages. Felix Janda kindly offered to take on that task, and has been
> making very good progress. I expect that in a week or two, we'll have
> a set of pages for public review (to see if there are any remaining
> bugs in the "massaging process" that Felix or I did not spot).
>

that's very good news.
btw, i am currently writing (or improving) a non-bloated man 
implementation: https://raw.github.com/rofl0r/hardcore-utils/master/man.c .
in the process i noted that the posix manpages from 2003 make use of 
some groff features like the tbl preprocessor (a hideous hack to display 
html-like tables in a completely unidiomatic way), for example in man 1p 
printf.
those features are not supported by any traditional *roff 
implementation, so i wonder if the next iteration of the posix manpages 
could stick to the basic nroff function set to improve compatibility...


regards,
--JS

Re: Re: status of POSIX man pages?

[Anthony J. Bentley]

John Spencer writes:
> On 09/08/2013 08:05 AM, Michael Kerrisk (man-pages) wrote:
> > On Fri, Sep 6, 2013 at 2:23 PM, John Spencer<maillist-musl@barfooze.de>  wr
> ote:
> >> On 07/26/2013 09:20 PM, Isaac wrote:
> >>>
> >>> On Tue, Jul 02, 2013 at 03:08:52AM +0200, Michael Kerrisk (man-pages)
> >>> wrote:
> >>>>
> >>>> As of a few days ago, the necessary permissions are granted. I do not
> >>>> yet have the source files (and so am unsure of the source format), but
> >>>> I expect that they will become available to us in the next couple of
> >>>> weeks.
> >>>
> >>>
> >>> I'm curious what the status of this is. Do you have the sources yet?
> >>>
> >>
> >> i am very interested in a status update as well.
> >> getting the posix 2008 manpages into my distro is a todo item since a long
> >> time
> >> https://github.com/rofl0r/sabotage/issues/34
> >
> > A while back we got permission from the IEEE and The Open Group to use
> > the POSIX.1-2013 pages (==POSIX.1-2008 + Technical Corrigendum 1,
> > published 2013).
> >
> > However, the source text that has been provided to us needs massaging
> > in a number of ways before it can be published as a set of standalone
> > pages. Felix Janda kindly offered to take on that task, and has been
> > making very good progress. I expect that in a week or two, we'll have
> > a set of pages for public review (to see if there are any remaining
> > bugs in the "massaging process" that Felix or I did not spot).
> >
> 
> that's very good news.
> btw, i am currently writing (or improving) a non-bloated man 
> implementation: https://raw.github.com/rofl0r/hardcore-utils/master/man.c .

Along those lines is mandoc, which is not a full troff implementation but
does support tbl, man, and mdoc. Used as the default man in several BSDs
and Minix. Also supports output to html (actually its original purpose).

http://mdocml.bsd.lv/

-- 
Anthony J. Bentley

Re: Re: status of POSIX man pages?

[Daniel Cegiełka]

2013/9/9 Anthony J. Bentley <anthony@cathet.us>:

> Along those lines is mandoc, which is not a full troff implementation but
> does support tbl, man, and mdoc. Used as the default man in several BSDs
> and Minix. Also supports output to html (actually its original purpose).
>
> http://mdocml.bsd.lv/

I use mandoc with musl and works great (very elegant solution and
worth recommendation).

Daniel

Re: Re: status of POSIX man pages?

[Rob Landley]

On 09/09/2013 12:40:49 AM, Daniel Cegiełka wrote:
> 2013/9/9 Anthony J. Bentley <anthony@cathet.us>:
> 
> > Along those lines is mandoc, which is not a full troff  
> implementation but
> > does support tbl, man, and mdoc. Used as the default man in several  
> BSDs
> > and Minix. Also supports output to html (actually its original  
> purpose).
> >
> > http://mdocml.bsd.lv/
> 
> I use mandoc with musl and works great (very elegant solution and
> worth recommendation).

I don't see this listed on the wiki page of other lightweight packages?

Rob

Re: Re: status of POSIX man pages?

[John Spencer]

On 09/19/2013 04:58 AM, Rob Landley wrote:
> On 09/09/2013 12:40:49 AM, Daniel Cegiełka wrote:
>> 2013/9/9 Anthony J. Bentley <anthony@cathet.us>:
>>
>> > Along those lines is mandoc, which is not a full troff
>> implementation but
>> > does support tbl, man, and mdoc. Used as the default man in several
>> BSDs
>> > and Minix. Also supports output to html (actually its original
>> purpose).
>> >
>> > http://mdocml.bsd.lv/
>>
>> I use mandoc with musl and works great (very elegant solution and
>> worth recommendation).
>
> I don't see this listed on the wiki page of other lightweight packages?

added.
btw, you have a wiki account as well, don't you ? (rhetoric question, no 
answer expected)