[PATCH] man: Add io_setup.3 and io_destroy.3

[PATCH] man: Add io_setup.3 and io_destroy.3

[Cyril Hrubis]

This is a second version that includes
fixes proposed by Michael Kerrisk.

Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
---
 man/io_destroy.3 |   41 +++++++++++++++++++++++++++++++++++++++++
 man/io_setup.3   |   41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 0 deletions(-)
 create mode 100644 man/io_destroy.3
 create mode 100644 man/io_setup.3

diff --git a/man/io_destroy.3 b/man/io_destroy.3
new file mode 100644
index 0000000..dc662bd
--- /dev/null
+++ b/man/io_destroy.3
@@ -0,0 +1,41 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_destroy \- destroy an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_destroy(io_context_t ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_destroy (2)
+system call.
+.PP
+See
+.BR io_queue_release (3)
+for the
+.I libaio
+high-level interface.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_getevents (3)
+.BR io_queue_release (3)
+.BR io_setup (3)
+.BR io_submit (3)
diff --git a/man/io_setup.3 b/man/io_setup.3
new file mode 100644
index 0000000..2427204
--- /dev/null
+++ b/man/io_setup.3
@@ -0,0 +1,41 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_setup \- create an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_setup(int maxevents, io_context_t *ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_setup (2)
+system call.
+.PP
+See
+.BR io_queue_init (3)
+for the
+.I libaio
+high-level interface.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_destroy (3)
+.BR io_getevents (3)
+.BR io_queue_init (3)
+.BR io_submit (3)
-- 
1.7.8.6


-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[Jeff Moyer]

Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> writes:

> This is a second version that includes
> fixes proposed by Michael Kerrisk.

Now that I see what this looks like, I think it's rather confusing to
have the user reference both the .2 and .3 pages to write code for
libaio.  I'd prefer to keep all of the text for how to use the library
inside the .3 man pages.

-Jeff
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[chrubis-AlSwsSmVLrQ]

Hi!
> > This is a second version that includes
> > fixes proposed by Michael Kerrisk.
> 
> Now that I see what this looks like, I think it's rather confusing to
> have the user reference both the .2 and .3 pages to write code for
> libaio.  I'd prefer to keep all of the text for how to use the library
> inside the .3 man pages.

Then we need to duplicate some of the information from the .2 pages to
the libaio .3 pages. I'm fine with that, but we should probably finish
the .2 pages cleanup first.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[chrubis-AlSwsSmVLrQ]

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

Hi!
> > This is a second version that includes
> > fixes proposed by Michael Kerrisk.
> 
> Now that I see what this looks like, I think it's rather confusing to
> have the user reference both the .2 and .3 pages to write code for
> libaio.  I'd prefer to keep all of the text for how to use the library
> inside the .3 man pages.

Attached is a new version of the patch that adds io_setup and io_destroy
man pages.

The change agains previous version is that the functinonality of the
wrappper is described right in the manual page.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org

[-- Attachment #2: 0001-man-Add-io_setup.3-and-io_destroy.3.patch --]
[-- Type: text/x-diff, Size: 3238 bytes --]

>From b1211ceb3e774075b9abedef15434bd91cdc8fe4 Mon Sep 17 00:00:00 2001
From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
Date: Tue, 26 Mar 2013 18:00:31 +0100
Subject: [PATCH] man: Add io_setup.3 and io_destroy.3

Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
---
 man/io_destroy.3 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 man/io_setup.3   |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 0 deletions(-)
 create mode 100644 man/io_destroy.3
 create mode 100644 man/io_setup.3

diff --git a/man/io_destroy.3 b/man/io_destroy.3
new file mode 100644
index 0000000..10f0e85
--- /dev/null
+++ b/man/io_destroy.3
@@ -0,0 +1,46 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_destroy \- destroy an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_destroy(io_context_t ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_destroy (2)
+system call.
+.PP
+See
+.BR io_queue_release (3)
+for the
+.I libaio
+high-level interface.
+
+The \fBio_destroy\fP() will attempt to cancel all outstanding asynchronous I/O
+operations previously submitted to \fIctx\fP. It will block on completion of
+operations that could not be canceled. Upon sucessfull return the I/O context
+\fIctx\fP is destroyed.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_getevents (3)
+.BR io_queue_release (3)
+.BR io_setup (3)
+.BR io_submit (3)
diff --git a/man/io_setup.3 b/man/io_setup.3
new file mode 100644
index 0000000..4b3704e
--- /dev/null
+++ b/man/io_setup.3
@@ -0,0 +1,50 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_setup \- create an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_setup(int maxevents, io_context_t *ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_setup (2)
+system call.
+.PP
+See
+.BR io_queue_init (3)
+for the
+.I libaio
+high-level interface.
+
+The
+.BR io_setup ()
+creates an asynchronous I/O context suitable for concurrently processing
+\fImaxevents\fP operations.
+The \fIctx\fP must not point to allready existing I/O context and must be
+initialized to 0 prior to the call.
+
+On successful initialization the \fIctx\fP is filled with a handle.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_destroy (3)
+.BR io_getevents (3)
+.BR io_queue_init (3)
+.BR io_submit (3)
-- 
1.7.8.6


[-- Attachment #3: 0001-man-Add-io_setup.3-and-io_destroy.3.patch --]
[-- Type: text/x-diff, Size: 3238 bytes --]

>From b1211ceb3e774075b9abedef15434bd91cdc8fe4 Mon Sep 17 00:00:00 2001
From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
Date: Tue, 26 Mar 2013 18:00:31 +0100
Subject: [PATCH] man: Add io_setup.3 and io_destroy.3

Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
---
 man/io_destroy.3 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 man/io_setup.3   |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 0 deletions(-)
 create mode 100644 man/io_destroy.3
 create mode 100644 man/io_setup.3

diff --git a/man/io_destroy.3 b/man/io_destroy.3
new file mode 100644
index 0000000..10f0e85
--- /dev/null
+++ b/man/io_destroy.3
@@ -0,0 +1,46 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_destroy \- destroy an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_destroy(io_context_t ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_destroy (2)
+system call.
+.PP
+See
+.BR io_queue_release (3)
+for the
+.I libaio
+high-level interface.
+
+The \fBio_destroy\fP() will attempt to cancel all outstanding asynchronous I/O
+operations previously submitted to \fIctx\fP. It will block on completion of
+operations that could not be canceled. Upon sucessfull return the I/O context
+\fIctx\fP is destroyed.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_getevents (3)
+.BR io_queue_release (3)
+.BR io_setup (3)
+.BR io_submit (3)
diff --git a/man/io_setup.3 b/man/io_setup.3
new file mode 100644
index 0000000..4b3704e
--- /dev/null
+++ b/man/io_setup.3
@@ -0,0 +1,50 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" This file is distributed according to the GNU General Public License.
+.\"
+.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_setup \- create an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_setup(int maxevents, io_context_t *ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_setup (2)
+system call.
+.PP
+See
+.BR io_queue_init (3)
+for the
+.I libaio
+high-level interface.
+
+The
+.BR io_setup ()
+creates an asynchronous I/O context suitable for concurrently processing
+\fImaxevents\fP operations.
+The \fIctx\fP must not point to allready existing I/O context and must be
+initialized to 0 prior to the call.
+
+On successful initialization the \fIctx\fP is filled with a handle.
+.SH RETURN VALUE
+On success,
+.BR io_setup ()
+returns 0. On failure, a negative error number is returned.
+.SH NOTES
+Note that the Linux system call uses a different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH SEE ALSO
+.BR io_cancel (3)
+.BR io_destroy (3)
+.BR io_getevents (3)
+.BR io_queue_init (3)
+.BR io_submit (3)
-- 
1.7.8.6

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[chrubis-AlSwsSmVLrQ]

Hi!
> > > This is a second version that includes
> > > fixes proposed by Michael Kerrisk.
> > 
> > Now that I see what this looks like, I think it's rather confusing to
> > have the user reference both the .2 and .3 pages to write code for
> > libaio.  I'd prefer to keep all of the text for how to use the library
> > inside the .3 man pages.
> 
> Attached is a new version of the patch that adds io_setup and io_destroy
> man pages.
> 
> The change agains previous version is that the functinonality of the
> wrappper is described right in the manual page.

Ping.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] man: Add io_setup.3 and io_destroy.3

[Cyril Hrubis]

This patch adds two missing manual pages.

I've tried to format them in accordance with
Linux man-pages project. If these are acked
I'll reformat the rest of the io_* system call
wrappers man pages to match.

Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
---
 man/io_destroy.3 |   45 +++++++++++++++++++++++++++++++++++++++++++++
 man/io_setup.3   |   45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 0 deletions(-)
 create mode 100644 man/io_destroy.3
 create mode 100644 man/io_setup.3

diff --git a/man/io_destroy.3 b/man/io_destroy.3
new file mode 100644
index 0000000..6d84213
--- /dev/null
+++ b/man/io_destroy.3
@@ -0,0 +1,45 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
+.\" This file is distributed according to the GNU General Public License.
+.\" %%%LICENSE_END
+.\"
+.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_destroy \- destroy an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_destroy(io_context_t ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_destroy
+system call, see
+.BR io_destroy (2)
+for more information.
+.PP
+See
+.BR io_queue_release (3)
+for
+.I libaio
+highlevel interface.
+.SH "RETURN VALUES"
+On success
+.BR io_setup ()
+returns 0. On failure negative error number is returned.
+.SH NOTES
+Note that Linux system call uses different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH "SEE ALSO"
+.BR io_queue_release (3)
+.BR io_setup (3)
+.BR io_submit (3)
+.BR io_cancel (3)
+.BR io_getevents (3)
diff --git a/man/io_setup.3 b/man/io_setup.3
new file mode 100644
index 0000000..626e954
--- /dev/null
+++ b/man/io_setup.3
@@ -0,0 +1,45 @@
+.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
+.\"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
+.\" This file is distributed according to the GNU General Public License.
+.\" %%%LICENSE_END
+.\"
+.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
+.SH NAME
+io_setup \- create an asynchronous I/O context
+.SH SYNOPSIS
+.nf
+.B #include <libaio.h>
+
+.BI "int io_setup(int maxevents, io_context_t *ctx)"
+.sp
+Link with \fI\-laio\fP.
+.fi
+.SH DESCRIPTION
+This is a wrapper for the
+.BR io_setup
+system call, see
+.BR io_setup (2)
+for more information.
+.PP
+See
+.BR io_queue_init (3)
+for
+.I libaio
+highlevel interface.
+.SH "RETURN VALUES"
+On success
+.BR io_setup ()
+returns 0. On failure negative error number is returned.
+.SH NOTES
+Note that Linux system call uses different type
+.RI ( "aio_context_t\ *" )
+for the
+.I ctx
+argument.
+.SH "SEE ALSO"
+.BR io_queue_init (3)
+.BR io_destroy (3)
+.BR io_submit (3)
+.BR io_cancel (3)
+.BR io_getevents (3)
-- 
1.7.8.6


-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[Michael Kerrisk (man-pages)]

Cyril,

On Tue, Mar 26, 2013 at 6:06 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> This patch adds two missing manual pages.
>
> I've tried to format them in accordance with
> Linux man-pages project. If these are acked
> I'll reformat the rest of the io_* system call
> wrappers man pages to match.

So, here's what I'm not clear on. AFAIK, the io_setup() wrapper (and
the other io_*() wrappers) is provided in libaio, right? And libaio is
a completely separate package from glibc, right?

The man-pages project documents the Linux syscall and glibc APIs, so
if my understanding above is correct, then these io_*(3) pages belong
in the libaio package, not in in man-pages. Could you or Jeff clarify?

Thanks,

Michael

> Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> ---
>  man/io_destroy.3 |   45 +++++++++++++++++++++++++++++++++++++++++++++
>  man/io_setup.3   |   45 +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 90 insertions(+), 0 deletions(-)
>  create mode 100644 man/io_destroy.3
>  create mode 100644 man/io_setup.3
>
> diff --git a/man/io_destroy.3 b/man/io_destroy.3
> new file mode 100644
> index 0000000..6d84213
> --- /dev/null
> +++ b/man/io_destroy.3
> @@ -0,0 +1,45 @@
> +.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> +.\"
> +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> +.\" This file is distributed according to the GNU General Public License.
> +.\" %%%LICENSE_END
> +.\"
> +.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
> +.SH NAME
> +io_destroy \- destroy an asynchronous I/O context
> +.SH SYNOPSIS
> +.nf
> +.B #include <libaio.h>
> +
> +.BI "int io_destroy(io_context_t ctx)"
> +.sp
> +Link with \fI\-laio\fP.
> +.fi
> +.SH DESCRIPTION
> +This is a wrapper for the
> +.BR io_destroy
> +system call, see
> +.BR io_destroy (2)
> +for more information.
> +.PP
> +See
> +.BR io_queue_release (3)
> +for
> +.I libaio
> +highlevel interface.
> +.SH "RETURN VALUES"
> +On success
> +.BR io_setup ()
> +returns 0. On failure negative error number is returned.
> +.SH NOTES
> +Note that Linux system call uses different type
> +.RI ( "aio_context_t\ *" )
> +for the
> +.I ctx
> +argument.
> +.SH "SEE ALSO"
> +.BR io_queue_release (3)
> +.BR io_setup (3)
> +.BR io_submit (3)
> +.BR io_cancel (3)
> +.BR io_getevents (3)
> diff --git a/man/io_setup.3 b/man/io_setup.3
> new file mode 100644
> index 0000000..626e954
> --- /dev/null
> +++ b/man/io_setup.3
> @@ -0,0 +1,45 @@
> +.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> +.\"
> +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> +.\" This file is distributed according to the GNU General Public License.
> +.\" %%%LICENSE_END
> +.\"
> +.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
> +.SH NAME
> +io_setup \- create an asynchronous I/O context
> +.SH SYNOPSIS
> +.nf
> +.B #include <libaio.h>
> +
> +.BI "int io_setup(int maxevents, io_context_t *ctx)"
> +.sp
> +Link with \fI\-laio\fP.
> +.fi
> +.SH DESCRIPTION
> +This is a wrapper for the
> +.BR io_setup
> +system call, see
> +.BR io_setup (2)
> +for more information.
> +.PP
> +See
> +.BR io_queue_init (3)
> +for
> +.I libaio
> +highlevel interface.
> +.SH "RETURN VALUES"
> +On success
> +.BR io_setup ()
> +returns 0. On failure negative error number is returned.
> +.SH NOTES
> +Note that Linux system call uses different type
> +.RI ( "aio_context_t\ *" )
> +for the
> +.I ctx
> +argument.
> +.SH "SEE ALSO"
> +.BR io_queue_init (3)
> +.BR io_destroy (3)
> +.BR io_submit (3)
> +.BR io_cancel (3)
> +.BR io_getevents (3)
> --
> 1.7.8.6
>
>
> --
> Cyril Hrubis
> chrubis-AlSwsSmVLrQ@public.gmane.org



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[chrubis-AlSwsSmVLrQ]

Hi!
> > This patch adds two missing manual pages.
> >
> > I've tried to format them in accordance with
> > Linux man-pages project. If these are acked
> > I'll reformat the rest of the io_* system call
> > wrappers man pages to match.
> 
> So, here's what I'm not clear on. AFAIK, the io_setup() wrapper (and
> the other io_*() wrappers) is provided in libaio, right? And libaio is
> a completely separate package from glibc, right?
> 
> The man-pages project documents the Linux syscall and glibc APIs, so
> if my understanding above is correct, then these io_*(3) pages belong
> in the libaio package, not in in man-pages. Could you or Jeff clarify?

You are 100% right and we both got it the first time you said this. I've
simply CCed you so that you can have a quick look at the pages and say
if they have all the information they should have before they got
included into libaio.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[Michael Kerrisk (man-pages)]

On Thu, Mar 28, 2013 at 10:35 AM,  <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> Hi!
>> > This patch adds two missing manual pages.
>> >
>> > I've tried to format them in accordance with
>> > Linux man-pages project. If these are acked
>> > I'll reformat the rest of the io_* system call
>> > wrappers man pages to match.
>>
>> So, here's what I'm not clear on. AFAIK, the io_setup() wrapper (and
>> the other io_*() wrappers) is provided in libaio, right? And libaio is
>> a completely separate package from glibc, right?
>>
>> The man-pages project documents the Linux syscall and glibc APIs, so
>> if my understanding above is correct, then these io_*(3) pages belong
>> in the libaio package, not in in man-pages. Could you or Jeff clarify?
>
> You are 100% right and we both got it the first time you said this. I've
> simply CCed you so that you can have a quick look at the pages and say
> if they have all the information they should have before they got
> included into libaio.

Ahh -- sorry, I misunderstood. I thought you were proposing to include
them into man-pages.

I'll go back and look at the pages and make a few comments.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man: Add io_setup.3 and io_destroy.3

[Michael Kerrisk (man-pages)]

On Tue, Mar 26, 2013 at 6:06 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> This patch adds two missing manual pages.
>
> I've tried to format them in accordance with
> Linux man-pages project. If these are acked
> I'll reformat the rest of the io_* system call
> wrappers man pages to match.
>
> Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> ---
>  man/io_destroy.3 |   45 +++++++++++++++++++++++++++++++++++++++++++++
>  man/io_setup.3   |   45 +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 90 insertions(+), 0 deletions(-)
>  create mode 100644 man/io_destroy.3
>  create mode 100644 man/io_setup.3
>
> diff --git a/man/io_destroy.3 b/man/io_destroy.3
> new file mode 100644
> index 0000000..6d84213
> --- /dev/null
> +++ b/man/io_destroy.3
> @@ -0,0 +1,45 @@
> +.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> +.\"
> +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> +.\" This file is distributed according to the GNU General Public License.
> +.\" %%%LICENSE_END

So, the above %%% lines are a man-pages specific thing. I think you
don't need them here, just the license.

> +.\"
> +.TH IO_DESTROY 3 2013-03-26 "Linux" "Linux AIO"
> +.SH NAME
> +io_destroy \- destroy an asynchronous I/O context
> +.SH SYNOPSIS
> +.nf
> +.B #include <libaio.h>
> +
> +.BI "int io_destroy(io_context_t ctx)"
> +.sp
> +Link with \fI\-laio\fP.
> +.fi
> +.SH DESCRIPTION
> +This is a wrapper for the
> +.BR io_destroy

.BR io_destroy (2)

> +system call,

And then I would just delete the next 3 lines.

> see
> +.BR io_destroy (2)
> +for more information.
> +.PP
> +See
> +.BR io_queue_release (3)
> +for

+ the

> +.I libaio
> +highlevel interface.

"high-level"

> +.SH "RETURN VALUES"

.SH RETURN VALUE

(No quotes needed, and remove the "S")

> +On success

Add comma.

> +.BR io_setup ()
> +returns 0. On failure negative error number is returned.

+returns 0. On failure, a negative error number is returned.

(Two changes)

> +.SH NOTES
> +Note that Linux system call uses different type

+ Note that the L:inux system call uses a differnt type

(Two changes)

> +.RI ( "aio_context_t\ *" )
> +for the
> +.I ctx
> +argument.
> +.SH "SEE ALSO"

(No quotes needed in the preceding line.)

In man-pages at least the convention is to order man pages under SEE
ALSO, by section and the _alphabetically_ within the section.

> +.BR io_queue_release (3)
> +.BR io_setup (3)
> +.BR io_submit (3)
> +.BR io_cancel (3)
> +.BR io_getevents (3)
> diff --git a/man/io_setup.3 b/man/io_setup.3
> new file mode 100644
> index 0000000..626e954
> --- /dev/null

All of the above comments apply to the following page also:

> +++ b/man/io_setup.3
> @@ -0,0 +1,45 @@
> +.\" Copyright (C) 2013 Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> +.\"
> +.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> +.\" This file is distributed according to the GNU General Public License.
> +.\" %%%LICENSE_END
> +.\"
> +.TH IO_SETUP 3 2013-03-26 "Linux" "Linux AIO"
> +.SH NAME
> +io_setup \- create an asynchronous I/O context
> +.SH SYNOPSIS
> +.nf
> +.B #include <libaio.h>
> +
> +.BI "int io_setup(int maxevents, io_context_t *ctx)"
> +.sp
> +Link with \fI\-laio\fP.
> +.fi
> +.SH DESCRIPTION
> +This is a wrapper for the
> +.BR io_setup
> +system call, see
> +.BR io_setup (2)
> +for more information.
> +.PP
> +See
> +.BR io_queue_init (3)
> +for
> +.I libaio
> +highlevel interface.
> +.SH "RETURN VALUES"
> +On success
> +.BR io_setup ()
> +returns 0. On failure negative error number is returned.
> +.SH NOTES
> +Note that Linux system call uses different type
> +.RI ( "aio_context_t\ *" )
> +for the
> +.I ctx
> +argument.
> +.SH "SEE ALSO"
> +.BR io_queue_init (3)
> +.BR io_destroy (3)
> +.BR io_submit (3)
> +.BR io_cancel (3)
> +.BR io_getevents (3)

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html