From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/3592 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: Tue, 9 Jul 2013 12:50:41 -0400 Message-ID: <20130709165041.GT29800@brightrain.aerifal.cx> References: <51DB56CD.6050306@gmail.com> <1373388169.27613.31@driftwood> 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 1373388654 2959 80.91.229.3 (9 Jul 2013 16:50:54 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 9 Jul 2013 16:50:54 +0000 (UTC) Cc: "Michael Kerrisk (man-pages)" To: musl@lists.openwall.com Original-X-From: musl-return-3596-gllmg-musl=m.gmane.org@lists.openwall.com Tue Jul 09 18:50:56 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 1Uwb7v-0005OS-IH for gllmg-musl@plane.gmane.org; Tue, 09 Jul 2013 18:50:55 +0200 Original-Received: (qmail 1332 invoked by uid 550); 9 Jul 2013 16:50:55 -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 32766 invoked from network); 9 Jul 2013 16:50:54 -0000 Content-Disposition: inline In-Reply-To: <1373388169.27613.31@driftwood> User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:3592 Archived-At: 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