diff options
Diffstat (limited to 'man/io_uring_sqe_set_flags.3')
| -rw-r--r-- | man/io_uring_sqe_set_flags.3 | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/man/io_uring_sqe_set_flags.3 b/man/io_uring_sqe_set_flags.3 new file mode 100644 index 0000000..75e836b --- /dev/null +++ b/man/io_uring_sqe_set_flags.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sqe_set_flags "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sqe_set_flags \- set flags for submission queue entry +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_sqe_set_flags(struct io_uring_sqe *" sqe "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_sqe_set_flags (3) +function allows the caller to change the behavior of the submission queue entry +by specifying flags. It enables the +.I flags +belonging to the +.I sqe +submission queue entry param. + +.I flags +is a bit mask of 0 or more of the following values ORed together: +.TP +.B IOSQE_FIXED_FILE +The file descriptor in the SQE refers to the index of a previously registered +file or direct file descriptor, not a normal file descriptor. +.TP +.B IOSQE_ASYNC +Normal operation for io_uring is to try and issue an sqe as non-blocking first, +and if that fails, execute it in an async manner. To support more efficient +overlapped operation of requests that the application knows/assumes will +always (or most of the time) block, the application can ask for an sqe to be +issued async from the start. Note that this flag immediately causes the SQE +to be offloaded to an async helper thread with no initial non-blocking attempt. +This may be less efficient and should not be used sporadically. +.TP +.B IOSQE_IO_LINK +When this flag is specified, the SQE forms a link with the next SQE in the +submission ring. That next SQE will not be started before the previous request +completes. This, in effect, forms a chain of SQEs, which can be arbitrarily +long. The tail of the chain is denoted by the first SQE that does not have this +flag set. Chains are not supported across submission boundaries. Even if the +last SQE in a submission has this flag set, it will still terminate the current +chain. This flag has no effect on previous SQE submissions, nor does it impact +SQEs that are outside of the chain tail. This means that multiple chains can be +executing in parallel, or chains and individual SQEs. Only members inside the +chain are serialized. A chain of SQEs will be broken if any request in that +chain ends in error. +.TP +.B IOSQE_IO_HARDLINK +Like +.B IOSQE_IO_LINK , +except the links aren't severed if an error or unexpected result occurs. +.TP +.B IOSQE_IO_DRAIN +When this flag is specified, the SQE will not be started before previously +submitted SQEs have completed, and new SQEs will not be started before this +one completes. +.TP +.B IOSQE_CQE_SKIP_SUCCESS +Request that no CQE be generated for this request, if it completes successfully. +This can be useful in cases where the application doesn't need to know when +a specific request completed, if it completed succesfully. +.TP +.B IOSQE_BUFFER_SELECT +If set, and if the request types supports it, select an IO buffer from the +indicated buffer group. This can be used with requests that read or receive +data from a file or socket, where buffer selection is deferred until the kernel +is ready to transfer data, instead of when the IO is originally submitted. The +application must also set the +.I buf_group +field in the SQE, indicating which previously registered buffer group to select +a buffer from. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_register (3) +.BR io_uring_register_buffers (3) +.BR io_uring_register_buf_ring (3) |