futex.2: ffix (ASCII art layout)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add ENOMEM case for FUTEX_CMP_REQUEUE_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add further details for FUTEX_CMP_REQUEUE_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Describe FUTEX_CMP_REQUEUE_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Note arguments ignored by FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srfix: FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Replace instances of EWOULDBLOCK by EAGAIN

On Linux, the two error numbers are the same. The kernel
code for futexes is somehwat inconsistent, using EAGAIN
in some places, and EWOULDBLOCK in others. Let's make the
manual page consistent at least.

This change requires reordering of one entry in ERRORS.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rework FUTEXT_TRYLOCK_PI text a litte + add FIXMEs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rework FUTEX_LOCK_PI text and add FIXMEs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Further tweaks to PI introductory text

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add more references to SEE ALSO

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rework Hart/Guniguntala text

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Integrate text from Darren Hart on PI Mutexes

From the 2009 Real-Time Linux Workshop paper
Requeue-PI: Making Glibc Condvars PI-Aware
Darren Hart, Dinakar Guniguntala
http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: Remove obsolete FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add subsection for PI futexes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Fix discussion of FUTEX_LOCK_PI 'timeout' argument

Reading futex_lock_pi(), it appears that the timeout is *not*
interpreted in the same way as for FUTEX_WAKE.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_WAKE_OP

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_WAIT_REQUEUE_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_CMP_REQUEUE_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_UNLOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_TRYLOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_LOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_WAKE_BITSET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add FUTEX_WAIT_BITSET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: mention FUTEX_WAKE_BITSET under FUTEX_WAIT

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Remove uneeded reference to ERRORS section

(The need to read ERRORS is implied.)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: RETURN VALUE: add placeholder for various operations

There are still several operations whose return value
is not yet described.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EPERM case for FUTEX_UNLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add ENOSYS case for FUTEX_UNLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EINVAL case for FUTEX_UNLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Document FUTEX_UNLOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rearrange order FUTEX_UNLOCK_PI in list of operations

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add ENOSYS case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: Add FIXME for the FUTEX_OWNER_DIED condition

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: Add FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EDEADLK case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: add FIXMEs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EAGAIN case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add ESRCH case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EPERM case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add EINVAL case for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: Add some FIXMEs for FUTEX_LOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ERRORS: Add ENOMEM for FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI

Reported-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Document FUTEX_LOCK_PI

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: SEE ALSO: add Documentation/{pi-futex.txt,futex-requeue-pi.txt}

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: add FIXMEs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: SEE ALSO: add get_robust_list(2)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Reorder operations list more or less chronologically

Since there are various sets of related futex operations
that were added at the same time, ordering the descriptions
of operations chronologically makes some sense. In the
meantime, though, keep all of the "PI" operations together.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add discussion of FUTEX_WAIT_BITSET/FUTEX_WAKE_BITSET "multiplexing"

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Enhance FUTEX_WAKE_BITSET text

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Document FUTEX_WAKE_BITSET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add description of FUTEX_WAIT_BITSET 'timeout' argument

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Document FUTEX_WAIT_BITSET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Consolidate EINVAL FUTEX_LOCK_PI errors

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Reword invalid timeout EINVAL case more generally

Several operations can produce this error, so reword
the text more generally.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: added FIXMES

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rewrite text of ETIMEDOUT to omit mention of FUTEX_WAIT

Several operations can employ timeouts, so word this error
more generally.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Reword EINVAL error for invalid 'uaddr'/ 'uaddr2' case

There's no need to list all of the various futex operations in
this error case. These arguments are used the same way by each
operation, so the text can be worded in a more general way.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.7: Note some other locking primitives that are built with futexes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Note the existence of the _PRIVATE constants for 'futex_op'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Expand FUTEX_FD description

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: note kernel commit that removed FUTEX_FD

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: add copyright notices

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: FUTEX_WAKE makes no guarantees about which waiters are awoken

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: FUTEX_WAIT_BITSET can also get EINTR error

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Add introductory paragraph describing 'timeout', 'uaddr2', and 'val3'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rewrite the intro paragraphs a little

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.7: Minor fix: futexes can also be shared between threads

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.7: Note that a futex is 4 bytes on all platforms

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Cut down discussion of FUTEX_REQUEUE; defer to FUTEX_CMP_REQUEUE

FUTEX_CMP_REQUEUE supercedes FUTEX_REQUEUE and provides a superset
of its functionality. There is need to duplicate any details in
the FUTEX_REQUEUE description, simple defer to the
FUTEX_CMP_REQUEUE and note the differences. This also guides the
reader to do the right thing: use FUTEX_CMP_REQUEUE rather than
FUTEX_REQUEUE.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Expand description of FUTEX_CMP_REQUEUE

With some help from "Futexes are tricky" bt Ulrich Drepper.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Warn that FUTEX_REQUEUE should be avoided in favor of FUTEX_CMP_REQUEUE

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Document FUTEX_WAKE_OP

Based on "Futexes are tricky" and some reading of the kernel
source.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: SEE ALSO: Add reference to "Futexes are tricky" by Ulrich Drepper

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Rename 'op' argument to 'futex_op'

This is a little more readable, and also helps avoid confusing
when talking about the 'op' subfield in the FUTEX_WAKE_OP
discussion.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: srcfix: add FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Elaborate on the operation of FUTEX_WAIT

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Remove duplicate EQWOULDBLOCK error

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Note that the CLOCK_MONOTONIC clock is used for relative timeouts

Verified from inspection of kernel/futex.c::futex_wait().

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Clarify that the FUTEX_WAIT timeout is relative

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

futex.2: Clarify which operations were available as at Linux 2.6.0

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>