MidnightBSD: The BSD For Everyone

Manual Pages and Info Files

Manual Pages and Info Files

Introduction

The most comprehensive documentation on MidnightBSD is in the form of manual pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and available arguments. Manual pages are always available offline and are considered the authoritative reference for the commands, system calls, file formats, and devices that ship with the operating system.

Manual pages are intentionally terse. They document what a command does and what options it accepts, but they are not tutorials. For step-by-step guides and conceptual explanations, consult the documentation on this website or the FreeBSD Handbook, whose coverage of base system topics applies equally to MidnightBSD.

MidnightBSD manual pages are also available online at man.midnightbsd.org. This is useful for looking up documentation from another machine or when the system is not available.

Reading Manual Pages

Manual pages are viewed with the man command:

For example, to read the manual page for ls:

To read the manual page for man itself:

Manual pages open in a pager (usually less or more) so you can scroll through them. Press q to quit. See the Pager Navigation section for a full list of navigation keys.

References to manual pages in written documentation use parenthetical section numbers, such as ls(1) or chmod(2). The number indicates which section of the manual contains that entry. This notation is a hint that you can look up the topic with man.

Manual Page Sections

Manual pages are divided into numbered sections representing the type of topic. In MidnightBSD the following sections are available:

• 1 — User commands. Programs you run from the shell, such as ls(1), cp(1), and grep(1).
• 2 — System calls and error numbers. Kernel interfaces called directly from C programs, such as open(2), fork(2), and read(2).
• 3 — Functions in the C libraries. Library functions such as printf(3), malloc(3), and strcmp(3).
• 4 — Device drivers and special files. Documentation for kernel drivers and devices under /dev, such as ada(4) and em(4).
• 5 — File formats and conventions. Descriptions of file formats such as fstab(5), rc.conf(5), and passwd(5).
• 6 — Games and other diversions.
• 7 — Miscellaneous information. Overviews of topics that do not fit elsewhere, such as hier(7) (the file system hierarchy) and environ(7) (the process environment).
• 8 — System maintenance and operation commands. Administrative tools typically run as root, such as mount(8), fsck(8), and sysctl(8).
• 9 — System kernel interfaces. Internal kernel functions and interfaces for kernel developers, such as malloc(9) and mutex(9).

A quick way to remember: sections 1 and 8 cover commands (user and admin respectively), sections 2 and 3 cover programming interfaces, section 4 covers drivers, and section 5 covers configuration file formats.

Specifying a Section

In some cases, the same topic name appears in more than one section. For example, chmod is both a user command (section 1) and a C library system call (section 2). Running man chmod without a section number displays the first match found, which may not be the one you want.

To display the manual page from a specific section, provide the section number before the topic name:

Other examples where specifying the section matters:

To see all available sections for a given name, use the -a flag. Each matching manual page is displayed in turn; press q to advance to the next one:

Searching Manual Pages

If you do not know the exact name of a command or function, use man -k to search the short description of every manual page for a keyword:

This displays a list of manual page entries whose descriptions contain the word "mail". The output format is name(section) — description. This is equivalent to the apropos command:

To search for an exact command name match rather than a keyword, use whatis. It shows only entries whose name exactly matches the argument:

To read the short descriptions for all commands in a directory:

The apropos and whatis databases are built from the manual pages installed on the system. If they return no results after installing new software, rebuild the database as root:

Manual Page Layout

Most manual pages follow a standard structure. Knowing these sections makes it faster to find the information you need:

• NAME — The command name and a one-line description. This is the text indexed by whatis and apropos.
• SYNOPSIS — The command syntax. Square brackets ([ ]) enclose optional arguments. An ellipsis (...) means the argument may be repeated. Items in italics or underline are placeholders for values you supply.
• DESCRIPTION — A detailed explanation of what the command does and what each option means.
• EXAMPLES — Practical usage examples (not always present but very useful when included).
• FILES — Configuration files and other files the command reads or writes.
• EXIT STATUS — The numeric exit codes the command returns and what they mean.
• ENVIRONMENT — Environment variables that affect the command's behavior.
• SEE ALSO — Related manual pages. This is a good way to discover connected commands and concepts.
• BUGS — Known limitations or defects.
• HISTORY — When the command was introduced and notable changes over time.

When reading an unfamiliar manual page, start with NAME for a quick summary, then SYNOPSIS to understand the argument structure, then DESCRIPTION for the details. Check SEE ALSO to find related pages that may be more relevant to your task.

Pager Navigation

Manual pages are displayed through a pager. The default pager is set by the PAGER environment variable; less is the most common choice. See the Shells documentation for how to set PAGER.

Key bindings when reading a manual page in less:

• Space or f — scroll forward one screen
• b — scroll backward one screen
• d — scroll forward half a screen
• u — scroll backward half a screen
• j or Down — scroll down one line
• k or Up — scroll up one line
• g — go to the beginning
• G — go to the end
• /pattern — search forward for a pattern
• ?pattern — search backward for a pattern
• n — repeat the last search forward
• N — repeat the last search backward
• h — display help for less itself
• q — quit

To open a manual page at the first occurrence of a search term directly:

To display a manual page formatted as plain text (useful for saving or piping):

MANPATH and Additional Pages

The man command searches a list of directories defined by the MANPATH environment variable. The default path includes /usr/share/man for the base system and /usr/local/share/man for software installed via mports.

If you install software to a non-standard location, add its manual directory to MANPATH in your shell startup file:

In tcsh:

To see the directories man is currently searching:

Manual pages for mports software are installed automatically when you install a package. They are placed in /usr/local/share/man, which is included in the default search path.

To display the manual page for a program installed in /usr/local without setting MANPATH:

GNU Info Files

MidnightBSD includes several applications and utilities produced by the Free Software Foundation (FSF). In addition to manual pages, these programs may include hypertext documents called info files. Info files use a node-and-link structure similar to a web page, allowing you to navigate between topics.

Info files are typically more detailed than manual pages for GNU software such as gcc, make, and the GNU C library. If a manual page's SEE ALSO section references an info file, the info file is likely the more complete reference.

To open the info reader at the top-level directory of all installed info files:

To open the info documentation for a specific program:

Navigation inside the info reader:

• h — display a brief introduction to info navigation
• ? — display a quick command reference
• Space — scroll forward through the current node
• Backspace — scroll backward through the current node
• n — go to the next node at the same level
• p — go to the previous node at the same level
• u — go up to the parent node
• t — go to the top node of the current document
• d — go to the top-level info directory
• s pattern — search for a pattern in the current file
• Enter — follow a cross-reference link
• l — go back to the last node visited
• q — quit

If emacs is installed from mports, you can browse info files in its built-in info mode, which provides a more comfortable reading experience with mouse support. Launch it with:

Or from within emacs, press C-h i (Ctrl+h then i).