Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_WAKE.2const

raw
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_WAKE 2const 2025-05-30 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_WAKE \- wake waiters that are inside FUTEX_WAIT
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE, uint32_t " val );
20 .fi
21 .SH DESCRIPTION
22 This operation wakes at most
23 .I val
24 of the waiters that are waiting (e.g., inside
25 .BR FUTEX_WAIT (2const))
26 on the futex word at the address
27 .IR uaddr .
28 .P
29 Most commonly,
30 .I val
31 is specified as either 1 (wake up a single waiter) or
32 .B INT_MAX
33 (wake up all waiters).
34 .P
35 No guarantee is provided about which waiters are awoken
36 (e.g., a waiter with a higher scheduling priority is not guaranteed
37 to be awoken in preference to a waiter with a lower priority).
38 .\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to
39 .\" a different example.
40 .\"
41 .\" For
42 .\" .BR futex (7),
43 .\" this is executed if incrementing the count showed that
44 .\" there were waiters,
45 .\" once the futex value has been set to 1
46 .\" (indicating that it is available).
47 .\"
48 .\" How does "incrementing the count show that there were waiters"?
49 .\"
50 .SH RETURN VALUE
51 On error,
52 \-1 is returned,
53 and
54 .I errno
55 is set to indicate the error.
56 .P
57 On success,
58 .B FUTEX_WAKE
59 returns the number of waiters that were woken up.
60 .SH ERRORS
61 See
62 .BR futex (2).
63 .TP
64 .B EINVAL
65 The kernel detected an inconsistency between the user-space state at
66 .I uaddr
67 and the kernel state\[em]that is, it detected a waiter which waits in
68 .BR FUTEX_LOCK_PI (2const)
69 or
70 .BR FUTEX_LOCK_PI2 (2const)
71 on
72 .IR uaddr .
73 .SH STANDARDS
74 Linux.
75 .SH HISTORY
76 Linux 2.6.0.
77 .\" Strictly speaking, since Linux 2.5.x
78 .SH SEE ALSO
79 .BR futex (2)