154 lines
3.2 KiB
Groff
154 lines
3.2 KiB
Groff
.\" $OpenBSD: futex.2,v 1.7 2023/11/09 09:13:32 jasper Exp $
|
|
.\"
|
|
.\" Copyright (c) 2017 Martin Pieuchot
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd $Mdocdate: November 9 2023 $
|
|
.Dt FUTEX 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm futex
|
|
.Nd fast userspace locking primitive
|
|
.Sh SYNOPSIS
|
|
.In sys/time.h
|
|
.In sys/futex.h
|
|
.Ft int
|
|
.Fo futex
|
|
.Fa "volatile uint32_t *uaddr"
|
|
.Fa "int op"
|
|
.Fa "int val"
|
|
.Fa "const struct timespec *timeout"
|
|
.Fa "volatile uint32_t *uaddr2"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn futex
|
|
syscall provides sleep and wakeup primitives related to a particular address.
|
|
.Pp
|
|
Three
|
|
.Fa op
|
|
operations are currently supported:
|
|
.Bl -tag -width FUTEX_REQUEUE -offset indent
|
|
.It Dv FUTEX_WAIT
|
|
If
|
|
.Fa val
|
|
is equal to
|
|
.Pf * Fa uaddr ,
|
|
the calling thread is blocked on the
|
|
.Dq wait channel
|
|
identified by
|
|
.Fa uaddr
|
|
until
|
|
.Fa timeout
|
|
expires or until another thread issues a
|
|
.Dv FUTEX_WAKE
|
|
or
|
|
.Dv FUTEX_REQUEUE
|
|
operation with the same
|
|
.Fa uaddr
|
|
address.
|
|
.Fa uaddr2
|
|
is ignored.
|
|
.It Dv FUTEX_WAKE
|
|
Unblocks
|
|
.Fa val
|
|
threads sleeping on the
|
|
wait channel identified by
|
|
.Fa uaddr .
|
|
.Fa timeout
|
|
and
|
|
.Fa uaddr2
|
|
are ignored.
|
|
.It Dv FUTEX_REQUEUE
|
|
Similar to
|
|
.Dv FUTEX_WAKE
|
|
but also requeue remaining threads from the wait channel
|
|
.Fa uaddr
|
|
to
|
|
.Fa uaddr2 .
|
|
In this case, pass
|
|
.Fa "uint32_t val2"
|
|
as the fourth argument instead of
|
|
.Fa timeout .
|
|
At most that number of threads is requeued.
|
|
.El
|
|
.Sh RETURN VALUES
|
|
For
|
|
.Dv FUTEX_WAKE
|
|
and
|
|
.Dv FUTEX_REQUEUE ,
|
|
.Fn futex
|
|
returns the number of woken threads.
|
|
.Pp
|
|
For
|
|
.Dv FUTEX_WAIT ,
|
|
.Fn futex
|
|
returns zero if woken by a matching
|
|
.Dv FUTEX_WAKE
|
|
or
|
|
.Dv FUTEX_REQUEUE
|
|
call.
|
|
Otherwise, a value of \-1 is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh ERRORS
|
|
.Fn futex
|
|
will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENOSYS
|
|
The
|
|
.Fa op
|
|
argument is invalid.
|
|
.It Bq Er EFAULT
|
|
The userspace address
|
|
.Fa uaddr
|
|
is invalid.
|
|
.It Bq Er EAGAIN
|
|
The value pointed to by
|
|
.Fa uaddr
|
|
is not the same as the expected value
|
|
.Fa val .
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa timeout
|
|
specified a second value less than zero,
|
|
or a nanosecond value less than zero or greater than or equal to 1000 million.
|
|
.It Bq Er ETIMEDOUT
|
|
The
|
|
.Fa timeout
|
|
expired before the thread was woken up.
|
|
.It Bq Er EINTR
|
|
A signal arrived.
|
|
.It Bq Er ECANCELED
|
|
A signal arrived and
|
|
.Fa SA_RESTART
|
|
was set.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr sigaction 2 ,
|
|
.Xr pthread_cond_wait 3 ,
|
|
.Xr pthread_mutex_lock 3 ,
|
|
.Xr tsleep 9
|
|
.Rs
|
|
.%A Ulrich Drepper
|
|
.%T Futexes Are Tricky
|
|
.%U https://www.akkadia.org/drepper/futex.pdf
|
|
.%D November 5, 2011
|
|
.Re
|
|
.Sh HISTORY
|
|
The
|
|
.Fn futex
|
|
syscall first appeared in Linux 2.5.7 and was added to
|
|
.Ox 6.2 .
|