[PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov <asml.silence@gmail.com>]

Describe the region API. As it was created for a bunch of ideas in mind,
it doesn't go into details about wait argument passing, which I assume
will be a separate page the region description can refer to.

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_register_region.3 | 123 +++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 man/io_uring_register_region.3

diff --git a/man/io_uring_register_region.3 b/man/io_uring_register_region.3
new file mode 100644
index 00000000..06ebd466
--- /dev/null
+++ b/man/io_uring_register_region.3
@@ -0,0 +1,123 @@
+.\" Copyright (C) 2026 Pavel Begunkov <asml.silence@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_region 3 "Jan 13, 2026" "liburing-2.14" "liburing Manual"
+.SH NAME
+io_uring_register_region \- register a memory region
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_region(struct io_uring *" ring ",
+.BI "                             struct io_uring_mem_region_reg *" reg ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_region (3)
+function registers a memory region to io_uring. The memory region can after be
+used, for example, to pass waiting parameters to the
+.BR io_uring_enter (2)
+system call in an efficient manner. The
+.IR ring
+argument should point to the ring in question, and the
+.IR reg
+argument should be a pointer to a
+.B struct io_uring_mem_region_reg .
+
+The
+.IR reg
+argument must be filled in with the appropriate information. It looks as
+follows:
+.PP
+.in +4n
+.EX
+struct io_uring_mem_region_reg {
+    __u64 region_uptr;
+    __u64 flags;
+    __u64 __resv[2];
+};
+.EE
+.in
+.PP
+The
+.I region_uptr
+field must contain a pointer to an appropriately filled
+.B struct io_uring_region_desc.
+.PP
+The
+.I flags
+field must contain a bitmask of the following values:
+.TP
+.B IORING_MEM_REGION_REG_WAIT_ARG
+allows to use the region topass waiting parameters to the
+.BR io_uring_enter (2)
+system call. If set, the registration is only allowed while the ring
+is in a disabled mode. See
+.B IORING_SETUP_R_DISABLED.
+.PP
+The __resv fields must be filled with zeroes.
+
+.PP
+.B struct io_uring_region_desc
+is defined as following:
+.PP
+.in +4n
+.EX
+struct io_uring_region_desc {
+    __u64 user_addr;
+    __u64 size;
+    __u32 flags;
+    __u32 id;
+    __u64 mmap_offset;
+    __u64 __resv[4];
+};
+.EE
+.in
+
+.PP
+The
+.I user_addr
+field must contain a pointer to the memory the user wants to register. It's
+only valid if
+.B IORING_MEM_REGION_TYPE_USER
+is set, and should be zero otherwise.
+
+.PP
+The
+.I size
+field should contain the size of the region.
+
+The
+.I flags
+field must contain a bitmask of the following values:
+.TP
+.B IORING_MEM_REGION_TYPE_USER
+tells the kernel to use memory specified by the
+.I user_addr
+field. If not set, the kernel will allocate memory for the region, which can
+then be mapped into the user space.
+
+.PP
+On a successful registration of a region with kernel provided memory, the
+.I mmap_offset
+field will contain an offset that can be passed to the
+.B mmap(2)
+system call to map the region into the user space.
+
+The
+.I id
+field is reserved and must be set to zero.
+
+The
+.I __resv
+fields must be filled with zeroes.
+
+Available since kernel 6.13.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_region (3)
+returns 0. On failure it returns
+.BR -errno .
-- 
2.52.0