FUTEX_WAIT_REQUEUE_PI(2const)                    FUTEX_WAIT_REQUEUE_PI(2const)

NAME
       FUTEX_WAIT_REQUEUE_PI - wait on a non-PI futex, and potentially be
       requeued onto a PI 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_WAIT_REQUEUE_PI,
                    uint32_t val,
                    const struct timespec *timeout,
                    uint32_t *uaddr2);

DESCRIPTION
       Wait on a non-PI futex at uaddr and potentially be requeued (via a
       FUTEX_CMP_REQUEUE_PI(2const) operation in another task) onto a PI futex
       at uaddr2.  The wait operation on uaddr is the same as for
       FUTEX_WAIT(2const).

       The waiter can be removed from the wait on uaddr without requeueing on
       uaddr2 via a FUTEX_WAKE(2const) operation in another task.  In this
       case, the FUTEX_WAIT_REQUEUE_PI operation fails with the error EAGAIN.

       If timeout is not NULL, the structure it points to specifies an
       absolute timeout for the wait operation.  If timeout is NULL, the
       operation can block indefinitely.

RETURN VALUE
       On error, -1 is returned, and errno is set to indicate the error.

       On success, FUTEX_WAIT_REQUEUE_PI returns 0 if the caller was
       successfully requeued to the futex for the futex word at uaddr2.

ERRORS
       See futex(2).

       EAGAIN The value pointed to by uaddr was not equal to the expected
              value val at the time of the call.

              Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK (both
              of which appear in different parts of the kernel futex code)
              have the same value.

       EFAULT uaddr2 or 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 uaddr2 does not point to a valid object--that is, the address is
              not four-byte-aligned.

       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.

       ETIMEDOUT
              The timeout expired before the operation completed.

STANDARDS
       Linux.

HISTORY
       Linux 2.6.31.

SEE ALSO
       futex(2)

Linux man-pages 6.15              2025-05-30     FUTEX_WAIT_REQUEUE_PI(2const)