Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_WAIT_BITSET.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_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)