1.\" $OpenBSD: futex.2,v 1.6 2021/05/26 18:11:59 kettenis Exp $ 2.\" 3.\" Copyright (c) 2017 Martin Pieuchot 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 26 2021 $ 18.Dt FUTEX 2 19.Os 20.Sh NAME 21.Nm futex 22.Nd fast userspace locking primitive 23.Sh SYNOPSIS 24.In sys/time.h 25.In sys/futex.h 26.Ft int 27.Fo futex 28.Fa "volatile uint32_t *uaddr" 29.Fa "int op" 30.Fa "int val" 31.Fa "const struct timespec *timeout" 32.Fa "volatile uint32_t *uaddr2" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn futex 37syscall provides sleep and wakeup primitives related to a particular address. 38.Pp 39Three 40.Fa op 41operations are currently supported: 42.Bl -tag -width FUTEX_REQUEUE -offset indent 43.It Dv FUTEX_WAIT 44If 45.Fa val 46is equal to 47.Pf * Fa uaddr , 48the calling thread is blocked on the 49.Dq wait channel 50identified by 51.Fa uaddr 52until 53.Fa timeout 54expires or until another thread issues a 55.Dv FUTEX_WAKE 56or 57.Dv FUTEX_REQUEUE 58operation with the same 59.Fa uaddr 60address. 61.Fa uaddr2 62is ignored. 63.It Dv FUTEX_WAKE 64Unblocks 65.Fa val 66threads sleeping on the 67wait channel identified by 68.Fa uaddr . 69.Fa timeout 70and 71.Fa uaddr2 72are ignored. 73.It Dv FUTEX_REQUEUE 74Similar to 75.Dv FUTEX_WAKE 76but also requeue remaining threads from the wait channel 77.Fa uaddr 78to 79.Fa uaddr2 . 80In this case, pass 81.Fa "uint32_t val2" 82as the fourth argument instead of 83.Fa timeout . 84At most that number of threads is requeued. 85.El 86.Sh RETURN VALUES 87For 88.Dv FUTEX_WAKE 89and 90.Dv FUTEX_REQUEUE , 91.Fn futex 92returns the number of woken threads. 93.Pp 94For 95.Dv FUTEX_WAIT , 96.Fn futex 97returns zero if woken by a matching 98.Dv FUTEX_WAKE 99or 100.Dv FUTEX_REQUEUE 101call. 102Otherwise, a value of \-1 is returned and 103.Va errno 104is set to indicate the error. 105.Sh ERRORS 106.Fn futex 107will fail if: 108.Bl -tag -width Er 109.It Bq Er ENOSYS 110The 111.Fa op 112argument is invalid. 113.It Bq Er EFAULT 114The userspace address 115.Fa uaddr 116is invalid. 117.It Bq Er EAGAIN 118The value pointed to by 119.Fa uaddr 120is not the same as the expected value 121.Fa val . 122.It Bq Er EINVAL 123The 124.Fa timeout 125specified a second value less than zero, 126or a nanosecond value less than zero or greater than or equal to 1000 million. 127.It Bq Er ETIMEDOUT 128The 129.Fa timeout 130expired before the thread was woken up 131.It Bq Er EINTR 132A signal arrived. 133.It Bq Er ECANCELED 134A signal arrived and 135.Fa SA_RESTART 136was set. 137.El 138.Sh SEE ALSO 139.Xr sigaction 2 , 140.Xr pthread_cond_wait 3 , 141.Xr pthread_mutex_lock 3 , 142.Xr tsleep 9 143.Rs 144.%A Ulrich Drepper 145.%T Futexes Are Tricky 146.%U https://www.akkadia.org/drepper/futex.pdf 147.%D November 5, 2011 148.Re 149.Sh HISTORY 150The 151.Fn futex 152syscall first appeared in Linux 2.5.7 and was added to 153.Ox 6.2 . 154