From: Rich Felker <dalias@aerifal.cx>
To: musl@lists.openwall.com
Cc: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Subject: Re: Re: Linux manpages (was Re: [musl] Request for volunteers)
Date: Mon, 8 Jul 2013 22:53:30 -0400 [thread overview]
Message-ID: <20130709025329.GM29800@brightrain.aerifal.cx> (raw)
In-Reply-To: <51DB56CD.6050306@gmail.com>
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
next prev parent reply other threads:[~2013-07-09 2:53 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-07-01 17:44 Request for volunteers Felix Janda
2013-07-02 1:08 ` Michael Kerrisk (man-pages)
2013-07-06 21:52 ` Linux manpages (was Re: [musl] Request for volunteers) Isaac
2013-07-06 22:12 ` Michael Kerrisk (man-pages)
2013-07-06 23:04 ` Justin Cormack
2013-07-07 0:03 ` Rich Felker
2013-07-09 0:18 ` Michael Kerrisk
2013-07-09 2:36 ` Kurt H Maier
2013-07-09 2:53 ` Rich Felker [this message]
2013-07-09 5:28 ` Michael Kerrisk (man-pages)
2013-07-10 19:39 ` Rob Landley
2013-07-09 16:42 ` Rob Landley
2013-07-09 16:50 ` Rich Felker
2013-07-26 19:20 ` status of POSIX man pages? (was: " Isaac
2013-09-06 12:23 ` Re: status of POSIX man pages? John Spencer
2013-09-08 6:05 ` Michael Kerrisk (man-pages)
2013-09-09 4:44 ` John Spencer
2013-09-09 5:29 ` Anthony J. Bentley
2013-09-09 5:40 ` Daniel Cegiełka
2013-09-19 2:58 ` Rob Landley
2013-09-19 9:54 ` John Spencer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20130709025329.GM29800@brightrain.aerifal.cx \
--to=dalias@aerifal.cx \
--cc=mtk.manpages@gmail.com \
--cc=musl@lists.openwall.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/musl/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).