Add missing documentation for new multishot recvmsg API
Signed-off-by: Dylan Yudaken <dylany@xxxxxx>
---
man/io_uring_prep_recvmsg.3 | 30 +++++++++++
man/io_uring_prep_recvmsg_multishot.3 | 1 +
man/io_uring_recvmsg_cmsg_firsthdr.3 | 1 +
man/io_uring_recvmsg_cmsg_nexthdr.3 | 1 +
man/io_uring_recvmsg_name.3 | 1 +
man/io_uring_recvmsg_out.3 | 78 +++++++++++++++++++++++++++
man/io_uring_recvmsg_payload.3 | 1 +
man/io_uring_recvmsg_payload_length.3 | 1 +
man/io_uring_recvmsg_validate.3 | 1 +
9 files changed, 115 insertions(+)
create mode 120000 man/io_uring_prep_recvmsg_multishot.3
create mode 120000 man/io_uring_recvmsg_cmsg_firsthdr.3
create mode 120000 man/io_uring_recvmsg_cmsg_nexthdr.3
create mode 120000 man/io_uring_recvmsg_name.3
create mode 100644 man/io_uring_recvmsg_out.3
create mode 120000 man/io_uring_recvmsg_payload.3
create mode 120000 man/io_uring_recvmsg_payload_length.3
create mode 120000 man/io_uring_recvmsg_validate.3
diff --git a/man/io_uring_prep_recvmsg.3 b/man/io_uring_prep_recvmsg.3
index f64326be0a99..07096ee4826c 100644
--- a/man/io_uring_prep_recvmsg.3
+++ b/man/io_uring_prep_recvmsg.3
@@ -15,6 +15,11 @@ io_uring_prep_recvmsg \- prepare a recvmsg request
.BI " int " fd ","
.BI " struct msghdr *" msg ","
.BI " unsigned " flags ");"
+.PP
+.BI "void io_uring_prep_recvmsg_multishot(struct io_uring_sqe *" sqe ","
+.BI " int " fd ","
+.BI " struct msghdr *" msg ","
+.BI " unsigned " flags ");"
.fi
.SH DESCRIPTION
.PP
@@ -37,6 +42,31 @@ This function prepares an async
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
+.B IOSQE_BUFFER_SELECT
+flag to be set and no
+.B 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 it's result.
+If a posted CQE does not have the
+.B IORING_CQE_F_MORE
+flag set then the multishot receive will be done and the application should issue a
+new request.
+
+Unlike
+.BR recvmsg (2)
+, multishot recvmsg will prepend a
+.I struct io_uring_recvmsg_out
+which describes the layout of the rest of the buffer in combination with the initial
+.I struct msghdr
+submitted with the request. See
+.B io_uring_recvmsg_out (3)
+for more information on accessing the data.
+
+Multishot variants are available since kernel 5.20.
+
After calling this function, additional io_uring internal modifier flags
may be set in the SQE
.I ioprio
diff --git a/man/io_uring_prep_recvmsg_multishot.3 b/man/io_uring_prep_recvmsg_multishot.3
new file mode 120000
index 000000000000..cd9566f2c2be
--- /dev/null
+++ b/man/io_uring_prep_recvmsg_multishot.3
@@ -0,0 +1 @@
+io_uring_prep_recvmsg.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_cmsg_firsthdr.3 b/man/io_uring_recvmsg_cmsg_firsthdr.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_cmsg_firsthdr.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_cmsg_nexthdr.3 b/man/io_uring_recvmsg_cmsg_nexthdr.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_cmsg_nexthdr.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_name.3 b/man/io_uring_recvmsg_name.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_name.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_out.3 b/man/io_uring_recvmsg_out.3
new file mode 100644
index 000000000000..60f92619d566
--- /dev/null
+++ b/man/io_uring_recvmsg_out.3
@@ -0,0 +1,78 @@
+.\" Copyright (C), 2022 Dylan Yudaken <dylany@xxxxxx>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_recvmsg_out 3 "Julyu 26, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_recvmsg_out - access data from multishot recvmsg
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "struct io_uring_recvmsg_out *io_uring_recvmsg_validate(void *" buf ","
+.BI " int " buf_len ","
+.BI " struct msghdr *" msgh ");"
+.PP
+.BI "void *io_uring_recvmsg_name(struct io_uring_recvmsg_out *" o ");"
+.PP
+.BI "struct cmsghdr *io_uring_recvmsg_cmsg_firsthdr(struct io_uring_recvmsg_out * " o ","
+.BI " struct msghdr *" msgh ");"
+.BI "struct cmsghdr *io_uring_recvmsg_cmsg_nexthdr(struct io_uring_recvmsg_out * " o ","
+.BI " struct msghdr *" msgh ","
+.BI " struct cmsghdr *" cmsg ");"
+.PP
+.BI "void *io_uring_recvmsg_payload(struct io_uring_recvmsg_out * " o ","
+.BI " struct msghdr *" msgh ");"
+.BI "unsigned int io_uring_recvmsg_payload_length(struct io_uring_recvmsg_out *" o ","
+.BI " int " buf_len ","
+.BI " struct msghdr *" msgh ");"
+.PP
+.fi
+
+.SH DESCRIPTION
+
+These functions are used to access data in the payload delivered by
+.BR io_uring_prep_recv_multishot (3)
+.
+.PP
+.BR io_uring_recvmsg_validate (3)
+will validate a buffer delivered by
+.BR io_uring_prep_recv_multishot (3)
+and extract the
+.I io_uring_recvmsg_out
+if it is valid, returning a pointer to it or else NULL.
+.PP
+The structure is defined as follows:
+.PP
+.in +4n
+.EX
+
+struct io_uring_recvmsg_out {
+ __u32 namelen; /* Name byte count as would have been populated
+ * by recvmsg(2) */
+ __u32 controllen; /* Control byte count */
+ __u32 payloadlen; /* Payload byte count as would have been returned
+ * by recvmsg(2) */
+ __u32 flags; /* Flags result as would have been populated
+ * by recvmsg(2) */
+};
+
+.IP * 3
+.BR io_uring_recvmsg_name (3)
+returns a pointer to the name in the buffer.
+.IP *
+.BR io_uring_recvmsg_cmsg_firsthdr (3)
+returns a pointer to the first cmsg in the buffer, or NULL.
+.IP *
+.BR io_uring_recvmsg_cmsg_nexthdr (3)
+returns a pointer to the next cmsg in the buffer, or NULL.
+.IP *
+.BR io_uring_recvmsg_payload (3)
+returns a pointer to the payload in the buffer.
+.IP *
+.BR io_uring_recvmsg_payload_length (3)
+Calculates the usable payload length in bytes.
+
+
+.SH "SEE ALSO"
+.BR io_uring_prep_recv_multishot (3)
diff --git a/man/io_uring_recvmsg_payload.3 b/man/io_uring_recvmsg_payload.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_payload.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_payload_length.3 b/man/io_uring_recvmsg_payload_length.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_payload_length.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
diff --git a/man/io_uring_recvmsg_validate.3 b/man/io_uring_recvmsg_validate.3
new file mode 120000
index 000000000000..8eb17436288d
--- /dev/null
+++ b/man/io_uring_recvmsg_validate.3
@@ -0,0 +1 @@
+io_uring_recvmsg_out.3
\ No newline at end of file
--
2.30.2
