.\" Copyright, the authors of the Linux man-pages project
.\"
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
.\" may be freely modified and distributed
.\" %%%LICENSE_END
.\"
.TH FUTEX_CMP_REQUEUE_PI 2const 2025-05-30 "Linux man-pages (unreleased)"
.SH NAME
FUTEX_CMP_REQUEUE_PI
\-
compare a priority-inheritance futex, wake a waiter, and requeue others
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/futex.h>" "  /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" "  /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_CMP_REQUEUE_PI, 1,"
.BI "             uint32_t " val2 ", uint32_t *" uaddr2 ,
.BI "             uint32_t " val3 );
.fi
.SH DESCRIPTION
This operation is a PI-aware variant of
.BR FUTEX_CMP_REQUEUE (2const).
It requeues waiters that are blocked via
.BR FUTEX_WAIT_REQUEUE_PI (2const)
on
.I uaddr
from a non-PI source futex
.RI ( uaddr )
to a PI target futex
.RI ( uaddr2 ).
.P
Unlike with
.BR FUTEX_CMP_REQUEUE (2const),
this operation wakes up a maximum of
1
waiter that is waiting on the futex at
.I uaddr
(since the main point is to avoid a thundering herd).
The remaining waiters are removed from the wait queue of the source futex at
.I uaddr
and added to the wait queue of the target futex at
.IR uaddr2 .
.P
The
.I val2
.\" val2 is the cap on the number of requeued waiters.
.\" In the glibc pthread_cond_broadcast() implementation, this argument
.\" is specified as INT_MAX, and for pthread_cond_signal() it is 0.
and
.I val3
arguments serve the same purposes as for
.BR FUTEX_CMP_REQUEUE (2const).
.\"
.\"       The page at http://locklessinc.com/articles/futex_cheat_sheet/
.\"       notes that "priority-inheritance Futex to priority-inheritance
.\"       Futex requeues are currently unsupported". However, probably
.\"       the page does not need to say nothing about this, since
.\"       Thomas Gleixner commented (July 2015): "they never will be
.\"       supported because they make no sense at all"
.\"
.SH RETURN VALUE
On error,
\-1 is returned,
and
.I errno
is set to indicate the error.
.P
On success,
.B FUTEX_CMP_REQUEUE_PI
Returns the total number of waiters that were woken up or
requeued to the futex for the futex word at
.IR uaddr2 .
If this value is greater than 1,
then difference is the number of waiters requeued to the futex for
the futex word at
.IR uaddr2 .
.SH ERRORS
See
.BR futex (2).
.TP
.B EAGAIN
The value pointed to by
.I uaddr
is not equal to the expected value
.IR val3 .
.TP
.B EAGAIN
The futex owner thread ID of
.I uaddr2
is about to exit,
but has not yet handled the internal state cleanup.
Try again.
.TP
.B EDEADLK
The futex word at
.I uaddr
is already locked by the caller.
.TP
.B EDEADLK
.\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some
.\"       places, and EDEADLOCK in others. On almost all architectures
.\"       these constants are synonymous. Is there a reason that both
.\"       names are used?
.\"
.\"       tglx (July 2015): "No. We should probably fix that."
.\"
While requeueing a waiter to the PI futex for the futex word at
.IR uaddr2 ,
the kernel detected a deadlock.
.TP
.B EFAULT
.I uaddr2
did not point to a valid user-space address.
.TP
.B EINVAL
.I uaddr2
does not point to a valid object\[em]that is,
the address is not four-byte-aligned.
.TP
.B EINVAL
.I uaddr
equals
.I uaddr2
(i.e., an attempt was made to requeue to the same futex).
.TP
.B EINVAL
The kernel detected an inconsistency between the user-space state at
.I uaddr2
and the kernel state;
.\" From a conversation with Thomas Gleixner (Aug 2015): ###
.\"	The kernel sees: I have non PI state for a futex you tried to
.\"     tell me was PI
that is, the kernel detected a waiter which waits via
.BR FUTEX_WAIT (2const)
or
.BR FUTEX_WAIT_BITSET (2const)
on
.IR uaddr2 .
.TP
.B EINVAL
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state;
that is, the kernel detected a waiter which waits via
.BR FUTEX_WAIT (2const)
or
.BR FUTEX_WAIT_BITSET (2const)
on
.IR uaddr .
.TP
.B EINVAL
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state;
that is, the kernel detected a waiter which waits on
.I uaddr
via
.BR FUTEX_LOCK_PI (2const)
or
.BR FUTEX_LOCK_PI2 (2const)
(instead of
.BR FUTEX_WAIT_REQUEUE_PI ).
.TP
.B EINVAL
.\" This deals with the case:
.\"     wait_requeue_pi(A, B);
.\"     requeue_pi(A, C);
An attempt was made to requeue a waiter to a futex other than that
specified by the matching
.B FUTEX_WAIT_REQUEUE_PI
call for that waiter.
.TP
.B EINVAL
The
fourth
argument is not 1.
.TP
.B ENOMEM
The kernel could not allocate memory to hold state information.
.TP
.B ENOSYS
A run-time check determined that the operation is not available.
The PI-futex operations are not implemented on all architectures and
are not supported on some CPU variants.
.TP
.B EPERM
The caller is not allowed to attach itself to the futex at
.IR uaddr2 .
(This may be caused by a state corruption in user space.)
.TP
.B ESRCH
The thread ID in the futex word at
.I uaddr
does not exist.
.TP
.B ESRCH
The thread ID in the futex word at
.I uaddr2
does not exist.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.31.
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
.SH SEE ALSO
.BR futex (2)