| 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) |