Skip to contentSkip to conversation

Split io_setup(3) from io_setup.2.

PATCH In review Alejandro Colomar 2 participants 9 messages Apr 8 – Apr 9 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Alejandro Colomar

author maintainer
#0 lore raw

cover Split io_setup(3) from io_setup.2.

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
Signature · 1 line
2.53.0
author maintainer
#1 lore raw

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

Signed-off-by Alejandro Colomar <[email protected]>
---
 man/man2/io_setup.2 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
man/man2/io_setup.2 +5 -5
index 3d52103d..43d9a631 100644
@@ -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
Signature · 1 line
2.53.0
author maintainer
#2 lore raw

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

In reply to Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
---
 man/man2/io_setup.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man/man2/io_setup.2 +1 -1
index 43d9a631..f2fa4af8 100644
@@ -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
Signature · 1 line
2.53.0
author maintainer
#3 lore raw

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

In reply to Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
---
 man/man2/io_setup.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
man/man2/io_setup.2 +4 -2
index f2fa4af8..08e98e89 100644
@@ -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
Signature · 1 line
2.53.0
author maintainer
#4 lore raw

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

In reply to Alejandro Colomar

Also, clarify that it must be initialized to 0.

Signed-off-by Alejandro Colomar <[email protected]>
---
 man/man2/io_setup.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
man/man2/io_setup.2 +2 -2
index 08e98e89..f2f59c61 100644
@@ -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
Signature · 1 line
2.53.0
author maintainer
#5 lore raw

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

In reply to 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 <[email protected]>
---
 man/man2/io_setup.2 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
man/man2/io_setup.2 +4 -2
index f2f59c61..398101fb 100644
@@ -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 :
Signature · 1 line
2.53.0
author maintainer
#6 lore raw

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

In reply to Alejandro Colomar

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

Cc Guillem Jover <[email protected]>
Cc <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
---
 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
man/man2/io_setup.2 +16 -44
index 398101fb..f58cb45b 100644
@@ -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.
man/man3/io_setup.3 new file +40 -0
new file mode 100644
index 00000000..28b59550
@@ -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.
Signature · 1 line
2.53.0
#7 lore raw

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

Hi!

Quoted 17 lines · Alejandro Colomar

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

Cc Guillem Jover <[email protected]>
Cc <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
---
 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
man/man2/io_setup.2 +0 -1
@@ -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.

man/man2/io_setup.2 .SH ERRORS · line 84

Quoted 10 lines
man/man2/io_setup.2 +1 -9
-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.

Quoted 36 lines
man/man3/io_setup.3 new file +30 -0
new file mode 100644
index 00000000..28b59550
@@ -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).

man/man3/io_setup.3 line 40

Quoted 10 lines
man/man3/io_setup.3 new file +10 -0
+.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

author maintainer
#8 lore raw

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

Hi Guillem!

Quoted 25 lines · Guillem Jover

Hi!

Quoted 22 lines · Alejandro Colomar

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

Cc Guillem Jover <[email protected]>
Cc <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
---
 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
man/man2/io_setup.2 +0 -6
@@ -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
Quoted 8 lines

man/man2/io_setup.2 .SH ERRORS · line 84

Quoted 5 lines
man/man2/io_setup.2 +1 -4
-.\" 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.

Quoted 41 lines
Quoted 41 lines
man/man3/io_setup.3 new file +35 -0
new file mode 100644
index 00000000..28b59550
@@ -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
Quoted 8 lines

man/man3/io_setup.3 line 40

Quoted 5 lines
man/man3/io_setup.3 new file +5 -0
+.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.

Quoted 2 lines

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.

Quoted 3 lines

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

Quoted 3 lines

Thanks,
Guillem

Signature · 1 line
<https://www.alejandro-colomar.es>