oracular (3) io_uring_prep_recvmsg.3.gz

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)