[PATCH] add man pages for new apis

[PATCH] add man pages for new apis

[Keith Busch]

From: Keith Busch <kbusch@kernel.org>

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

Signed-off-by: Keith Busch <kbusch@kernel.org>
---
 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

diff --git a/man/io_uring_get_sqe128.3 b/man/io_uring_get_sqe128.3
new file mode 100644
index 00000000..25db811a
--- /dev/null
+++ b/man/io_uring_get_sqe128.3
@@ -0,0 +1,59 @@
+.\" Copyright (C) 2020 Jens Axboe <axboe@kernel.dk>
+.\" 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)
diff --git a/man/io_uring_prep_nop128.3 b/man/io_uring_prep_nop128.3
new file mode 100644
index 00000000..4e0c012b
--- /dev/null
+++ b/man/io_uring_prep_nop128.3
@@ -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),
diff --git a/man/io_uring_prep_uring_cmd.3 b/man/io_uring_prep_uring_cmd.3
new file mode 100644
index 00000000..b8a95233
--- /dev/null
+++ b/man/io_uring_prep_uring_cmd.3
@@ -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),
diff --git a/man/io_uring_prep_uring_cmd128.3 b/man/io_uring_prep_uring_cmd128.3
new file mode 100644
index 00000000..41853c51
--- /dev/null
+++ b/man/io_uring_prep_uring_cmd128.3
@@ -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),
-- 
2.47.3

Re: [PATCH] add man pages for new apis

[Jens Axboe]

On 10/22/25 12:00 PM, Keith Busch wrote:
> From: Keith Busch <kbusch@kernel.org>
> 
> 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.

-- 
Jens Axboe

Re: [PATCH] add man pages for new apis

[Keith Busch]

On Wed, Oct 22, 2025 at 12:02:02PM -0600, Jens Axboe wrote:
> On 10/22/25 12:00 PM, Keith Busch wrote:
> > From: Keith Busch <kbusch@kernel.org>
> > 
> > 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.

Re: [PATCH] add man pages for new apis

[Jens Axboe]

On 10/22/25 12:06 PM, Keith Busch wrote:
> On Wed, Oct 22, 2025 at 12:02:02PM -0600, Jens Axboe wrote:
>> On 10/22/25 12:00 PM, Keith Busch wrote:
>>> From: Keith Busch <kbusch@kernel.org>
>>>
>>> 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.

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.

-- 
Jens Axboe

Re: [PATCH] add man pages for new apis

[Jens Axboe]

On Wed, 22 Oct 2025 11:00:02 -0700, Keith Busch wrote:
> 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,
-- 
Jens Axboe