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 |CAVEATS |SEE ALSO |COLOPHON | |
FUTEX_WAIT(2const)FUTEX_WAIT(2const)FUTEX_WAIT - sleep waiting for a FUTEX_WAKE operation
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, uint32_tval,const struct timespec *_Nullabletimeout);
This operation tests that the value at the futex word pointed to by the addressuaddr still contains the expected valueval, and if so, then sleeps waiting for aFUTEX_WAKE(2const) operation on the futex word. The load of the value of the futex word is an atomic memory access (i.e., using atomic machine instructions of the respective architecture). This load, the comparison with the expected value, and starting to sleep are performed atomically and totally ordered with respect to other futex operations on the same futex word. If the thread starts to sleep, it is considered a waiter on this futex word. If the futex value does not matchval, then the call fails immediately with the errorEAGAIN. The purpose of the comparison with the expected value is to prevent lost wake-ups. If another thread changed the value of the futex word after the calling thread decided to block based on the prior value, and if the other thread executed aFUTEX_WAKE(2const) operation (or similar wake-up) after the value change and before thisFUTEX_WAIToperation, then the calling thread will observe the value change and will not start to sleep. If thetimeout is not NULL, the structure it points to specifies a timeout for the wait. (This interval will be rounded up to the system clock granularity, and is guaranteed not to expire early.) Iftimeout is NULL, the call blocks indefinitely.
On error, -1 is returned, anderrno is set to indicate the error. On success,FUTEX_WAITreturns 0 if the caller was woken up. Note that a wake-up can also be caused by common futex usage patterns in unrelated code that happened to have previously used the futex word's memory location (e.g., typical futex-based implementations of Pthreads mutexes can cause this under some conditions). Therefore, callers should always conservatively assume that a return value of 0 can mean a spurious wake-up, and use the futex word's value (i.e., the user-space synchronization scheme) to decide whether to continue to block or not.
Seefutex(2).EAGAINThe 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.EINTRThe operation 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).ETIMEDOUT The timeout expired before the operation completed.
Linux.
Linux 2.6.0.
timeout is interpreted as arelative value. This differs from other futex operations, wheretimeout is interpreted as an absolute value. To obtain the equivalent ofFUTEX_WAITwith an absolute timeout, employFUTEX_WAIT_BITSET(2const) withval3 specified asFUTEX_BITSET_MATCH_ANY.
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(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_BITSET(2const), FUTEX_WAIT_REQUEUE_PI(2const), FUTEX_WAKE(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. | |