Prepare a recvmsg request
# DESCRIPTION
The [io_uring_prep_recvmsg] 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](https://man7.org/linux/man-pages/man2/recvmsg.2.html) defined flags in the *flags* argument.
This function prepares an async [recvmsg](https://man7.org/linux/man-pages/man2/recvmsg.2.html) 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](https://man7.org/linux/man-pages/man2/recvmsg.2.html), 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] 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](https://man7.org/linux/man-pages/man2/recv.2.html) or [recvmsg](https://man7.org/linux/man-pages/man2/recvmsg.2.html)
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].
Despite accepting an array of iovec's with a size_t number of bytes
each, these functions can transfer at most INT_MAX bytes per call (the
maximum for the underlying syscall interface).
# SEE ALSO
[io_uring_get_sqe], [io_uring_submit],
[io_uring_buf_ring_init], [io_uring_buf_ring_add],
[recvmsg](https://man7.org/linux/man-pages/man2/recvmsg.2.html)