Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Sat, 6 Jul 2013 20:03:24 -0400
From: Rich Felker <dalias@...ifal.cx>
To: musl@...ts.openwall.com
Cc: "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
Subject: Re: Re: Linux manpages (was Re: Request for volunteers)

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

Powered by blists - more mailing lists

Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.