Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_WAIT.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
4 .\" may be freely modified and distributed
5 .\" %%%LICENSE_END
6 .\"
7 .TH FUTEX_WAIT 2const 2026-02-10 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_WAIT
10 \-
11 sleep waiting for a FUTEX_WAKE operation
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT, uint32_t " val ,
22 .BI " const struct timespec *_Nullable " timeout );
23 .fi
24 .SH DESCRIPTION
25 This operation tests that the value at the
26 futex word pointed to by the address
27 .I uaddr
28 still contains the expected value
29 .IR val ,
30 and if so, then sleeps waiting for a
31 .BR FUTEX_WAKE (2const)
32 operation on the futex word.
33 .P
34 The load of the value of the futex word is an atomic memory
35 access (i.e., using atomic machine instructions of the respective
36 architecture).
37 This load, the comparison with the expected value, and
38 starting to sleep are performed atomically
39 .\" FIXME: Torvald, I think we may need to add some explanation of
40 .\" "totally ordered" here.
41 and totally ordered
42 with respect to other futex operations on the same futex word.
43 .P
44 If the thread starts to sleep,
45 it is considered a waiter on this futex word.
46 If the futex value does not match
47 .IR val ,
48 then the call fails immediately with the error
49 .BR EAGAIN .
50 .P
51 The purpose of the comparison with the expected value is to prevent lost
52 wake-ups.
53 If another thread changed the value of the futex word after the
54 calling thread decided to block based on the prior value,
55 and if the other thread executed a
56 .BR FUTEX_WAKE (2const)
57 operation (or similar wake-up) after the value change and before this
58 .B FUTEX_WAIT
59 operation, then the calling thread will observe the
60 value change and will not start to sleep.
61 .P
62 If the
63 .I timeout
64 is not NULL, the structure it points to specifies a
65 timeout for the wait.
66 (This interval will be rounded up to the system clock granularity,
67 and is guaranteed not to expire early.)
68 If
69 .I timeout
70 is NULL, the call blocks indefinitely.
71 .\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to a
72 .\" different example.
73 .\"
74 .\" For
75 .\" .BR futex (7),
76 .\" this call is executed if decrementing the count gave a negative value
77 .\" (indicating contention),
78 .\" and will sleep until another process or thread releases
79 .\" the futex and executes the
80 .\" .B FUTEX_WAKE
81 .\" operation.
82 .\"
83 .SH RETURN VALUE
84 On error,
85 \-1 is returned,
86 and
87 .I errno
88 is set to indicate the error.
89 .P
90 On success,
91 .B FUTEX_WAIT
92 returns 0 if the caller was woken up.
93 Note that a wake-up can also be caused by common futex usage patterns
94 in unrelated code that happened to have previously used the futex word's
95 memory location (e.g., typical futex-based implementations of
96 Pthreads mutexes can cause this under some conditions).
97 Therefore, callers should always conservatively assume that a return
98 value of 0 can mean a spurious wake-up, and use the futex word's value
99 (i.e., the user-space synchronization scheme)
100 to decide whether to continue to block or not.
101 .SH ERRORS
102 See
103 .BR futex (2).
104 .TP
105 .BR EAGAIN " or " EWOULDBLOCK
106 The value pointed to by
107 .I uaddr
108 was not equal to the expected value
109 .I val
110 at the time of the call.
111 .TP
112 .B EFAULT
113 .I timeout
114 did not point to a valid user-space address.
115 .TP
116 .B EINTR
117 The
118 operation was interrupted by a signal (see
119 .BR signal (7)).
120 Before Linux 2.6.22,
121 this error could also be returned for
122 a spurious wakeup;
123 since Linux 2.6.22,
124 this no longer happens.
125 .TP
126 .B EINVAL
127 The supplied
128 .I timeout
129 argument was invalid
130 .RI ( tv_sec
131 was less than zero, or
132 .I tv_nsec
133 was not less than 1,000,000,000).
134 .TP
135 .B ETIMEDOUT
136 The timeout expired before the operation completed.
137 .\"
138 .SH STANDARDS
139 Linux.
140 .SH HISTORY
141 Linux 2.6.0.
142 .\" Strictly speaking, since some time in Linux 2.5.x
143 .SH CAVEATS
144 .I timeout
145 is interpreted as a
146 .I relative
147 value.
148 This differs from other futex operations, where
149 .I timeout
150 is interpreted as an absolute value.
151 To obtain the equivalent of
152 .B FUTEX_WAIT
153 with an absolute timeout, employ
154 .BR FUTEX_WAIT_BITSET (2const)
155 with
156 .I val3
157 specified as
158 .BR FUTEX_BITSET_MATCH_ANY .
159 .SH SEE ALSO
160 .BR futex (2)