# FUTEX_CMP_REQUEUE_PI

## NAME



           FUTEX_CMP_REQUEUE_PI - compare a priority-inheritance futex, wake
           a waiter, and requeue others
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/futex.h>  **/* Definition of **FUTEX_*** constants */
           **#include <sys/syscall.h>  **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **long syscall(SYS_futex, uint32_t ***_uaddr_**, FUTEX_CMP_REQUEUE_PI, 1,**
                        **uint32_t** _val2_**, uint32_t ***_uaddr2_**,**
                        **uint32_t** _val3_**);**
    


## DESCRIPTION



           This operation is a PI-aware variant of FUTEX_CMP_REQUEUE(2const).
           It requeues waiters that are blocked via
           FUTEX_WAIT_REQUEUE_PI(2const) on _uaddr_ from a non-PI source futex
           (_uaddr_) to a PI target futex (_uaddr2_).
    
           Unlike with FUTEX_CMP_REQUEUE(2const), this operation wakes up a
           maximum of 1 waiter that is waiting on the futex at _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
           _uaddr_ and added to the wait queue of the target futex at _uaddr2_.
    
           The _val2_ and _val3_ arguments serve the same purposes as for
           FUTEX_CMP_REQUEUE(2const).
    


## RETURN VALUE



           On error, -1 is returned, and _errno_ is set to indicate the error.
    
           On success, **FUTEX_CMP_REQUEUE_PI** Returns the total number of
           waiters that were woken up or requeued to the futex for the futex
           word at _uaddr2_.  If this value is greater than 1, then difference
           is the number of waiters requeued to the futex for the futex word
           at _uaddr2_.
    


## ERRORS



           See futex(2).
    
           **EAGAIN** The value pointed to by _uaddr_ is not equal to the expected
                  value _val3_.
    
           **EAGAIN** The futex owner thread ID of _uaddr2_ is about to exit, but
                  has not yet handled the internal state cleanup.  Try again.
    
           **EDEADLK**
                  The futex word at _uaddr_ is already locked by the caller.
    
           **EDEADLK**
                  While requeueing a waiter to the PI futex for the futex
                  word at _uaddr2_ , the kernel detected a deadlock.
    
           **EFAULT** _uaddr2_ did not point to a valid user-space address.
    
           **EINVAL** _uaddr2_ does not point to a valid object—that is, the
                  address is not four-byte-aligned.
    
           **EINVAL** _uaddr_ equals _uaddr2_ (i.e., an attempt was made to requeue
                  to the same futex).
    
           **EINVAL** The kernel detected an inconsistency between the user-space
                  state at _uaddr2_ and the kernel state; that is, the kernel
                  detected a waiter which waits via FUTEX_WAIT(2const) or
                  FUTEX_WAIT_BITSET(2const) on _uaddr2_.
    
           **EINVAL** The kernel detected an inconsistency between the user-space
                  state at _uaddr_ and the kernel state; that is, the kernel
                  detected a waiter which waits via FUTEX_WAIT(2const) or
                  FUTEX_WAIT_BITSET(2const) on _uaddr_.
    
           **EINVAL** The kernel detected an inconsistency between the user-space
                  state at _uaddr_ and the kernel state; that is, the kernel
                  detected a waiter which waits on _uaddr_ via
                  FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) (instead of
                  **FUTEX_WAIT_REQUEUE_PI**).
    
           **EINVAL** An attempt was made to requeue a waiter to a futex other
                  than that specified by the matching **FUTEX_WAIT_REQUEUE_PI**
                  call for that waiter.
    
           **EINVAL** The fourth argument is not 1.
    
           **ENOMEM** The kernel could not allocate memory to hold state
                  information.
    
           **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.
    
           **EPERM** The caller is not allowed to attach itself to the futex at
                  _uaddr2_.  (This may be caused by a state corruption in user
                  space.)
    
           **ESRCH** The thread ID in the futex word at _uaddr_ does not exist.
    
           **ESRCH** The thread ID in the futex word at _uaddr2_ does not exist.
    


## STANDARDS



           Linux.
    


* * *