[PATCH v1 6/6] man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2

Alejandro Colomar
2026-04-08T09:18:55Z

This simplifies the documentation of the system call.
Let the wrapper be documented as io_setup(3).

Cc: Guillem Jover <guillem@debian.org>
Cc: <linux-aio@kvack.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
man/man2/io_setup.2 | 60 ++++++++++++---------------------------------
man/man3/io_setup.3 | 40 ++++++++++++++++++++++++++++++
2 files changed, 56 insertions(+), 44 deletions(-)
create mode 100644 man/man3/io_setup.3

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index 398101fb..f58cb45b 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -9,10 +9,6 @@ .SH NAME
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
-.P
-Alternatively, Asynchronous I/O library
-.RI ( libaio ,\~ \-laio );
-see VERSIONS.
.SH SYNOPSIS
.nf
.B #include <linux/aio_abi.h>
@@ -21,19 +17,13 @@ .SH SYNOPSIS
.P
.BI "long\~syscall(SYS_io_setup, unsigned int " n ", aio_context_t *" ctx_idp );
.fi
-.P
-.IR Note :
-There is no glibc wrapper for this system call;
-see VERSIONS.
.SH DESCRIPTION
.IR Note :
-this page describes the raw Linux system call interface.
-The wrapper function provided by
-.I libaio
-uses a different type for the
-.I ctx_idp
-argument.
-See VERSIONS.
+you probably want to use the
+.BR io_setup (3)
+wrapper function provided by
+.IR libaio ;
+see VERSIONS.
.P
The
.BR io_setup ()
@@ -53,7 +43,11 @@ .SH RETURN VALUE
On success,
.BR io_setup ()
returns 0.
-For the failure return, see VERSIONS.
+On error,
+\-1 is returned,
+and
+.I errno
+is set to indicate the error.
.SH ERRORS
.TP
.B EAGAIN
@@ -87,35 +81,12 @@ .SH ERRORS
.BR io_setup ()
is not implemented on this architecture.
.SH VERSIONS
-glibc does not provide a wrapper for this system call.
-You could invoke it using
-.BR syscall (2).
-But instead, you probably want to use the
-.BR io_setup ()
-wrapper function provided by
-.\" http://git.fedorahosted.org/git/?p=libaio.git
-.IR libaio .
-.P
-Note that the
+.UR https://pagure.io/libaio
.I libaio
-wrapper function uses a different type
-.RI ( "io_context_t\ *" )
-.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
-.\" the system call.
-for the
-.I ctx_idp
-argument.
-Note also that the
-.I libaio
-wrapper does not follow the usual C library conventions for indicating errors:
-on error it returns a negated error number
-(the negative of one of the values listed in ERRORS).
-If the system call is invoked via
-.BR syscall (2),
-then the return value follows the usual conventions for
-indicating an error: \-1, with
-.I errno
-set to a (positive) value that indicates the error.
+.UE
+provides a wrapper function with the same name,
+but different prototype and return value.
+You probably want to use that wrapper.
.SH STANDARDS
Linux.
.SH HISTORY
@@ -125,6 +96,7 @@ .SH SEE ALSO
.BR io_destroy (2),
.BR io_getevents (2),
.BR io_submit (2),
+.BR io_setup (3),
.BR aio (7)
.\" .SH AUTHOR
.\" Kent Yoder.
diff --git a/man/man3/io_setup.3 b/man/man3/io_setup.3
new file mode 100644
index 00000000..28b59550
--- /dev/null
+++ b/man/man3/io_setup.3
@@ -0,0 +1,40 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH io_setup 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+io_setup \- create an asynchronous I/O context
+.SH LIBRARY
+Asynchronous I/O library
+.RI ( libaio ,\~ \-laio )
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+.P
+.BI "long\~io_setup(unsigned int " n ", io_context_t *" ctx_idp );
+.fi
+.SH DESCRIPTION
+.BR io_setup ()
+creates an asynchronous I/O context suitable for concurrently processing
+.I n
+operations.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0.
+On error,
+a negative error code is returned to indicate the error.
+.SH ERRORS
+See
+.BR io_setup (2).
+.SH STANDARDS
+libaio.
+.SH HISTORY
+libaio.
+.SH SEE ALSO
+.BR io (3),
+.BR io_setup (2),
+.BR aio (7)
+.\" .SH AUTHOR
+.\" Kent Yoder.
--
2.53.0