1io_uring_prep_recv(3)           liburing Manual          io_uring_prep_recv(3)
2
3
4

NAME

6       io_uring_prep_recv - prepare a recv request
7

SYNOPSIS

9       #include <liburing.h>
10
11       void io_uring_prep_recv(struct io_uring_sqe *sqe,
12                               int sockfd,
13                               void *buf,
14                               size_t len,
15                               int flags);
16
17       void io_uring_prep_recv_multishot(struct io_uring_sqe *sqe,
18                                         int sockfd,
19                                         void *buf,
20                                         size_t len,
21                                         int flags);
22

DESCRIPTION

24       The io_uring_prep_recv(3) function prepares a recv request. The submis‐
25       sion queue entry sqe is setup to use  the  file  descriptor  sockfd  to
26       start  receiving  the data into the buffer destination buf of size size
27       and with modifier flags flags.
28
29       This function prepares an async recv(2) request. See that man page  for
30       details on the arguments specified to this prep helper.
31
32       The  multishot version allows the application to issue a single receive
33       request, which repeatedly posts a CQE when data is  available.  It  re‐
34       quires  length  to be 0 , the IOSQE_BUFFER_SELECT flag to be set and no
35       MSG_WAITALL flag to be set.  Therefore each CQE will take a buffer  out
36       of  a provided buffer pool for receiving.  The application should check
37       the flags of each CQE, regardless of it's result.  If a posted CQE does
38       not have the IORING_CQE_F_MORE flag set then the multishot receive will
39       be done and the application should  issue  a  new  request.   Multishot
40       variants are available since kernel 6.0.
41
42
43       After  calling  this  function,  additional  io_uring internal modifier
44       flags may be set in the SQE ioprio field. The following flags are  sup‐
45       ported:
46
47       IORING_RECVSEND_POLL_FIRST
48              If  set,  io_uring will assume the socket is currently empty and
49              attempting to receive data will be unsuccessful. For this  case,
50              io_uring  will  arm  internal  poll and trigger a receive of the
51              data when the socket has data to be read.  This initial  receive
52              attempt  can  be  wasteful  for the case where the socket is ex‐
53              pected to be empty, setting this flag will  bypass  the  initial
54              receive attempt and go straight to arming poll. If poll does in‐
55              dicate that data is ready to be  received,  the  operation  will
56              proceed.
57
58              Can  be used with the CQE IORING_CQE_F_SOCK_NONEMPTY flag, which
59              io_uring will set on CQEs after a recv(2) or  recvmsg(2)  opera‐
60              tion. If set, the socket still had data to be read after the op‐
61              eration completed. Both these flags are available since 5.19.
62

RETURN VALUE

64       None
65

ERRORS

67       The CQE res field will contain the result of the operation. See the re‐
68       lated man page for details on possible values. Note that where synchro‐
69       nous system calls will return -1 on failure and set errno to the actual
70       error value, io_uring never uses errno.  Instead it returns the negated
71       errno directly in the CQE res field.
72

SEE ALSO

74       io_uring_get_sqe(3), io_uring_submit(3), recv(2)
75
76
77
78liburing-2.2                    March 12, 2022           io_uring_prep_recv(3)
Impressum