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

NAME

6       io_uring_prep_readv2 - prepare vector I/O read request with flags
7

SYNOPSIS

9       #include <sys/uio.h>
10       #include <liburing.h>
11
12       void io_uring_prep_readv2(struct io_uring_sqe *sqe,
13                                 int fd,
14                                 const struct iovec *iovecs,
15                                 unsigned nr_vecs,
16                                 __u64 offset,
17                                 int flags);
18

DESCRIPTION

20       The  io_uring_prep_readv2(3)  prepares  a vectored IO read request. The
21       submission queue entry sqe is setup to use the file  descriptor  fd  to
22       start  reading  nr_vecs  into the iovecs array at the specified offset.
23       The behavior of the function can be controlled with the  flags  parame‐
24       ter.
25
26       Supported values for flags are:
27
28       RWF_HIPRI
29              High priority request, poll if possible
30
31       RWF_DSYNC
32              per-IO O_DSYNC
33
34       RWF_SYNC
35              per-IO O_SYNC
36
37       RWF_NOWAIT
38              per-IO, return -EAGAIN if operation would block
39
40       RWF_APPEND
41              per-IO O_APPEND
42
43
44       On files that support seeking, if the offset is set to -1, the read op‐
45       eration commences at the file offset, and the  file  offset  is  incre‐
46       mented  by the number of bytes read. See read(2) for more details. Note
47       that for an async API, reading and updating the current file offset may
48       result  in unpredictable behavior, unless access to the file is serial‐
49       ized. It is not encouraged to use this feature,  if  it's  possible  to
50       provide the desired IO offset from the application or library.
51
52       On files that are not capable of seeking, the offset must be 0 or -1.
53
54       After  the  read has been prepared, it can be submitted with one of the
55       submit functions.
56
57

RETURN VALUE

59       None
60

ERRORS

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

NOTES

69       Unless an application explicitly needs to pass in more than one  iovec,
70       it  is  more  efficient  to  use io_uring_prep_read(3) rather than this
71       function, as no state has to be maintained for a  non-vectored  IO  re‐
72       quest.   As with any request that passes in data in a struct, that data
73       must remain valid until the request has been successfully submitted. It
74       need not remain valid until completion. Once a request has been submit‐
75       ted, the in-kernel state is stable. Very early kernels  (5.4  and  ear‐
76       lier) required state to be stable until the completion occurred. Appli‐
77       cations can test for this behavior by inspecting  the  IORING_FEAT_SUB‐
78       MIT_STABLE flag passed back from io_uring_queue_init_params(3).
79

SEE ALSO

81       io_uring_get_sqe(3),   io_uring_prep_read(3),   io_uring_prep_readv(3),
82       io_uring_submit(3)
83
84
85
86liburing-2.1                   November 15, 2021       io_uring_prep_readv2(3)