Manual Page Search Parameters

FUTEX(2) System Calls Manual FUTEX(2)

fast userspace locking primitive

#include <sys/time.h>
#include <sys/futex.h>
futex(volatile uint32_t *uaddr, int op, int val, const struct timespec *timeout, volatile uint32_t *uaddr2);

The futex() syscall provides sleep and wakeup primitives related to a particular address.
Three op operations are currently supported:
If val is equal to *uaddr, the calling thread is blocked on the “wait channel” identified by uaddr until timeout expires or until another thread issues a FUTEX_WAKE or FUTEX_REQUEUE operation with the same uaddr address. uaddr2 is ignored.
Unblocks val threads sleeping on the wait channel identified by uaddr. timeout and uaddr2 are ignored.
Similar to FUTEX_WAKE but also requeue remaining threads from the wait channel uaddr to uaddr2. In this case, pass uint32_t val2 as the fourth argument instead of timeout. At most that number of threads is requeued.

For FUTEX_WAKE and FUTEX_REQUEUE, futex() returns the number of woken threads.
For FUTEX_WAIT, futex() returns zero if woken by a matching FUTEX_WAKE or FUTEX_REQUEUE call, otherwise an error number is returned to indicate the error.

futex() will fail if:
The op argument is invalid.
The userspace address uaddr is invalid.
The value pointed to by uaddr is not the same as the expected value val.
The timeout expired before the thread was woken up
A signal arrived.
A signal arrived and SA_RESTART was set.

sigaction(2), pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9)
Ulrich Drepper, Futexes Are Tricky, https://www.akkadia.org/drepper/futex.pdf, November 5, 2011.

The futex() syscall first appeared in Linux 2.5.7 and was added to OpenBSD 6.2.
April 24, 2018 OpenBSD-current