# FUTEX_WAIT

## 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.
    


## 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**.
    


* * *