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.

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), recv(2)

liburing-2.2                                     March 12, 2022                            io_uring_prep_recv(3)