FUTEX(2) | System Calls Manual | FUTEX(2) |
futex
— fast
userspace locking primitive
#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);
The
futex
()
syscall provides sleep and wakeup primitives related to a particular
address.
Three op operations are currently supported:
FUTEX_WAIT
FUTEX_WAKE
or
FUTEX_REQUEUE
operation with the same
uaddr address. uaddr2 is
ignored.FUTEX_WAKE
FUTEX_REQUEUE
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, a value of -1 is returned and errno
is set to indicate the error.
futex
() will fail if:
ENOSYS
]EFAULT
]EAGAIN
]EINVAL
]ETIMEDOUT
]EINTR
]ECANCELED
]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.
May 26, 2021 | OpenBSD-current |