On Thu, May 10, 2012 at 2:27 AM, Cyril Hrubis <chrubis@xxxxxxx> 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
