.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_wait_cqe_timeout 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
.SH NAME
io_uring_wait_cqe_timeout \- wait for one io_uring completion event with timeout
.SH SYNOPSIS
.nf
.B #include <liburing.h>
.PP
.BI "int io_uring_wait_cqe_timeout(struct io_uring *" ring ","
.BI "                              struct io_uring_cqe **" cqe_ptr ","
.BI "                              struct __kernel_timespec *" ts ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_wait_cqe_timeout (3)
function waits for one IO completion to be available from the queue belonging
to the
.I ring
param, waiting for it if necessary or until the timeout
.I ts
expires. If an event is already available in the ring when invoked, no waiting
will occur.

The
.I cqe_ptr
param is filled in on success.

If
.I ts
is specified and an older kernel without
.B IORING_FEAT_EXT_ARG
is used, the application does not need to call
.BR io_uring_submit (3)
before calling
.BR io_uring_wait_cqes (3).
For newer kernels with that feature flag set, there is no implied submit
when waiting for a request.

If
.I ts
is
.B NULL ,
then this behaves like
.BR io_uring_wait_cqe (3)
in that it will wait forever for an event.

.SH RETURN VALUE
On success
.BR io_uring_wait_cqe_timeout (3)
returns 0 and the cqe_ptr param is filled in. On failure it returns
.BR -errno .
The return value indicates the result of waiting for a CQE, and it has no
relation to the CQE result itself.
.SH SEE ALSO
.BR io_uring_submit (3),
.BR io_uring_wait_cqes (3),
.BR io_uring_wait_cqe (3)