HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
FUTEX_CMP_REQUEUE_PI(2const)FUTEX_CMP_REQUEUE_PI(2const)FUTEX_CMP_REQUEUE_PI - compare a priority-inheritance futex, wake a waiter, and requeue others
Standard C library (libc,-lc)
#include <linux/futex.h>/* Definition ofFUTEX_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(SYS_futex, uint32_t *uaddr, FUTEX_CMP_REQUEUE_PI, 1,uint32_tval2, uint32_t *uaddr2,uint32_tval3);
This operation is a PI-aware variant ofFUTEX_CMP_REQUEUE(2const). It requeues waiters that are blocked viaFUTEX_WAIT_REQUEUE_PI(2const) onuaddr from a non-PI source futex (uaddr) to a PI target futex (uaddr2). Unlike withFUTEX_CMP_REQUEUE(2const), this operation wakes up a maximum of 1 waiter that is waiting on the futex atuaddr (since the main point is to avoid a thundering herd). The remaining waiters are removed from the wait queue of the source futex atuaddr and added to the wait queue of the target futex atuaddr2. Theval2 andval3 arguments serve the same purposes as forFUTEX_CMP_REQUEUE(2const).
On error, -1 is returned, anderrno is set to indicate the error. On success,FUTEX_CMP_REQUEUE_PIReturns the total number of waiters that were woken up or requeued to the futex for the futex word atuaddr2. If this value is greater than 1, then difference is the number of waiters requeued to the futex for the futex word atuaddr2.
Seefutex(2).EAGAINThe value pointed to byuaddr is not equal to the expected valueval3.EAGAINThe futex owner thread ID ofuaddr2 is about to exit, but has not yet handled the internal state cleanup. Try again.EDEADLK The futex word atuaddr is already locked by the caller.EDEADLK While requeueing a waiter to the PI futex for the futex word atuaddr2, the kernel detected a deadlock.EFAULTuaddr2 did not point to a valid user-space address.EINVALuaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.EINVALuaddr equalsuaddr2 (i.e., an attempt was made to requeue to the same futex).EINVALThe kernel detected an inconsistency between the user-space state atuaddr2 and the kernel state; that is, the kernel detected a waiter which waits viaFUTEX_WAIT(2const) orFUTEX_WAIT_BITSET(2const) onuaddr2.EINVALThe kernel detected an inconsistency between the user-space state atuaddr and the kernel state; that is, the kernel detected a waiter which waits viaFUTEX_WAIT(2const) orFUTEX_WAIT_BITSET(2const) onuaddr.EINVALThe kernel detected an inconsistency between the user-space state atuaddr and the kernel state; that is, the kernel detected a waiter which waits onuaddr viaFUTEX_LOCK_PI(2const) orFUTEX_LOCK_PI2(2const) (instead ofFUTEX_WAIT_REQUEUE_PI).EINVALAn attempt was made to requeue a waiter to a futex other than that specified by the matchingFUTEX_WAIT_REQUEUE_PI call for that waiter.EINVALThe fourth argument is not 1.ENOMEMThe kernel could not allocate memory to hold state information.ENOSYSA 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.EPERMThe caller is not allowed to attach itself to the futex atuaddr2. (This may be caused by a state corruption in user space.)ESRCHThe thread ID in the futex word atuaddr does not exist.ESRCHThe thread ID in the futex word atuaddr2 does not exist.
Linux.
Linux 2.6.31.
futex(2)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-30FUTEX_CMP_REQUEUE_PI(2const)Pages that refer to this page:futex(2), FUTEX_WAIT_REQUEUE_PI(2const)
Copyright and license for this manual page
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |