|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | SEE ALSO | COLOPHON |
|
|
|
io_uring_pr...d_multishot(3) liburing Manual io_uring_pr...d_multishot(3)
io_uring_prep_read_multishot - prepare I/O read multishot request
#include <liburing.h>
void io_uring_prep_read_multishot(struct io_uring_sqe *sqe,
int fd,
unsigned nbytes,
__u64 offset,
int buf_group);
The io_uring_prep_read_multishot(3) helper prepares an IO read
multishot request. The submission queue entry sqe is setup to use
the file descriptor fd to start reading into a buffer from the
provided buffer group with ID buf_group at the specified offset.
nbytes must be set to zero, as the size read will be given by the
size of the buffers in the indicated buffer group IO.
On files that are not capable of seeking, the offset must be 0 or
-1.
If nbytes exceeds the size of the buffers in the specified buffer
group, or if nbytes is 0 , then the size of the buffer in that
group will be used for the transfer.
A multishot read request will repeatedly trigger a completion
event whenever data is available to read from the file. Because of
that, this type of request can only be used with a file type that
is pollable. Examples of that include pipes, tun devices, etc. If
used with a regular file, or a wrong file type in general, the
request will fail with -EBADFD in the CQE res field.
Since multishot requests repeatedly trigger completion events as
data arrives, it must be used with provided buffers. With provided
buffers, the application provides buffers to io_uring upfront, and
then the kernel picks a buffer from the specified group in
buf_group when the request is ready to transfer data.
A multishot request will persist as long as no errors are
encountered doing handling of the request. For each CQE posted on
behalf of this request, the CQE flags will have IORING_CQE_F_MORE
set if the application should expect more completions from this
request. If this flag isn't set, then that signifies termination
of the multishot read request.
After the read has been prepared it can be submitted with one of
the submit functions.
Available since 6.7.
None
The CQE res field will contain the result of the operation. See
the related man page for details on possible values. Note that
where synchronous system calls will return -1 on failure and set
errno to the actual error value, io_uring never uses errno.
Instead it returns the negated errno directly in the CQE res
field.
io_uring_get_sqe(3), io_uring_prep_read(3),
io_uring_buf_ring_init(3) io_uring_buf_ring_add(3),
io_uring_submit(3)
This page is part of the liburing (A library for io_uring)
project. Information about the project can be found at
⟨https://github.com/axboe/liburing⟩. If you have a bug report for
this manual page, send it to io-uring@vger.kernel.org. This page
was obtained from the project's upstream Git repository
⟨https://github.com/axboe/liburing⟩ on 2025-08-11. (At that time,
the date of the most recent commit that was found in the
repository was 2025-08-02.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
liburing-2.5 September 12, 2023io_uring_pr...d_multishot(3)
Pages that refer to this page: io_uring_prep_read_multishot(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|