aio manuals

aio manuals

[Cyril Hrubis]

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

Hi!
The io_* manuals says that we should use aio_context_t as type for aio
handle. That is wrong as the functions are defined with io_context_t
(libaio.h). Patch attached.

The only oustanding issue is that manual for io_setup says that we must
set the io_context_t to 0 before use. And as the io_context_t is defined
as opaque type (and it's defined as pointer now) the only way to
initalize it without warnigs is memset(&ctxp, 0, sizeof(ctxp));. Perhaps
this is not needed at all, as the ctpx is passed to the syscall and then
initalized in the kernel (at least I haven't seem any checks in the
codepath).

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

[-- Attachment #2: io_context_t.patch --]
[-- Type: text/x-patch, Size: 2122 bytes --]

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index a3fc213..1e21869 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -32,7 +32,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
 .\"#include <linux/aio.h>
 .sp
 .\" .HP 16
-.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
 .BI "              struct io_event *" result );
 .\" .ad
 .\" .hy
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index 6a165e1..47d031a 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -31,7 +31,7 @@ io_destroy \- destroy an asynchronous I/O context
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 17
-.BI "int io_destroy(aio_context_t " ctx );
+.BI "int io_destroy(io_context_t " ctx );
 .\" .ad
 .\" .hy
 .sp
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index e990f6d..a337404 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 19
-.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
+.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
 .BI "                 struct io_event *" events \
 ", struct timespec *" timeout );
 .\" .ad
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index d9b5117..ea84cb9 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -31,7 +31,7 @@ io_setup \- create an asynchronous I/O context
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 15
-.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
+.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctxp );
 .\" .ad
 .\" .hy
 .sp
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index 1eae429..3b6bbf2 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -31,7 +31,7 @@ io_submit \- submit asynchronous I/O blocks for processing
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 16
-.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
+.BI "int io_submit(io_context_t " ctx_id ", long " nr \
 ", struct iocb **" iocbpp );
 .\" .ad
 .\" .hy

Re: aio manuals

[Jeff Moyer]

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

> Hi!
> The io_* manuals says that we should use aio_context_t as type for aio
> handle. That is wrong as the functions are defined with io_context_t
> (libaio.h). Patch attached.
>
> The only oustanding issue is that manual for io_setup says that we must
> set the io_context_t to 0 before use. And as the io_context_t is defined
> as opaque type (and it's defined as pointer now) the only way to
> initalize it without warnigs is memset(&ctxp, 0, sizeof(ctxp));. Perhaps
> this is not needed at all, as the ctpx is passed to the syscall and then
> initalized in the kernel (at least I haven't seem any checks in the
> codepath).

There are checks in place for this, so the man page should not change in
that regard.

Cheers,
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: aio manuals

[Cyril Hrubis]

Hi!
> > The io_* manuals says that we should use aio_context_t as type for aio
> > handle. That is wrong as the functions are defined with io_context_t
> > (libaio.h). Patch attached.
> >
> > The only oustanding issue is that manual for io_setup says that we must
> > set the io_context_t to 0 before use. And as the io_context_t is defined
> > as opaque type (and it's defined as pointer now) the only way to
> > initalize it without warnigs is memset(&ctxp, 0, sizeof(ctxp));. Perhaps
> > this is not needed at all, as the ctpx is passed to the syscall and then
> > initalized in the kernel (at least I haven't seem any checks in the
> > codepath).
> 
> There are checks in place for this, so the man page should not change in
> that regard.

So should we settle for memset()? I could update send updated patch
then.

-- 
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: aio manuals

[Jeff Moyer]

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

> Hi!
>> > The io_* manuals says that we should use aio_context_t as type for aio
>> > handle. That is wrong as the functions are defined with io_context_t
>> > (libaio.h). Patch attached.
>> >
>> > The only oustanding issue is that manual for io_setup says that we must
>> > set the io_context_t to 0 before use. And as the io_context_t is defined
>> > as opaque type (and it's defined as pointer now) the only way to
>> > initalize it without warnigs is memset(&ctxp, 0, sizeof(ctxp));. Perhaps
>> > this is not needed at all, as the ctpx is passed to the syscall and then
>> > initalized in the kernel (at least I haven't seem any checks in the
>> > codepath).
>> 
>> There are checks in place for this, so the man page should not change in
>> that regard.
>
> So should we settle for memset()? I could update send updated patch
> then.

Yeah, memset is what I typically have done.

Thanks, Cyril.

-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: aio manuals

[Cyril Hrubis]

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

Hi!
> > So should we settle for memset()? I could update send updated patch
> > then.
> 
> Yeah, memset is what I typically have done.
> 

Here comes updated patch.

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

[-- Attachment #2: 0001-Fix-io_-manuals.patch --]
[-- Type: text/x-patch, Size: 3453 bytes --]

>From 61ea8972c02120ed534554b134c45086243d911e Mon Sep 17 00:00:00 2001
From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
Date: Wed, 16 Mar 2011 16:14:19 +0100
Subject: [PATCH] Fix io_* manuals.

The manuals says that we should use aio_context_t as type for ctpx
handle. That is wrong as the functions are defined with io_context_t in
libaio.h.

Also as the io_context_t is opaque type, it should be initalized with:

memset(&ctpx, 0, sizeof(ctpx));

Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
---
 man2/io_cancel.2    |    2 +-
 man2/io_destroy.2   |    2 +-
 man2/io_getevents.2 |    2 +-
 man2/io_setup.2     |    8 ++++++--
 man2/io_submit.2    |    2 +-
 5 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index a3fc213..1e21869 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -32,7 +32,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
 .\"#include <linux/aio.h>
 .sp
 .\" .HP 16
-.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
 .BI "              struct io_event *" result );
 .\" .ad
 .\" .hy
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index 6a165e1..47d031a 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -31,7 +31,7 @@ io_destroy \- destroy an asynchronous I/O context
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 17
-.BI "int io_destroy(aio_context_t " ctx );
+.BI "int io_destroy(io_context_t " ctx );
 .\" .ad
 .\" .hy
 .sp
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index e990f6d..a337404 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 19
-.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
+.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
 .BI "                 struct io_event *" events \
 ", struct timespec *" timeout );
 .\" .ad
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index d9b5117..851b0c4 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -31,7 +31,7 @@ io_setup \- create an asynchronous I/O context
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 15
-.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
+.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctxp );
 .\" .ad
 .\" .hy
 .sp
@@ -42,8 +42,12 @@ Link with \fI\-laio\fP.
 .BR io_setup ()
 creates an asynchronous I/O context capable of receiving
 at least \fInr_events\fP.
-\fIctxp\fP must not point to an AIO context that already exists, and must
+The \fIctxp\fP must not point to an AIO context that already exists, and must
 be initialized to 0 prior to the call.
+
+Note that io_context_t is opaque type and thuss \fIctxp\fP should be zeroed
+with memset(&ctpx, 0, sizeof(ctpx)).
+
 On successful creation of the AIO context, \fI*ctxp\fP is filled in
 with the resulting handle.
 .SH "RETURN VALUE"
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index 1eae429..3b6bbf2 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -31,7 +31,7 @@ io_submit \- submit asynchronous I/O blocks for processing
 .\" #include <linux/aio.h>
 .sp
 .\" .HP 16
-.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
+.BI "int io_submit(io_context_t " ctx_id ", long " nr \
 ", struct iocb **" iocbpp );
 .\" .ad
 .\" .hy
-- 
1.6.4.2

Re: aio manuals

[Cyril Hrubis]

Hi!
> > > So should we settle for memset()? I could update send updated patch
> > > then.
> > 
> > Yeah, memset is what I typically have done.
> > 
> 
> Here comes updated patch.

I've checked the latest man pages git and these changes aren't there
yet. Any comments?

> From 61ea8972c02120ed534554b134c45086243d911e Mon Sep 17 00:00:00 2001
> From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> Date: Wed, 16 Mar 2011 16:14:19 +0100
> Subject: [PATCH] Fix io_* manuals.
> 
> The manuals says that we should use aio_context_t as type for ctpx
> handle. That is wrong as the functions are defined with io_context_t in
> libaio.h.
> 
> Also as the io_context_t is opaque type, it should be initalized with:
> 
> memset(&ctpx, 0, sizeof(ctpx));
> 
> Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
> ---
>  man2/io_cancel.2    |    2 +-
>  man2/io_destroy.2   |    2 +-
>  man2/io_getevents.2 |    2 +-
>  man2/io_setup.2     |    8 ++++++--
>  man2/io_submit.2    |    2 +-
>  5 files changed, 10 insertions(+), 6 deletions(-)
> 
> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> index a3fc213..1e21869 100644
> --- a/man2/io_cancel.2
> +++ b/man2/io_cancel.2
> @@ -32,7 +32,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
>  .\"#include <linux/aio.h>
>  .sp
>  .\" .HP 16
> -.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
> +.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
>  .BI "              struct io_event *" result );
>  .\" .ad
>  .\" .hy
> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
> index 6a165e1..47d031a 100644
> --- a/man2/io_destroy.2
> +++ b/man2/io_destroy.2
> @@ -31,7 +31,7 @@ io_destroy \- destroy an asynchronous I/O context
>  .\" #include <linux/aio.h>
>  .sp
>  .\" .HP 17
> -.BI "int io_destroy(aio_context_t " ctx );
> +.BI "int io_destroy(io_context_t " ctx );
>  .\" .ad
>  .\" .hy
>  .sp
> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
> index e990f6d..a337404 100644
> --- a/man2/io_getevents.2
> +++ b/man2/io_getevents.2
> @@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
>  .\" #include <linux/aio.h>
>  .sp
>  .\" .HP 19
> -.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
> +.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
>  .BI "                 struct io_event *" events \
>  ", struct timespec *" timeout );
>  .\" .ad
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index d9b5117..851b0c4 100644
> --- a/man2/io_setup.2
> +++ b/man2/io_setup.2
> @@ -31,7 +31,7 @@ io_setup \- create an asynchronous I/O context
>  .\" #include <linux/aio.h>
>  .sp
>  .\" .HP 15
> -.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
> +.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctxp );
>  .\" .ad
>  .\" .hy
>  .sp
> @@ -42,8 +42,12 @@ Link with \fI\-laio\fP.
>  .BR io_setup ()
>  creates an asynchronous I/O context capable of receiving
>  at least \fInr_events\fP.
> -\fIctxp\fP must not point to an AIO context that already exists, and must
> +The \fIctxp\fP must not point to an AIO context that already exists, and must
>  be initialized to 0 prior to the call.
> +
> +Note that io_context_t is opaque type and thuss \fIctxp\fP should be zeroed
> +with memset(&ctpx, 0, sizeof(ctpx)).
> +
>  On successful creation of the AIO context, \fI*ctxp\fP is filled in
>  with the resulting handle.
>  .SH "RETURN VALUE"
> diff --git a/man2/io_submit.2 b/man2/io_submit.2
> index 1eae429..3b6bbf2 100644
> --- a/man2/io_submit.2
> +++ b/man2/io_submit.2
> @@ -31,7 +31,7 @@ io_submit \- submit asynchronous I/O blocks for processing
>  .\" #include <linux/aio.h>
>  .sp
>  .\" .HP 16
> -.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
> +.BI "int io_submit(io_context_t " ctx_id ", long " nr \
>  ", struct iocb **" iocbpp );
>  .\" .ad
>  .\" .hy
> -- 
> 1.6.4.2
> 


-- 
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: aio manuals

[Jeff Moyer]

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

> Hi!
>> > > So should we settle for memset()? I could update send updated patch
>> > > then.
>> > 
>> > Yeah, memset is what I typically have done.
>> > 
>> 
>> Here comes updated patch.
>
> I've checked the latest man pages git and these changes aren't there
> yet. Any comments?
>> @@ -42,8 +42,12 @@ Link with \fI\-laio\fP.
>>  .BR io_setup ()
>>  creates an asynchronous I/O context capable of receiving
>>  at least \fInr_events\fP.
>> -\fIctxp\fP must not point to an AIO context that already exists, and must
>> +The \fIctxp\fP must not point to an AIO context that already exists, and must
>>  be initialized to 0 prior to the call.
>> +
>> +Note that io_context_t is opaque type and thuss \fIctxp\fP should be zeroed

One extra 's' in thus.

other than that, looks good to me.

-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: aio manuals

[Michael Kerrisk (man-pages)]

On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> Hi!
>> > > So should we settle for memset()? I could update send updated patch
>> > > then.
>> >
>> > Yeah, memset is what I typically have done.
>> >
>>
>> Here comes updated patch.
>
> I've checked the latest man pages git and these changes aren't there
> yet. Any comments?

So, I'm struggling. What is the relationship between the io_*()
functions in libaio and the io_*() syscalls?

The page was attempting to document the system calls, which use
aio_context_t structures,

Cheers,

Michael



>> From 61ea8972c02120ed534554b134c45086243d911e Mon Sep 17 00:00:00 2001
>> From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
>> Date: Wed, 16 Mar 2011 16:14:19 +0100
>> Subject: [PATCH] Fix io_* manuals.
>>
>> The manuals says that we should use aio_context_t as type for ctpx
>> handle. That is wrong as the functions are defined with io_context_t in
>> libaio.h.
>>
>> Also as the io_context_t is opaque type, it should be initalized with:
>>
>> memset(&ctpx, 0, sizeof(ctpx));
>>
>> Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
>> ---
>>  man2/io_cancel.2    |    2 +-
>>  man2/io_destroy.2   |    2 +-
>>  man2/io_getevents.2 |    2 +-
>>  man2/io_setup.2     |    8 ++++++--
>>  man2/io_submit.2    |    2 +-
>>  5 files changed, 10 insertions(+), 6 deletions(-)
>>
>> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
>> index a3fc213..1e21869 100644
>> --- a/man2/io_cancel.2
>> +++ b/man2/io_cancel.2
>> @@ -32,7 +32,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
>>  .\"#include <linux/aio.h>
>>  .sp
>>  .\" .HP 16
>> -.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
>> +.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
>>  .BI "              struct io_event *" result );
>>  .\" .ad
>>  .\" .hy
>> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
>> index 6a165e1..47d031a 100644
>> --- a/man2/io_destroy.2
>> +++ b/man2/io_destroy.2
>> @@ -31,7 +31,7 @@ io_destroy \- destroy an asynchronous I/O context
>>  .\" #include <linux/aio.h>
>>  .sp
>>  .\" .HP 17
>> -.BI "int io_destroy(aio_context_t " ctx );
>> +.BI "int io_destroy(io_context_t " ctx );
>>  .\" .ad
>>  .\" .hy
>>  .sp
>> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
>> index e990f6d..a337404 100644
>> --- a/man2/io_getevents.2
>> +++ b/man2/io_getevents.2
>> @@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
>>  .\" #include <linux/aio.h>
>>  .sp
>>  .\" .HP 19
>> -.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
>> +.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
>>  .BI "                 struct io_event *" events \
>>  ", struct timespec *" timeout );
>>  .\" .ad
>> diff --git a/man2/io_setup.2 b/man2/io_setup.2
>> index d9b5117..851b0c4 100644
>> --- a/man2/io_setup.2
>> +++ b/man2/io_setup.2
>> @@ -31,7 +31,7 @@ io_setup \- create an asynchronous I/O context
>>  .\" #include <linux/aio.h>
>>  .sp
>>  .\" .HP 15
>> -.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
>> +.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctxp );
>>  .\" .ad
>>  .\" .hy
>>  .sp
>> @@ -42,8 +42,12 @@ Link with \fI\-laio\fP.
>>  .BR io_setup ()
>>  creates an asynchronous I/O context capable of receiving
>>  at least \fInr_events\fP.
>> -\fIctxp\fP must not point to an AIO context that already exists, and must
>> +The \fIctxp\fP must not point to an AIO context that already exists, and must
>>  be initialized to 0 prior to the call.
>> +
>> +Note that io_context_t is opaque type and thuss \fIctxp\fP should be zeroed
>> +with memset(&ctpx, 0, sizeof(ctpx)).
>> +
>>  On successful creation of the AIO context, \fI*ctxp\fP is filled in
>>  with the resulting handle.
>>  .SH "RETURN VALUE"
>> diff --git a/man2/io_submit.2 b/man2/io_submit.2
>> index 1eae429..3b6bbf2 100644
>> --- a/man2/io_submit.2
>> +++ b/man2/io_submit.2
>> @@ -31,7 +31,7 @@ io_submit \- submit asynchronous I/O blocks for processing
>>  .\" #include <linux/aio.h>
>>  .sp
>>  .\" .HP 16
>> -.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
>> +.BI "int io_submit(io_context_t " ctx_id ", long " nr \
>>  ", struct iocb **" iocbpp );
>>  .\" .ad
>>  .\" .hy
>> --
>> 1.6.4.2
>>
>
>
> --
> 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: aio manuals

[Jeff Moyer]

"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>> Hi!
>>> > > So should we settle for memset()? I could update send updated patch
>>> > > then.
>>> >
>>> > Yeah, memset is what I typically have done.
>>> >
>>>
>>> Here comes updated patch.
>>
>> I've checked the latest man pages git and these changes aren't there
>> yet. Any comments?
>
> So, I'm struggling. What is the relationship between the io_*()
> functions in libaio and the io_*() syscalls?

The io_* library calls are wrappers around the system calls.  In some
cases, the wrappers simply pass the arguments on to the system call.  In
other cases, there is some work performed by the library.

> The page was attempting to document the system calls, which use
> aio_context_t structures,

Well, aio_context_t is not a structure, it's just an unsigned long.

I guess that we'll ultimately need the io_* syscalls documented in
chapter 2, and the library function documented in chapter 3, right?

Cheers,
Jeff


>>> From 61ea8972c02120ed534554b134c45086243d911e Mon Sep 17 00:00:00 2001
>>> From: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
>>> Date: Wed, 16 Mar 2011 16:14:19 +0100
>>> Subject: [PATCH] Fix io_* manuals.
>>>
>>> The manuals says that we should use aio_context_t as type for ctpx
>>> handle. That is wrong as the functions are defined with io_context_t in
>>> libaio.h.
>>>
>>> Also as the io_context_t is opaque type, it should be initalized with:
>>>
>>> memset(&ctpx, 0, sizeof(ctpx));
>>>
>>> Signed-off-by: Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org>
>>> ---
>>>  man2/io_cancel.2    |    2 +-
>>>  man2/io_destroy.2   |    2 +-
>>>  man2/io_getevents.2 |    2 +-
>>>  man2/io_setup.2     |    8 ++++++--
>>>  man2/io_submit.2    |    2 +-
>>>  5 files changed, 10 insertions(+), 6 deletions(-)
>>>
>>> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
>>> index a3fc213..1e21869 100644
>>> --- a/man2/io_cancel.2
>>> +++ b/man2/io_cancel.2
>>> @@ -32,7 +32,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
>>>  .\"#include <linux/aio.h>
>>>  .sp
>>>  .\" .HP 16
>>> -.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
>>> +.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
>>>  .BI "              struct io_event *" result );
>>>  .\" .ad
>>>  .\" .hy
>>> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
>>> index 6a165e1..47d031a 100644
>>> --- a/man2/io_destroy.2
>>> +++ b/man2/io_destroy.2
>>> @@ -31,7 +31,7 @@ io_destroy \- destroy an asynchronous I/O context
>>>  .\" #include <linux/aio.h>
>>>  .sp
>>>  .\" .HP 17
>>> -.BI "int io_destroy(aio_context_t " ctx );
>>> +.BI "int io_destroy(io_context_t " ctx );
>>>  .\" .ad
>>>  .\" .hy
>>>  .sp
>>> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
>>> index e990f6d..a337404 100644
>>> --- a/man2/io_getevents.2
>>> +++ b/man2/io_getevents.2
>>> @@ -32,7 +32,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
>>>  .\" #include <linux/aio.h>
>>>  .sp
>>>  .\" .HP 19
>>> -.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
>>> +.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
>>>  .BI "                 struct io_event *" events \
>>>  ", struct timespec *" timeout );
>>>  .\" .ad
>>> diff --git a/man2/io_setup.2 b/man2/io_setup.2
>>> index d9b5117..851b0c4 100644
>>> --- a/man2/io_setup.2
>>> +++ b/man2/io_setup.2
>>> @@ -31,7 +31,7 @@ io_setup \- create an asynchronous I/O context
>>>  .\" #include <linux/aio.h>
>>>  .sp
>>>  .\" .HP 15
>>> -.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
>>> +.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctxp );
>>>  .\" .ad
>>>  .\" .hy
>>>  .sp
>>> @@ -42,8 +42,12 @@ Link with \fI\-laio\fP.
>>>  .BR io_setup ()
>>>  creates an asynchronous I/O context capable of receiving
>>>  at least \fInr_events\fP.
>>> -\fIctxp\fP must not point to an AIO context that already exists, and must
>>> +The \fIctxp\fP must not point to an AIO context that already exists, and must
>>>  be initialized to 0 prior to the call.
>>> +
>>> +Note that io_context_t is opaque type and thuss \fIctxp\fP should be zeroed
>>> +with memset(&ctpx, 0, sizeof(ctpx)).
>>> +
>>>  On successful creation of the AIO context, \fI*ctxp\fP is filled in
>>>  with the resulting handle.
>>>  .SH "RETURN VALUE"
>>> diff --git a/man2/io_submit.2 b/man2/io_submit.2
>>> index 1eae429..3b6bbf2 100644
>>> --- a/man2/io_submit.2
>>> +++ b/man2/io_submit.2
>>> @@ -31,7 +31,7 @@ io_submit \- submit asynchronous I/O blocks for processing
>>>  .\" #include <linux/aio.h>
>>>  .sp
>>>  .\" .HP 16
>>> -.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
>>> +.BI "int io_submit(io_context_t " ctx_id ", long " nr \
>>>  ", struct iocb **" iocbpp );
>>>  .\" .ad
>>>  .\" .hy
>>> --
>>> 1.6.4.2
>>>
>>
>>
>> --
>> 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: aio manuals

[Michael Kerrisk (man-pages)]

On Tue, May 8, 2012 at 1:44 AM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
>> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>>> Hi!
>>>> > > So should we settle for memset()? I could update send updated patch
>>>> > > then.
>>>> >
>>>> > Yeah, memset is what I typically have done.
>>>> >
>>>>
>>>> Here comes updated patch.
>>>
>>> I've checked the latest man pages git and these changes aren't there
>>> yet. Any comments?
>>
>> So, I'm struggling. What is the relationship between the io_*()
>> functions in libaio and the io_*() syscalls?
>
> The io_* library calls are wrappers around the system calls.  In some
> cases, the wrappers simply pass the arguments on to the system call.  In
> other cases, there is some work performed by the library.
>
>> The page was attempting to document the system calls, which use
>> aio_context_t structures,
>
> Well, aio_context_t is not a structure, it's just an unsigned long.
>
> I guess that we'll ultimately need the io_* syscalls documented in
> chapter 2, and the library function documented in chapter 3, right?

Jeff,

Quick question: where is the canonical home of libaio? It's not easy
to find. I'd like to ensure I'l looking at the latest sources, ideally
by pulling from a VCS.

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: aio manuals

[Jeff Moyer]

"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> On Tue, May 8, 2012 at 1:44 AM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>
>>> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>>>> Hi!
>>>>> > > So should we settle for memset()? I could update send updated patch
>>>>> > > then.
>>>>> >
>>>>> > Yeah, memset is what I typically have done.
>>>>> >
>>>>>
>>>>> Here comes updated patch.
>>>>
>>>> I've checked the latest man pages git and these changes aren't there
>>>> yet. Any comments?
>>>
>>> So, I'm struggling. What is the relationship between the io_*()
>>> functions in libaio and the io_*() syscalls?
>>
>> The io_* library calls are wrappers around the system calls.  In some
>> cases, the wrappers simply pass the arguments on to the system call.  In
>> other cases, there is some work performed by the library.
>>
>>> The page was attempting to document the system calls, which use
>>> aio_context_t structures,
>>
>> Well, aio_context_t is not a structure, it's just an unsigned long.
>>
>> I guess that we'll ultimately need the io_* syscalls documented in
>> chapter 2, and the library function documented in chapter 3, right?
>
> Jeff,
>
> Quick question: where is the canonical home of libaio? It's not easy
> to find. I'd like to ensure I'l looking at the latest sources, ideally
> by pulling from a VCS.

http://git.fedorahosted.org/git/?p=libaio.git

Cheers,
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: aio manuals

[Michael Kerrisk (man-pages)]

Jeff, Cyril,

On Tue, May 8, 2012 at 1:44 AM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>
>> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>>> Hi!
>>>> > > So should we settle for memset()? I could update send updated patch
>>>> > > then.
>>>> >
>>>> > Yeah, memset is what I typically have done.
>>>> >
>>>>
>>>> Here comes updated patch.
>>>
>>> I've checked the latest man pages git and these changes aren't there
>>> yet. Any comments?
>>
>> So, I'm struggling. What is the relationship between the io_*()
>> functions in libaio and the io_*() syscalls?
>
> The io_* library calls are wrappers around the system calls.  In some
> cases, the wrappers simply pass the arguments on to the system call.  In
> other cases, there is some work performed by the library.
>
>> The page was attempting to document the system calls, which use
>> aio_context_t structures,
>
> Well, aio_context_t is not a structure, it's just an unsigned long.

(Yep, I realized that afterward ;-).)

> I guess that we'll ultimately need the io_* syscalls documented in
> chapter 2, and the library function documented in chapter 3, right?

So, as I understand it (please correct me where I've got something
wrong), things are like this:

0. We've got the 5 kernel io_* syscalls, which use aio_context_t:
io_cancel(), io_destroy(), io_setup(), io_submit(), and
io_getevents().

1. There's a corresponding set of io_* wrappers in libaio that use
io_context_t. These wrappers are sometimes, but not always, very thin
wrappers for the system calls. Examples of thin wrappers are
io_cancel(), io_destroy(), io_setup(), and io_submit(). On the other
hand, io_getevents() is a non-thin wrapper.

2. libaio also provides a number of io_* functions that use the system
calls, but don't correspond directly to one of the kernel syscalls.
For example, io_poll() (inline in libaio.h) and io_queue_init().

3. libaio is *not* part of glibc.

4. There is a set of related man pages in the man-pages package:

a) io_*.2 pages documenting the 5 system calls. These seem to date
from early 2003, have an FSF/GPL copyright/license, and look to have
been written by Kent Yoder. These pages have seen some maintenance
over the years, but are a bit confused as to whether they are
describing the system calls or the libaio interface.

b) aio_*/lio_* pages documenting the aio interface provided by glibc.
These date from 2003 (by Andries Brouwer) and 2010 (a couple of
missing pieces and pages added by me).

(The existence of the above pages corresponds to normal man-pages
practice: man-pages aims to have a complete set if pages for for the
kernel syscalls and the glibc APIs; it's reasonably complete for the
former, but has still some gaps for the latter.

5. libaio has some man pages also. (By the way, these pages carry NO
copyright notice or license in the source file. What is the license?
One can't really imply the license from the COPYING file in the parent
directory.) These pages date from 2002, and seem to have seen no
maintenance since then. The pages are:

a) aio_*/lio_* pages documenting the aio interface provided by glibc.

b) io_*.3 pages that document interfaces provided by libaio.

c) io_*.1 pages (why ".1"?) that document the io_* system calls. But
these pages are mostly stubs. Only io_submit.1 has something like a
complete description.

Looking at the above (5a), I'm puzzled. Why is libaio providing some
man pages for glibc? It makes no sense for one library package to
provide man pages for functions implemented in a separately maintained
library. Further, it creates confusion if someone installs libaio, an
din the process overwrites man pages provided by man-pages.

Here's what I think should be done:

1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:

a) There should be .2 pages provided by man-pages that document the
raw system calls. These pages need a bit of cleaning up. These pages
should be updated to focus on the system calls, and note the existence
of libaio and the existence of the wrappers it provides.

b) There should be .3 pages provided by libaio. (The pages should be
provided by libaio, because that's the library that implements them.
If those wrappers were in glibc, then I'd have said that man-pages
should provide them.) Since the wrappers are mostly very thin, I think
it would be sufficient to have very short man pages that:
- note the need to link with "-laio"
- document io_context_t versus aio_context_t
- refer the reader to the corresponding .2 page for details of behavior.

2) For the other io_* functions provided by libaio:

a) libaio should provide man pages. (And this seems already to be the case.)

3) For the aio_* and lio_listio functions:

a) The right place to document these is man-pages, since they are
glibc interfaces, not libaio interfaces. man-pages already has such
pages.

b) The versions of these man pages in libaio should be dropped. The
pages seem to be unmaintained, and they describe interfaces that are
not even part of libaio. Along the way, we should check if there are
pieces in the libaio pages that could usefully be added to the
corresponding man-pages pages.

How does the above sound?

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: aio manuals

[Jeff Moyer]

"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> Here's what I think should be done:
>
> 1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:
>
> a) There should be .2 pages provided by man-pages that document the
> raw system calls. These pages need a bit of cleaning up. These pages
> should be updated to focus on the system calls, and note the existence
> of libaio and the existence of the wrappers it provides.
>
> b) There should be .3 pages provided by libaio. (The pages should be
> provided by libaio, because that's the library that implements them.
> If those wrappers were in glibc, then I'd have said that man-pages
> should provide them.) Since the wrappers are mostly very thin, I think
> it would be sufficient to have very short man pages that:
> - note the need to link with "-laio"
> - document io_context_t versus aio_context_t
> - refer the reader to the corresponding .2 page for details of behavior.
>
> 2) For the other io_* functions provided by libaio:
>
> a) libaio should provide man pages. (And this seems already to be the case.)
>
> 3) For the aio_* and lio_listio functions:
>
> a) The right place to document these is man-pages, since they are
> glibc interfaces, not libaio interfaces. man-pages already has such
> pages.
>
> b) The versions of these man pages in libaio should be dropped. The
> pages seem to be unmaintained, and they describe interfaces that are
> not even part of libaio. Along the way, we should check if there are
> pieces in the libaio pages that could usefully be added to the
> corresponding man-pages pages.
>
> How does the above sound?

Sounds like a plan.  I'll clean this up in the coming weeks, if nobody
beats me to it.

Cheers,
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: aio manuals

[Cyril Hrubis]

Hi!
> Here's what I think should be done:
> 
> 1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:
> 
> a) There should be .2 pages provided by man-pages that document the
> raw system calls. These pages need a bit of cleaning up. These pages
> should be updated to focus on the system calls, and note the existence
> of libaio and the existence of the wrappers it provides.
> 
> b) There should be .3 pages provided by libaio. (The pages should be
> provided by libaio, because that's the library that implements them.
> If those wrappers were in glibc, then I'd have said that man-pages
> should provide them.) Since the wrappers are mostly very thin, I think
> it would be sufficient to have very short man pages that:
> - note the need to link with "-laio"
> - document io_context_t versus aio_context_t
> - refer the reader to the corresponding .2 page for details of behavior.
> 
> 2) For the other io_* functions provided by libaio:
> 
> a) libaio should provide man pages. (And this seems already to be the case.)
> 
> 3) For the aio_* and lio_listio functions:
> 
> a) The right place to document these is man-pages, since they are
> glibc interfaces, not libaio interfaces. man-pages already has such
> pages.
> 
> b) The versions of these man pages in libaio should be dropped. The
> pages seem to be unmaintained, and they describe interfaces that are
> not even part of libaio. Along the way, we should check if there are
> pieces in the libaio pages that could usefully be added to the
> corresponding man-pages pages.
> 
> How does the above sound?

Agree with these changes. And I could lend a hand with some of the work
if needed.

-- 
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: aio manuals

[Michael Kerrisk (man-pages)]

On Thu, May 10, 2012 at 2:27 AM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> Hi!
>> Here's what I think should be done:
>>
>> 1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:
>>
>> a) There should be .2 pages provided by man-pages that document the
>> raw system calls. These pages need a bit of cleaning up. These pages
>> should be updated to focus on the system calls, and note the existence
>> of libaio and the existence of the wrappers it provides.
>>
>> b) There should be .3 pages provided by libaio. (The pages should be
>> provided by libaio, because that's the library that implements them.
>> If those wrappers were in glibc, then I'd have said that man-pages
>> should provide them.) Since the wrappers are mostly very thin, I think
>> it would be sufficient to have very short man pages that:
>> - note the need to link with "-laio"
>> - document io_context_t versus aio_context_t
>> - refer the reader to the corresponding .2 page for details of behavior.
>>
>> 2) For the other io_* functions provided by libaio:
>>
>> a) libaio should provide man pages. (And this seems already to be the case.)
>>
>> 3) For the aio_* and lio_listio functions:
>>
>> a) The right place to document these is man-pages, since they are
>> glibc interfaces, not libaio interfaces. man-pages already has such
>> pages.
>>
>> b) The versions of these man pages in libaio should be dropped. The
>> pages seem to be unmaintained, and they describe interfaces that are
>> not even part of libaio. Along the way, we should check if there are
>> pieces in the libaio pages that could usefully be added to the
>> corresponding man-pages pages.
>>
>> How does the above sound?
>
> Agree with these changes. And I could lend a hand with some of the work
> if needed.

Cyril, perhaps you could tackle some of the tasks in the libaio pages?
I've done most of what I can do on the man-pages side, and the results
are pushed out to git.

Thanks,

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: aio manuals

[Michael Kerrisk (man-pages)]

On Thu, May 10, 2012 at 1:59 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On Thu, May 10, 2012 at 2:27 AM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>> Hi!
>>> Here's what I think should be done:
>>>
>>> 1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:
>>>
>>> a) There should be .2 pages provided by man-pages that document the
>>> raw system calls. These pages need a bit of cleaning up. These pages
>>> should be updated to focus on the system calls, and note the existence
>>> of libaio and the existence of the wrappers it provides.
>>>
>>> b) There should be .3 pages provided by libaio. (The pages should be
>>> provided by libaio, because that's the library that implements them.
>>> If those wrappers were in glibc, then I'd have said that man-pages
>>> should provide them.) Since the wrappers are mostly very thin, I think
>>> it would be sufficient to have very short man pages that:
>>> - note the need to link with "-laio"
>>> - document io_context_t versus aio_context_t
>>> - refer the reader to the corresponding .2 page for details of behavior.
>>>
>>> 2) For the other io_* functions provided by libaio:
>>>
>>> a) libaio should provide man pages. (And this seems already to be the case.)
>>>
>>> 3) For the aio_* and lio_listio functions:
>>>
>>> a) The right place to document these is man-pages, since they are
>>> glibc interfaces, not libaio interfaces. man-pages already has such
>>> pages.
>>>
>>> b) The versions of these man pages in libaio should be dropped. The
>>> pages seem to be unmaintained, and they describe interfaces that are
>>> not even part of libaio. Along the way, we should check if there are
>>> pieces in the libaio pages that could usefully be added to the
>>> corresponding man-pages pages.
>>>
>>> How does the above sound?
>>
>> Agree with these changes. And I could lend a hand with some of the work
>> if needed.
>
> Cyril, perhaps you could tackle some of the tasks in the libaio pages?
> I've done most of what I can do on the man-pages side, and the results
> are pushed out to git.
>
> Thanks,
>
> Michael

As noted earlier in the thread, I've done everything that I think is
required on the *.2 pages. What is the status of the libaio pages now?

Thanks,

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: aio manuals

[chrubis-AlSwsSmVLrQ]

Hi!
> As noted earlier in the thread, I've done everything that I think is
> required on the *.2 pages. What is the status of the libaio pages now?

This basically ended up burried in my mailbox (as I've had higher
priority work at the time).

Jeff what is the status, do you need some help?

-- 
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: aio manuals

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
>> As noted earlier in the thread, I've done everything that I think is
>> required on the *.2 pages. What is the status of the libaio pages now?
>
> This basically ended up burried in my mailbox (as I've had higher
> priority work at the time).
>
> Jeff what is the status, do you need some help?

Yeah, if you want to tackle this, that would be great!

Thanks, Cyril!

-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: aio manuals

[chrubis-AlSwsSmVLrQ]

Hi!
> >> As noted earlier in the thread, I've done everything that I think is
> >> required on the *.2 pages. What is the status of the libaio pages now?
> >
> > This basically ended up burried in my mailbox (as I've had higher
> > priority work at the time).
> >
> > Jeff what is the status, do you need some help?
> 
> Yeah, if you want to tackle this, that would be great!

Added to my TODO with sligtly lower priority.

-- 
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: aio manuals

[Michael Kerrisk (man-pages)]

On Mon, Nov 12, 2012 at 5:09 PM,  <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
> Hi!
>> >> As noted earlier in the thread, I've done everything that I think is
>> >> required on the *.2 pages. What is the status of the libaio pages now?
>> >
>> > This basically ended up burried in my mailbox (as I've had higher
>> > priority work at the time).
>> >
>> > Jeff what is the status, do you need some help?
>>
>> Yeah, if you want to tackle this, that would be great!
>
> Added to my TODO with sligtly lower priority.

Any progress here?

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: aio manuals

[chrubis-AlSwsSmVLrQ]

Hi!
> > Added to my TODO with sligtly lower priority.
> 
> Any progress here?
> 

Not yet, thanks for reminding. I'll try to get to this soon.

-- 
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: aio manuals

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
>> > Added to my TODO with sligtly lower priority.
>> 
>> Any progress here?
>> 
>
> Not yet, thanks for reminding. I'll try to get to this soon.

I've got other work I'm doing in libaio now, so I'll dig up the old
thread on this and try to remember what needs doing.  ;-)  I think I
should be able to get to this no later than next week.

Michael, you are a patient man!  Thanks for the continued prodding.

Cheers,
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: aio manuals

[Michael Kerrisk (man-pages)]

On Mon, May 7, 2012 at 11:14 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Jeff, Cyril,
>
> On Tue, May 8, 2012 at 1:44 AM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>
>>> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis-AlSwsSmVLrQ@public.gmane.org> wrote:
>>>> Hi!
>>>>> > > So should we settle for memset()? I could update send updated patch
>>>>> > > then.
>>>>> >
>>>>> > Yeah, memset is what I typically have done.
>>>>> >
>>>>>
>>>>> Here comes updated patch.
>>>>
>>>> I've checked the latest man pages git and these changes aren't there
>>>> yet. Any comments?
>>>
>>> So, I'm struggling. What is the relationship between the io_*()
>>> functions in libaio and the io_*() syscalls?
>>
>> The io_* library calls are wrappers around the system calls.  In some
>> cases, the wrappers simply pass the arguments on to the system call.  In
>> other cases, there is some work performed by the library.
>>
>>> The page was attempting to document the system calls, which use
>>> aio_context_t structures,
>>
>> Well, aio_context_t is not a structure, it's just an unsigned long.
>
> (Yep, I realized that afterward ;-).)
>
>> I guess that we'll ultimately need the io_* syscalls documented in
>> chapter 2, and the library function documented in chapter 3, right?
>
> So, as I understand it (please correct me where I've got something
> wrong), things are like this:
>
> 0. We've got the 5 kernel io_* syscalls, which use aio_context_t:
> io_cancel(), io_destroy(), io_setup(), io_submit(), and
> io_getevents().
>
> 1. There's a corresponding set of io_* wrappers in libaio that use
> io_context_t. These wrappers are sometimes, but not always, very thin
> wrappers for the system calls. Examples of thin wrappers are
> io_cancel(), io_destroy(), io_setup(), and io_submit(). On the other
> hand, io_getevents() is a non-thin wrapper.
>
> 2. libaio also provides a number of io_* functions that use the system
> calls, but don't correspond directly to one of the kernel syscalls.
> For example, io_poll() (inline in libaio.h) and io_queue_init().
>
> 3. libaio is *not* part of glibc.
>
> 4. There is a set of related man pages in the man-pages package:
>
> a) io_*.2 pages documenting the 5 system calls. These seem to date
> from early 2003, have an FSF/GPL copyright/license, and look to have
> been written by Kent Yoder. These pages have seen some maintenance
> over the years, but are a bit confused as to whether they are
> describing the system calls or the libaio interface.
>
> b) aio_*/lio_* pages documenting the aio interface provided by glibc.
> These date from 2003 (by Andries Brouwer) and 2010 (a couple of
> missing pieces and pages added by me).
>
> (The existence of the above pages corresponds to normal man-pages
> practice: man-pages aims to have a complete set if pages for for the
> kernel syscalls and the glibc APIs; it's reasonably complete for the
> former, but has still some gaps for the latter.
>
> 5. libaio has some man pages also. (By the way, these pages carry NO
> copyright notice or license in the source file. What is the license?
> One can't really imply the license from the COPYING file in the parent
> directory.) These pages date from 2002, and seem to have seen no
> maintenance since then. The pages are:
>
> a) aio_*/lio_* pages documenting the aio interface provided by glibc.
>
> b) io_*.3 pages that document interfaces provided by libaio.
>
> c) io_*.1 pages (why ".1"?) that document the io_* system calls. But
> these pages are mostly stubs. Only io_submit.1 has something like a
> complete description.
>
> Looking at the above (5a), I'm puzzled. Why is libaio providing some
> man pages for glibc? It makes no sense for one library package to
> provide man pages for functions implemented in a separately maintained
> library. Further, it creates confusion if someone installs libaio, an
> din the process overwrites man pages provided by man-pages.
>
> Here's what I think should be done:
>
> 1) For io_submit, io_cancel, io_getevents, io_destroy, io_setup:
>
> a) There should be .2 pages provided by man-pages that document the
> raw system calls. These pages need a bit of cleaning up. These pages
> should be updated to focus on the system calls, and note the existence
> of libaio and the existence of the wrappers it provides.
>
> b) There should be .3 pages provided by libaio. (The pages should be
> provided by libaio, because that's the library that implements them.
> If those wrappers were in glibc, then I'd have said that man-pages
> should provide them.) Since the wrappers are mostly very thin, I think
> it would be sufficient to have very short man pages that:
> - note the need to link with "-laio"
> - document io_context_t versus aio_context_t
> - refer the reader to the corresponding .2 page for details of behavior.
>
> 2) For the other io_* functions provided by libaio:
>
> a) libaio should provide man pages. (And this seems already to be the case.)
>
> 3) For the aio_* and lio_listio functions:
>
> a) The right place to document these is man-pages, since they are
> glibc interfaces, not libaio interfaces. man-pages already has such
> pages.
>
> b) The versions of these man pages in libaio should be dropped. The
> pages seem to be unmaintained, and they describe interfaces that are
> not even part of libaio. Along the way, we should check if there are
> pieces in the libaio pages that could usefully be added to the
> corresponding man-pages pages.
>
> How does the above sound?

So from the side of the man-pages projerct, I think we're done. Jeff,
Cyril, do you see anything that I still need to do on my side?

Thanks,

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

Re: aio manuals

[chrubis-AlSwsSmVLrQ]

Hi!
> So from the side of the man-pages projerct, I think we're done. Jeff,
> Cyril, do you see anything that I still need to do on my side?

We had a Hackweek here in SUSE (8. - 12.), so I've returned to my usuall
job just Yesterday. I will rework the patches for the aio manpages
hopefully during this week.

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