HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
FUTEX_WAIT_BITSET(2const)FUTEX_WAIT_BITSET(2const)FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET - selective futex waiting and waking
Standard C library (libc,-lc)
#include <linux/futex.h>/* Definition ofFUTEX_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAIT_BITSET, uint32_tval,const struct timespec *timeout, NULL,uint32_tval3);long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE_BITSET, uint32_tval,NULL, NULL,uint32_tval3);
FUTEX_WAIT_BITSET This operation is likeFUTEX_WAIT(2const) except thatval3 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 ofFUTEX_WAKE_BITSETfor further details. Iftimeout is not NULL, the structure it points to specifies an absolute timeout for the wait operation. Iftimeout is NULL, the operation can block indefinitely.FUTEX_WAKE_BITSET This operation is the same asFUTEX_WAKE(2const) except that theval3 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 inval3) and the bit mask which is stored in the kernel-internal state of the waiter (the "wait" bit mask that is set usingFUTEX_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 ofFUTEX_WAIT_BITSETandFUTEX_WAKE_BITSETis 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 constantFUTEX_BITSET_MATCH_ANY, which corresponds to all 32 bits set in the bit mask, can be used as theval3 argument forFUTEX_WAIT_BITSETandFUTEX_WAKE_BITSET. Other than differences in the handling of thetimeout argument, theFUTEX_WAIT(2const) operation is equivalent toFUTEX_WAIT_BITSETwithval3 specified asFUTEX_BITSET_MATCH_ANY; that is, allow a wake-up by any waker. TheFUTEX_WAKE(2const) operation is equivalent toFUTEX_WAKE_BITSETwithval3 specified asFUTEX_BITSET_MATCH_ANY; that is, wake up any waiter(s).
On error, -1 is returned, anderrno 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. SeeFUTEX_WAIT(2const) for how to interpret this correctly in practice.FUTEX_WAKE_BITSET Returns the number of waiters that were woken up.
Seefutex(2).EAGAIN(FUTEX_WAIT_BITSET) The value pointed to byuaddr was not equal to the expected valueval at the time of the call.Note: on Linux, the symbolic namesEAGAINandEWOULDBLOCK (both of which appear in different parts of the kernel futex code) have the same value.EFAULTtimeout did not point to a valid user-space address.EINTRAFUTEX_WAIT_BITSEToperation was interrupted by a signal (seesignal(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.EINVALThe suppliedtimeout argument was invalid (tv_sec was less than zero, ortv_nsec was not less than 1,000,000,000).EINVALuaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.EINVALThe bit mask supplied inval3 is zero.EINVAL(FUTEX_WAKE_BITSET) The kernel detected an inconsistency between the user-space state atuaddr and the kernel state— that is, it detected a waiter which waits inFUTEX_LOCK_PI(2const) orFUTEX_LOCK_PI2(2const) onuaddr.ETIMEDOUT The timeout expired before the operation completed.
Linux.
Linux 2.6.25.
futex(2)
This page is part of theman-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 isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-30FUTEX_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)
Copyright and license for this manual page
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |