[PATCH v1 0/6] Split io_setup(3) from io_setup.2.

[PATCH v1 0/6] Split io_setup(3) from io_setup.2.

[Alejandro Colomar]

Hi!

I plan to split documentation of io_* system calls from their libaio
wrapper (which will be moved to io_*(3), as they're library functions).
I'm CCing linux-aio@, just so they're aware, and Guillem, which seems to
be the maintainer of the Debian package.

If you (libaio) want to get ownership of the man3 manual pages I'm
creating, feel free to steal them.  If you prefer that I keep them in
this repo, that's fine too; I'm happy to keep them.

I have made sure to not duplicate information, so for example
io_setup(3)'s ERRORS refers to io_setup(2).  I don't care too much
whether io_setup(3) should refer to io_setup(2) or vice versa, so for
now I've made io_setup(3) defer to the system call (as that's the real
source of truth).  If you have a preference, please let me know.

I have left ctx_idp undocumented in the libaio wrapper, because other
than having a different type (which is visible in the synopsis), I don't
know anything about it.  I can see that the system call documentation
doesn't apply, because by being a pointer to an incomplete structure,
users can't bzero(3) it.  So clearly, the documentation that applies to
the system call doesn't apply to the wrapper (one of the strong reasons
to split the manual page).

This sample patch set only touches io_setup(2/3), but I may/will do this
with other io_*(2) APIs implemented by libaio.  I'm even considering it
for some pages that document significant differences between system
calls and glibc wrappers.

Any comments?


Have a lovely day!
Alex

Alejandro Colomar (6):
  man/man2/io_setup.2: Reduce parameter name
  man/man2/io_setup.2: Update reference (proc(5) => proc_sys_fs(5))
  man/man2/io_setup.2: ERRORS: Split EINVAL
  man/man2/io_setup.2: ERRORS: It is *ctx_idp that must be initialized
  man/man2/io_setup.2: Use syscall(2) in the SYNOPSIS
  man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2

 man/man2/io_setup.2 | 84 ++++++++++++++++-----------------------------
 man/man3/io_setup.3 | 40 +++++++++++++++++++++
 2 files changed, 70 insertions(+), 54 deletions(-)
 create mode 100644 man/man3/io_setup.3

Range-diff against v0:
-:  -------- > 1:  6e23fd87 man/man2/io_setup.2: Reduce parameter name
-:  -------- > 2:  978c3109 man/man2/io_setup.2: Update reference (proc(5) => proc_sys_fs(5))
-:  -------- > 3:  28e8dc04 man/man2/io_setup.2: ERRORS: Split EINVAL
-:  -------- > 4:  31b6dec8 man/man2/io_setup.2: ERRORS: It is *ctx_idp that must be initialized
-:  -------- > 5:  7811fd45 man/man2/io_setup.2: Use syscall(2) in the SYNOPSIS
-:  -------- > 6:  c6fcae43 man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2
-- 
2.53.0

[PATCH v1 1/6] man/man2/io_setup.2: Reduce parameter name

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/io_setup.2 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index 3d52103d..43d9a631 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -17,7 +17,7 @@ .SH SYNOPSIS
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .P
-.BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp );
+.BI "long io_setup(unsigned int " n ", aio_context_t *" ctx_idp );
 .fi
 .P
 .IR Note :
@@ -37,7 +37,7 @@ .SH DESCRIPTION
 .BR io_setup ()
 system call
 creates an asynchronous I/O context suitable for concurrently processing
-.I nr_events
+.I n
 operations.
 The
 .I ctx_idp
@@ -56,7 +56,7 @@ .SH ERRORS
 .TP
 .B EAGAIN
 The specified
-.I nr_events
+.I n
 exceeds the limit of available events,
 as defined in
 .I /proc/sys/fs/aio\-max\-nr
@@ -71,9 +71,9 @@ .SH ERRORS
 .I ctx_idp
 is not initialized,
 or the specified
-.I nr_events
+.I n
 exceeds internal limits.
-.I nr_events
+.I n
 should be greater than 0.
 .TP
 .B ENOMEM
-- 
2.53.0

[PATCH v1 2/6] man/man2/io_setup.2: Update reference (proc(5) => proc_sys_fs(5))

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/io_setup.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index 43d9a631..f2fa4af8 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -61,7 +61,7 @@ .SH ERRORS
 as defined in
 .I /proc/sys/fs/aio\-max\-nr
 (see
-.BR proc (5)).
+.BR proc_sys_fs (5)).
 .TP
 .B EFAULT
 An invalid pointer is passed for
-- 
2.53.0

[PATCH v1 3/6] man/man2/io_setup.2: ERRORS: Split EINVAL

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/io_setup.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index f2fa4af8..08e98e89 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -69,8 +69,10 @@ .SH ERRORS
 .TP
 .B EINVAL
 .I ctx_idp
-is not initialized,
-or the specified
+is not initialized.
+.TP
+.B EINVAL
+The specified
 .I n
 exceeds internal limits.
 .I n
-- 
2.53.0

[PATCH v1 4/6] man/man2/io_setup.2: ERRORS: It is *ctx_idp that must be initialized

[Alejandro Colomar]

Also, clarify that it must be initialized to 0.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/io_setup.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index 08e98e89..f2f59c61 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -68,8 +68,8 @@ .SH ERRORS
 .IR ctx_idp .
 .TP
 .B EINVAL
-.I ctx_idp
-is not initialized.
+.I *ctx_idp
+is not initialized to 0.
 .TP
 .B EINVAL
 The specified
-- 
2.53.0

[PATCH v1 5/6] man/man2/io_setup.2: Use syscall(2) in the SYNOPSIS

[Alejandro Colomar]

That's what we do when there's no glibc wrapper.

Also, remove the comment on the existing include, as we usually don't
comment when includes are needed for types; we only comment for
constants.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man2/io_setup.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2
index f2f59c61..398101fb 100644
--- a/man/man2/io_setup.2
+++ b/man/man2/io_setup.2
@@ -15,9 +15,11 @@ .SH LIBRARY
 see VERSIONS.
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+.B #include <linux/aio_abi.h>
+.BR "#include <sys/syscall.h>" "    /* Definition of SYS_* constants */"
+.B #include <unistd.h>
 .P
-.BI "long io_setup(unsigned int " n ", aio_context_t *" ctx_idp );
+.BI "long\~syscall(SYS_io_setup, unsigned int " n ", aio_context_t *" ctx_idp );
 .fi
 .P
 .IR Note :
-- 
2.53.0

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

[Alejandro Colomar]

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

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

[Guillem Jover]

Hi!

On Wed, 2026-04-08 at 11:18:51 +0200, Alejandro Colomar wrote:
> 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

> @@ -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

The pagure.io site is being decommissioned in few months, and I've
been meaning to ask where the project will be moved for its hosting.

> 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.

I think it makes sense to split the syscall from the actual library
function man pages, and IMO it would make sense to move the .3 man pages
for the wrapper functions to libaio, as it's the project providing them.
I think though it would be nice to have them being self-contained, and
only refer to the syscall man page for reference, but not to delegate
content.

Thanks,
Guillem

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3841 bytes --]

Hi Guillem!

On 2026-04-09T18:50:43+0200, Guillem Jover wrote:
> Hi!
> 
> On Wed, 2026-04-08 at 11:18:51 +0200, Alejandro Colomar wrote:
> > 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
> 
> > @@ -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
> 
> The pagure.io site is being decommissioned in few months, and I've
> been meaning to ask where the project will be moved for its hosting.

Thanks!  Please let me know if you learn anything about this.

> > 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.
> 
> I think it makes sense to split the syscall from the actual library
> function man pages,

Thanks!  I'll go on with this.

> and IMO it would make sense to move the .3 man pages
> for the wrapper functions to libaio, as it's the project providing them.

On the other hand, it depends on how much work a project will spend on
their manual pages.  To me, it's just a small percentage of extra pages,
so I'm fine handling them if it would mean a lot of work to the project.

I might need their feedback every now and then, but since I don't expect
the APIs to change much if at all, I guess I won't need that much help.

We can do whatever they prefer to do.

> I think though it would be nice to have them being self-contained, and
> only refer to the syscall man page for reference, but not to delegate
> content.

This means more maintenance work.  It's harder to keep them in sync.

And it's also harder to spot the actual differences.  I tend to prefer
referencing other pages.  Of course, there's a limit to that; you don't
want to read 10 or 20 pages to understand an API; but 2 pages could be
reasonable, depending on the case.


Have a lovely night!
Alex

> 
> Thanks,
> Guillem

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]