From: Alejandro Colomar Date: Thu, 29 May 2025 21:25:36 +0000 (+0200) Subject: man/man2/futex.2, man/man2const/FUTEX_LOCK_PI2.2const: Split FUTEX_LOCK_PI2 from... X-Git-Tag: man-pages-6.15~43^2~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2cf885e9c33bdd90f5288ddca5380d186f9b7442;p=thirdparty%2Fman-pages.git man/man2/futex.2, man/man2const/FUTEX_LOCK_PI2.2const: Split FUTEX_LOCK_PI2 from futex(2) Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/futex.2 b/man/man2/futex.2 index 77fa9280a..ea74ea08f 100644 --- a/man/man2/futex.2 +++ b/man/man2/futex.2 @@ -235,7 +235,7 @@ This option bit can be employed only with the and (since Linux 5.14) .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae -.B FUTEX_LOCK_PI2 +.BR FUTEX_LOCK_PI2 (2const) operations. .IP If this option is set, the kernel measures the @@ -363,7 +363,7 @@ If a futex is already acquired (i.e., has a nonzero value), waiters must employ the .BR FUTEX_LOCK_PI (2const) or -.B FUTEX_LOCK_PI2 +.BR FUTEX_LOCK_PI2 (2const) operations to acquire the lock. If other threads are waiting for the lock, then the .B FUTEX_WAITERS @@ -424,7 +424,7 @@ Note that the PI futex operations must be used as paired operations and are subject to some additional requirements: .IP \[bu] 3 .BR FUTEX_LOCK_PI (2const), -.BR FUTEX_LOCK_PI2 , +.BR FUTEX_LOCK_PI2 (2const), and .B FUTEX_TRYLOCK_PI pair with @@ -455,22 +455,8 @@ The PI futex operations are as follows: .\" .TP .BR FUTEX_LOCK_PI (2const) -.TP -.BR FUTEX_LOCK_PI2 " (since Linux 5.14)" -.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae -This operation is the same as -.BR FUTEX_LOCK_PI (2const), -except that the clock against which -.I timeout -is measured is selectable. -By default, the (absolute) timeout specified in -.I timeout -is measured against the -.B CLOCK_MONOTONIC -clock. -.\" -.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.\" +.TQ +.BR FUTEX_LOCK_PI2 (2const) .TP .BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)" .\" commit c87e2837be82df479a6bae9f155c43516d2feebc @@ -519,7 +505,7 @@ arguments are ignored. This operation wakes the top priority waiter that is waiting in .BR FUTEX_LOCK_PI (2const) or -.B FUTEX_LOCK_PI2 +.BR FUTEX_LOCK_PI2 (2const) on the futex address provided by the .I uaddr argument. @@ -679,9 +665,6 @@ is set to indicate the error. The return value on success depends on the operation, as described in the following list: .TP -.B FUTEX_LOCK_PI2 -Returns 0 if the futex was successfully locked. -.TP .B FUTEX_TRYLOCK_PI Returns 0 if the futex was successfully locked. .TP @@ -734,8 +717,7 @@ is not equal to the expected value .IR val3 . .TP .B EAGAIN -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) The futex owner thread ID of .I uaddr @@ -747,8 +729,7 @@ but has not yet handled the internal state cleanup. Try again. .TP .B EDEADLK -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) The futex word at .I uaddr @@ -810,8 +791,7 @@ equals (i.e., an attempt was made to requeue to the same futex). .TP .B EINVAL -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_UNLOCK_PI ) The kernel detected an inconsistency between the user-space state at .I uaddr @@ -861,7 +841,7 @@ that is, the kernel detected a waiter which waits on via .BR FUTEX_LOCK_PI (2const) or -.B FUTEX_LOCK_PI2 +.BR FUTEX_LOCK_PI2 (2const) (instead of .BR FUTEX_WAIT_REQUEUE_PI ). .TP @@ -885,8 +865,7 @@ argument is not 1. Invalid argument. .TP .B ENOMEM -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) The kernel could not allocate memory to hold state information. .TP @@ -903,11 +882,10 @@ but the accompanying operation was neither .BR FUTEX_WAIT_BITSET (2const), .BR FUTEX_WAIT_REQUEUE_PI , nor -.BR FUTEX_LOCK_PI2 . +.BR FUTEX_LOCK_PI2 (2const). .TP .B ENOSYS -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_UNLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI , .BR FUTEX_WAIT_REQUEUE_PI ) @@ -916,8 +894,7 @@ The PI-futex operations are not implemented on all architectures and are not supported on some CPU variants. .TP .B EPERM -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) The caller is not allowed to attach itself to the futex at .I uaddr @@ -932,8 +909,7 @@ the futex at The caller does not own the lock represented by the futex word. .TP .B ESRCH -.RB ( FUTEX_LOCK_PI2 , -.BR FUTEX_TRYLOCK_PI , +.RB ( FUTEX_TRYLOCK_PI , .BR FUTEX_CMP_REQUEUE_PI ) The thread ID in the futex word at .I uaddr diff --git a/man/man2const/FUTEX_LOCK_PI2.2const b/man/man2const/FUTEX_LOCK_PI2.2const new file mode 100644 index 000000000..acb734117 --- /dev/null +++ b/man/man2const/FUTEX_LOCK_PI2.2const @@ -0,0 +1,112 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" may be freely modified and distributed +.\" %%%LICENSE_END +.\" +.TH FUTEX_LOCK_PI2 2const (date) "Linux man-pages (unreleased)" +.SH NAME +FUTEX_LOCK_PI2 \- lock a priority‐inheritance futex +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " FUTEX_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_LOCK_PI2, 0," +.BI " const struct timespec *" timeout ); +.fi +.SH DESCRIPTION +.TP +.BR FUTEX_LOCK_PI2 " (since Linux 5.14)" +.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae +This operation is the same as +.BR FUTEX_LOCK_PI (2const), +except that the clock against which +.I timeout +is measured is selectable. +By default, the (absolute) timeout specified in +.I timeout +is measured against the +.B CLOCK_MONOTONIC +clock. +.\" +.SH RETURN VALUE +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.P +On success, +.B FUTEX_LOCK_PI2 +Returns 0 if the futex was successfully locked. +.SH ERRORS +See +.BR futex (2). +.TP +.B EAGAIN +The futex owner thread ID of +.I uaddr +is about to exit, +but has not yet handled the internal state cleanup. +Try again. +.TP +.B EDEADLK +The futex word at +.I uaddr +is already locked by the caller. +.TP +.B EFAULT +.I timeout +did not point to a valid user-space address. +.TP +.B EINVAL +The supplied +.I timeout +argument was invalid +.RI ( tv_sec +was less than zero, or +.I tv_nsec +was not less than 1,000,000,000). +.TP +.B EINVAL +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state. +This indicates either state corruption +or that the kernel found a waiter on +.I uaddr +which is waiting via +.BR FUTEX_WAIT (2const) +or +.BR FUTEX_WAIT_BITSET (2const). +.TP +.B ENOMEM +The kernel could not allocate memory to hold state information. +.TP +.B ENOSYS +A run-time check determined that the operation is not available. +The PI-futex operations are not implemented on all architectures and +are not supported on some CPU variants. +.TP +.B EPERM +The caller is not allowed to attach itself to the futex at +.IR uaddr . +(This may be caused by a state corruption in user space.) +.TP +.B ESRCH +The thread ID in the futex word at +.I uaddr +does not exist. +.TP +.B ETIMEDOUT +The timeout expired before the operation completed. +.SH STANDARDS +Linux. +.SH HISTORY +.SH SEE ALSO +.BR futex (2)