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 |