Debian Codegraph @

upstream/debian-unstable/man2/futex_waitv.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: MIT
4 .\"
5 .TH futex_waitv 2 2026-02-18 "Linux man-pages 6.18"
6 .SH NAME
7 futex_waitv \- wait for FUTEX_WAKE operation on a vector of futexes
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX* " constants */"
14 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
15 .B #include <unistd.h>
16 .B #include <time.h>
17 .P
18 .BR long\~syscall( unsigned\~int\~n;
19 .BI " SYS_futex_waitv, struct\~futex_waitv\~" waiters [ n ],
20 .BI " unsigned\~int\~" n ", unsigned\~int\~" flags ,
21 .BI " const\~struct\~timespec\~*_Nullable\~" timeout ", clockid_t\~" clockid );
22 .fi
23 .P
24 .EX
25 .B "#include <linux/futex.h>"
26 .P
27 struct futex_waitv {
28 u64 val; /* Expected value at \f[I]uaddr\f[] */
29 u64 uaddr; /* User address to wait on */
30 u32 flags; /* Flags for this waiter */
31 u32 __reserved; /* Align to u64 */
32 };
33 .EE
34 .SH DESCRIPTION
35 .\" This name is used internally in the kernel
36 Implements the FUTEX_WAIT_MULTIPLE operation,
37 analogous to a synchronous atomic parallel
38 .BR FUTEX_WAIT (2const)
39 or
40 .B FUTEX_WAIT_PRIVATE
41 on up to
42 .B FUTEX_WAITV_MAX
43 futex words.
44 For an overview of futexes, see
45 .BR futex (7);
46 for a description of the general interface, see
47 .BR futex (2);
48 for general minutiae of futex waiting, see the page above.
49 .P
50 This operation tests that the values at the
51 futex words
52 .IR waiters []. uaddr[0]
53 still contain respective expected values
54 .IR waiters []. val ,
55 and if so, sleeps waiting for a
56 .BR FUTEX_WAKE (2const)
57 operation on any of the futex words,
58 and returns the index of
59 .I a
60 waiter whose futex was woken.
61 .P
62 If the thread starts to sleep,
63 it is considered a waiter on all given futex words.
64 If any of the futex values do not match their respective
65 .IR waiters []. val ,
66 the call fails immediately with the error
67 .BR EAGAIN .
68 .P
69 If
70 .I timeout
71 is NULL,
72 the call blocks indefinitely.
73 Otherwise,
74 .I *timeout
75 specifies a deadline measured against clock
76 .IR clockid .
77 This interval will be rounded up to the system clock granularity,
78 and is guaranteed not to expire early.
79 .P
80 The following clocks are supported:
81 .TP
82 .B CLOCK_MONOTONIC
83 .TQ
84 .B CLOCK_REALTIME
85 .P
86 Futex words to monitor are given by
87 .IR "struct futex_waitv" ,
88 whose fields are analogous to
89 .BR FUTEX_WAIT (2const)
90 parameters, except
91 .I .__reserved
92 must be 0
93 and
94 .I .flags
95 must contain exactly one size flag,
96 ORed with some other flags.
97 .TP
98 .B FUTEX2_SIZE_U32
99 .I .val
100 and
101 .I .uaddr[]
102 are 32-bit unsigned integers.
103 .TP
104 .B FUTEX2_SIZE_U8
105 .TQ
106 .B FUTEX2_SIZE_U16
107 .TQ
108 .B FUTEX2_SIZE_U64
109 These are defined,
110 but not supported
111 .RB ( EINVAL ).
112 .TP
113 .B FUTEX2_NUMA
114 The futex word is followed by another word of the same size
115 .RI ( .uaddr
116 points to
117 .IR uint N _t[2]
118 rather than
119 .IR uint N _t .
120 The word is given by
121 .IR .uaddr[1] ),
122 which can be either
123 .B FUTEX_NO_NODE
124 (all bits set)
125 or a NUMA node number.
126 .IP
127 If the NUMA word is
128 .BR FUTEX_NO_NODE ,
129 the node number of the processor the syscall executes on is written to it.
130 (Except that in an
131 .B EINVAL
132 or
133 .B EFAULT
134 condition, this happens to all waiters whose
135 .I .flags
136 have
137 .B FUTEX2_NUMA
138 set.)
139 .IP
140 Futexes are placed on the NUMA node given by the NUMA word.
141 Futexes without this flag are placed on a random node.
142 .\" linux.git cec199c5e39b (2025-05-03; "futex: Implement FUTEX2_NUMA")
143 .\"
144 .\" FUTEX2_MPOL is not documented or used anywhere;
145 .\" it's unclear to me what it does (defined in
146 .\" linux.git c042c505210d (2025-05-03; "futex: Implement FUTEX2_MPOL"))
147 .TP
148 .B FUTEX2_PRIVATE
149 By default, the futex is shared
150 (like
151 .BR FUTEX_WAIT (2const)),
152 and can be accessed by multiple processes;
153 this flag waits on a private futex word,
154 where all users must use the same virtual memory map
155 (like
156 .BR FUTEX_WAIT_PRIVATE ;
157 this most often means they are part of the same process).
158 Private futexes are faster than shared ones.
159 .P
160 Programs should assign to
161 .I .uaddr
162 by casting a pointer to
163 .IR uintptr_t .
164 .\"
165 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
166 .\"
167 .SH RETURN VALUE
168 Returns an index to an arbitrary entry in
169 .I waiters
170 corresponding to some woken-up futex.
171 This implies no information about other waiters.
172 .P
173 On error,
174 \-1 is returned,
175 and
176 .I errno
177 is set to indicate the error.
178 .\"
179 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
180 .\"
181 .SH ERRORS
182 .TP
183 .B EFAULT
184 .I waiters
185 points outside the accessible address space.
186 .TP
187 .B EFAULT
188 .I timeout
189 is not NULL and points outside the accessible address space.
190 .TP
191 .B EFAULT
192 Any
193 .IR waiters []. uaddr
194 field points outside the accessible address space.
195 .TP
196 .B EINVAL
197 Any
198 .IR waiters []. uaddr
199 field does not point to a valid object\[em]that is,
200 the address is not aligned appropriately for the specified
201 .BI FUTEX2_SIZE_ * .
202 .TP
203 .B EINVAL
204 .I flags
205 was not 0.
206 .TP
207 .B EINVAL
208 .I n
209 was not in the range
210 .RB [ 1 ,
211 .BR FUTEX_WAITV_MAX ].
212 .TP
213 .B EINVAL
214 .I timeout
215 was not NULL and
216 .I clockid
217 was not a valid clock.
218 .TP
219 .B EINVAL
220 .I *timeout
221 is denormal (before epoch or
222 .I tv_nsec
223 not in the range
224 .RB [ 0 ,
225 .BR 999\[aq]999\[aq]999 ]).
226 .TP
227 .B EINVAL
228 Any
229 .IR waiters []. flags
230 field contains an unknown flag.
231 .TP
232 .B EINVAL
233 Any
234 .IR waiters []. flags
235 field does not contain exactly one size flag,
236 or it contains an unsupported one.
237 .TP
238 .B EINVAL
239 Any
240 .IR waiters []. __reserved
241 field is not 0.
242 .TP
243 .B EINVAL
244 Any
245 .IR waiters []. value
246 field has more bits set than permitted than the size flags.
247 .TP
248 .B EINVAL
249 .B FUTEX2_NUMA
250 was set in
251 .IR waiters []. flags ,
252 and the NUMA word
253 (which is the same size as the futex word)
254 is too small to contain the highest possible index of a NUMA domain
255 (for example,
256 .B FUTEX2_SIZE_U8
257 and there are at least 255 possible NUMA domains).
258 .TP
259 .B EINVAL
260 .B FUTEX2_NUMA
261 was set in
262 .IR waiters []. flags ,
263 and the NUMA word is larger than the maximum possible NUMA node and not
264 .BR FUTEX_NO_NODE .
265 .TP
266 .B ETIMEDOUT
267 The timeout elapsed before any futex was woken.
268 .TP
269 .BR EAGAIN " or " EWOULDBLOCK
270 The value in
271 .I .uaddr[0]
272 was not equal to the expected value
273 .I .val
274 at the time of the call.
275 .TP
276 .B EINTR
277 The
278 operation was interrupted by a signal (see
279 .BR signal (7)).
280 .\"
281 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
282 .\"
283 .SH STANDARDS
284 Linux.
285 .SH HISTORY
286 .\" commit bf69bad38cf63d980e8a603f8d1bd1f85b5ed3d9
287 .\" Author: André Almeida <[email protected]>
288 .\" Date: Thu Sep 23 14:11:05 2021 -0300
289 .\"
290 .\" futex: Implement sys_futex_waitv()
291 Linux 5.16.
292 .SH EXAMPLES
293 The program below executes a linear-time operation on 10 threads,
294 displaying the results in real time,
295 waiting at most 1 second for each new result.
296 The first 3 threads operate on the same data (complete in the same time).
297 .B !\&
298 indicates the futex that woke up each
299 .BR futex_waitv ().
300 .P
301 .in +4
302 .EX
303 .RB $\~ ./futex_waitv
304 153 153 153 237 100 245 177 127 215 61
305 122!
306 200!
307 254!
308 306 306!
309 306!
310 354!
311 430!
312 474!
313 490!
314 futex_waitv: my_futex_waitv: Connection timed out
315 .EE
316 .P
317 .\" SRC BEGIN (futex_waitv.c)
318 .EX
319 #include <err.h>
320 #include <errno.h>
321 #include <linux/futex.h>
322 #include <pthread.h>
323 #include <stdatomic.h>
324 #include <stdcountof.h>
325 #include <stdint.h>
326 #include <stdio.h>
327 #include <stdlib.h>
328 #include <string.h>
329 #include <sys/syscall.h>
330 #include <time.h>
331 #include <unistd.h>
332 \&
333 static inline long
334 my_futex_wake_private(_Atomic uint32_t *uaddr, uint32_t val)
335 {
336 return syscall(SYS_futex, uaddr, FUTEX_WAKE_PRIVATE, val);
337 }
338 \&
339 static inline long
340 my_futex_waitv(unsigned int n;
341 struct futex_waitv waiters[n], unsigned int n,
342 unsigned int flags, const struct timespec *timeout,
343 clockid_t clockid)
344 {
345 return syscall(SYS_futex_waitv, waiters, n, flags, timeout, clockid);
346 }
347 \&
348 void *
349 worker(void *arg)
350 {
351 _Atomic uint32_t *futex = arg;
352 \&
353 usleep(*futex * 10000);
354 *futex *= 2;
355 my_futex_wait_private(futex, 1);
356 return NULL;
357 }
358 \&
359 int
360 main(void)
361 {
362 _Atomic uint32_t futexes[10];
363 uint8_t init[countof(futexes)];
364 struct futex_waitv waiters[countof(futexes)] = {};
365 \&
366 if (getentropy(init, sizeof(init)))
367 err(EXIT_FAILURE, "getentropy");
368 init[0] = init[1] = init[2];
369 for (int i = 0; i < countof(futexes); ++i) {
370 printf("%w8u\[rs]t", init[i]);
371 atomic_init(&futexes[i], init[i]);
372 pthread_create(&(pthread_t){}, NULL, worker, &futexes[i]);
373 }
374 putchar(\[aq]\[rs]n\[aq]);
375 \&
376 for (int i = 0; i < countof(futexes); ++i) {
377 waiters[i].val = futexes[i];
378 waiters[i].uaddr = (uintptr_t) &futexes[i];
379 waiters[i].flags = FUTEX2_SIZE_U32 | FUTEX2_PRIVATE;
380 }
381 for (;;) {
382 int woke;
383 struct timespec timeout;
384 \&
385 clock_gettime(CLOCK_MONOTONIC, &timeout);
386 timeout.tv_sec += 1;
387 \&
388 woke = my_futex_waitv(waiters, countof(futexes), 0, &timeout, CLOCK_MONOTONIC);
389 if (woke == \-1 && (errno != EAGAIN && errno != EWOULDBLOCK))
390 err(EXIT_FAILURE, "my_futex_waitv");
391 \&
392 for (int i = 0; i < countof(futexes); ++i) {
393 if (futexes[i] != waiters[i].val)
394 printf("%w32u%s", futexes[i], i == woke ? "!" : "");
395 putchar(\[aq]\[rs]t\[aq]);
396 }
397 putchar(\[aq]\[rs]n\[aq]);
398 \&
399 for (int i = 0; i < countof(futexes); ++i)
400 waiters[i].val = futexes[i];
401 }
402 }
403 .EE
404 .\" SRC END
405 .SH SEE ALSO
406 .BR futex (2),
407 .BR FUTEX_WAIT (2const),
408 .BR FUTEX_WAKE (2const),
409 .BR futex (7)
410 .P
411 Kernel source file
412 .I Documentation/userspace-api/futex2.rst