.BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)"
.\" commit 1acdac104668a0834cfa267de9946fac7764d486
This option bit can be employed only with the
-.BR FUTEX_WAIT_BITSET ,
+.BR FUTEX_WAIT_BITSET (2const),
.BR FUTEX_WAIT_REQUEUE_PI ,
(since Linux 4.5)
.\" commit 337f13046ff03717a9e99675284a817527440a49
.BR FUTEX_CMP_REQUEUE (2const)
.TQ
.BR FUTEX_WAKE_OP (2const)
-.TP
-.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
-.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
-This operation is like
-.BR FUTEX_WAIT (2const)
-except that
-.I val3
-is used to provide a 32-bit bit mask to the kernel.
-This bit mask, in which at least one bit must be set,
-is stored in the kernel-internal state of the waiter.
-See the description of
-.B FUTEX_WAKE_BITSET
-for further details.
-.IP
-If
-.I timeout
-is not NULL, the structure it points to specifies
-an absolute timeout for the wait operation.
-If
-.I timeout
-is NULL, the operation can block indefinitely.
-.IP
-The
-.I uaddr2
-argument is ignored.
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.\"
-.TP
-.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
-.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
-This operation is the same as
-.BR FUTEX_WAKE (2const)
-except that the
-.I val3
-argument is used to provide a 32-bit bit mask to the kernel.
-This bit mask, in which at least one bit must be set,
-is used to select which waiters should be woken up.
-The selection is done by a bitwise AND of the "wake" bit mask
-(i.e., the value in
-.IR val3 )
-and the bit mask which is stored in the kernel-internal
-state of the waiter (the "wait" bit mask that is set using
-.BR FUTEX_WAIT_BITSET ).
-All of the waiters for which the result of the AND is nonzero are woken up;
-the remaining waiters are left sleeping.
-.IP
-The effect of
-.B FUTEX_WAIT_BITSET
-and
-.B FUTEX_WAKE_BITSET
-is to allow selective wake-ups among multiple waiters that are blocked
-on the same futex.
-However, note that, depending on the use case,
-employing this bit-mask multiplexing feature on a
-futex can be less efficient than simply using multiple futexes,
-because employing bit-mask multiplexing requires the kernel
-to check all waiters on a futex,
-including those that are not interested in being woken up
-(i.e., they do not have the relevant bit set in their "wait" bit mask).
-.\" According to http://locklessinc.com/articles/futex_cheat_sheet/:
-.\"
-.\" "The original reason for the addition of these extensions
-.\" was to improve the performance of pthread read-write locks
-.\" in glibc. However, the pthreads library no longer uses the
-.\" same locking algorithm, and these extensions are not used
-.\" without the bitset parameter being all ones.
-.\"
-.\" The page goes on to note that the FUTEX_WAIT_BITSET operation
-.\" is nevertheless used (with a bit mask of all ones) in order to
-.\" obtain the absolute timeout functionality that is useful
-.\" for efficiently implementing Pthreads APIs (which use absolute
-.\" timeouts); FUTEX_WAIT provides only relative timeouts.
-.IP
-The constant
-.BR FUTEX_BITSET_MATCH_ANY ,
-which corresponds to all 32 bits set in the bit mask, can be used as the
-.I val3
-argument for
-.B FUTEX_WAIT_BITSET
-and
-.BR FUTEX_WAKE_BITSET .
-Other than differences in the handling of the
-.I timeout
-argument, the
-.BR FUTEX_WAIT (2const)
-operation is equivalent to
-.B FUTEX_WAIT_BITSET
-with
-.I val3
-specified as
-.BR FUTEX_BITSET_MATCH_ANY ;
-that is, allow a wake-up by any waker.
-The
-.BR FUTEX_WAKE (2const)
-operation is equivalent to
-.B FUTEX_WAKE_BITSET
-with
-.I val3
-specified as
-.BR FUTEX_BITSET_MATCH_ANY ;
-that is, wake up any waiter(s).
-.IP
-The
-.I uaddr2
-and
-.I timeout
-arguments are ignored.
-.\"
-.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TQ
+.BR FUTEX_WAIT_BITSET (2const)
+.TQ
+.BR FUTEX_WAKE_BITSET (2const)
.\"
.SS Priority-inheritance futexes
Linux supports priority-inheritance (PI) futexes in order to handle
The return value on success depends on the operation,
as described in the following list:
.TP
-.B FUTEX_WAIT_BITSET
-Returns 0 if the caller was woken up.
-See
-.BR FUTEX_WAIT (2const)
-for how to interpret this correctly in practice.
-.TP
-.B FUTEX_WAKE_BITSET
-Returns the number of waiters that were woken up.
-.TP
.B FUTEX_LOCK_PI
Returns 0 if the futex was successfully locked.
.TP
No read access to the memory of a futex word.
.TP
.B EAGAIN
-.RB ( FUTEX_WAIT_BITSET ,
-.BR FUTEX_WAIT_REQUEUE_PI )
+.RB ( FUTEX_WAIT_REQUEUE_PI )
The value pointed to by
.I uaddr
was not equal to the expected value
.IR timeout )
did not point to a valid user-space address.
.TP
-.B EINTR
-A
-.B FUTEX_WAIT_BITSET
-operation was interrupted by a signal (see
-.BR signal (7)).
-Before Linux 2.6.22, this error could also be returned for
-a spurious wakeup; since Linux 2.6.22, this no longer happens.
-.TP
.B EINVAL
The operation in
.I futex_op
the address is not four-byte-aligned.
.TP
.B EINVAL
-.RB ( FUTEX_WAIT_BITSET ,
-.BR FUTEX_WAKE_BITSET )
-The bit mask supplied in
-.I val3
-is zero.
-.TP
-.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
.I uaddr
equals
(i.e., an attempt was made to requeue to the same futex).
.TP
.B EINVAL
-.RB ( FUTEX_WAKE_BITSET )
-The kernel detected an inconsistency between the user-space state at
-.I uaddr
-and the kernel state\[em]that is, it detected a waiter which waits in
-.B FUTEX_LOCK_PI
-or
-.B FUTEX_LOCK_PI2
-on
-.IR uaddr .
-.TP
-.B EINVAL
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
which is waiting via
.BR FUTEX_WAIT (2const)
or
-.BR FUTEX_WAIT_BITSET .
+.BR FUTEX_WAIT_BITSET (2const).
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
that is, the kernel detected a waiter which waits via
.BR FUTEX_WAIT (2const)
or
-.B FUTEX_WAIT_BITSET
+.BR FUTEX_WAIT_BITSET (2const)
on
.IR uaddr2 .
.TP
that is, the kernel detected a waiter which waits via
.BR FUTEX_WAIT (2const)
or
-.B FUTEX_WAIT_BITSET
+.BR FUTEX_WAIT_BITSET (2const)
on
.IR uaddr .
.TP
option was specified in
.IR futex_op ,
but the accompanying operation was neither
-.BR FUTEX_WAIT_BITSET ,
+.BR FUTEX_WAIT_BITSET (2const),
.BR FUTEX_WAIT_REQUEUE_PI ,
nor
.BR FUTEX_LOCK_PI2 .
--- /dev/null
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
+.\" may be freely modified and distributed
+.\" %%%LICENSE_END
+.\"
+.TH FUTEX_WAIT_BITSET 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+FUTEX_WAIT_BITSET,
+FUTEX_WAKE_BITSET
+\-
+selective futex waiting and waking
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
+.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT_BITSET, uint32_t " val ,
+.BI " const struct timespec *" timeout ", NULL,"
+.BI " uint32_t " val3 );
+.P
+.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE_BITSET, uint32_t " val ,
+.B " NULL, NULL,"
+.BI " uint32_t " val3 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
+.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
+This operation is like
+.BR FUTEX_WAIT (2const)
+except that
+.I val3
+is used to provide a 32-bit bit mask to the kernel.
+This bit mask, in which at least one bit must be set,
+is stored in the kernel-internal state of the waiter.
+See the description of
+.B FUTEX_WAKE_BITSET
+for further details.
+.IP
+If
+.I timeout
+is not NULL, the structure it points to specifies
+an absolute timeout for the wait operation.
+If
+.I timeout
+is NULL, the operation can block indefinitely.
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
+.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
+.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
+This operation is the same as
+.BR FUTEX_WAKE (2const)
+except that the
+.I val3
+argument is used to provide a 32-bit bit mask to the kernel.
+This bit mask, in which at least one bit must be set,
+is used to select which waiters should be woken up.
+The selection is done by a bitwise AND of the "wake" bit mask
+(i.e., the value in
+.IR val3 )
+and the bit mask which is stored in the kernel-internal
+state of the waiter (the "wait" bit mask that is set using
+.BR FUTEX_WAIT_BITSET ).
+All of the waiters for which the result of the AND is nonzero are woken up;
+the remaining waiters are left sleeping.
+.IP
+The effect of
+.B FUTEX_WAIT_BITSET
+and
+.B FUTEX_WAKE_BITSET
+is to allow selective wake-ups among multiple waiters that are blocked
+on the same futex.
+However, note that, depending on the use case,
+employing this bit-mask multiplexing feature on a
+futex can be less efficient than simply using multiple futexes,
+because employing bit-mask multiplexing requires the kernel
+to check all waiters on a futex,
+including those that are not interested in being woken up
+(i.e., they do not have the relevant bit set in their "wait" bit mask).
+.\" According to http://locklessinc.com/articles/futex_cheat_sheet/:
+.\"
+.\" "The original reason for the addition of these extensions
+.\" was to improve the performance of pthread read-write locks
+.\" in glibc. However, the pthreads library no longer uses the
+.\" same locking algorithm, and these extensions are not used
+.\" without the bitset parameter being all ones.
+.\"
+.\" The page goes on to note that the FUTEX_WAIT_BITSET operation
+.\" is nevertheless used (with a bit mask of all ones) in order to
+.\" obtain the absolute timeout functionality that is useful
+.\" for efficiently implementing Pthreads APIs (which use absolute
+.\" timeouts); FUTEX_WAIT provides only relative timeouts.
+.IP
+The constant
+.BR FUTEX_BITSET_MATCH_ANY ,
+which corresponds to all 32 bits set in the bit mask, can be used as the
+.I val3
+argument for
+.B FUTEX_WAIT_BITSET
+and
+.BR FUTEX_WAKE_BITSET .
+Other than differences in the handling of the
+.I timeout
+argument, the
+.BR FUTEX_WAIT (2const)
+operation is equivalent to
+.B FUTEX_WAIT_BITSET
+with
+.I val3
+specified as
+.BR FUTEX_BITSET_MATCH_ANY ;
+that is, allow a wake-up by any waker.
+The
+.BR FUTEX_WAKE (2const)
+operation is equivalent to
+.B FUTEX_WAKE_BITSET
+with
+.I val3
+specified as
+.BR FUTEX_BITSET_MATCH_ANY ;
+that is, wake up any waiter(s).
+.\"
+.SH RETURN VALUE
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
+.P
+The return value on success depends on the operation,
+as described in the following list:
+.TP
+.B FUTEX_WAIT_BITSET
+Returns 0 if the caller was woken up.
+See
+.BR FUTEX_WAIT (2const)
+for how to interpret this correctly in practice.
+.TP
+.B FUTEX_WAKE_BITSET
+Returns the number of waiters that were woken up.
+.SH ERRORS
+See
+.BR futex (2).
+.TP
+.B EAGAIN
+.RB ( FUTEX_WAIT_BITSET )
+The value pointed to by
+.I uaddr
+was not equal to the expected value
+.I val
+at the time of the call.
+.IP
+.BR Note :
+on Linux, the symbolic names
+.B EAGAIN
+and
+.B EWOULDBLOCK
+(both of which appear in different parts of the kernel futex code)
+have the same value.
+.TP
+.B EFAULT
+.I timeout
+did not point to a valid user-space address.
+.TP
+.B EINTR
+A
+.B FUTEX_WAIT_BITSET
+operation was interrupted by a signal (see
+.BR signal (7)).
+Before Linux 2.6.22, this error could also be returned for
+a spurious wakeup; since Linux 2.6.22, this no longer happens.
+.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
+.I uaddr2
+does not point to a valid object\[em]that is,
+the address is not four-byte-aligned.
+.TP
+.B EINVAL
+The bit mask supplied in
+.I val3
+is zero.
+.TP
+.B EINVAL
+.RB ( FUTEX_WAKE_BITSET )
+The kernel detected an inconsistency between the user-space state at
+.I uaddr
+and the kernel state\[em]that is, it detected a waiter which waits in
+.B FUTEX_LOCK_PI
+or
+.B FUTEX_LOCK_PI2
+on
+.IR uaddr .
+.TP
+.B ETIMEDOUT
+The timeout expired before the operation completed.
+.\"
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.25.
+.SH SEE ALSO
+.BR futex (2)
projects / thirdparty / man-pages.git / commitdiff
