From: Masatake Y. <ya...@re...> - 2008-06-18 08:04:32
|
Dear man page maintainer Thank you for your great work. I'm working for test cases for io_channel(2) of linux kernel in Linux Test Project. During writing the test cases, I found some mistakes. Could you apply my patch to your master nroff file? I'm not sure following line is needed but anyway I sign. Signed-off-by: Masatake YAMATO <ya...@re...> *** io_cancel.2.orig 2008-06-11 13:20:43.000000000 +0900 --- io_cancel.2 2008-06-18 16:46:22.000000000 +0900 *************** *** 55,70 **** on failure, it returns one of the errors listed under ERRORS. .SH "ERRORS" .TP ! .B EINVAL The AIO context specified by \fIctx_id\fP is invalid. .TP ! .B EFAULT One of the data structures points to invalid data. .TP ! .B EAGAIN The \fIiocb\fP specified was not canceled. .TP ! .B ENOSYS .BR io_cancel () is not implemented on this architecture. .SH "VERSIONS" --- 55,70 ---- on failure, it returns one of the errors listed under ERRORS. .SH "ERRORS" .TP ! .B -EINVAL The AIO context specified by \fIctx_id\fP is invalid. .TP ! .B -EFAULT One of the data structures points to invalid data. .TP ! .B -EAGAIN The \fIiocb\fP specified was not canceled. .TP ! .B -ENOSYS .BR io_cancel () is not implemented on this architecture. .SH "VERSIONS" |
From: Michael K. <mtk...@go...> - 2008-06-18 09:05:30
|
Hello Masatake, On Wed, Jun 18, 2008 at 10:04 AM, Masatake YAMATO <ya...@re...> wrote: > Dear man page maintainer > > Thank you for your great work. > > I'm working for test cases for io_channel(2) of linux kernel Do you mean io_cancel(2)? > in Linux Test Project. > > > During writing the test cases, I found some mistakes. > Could you apply my patch to your master nroff file? What version of man-pages are you looking at? This patch doesn' seem to match a problem in my io_cancel page: http://www.kernel.org/doc/man-pages/online/pages/man2/io_cancel.2.html Maybe you have a version of a page from anotehr source? (Have a look here: http://www.kernel.org/doc/man-pages/man_pages_other.html ) Cheers, Michael PS Patches are good, but "diff -u" form is preferred. > I'm not sure following line is needed but anyway I sign. > > Signed-off-by: Masatake YAMATO <ya...@re...> > > *** io_cancel.2.orig 2008-06-11 13:20:43.000000000 +0900 > --- io_cancel.2 2008-06-18 16:46:22.000000000 +0900 > *************** > *** 55,70 **** > on failure, it returns one of the errors listed under ERRORS. > .SH "ERRORS" > .TP > ! .B EINVAL > The AIO context specified by \fIctx_id\fP is invalid. > .TP > ! .B EFAULT > One of the data structures points to invalid data. > .TP > ! .B EAGAIN > The \fIiocb\fP specified was not canceled. > .TP > ! .B ENOSYS > .BR io_cancel () > is not implemented on this architecture. > .SH "VERSIONS" > --- 55,70 ---- > on failure, it returns one of the errors listed under ERRORS. > .SH "ERRORS" > .TP > ! .B -EINVAL > The AIO context specified by \fIctx_id\fP is invalid. > .TP > ! .B -EFAULT > One of the data structures points to invalid data. > .TP > ! .B -EAGAIN > The \fIiocb\fP specified was not canceled. > .TP > ! .B -ENOSYS > .BR io_cancel () > is not implemented on this architecture. > .SH "VERSIONS" > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Michael K. <mtk...@go...> - 2008-06-18 09:51:28
|
Hello Masatake, On Wed, Jun 18, 2008 at 11:12 AM, Masatake YAMATO <ya...@re...> wrote: >> On Wed, Jun 18, 2008 at 10:04 AM, Masatake YAMATO <ya...@re...> wrote: >> > Dear man page maintainer >> > >> > Thank you for your great work. >> > >> > I'm working for test cases for io_channel(2) of linux kernel >> >> Do you mean io_cancel(2)? > > I'm sorry. You are right. I'm talking about io_cancel(2). > >> > in Linux Test Project. >> > >> > >> > During writing the test cases, I found some mistakes. >> > Could you apply my patch to your master nroff file? >> >> What version of man-pages are you looking at? This patch doesn' seem >> to match a problem in my io_cancel page: >> >> http://www.kernel.org/doc/man-pages/online/pages/man2/io_cancel.2.html > > man-pages-3.00. > > io_cancel returns negative value if an error occurs. > My patch points out this. Ahh -- now I see what you are saying. Okay -- at the kernel level, nearly every syscall returns a negative errno value on error. But glibc always turns that into a -1 return, and an positive errno value. The man-pages document things from that latter perspective. Do you see what I mean? >> PS Patches are good, but "diff -u" form is preferred. > > I'll use -u next time. Sorry this time. No problem. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Masatake Y. <ya...@re...> - 2008-06-18 10:51:59
|
Hi, > Ahh -- now I see what you are saying. Okay -- at the kernel level, > nearly every syscall returns a negative errno value on error. But > glibc always turns that into a -1 return, and an positive errno value. > The man-pages document things from that latter perspective. Do you > see what I mean? Generally what you write is correct. However, *it seems that* io_cancel is not in glibc; and io_cancel doesn't use errno. (If wrong, let me know.) I'd like to explain: First see the man page of io_cancel: SYNOPSIS #include <libaio.h> int io_cancel(aio_context_t ctx_id, struct iocb *iocb, struct io_event *result); Link with -laio. So we have to see the internal of libaio.h and libaio.so. Where is the master soruce code? See http://people.redhat.com/jmoyer/. # CVS Access to the libaio sources $ cvs -d :pserver:ano...@rh...:/usr/local/CVS login No password, so simply hit enter when prompted. $ cvs -d :pserver:ano...@rh...:/usr/local/CVS co libaio Let' check out and find the definition of io_cancel. libaio/src/io_cancel.c: #include <libaio.h> #include "syscall.h" io_syscall3(int, io_cancel_0_4, io_cancel, io_context_t, ctx, struct iocb *, iocb, struct io_even t *, event) DEFSYMVER(io_cancel_0_4, io_cancel, 0.4) libaio/src/syscall.h: #if defined(__i386__) #include "syscall-i386.h" libaio/src/syscall-i386.h: #define io_syscall3(type,fname,sname,type1,arg1,type2,arg2,type3,arg3) \ type fname(type1 arg1,type2 arg2,type3 arg3) \ { \ long __res; \ __asm__ volatile ("xchgl %%edi,%%ebx\n" \ "int $0x80\n" \ "xchgl %%edi,%%ebx" \ : "=a" (__res) \ : "0" (__NR_##sname),"D" ((long)(arg1)),"c" ((long)(arg2)), \ "d" ((long)(arg3))); \ return __res; \ } As I shown io_cancel is nothing to do with glibc and errno. About i386, just it returns eax. Again you wrote: > at the kernel level, > nearly every syscall returns a negative errno value on error. Yes. And the negative errno is returned directory as returned value of io_cancel wrapper function. Masatake |
From: Michael K. <mtk...@go...> - 2008-06-18 11:56:13
|
[CC += jmoyer, who maybe has some thoughts here. Context: we are talking about the io_*.2 man pages that are part of the man-pages set (see them online at http://www.kernel.org/doc/man-pages/online/dir_section_2.html ). Mail thread: http://marc.info/?l=ltp-list&m=121377627410561&w=2 ] Hi Masatake, Thanks for your patient, detailed response! On Wed, Jun 18, 2008 at 12:51 PM, Masatake YAMATO <ya...@re...> wrote: > Hi, > >> Ahh -- now I see what you are saying. Okay -- at the kernel level, >> nearly every syscall returns a negative errno value on error. But >> glibc always turns that into a -1 return, and an positive errno value. >> The man-pages document things from that latter perspective. Do you >> see what I mean? > > Generally what you write is correct. However, *it seems that* io_cancel > is not in glibc; and io_cancel doesn't use errno. > (If wrong, let me know.) Yes, you are correct. I forgot that. > I'd like to explain: > > First see the man page of io_cancel: > > SYNOPSIS > #include <libaio.h> > > int io_cancel(aio_context_t ctx_id, struct iocb *iocb, > struct io_event *result); > > Link with -laio. > > So we have to see the internal of libaio.h and libaio.so. > Where is the master soruce code? See http://people.redhat.com/jmoyer/. > > # CVS Access to the libaio sources > > $ cvs -d :pserver:ano...@rh...:/usr/local/CVS login > No password, so simply hit enter when prompted. > $ cvs -d :pserver:ano...@rh...:/usr/local/CVS co libaio > > Let' check out and find the definition of io_cancel. > > libaio/src/io_cancel.c: > > #include <libaio.h> > #include "syscall.h" > > io_syscall3(int, io_cancel_0_4, io_cancel, io_context_t, ctx, struct iocb *, iocb, struct io_even > t *, event) > DEFSYMVER(io_cancel_0_4, io_cancel, 0.4) > > libaio/src/syscall.h: > > #if defined(__i386__) > #include "syscall-i386.h" > > libaio/src/syscall-i386.h: > > #define io_syscall3(type,fname,sname,type1,arg1,type2,arg2,type3,arg3) \ > type fname(type1 arg1,type2 arg2,type3 arg3) \ > { \ > long __res; \ > __asm__ volatile ("xchgl %%edi,%%ebx\n" \ > "int $0x80\n" \ > "xchgl %%edi,%%ebx" \ > : "=a" (__res) \ > : "0" (__NR_##sname),"D" ((long)(arg1)),"c" ((long)(arg2)), \ > "d" ((long)(arg3))); \ > return __res; \ > } > > > As I shown io_cancel is nothing to do with glibc and errno. > About i386, just it returns eax. I agree with your analysis of what libaio is doing. > Again you wrote: > >> at the kernel level, >> nearly every syscall returns a negative errno value on error. > > Yes. And the negative errno is returned directory as returned value > of io_cancel wrapper function. Okay -- I agree that something is wrong with the man page(s) ;-). However, I'm not sure that the solution is what you propose. Here's why: a) Normally, when a system call doesn't have a wrapper in glibc, then we make use of syscall(2) to call it. (Most man pages say this, in the cases where there is no glibc wrapper.) syscall(2) does "the right thing", converting the negative return from a system call into -1 + positive errno. b) Back in man-pages-2.61, I added the "Link with -laio" text to the io_*.2 pages. I think that was probably a mistake on my part. I think that anyone making use of these syscalls probably *shouldn't* use libaio (I cannot really see any reason why they should), but rather they should directly invoke the system call using syscall(2). So, my proposed fix for all of the io_*.2 pages would be: 1) remove the "link with -laio" text. 2) Add a note that these system calls are not warapped by glibc, and that one should use syscall(2). (see NOTES in gettid(2) for an example). 3) Probably, there needs to be some suitable adjustment to the header files mentioned in the man page. since mentioning libaio.h doesn't seem correct -- probably it should be <linux/aio.h> instead. (Indeed back in Linux 2.44 I made the change linux/aio.h --> libaio.h, after being misled by some downstream fedora patches.) How does that sound? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-18 13:51:36
|
"Michael Kerrisk" <mtk...@go...> writes: > [CC += jmoyer, who maybe has some thoughts here. Context: we are > talking about the io_*.2 man pages that are part of the man-pages set > (see them online at > http://www.kernel.org/doc/man-pages/online/dir_section_2.html ). > Mail thread: http://marc.info/?l=ltp-list&m=121377627410561&w=2 > ] > Okay -- I agree that something is wrong with the man page(s) ;-). > > However, I'm not sure that the solution is what you propose. Here's why: > > a) Normally, when a system call doesn't have a wrapper in glibc, then > we make use of syscall(2) to call it. (Most man pages say this, in > the cases where there is no glibc wrapper.) syscall(2) does "the > right thing", converting the negative return from a system call into > -1 + positive errno. In this case, you have a separate library to handle the syscall magic. > b) Back in man-pages-2.61, I added the "Link with -laio" text to the > io_*.2 pages. I think that was probably a mistake on my part. I > think that anyone making use of these syscalls probably *shouldn't* > use libaio (I cannot really see any reason why they should), but > rather they should directly invoke the system call using syscall(2). I think the intent was to utilize a shared ring buffer space for passing messages between the kernel and userspace, but that never materialized. > So, my proposed fix for all of the io_*.2 pages would be: > 1) remove the "link with -laio" text. > 2) Add a note that these system calls are not warapped by glibc, and > that one should use syscall(2). (see NOTES in gettid(2) for an > example). > > 3) Probably, there needs to be some suitable adjustment to the header > files mentioned in the man page. since mentioning libaio.h doesn't > seem correct -- probably it should be <linux/aio.h> instead. (Indeed > back in Linux 2.44 I made the change linux/aio.h --> libaio.h, after > being misled by some downstream fedora patches.) > > How does that sound? The include file linux/aio.h is kernel-internal; it shouldn't even be distributed with the kernel-headers package. The libaio.h header file contains all of the data type definitions required for performing asynchronous I/O, so it needs to be included. It also contains macros to help fill in iocbs for various operations. Given that there are consumers of the libaio library, I will continue to maintain it. So, I don't see a need to tell folks not to use it. Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-18 14:22:05
|
Hi Jeff, Thanks for responding. On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> [CC += jmoyer, who maybe has some thoughts here. Context: we are >> talking about the io_*.2 man pages that are part of the man-pages set >> (see them online at >> http://www.kernel.org/doc/man-pages/online/dir_section_2.html ). >> Mail thread: http://marc.info/?l=ltp-list&m=121377627410561&w=2 >> ] > >> Okay -- I agree that something is wrong with the man page(s) ;-). >> >> However, I'm not sure that the solution is what you propose. Here's why: >> >> a) Normally, when a system call doesn't have a wrapper in glibc, then >> we make use of syscall(2) to call it. (Most man pages say this, in >> the cases where there is no glibc wrapper.) syscall(2) does "the >> right thing", converting the negative return from a system call into >> -1 + positive errno. > > In this case, you have a separate library to handle the syscall magic. I'm not sure of the point you are making here. Can you say a little more please? >> b) Back in man-pages-2.61, I added the "Link with -laio" text to the >> io_*.2 pages. I think that was probably a mistake on my part. I >> think that anyone making use of these syscalls probably *shouldn't* >> use libaio (I cannot really see any reason why they should), but >> rather they should directly invoke the system call using syscall(2). > > I think the intent was to utilize a shared ring buffer space for passing > messages between the kernel and userspace, but that never materialized. > >> So, my proposed fix for all of the io_*.2 pages would be: > >> 1) remove the "link with -laio" text. > >> 2) Add a note that these system calls are not warapped by glibc, and >> that one should use syscall(2). (see NOTES in gettid(2) for an >> example). >> >> 3) Probably, there needs to be some suitable adjustment to the header >> files mentioned in the man page. since mentioning libaio.h doesn't >> seem correct -- probably it should be <linux/aio.h> instead. (Indeed >> back in Linux 2.44 I made the change linux/aio.h --> libaio.h, after >> being misled by some downstream fedora patches.) >> >> How does that sound? > > The include file linux/aio.h is kernel-internal; it shouldn't even be > distributed with the kernel-headers package. Hmmm -- that's true. I guess the alternative could be to mention no header file at all (which is what is done for a few syscalls that similarly don't have wrappers in glibc). > The libaio.h header file > contains all of the data type definitions required for performing > asynchronous I/O, so it needs to be included. It also contains macros > to help fill in iocbs for various operations. Okay. > Given that there are consumers of the libaio library, I will continue to > maintain it. So, I don't see a need to tell folks not to use it. I see your point. However, it is unfortunate that the syscall wrappers in libaio don't follow the conventions employed for every other syscall wrapper (in glibc and elsewhere). Is there a reason for that? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-18 14:27:06
|
"Michael Kerrisk" <mtk...@go...> writes: > Hi Jeff, > > Thanks for responding. > > On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: >> "Michael Kerrisk" <mtk...@go...> writes: >> >>> [CC += jmoyer, who maybe has some thoughts here. Context: we are >>> talking about the io_*.2 man pages that are part of the man-pages set >>> (see them online at >>> http://www.kernel.org/doc/man-pages/online/dir_section_2.html ). >>> Mail thread: http://marc.info/?l=ltp-list&m=121377627410561&w=2 >>> ] >> >>> Okay -- I agree that something is wrong with the man page(s) ;-). >>> >>> However, I'm not sure that the solution is what you propose. Here's why: >>> >>> a) Normally, when a system call doesn't have a wrapper in glibc, then >>> we make use of syscall(2) to call it. (Most man pages say this, in >>> the cases where there is no glibc wrapper.) syscall(2) does "the >>> right thing", converting the negative return from a system call into >>> -1 + positive errno. >> >> In this case, you have a separate library to handle the syscall magic. > > I'm not sure of the point you are making here. Can you say a little > more please? My point is simply that you have a library which abstracts the syscall. That's all. >> The include file linux/aio.h is kernel-internal; it shouldn't even be >> distributed with the kernel-headers package. > > Hmmm -- that's true. I guess the alternative could be to mention no > header file at all (which is what is done for a few syscalls that > similarly don't have wrappers in glibc). Except for the fact that you need the data structure definitions. >> The libaio.h header file >> contains all of the data type definitions required for performing >> asynchronous I/O, so it needs to be included. It also contains macros >> to help fill in iocbs for various operations. > > Okay. > >> Given that there are consumers of the libaio library, I will continue to >> maintain it. So, I don't see a need to tell folks not to use it. > > I see your point. However, it is unfortunate that the syscall > wrappers in libaio don't follow the conventions employed for every > other syscall wrapper (in glibc and elsewhere). Is there a reason for > that? I was not the original author, and I don't know the rationale behind it. Ben LeHaise wrote it, so maybe he can answer your question more thoroughly. Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-18 14:37:01
|
On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> [CC += jmoyer, who maybe has some thoughts here. Context: we are >> talking about the io_*.2 man pages that are part of the man-pages set >> (see them online at >> http://www.kernel.org/doc/man-pages/online/dir_section_2.html ). >> Mail thread: http://marc.info/?l=ltp-list&m=121377627410561&w=2 >> ] > >> Okay -- I agree that something is wrong with the man page(s) ;-). >> >> However, I'm not sure that the solution is what you propose. Here's why: >> >> a) Normally, when a system call doesn't have a wrapper in glibc, then >> we make use of syscall(2) to call it. (Most man pages say this, in >> the cases where there is no glibc wrapper.) syscall(2) does "the >> right thing", converting the negative return from a system call into >> -1 + positive errno. > > In this case, you have a separate library to handle the syscall magic. > >> b) Back in man-pages-2.61, I added the "Link with -laio" text to the >> io_*.2 pages. I think that was probably a mistake on my part. I >> think that anyone making use of these syscalls probably *shouldn't* >> use libaio (I cannot really see any reason why they should), but >> rather they should directly invoke the system call using syscall(2). > > I think the intent was to utilize a shared ring buffer space for passing > messages between the kernel and userspace, but that never materialized. > >> So, my proposed fix for all of the io_*.2 pages would be: > >> 1) remove the "link with -laio" text. > >> 2) Add a note that these system calls are not warapped by glibc, and >> that one should use syscall(2). (see NOTES in gettid(2) for an >> example). >> >> 3) Probably, there needs to be some suitable adjustment to the header >> files mentioned in the man page. since mentioning libaio.h doesn't >> seem correct -- probably it should be <linux/aio.h> instead. (Indeed >> back in Linux 2.44 I made the change linux/aio.h --> libaio.h, after >> being misled by some downstream fedora patches.) >> >> How does that sound? > > The include file linux/aio.h is kernel-internal; it shouldn't even be > distributed with the kernel-headers package. The libaio.h header file > contains all of the data type definitions required for performing > asynchronous I/O, so it needs to be included. It also contains macros > to help fill in iocbs for various operations. > > Given that there are consumers of the libaio library, I will continue to > maintain it. So, I don't see a need to tell folks not to use it. I meant to ask... So yes there are consumers of the library, but I wonder if there are actually consumers (outside the library itself) of those 5 io_*(2) syscall wrappers. Any idea on that? -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-18 14:40:44
|
"Michael Kerrisk" <mtk...@go...> writes: > On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: >> Given that there are consumers of the libaio library, I will continue to >> maintain it. So, I don't see a need to tell folks not to use it. > > I meant to ask... So yes there are consumers of the library, but I > wonder if there are actually consumers (outside the library itself) > of those 5 io_*(2) syscall wrappers. Any idea on that? I'm not sure I understand your question. Are you referring to these calls? io_setup io_getevents io_submit io_destroy io_cancel If so, then yes, I would say that every application that links with libaio uses these calls. Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-18 14:45:07
|
On Wed, Jun 18, 2008 at 4:40 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: > >>> Given that there are consumers of the libaio library, I will continue to >>> maintain it. So, I don't see a need to tell folks not to use it. >> >> I meant to ask... So yes there are consumers of the library, but I >> wonder if there are actually consumers (outside the library itself) >> of those 5 io_*(2) syscall wrappers. Any idea on that? > > I'm not sure I understand your question. Are you referring to these > calls? > > io_setup > io_getevents > io_submit > io_destroy > io_cancel Yes, I meant: are apps using these wrappers *directly*, rather than using the POSIX aio* interrfaces (which then invoke 5 aforementioned wrappers). > If so, then yes, I would say that every application that links with > libaio uses these calls. And it sounds like you are saying the former then. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-18 16:13:49
|
"Michael Kerrisk" <mtk...@go...> writes: > On Wed, Jun 18, 2008 at 4:40 PM, Jeff Moyer <jm...@re...> wrote: >> "Michael Kerrisk" <mtk...@go...> writes: >> >>> On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: >> >>>> Given that there are consumers of the libaio library, I will continue to >>>> maintain it. So, I don't see a need to tell folks not to use it. >>> >>> I meant to ask... So yes there are consumers of the library, but I >>> wonder if there are actually consumers (outside the library itself) >>> of those 5 io_*(2) syscall wrappers. Any idea on that? >> >> I'm not sure I understand your question. Are you referring to these >> calls? >> >> io_setup >> io_getevents >> io_submit >> io_destroy >> io_cancel > > Yes, I meant: are apps using these wrappers *directly*, rather than > using the POSIX aio* interrfaces (which then invoke 5 aforementioned > wrappers). Yes, database applications, in particular, are more fond of these interfaces than the posix ones. Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-18 20:40:08
|
On Wed, Jun 18, 2008 at 6:28 PM, Michael Kerrisk <mtk...@go...> wrote: > On Wed, Jun 18, 2008 at 6:13 PM, Jeff Moyer <jm...@re...> wrote: >> "Michael Kerrisk" <mtk...@go...> writes: >> >>> On Wed, Jun 18, 2008 at 4:40 PM, Jeff Moyer <jm...@re...> wrote: >>>> "Michael Kerrisk" <mtk...@go...> writes: >>>> >>>>> On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: >>>> >>>>>> Given that there are consumers of the libaio library, I will continue to >>>>>> maintain it. So, I don't see a need to tell folks not to use it. >>>>> >>>>> I meant to ask... So yes there are consumers of the library, but I >>>>> wonder if there are actually consumers (outside the library itself) >>>>> of those 5 io_*(2) syscall wrappers. Any idea on that? >>>> >>>> I'm not sure I understand your question. Are you referring to these >>>> calls? >>>> >>>> io_setup >>>> io_getevents >>>> io_submit >>>> io_destroy >>>> io_cancel >>> >>> Yes, I meant: are apps using these wrappers *directly*, rather than >>> using the POSIX aio* interrfaces (which then invoke 5 aforementioned >>> wrappers). >> >> Yes, database applications, in particular, are more fond of these >> interfaces than the posix ones. > > Thanks for clearing that up. > > So in the end it sounds like I'll need to document the aberrant > behavior of these 5 wrappers, and note that life is different if you > use syscall(2). And the text I'll add to each page is something like this: RETURN VALUE On success, io_cancel() returns 0. For the failure return, see NOTES. NOTES Glibc does not provide a wrapper function for this system call. The wrapper provided in libaio for io_cancel() does not follow the usual C library conventions for indicating error: 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 syscall(2), then the return value follows the usual conventions for indicating an error: -1, with errno set to a (positive) value that indicates the error. Seem okay? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-18 20:47:49
|
"Michael Kerrisk" <mtk...@go...> writes: > On Wed, Jun 18, 2008 at 6:28 PM, Michael Kerrisk > > And the text I'll add to each page is something like this: > > RETURN VALUE > On success, io_cancel() returns 0. For the failure > return, see NOTES. > > NOTES > Glibc does not provide a wrapper function for this system > call. > > The wrapper provided in libaio for io_cancel() does not > follow the usual C library conventions for indicating > error: 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 syscall(2), then the return > value follows the usual conventions for indicating an > error: -1, with errno set to a (positive) value that > indicates the error. > > Seem okay? That looks fine to me. Thanks for your persistence; we all benefit from better documentation. Cheers, Jeff |
From: Masatake Y. <ya...@re...> - 2008-06-19 02:48:14
|
> And the text I'll add to each page is something like this: > > RETURN VALUE > On success, io_cancel() returns 0. For the failure > return, see NOTES. > > NOTES > Glibc does not provide a wrapper function for this system > call. > > The wrapper provided in libaio for io_cancel() does not > follow the usual C library conventions for indicating > error: 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 syscall(2), then the return > value follows the usual conventions for indicating an > error: -1, with errno set to a (positive) value that > indicates the error. Really good. I have learnt many your discussion. Thank you. >>>> io_setup >>>> io_getevents >>>> io_submit >>>> io_destroy >>>> io_cancel How about other system calls than io_cancel? I'll write test cases for them based on your man page. I wonder the NOTES are applicable to the other system call. Masatake |
From: Michael K. <mtk...@go...> - 2008-06-19 14:17:14
|
Masatake, On Thu, Jun 19, 2008 at 4:48 AM, Masatake YAMATO <ya...@re...> wrote: >> And the text I'll add to each page is something like this: >> >> RETURN VALUE >> On success, io_cancel() returns 0. For the failure >> return, see NOTES. >> >> NOTES >> Glibc does not provide a wrapper function for this system >> call. >> >> The wrapper provided in libaio for io_cancel() does not >> follow the usual C library conventions for indicating >> error: 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 syscall(2), then the return >> value follows the usual conventions for indicating an >> error: -1, with errno set to a (positive) value that >> indicates the error. > > Really good. I have learnt many your discussion. > Thank you. > >>>>> io_setup >>>>> io_getevents >>>>> io_submit >>>>> io_destroy >>>>> io_cancel > > How about other system calls than io_cancel? > I'll write test cases for them based on your man page. I'm not sure how much the man pages will help == some of the io_* man pages seem rather thin on details. > I wonder the NOTES are applicable to the other system call. Yes, I have added similar text to all of the io_* pages. It will be in man-pages-3.01. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Michael K. <mtk...@go...> - 2008-06-18 16:28:21
|
On Wed, Jun 18, 2008 at 6:13 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> On Wed, Jun 18, 2008 at 4:40 PM, Jeff Moyer <jm...@re...> wrote: >>> "Michael Kerrisk" <mtk...@go...> writes: >>> >>>> On Wed, Jun 18, 2008 at 3:51 PM, Jeff Moyer <jm...@re...> wrote: >>> >>>>> Given that there are consumers of the libaio library, I will continue to >>>>> maintain it. So, I don't see a need to tell folks not to use it. >>>> >>>> I meant to ask... So yes there are consumers of the library, but I >>>> wonder if there are actually consumers (outside the library itself) >>>> of those 5 io_*(2) syscall wrappers. Any idea on that? >>> >>> I'm not sure I understand your question. Are you referring to these >>> calls? >>> >>> io_setup >>> io_getevents >>> io_submit >>> io_destroy >>> io_cancel >> >> Yes, I meant: are apps using these wrappers *directly*, rather than >> using the POSIX aio* interrfaces (which then invoke 5 aforementioned >> wrappers). > > Yes, database applications, in particular, are more fond of these > interfaces than the posix ones. Thanks for clearing that up. So in the end it sounds like I'll need to document the aberrant behavior of these 5 wrappers, and note that life is different if you use syscall(2). Ben, I'm still curious why there is the aberration, if you have some insight... Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Michael K. <mtk...@go...> - 2008-06-18 20:35:31
|
Jeff, veering off a little... Why are there some .1 (*not* .2) pages in the libaio tree for these system calls? Most of the pages are just stubs, but io_submit looks to have useful information. Cheers, Michael |
From: Jeff M. <jm...@re...> - 2008-06-18 20:46:29
|
"Michael Kerrisk" <mtk...@go...> writes: > Jeff, > > veering off a little... > > Why are there some .1 (*not* .2) pages in the libaio tree for these > system calls? Most of the pages are just stubs, but io_submit looks > to have useful information. I have no idea. The only log entry in CVS for those files is: libaio-0.4.0 targetted changes The man pages are not part of the top-level install target, so at least they've never been unleashed on the world. Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-19 14:21:41
|
Jeff, On Wed, Jun 18, 2008 at 10:46 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> Jeff, >> >> veering off a little... >> >> Why are there some .1 (*not* .2) pages in the libaio tree for these >> system calls? Most of the pages are just stubs, but io_submit looks >> to have useful information. > > I have no idea. The only log entry in CVS for those files is: > > libaio-0.4.0 targetted changes > > The man pages are not part of the top-level install target, so at least > they've never been unleashed on the world. Could you take a look at the io_submit.1 page in the libaio package, and compare it to the io_submit.2 in man-pages (http://www.kernel.org/doc/man-pages/online/pages/man2/io_submit.2.html ). The libaio page mentions details that aren't in the man-pages. Is there some content in the former that should be moved to the latter? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Jeff M. <jm...@re...> - 2008-06-19 19:10:42
|
"Michael Kerrisk" <mtk...@go...> writes: > Jeff, > > On Wed, Jun 18, 2008 at 10:46 PM, Jeff Moyer <jm...@re...> wrote: >> "Michael Kerrisk" <mtk...@go...> writes: >> >>> Jeff, >>> >>> veering off a little... >>> >>> Why are there some .1 (*not* .2) pages in the libaio tree for these >>> system calls? Most of the pages are just stubs, but io_submit looks >>> to have useful information. >> >> I have no idea. The only log entry in CVS for those files is: >> >> libaio-0.4.0 targetted changes >> >> The man pages are not part of the top-level install target, so at least >> they've never been unleashed on the world. > > Could you take a look at the io_submit.1 page in the libaio package, > and compare it to the io_submit.2 in man-pages > (http://www.kernel.org/doc/man-pages/online/pages/man2/io_submit.2.html > ). The libaio page mentions details that aren't in the man-pages. Is > there some content in the former that should be moved to the latter? Yes, the description of the iocb structure is pertinent. Also, your man page seems to use "I/O request block" for iocb. Why don't you use I/O control block? Cheers, Jeff |
From: Michael K. <mtk...@go...> - 2008-06-20 08:36:40
|
Hi Jeff, On Thu, Jun 19, 2008 at 9:10 PM, Jeff Moyer <jm...@re...> wrote: > "Michael Kerrisk" <mtk...@go...> writes: > >> Jeff, >> >> On Wed, Jun 18, 2008 at 10:46 PM, Jeff Moyer <jm...@re...> wrote: >>> "Michael Kerrisk" <mtk...@go...> writes: >>> >>>> Jeff, >>>> >>>> veering off a little... >>>> >>>> Why are there some .1 (*not* .2) pages in the libaio tree for these >>>> system calls? Most of the pages are just stubs, but io_submit looks >>>> to have useful information. >>> >>> I have no idea. The only log entry in CVS for those files is: >>> >>> libaio-0.4.0 targetted changes >>> >>> The man pages are not part of the top-level install target, so at least >>> they've never been unleashed on the world. >> >> Could you take a look at the io_submit.1 page in the libaio package, >> and compare it to the io_submit.2 in man-pages >> (http://www.kernel.org/doc/man-pages/online/pages/man2/io_submit.2.html >> ). The libaio page mentions details that aren't in the man-pages. Is >> there some content in the former that should be moved to the latter? > > Yes, the description of the iocb structure is pertinent. Thanks. I'll have a shot at integrating that text. > Also, your man page seems to use "I/O request block" for iocb. > Why don't you use I/O control block? I didn't write these pages, and I haven't given them a whole lot of love in the time I've been maintainer. This thread prompted me to give them a closer look. Your suggestion of course makes sense, and I fixed that in io_submit.2. Cheers, Michael > > Cheers, > > Jeff > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html |
From: Masatake Y. <ya...@re...> - 2008-06-18 09:12:59
|
> On Wed, Jun 18, 2008 at 10:04 AM, Masatake YAMATO <ya...@re...> wrote: > > Dear man page maintainer > > > > Thank you for your great work. > > > > I'm working for test cases for io_channel(2) of linux kernel > > Do you mean io_cancel(2)? I'm sorry. You are right. I'm talking about io_cancel(2). > > in Linux Test Project. > > > > > > During writing the test cases, I found some mistakes. > > Could you apply my patch to your master nroff file? > > What version of man-pages are you looking at? This patch doesn' seem > to match a problem in my io_cancel page: > > http://www.kernel.org/doc/man-pages/online/pages/man2/io_cancel.2.html man-pages-3.00. io_cancel returns negative value if an error occurs. My patch points out this. > PS Patches are good, but "diff -u" form is preferred. I'll use -u next time. Sorry this time. Masatake |