io_uring_prep_read_multishot(3) — Linux manual page

io_uring_pr...d_multishot(3) liburing Manualio_uring_pr...d_multishot(3)

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)

COLOPHON

       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 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-03.)  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)

---