---
name: "FUTEX_WAIT_BITSET"
section: "2const"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/FUTEX_WAIT_BITSET"
---

# FUTEX\_WAIT\_BITSET(2const)

selective futex waiting and waking

## NAME

FUTEX\_WAIT\_BITSET, FUTEX\_WAKE\_BITSET - selective futex waiting and waking

## 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\_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

- **FUTEX\_WAIT\_BITSET**

  This operation is like [**FUTEX\_WAIT**(2const)](/FUTEX_WAIT/2const.md) 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)](/FUTEX_WAKE/2const.md) 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)](/FUTEX_WAIT/2const.md) 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)](/FUTEX_WAKE/2const.md) operation is equivalent to **FUTEX\_WAKE\_BITSET** with *val3* specified as **FUTEX\_BITSET\_MATCH\_ANY**; that is, wake up any waiter(s).

## RETURN VALUE

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)](/FUTEX_WAIT/2const.md) for how to interpret this correctly in practice.

- **FUTEX\_WAKE\_BITSET**

  Returns the number of waiters that were woken up.

## ERRORS

See [**futex**(2)](/futex/2.md).

- **EAGAIN** or **EWOULDBLOCK**

  (**FUTEX\_WAIT\_BITSET**) The value pointed to by *uaddr* was not equal to the expected value *val* at the time of the call.

- **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)](/signal/7.md)). 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)](/FUTEX_LOCK_PI/2const.md) or [**FUTEX\_LOCK\_PI2**(2const)](/FUTEX_LOCK_PI2/2const.md) on *uaddr*.

- **ETIMEDOUT**

  The timeout expired before the operation completed.

## STANDARDS

Linux.

## HISTORY

Linux 2.6.25.

## SEE ALSO

[**futex**(2)](/futex/2.md)