This document was written for
A Tour through the NetBSD Documentation
Part I: Manual Pages
Hubert Feyrer, March 2001
"RTFM" is the Unix way of telling people to have a look at the
documentation. Often, users new to a system don't know where all the
fantastic manuals are, how to access them and/or what the topics
covered are. To approach this problem from the practical side, this
text gives a tour through all the documentation that's shipped in the
NetBSD 1.5 system.
It is assumed that all the base operating system's sets are installed,
including base, comp, text, misc and share. Besides that, there are
some rather interesting papers in the sources, which are expected to
be unpacked under /usr/src.
As another side note on systems, most concepts and contents are not
only present on NetBSD, but are also present on fellow BSD and other
Unix systems. The papers available in the third part of this are
special to the BSD world, but info pages can be found on all systems
using GNU software, and man pages are THE documentation format found
on all Unix systems used today.
Traditionally, the Unix manuals came in print (dead-tree) version, and
in an online readable form at the same time. The manuals were divided
into several chapters, describing user commands, system calls,
etc. Usually, one manual "page" describes one such
command/call/whatever, even though the real description may be much
longer than one physical page. To make it clear which section of the
manual a certain page belongs to, the section is appended in
parentheses right after the command etc. described, e.g. ls(1) tells
the user that the 'ls' command is described in section 1 of the manual
pages, open(2) is from section two, etc.
Now if one knows what sections there are, he can take an educated
guess at where to start looking for documentation. In the BSD world,
manual sections go from 1 to 9, and the topics they cover are
- 1: General tools and utilities intended to be used by users.
- Covers all the commands in your /bin and /usr/bin dirs such as
text editors, command shell interpreters, searching and
sorting tools, file manipulation commands system status
commands, remote file copy commands, mail commands, compilers
and compiler tools, formatted output tools, and line printer
commands. 440 manual page entries.
- 2: System calls offered by the kernel.
- You will find an overview of the system calls provided by
NetBSD, the error codes they return together with their
meaning, and a number of commonly used definitions and
concepts like what a pathname is, distinction between real and
effective user/group id, and some more. 188 manual page
- 3: C library calls documentation.
- NetBSD comes with a fair set of libraries for C programming,
including the standard C library, the Curses screen library,
math routines and many more that contain all sort of
convenience functions. 1165 manual page entries.
- 4: Hardware, drivers and special files (devices).
- This section contains man-pages for about all hardware drivers
available on all NetBSD ports, including a description of the
hardware they support, any flavours like different chipsets,
and any flags available for tuning inside the kernel. Besides
drivers, many of the "special" files like /dev/zero are
described here. 471 manual page entries.
- 5: Binary and config file formats.
- The manpages found here document every config file found in
the /etc dir of NetBSD, as well as many other files and data
structures like the ones found in filesystem and directory
organisation, binary object and core files, and many more.
Good for a reading to get a deeper understanding of how many
things work in NetBSD even when you don't want to change
anything! 106 manual page entries.
- 6: Games - now that's what we have all been waiting for!
- Section 6 of the NetBSD manual pages describe the games found
in /usr/games as well as the small utilities found there that
help in factoring primes, predicting managerial behaviour and
other common tasks. 46 manual page entries.
- 7: Miscellaneous information that didn't fit elsewhere.
- There's always documentation that doesn't fit into any
category, and in NetBSD this is put together in this
section. Interesting items here are the hier(7) filesystem
structure documentation, various manpages on how to write
manpages, layout of a NetBSD release description, and some
others. 25 manual page entries.
- 8: System maintenance and operation command
- The system maintenance section documents things commonly found
in /sbin, /usr/sbin and a few other places. Administrative
concepts documented are user management, filesystem creation,
maintenance and backup, setting up network services like ftp,
rtadvd, NIS and many more. 429 manual page entries.
- 9: Internals for kernel hackers
- The last section of the NetBSD manual covers functions and
interfaces available inside the kernel. Among them are the bus
space and bus dma framework, the pool allocator, packet filter
interfaces, description of the various spl levels, callout,
rnd, real time and virtual memory interfaces. All manpages in
this section include code references into the live NetBSD
source. 304 manual page entries.
Accessing the Manual
To access any of the manual pages, the "man" (manual) command is
used. Give it the command, system call etc. you want documentation
on, optionally preceded by the manual section if you know it. E.g. to
get information on the man(1) command itself, type:
$ man 1 man
If you don't know exactly what you're looking for, a simple keyword
search is also available via the -k option of the man(1) command:
$ man -k manual
It will tell you any manpages and their section that match that
keyword, together with a short description of the manpage. An
alternative invocation of "man -k" is the apropos(1) command.
To get a detailed description on any of the manpage section with more
information like error codes and their reason, fundamental
concepts of system programming, etc., there's an "intro" manpage for
each section: intro(1), intro(2), etc. - be sure to have a look!
Last but not least, it should be mentioned that the manpages are
stored under /usr/share/man in NetBSD.
(c) Copyright 20000110 Hubert Feyrer
$Id: nbdocsI.html,v 1.2 2001/03/16 11:04:09 feyrer Exp $