.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_submit 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
.SH NAME
io_uring_submit \- submit requests to the submission queue
.SH SYNOPSIS
.nf
.B #include <liburing.h>
.PP
.BI "int io_uring_submit(struct io_uring *" ring ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_submit (3)
function submits the next events to the submission queue belonging to the
.IR ring .

After the caller retrieves a submission queue entry (SQE) with
.BR io_uring_get_sqe (3)
and prepares the SQE using one of the provided helpers, it can be submitted with
.BR io_uring_submit (3) .

.SH RETURN VALUE
On success
.BR io_uring_submit (3)
returns the number of submitted submission queue entries, if SQPOLL is not used.
If SQPOLL is used, the return value may report a higher number of submitted
entries than actually submitted. If the the user requires accurate information
about how many submission queue entries have been successfully submitted, while
using SQPOLL, the user must fall back to repeatedly submitting a single submission
queue entry. On failure it returns
.BR -errno .
.SH NOTES
For any request that passes in data in a struct, that data must remain
valid until the request has been successfully submitted. It need not remain
valid until completion. Once a request has been submitted, the in-kernel
state is stable. Very early kernels (5.4 and earlier) required state to be
stable until the completion occurred. Applications can test for this
behavior by inspecting the
.B IORING_FEAT_SUBMIT_STABLE
flag passed back from
.BR io_uring_queue_init_params (3).
In general, the man pages for the individual prep helpers will have a note
mentioning this fact as well, if required for the given command.
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_submit_and_wait (3),
.BR io_uring_submit_and_wait_timeout (3)