87 lines
3.4 KiB
Groff
87 lines
3.4 KiB
Groff
|
.\" 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)
|