From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/3591 Path: news.gmane.org!not-for-mail From: Rob Landley Newsgroups: gmane.linux.lib.musl.general Subject: Re: Re: Linux manpages (was Re: [musl] Request for volunteers) Date: Tue, 09 Jul 2013 11:42:49 -0500 Message-ID: <1373388169.27613.31@driftwood> References: <51DB56CD.6050306@gmail.com> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; DelSp=Yes; Format=Flowed Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1373388191 29604 80.91.229.3 (9 Jul 2013 16:43:11 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 9 Jul 2013 16:43:11 +0000 (UTC) Cc: Rich Felker , musl@lists.openwall.com, "Michael Kerrisk (man-pages)" To: musl@lists.openwall.com Original-X-From: musl-return-3595-gllmg-musl=m.gmane.org@lists.openwall.com Tue Jul 09 18:43:09 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 1Uwb0P-0006Jm-Jb for gllmg-musl@plane.gmane.org; Tue, 09 Jul 2013 18:43:09 +0200 Original-Received: (qmail 25875 invoked by uid 550); 9 Jul 2013 16:43:07 -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 25857 invoked from network); 9 Jul 2013 16:43:05 -0000 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=date:from:subject:to:cc:in-reply-to:x-mailer:message-id :mime-version:content-type:content-disposition :content-transfer-encoding:x-gm-message-state; bh=wE5dZACWcaJkzVSqkT7ubR26d5MIyjvWEzNStjlPht8=; b=LDgUcLZ2wS4s5wPTvsR05EAAg6TsDY/aADDmaj3PQLhEIedpPWoQRM0knCeUxATwZ7 VRBFNs5qSUvZGgqdNW2U/7kPkhjWVyD+OgoTrojADgYK9jemYGO7RjsxZJR+8nwvT0KI zBBaTPpNVXShTMVeI1ZximJt3S2qE6O6pszS6AcQFXxe7SiUmWhjAZ5WGbS730U3ZXVC BUCa5IeOwL2Xr53EjenK3oy566cQ7mWBI3jTyd3wusxoRwIwaHY3Nkn+dOIidNun0MPg k5xvYjP1qFefv3zi8T5P7n9VLu4IPHEOn1krLRWxeXWp6Im9ONgyYSyEJjuobVunnD7R Ss9g== X-Received: by 10.236.5.142 with SMTP id 14mr15545431yhl.207.1373388173488; Tue, 09 Jul 2013 09:42:53 -0700 (PDT) In-Reply-To: <51DB56CD.6050306@gmail.com> (from mtk.manpages@gmail.com on Mon Jul 8 19:18:21 2013) X-Mailer: Balsa 2.4.11 Content-Disposition: inline X-Gm-Message-State: ALoCoQnoKIkByGNlcpPcrHoiI/lSwZNj75sz06kUmXdK+ec6sEjquixpmIWgt23BGfOYp0u6klxz Xref: news.gmane.org gmane.linux.lib.musl.general:3591 Archived-At: 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 =20 > 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 >=20 > ("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 =20 array of longs, with each processor's bit living at: int x =3D 255 & (mask[cpu/sizeof(long)] >> (8*(cpu&(sizeof(long)-1)))); I know this because I implemented taskset against the raw system call, =20 and read kernel code until I found the obscure corner where this is =20 actually documented, namely: arch/powerpc/include/asm/bitops.h (And yes, _only_ described in that architecture, not in any of the =20 others. Go figure.) (The toybox project is not a GNU program, and does not #define =20 GNU_DAMMIT to access extra magic header bits. Where necessary, it =20 provides its own header definitions.) > > the syscall is insufficient to provide POSIX semantics, which are =20 > left > > to userspace to provide. Such section 2 pages could then have > > corresponding section 3 pages that document the library behavior. >=20 > See =20 > 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 =20 in the "deviant glibc-specific perversions" section? Syscall wrappers in Section 2 make sense, it _is_ a syscall, and most =20 wrappers should be NOPs. The objection is not documenting what the =20 actual syscall does (when you can call it via syscall(), or get the raw =20 behavior when using klibc). Rob=