8

The kernel sources contain functions and data structures which are documented, for instance in panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

Instead of going through the sources every time, it would be useful to view those APIs as manpages and leverage this existing documentation framework.


How do you install/make the kernel section 9 manpages(/usr/share/man/man9) which document the aforementioned functions and data structures?

  • 2
    Care to share the distro you're using? – tink Aug 5 '14 at 2:36
  • Why are you so sure there are always man pages (especially updated) for every release? – mdpc Aug 5 '14 at 2:39
  • 1
    @mdpc why wont a well maintained kernel will not have any man pages,i think my question is valid – kakeh Aug 5 '14 at 2:43
  • 3
    "You need to install xmlto " seems like the place to start, no? – Braiam Aug 5 '14 at 2:44
  • @Bralam updated the surprise :( – kakeh Aug 5 '14 at 2:49
5

The content is parsed directly (see also this) from the source .c files1:

In order to provide embedded, 'C' friendly, easy to maintain, but consistent and extractable documentation of the functions and data structures in the Linux kernel, the Linux kernel has adopted a consistent style for documenting functions and their parameters, and structures and their members.

The format for this documentation is called the kernel-doc format. It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.

This style embeds the documentation within the source files, using a few simple conventions. The scripts/kernel-doc perl script, some SGML templates in Documentation/DocBook, and other tools understand these conventions, and are used to extract this embedded documentation into various documents. [...]

The opening comment mark "/**" is reserved for kernel-doc comments. Only comments so marked will be considered by the kernel-doc scripts, and any comment so marked must be in kernel-doc format.

Which means only such formatted comments can be extracted this way and that you could leverage the kernel-doc Perl script used by the make process:

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

and therefore that you are not limited to the mandocs target:

After installation, "make psdocs", "make pdfdocs", "make htmldocs", or "make mandocs" will render the documentation in the requested format.

There are also driver specific text files in the kernel repository/source. More generally, their Linux man-pages project (man1 through man8) is available for download. On a last note kernel.org also maintains some output documentation.


1. The kernel is not the only case where such a technique is used to generate manpages. GNU coreutils is one such other case; most of its manpages are generated using the output of command --help the content of which is in the usage function the utility source file ( 1 2 ).

  • make mandocs throws me Makefile:19: /Documentation/DocBook/media/Makefile: No such file or directory – kakeh Aug 6 '14 at 17:44
  • yes i have it but Documentation/ is not present in /its present in /lib/modules/3.2.0-57-generic-pae/build/ – kakeh Aug 7 '14 at 3:04
  • @Shyam Those are the files for the modules etc., like the link to text files in my A. You can maybe try ./scripts/kernel-doc -man ./**/*.c >mydoc from the sources top directory and see if you can't put in all directly into one file by parsing the sources directly. – user44370 Aug 7 '14 at 3:16
4

Assuming you are using Ubuntu,

apt-get install linux-manual-3.2

or similar (pick the correct version). There is also another documentation package

apt-get install linux-doc

but this is html.

  • this doesnt show kernel api's documentation – kakeh Aug 6 '14 at 17:18
  • @Shyam Example? – Faheem Mitha Aug 6 '14 at 17:22
  • 1
    On Arch(Bang) I have: linux-manpages 3.14-1 which contains the section 9 manpages! Thank you! An example is kcalloc.9.gz. There is about 4000 of them... – user44370 Aug 7 '14 at 2:39
  • @Faheem Mitha treid of viewing the man alloc_register_region but said no manual entry are docs different from man pages ?? – kakeh Aug 7 '14 at 3:07
  • @FaheemMitha i dont think kernel's low level api's are available with linux-doc ! – kakeh Aug 7 '14 at 3:09
3

Download the kernel source code and in the source dir execute

make mandocs

After the man documents have been made, execute

make installmandocs

This will install the manual pages into /usr/local/man/man9/. Now you can view man pages by typing man <api-name>, or if you are editing in vim just press K over the API name.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.