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 will be done and the application should issue a
       new request.

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

SEE ALSO

       io_uring_get_sqe(3), io_uring_submit(3), recvmsg(2)

liburing-2.2                                     March 12, 2022                         io_uring_prep_recvmsg(3)