NAME

       io_uring_prep_recv - prepare a recv request

SYNOPSIS

       #include <liburing.h>

       void io_uring_prep_recv(struct io_uring_sqe *sqe,
                               int sockfd,
                               void *buf,
                               size_t len,
                               int flags);

       void io_uring_prep_recv_multishot(struct io_uring_sqe *sqe,
                                         int sockfd,
                                         void *buf,
                                         size_t len,
                                         int flags);

DESCRIPTION

       The  io_uring_prep_recv(3)  function  prepares a recv request. The submission queue entry sqe is setup to
       use the file descriptor sockfd to start receiving the data into the destination buffer buf  of  size  len
       and with modifier flags flags.

       This function prepares an async recv(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 length to be 0, 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 will be done and the
       application should issue a new request.  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.

       IORING_RECVSEND_BUNDLE
              If set and provided buffers are used with IOSQE_BUFFER_SELECT , the receive operation will attempt
              to fill multiple buffers with rather than just pick a single buffer to fill. To  receive  multiple
              buffers in a single receive, the buffer group ID set in the SQE must be of the ring provided type.
              If set, the CQE res field indicates the total number of bytes received, and the buffer ID returned
              in  the  CQE flags field indicates the first buffer in the receive operation. The application must
              process the indicated initial buffer ID and until all res bytes have been seen to  know  which  is
              the  last  buffer  in  the  receive  operation.   The buffers consumed will be contiguous from the
              initial buffer, in the order in which they appear in the buffer ring.  The  CQE  struct  does  not
              contain  the  position  of  the  buffer in the buffer ring, therefore in order to identify buffers
              contained by the bundle, it is advised to maintain the cached head index  per  buffer  ring.  This
              uint16_t  index  represents  the  position of the next buffer to be consumed within the ring. Upon
              completion of a receive operation, the  cached  head  index  should  be  incremented  accordingly.
              Receiving  in  bundles  can  improve  performance when more than one chunk of data is available to
              receive, by eliminating redundant round trips through the networking stack. Receive bundles may be
              used by both single shot and multishot receive operations. Note that, internally, bundles rely  on
              the  networking  stack passing back how much data is left in the socket after the initial receive.
              This means that the initial receive may contain less buffers than  what  is  available,  with  the
              followup receive(s) containing more buffers. Available since 6.10.

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_submit(3), io_uring_buf_ring_init(3), io_uring_buf_ring_add(3), recv(2)

liburing-2.2                                     March 12, 2022                            io_uring_prep_recv(3)