# io_uring_prep_recvmsg_multishot

## NAME



           io_uring_prep_recvmsg - prepare a recvmsg request
    


## SYNOPSIS



           **#include <sys/types.h>**
           **#include <sys/socket.h>**
           **#include <liburing.h>**
    
           **void io_uring_prep_recvmsg(struct io_uring_sqe ***_sqe_**,**
                                      **int** _fd_**,**
                                      **struct msghdr ***_msg_**,**
                                      **unsigned** _flags_**);**
    
           **void io_uring_prep_recvmsg_multishot(struct io_uring_sqe ***_sqe_**,**
                                                **int** _fd_**,**
                                                **struct msghdr ***_msg_**,**
                                                **unsigned** _flags_**);**
    


## DESCRIPTION



           The io_uring_prep_recvmsg(3) function prepares a recvmsg request.
           The submission queue entry _sqe_ is setup to use the file descriptor
           _fd_ to start receiving the data indicated by _msg_ with the
           recvmsg(2) defined flags in the _flags_ argument.
    
           This function prepares an async recvmsg(2) request. See that man
           page for details on the arguments specified to this prep helper.
    
           The multishot version allows the application to issue a single
           receive request, which repeatedly posts a CQE when data is
           available. It requires the **IOSQE_BUFFER_SELECT** flag to be set and
           no **MSG_WAITALL** flag to be set.  Therefore each CQE will take a
           buffer out of a provided buffer pool for receiving.  The
           application should check the flags of each CQE, regardless of its
           result.  If a posted CQE does not have the **IORING_CQE_F_MORE** flag
           set, then the multishot receive is done and the application must
           issue a new request if it still wishes to receive data from the
           socket.
    
           Unlike recvmsg(2), multishot recvmsg will prepend a _struct_
           _io_uring_recvmsg_out_ which describes the layout of the rest of the
           buffer in combination with the initial _struct msghdr_ submitted
           with the request. See io_uring_recvmsg_out(3) for more information
           on accessing the data.
    
           Multishot variants are available since kernel 6.0.
    
           After calling this function, additional io_uring internal modifier
           flags may be set in the SQE _ioprio_ field. The following flags are
           supported:
    
           **IORING_RECVSEND_POLL_FIRST**
                  If set, io_uring will assume the socket is currently empty
                  and attempting to receive data will be unsuccessful. For
                  this case, io_uring will arm internal poll and trigger a
                  receive of the data when the socket has data to be read.
                  This initial receive attempt can be wasteful for the case
                  where the socket is expected to be empty, setting this flag
                  will bypass the initial receive attempt and go straight to
                  arming poll. If poll does indicate that data is ready to be
                  received, the operation will proceed.
    
                  Can be used with the CQE **IORING_CQE_F_SOCK_NONEMPTY** flag,
                  which io_uring will set on CQEs after a recv(2) or
                  recvmsg(2) operation. If set, the socket still had data to
                  be read after the operation completed. Both these flags are
                  available since 5.19.
    


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


## NOTES



           As with any request that passes in data in a struct, that data
           must remain valid until the request has been successfully
           submitted. It need not remain valid until completion. Once a
           request has been submitted, the in-kernel state is stable. Very
           early kernels (5.4 and earlier) required state to be stable until
           the completion occurred. Applications can test for this behavior
           by inspecting the **IORING_FEAT_SUBMIT_STABLE** flag passed back from
           io_uring_queue_init_params(3).
    


* * *