Re: DOCUMENTATION Re: [PATCH] Add FUTEX_CMP_REQUEUE futex op

[Jakub Jelinek <jakub@redhat.com>]

On Fri, May 28, 2004 at 03:09:35PM +0200, bert hubert wrote:
> > > It's a bit of a shame that you need to be a rocket scientist to 
> > > understand the futex syscall interface.  Bert, are you still maintaining
> > > the manpage?  If so, is there enough info here to update it?
> > 
> > The latest futex(2) or futex(4) manpage I saw doesn't mention FUTEX_REQUEUE
> > at all.
> 
> Now fixed, please see http://ds9a.nl/futex-manpages - but please realise I'm
> somewhat out of my depth. Comments welcome.
> 
> Futexes have mutated into complicated things, I wonder if this was the last
> of the changes needed.
> 
> The big change in the manpages is the addition of FUTEX_REQUEUE and
> FUTEX_CMP_REQUEUE. Furthermore, I realised that the futex system call does
> not return EAGAIN etc, it returns -EAGAIN. I guesstimated that CMP_REQUEUE

futex behaves like most of the other syscalls, i.e. on error returns -1
and sets errno to the error value, like EAGAIN, EFAULT etc.
This is done in a userland wrapper around the syscall, how the kernel tells
userland an error happened and what errno value should be set is an
architecture specific implementation detail.
The man pages in the 2nd section document the behaviour of the userland
wrappers (see e.g. read(2)), not what the kernel actually returns.

> Ulrich, does/will glibc provide a futex(2) function? Or should people just
> call the syscall themselves? 

glibc doesn't provide a futex(2) function, so at least ATM people can use
#include <sys/syscall.h>
syscall (SYS_futex, &futex, FUTEX_xyz, ...) or come up with their own
assembly to invoke the syscall.

	Jakub