.\" Copyright, the authors of the Linux man-pages project .\" .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) .\" may be freely modified and distributed .\" %%%LICENSE_END .\" .TH FUTEX_LOCK_PI 2const 2025-05-30 "Linux man-pages 6.15" .SH NAME FUTEX_LOCK_PI \- lock a priority-inheritance futex .SH LIBRARY Standard C library .RI ( libc ,\~ \-lc ) .SH SYNOPSIS .nf .BR "#include " " /* Definition of " FUTEX_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include .P .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_LOCK_PI, 0," .BI " const struct timespec *" timeout ); .fi .SH 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\[em]specifically, because it contained the (PID-namespace-specific) TID of the lock owner. .P The operation checks the value of the futex word at the address .IR 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 .B 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. .\" tglx (July 2015): .\" The operation here is similar to the FUTEX_WAIT logic. When the user .\" space atomic acquire does not succeed because the futex value was non .\" zero, then the waiter goes into the kernel, takes the kernel internal .\" lock and retries the acquisition under the lock. If the acquisition .\" does not succeed either, then it sets the FUTEX_WAITERS bit, to signal .\" the lock owner that it needs to go into the kernel. Here is the pseudo .\" code: .\" .\" lock(kernel_lock); .\" retry: .\" .\" /* .\" * Owner might have unlocked in user space before we .\" * were able to set the waiter bit. .\" */ .\" if (atomic_acquire(futex) == SUCCESS) { .\" unlock(kernel_lock()); .\" return 0; .\" } .\" .\" /* .\" * Owner might have unlocked after the above atomic_acquire() .\" * attempt. .\" */ .\" if (atomic_set_waiters_bit(futex) != SUCCESS) .\" goto retry; .\" .\" queue_waiter(); .\" unlock(kernel_lock); .\" block(); .\" After that, the kernel: .IP (1) 5 Tries to find the thread which is associated with the owner TID. .IP (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.) .IP (3) Attaches the waiter to the futex (i.e., the waiter is enqueued on the RT-mutex waiter list). .P 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 .BR SCHED_DEADLINE , .BR SCHED_FIFO , and .B SCHED_RR scheduling policies in .BR sched (7).) The owner inherits either the waiter's CPU bandwidth (if the waiter is scheduled under the .B SCHED_DEADLINE policy) or the waiter's priority (if the waiter is scheduled under the .B SCHED_RR or .B SCHED_FIFO policy). .\" August 2015: .\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL) .\" processes, does the nice value come into play also? .\" .\" tglx: No. SCHED_OTHER/NORMAL tasks are handled in FIFO order This inheritance follows the lock chain in the case of nested locking .\" (i.e., task 1 blocks on lock A, held by task 2, .\" while task 2 blocks on lock B, held by task 3) and performs deadlock detection. .P The .I timeout argument provides a timeout for the lock attempt. If .I timeout is not NULL, the structure it points to specifies an absolute timeout. If .I timeout is NULL, the operation will block indefinitely. .SH RETURN VALUE On error, \-1 is returned, and .I errno is set to indicate the error. .P On success, .B FUTEX_LOCK_PI returns 0 if the futex was successfully locked. .SH ERRORS See .BR futex (2). .TP .B EAGAIN The futex owner thread ID of .I uaddr 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 EFAULT .I timeout did not point to a valid user-space address. .TP .B EINVAL The supplied .I timeout argument was invalid .RI ( tv_sec was less than zero, or .I tv_nsec was not less than 1,000,000,000). .TP .B EINVAL The kernel detected an inconsistency between the user-space state at .I uaddr and the kernel state. This indicates either state corruption or that the kernel found a waiter on .I uaddr which is waiting via .BR FUTEX_WAIT (2const) or .BR FUTEX_WAIT_BITSET (2const). .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 uaddr . (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 ETIMEDOUT The timeout expired before the operation completed. .\" .SH STANDARDS Linux. .SH HISTORY Linux 2.6.18. .\" commit c87e2837be82df479a6bae9f155c43516d2feebc .SH CAVEATS Unlike other .BR futex (2) operations, the timeout is measured against the .B CLOCK_REALTIME clock. .\" 2016-07-07 response from Thomas Gleixner on LKML: .\" From: Thomas Gleixner .\" Date: 6 July 2016 at 20:57 .\" Subject: Re: futex: Allow FUTEX_CLOCK_REALTIME with FUTEX_WAIT op .\" .\" On Thu, 23 Jun 2016, Michael Kerrisk (man-pages) wrote: .\" > On 06/23/2016 08:28 PM, Darren Hart wrote: .\" > > And as a follow-on, what is the reason for FUTEX_LOCK_PI only using .\" > > CLOCK_REALTIME? It seems reasonable to me that a user may want to wait a .\" > > specific amount of time, regardless of wall time. .\" > .\" > Yes, that's another weird inconsistency. .\" .\" The reason is that phtread_mutex_timedlock() uses absolute timeouts based on .\" CLOCK_REALTIME. glibc folks asked to make that the default behaviour back .\" then when we added LOCK_PI. .\" .SH SEE ALSO .BR futex (2)