Locating Man Pages Across Languages And Sections On Linux

Finding Man Pages for Commands

The man pages on Linux provide detailed documentation on system commands, configuration files, APIs, and more. However, locating the right man page can be challenging due to the extensive documentation distributed across languages and manual sections.

The first step in finding man pages is understanding the different locations they can reside. Man pages are found in section directories stemming from central directories where the man system stores its database of preformatted and compressed documentation.

Search Paths for Locating Man Pages

When executing the man command to view documentation, your system searches a standard set of paths including:

Table of Contents

/usr/local/share/man
/usr/share/man
/opt/*/man – Contains man pages for software residing in /opt

You can view the current man page search path by inspecting the MANPATH environment variable:

$ echo $MANPATH
/usr/local/share/man:/usr/share/man

If needed, you can customize the search path by modifying MANPATH to meet your requirements.

Viewing Man Pages in Different Languages

Man pages on Linux come translated into various languages. English documentation has the .ez extension while other languages use their two-character ISO 639-1 language code. For example:

de = German
es = Spanish
fr = French

To view man pages in your preferred locale, set the LANG environment variable appropriately:

$ export LANG=de_DE.utf-8
$ man ls

This will display German translations for programs that offer multilingual documentation.

Navigating Man Page Sections

Beyond different languages, man pages also reside in different manual sections. Sections group related documentation into eight standard areas plus additional custom sections:

Executable programs and shell commands
System calls provided by the kernel
Library calls offered by program libraries
Special files found in /dev
File formats and protocols like /etc/passwd
Games and fun diversionary programs
Overviews, conventions, and miscellaneous documentation
System administration and privileged commands

Identifying the appropriate section gives you better precision when locating information. We will explore accessing distinct sections later on.

Using the man Command

With an understanding of where documentation resides, you can now leverage the man utility to access man pages. The man command offers options to specify sections and search for relevant content.

Specifying Sections with man

By default man searches available sections looking for the first matching page. You can have man display a specific section by using the -s option:

$ man -s 2 open

This will show the man page for open found in section 2, describing the kernel system call interface. Specifying a section helps when multiple man pages share the same name.

Searching Man Pages with man

Beyond viewing a particular man page, you can search for content across all documentation on your system using the -k option:

 
$ man -k file system
ext4 (5)            - ext4 filesystem format
mkfs (8)            - build a Linux filesystem
mount (8)           - mount a filesystem

This prints descriptions of relevant man pages containing your search phrases. You can then access any individual page for more details.

Locating Man Pages by Section

With thousands of man pages available, narrowing your search by section helps restrict results to relevant areas of documentation.

Standard Man Page Sections

The defined man sections provide a basic starting point when browsing documentation:

Section 1 – User commands provided by shells and command interpreters primarily found in /bin and /usr/bin. This includes fundamental programs like ls, grep, cp and system administration tools.
Section 2 – Kernel system calls and facilities provided by the Linux kernel, located under /usr/include/linux/. This covers interactions between processes and the kernel such as open, read, exit.
Section 3 – Library calls that language bindings and application libraries implement, usually C. Found under /usr/include/, this includes functionality like printf, socket, and other common programming interfaces.
Section 4 – Device files that reside in /dev. Man pages document drivers and information on interfacing with hardware like terminals, serial ports, input devices.
Section 5 – File formats found in /etc as well as common protocols like /etc/passwd, /etc/shadow, NFS, and more.
Section 6 – Games and entertainment programs located in /usr/games.
Section 7 – Overviews, conventions like filesystem hierarchy standards, character set guides, and standards.
Section 8 – Commands typically reserved for root and system administration tasks found in /usr/sbin.

Special Man Page Sections

Beyond the defaults, some software packages provide custom man page sections for additional context:

Section 9 – Kernel routines offering interfaces for kernel development and embedding.
Section n – New commands in the default category before moving to main sections after maturing.
Section l – Local application documentation specific to the system.
Section p – POSIX standards which Unix systems implement.
Section o – Old commands provided for legacy script compatibility.

Special sections contain relevant documentation but may require extra effort locating since they are not consistently populated or available.

Man Page Directories and Organization

Man pages reside in hierarchies of section directories branching from central man page database locations. Understanding this storage structure helps track down missing pages or install custom documentation.

Typical Man Page Directory Structure

A regular Linux system stores man pages under /usr/share/man where they are compressed, preformatted, and indexed for searching. Within this directory, pages split into section folders like:

/usr/share/man
  /man1
  /man2 
  /man3
  /man4
  /man5 
  /man6
  /man7
  /man8

Each numeric directory contains all man pages fitting the respective section categorization scheme. Further levels separate individual pages into subtopics and areas of focus.

System Man Page Locations

The main system-wide repository under /usr/share/man provides documentation for OS packages and globally accessible commands. Additionally, other standard locations can house relevant pages including:

/usr/local/share/man – Man pages for user installed software residing in /usr/local following common FreeBSD directory conventions.
/usr/X11R6/man – Man pages covering X Window System commands and standards.
/opt/*/man – Documentation for commercial software packages located under /opt.

Custom Man Page Locations

If you do not have access permissions for the main system /usr/share/man hierarchy, you can still reference local custom man pages. Simply set MANPATH to include additional directories containing your own documentation.

This method also allows extending available man pages for niche programs. Rather than modify main system storage areas, user and custom man pages can reside in their own distinct locations while still being findable by man and other tooling for a self-contained customized documentation set.

$ export MANPATH=$HOME/myman:$MANPATH 
$ man myprogram

Troubleshooting Missing Man Pages

Despite man documentation spanning languages and manual sections, you may still encounter cases of missing pages. Several steps can help track down or restore absent documentation.

Checking Environment Variables

First, verify that essential environment variables like MANPATH, LANG, and LOCPATH are set correctly. Common issues include:

MANPATH not including custom documentation directories.
Missing localization preventing translated content from appearing.
LOCPATH not allowing NLS data from being found.

Double check variables are:

Listing all man page repository locations.
Enabling your preferred locale and language.
Pointing to the right NLS data paths.

Run env to inspect if settings seem correct.

Rebuilding Man Page Databases

If environmental configuration appears solid, a missing or corrupted database index may be interfering with man page queries. Try recreating the cached man page directory database:

# mandb

This will regenerate the stored index from scratch which may reveal previously hidden pages. Additionally, on RPM/Yum based systems, ensure man DB packages are fully installed for proper search functionality.