linux-kernel - Re: futex(2) man page update help request

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <1400100977.3865.30.camel@buesod1.americas.hpqcorp.net>
Date:	Wed, 14 May 2014 13:56:17 -0700
From:	Davidlohr Bueso <davidlohr@...com>
To:	mtk.manpages@...il.com
Cc:	Darren Hart <dvhart@...ux.intel.com>,
	Thomas Gleixner <tglx@...utronix.de>,
	Ingo Molnar <mingo@...e.hu>, Jakub Jelinek <jakub@...hat.com>,
	"linux-man@...r.kernel.org" <linux-man@...r.kernel.org>,
	lkml <linux-kernel@...r.kernel.org>,
	Davidlohr Bueso <davidlohr.bueso@...com>,
	Arnd Bergmann <arnd@...db.de>,
	Steven Rostedt <rostedt@...dmis.org>,
	Peter Zijlstra <peterz@...radead.org>,
	Linux API <linux-api@...r.kernel.org>,
	Carlos O'Donell <carlos@...hat.com>
Subject: Re: futex(2) man page update help request

On Wed, 2014-05-14 at 21:03 +0200, Michael Kerrisk (man-pages) wrote:
> Hi Darren,
> 
> On Wed, May 14, 2014 at 6:18 PM, Darren Hart <dvhart@...ux.intel.com> wrote:
> > On 5/14/14, 3:35, "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
> > wrote:
> >
> >>[So, some futex recent discussions remind me I should make this request]
> >>
> >>Hello all (especially those in the To:, namely Thomas, Darren, Ingo,
> >>Jakub),
> >>
> >>The futex man pages:
> >>http://man7.org/linux/man-pages/man2/futex.2.html
> >>http://man7.org/linux/man-pages/man7/futex.7.html
> >>are currently in a sorry state. I'm by no means convinced that all of the
> >>futex operations described there are explained fully and correctly. And
> >>probably not all error cases for each operation are properly documented.
> >>I'd be very happy if some folk could review those pages and send me
> >>corrections (Git:
> >>http://git.kernel.org/pub/scm/docs/man-pages/man-pages).
> >>
> >>But worse, a number of futex operations remain undocumented in futex(2)
> >>(see the list below).
> >>
> >>I am aware of Documentation/pi-futex.txt and
> >>Documentation/futex-requeue-pi.txt. However, both of those documents
> >>are rather thin on details / explain what certain FUTEX_* operations are
> >>used for rather than what they do / focus on the implementation, rather
> >>than the semantics.
> >>
> >>What I would like is that the futex(2) page documenta each one of
> >>these operations with a focus on the semantics in a way that might be
> >>useful to writers of library functions or those who simply wish to
> >>better understand (from a user-space perspective) what futexes are
> >>and how they are used. However, I don't have the knowledge to do
> >>this well in any reasonable time.
> >>
> >>Would the folk in the To: list (or anyone else who is knowledgeable)
> >>be willing to write patches
> >>(Git: http://git.kernel.org/pub/scm/docs/man-pages/man-pages )
> >>or just supply me with some raw text that documents these currently
> >>undocumented futex operations, in the manner suggested?
> >
> > Yes, I'll be glad to help.
> 
> Thanks!
> 
> > However, unless I'm sorely mistaken, the larger problem is that glibc
> > removed the futex() call entirely, so these man pages don't describe
> 
> I don't think futex() ever was in glibc--that's by design, and
> completely understandable: no user-space application would want to
> directly use futex(). 

That's actually not quite true. There are plenty of software efforts out
there that use futex calls directly to implement userspace serialization
mechanisms as an alternative to the bulky sysv semaphores. I worked
closely with an in-memory DB project that makes heavy use of them. Not
everyone can simply rely on pthreads.

> (BTW, I mispoke in my earlier mail when I said I
> wanted documentation suitable for "writers of library functions" -- I
> meant suitable for "writers of *C library*".)

While kind of beyond the scope of documentation like manpages, I would
very much welcome this! The internet is full of
misleading/false/stupid/incomplete references to futexes and how to use
them. Having a best practises helps the kernel directly avoiding users
from misusing them.

Thanks,
Davidlohr


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/