On Mon, May 7, 2012 at 11:14 PM, Michael Kerrisk (man-pages) <mtk.manpages@xxxxxxxxx> wrote: > Jeff, Cyril, > > On Tue, May 8, 2012 at 1:44 AM, Jeff Moyer <jmoyer@xxxxxxxxxx> wrote: >> "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> writes: >> >>> On Thu, Oct 13, 2011 at 9:29 PM, Cyril Hrubis <chrubis@xxxxxxx> 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
