# FUTEX_WAIT_BITSET

## 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) 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



           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



           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



           Linux.
    


* * *