Skip to contentSkip to conversation

add man pages for new apis

PATCH Applied Keith Busch 3 participants 5 messages Oct 22, 2025 io_uring

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 add man pages for new apis

From: Keith Busch <[email protected]>

Add manuals for getting 128b submission queue entries, and the new prep functions.

---
 man/io_uring_get_sqe128.3        | 59 ++++++++++++++++++++++++++++++++
 man/io_uring_prep_nop128.3       | 30 ++++++++++++++++
 man/io_uring_prep_uring_cmd.3    | 37 ++++++++++++++++++++
 man/io_uring_prep_uring_cmd128.3 | 38 ++++++++++++++++++++
 4 files changed, 164 insertions(+)
 create mode 100644 man/io_uring_get_sqe128.3
 create mode 100644 man/io_uring_prep_nop128.3
 create mode 100644 man/io_uring_prep_uring_cmd.3
 create mode 100644 man/io_uring_prep_uring_cmd128.3
man/io_uring_get_sqe128.3 new file +59 -0
new file mode 100644
index 00000000..25db811a
@@ -0,0 +1,59 @@
+.\" Copyright (C) 2020 Jens Axboe <[email protected]>
+.\" Copyright (C) 2020 Red Hat, Inc.
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_get_sqe128 3 "October 22, 2025" "liburing-0.7" "liburing Manual"
+.SH NAME
+io_uring_get_sqe128 \- get the next available 128-byte submission queue entry
+from the submission queue
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "struct io_uring_sqe *io_uring_get_sqe128(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_get_sqe128 (3)
+function gets the next available 128-byte submission queue entry from the
+submission queue belonging to the
+.I ring
+param.
+
+On success
+.BR io_uring_get_sqe128 (3)
+returns a pointer to the submission queue entry. On failure NULL is returned.
+
+If a submission queue entry is returned, it should be filled out via one of the
+prep functions such as
+.BR io_uring_prep_uring_cmd128 (3)
+and submitted via
+.BR io_uring_submit (3).
+
+Note that neither
+.BR io_uring_get_sqe128
+nor the prep functions set (or clear) the
+.B user_data
+field of the SQE. If the caller expects
+.BR io_uring_cqe_get_data (3)
+or
+.BR io_uring_cqe_get_data64 (3)
+to return valid data when reaping IO completions, either
+.BR io_uring_sqe_set_data (3)
+or
+.BR io_uring_sqe_set_data64 (3)
+.B MUST
+have been called before submitting the request.
+
+.SH RETURN VALUE
+.BR io_uring_get_sqe128 (3)
+returns a pointer to the next submission queue event on success and NULL on
+failure. If NULL is returned, the SQ ring either wasn't created with 128-byte
+entries (IORING_SETUP_SQE128 or IORING_SETUP_SQE_MIXED) or is currently full
+and entries must be submitted for processing before new ones can get allocated.
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_sqe_set_data (3)
man/io_uring_prep_nop128.3 new file +30 -0
new file mode 100644
index 00000000..4e0c012b
@@ -0,0 +1,30 @@
+.\" Copyright (C) 2022 Samuel Williams
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_nop128 3 "October 22, 2025" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_nop128 \- prepare a nop request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_nop128(struct io_uring_sqe *" sqe ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_nop128 (3)
+function prepares nop (no operation) request for a 128-byte entry. The
+submission queue entry
+.I sqe
+does not require any additional setup.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+None
+.SH SEE ALSO
+.BR io_uring_prep_nop (3),
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
man/io_uring_prep_uring_cmd.3 new file +37 -0
new file mode 100644
index 00000000..b8a95233
@@ -0,0 +1,37 @@
+.\" Copyright (C) 2022 Samuel Williams
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_uring_cmd 3 "October 22, 2025" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_uring_cmd \- prepare a uring_cmd request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_uring_cmd(struct io_uring_sqe *" sqe ","
+.BI "                                           int " cmd_op ","
+.BI "                                           int " fd ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_uring_cmd (3)
+function prepares uring_cmd (fd specific) request. The submission queue entry
+.I sqe
+is setup to use the filedescriptor
+.I fd
+to send file descriptor specific
+.IR cmd_op .
+
+The reserved fields are initialized to 0. Otherwise the caller has to set up
+any submission queue entry's operation specific fields.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+None
+.SH SEE ALSO
+.BR io_uring_prep_uring_cmd128 (3),
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
man/io_uring_prep_uring_cmd128.3 new file +38 -0
new file mode 100644
index 00000000..41853c51
@@ -0,0 +1,38 @@
+.\" Copyright (C) 2022 Samuel Williams
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_uring_cmd128 3 "October 22, 2025" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_uring_cmd128 \- prepare a uring_cmd request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_uring_cmd128(struct io_uring_sqe *" sqe ","
+.BI "                                           int " cmd_op ","
+.BI "                                           int " fd ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_uring_cmd128 (3)
+function prepares uring_cmd (fd specific) request for a 128 byte submission
+queue entry. The submission queue entry
+.I sqe
+is setup to use the filedescriptor
+.I fd
+to send file descriptor specific
+.IR cmd_op .
+
+The reserved fields are initialized to 0. Otherwise the caller has to set up
+any submission queue entry's operation specific fields.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+None
+.SH SEE ALSO
+.BR io_uring_prep_uring_cmd (3),
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
Signature · 1 line
2.47.3
maintainer
#1 lore raw
Quoted 4 lines · Keith Busch

From: Keith Busch <[email protected]>

Add manuals for getting 128b submission queue entries, and the new prep functions.

Thanks! A bit of too much copy pasting in terms of versions etc, but I can just fix those up. Also needs a bit of man formatting love, I'll do that too.

Signature · 1 line
Jens Axboe
#2 lore raw
Quoted 9 lines · Jens Axboe
Quoted 4 lines · Keith Busch

From: Keith Busch <[email protected]>

Add manuals for getting 128b submission queue entries, and the new prep functions.

Thanks! A bit of too much copy pasting in terms of versions etc, but I can just fix those up. Also needs a bit of man formatting love, I'll do that too.

Ah, thanks. man syntax is weird, I usually see projects generate them from a more friendly markup rather than committing their raw format.

maintainer
#3 lore raw
Quoted 7 lines · Keith Busch
Quoted 6 lines · Jens Axboe
Quoted 4 lines · Keith Busch

From: Keith Busch <[email protected]>

Add manuals for getting 128b submission queue entries, and the new prep functions.

Quoted 6 lines
Quoted 3 lines

Thanks! A bit of too much copy pasting in terms of versions etc, but I can just fix those up. Also needs a bit of man formatting love, I'll do that too.

Ah, thanks. man syntax is weird, I usually see projects generate them from a more friendly markup rather than committing their raw format.

Yeah it's terrible... At least copy/paste is a thing, but unfortunately then quite common to miss changing a name or the date/version.

Signature · 1 line
Jens Axboe
maintainer Applied
#4 lore raw
In reply to Keith Busch
Quoted 4 lines · Keith Busch

Add manuals for getting 128b submission queue entries, and the new prep functions.

Applied, thanks!

[1/1] add man pages for new apis

      commit: 35a7e0a0bc69178cbb5ab3ffaa453a7f5a481333

Best regards,

Signature · 1 line
Jens Axboe