# io_uring_prep_read_multishot

## 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.
    
           Available since 6.7.
    


## 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.
    


* * *