plucky (3) io_uring_prep_recv.3.gz

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)