FUTEX_WAIT(2const)                                          FUTEX_WAIT(2const)

NAME
       FUTEX_WAIT - sleep waiting for a FUTEX_WAKE operation

LIBRARY
       Standard C library (libc, -lc)

SYNOPSIS
       #include <linux/futex.h>  /* Definition of FUTEX_* constants */
       #include <sys/syscall.h>  /* Definition of SYS_* constants */
       #include <unistd.h>

       long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAIT, uint32_t val,
                    const struct timespec *_Nullable timeout);

DESCRIPTION
       This operation tests that the value at the futex word pointed to by the
       address uaddr still contains the expected value val, and if so, then
       sleeps waiting for a FUTEX_WAKE(2const) operation on the futex word.

       The load of the value of the futex word is an atomic memory access
       (i.e., using atomic machine instructions of the respective
       architecture).  This load, the comparison with the expected value, and
       starting to sleep are performed atomically and totally ordered with
       respect to other futex operations on the same futex word.

       If the thread starts to sleep, it is considered a waiter on this futex
       word.  If the futex value does not match val, then the call fails
       immediately with the error EAGAIN.

       The purpose of the comparison with the expected value is to prevent
       lost wake-ups.  If another thread changed the value of the futex word
       after the calling thread decided to block based on the prior value, and
       if the other thread executed a FUTEX_WAKE(2const) operation (or similar
       wake-up) after the value change and before this FUTEX_WAIT operation,
       then the calling thread will observe the value change and will not
       start to sleep.

       If the timeout is not NULL, the structure it points to specifies a
       timeout for the wait.  (This interval will be rounded up to the system
       clock granularity, and is guaranteed not to expire early.)  If timeout
       is NULL, the call blocks indefinitely.

RETURN VALUE
       On error, -1 is returned, and errno is set to indicate the error.

       On success, FUTEX_WAIT returns 0 if the caller was woken up.  Note that
       a wake-up can also be caused by common futex usage patterns in
       unrelated code that happened to have previously used the futex word's
       memory location (e.g., typical futex-based implementations of Pthreads
       mutexes can cause this under some conditions).  Therefore, callers
       should always conservatively assume that a return value of 0 can mean a
       spurious wake-up, and use the futex word's value (i.e., the user-space
       synchronization scheme) to decide whether to continue to block or not.

ERRORS
       See futex(2).

       EAGAIN The value pointed to by uaddr was not equal to the expected
              value val at the time of the call.

              Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK (both
              of which appear in different parts of the kernel futex code)
              have the same value.

       EFAULT timeout did not point to a valid user-space address.

       EINTR  The operation was interrupted by a signal (see signal(7)).
              Before Linux 2.6.22, this error could also be returned for a
              spurious wakeup; since Linux 2.6.22, this no longer happens.

       EINVAL The supplied timeout argument was invalid (tv_sec was less than
              zero, or tv_nsec was not less than 1,000,000,000).

       ETIMEDOUT
              The timeout expired before the operation completed.

STANDARDS
       Linux.

HISTORY
       Linux 2.6.0.

CAVEATS
       timeout is interpreted as a relative value.  This differs from other
       futex operations, where timeout is interpreted as an absolute value.
       To obtain the equivalent of FUTEX_WAIT with an absolute timeout, employ
       FUTEX_WAIT_BITSET(2const) with val3 specified as
       FUTEX_BITSET_MATCH_ANY.

SEE ALSO
       futex(2)

Linux man-pages 6.15              2025-05-30                FUTEX_WAIT(2const)