io_uring_prep_recvmsg_multishot(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | SEE ALSO | COLOPHON

io_uring_prep_recvmsg(3)     liburing Manual    io_uring_prep_recvmsg(3)

NAME         top

       io_uring_prep_recvmsg - prepare a recvmsg request

SYNOPSIS         top

       #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         top

       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         top

       None

ERRORS         top

       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         top

       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         top

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

COLOPHON         top

       This page is part of the liburing (A library for io_uring)
       project.  Information about the project can be found at 
       ⟨https://github.com/axboe/liburing⟩.  If you have a bug report for
       this manual page, send it to io-uring@vger.kernel.org.  This page
       was obtained from the project's upstream Git repository
       ⟨https://github.com/axboe/liburing⟩ on 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-19.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

liburing-2.2                 March 12, 2022     io_uring_prep_recvmsg(3)

Pages that refer to this page: io_uring_recvmsg_cmsg_firsthdr(3)io_uring_recvmsg_cmsg_nexthdr(3)io_uring_recvmsg_name(3)io_uring_recvmsg_out(3)io_uring_recvmsg_payload(3)io_uring_recvmsg_payload_length(3)io_uring_recvmsg_validate(3)