| 1 |
.\" Copyright, the authors of the Linux man-pages project |
| 2 |
.\" |
| 3 |
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) |
| 4 |
.\" may be freely modified and distributed |
| 5 |
.\" %%%LICENSE_END |
| 6 |
.\" |
| 7 |
.TH FUTEX_WAIT 2const 2026-02-10 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
FUTEX_WAIT |
| 10 |
\- |
| 11 |
sleep waiting for a FUTEX_WAKE operation |
| 12 |
.SH LIBRARY |
| 13 |
Standard C library |
| 14 |
.RI ( libc ,\~ \-lc ) |
| 15 |
.SH SYNOPSIS |
| 16 |
.nf |
| 17 |
.BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */" |
| 18 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 19 |
.B #include <unistd.h> |
| 20 |
.P |
| 21 |
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT, uint32_t " val , |
| 22 |
.BI " const struct timespec *_Nullable " timeout ); |
| 23 |
.fi |
| 24 |
.SH DESCRIPTION |
| 25 |
This operation tests that the value at the |
| 26 |
futex word pointed to by the address |
| 27 |
.I uaddr |
| 28 |
still contains the expected value |
| 29 |
.IR val , |
| 30 |
and if so, then sleeps waiting for a |
| 31 |
.BR FUTEX_WAKE (2const) |
| 32 |
operation on the futex word. |
| 33 |
.P |
| 34 |
The load of the value of the futex word is an atomic memory |
| 35 |
access (i.e., using atomic machine instructions of the respective |
| 36 |
architecture). |
| 37 |
This load, the comparison with the expected value, and |
| 38 |
starting to sleep are performed atomically |
| 39 |
.\" FIXME: Torvald, I think we may need to add some explanation of |
| 40 |
.\" "totally ordered" here. |
| 41 |
and totally ordered |
| 42 |
with respect to other futex operations on the same futex word. |
| 43 |
.P |
| 44 |
If the thread starts to sleep, |
| 45 |
it is considered a waiter on this futex word. |
| 46 |
If the futex value does not match |
| 47 |
.IR val , |
| 48 |
then the call fails immediately with the error |
| 49 |
.BR EAGAIN . |
| 50 |
.P |
| 51 |
The purpose of the comparison with the expected value is to prevent lost |
| 52 |
wake-ups. |
| 53 |
If another thread changed the value of the futex word after the |
| 54 |
calling thread decided to block based on the prior value, |
| 55 |
and if the other thread executed a |
| 56 |
.BR FUTEX_WAKE (2const) |
| 57 |
operation (or similar wake-up) after the value change and before this |
| 58 |
.B FUTEX_WAIT |
| 59 |
operation, then the calling thread will observe the |
| 60 |
value change and will not start to sleep. |
| 61 |
.P |
| 62 |
If the |
| 63 |
.I timeout |
| 64 |
is not NULL, the structure it points to specifies a |
| 65 |
timeout for the wait. |
| 66 |
(This interval will be rounded up to the system clock granularity, |
| 67 |
and is guaranteed not to expire early.) |
| 68 |
If |
| 69 |
.I timeout |
| 70 |
is NULL, the call blocks indefinitely. |
| 71 |
.\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to a |
| 72 |
.\" different example. |
| 73 |
.\" |
| 74 |
.\" For |
| 75 |
.\" .BR futex (7), |
| 76 |
.\" this call is executed if decrementing the count gave a negative value |
| 77 |
.\" (indicating contention), |
| 78 |
.\" and will sleep until another process or thread releases |
| 79 |
.\" the futex and executes the |
| 80 |
.\" .B FUTEX_WAKE |
| 81 |
.\" operation. |
| 82 |
.\" |
| 83 |
.SH RETURN VALUE |
| 84 |
On error, |
| 85 |
\-1 is returned, |
| 86 |
and |
| 87 |
.I errno |
| 88 |
is set to indicate the error. |
| 89 |
.P |
| 90 |
On success, |
| 91 |
.B FUTEX_WAIT |
| 92 |
returns 0 if the caller was woken up. |
| 93 |
Note that a wake-up can also be caused by common futex usage patterns |
| 94 |
in unrelated code that happened to have previously used the futex word's |
| 95 |
memory location (e.g., typical futex-based implementations of |
| 96 |
Pthreads mutexes can cause this under some conditions). |
| 97 |
Therefore, callers should always conservatively assume that a return |
| 98 |
value of 0 can mean a spurious wake-up, and use the futex word's value |
| 99 |
(i.e., the user-space synchronization scheme) |
| 100 |
to decide whether to continue to block or not. |
| 101 |
.SH ERRORS |
| 102 |
See |
| 103 |
.BR futex (2). |
| 104 |
.TP |
| 105 |
.BR EAGAIN " or " EWOULDBLOCK |
| 106 |
The value pointed to by |
| 107 |
.I uaddr |
| 108 |
was not equal to the expected value |
| 109 |
.I val |
| 110 |
at the time of the call. |
| 111 |
.TP |
| 112 |
.B EFAULT |
| 113 |
.I timeout |
| 114 |
did not point to a valid user-space address. |
| 115 |
.TP |
| 116 |
.B EINTR |
| 117 |
The |
| 118 |
operation was interrupted by a signal (see |
| 119 |
.BR signal (7)). |
| 120 |
Before Linux 2.6.22, |
| 121 |
this error could also be returned for |
| 122 |
a spurious wakeup; |
| 123 |
since Linux 2.6.22, |
| 124 |
this no longer happens. |
| 125 |
.TP |
| 126 |
.B EINVAL |
| 127 |
The supplied |
| 128 |
.I timeout |
| 129 |
argument was invalid |
| 130 |
.RI ( tv_sec |
| 131 |
was less than zero, or |
| 132 |
.I tv_nsec |
| 133 |
was not less than 1,000,000,000). |
| 134 |
.TP |
| 135 |
.B ETIMEDOUT |
| 136 |
The timeout expired before the operation completed. |
| 137 |
.\" |
| 138 |
.SH STANDARDS |
| 139 |
Linux. |
| 140 |
.SH HISTORY |
| 141 |
Linux 2.6.0. |
| 142 |
.\" Strictly speaking, since some time in Linux 2.5.x |
| 143 |
.SH CAVEATS |
| 144 |
.I timeout |
| 145 |
is interpreted as a |
| 146 |
.I relative |
| 147 |
value. |
| 148 |
This differs from other futex operations, where |
| 149 |
.I timeout |
| 150 |
is interpreted as an absolute value. |
| 151 |
To obtain the equivalent of |
| 152 |
.B FUTEX_WAIT |
| 153 |
with an absolute timeout, employ |
| 154 |
.BR FUTEX_WAIT_BITSET (2const) |
| 155 |
with |
| 156 |
.I val3 |
| 157 |
specified as |
| 158 |
.BR FUTEX_BITSET_MATCH_ANY . |
| 159 |
.SH SEE ALSO |
| 160 |
.BR futex (2) |