| 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_BITSET 2const 2026-02-10 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
FUTEX_WAIT_BITSET, |
| 10 |
FUTEX_WAKE_BITSET |
| 11 |
\- |
| 12 |
selective futex waiting and waking |
| 13 |
.SH LIBRARY |
| 14 |
Standard C library |
| 15 |
.RI ( libc ,\~ \-lc ) |
| 16 |
.SH SYNOPSIS |
| 17 |
.nf |
| 18 |
.BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */" |
| 19 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 20 |
.B #include <unistd.h> |
| 21 |
.P |
| 22 |
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT_BITSET, uint32_t " val , |
| 23 |
.BI " const struct timespec *" timeout ", NULL," |
| 24 |
.BI " uint32_t " val3 ); |
| 25 |
.P |
| 26 |
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE_BITSET, uint32_t " val , |
| 27 |
.B " NULL, NULL," |
| 28 |
.BI " uint32_t " val3 ); |
| 29 |
.fi |
| 30 |
.SH DESCRIPTION |
| 31 |
.TP |
| 32 |
.B FUTEX_WAIT_BITSET |
| 33 |
This operation is like |
| 34 |
.BR FUTEX_WAIT (2const) |
| 35 |
except that |
| 36 |
.I val3 |
| 37 |
is used to provide a 32-bit bit mask to the kernel. |
| 38 |
This bit mask, in which at least one bit must be set, |
| 39 |
is stored in the kernel-internal state of the waiter. |
| 40 |
See the description of |
| 41 |
.B FUTEX_WAKE_BITSET |
| 42 |
for further details. |
| 43 |
.IP |
| 44 |
If |
| 45 |
.I timeout |
| 46 |
is not NULL, the structure it points to specifies |
| 47 |
an absolute timeout for the wait operation. |
| 48 |
If |
| 49 |
.I timeout |
| 50 |
is NULL, the operation can block indefinitely. |
| 51 |
.\" |
| 52 |
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| 53 |
.\" |
| 54 |
.TP |
| 55 |
.B FUTEX_WAKE_BITSET |
| 56 |
This operation is the same as |
| 57 |
.BR FUTEX_WAKE (2const) |
| 58 |
except that the |
| 59 |
.I val3 |
| 60 |
argument is used to provide a 32-bit bit mask to the kernel. |
| 61 |
This bit mask, in which at least one bit must be set, |
| 62 |
is used to select which waiters should be woken up. |
| 63 |
The selection is done by a bitwise AND of the "wake" bit mask |
| 64 |
(i.e., the value in |
| 65 |
.IR val3 ) |
| 66 |
and the bit mask which is stored in the kernel-internal |
| 67 |
state of the waiter (the "wait" bit mask that is set using |
| 68 |
.BR FUTEX_WAIT_BITSET ). |
| 69 |
All of the waiters for which the result of the AND is nonzero are woken up; |
| 70 |
the remaining waiters are left sleeping. |
| 71 |
.IP |
| 72 |
The effect of |
| 73 |
.B FUTEX_WAIT_BITSET |
| 74 |
and |
| 75 |
.B FUTEX_WAKE_BITSET |
| 76 |
is to allow selective wake-ups among multiple waiters that are blocked |
| 77 |
on the same futex. |
| 78 |
However, note that, depending on the use case, |
| 79 |
employing this bit-mask multiplexing feature on a |
| 80 |
futex can be less efficient than simply using multiple futexes, |
| 81 |
because employing bit-mask multiplexing requires the kernel |
| 82 |
to check all waiters on a futex, |
| 83 |
including those that are not interested in being woken up |
| 84 |
(i.e., they do not have the relevant bit set in their "wait" bit mask). |
| 85 |
.\" According to http://locklessinc.com/articles/futex_cheat_sheet/: |
| 86 |
.\" |
| 87 |
.\" "The original reason for the addition of these extensions |
| 88 |
.\" was to improve the performance of pthread read-write locks |
| 89 |
.\" in glibc. However, the pthreads library no longer uses the |
| 90 |
.\" same locking algorithm, and these extensions are not used |
| 91 |
.\" without the bitset parameter being all ones. |
| 92 |
.\" |
| 93 |
.\" The page goes on to note that the FUTEX_WAIT_BITSET operation |
| 94 |
.\" is nevertheless used (with a bit mask of all ones) in order to |
| 95 |
.\" obtain the absolute timeout functionality that is useful |
| 96 |
.\" for efficiently implementing Pthreads APIs (which use absolute |
| 97 |
.\" timeouts); FUTEX_WAIT provides only relative timeouts. |
| 98 |
.IP |
| 99 |
The constant |
| 100 |
.BR FUTEX_BITSET_MATCH_ANY , |
| 101 |
which corresponds to all 32 bits set in the bit mask, can be used as the |
| 102 |
.I val3 |
| 103 |
argument for |
| 104 |
.B FUTEX_WAIT_BITSET |
| 105 |
and |
| 106 |
.BR FUTEX_WAKE_BITSET . |
| 107 |
Other than differences in the handling of the |
| 108 |
.I timeout |
| 109 |
argument, the |
| 110 |
.BR FUTEX_WAIT (2const) |
| 111 |
operation is equivalent to |
| 112 |
.B FUTEX_WAIT_BITSET |
| 113 |
with |
| 114 |
.I val3 |
| 115 |
specified as |
| 116 |
.BR FUTEX_BITSET_MATCH_ANY ; |
| 117 |
that is, allow a wake-up by any waker. |
| 118 |
The |
| 119 |
.BR FUTEX_WAKE (2const) |
| 120 |
operation is equivalent to |
| 121 |
.B FUTEX_WAKE_BITSET |
| 122 |
with |
| 123 |
.I val3 |
| 124 |
specified as |
| 125 |
.BR FUTEX_BITSET_MATCH_ANY ; |
| 126 |
that is, wake up any waiter(s). |
| 127 |
.\" |
| 128 |
.SH RETURN VALUE |
| 129 |
On error, |
| 130 |
\-1 is returned, |
| 131 |
and |
| 132 |
.I errno |
| 133 |
is set to indicate the error. |
| 134 |
.P |
| 135 |
The return value on success depends on the operation, |
| 136 |
as described in the following list: |
| 137 |
.TP |
| 138 |
.B FUTEX_WAIT_BITSET |
| 139 |
Returns 0 if the caller was woken up. |
| 140 |
See |
| 141 |
.BR FUTEX_WAIT (2const) |
| 142 |
for how to interpret this correctly in practice. |
| 143 |
.TP |
| 144 |
.B FUTEX_WAKE_BITSET |
| 145 |
Returns the number of waiters that were woken up. |
| 146 |
.SH ERRORS |
| 147 |
See |
| 148 |
.BR futex (2). |
| 149 |
.TP |
| 150 |
.BR EAGAIN " or " EWOULDBLOCK |
| 151 |
.RB ( FUTEX_WAIT_BITSET ) |
| 152 |
The value pointed to by |
| 153 |
.I uaddr |
| 154 |
was not equal to the expected value |
| 155 |
.I val |
| 156 |
at the time of the call. |
| 157 |
.TP |
| 158 |
.B EFAULT |
| 159 |
.I timeout |
| 160 |
did not point to a valid user-space address. |
| 161 |
.TP |
| 162 |
.B EINTR |
| 163 |
A |
| 164 |
.B FUTEX_WAIT_BITSET |
| 165 |
operation was interrupted by a signal (see |
| 166 |
.BR signal (7)). |
| 167 |
Before Linux 2.6.22, |
| 168 |
this error could also be returned for |
| 169 |
a spurious wakeup; |
| 170 |
since Linux 2.6.22, |
| 171 |
this no longer happens. |
| 172 |
.TP |
| 173 |
.B EINVAL |
| 174 |
The supplied |
| 175 |
.I timeout |
| 176 |
argument was invalid |
| 177 |
.RI ( tv_sec |
| 178 |
was less than zero, or |
| 179 |
.I tv_nsec |
| 180 |
was not less than 1,000,000,000). |
| 181 |
.TP |
| 182 |
.B EINVAL |
| 183 |
.I uaddr2 |
| 184 |
does not point to a valid object\[em]that is, |
| 185 |
the address is not four-byte-aligned. |
| 186 |
.TP |
| 187 |
.B EINVAL |
| 188 |
The bit mask supplied in |
| 189 |
.I val3 |
| 190 |
is zero. |
| 191 |
.TP |
| 192 |
.B EINVAL |
| 193 |
.RB ( FUTEX_WAKE_BITSET ) |
| 194 |
The kernel detected an inconsistency between the user-space state at |
| 195 |
.I uaddr |
| 196 |
and the kernel state\[em]that is, it detected a waiter which waits in |
| 197 |
.BR FUTEX_LOCK_PI (2const) |
| 198 |
or |
| 199 |
.BR FUTEX_LOCK_PI2 (2const) |
| 200 |
on |
| 201 |
.IR uaddr . |
| 202 |
.TP |
| 203 |
.B ETIMEDOUT |
| 204 |
The timeout expired before the operation completed. |
| 205 |
.\" |
| 206 |
.SH STANDARDS |
| 207 |
Linux. |
| 208 |
.SH HISTORY |
| 209 |
Linux 2.6.25. |
| 210 |
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d |
| 211 |
.SH SEE ALSO |
| 212 |
.BR futex (2) |