Re: futex(2) man page update help request
From: Darren Hart
Date: Wed May 14 2014 - 15:59:11 EST
On 5/14/14, 12:03, "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx>
wrote:
>Hi Darren,
>
>On Wed, May 14, 2014 at 6:18 PM, Darren Hart <dvhart@xxxxxxxxxxxxxxx>
>wrote:
>> On 5/14/14, 3:35, "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx>
>> 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(). (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*".)
>
>> something users even have access to anymore. I had to revert to calling
>> the syscalls directly in the futextest test suite because of this:
>>
>>
>>http://git.kernel.org/cgit/linux/kernel/git/dvhart/futextest.git/tree/inc
>>lu
>> de/futextest.h#n67
>>
>>
>> Which basically defines:
>>
>> #define futex(uaddr, op, val, timeout, uaddr2, val3, opflags) \
>> syscall(SYS_futex, uaddr, op | opflags, val, timeout, uaddr2,
>>val3)
>>
>>
>> Adding Carlos for his perspective.
>>
>> If I'm wrong, or we can restore the futex() call, great. If not...
>>Should
>> we keep the man-pages and document it as syscall(SYS_futex, ..., op,
>>...) ?
>
>We should keep the man page ;-). I just need to add some words to
>point out the use of syscall(). Mostly though, I'm interested in
>getting documentation of the operations listed below :-).
OK, yes - because the following doesn't work:
#include <linux/futex.h>
#include <sys/time.h>
int futex(int *uaddr, int op, int val, const struct timespec
*timeout,
int *uaddr2, int val3);
It's going to be difficult for me to make the time to do this - but I do
want it done, so please don't hesitate to nag me.
Thanks,
>>> commit 4732efbeb997189d9f9b04708dc26bf8613ed721
>>> Author: Jakub Jelinek <jakub@xxxxxxxxxx>
>>> Date: Tue Sep 6 15:16:25 2005 -0700
>>> See also https://bugzilla.kernel.org/show_bug.cgi?id=14303
>>>
>>>2.6.18 adds priority inheritance support:
>>>FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI.
>>> commit c87e2837be82df479a6bae9f155c43516d2feebc
>>> Author: Ingo Molnar <mingo@xxxxxxx>
>>> Date: Tue Jun 27 02:54:58 2006 -0700
>>>
>>> commit e2970f2fb6950183a34e8545faa093eb49d186e1
>>> Author: Ingo Molnar <mingo@xxxxxxx>
>>> Date: Tue Jun 27 02:54:47 2006 -0700
>>>
>>> See Documentation/pi-futex.txt
>>>
>>>2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
>>> commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
>>> Author: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
>>> Date: Fri Feb 1 17:45:14 2008 +0100
>>>
>>>2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI
>>> commit 52400ba946759af28442dee6265c5c0180ac7122
>>> Author: Darren Hart <dvhltc@xxxxxxxxxx>
>>> Date: Fri Apr 3 13:40:49 2009 -0700
>>>
>>> commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358
>>> Author: Darren Hart <dvhltc@xxxxxxxxxx>
>>> Date: Mon Apr 20 22:22:22 2009 -0700
>>>
>>> See Documentation/futex-requeue-pi.txt
>>>
>>>Thanks,
>>>
>>>Michael
>>>
>>>
>>>--
>>>Michael Kerrisk
>>>Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>>>Linux/UNIX System Programming Training: http://man7.org/training/
>>>
>>
>>
>> --
>> Darren Hart Open Source Technology
>>Center
>> darren.hart@xxxxxxxxx Intel
>>Corporation
>>
>>
>>
>
>
>
>--
>Michael Kerrisk
>Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>Linux/UNIX System Programming Training: http://man7.org/training/
>
--
Darren Hart Open Source Technology Center
darren.hart@xxxxxxxxx Intel Corporation
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/