.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_prep_futex_wake 3 "Sep 29, 2023" "liburing-2.5" "liburing Manual"
.SH NAME
io_uring_prep_futex_wake \- prepare a futex wake request
.SH SYNOPSIS
.nf
.B #include <linux/futex.h>
.B #include <unistd.h>
.B #include <liburing.h>
.PP
.BI "void io_uring_prep_futex_wake(struct io_uring_sqe *" sqe ","
.BI "                              uint32_t *" futex ","
.BI "                              uint64_t " val ","
.BI "                              uint64_t " mask ","
.BI "                              uint32_t " futex_flags ","
.BI "                              unsigned int " flags ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_prep_futex_wake (3)
function prepares a futex wake request. The submission queue entry
.I sqe
is setup for waking any waiters on the futex indicated by
.I futex
and at most
.I val
futexes.
.I futex_flags
indicates the
.BR futex2 (2)
modifier flags, and io_uring futex flags of
.I flags .

If a given bitset for who to wake is desired, then that must be set in
.I mask .
Use
.B FUTEX_BITSET_MATCH_ANY
to match any waiter on the given futex.

.I flags
are currently unused and hence
.B 0
must be passed.

This function prepares an async
.BR futex (2)
wake request. See that man page for details. Note that the io_uring futex
wake request is similar to the
.B FUTEX_WAKE_BITSET
operation, as
.B FUTEX_WAKE
is a strict subset of that.

.SH RETURN VALUE
None
.SH ERRORS
The CQE
.I res
field will contain the result of the operation. On success, the value will be
the index into
.I futexv
which received a wakeup. See the related man page for details on possible
values for errors. Note that where synchronous system calls will return
.B -1
on failure and set
.I errno
to the actual error value, io_uring never uses
.IR errno .
Instead it returns the negated
.I errno
directly in the CQE
.I res
field.
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
.BR io_uring_prep_futex_wait (3),
.BR io_uring_prep_futex_waitv (3),
.BR futex (2)
.BR futex2 (2)