FUTEX_WAIT_BITSET(2const) — Linux manual page

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

FUTEX_WAIT_BITSET(2const)                       FUTEX_WAIT_BITSET(2const)

NAME         top

       FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET - selective futex waiting and
       waking

LIBRARY         top

       Standard C library (libc, -lc)

SYNOPSIS         top

       #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_BITSET, uint32_t val,
                    const struct timespec *timeout, NULL,
                    uint32_t val3);

       long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE_BITSET, uint32_t val,
                    NULL, NULL,
                    uint32_t val3);

DESCRIPTION         top

       FUTEX_WAIT_BITSET
              This operation is like FUTEX_WAIT(2const) except that val3
              is used to provide a 32-bit bit mask to the kernel.  This
              bit mask, in which at least one bit must be set, is stored
              in the kernel-internal state of the waiter.  See the
              description of FUTEX_WAKE_BITSET for further details.

              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.

       FUTEX_WAKE_BITSET
              This operation is the same as FUTEX_WAKE(2const) except
              that the val3 argument is used to provide a 32-bit bit mask
              to the kernel.  This bit mask, in which at least one bit
              must be set, is used to select which waiters should be
              woken up.  The selection is done by a bitwise AND of the
              "wake" bit mask (i.e., the value in val3) and the bit mask
              which is stored in the kernel-internal state of the waiter
              (the "wait" bit mask that is set using FUTEX_WAIT_BITSET).
              All of the waiters for which the result of the AND is
              nonzero are woken up; the remaining waiters are left
              sleeping.

              The effect of FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET is to
              allow selective wake-ups among multiple waiters that are
              blocked on the same futex.  However, note that, depending
              on the use case, employing this bit-mask multiplexing
              feature on a futex can be less efficient than simply using
              multiple futexes, because employing bit-mask multiplexing
              requires the kernel to check all waiters on a futex,
              including those that are not interested in being woken up
              (i.e., they do not have the relevant bit set in their
              "wait" bit mask).

              The constant FUTEX_BITSET_MATCH_ANY, which corresponds to
              all 32 bits set in the bit mask, can be used as the val3
              argument for FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET.
              Other than differences in the handling of the timeout
              argument, the FUTEX_WAIT(2const) operation is equivalent to
              FUTEX_WAIT_BITSET with val3 specified as
              FUTEX_BITSET_MATCH_ANY; that is, allow a wake-up by any
              waker.  The FUTEX_WAKE(2const) operation is equivalent to
              FUTEX_WAKE_BITSET with val3 specified as
              FUTEX_BITSET_MATCH_ANY; that is, wake up any waiter(s).

RETURN VALUE         top

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

       The return value on success depends on the operation, as described
       in the following list:

       FUTEX_WAIT_BITSET
              Returns 0 if the caller was woken up.  See
              FUTEX_WAIT(2const) for how to interpret this correctly in
              practice.

       FUTEX_WAKE_BITSET
              Returns the number of waiters that were woken up.

ERRORS         top

       See futex(2).

       EAGAIN (FUTEX_WAIT_BITSET) 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 timeout did not point to a valid user-space address.

       EINTR  A FUTEX_WAIT_BITSET operation was interrupted by a signal
              (see signal(7)).  Before Linux 2.6.22, this error could
              also be returned for a spurious wakeup; since Linux 2.6.22,
              this no longer happens.

       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.

       EINVAL The bit mask supplied in val3 is zero.

       EINVAL (FUTEX_WAKE_BITSET) The kernel detected an inconsistency
              between the user-space state at uaddr and the kernel state—
              that is, it detected a waiter which waits in
              FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) on uaddr.

       ETIMEDOUT
              The timeout expired before the operation completed.

STANDARDS         top

       Linux.

HISTORY         top

       Linux 2.6.25.

SEE ALSO         top

       futex(2)

COLOPHON         top

       This page is part of the man-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 is not
       part of the original manual page), send a mail to
       [email protected]

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

Pages that refer to this page: futex(2)FUTEX_CMP_REQUEUE_PI(2const)FUTEX_LOCK_PI(2const)FUTEX_TRYLOCK_PI(2const)FUTEX_UNLOCK_PI(2const)FUTEX_WAIT(2const)