1.\" $OpenBSD: futex.2,v 1.5 2019/01/18 05:06:37 cheloha 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: January 18 2019 $ 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, otherwise an error number is returned to indicate the error. 102.Sh ERRORS 103.Fn futex 104will fail if: 105.Bl -tag -width Er 106.It Bq Er ENOSYS 107The 108.Fa op 109argument is invalid. 110.It Bq Er EFAULT 111The userspace address 112.Fa uaddr 113is invalid. 114.It Bq Er EAGAIN 115The value pointed to by 116.Fa uaddr 117is not the same as the expected value 118.Fa val . 119.It Bq Er EINVAL 120The 121.Fa timeout 122specified a second value less than zero, 123or a nanosecond value less than zero or greater than or equal to 1000 million. 124.It Bq Er ETIMEDOUT 125The 126.Fa timeout 127expired before the thread was woken up 128.It Bq Er EINTR 129A signal arrived. 130.It Bq Er ECANCELED 131A signal arrived and 132.Fa SA_RESTART 133was set. 134.El 135.Sh SEE ALSO 136.Xr sigaction 2 , 137.Xr pthread_cond_wait 3 , 138.Xr pthread_mutex_lock 3 , 139.Xr tsleep 9 140.Rs 141.%A Ulrich Drepper 142.%T Futexes Are Tricky 143.%U https://www.akkadia.org/drepper/futex.pdf 144.%D November 5, 2011 145.Re 146.Sh HISTORY 147The 148.Fn futex 149syscall first appeared in Linux 2.5.7 and was added to 150.Ox 6.2 . 151