From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/3561 Path: news.gmane.org!not-for-mail From: Rich Felker Newsgroups: gmane.linux.lib.musl.general Subject: Re: Re: Linux manpages (was Re: [musl] Request for volunteers) Date: Sat, 6 Jul 2013 20:03:24 -0400 Message-ID: <20130707000324.GU29800@brightrain.aerifal.cx> References: <20130701174411.GA1631@gauss> <20130706215227.GC26987@newbook> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1373155435 10530 80.91.229.3 (7 Jul 2013 00:03:55 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 7 Jul 2013 00:03:55 +0000 (UTC) Cc: "Michael Kerrisk (man-pages)" To: musl@lists.openwall.com Original-X-From: musl-return-3565-gllmg-musl=m.gmane.org@lists.openwall.com Sun Jul 07 02:03:57 2013 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1UvcSJ-0003mH-9U for gllmg-musl@plane.gmane.org; Sun, 07 Jul 2013 02:03:55 +0200 Original-Received: (qmail 15993 invoked by uid 550); 7 Jul 2013 00:03:53 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 15836 invoked from network); 7 Jul 2013 00:03:37 -0000 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:3561 Archived-At: 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