improve sendzc man pages
cover improve sendzc man pages
Add a note about failing zc requests with -EOPNOTSUPP and add a paragraph about IORING_RECVSEND_FIXED_BUF.
Pavel Begunkov (3):
io_uring_enter.2: add sendzc -EOPNOTSUPP note io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF
man/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 2 deletions(-)
Signature · 1 line
2.38.0
PATCH 1/3 io_uring_enter.2: add sendzc -EOPNOTSUPP note
--- man/io_uring_enter.2 | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-)
man/io_uring_enter.2 +5 -2
@@ -1098,8 +1098,11 @@ Available since 5.19. Issue the zerocopy equivalent of a .BR send(2) system call. Similar to IORING_OP_SEND, but tries to avoid making intermediate -copies of data. Zerocopy execution is not guaranteed and it may fall back to -copying. +copies of data. Zerocopy execution is not guaranteed and may fall back to +copying. The request may also fail with +.B -EOPNOTSUPP, +for instance when a protocol doesn't support zerocopy in the first place, in +which case users are recommended to use copying sends instead. The .I flags
Signature · 1 line
2.38.0
PATCH 2/3 io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST
In reply to Pavel Begunkov--- man/io_uring_enter.2 | 85 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+)
man/io_uring_enter.2 +85 -0
@@ -394,12 +394,46 @@ holds the flags associated with the system call. See also .BR sendmsg (2) for the general description of the related system call. Available since 5.3. +This command also supports the following modifiers in +.I ioprio: + +.PP +.in +12 +.B IORING_RECVSEND_POLL_FIRST +If set, io_uring will assume the socket is currently full and attempting to +send data will be unsuccessful. For this case, io_uring will arm internal +poll and trigger a send of the data when there is enough space available. +This initial send attempt can be wasteful for the case where the socket +is expected to be full, setting this flag will bypass the initial send +attempt and go straight to arming poll. If poll does indicate that data can +be sent, the operation will proceed. +.EE +.in +.PP + .TP .B IORING_OP_RECVMSG Works just like IORING_OP_SENDMSG, except for .BR recvmsg(2) instead. See the description of IORING_OP_SENDMSG. Available since 5.3. +This command also supports the following modifiers in +.I ioprio: + +.PP +.in +12 +.B 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. +.EE +.in +.PP + .TP .B IORING_OP_SEND Issue the equivalent of a
@@ -416,12 +450,46 @@ holds the flags associated with the system call. See also .BR send(2) for the general description of the related system call. Available since 5.6. +This command also supports the following modifiers in +.I ioprio: + +.PP +.in +12 +.B IORING_RECVSEND_POLL_FIRST +If set, io_uring will assume the socket is currently full and attempting to +send data will be unsuccessful. For this case, io_uring will arm internal +poll and trigger a send of the data when there is enough space available. +This initial send attempt can be wasteful for the case where the socket +is expected to be full, setting this flag will bypass the initial send +attempt and go straight to arming poll. If poll does indicate that data can +be sent, the operation will proceed. +.EE +.in +.PP + .TP .B IORING_OP_RECV Works just like IORING_OP_SEND, except for .BR recv(2) instead. See the description of IORING_OP_SEND. Available since 5.6. +This command also supports the following modifiers in +.I ioprio: + +.PP +.in +12 +.B 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. +.EE +.in +.PP + .TP .B IORING_OP_TIMEOUT This command will register a timeout operation. The
@@ -1150,6 +1218,23 @@ system call equivalent. Available since 6.0. +This command also supports the following modifiers in +.I ioprio: + +.PP +.in +12 +.B IORING_RECVSEND_POLL_FIRST +If set, io_uring will assume the socket is currently full and attempting to +send data will be unsuccessful. For this case, io_uring will arm internal +poll and trigger a send of the data when there is enough space available. +This initial send attempt can be wasteful for the case where the socket +is expected to be full, setting this flag will bypass the initial send +attempt and go straight to arming poll. If poll does indicate that data can +be sent, the operation will proceed. +.EE +.in +.PP + .PP The .I flags
Signature · 1 line
2.38.0
PATCH 3/3 io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF
In reply to Pavel Begunkov--- man/io_uring_enter.2 | 6 ++++++ 1 file changed, 6 insertions(+)
man/io_uring_enter.2 +6 -0
@@ -1231,6 +1231,12 @@ This initial send attempt can be wasteful for the case where the socket is expected to be full, setting this flag will bypass the initial send attempt and go straight to arming poll. If poll does indicate that data can be sent, the operation will proceed. + +.B IORING_RECVSEND_FIXED_BUF +instructs to use a pre-mapped buffer. If set, the +.I buf_index +field should contain an index into an array of fixed buffers. See +io_uring_register(2) for details on how to setup a context for fixed buffer I/O. .EE .in .PP
Signature · 1 line
2.38.0
Jens Axboe
maintainerQuoted 10 lines · Pavel Begunkov
Add a note about failing zc requests with
-EOPNOTSUPPand add a paragraph aboutIORING_RECVSEND_FIXED_BUF.Pavel Begunkov (3):
io_uring_enter.2: add sendzc-EOPNOTSUPPnote io_uring_enter.2: documentIORING_RECVSEND_POLL_FIRSTio_uring_enter.2: documentIORING_RECVSEND_FIXED_BUFman/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 2 deletions(-)
Applied with minor edits, thanks!
Signature · 1 line
Jens Axboe