| .\" 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) |
