Debian Codegraph @

upstream/debian-unstable/man2/FUTEX_WAIT_REQUEUE_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_WAIT_REQUEUE_PI 2const 2026-02-10 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_WAIT_REQUEUE_PI
10 \-
11 wait on a non-PI futex, and potentially be requeued onto a PI futex
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_REQUEUE_PI,"
22 .BI " uint32_t " val ,
23 .BI " const struct timespec *" timeout ,
24 .BI " uint32_t *" uaddr2 );
25 .fi
26 .SH DESCRIPTION
27 Wait on a non-PI futex at
28 .I uaddr
29 and potentially be requeued (via a
30 .BR FUTEX_CMP_REQUEUE_PI (2const)
31 operation in another task) onto a PI futex at
32 .IR uaddr2 .
33 The wait operation on
34 .I uaddr
35 is the same as for
36 .BR FUTEX_WAIT (2const).
37 .P
38 The waiter can be removed from the wait on
39 .I uaddr
40 without requeueing on
41 .I uaddr2
42 via a
43 .BR FUTEX_WAKE (2const)
44 operation in another task.
45 In this case, the
46 .B FUTEX_WAIT_REQUEUE_PI
47 operation fails with the error
48 .BR EAGAIN .
49 .P
50 If
51 .I timeout
52 is not NULL, the structure it points to specifies
53 an absolute timeout for the wait operation.
54 If
55 .I timeout
56 is NULL, the operation can block indefinitely.
57 .\"
58 .SH RETURN VALUE
59 On error,
60 \-1 is returned,
61 and
62 .I errno
63 is set to indicate the error.
64 .P
65 On success,
66 .B FUTEX_WAIT_REQUEUE_PI
67 returns 0 if the caller was successfully requeued to the futex for
68 the futex word at
69 .IR uaddr2 .
70 .\"
71 .SH ERRORS
72 See
73 .BR futex (2).
74 .TP
75 .BR EAGAIN " or " EWOULDBLOCK
76 The value pointed to by
77 .I uaddr
78 was not equal to the expected value
79 .I val
80 at the time of the call.
81 .TP
82 .B EFAULT
83 .I uaddr2
84 or
85 .I timeout
86 did not point to a valid user-space address.
87 .TP
88 .B EINVAL
89 The supplied
90 .I timeout
91 argument was invalid
92 .RI ( tv_sec
93 was less than zero, or
94 .I tv_nsec
95 was not less than 1,000,000,000).
96 .TP
97 .B EINVAL
98 .I uaddr2
99 does not point to a valid object\[em]that is,
100 the address is not four-byte-aligned.
101 .TP
102 .B ENOSYS
103 A run-time check determined that the operation is not available.
104 The PI-futex operations are not implemented on all architectures and
105 are not supported on some CPU variants.
106 .TP
107 .B ETIMEDOUT
108 The timeout expired before the operation completed.
109 .\"
110 .SH STANDARDS
111 Linux.
112 .SH HISTORY
113 Linux 2.6.31.
114 .\" commit 52400ba946759af28442dee6265c5c0180ac7122
115 .SH SEE ALSO
116 .BR futex (2)