|
HTML rendering created 2023-12-22 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 Manualio_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 nbytes into a buffer from
the provided buffer group with ID buf_group at the specified
offset.
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.
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 2023-12-22. (At that
time, the date of the most recent commit that was found in the
repository was 2023-12-19.) 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 2023-12-22 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. |
|