io\_uring\_prep\_futex\_wait(3) liburing Manual io\_uring\_prep\_futex\_wait(3)

# [NAME](#NAME)

io\_uring\_prep\_futex\_wait - prepare a futex wait request

# [SYNOPSIS](#SYNOPSIS)

```
#include <linux/futex.h>
#include <unistd.h>
#include <liburing.h>
```

```
void io_uring_prep_futex_wait(struct io_uring_sqe *sqe,
                              const uint32_t *futex,
                              uint64_t val,
                              uint64_t mask,
                              uint32_t futex_flags,
                              unsigned int flags);
```

# [DESCRIPTION](#DESCRIPTION)

The [**io\_uring\_prep\_futex\_wait**(3)](/man/os/liburing/io_uring_prep_futex_wait.3) function prepares a futex wait request. The submission queue entry *sqe* is setup for waiting on a futex at address *futex* and which still has the value *val* and with [**futex2**(2)](/man/os/liburing/futex2.2) flags of *futex\_flags* and io\_uring futex flags of *flags .*

*mask* can be set to a specific bitset mask, which will be matched by the waking side to decide who to wake up. To always get woken, an application may use **FUTEX\_BITSET\_MATCH\_ANY .**

*futex\_flags* follows the [**futex2**(2)](/man/os/liburing/futex2.2) flags, not the [**futex**(2)](/man/os/liburing/futex.2) v1 interface flags.

*flags* are currently unused and hence **0** must be passed.

This function prepares an async [**futex**(2)](/man/os/liburing/futex.2) wait request. See that man page for details. Note that the io\_uring futex wait request is similar to the **FUTEX\_WAIT\_BITSET** operation, as **FUTEX\_WAIT** is a strict subset of that.

Available since kernel 6.7.

# [RETURN VALUE](#RETURN_VALUE)

None

# [ERRORS](#ERRORS)

The CQE *res* field will contain the result of the operation. See the related man page for details on possible values. Note that where synchronous system calls will return **-1** on failure and set *errno* to the actual error value, io\_uring never uses *errno*. Instead it returns the negated *errno* directly in the CQE *res* field.

# [NOTES](#NOTES)

Unlike the sync futex syscalls that wait on a futex, io\_uring does not support passing in a timeout for the request. Instead, applications are encouraged to use a linked timeout to abort the futex request at a given time, if desired.

# [SEE ALSO](#SEE_ALSO)

[**io\_uring\_get\_sqe**(3)](/man/os/liburing/io_uring_get_sqe.3), [**io\_uring\_submit**(3)](/man/os/liburing/io_uring_submit.3), [**io\_uring\_prep\_futex\_waitv**(3)](/man/os/liburing/io_uring_prep_futex_waitv.3), [**io\_uring\_prep\_futex\_wake**(3)](/man/os/liburing/io_uring_prep_futex_wake.3), [**io\_uring\_prep\_link\_timeout**(3)](/man/os/liburing/io_uring_prep_link_timeout.3), [**futex**(2)](/man/os/liburing/futex.2) [**futex2**(2)](/man/os/liburing/futex2.2)

September 29, 2023 liburing-2.5

---

Document: io_uring_prep_futex_wait(3) from liburing 2.15-r4 (Chainguard OS)
Source: https://github.com/axboe/liburing.git