| 1 |
.\" Copyright, the authors of the Linux man-pages project |
| 2 |
.\" |
| 3 |
.\" SPDX-License-Identifier: MIT |
| 4 |
.\" |
| 5 |
.TH futex 7 2026-02-17 "Linux man-pages 6.18" |
| 6 |
.SH NAME |
| 7 |
futex \- fast user-space locking |
| 8 |
.SH SYNOPSIS |
| 9 |
.nf |
| 10 |
.B #include <linux/futex.h> |
| 11 |
.fi |
| 12 |
.SH DESCRIPTION |
| 13 |
The Linux kernel provides futexes ("Fast user-space mutexes") |
| 14 |
as a building block for fast user-space |
| 15 |
locking and semaphores. |
| 16 |
Futexes are very basic and lend themselves well for building higher-level |
| 17 |
locking abstractions such as |
| 18 |
mutexes, condition variables, read-write locks, barriers, and semaphores. |
| 19 |
.P |
| 20 |
Most programmers will in fact not be using futexes directly but will |
| 21 |
instead rely on system libraries built on them, |
| 22 |
such as the Native POSIX Thread Library (NPTL) (see |
| 23 |
.BR pthreads (7)). |
| 24 |
.P |
| 25 |
A futex is identified by a piece of memory which can be |
| 26 |
shared between processes or threads. |
| 27 |
In these different processes, the futex need not have identical addresses. |
| 28 |
In its bare form, a futex has semaphore semantics; |
| 29 |
it is a counter that can be incremented and decremented atomically; |
| 30 |
processes can wait for the value to become positive. |
| 31 |
.P |
| 32 |
Futex operation occurs entirely in user space for the noncontended case. |
| 33 |
The kernel is involved only to arbitrate the contended case. |
| 34 |
As any sane design will strive for noncontention, |
| 35 |
futexes are also optimized for this situation. |
| 36 |
.P |
| 37 |
In its bare form, a futex is an aligned integer which is |
| 38 |
touched only by atomic assembler instructions. |
| 39 |
This integer is four bytes long on all platforms. |
| 40 |
Processes can share this integer using |
| 41 |
.BR mmap (2), |
| 42 |
via shared memory segments, or because they share memory space, |
| 43 |
in which case the application is commonly called multithreaded. |
| 44 |
.SS Semantics |
| 45 |
Any futex operation starts in user space, |
| 46 |
but it may be necessary to communicate with the kernel using the |
| 47 |
.BR futex (2) |
| 48 |
or |
| 49 |
.BR futex_waitv (2) |
| 50 |
system calls. |
| 51 |
.P |
| 52 |
To "up" a futex, execute the proper assembler instructions that |
| 53 |
will cause the host CPU to atomically increment the integer. |
| 54 |
Afterward, check if it has in fact changed from 0 to 1, in which case |
| 55 |
there were no waiters and the operation is done. |
| 56 |
This is the noncontended case which is fast and should be common. |
| 57 |
.P |
| 58 |
In the contended case, the atomic increment changed the counter |
| 59 |
from \-1 (or some other negative number). |
| 60 |
If this is detected, there are waiters. |
| 61 |
User space should now set the counter to 1 and instruct the |
| 62 |
kernel to wake up any waiters using the |
| 63 |
.B FUTEX_WAKE |
| 64 |
operation. |
| 65 |
.P |
| 66 |
Waiting on a futex, to "down" it, is the reverse operation. |
| 67 |
Atomically decrement the counter and check if it changed to 0, |
| 68 |
in which case the operation is done and the futex was uncontended. |
| 69 |
In all other circumstances, the process should set the counter to \-1 |
| 70 |
and request that the kernel wait for another process to up the futex. |
| 71 |
This is done using the |
| 72 |
.B FUTEX_WAIT |
| 73 |
operation. |
| 74 |
.P |
| 75 |
The |
| 76 |
.BR futex (2) |
| 77 |
and |
| 78 |
.BR futex_waitv (2) |
| 79 |
system calls can optionally be passed a timeout specifying how long |
| 80 |
the kernel should |
| 81 |
wait for the futex to be upped. |
| 82 |
In this case, semantics are more complex and the programmer is referred |
| 83 |
to |
| 84 |
.BR futex (2) |
| 85 |
for |
| 86 |
more details. |
| 87 |
The same holds for asynchronous futex waiting. |
| 88 |
.SH VERSIONS |
| 89 |
Initial futex support was merged in Linux 2.5.7 |
| 90 |
but with different semantics from those described above. |
| 91 |
Current semantics are available from Linux 2.5.40 onward. |
| 92 |
.SH NOTES |
| 93 |
To reiterate, |
| 94 |
bare futexes are not intended |
| 95 |
as an easy-to-use abstraction for end users. |
| 96 |
Implementors are expected to be assembly-literate |
| 97 |
and to have read |
| 98 |
the sources of the futex user-space library referenced below. |
| 99 |
.P |
| 100 |
This manual page illustrates the most common use of the |
| 101 |
.BR futex (2) |
| 102 |
primitives; |
| 103 |
it is by no means the only one. |
| 104 |
.\" .SH AUTHORS |
| 105 |
.\" .P |
| 106 |
.\" Futexes were designed and worked on by Hubertus Franke |
| 107 |
.\" (IBM Thomas J.\& Watson Research Center), |
| 108 |
.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and |
| 109 |
.\" Rusty Russell (IBM Linux Technology Center). |
| 110 |
.\" This page written by bert hubert. |
| 111 |
.SH SEE ALSO |
| 112 |
.BR clone (2), |
| 113 |
.BR futex (2), |
| 114 |
.BR futex_waitv (2), |
| 115 |
.BR get_robust_list (2), |
| 116 |
.BR set_robust_list (2), |
| 117 |
.BR set_tid_address (2), |
| 118 |
.BR pthreads (7) |
| 119 |
.P |
| 120 |
.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux |
| 121 |
(proceedings of the Ottawa Linux Symposium 2002), |
| 122 |
futex example library, futex-*.tar.bz2 |
| 123 |
.UR https:\://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
| 124 |
.UE . |