Movatterモバイル変換

FUTEX_LOCK_PI(2const) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|STANDARDS \|HISTORY \|CAVEATS \|SEE ALSO \|COLOPHON

FUTEX_LOCK_PI(2const)FUTEX_LOCK_PI(2const)

NAME top

       FUTEX_LOCK_PI - lock a priority-inheritance futex

LIBRARY top

       Standard C library (libc,-lc)

SYNOPSIS top

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

DESCRIPTION top

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 addressuaddr. 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 theFUTEX_WAITERSbit, 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 theSCHED_DEADLINE,SCHED_FIFO, andSCHED_RR scheduling policies insched(7).) The owner inherits either the waiter's CPU bandwidth (if the waiter is scheduled under theSCHED_DEADLINEpolicy) or the waiter's priority (if the waiter is scheduled under theSCHED_RRorSCHED_FIFOpolicy). This inheritance follows the lock chain in the case of nested locking and performs deadlock detection. Thetimeout argument provides a timeout for the lock attempt. Iftimeout is not NULL, the structure it points to specifies an absolute timeout. Iftimeout is NULL, the operation will block indefinitely.

RETURN VALUE top

       On error, -1 is returned, anderrno is set to indicate the error.       On success,FUTEX_LOCK_PIreturns 0 if the futex was successfully       locked.

ERRORS top

       Seefutex(2).EAGAINThe futex owner thread ID ofuaddr 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.EFAULTtimeout did not point to a valid user-space address.EINVALThe suppliedtimeout argument was invalid (tv_sec was less              than zero, ortv_nsec was not less than 1,000,000,000).EINVALThe kernel detected an inconsistency between the user-space              state atuaddr and the kernel state.  This indicates either              state corruption or that the kernel found a waiter onuaddr              which is waiting viaFUTEX_WAIT(2const) orFUTEX_WAIT_BITSET(2const).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 atuaddr.  (This may be caused by a state corruption in user              space.)ESRCHThe thread ID in the futex word atuaddr does not exist.ETIMEDOUT              The timeout expired before the operation completed.

STANDARDS top

       Linux.

HISTORY top

       Linux 2.6.18.

CAVEATS top

       Unlike otherfutex(2) operations, the timeout is measured against       theCLOCK_REALTIMEclock.

COLOPHON top

       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_LOCK_PI(2const)

Pages that refer to this page:futex(2), FUTEX_CMP_REQUEUE(2const), FUTEX_CMP_REQUEUE_PI(2const), FUTEX_LOCK_PI2(2const), FUTEX_REQUEUE(2const), FUTEX_UNLOCK_PI(2const), FUTEX_WAIT_BITSET(2const), FUTEX_WAKE(2const), FUTEX_WAKE_OP(2const)