# FUTEX_LOCK_PI

## NAME



           FUTEX_LOCK_PI - lock a priority-inheritance futex
    


## 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_LOCK_PI, 0,**
                        **const struct timespec ***_timeout_**);**
    


## DESCRIPTION



           This operation is used after an attempt to acquire the lock via an
           atomic user-mode instruction failed because the futex word has a
           nonzero value—specifically, because it contained the (PID-
           namespace-specific) TID of the lock owner.
    
           The operation checks the value of the futex word at the address
           _uaddr_.  If the value is 0, then the kernel tries to atomically set
           the futex value to the caller's TID.  If the futex word's value is
           nonzero, the kernel atomically sets the **FUTEX_WAITERS** bit, which
           signals the futex owner that it cannot unlock the futex in user
           space atomically by setting the futex value to 0.  After that, the
           kernel:
    
           (1)  Tries to find the thread which is associated with the owner
                TID.
    
           (2)  Creates or reuses kernel state on behalf of the owner.  (If
                this is the first waiter, there is no kernel state for this
                futex, so kernel state is created by locking the RT-mutex and
                the futex owner is made the owner of the RT-mutex.  If there
                are existing waiters, then the existing state is reused.)
    
           (3)  Attaches the waiter to the futex (i.e., the waiter is
                enqueued on the RT-mutex waiter list).
    
           If more than one waiter exists, the enqueueing of the waiter is in
           descending priority order.  (For information on priority ordering,
           see the discussion of the **SCHED_DEADLINE** , **SCHED_FIFO** , and **SCHED_RR**
           scheduling policies in sched(7).)  The owner inherits either the
           waiter's CPU bandwidth (if the waiter is scheduled under the
           **SCHED_DEADLINE** policy) or the waiter's priority (if the waiter is
           scheduled under the **SCHED_RR** or **SCHED_FIFO** policy).  This
           inheritance follows the lock chain in the case of nested locking
           and performs deadlock detection.
    
           The _timeout_ argument provides a timeout for the lock attempt.  If
           _timeout_ is not NULL, the structure it points to specifies an
           absolute timeout.  If _timeout_ is NULL, the operation will block
           indefinitely.
    


## RETURN VALUE



           On error, -1 is returned, and _errno_ is set to indicate the error.
    
           On success, **FUTEX_LOCK_PI** returns 0 if the futex was successfully
           locked.
    


## ERRORS



           See futex(2).
    
           **EAGAIN** The futex owner thread ID of _uaddr_ 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.
    
           **EFAULT** _timeout_ did not point to a valid user-space address.
    
           **EINVAL** The supplied _timeout_ argument was invalid (_tv_sec_ was less
                  than zero, or _tv_nsec_ was not less than 1,000,000,000).
    
           **EINVAL** The kernel detected an inconsistency between the user-space
                  state at _uaddr_ and the kernel state.  This indicates either
                  state corruption or that the kernel found a waiter on _uaddr_
                  which is waiting via FUTEX_WAIT(2const) or
                  FUTEX_WAIT_BITSET(2const).
    
           **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
                  _uaddr_.  (This may be caused by a state corruption in user
                  space.)
    
           **ESRCH** The thread ID in the futex word at _uaddr_ does not exist.
    
           **ETIMEDOUT**
                  The timeout expired before the operation completed.
    


## STANDARDS



           Linux.
    


## CAVEATS



           Unlike other futex(2) operations, the timeout is measured against
           the **CLOCK_REALTIME** clock.
    


* * *