Debian Codegraph @

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

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
5 .\" may be freely modified and distributed
6 .\" %%%LICENSE_END
7 .\"
8 .TH FUTEX_WAKE_OP 2const 2025-09-21 "Linux man-pages 6.18"
9 .SH NAME
10 FUTEX_WAKE_OP \- fast user-space locking
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE_OP, uint32_t " val ,
21 .BI " uint32_t " val2 ", uint32_t *" uaddr2 ,
22 .BI " uint32_t " val3 );
23 .fi
24 .SH DESCRIPTION
25 .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721
26 .\" Author: Jakub Jelinek <[email protected]>
27 .\" Date: Tue Sep 6 15:16:25 2005 -0700
28 .\" FIXME . (Torvald) The glibc condvar implementation is currently being
29 .\" revised (e.g., to not use an internal lock anymore).
30 .\" It is probably more future-proof to remove this paragraph.
31 .\" [Torvald, do you have an update here?]
32 This operation was added to support some user-space use cases
33 where more than one futex must be handled at the same time.
34 The most notable example is the implementation of
35 .BR pthread_cond_signal (3),
36 which requires operations on two futexes,
37 the one used to implement the mutex and the one used in the implementation
38 of the wait queue associated with the condition variable.
39 .B FUTEX_WAKE_OP
40 allows such cases to be implemented without leading to
41 high rates of contention and context switching.
42 .P
43 The
44 .B FUTEX_WAKE_OP
45 operation is equivalent to executing the following code atomically
46 and totally ordered with respect to other futex operations on
47 any of the two supplied futex words:
48 .P
49 .in +4n
50 .EX
51 uint32_t oldval = *(uint32_t *) uaddr2;
52 *(uint32_t *) uaddr2 = oldval \f[I]op\f[] \f[I]oparg\f[];
53 futex(uaddr, FUTEX_WAKE, val, 0, 0, 0);
54 if (oldval \f[I]cmp\f[] \f[I]cmparg\f[])
55 futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0);
56 .EE
57 .in
58 .P
59 In other words,
60 .B FUTEX_WAKE_OP
61 does the following:
62 .IP \[bu] 3
63 saves the original value of the futex word at
64 .I uaddr2
65 and performs an operation to modify the value of the futex at
66 .IR uaddr2 ;
67 this is an atomic read-modify-write memory access (i.e., using atomic
68 machine instructions of the respective architecture)
69 .IP \[bu]
70 wakes up a maximum of
71 .I val
72 waiters on the futex for the futex word at
73 .IR uaddr ;
74 and
75 .IP \[bu]
76 dependent on the results of a test of the original value of the
77 futex word at
78 .IR uaddr2 ,
79 wakes up a maximum of
80 .I val2
81 waiters on the futex for the futex word at
82 .IR uaddr2 .
83 .P
84 The operation and comparison that are to be performed are encoded
85 in the bits of the argument
86 .IR val3 .
87 Pictorially, the encoding is:
88 .P
89 .in +4n
90 .EX
91 +---+---+-----------+-----------+
92 |op |cmp| oparg | cmparg |
93 +---+---+-----------+-----------+
94 4 4 12 12 <== # of bits
95 .EE
96 .in
97 .P
98 Expressed in code, the encoding is:
99 .P
100 .in +4n
101 .EX
102 #define FUTEX_OP(op, oparg, cmp, cmparg) \[rs]
103 (((op & 0xf) << 28) | \[rs]
104 ((cmp & 0xf) << 24) | \[rs]
105 ((oparg & 0xfff) << 12) | \[rs]
106 (cmparg & 0xfff))
107 .EE
108 .in
109 .P
110 In the above,
111 .I op
112 and
113 .I cmp
114 are each one of the codes listed below.
115 The
116 .I oparg
117 and
118 .I cmparg
119 components are literal numeric values, except as noted below.
120 .P
121 The
122 .I op
123 component has one of the following values:
124 .P
125 .in +4n
126 .TS
127 l l l.
128 FUTEX_OP_SET 0 /* uaddr2 = oparg; */
129 FUTEX_OP_ADD 1 /* uaddr2 += oparg; */
130 FUTEX_OP_OR 2 /* uaddr2 |= oparg; */
131 FUTEX_OP_ANDN 3 /* uaddr2 &= \[ti]oparg; */
132 FUTEX_OP_XOR 4 /* uaddr2 \[ha]= oparg; */
133 .TE
134 .in
135 .P
136 In addition, bitwise ORing the following value into
137 .I op
138 causes
139 .I (1\~<<\~oparg)
140 to be used as the operand:
141 .P
142 .in +4n
143 .EX
144 FUTEX_OP_ARG_SHIFT 8 /* Use (1 << oparg) as operand */
145 .EE
146 .in
147 .P
148 The
149 .I cmp
150 field is one of the following:
151 .P
152 .in +4n
153 .EX
154 FUTEX_OP_CMP_EQ 0 /* if (oldval == cmparg) wake */
155 FUTEX_OP_CMP_NE 1 /* if (oldval != cmparg) wake */
156 FUTEX_OP_CMP_LT 2 /* if (oldval < cmparg) wake */
157 FUTEX_OP_CMP_LE 3 /* if (oldval <= cmparg) wake */
158 FUTEX_OP_CMP_GT 4 /* if (oldval > cmparg) wake */
159 FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */
160 .EE
161 .in
162 .P
163 The return value of
164 .B FUTEX_WAKE_OP
165 is the sum of the number of waiters woken on the futex
166 .I uaddr
167 plus the number of waiters woken on the futex
168 .IR uaddr2 .
169 .\"
170 .SH RETURN VALUE
171 On error,
172 \-1 is returned,
173 and
174 .I errno
175 is set to indicate the error.
176 .P
177 On success,
178 .B FUTEX_WAKE_OP
179 Returns the total number of waiters that were woken up.
180 This is the sum of the woken waiters on the two futexes for
181 the futex words at
182 .I uaddr
183 and
184 .IR uaddr2 .
185 .SH ERRORS
186 See
187 .BR futex (2).
188 .TP
189 .B EFAULT
190 .I uaddr2
191 did not point to a valid user-space address.
192 .TP
193 .B EINVAL
194 .I uaddr2
195 does not point to a valid object\[em]that is,
196 the address is not four-byte-aligned.
197 .TP
198 .B EINVAL
199 The kernel detected an inconsistency between the user-space state at
200 .I uaddr
201 and the kernel state\[em]that is, it detected a waiter which waits in
202 .BR FUTEX_LOCK_PI (2const)
203 or
204 .BR FUTEX_LOCK_PI2 (2const)
205 on
206 .IR uaddr .
207 .SH STANDARDS
208 Linux.
209 .SH HISTORY
210 Linux 2.6.14.
211 .SH SEE ALSO
212 .BR futex (2)