.\" Copyright, the authors of the Linux man-pages project
.\"
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
.\" may be freely modified and distributed
.\" %%%LICENSE_END
.\"
.TH FUTEX_WAIT_BITSET 2const 2025-05-30 "Linux man-pages (unreleased)"
.SH NAME
FUTEX_WAIT_BITSET,
FUTEX_WAKE_BITSET
\-
selective futex waiting and waking
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/futex.h>" "  /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" "  /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT_BITSET, uint32_t " val ,
.BI "             const struct timespec *" timeout ", NULL,"
.BI "             uint32_t " val3 );
.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE_BITSET, uint32_t " val ,
.B "             NULL, NULL,"
.BI "             uint32_t " val3 );
.fi
.SH DESCRIPTION
.TP
.B FUTEX_WAIT_BITSET
This operation is like
.BR FUTEX_WAIT (2const)
except that
.I 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
.B FUTEX_WAKE_BITSET
for further details.
.IP
If
.I timeout
is not NULL, the structure it points to specifies
an absolute timeout for the wait operation.
If
.I timeout
is NULL, the operation can block indefinitely.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.B FUTEX_WAKE_BITSET
This operation is the same as
.BR FUTEX_WAKE (2const)
except that the
.I 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
.IR val3 )
and the bit mask which is stored in the kernel-internal
state of the waiter (the "wait" bit mask that is set using
.BR 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.
.IP
The effect of
.B FUTEX_WAIT_BITSET
and
.B 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).
.\" According to http://locklessinc.com/articles/futex_cheat_sheet/:
.\"
.\"    "The original reason for the addition of these extensions
.\"     was to improve the performance of pthread read-write locks
.\"     in glibc. However, the pthreads library no longer uses the
.\"     same locking algorithm, and these extensions are not used
.\"     without the bitset parameter being all ones.
.\"
.\" The page goes on to note that the FUTEX_WAIT_BITSET operation
.\" is nevertheless used (with a bit mask of all ones) in order to
.\" obtain the absolute timeout functionality that is useful
.\" for efficiently implementing Pthreads APIs (which use absolute
.\" timeouts); FUTEX_WAIT provides only relative timeouts.
.IP
The constant
.BR FUTEX_BITSET_MATCH_ANY ,
which corresponds to all 32 bits set in the bit mask, can be used as the
.I val3
argument for
.B FUTEX_WAIT_BITSET
and
.BR FUTEX_WAKE_BITSET .
Other than differences in the handling of the
.I timeout
argument, the
.BR FUTEX_WAIT (2const)
operation is equivalent to
.B FUTEX_WAIT_BITSET
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, allow a wake-up by any waker.
The
.BR FUTEX_WAKE (2const)
operation is equivalent to
.B FUTEX_WAKE_BITSET
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, wake up any waiter(s).
.\"
.SH RETURN VALUE
On error,
\-1 is returned,
and
.I errno
is set to indicate the error.
.P
The return value on success depends on the operation,
as described in the following list:
.TP
.B FUTEX_WAIT_BITSET
Returns 0 if the caller was woken up.
See
.BR FUTEX_WAIT (2const)
for how to interpret this correctly in practice.
.TP
.B FUTEX_WAKE_BITSET
Returns the number of waiters that were woken up.
.SH ERRORS
See
.BR futex (2).
.TP
.B EAGAIN
.RB ( FUTEX_WAIT_BITSET )
The value pointed to by
.I uaddr
was not equal to the expected value
.I val
at the time of the call.
.IP
.BR Note :
on Linux, the symbolic names
.B EAGAIN
and
.B EWOULDBLOCK
(both of which appear in different parts of the kernel futex code)
have the same value.
.TP
.B EFAULT
.I timeout
did not point to a valid user-space address.
.TP
.B EINTR
A
.B FUTEX_WAIT_BITSET
operation was interrupted by a signal (see
.BR 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.
.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
.I uaddr2
does not point to a valid object\[em]that is,
the address is not four-byte-aligned.
.TP
.B EINVAL
The bit mask supplied in
.I val3
is zero.
.TP
.B EINVAL
.RB ( FUTEX_WAKE_BITSET )
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state\[em]that is, it detected a waiter which waits in
.BR FUTEX_LOCK_PI (2const)
or
.BR FUTEX_LOCK_PI2 (2const)
on
.IR uaddr .
.TP
.B ETIMEDOUT
The timeout expired before the operation completed.
.\"
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.25.
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
.SH SEE ALSO
.BR futex (2)