Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_CMP_REQUEUE_PI.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_CMP_REQUEUE_PI 2const 2025-09-21 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_CMP_REQUEUE_PI
10 \-
11 compare a priority-inheritance futex, wake a waiter, and requeue others
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_CMP_REQUEUE_PI, 1,"
22 .BI " uint32_t " val2 ", uint32_t *" uaddr2 ,
23 .BI " uint32_t " val3 );
24 .fi
25 .SH DESCRIPTION
26 This operation is a PI-aware variant of
27 .BR FUTEX_CMP_REQUEUE (2const).
28 It requeues waiters that are blocked via
29 .BR FUTEX_WAIT_REQUEUE_PI (2const)
30 on
31 .I uaddr
32 from a non-PI source futex
33 .RI ( uaddr )
34 to a PI target futex
35 .RI ( uaddr2 ).
36 .P
37 Unlike with
38 .BR FUTEX_CMP_REQUEUE (2const),
39 this operation wakes up a maximum of
40 1
41 waiter that is waiting on the futex at
42 .I uaddr
43 (since the main point is to avoid a thundering herd).
44 The remaining waiters are removed from the wait queue of the source futex at
45 .I uaddr
46 and added to the wait queue of the target futex at
47 .IR uaddr2 .
48 .P
49 The
50 .I val2
51 .\" val2 is the cap on the number of requeued waiters.
52 .\" In the glibc pthread_cond_broadcast() implementation, this argument
53 .\" is specified as INT_MAX, and for pthread_cond_signal() it is 0.
54 and
55 .I val3
56 arguments serve the same purposes as for
57 .BR FUTEX_CMP_REQUEUE (2const).
58 .\"
59 .\" The page at http://locklessinc.com/articles/futex_cheat_sheet/
60 .\" notes that "priority-inheritance Futex to priority-inheritance
61 .\" Futex requeues are currently unsupported". However, probably
62 .\" the page does not need to say nothing about this, since
63 .\" Thomas Gleixner commented (July 2015): "they never will be
64 .\" supported because they make no sense at all"
65 .\"
66 .SH RETURN VALUE
67 On error,
68 \-1 is returned,
69 and
70 .I errno
71 is set to indicate the error.
72 .P
73 On success,
74 .B FUTEX_CMP_REQUEUE_PI
75 Returns the total number of waiters that were woken up or
76 requeued to the futex for the futex word at
77 .IR uaddr2 .
78 If this value is greater than 1,
79 then difference is the number of waiters requeued to the futex for
80 the futex word at
81 .IR uaddr2 .
82 .SH ERRORS
83 See
84 .BR futex (2).
85 .TP
86 .B EAGAIN
87 The value pointed to by
88 .I uaddr
89 is not equal to the expected value
90 .IR val3 .
91 .TP
92 .B EAGAIN
93 The futex owner thread ID of
94 .I uaddr2
95 is about to exit,
96 but has not yet handled the internal state cleanup.
97 Try again.
98 .TP
99 .B EDEADLK
100 The futex word at
101 .I uaddr
102 is already locked by the caller.
103 .TP
104 .B EDEADLK
105 .\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some
106 .\" places, and EDEADLOCK in others. On almost all architectures
107 .\" these constants are synonymous. Is there a reason that both
108 .\" names are used?
109 .\"
110 .\" tglx (July 2015): "No. We should probably fix that."
111 .\"
112 While requeueing a waiter to the PI futex for the futex word at
113 .IR uaddr2 ,
114 the kernel detected a deadlock.
115 .TP
116 .B EFAULT
117 .I uaddr2
118 did not point to a valid user-space address.
119 .TP
120 .B EINVAL
121 .I uaddr2
122 does not point to a valid object\[em]that is,
123 the address is not four-byte-aligned.
124 .TP
125 .B EINVAL
126 .I uaddr
127 equals
128 .I uaddr2
129 (i.e., an attempt was made to requeue to the same futex).
130 .TP
131 .B EINVAL
132 The kernel detected an inconsistency between the user-space state at
133 .I uaddr2
134 and the kernel state;
135 .\" From a conversation with Thomas Gleixner (Aug 2015): ###
136 .\" The kernel sees: I have non PI state for a futex you tried to
137 .\" tell me was PI
138 that is, the kernel detected a waiter which waits via
139 .BR FUTEX_WAIT (2const)
140 or
141 .BR FUTEX_WAIT_BITSET (2const)
142 on
143 .IR uaddr2 .
144 .TP
145 .B EINVAL
146 The kernel detected an inconsistency between the user-space state at
147 .I uaddr
148 and the kernel state;
149 that is, the kernel detected a waiter which waits via
150 .BR FUTEX_WAIT (2const)
151 or
152 .BR FUTEX_WAIT_BITSET (2const)
153 on
154 .IR uaddr .
155 .TP
156 .B EINVAL
157 The kernel detected an inconsistency between the user-space state at
158 .I uaddr
159 and the kernel state;
160 that is, the kernel detected a waiter which waits on
161 .I uaddr
162 via
163 .BR FUTEX_LOCK_PI (2const)
164 or
165 .BR FUTEX_LOCK_PI2 (2const)
166 (instead of
167 .BR FUTEX_WAIT_REQUEUE_PI ).
168 .TP
169 .B EINVAL
170 .\" This deals with the case:
171 .\" wait_requeue_pi(A, B);
172 .\" requeue_pi(A, C);
173 An attempt was made to requeue a waiter to a futex other than that
174 specified by the matching
175 .B FUTEX_WAIT_REQUEUE_PI
176 call for that waiter.
177 .TP
178 .B EINVAL
179 The
180 fourth
181 argument is not 1.
182 .TP
183 .B ENOMEM
184 The kernel could not allocate memory to hold state information.
185 .TP
186 .B ENOSYS
187 A run-time check determined that the operation is not available.
188 The PI-futex operations are not implemented on all architectures and
189 are not supported on some CPU variants.
190 .TP
191 .B EPERM
192 The caller is not allowed to attach itself to the futex at
193 .IR uaddr2 .
194 (This may be caused by a state corruption in user space.)
195 .TP
196 .B ESRCH
197 The thread ID in the futex word at
198 .I uaddr
199 does not exist.
200 .TP
201 .B ESRCH
202 The thread ID in the futex word at
203 .I uaddr2
204 does not exist.
205 .SH STANDARDS
206 Linux.
207 .SH HISTORY
208 Linux 2.6.31.
209 .\" commit 52400ba946759af28442dee6265c5c0180ac7122
210 .SH SEE ALSO
211 .BR futex (2)