NAME¶

io_uring_prep_read_multishot - prepare I/O read multishot request

SYNOPSIS¶

#include <liburing.h>

void io_uring_prep_read_multishot(struct io_uring_sqe *sqe,
                                  int fd,
                                  unsigned nbytes,
                                  __u64 offset,
                                  int buf_group);

DESCRIPTION¶

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.

RETURN VALUE¶

None

ERRORS¶

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.

SEE ALSO¶

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)