Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_LOCK_PI.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_LOCK_PI 2const 2025-12-25 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_LOCK_PI \- lock a priority-inheritance futex
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_LOCK_PI, 0,"
20 .BI " const struct timespec *" timeout );
21 .fi
22 .SH DESCRIPTION
23 This operation is used after an attempt to acquire
24 the lock via an atomic user-mode instruction failed
25 because the futex word has a nonzero value\[em]specifically,
26 because it contained the (PID-namespace-specific) TID of the lock owner.
27 .P
28 The operation checks the value of the futex word at the address
29 .IR uaddr .
30 If the value is 0, then the kernel tries to atomically set
31 the futex value to the caller's TID.
32 If the futex word's value is nonzero,
33 the kernel atomically sets the
34 .B FUTEX_WAITERS
35 bit, which signals the futex owner that it cannot unlock the futex in
36 user space atomically by setting the futex value to 0.
37 .\" tglx (July 2015):
38 .\" The operation here is similar to the FUTEX_WAIT logic. When the user
39 .\" space atomic acquire does not succeed because the futex value was non
40 .\" zero, then the waiter goes into the kernel, takes the kernel internal
41 .\" lock and retries the acquisition under the lock. If the acquisition
42 .\" does not succeed either, then it sets the FUTEX_WAITERS bit, to signal
43 .\" the lock owner that it needs to go into the kernel. Here is the pseudo
44 .\" code:
45 .\"
46 .\" lock(kernel_lock);
47 .\" retry:
48 .\"
49 .\" /*
50 .\" * Owner might have unlocked in user space before we
51 .\" * were able to set the waiter bit.
52 .\" */
53 .\" if (atomic_acquire(futex) == SUCCESS) {
54 .\" unlock(kernel_lock());
55 .\" return 0;
56 .\" }
57 .\"
58 .\" /*
59 .\" * Owner might have unlocked after the above atomic_acquire()
60 .\" * attempt.
61 .\" */
62 .\" if (atomic_set_waiters_bit(futex) != SUCCESS)
63 .\" goto retry;
64 .\"
65 .\" queue_waiter();
66 .\" unlock(kernel_lock);
67 .\" block();
68 .\"
69 After that, the kernel:
70 .IP (1) 5
71 Tries to find the thread which is associated with the owner TID.
72 .IP (2)
73 Creates or reuses kernel state on behalf of the owner.
74 (If this is the first waiter, there is no kernel state for this
75 futex, so kernel state is created by locking the RT-mutex
76 and the futex owner is made the owner of the RT-mutex.
77 If there are existing waiters, then the existing state is reused.)
78 .IP (3)
79 Attaches the waiter to the futex
80 (i.e., the waiter is enqueued on the RT-mutex waiter list).
81 .P
82 If more than one waiter exists,
83 the enqueueing of the waiter is in descending priority order.
84 (For information on priority ordering, see the discussion of the
85 .BR SCHED_DEADLINE ,
86 .BR SCHED_FIFO ,
87 and
88 .B SCHED_RR
89 scheduling policies in
90 .BR sched (7).)
91 The owner inherits either the waiter's CPU bandwidth
92 (if the waiter is scheduled under the
93 .B SCHED_DEADLINE
94 policy) or the waiter's priority (if the waiter is scheduled under the
95 .B SCHED_RR
96 or
97 .B SCHED_FIFO
98 policy).
99 .\" August 2015:
100 .\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL)
101 .\" processes, does the nice value come into play also?
102 .\"
103 .\" tglx: No. SCHED_OTHER/NORMAL tasks are handled in FIFO order
104 This inheritance follows the lock chain in the case of nested locking
105 .\" (i.e., task 1 blocks on lock A, held by task 2,
106 .\" while task 2 blocks on lock B, held by task 3)
107 and performs deadlock detection.
108 .P
109 The
110 .I timeout
111 argument provides a timeout for the lock attempt.
112 If
113 .I timeout
114 is not NULL, the structure it points to specifies
115 an absolute timeout.
116 If
117 .I timeout
118 is NULL, the operation will block indefinitely.
119 .SH RETURN VALUE
120 On error,
121 \-1 is returned,
122 and
123 .I errno
124 is set to indicate the error.
125 .P
126 On success,
127 .B FUTEX_LOCK_PI
128 returns 0 if the futex was successfully locked.
129 .SH ERRORS
130 See
131 .BR futex (2).
132 .TP
133 .B EAGAIN
134 The futex owner thread ID of
135 .I uaddr
136 is about to exit,
137 but has not yet handled the internal state cleanup.
138 Try again.
139 .TP
140 .B EDEADLK
141 The futex word at
142 .I uaddr
143 is already locked by the caller.
144 .TP
145 .B EFAULT
146 .I timeout
147 did not point to a valid user-space address.
148 .TP
149 .B EINVAL
150 The supplied
151 .I timeout
152 argument was invalid
153 .RI ( tv_sec
154 was less than zero, or
155 .I tv_nsec
156 was not less than 1,000,000,000).
157 .TP
158 .B EINVAL
159 The kernel detected an inconsistency between the user-space state at
160 .I uaddr
161 and the kernel state.
162 This indicates either state corruption
163 or that the kernel found a waiter on
164 .I uaddr
165 which is waiting via
166 .BR FUTEX_WAIT (2const)
167 or
168 .BR FUTEX_WAIT_BITSET (2const).
169 .TP
170 .B ENOMEM
171 The kernel could not allocate memory to hold state information.
172 .TP
173 .B ENOSYS
174 A run-time check determined that the operation is not available.
175 The PI-futex operations are not implemented on all architectures and
176 are not supported on some CPU variants.
177 .TP
178 .B EPERM
179 The caller is not allowed to attach itself to the futex at
180 .IR uaddr .
181 (This may be caused by a state corruption in user space.)
182 .TP
183 .B ESRCH
184 The thread ID in the futex word at
185 .I uaddr
186 does not exist.
187 .TP
188 .B ETIMEDOUT
189 The timeout expired before the operation completed.
190 .\"
191 .SH STANDARDS
192 Linux.
193 .SH HISTORY
194 Linux 2.6.18.
195 .\" commit c87e2837be82df479a6bae9f155c43516d2feebc
196 .SH CAVEATS
197 Unlike other
198 .BR futex (2)
199 operations,
200 the timeout is measured against the
201 .B CLOCK_REALTIME
202 clock.
203 .\" 2016-07-07 response from Thomas Gleixner on LKML:
204 .\" From: Thomas Gleixner <[email protected]>
205 .\" Date: 6 July 2016 at 20:57
206 .\" Subject: Re: futex: Allow FUTEX_CLOCK_REALTIME with FUTEX_WAIT op
207 .\"
208 .\" On Thu, 23 Jun 2016, Michael Kerrisk (man-pages) wrote:
209 .\" > On 06/23/2016 08:28 PM, Darren Hart wrote:
210 .\" > > And as a follow-on, what is the reason for FUTEX_LOCK_PI only using
211 .\" > > CLOCK_REALTIME? It seems reasonable to me that a user may want to wait a
212 .\" > > specific amount of time, regardless of wall time.
213 .\" >
214 .\" > Yes, that's another weird inconsistency.
215 .\"
216 .\" The reason is that phtread_mutex_timedlock() uses absolute timeouts based on
217 .\" CLOCK_REALTIME. glibc folks asked to make that the default behavior back
218 .\" then when we added LOCK_PI.
219 .\"
220 .SH SEE ALSO
221 .BR futex (2)