.\" Copyright, the authors of the Linux man-pages project
.\"
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
.\" may be freely modified and distributed
.\" %%%LICENSE_END
.\"
.TH FUTEX_WAIT 2const (date) "Linux man-pages (unreleased)"
.SH NAME
FUTEX_WAIT
\-
sleep waiting for a FUTEX_WAKE operation
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/futex.h>" "  /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" "  /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT, uint32_t " val ,
.BI "             const struct timespec *_Nullable " timeout );
.fi
.SH DESCRIPTION
This operation tests that the value at the
futex word pointed to by the address
.I uaddr
still contains the expected value
.IR val ,
and if so, then sleeps waiting for a
.BR FUTEX_WAKE (2const)
operation on the futex word.
.P
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
.\" FIXME: Torvald, I think we may need to add some explanation of
.\" "totally ordered" here.
and totally ordered
with respect to other futex operations on the same futex word.
.P
If the thread starts to sleep,
it is considered a waiter on this futex word.
If the futex value does not match
.IR val ,
then the call fails immediately with the error
.BR EAGAIN .
.P
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
.BR FUTEX_WAKE (2const)
operation (or similar wake-up) after the value change and before this
.B FUTEX_WAIT
operation, then the calling thread will observe the
value change and will not start to sleep.
.P
If the
.I 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
.I timeout
is NULL, the call blocks indefinitely.
.\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to a
.\" different example.
.\"
.\"     For
.\"     .BR futex (7),
.\"     this call is executed if decrementing the count gave a negative value
.\"     (indicating contention),
.\"     and will sleep until another process or thread releases
.\"     the futex and executes the
.\"     .B FUTEX_WAKE
.\"     operation.
.\"
.SH RETURN VALUE
On error,
\-1 is returned,
and
.I errno
is set to indicate the error.
.P
On success,
.B 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.
.SH ERRORS
See
.BR futex (2).
.TP
.B EAGAIN
The value pointed to by
.I uaddr
was not equal to the expected value
.I val
at the time of the call.
.IP
.BR Note :
on Linux, the symbolic names
.B EAGAIN
and
.B EWOULDBLOCK
(both of which appear in different parts of the kernel futex code)
have the same value.
.TP
.B EFAULT
.I timeout
did not point to a valid user-space address.
.TP
.B EINTR
The
operation was interrupted by a signal (see
.BR 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.
.TP
.B EINVAL
The supplied
.I timeout
argument was invalid
.RI ( tv_sec
was less than zero, or
.I tv_nsec
was not less than 1,000,000,000).
.TP
.B ETIMEDOUT
The timeout expired before the operation completed.
.\"
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.0.
.\" Strictly speaking, since some time in Linux 2.5.x
.SH CAVEATS
.I timeout
is interpreted as a
.I relative
value.
This differs from other futex operations, where
.I timeout
is interpreted as an absolute value.
To obtain the equivalent of
.B FUTEX_WAIT
with an absolute timeout, employ
.BR FUTEX_WAIT_BITSET (2const)
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY .
.SH SEE ALSO
.BR futex (2)