[OpenBSD]

Manual Page Search Parameters

FUTEX(2) System Calls Manual FUTEX(2)

NAME

futexfast userspace locking primitive

SYNOPSIS

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

DESCRIPTION

The futex() syscall provides sleep and wakeup primitives related to a particular address.
Three op operations are currently supported:
 
 
FUTEX_WAIT
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.
 
 
FUTEX_WAKE
Unblocks val threads sleeping on the wait channel identified by uaddr. timeout and uaddr2 are ignored.
 
 
FUTEX_REQUEUE
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.

RETURN VALUES

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.

ERRORS

futex() will fail if:
 
 
[ENOSYS]
The op argument is invalid.
 
 
[EFAULT]
The userspace address uaddr is invalid.
 
 
[EAGAIN]
The value pointed to by uaddr is not the same as the expected value val.
 
 
[ETIMEDOUT]
The timeout expired before the thread was woken up
 
 
[EINTR]
A signal arrived.

SEE ALSO

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.

HISTORY

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