Ubuntu Manpage: FUTEX_WAIT - sleep waiting for a FUTEX

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.