Linux 101 (Part 3): Manual Pages explained

Learn Linux CLI the Right Way

Objective

After exploring basic command structure in Part 2, a crucial insight emerges, commands in Linux operating system have significant variation in their behavior. This diversity can be shown in several ways:

Input handling: Some commands require input parameters, others function without any, and certain commands can process multiple inputs simultaneously.

Option formatting: Many commands support long-form options (like --help), while others only recognize short-form flags (like -h).

Syntax patterns: Certain commands use equal signs (=) to assign values to options (e.g., command --option=value), whereas others employ spacing (e.g., command --option value).

Given this complexity, a critical question arises: How can we systematically determine the proper usage patterns for any specific command? How do we discover which options are available, what inputs are acceptable, and what syntax rules apply?

The solution lies in manual pages (commonly called "man pages"). Each command in a Linux system comes with its own comprehensive documentation.

In this tutorial, we will:

1. Learn how to access manual pages using the “man” command

2. Understand the standard structure of manual pages

3. Navigate efficiently through documentation

4. Extract relevant information for specific use cases

By mastering the use of manual pages, you'll gain the ability to self-guide through any command's capabilities, significantly enhancing your command-line proficiency and reducing dependency on external resources.

---

Manual Structure

When exploring manual pages in Linux, it's important to recognize that they are organized into a structured system of 8 distinct sections. This organization isn't random - it's a deliberate categorization that helps you navigate the vast documentation available in your Linux system.

1. Section-1: User Commands

Contains documentation for commands that can be executed by regular users regardless of their privileges (we will discuss privileges and permissions later). These include everyday commands like ls, date, cal, and other utilities you commonly use at the command line.

2. Section-2: System Calls

Contains documentations about programming functions, These are the core functions that allow software to request services from the operating system kernel, such as read(), write(), and fork(). So unless you are doing some advanced stuff you probably not going to use section 2.

3. Section-3: C Library Functions

Covers programming library functions like those found in the C standard library. These include string manipulation functions, mathematical operations, and other programming resources, similar to section 2 mostly you are not going to use it.

4. Section-4: Devices and Special Files

Details information about device files and drivers, typically found in the /dev directory. This section helps understand how Linux interfaces with hardware components.

5. Section-5: File Formats and Conventions

This section is like a dictionary that explains the structure and format of the important files your system uses to store settings and information. For example, if you want to understand how the /etc/passwd file works (which stores user account information) then you need to refer to this section.

6. Section-6: Games

Contains documentation for games and fun programs included with the Linux distribution.

7. Section-7: Miscellaneous

Covers various topics that don't fit neatly elsewhere, including protocols, file systems, and conventions.

8. Section-8: System Administration

Documents commands that typically require administrative (root) privileges. These powerful utilities handle system configuration, user management, and other administrative tasks.

Summary

When using the “man” command (as we will see in the next section below), you can specify which section to search by providing the section number before the command name (e.g., man 5 passwd to view information about the password file format rather than the passwd command).

we will mostly spend our time within three sections only, User Commands, File Formats, and System administration.

---

Search, Access and Read the Manual Pages

Now you know that the manual is broken into 8 sections, how to know into which section you should look in order to find what you are searching for?

let’s assume that you wanted to look for information about the “which” command, first to search the manual you have to use the “man” command which is short for the word “manual”, Next we need to provide “-k “option which is used for searching, and finally we need to provide our input which is the search term and in our case it’s “which” command:

root@vps004:~# man -k which 
getcpu (2)           - determine CPU and NUMA node on which the calling thread is running
getgrouplist (3)     - get list of groups to which a user belongs
git-sparse-checkout (1) - Initialize and modify the sparse-checkout configuration, which reduces the checkout to a set of paths given by a list of patterns.
ifcfg (8)            - simplistic script which replaces ifconfig IP management
lcf (1)              - Determine which of the historical versions of a config is installed
pam_exec (8)         - PAM module which calls an external command
pam_warn (8)         - PAM module which logs all PAM items if called
sched_getcpu (3)     - determine CPU on which the calling thread is running
securetty (5)        - file which lists terminals from which root can log in
which (1)            - locate a command

To the left, we got the name of certain manual pages, and to the right we got a bit of synopsis (description for the specific man page)

next to the manual page name, between (parentheses) we got the section number, for example the last line of our output:

• Manual page name: which

• Section: (1)

• description: locate a command

so it’s clear that the name of the manual page we are looking for is “which” and it’s in section 1 (User Commands), so let’s go ahead and open this documentation page that will explain to us how we can use the “which” command.

to open manual page:

man + SectionNumber + PageName

applying to that to our example, the command we need to type will be:

man 1 which

now because section 1 is used so often, we can skip the section number and just type:

man which

and we will get the following documentation page about which command as an output, in order to close the page and get back to CLI, just press “q”

So how do we read the manual page?

When you open a manual page using the man command (like man which), you'll notice it's organized into several standard sections that make it easier to find the information you need:

• Name: The command name and a brief one-line description of what it does.

• Synopsis: Shows the command's syntax pattern - how to structure the command with its options and arguments. This gives you a quick overview of command layout and how to actually type the command.

back to our example above, we can see the “which” command syntax is:

which [-a] filename ...

• which : this is the command (program) name that you will type first thing

• [-a] : this -a option is optional, and we can tell it’s optional because it’s inside of square brackets, in man page if [something] is inside square brackets that means it’s optional and you can understand what this option is doing by reading the “options” part of the man page

• filename … : this is your input, for example you are looking for “echo” using “which” command then “echo” is your input in this case. but we also see these three dots … this means that you can enter more than one input.

so just to prove what we learned here, let’s use the “which” command:

root@vps004:~# which -a echo cal date
/usr/bin/echo
/bin/echo
/usr/bin/cal
/bin/cal
/usr/bin/date
/bin/date

so we used the “which” command to find 3 different commands paths at the same time, “cal” , “date” and “echo”.

• Description: Provides a detailed explanation of the command's purpose and functionality. it’s very useful part that tells what the command actually do.

• Options: Lists all available command-line options (like -a or --all) with descriptions of what each one does.

• Exit Status: Explains the possible return codes when the command finishes, which are useful for scripting.

Additional Sections You Might Find

• Examples: Shows practical usage examples to demonstrate how the command works in real scenarios.

• See Also: References related commands or additional documentation sources.

• Environment: Describes any environment variables that affect the command's behavior.

• Files: Lists important files associated with the command.

• Bugs: Known issues or limitations.

• Authors: Credits the creators or maintainers.

---

Manual Page Notation

• Square brackets [ ]: Indicate optional elements. For example, in ls [-a] directory, the -a flag is optional.

• Angle brackets < >: Indicate required elements. If you see mv <source> <destination>, both the source and destination parameters are mandatory.

• Vertical bar |: Represents "OR" - you must choose one of the options. For example, command [-a|-b] means you can use either -a OR -b, but not both.

• Ellipsis ...: Indicates that you can repeat the previous element. For example, cp [option]... source... directory means you can provide multiple options and multiple source files.

---

Additional Tips for Reading Man Pages

1. Keyboard Navigation: Use Space to scroll down a page, B to scroll back up, and Q to quit.

2. Searching: Press / followed by your search term to find text within the man page. Use n to find the next occurrence.

3. Section Jumping: Press g to go to the top of the page or G to go to the bottom.

4. Man Page for Man: Try man man to learn more about the manual system itself.

5. Quick Help: The -h or --help flag with most commands provides a condensed version of the manual page.

---

Summary

• You understand The benefit of Manual pages.

• You understand how the manual pages are categorized in 8 sections

• You understand how to search the manual pages using man -k and find the one you are looking for.

• You understand how to access a specific man page using “man SectionNumber PageName”

• You understand how to read the manual pages for specific command structure and translate different symbols into their meaning.

---