Linux’s Built-in Manual
There’s an old (from the Unix golden era) Linux joke that the only command you need to know is man, the system entry point to the user manual. There’s a smidgen of truth in this, but even man can be confusing at first. Or, more accurately, finding the information you need can be confusing.
Have you ever known what you wanted to do, but didn’t know the name of the command that would get the task done? We’ve probably all been there. It’s like trying to look up a word in the dictionary when you don’t know the word.
So, how can you find what you’re looking for? Well, there are ways around this quandary with man.
The numbers are another freshman issue. What are they, and what do they mean? You’ll see things like man(2) or man(5) quoted in the documentation and on the internet. You’ll see references to commands followed by numbers, too, like mount(2) and mount(8). Surely there can’t be more than one mount command, right? As we’ll see, the numbers are important and relatively simple.
Speaking of simple, searching within man is pretty easy once you know how to do it. In fact, there are some neat ways you can search and navigate within man. Let’s fire it up and take a look!
RELATED: 37 Important Linux Commands You Should Know
How to Open the Manual
To use man, you type man on the command line, followed by a space and a Linux command. man opens the Linux manual to the “man page” that describes that command—if it can find it, of course.
Let’s type the following and see what man says about man:
The man page for man opens.
As you can see, this is the man(1) page.
Follow these tips to navigate the page:
To move through the man page one line at a time: Use the scroll wheel on your mouse, or the Up and Down arrow and Enter keys. To move through the man page one screen at a time: Press the Space bar, and the PgDn and PgUp keys. To move directly to the top or bottom of the man page: Press the Home and End keys.
If you press H, you enter the help section and see a table of alternate keystrokes you can use. Those listed above will probably feel more natural to most people.
To exit man, just press Q.
The Anatomy of a man Page
At the top of the page, you see the headings “Name” and “Synopsis.” There’s a convention to the layout of man pages. There are man pages for commands, programs, and programming functions (library routines). You won’t see all of these headings on every man page, because some of them only apply to certain types of commands.
The following are some of the headings you might see:
Name: The name of the command the man page is describing. Synopsis: A summary of the command and its syntax. Configuration: Configuration details for a device. Description: An explanation of what the program does. Options: A description of the command-line options the command accepts. Exit Status: Possible exit status values for the command, and what might cause them to be used. Return Value: If the man page is for a library routine, this describes the value the library routine can send back to the function that called that routine. Errors: A list of the values that might be placed in errno in the event of an error. Environment: A list of the environment variables that affect the command or program, and in what way. Files: A list of the files the command or program uses, such as configuration files. Attributes: A summary of various attributes of the command. Versions: Details of the Linux kernel or library versions where a system call or library function first appeared or changed significantly from previous versions. Conforming to: A description of any standards with which the command might comply, such as POSIX. Notes: Miscellaneous notes. Bugs: Known issues. Examples: One or more examples demonstrating the use of the command. Authors: The people who wrote or maintain the command. See also: Recommended reading related to the command or topic.
The man Sections
If you scroll down a couple of pages, you see a list of the sections in the manual.
The sections are:
General commands: Commands you use on the command line. System calls: Functions the kernel provides that a program can call. Library functions: Functions programs can call in code libraries (mainly the C standard). Special files: Usually devices, such as those found in /dev, and their drivers. File formats and conventions: Formats for files, such as the passwd, cron table, and tar archive files. Games: Descriptions of commands, like fortune, that display quotes from a database when you run them. Miscellaneous: Descriptions of things like inodes, boot parameters, and man itself. System administration: Commands and daemons usually reserved for root to work with. Kernel Routines: Information related to the internal operation of the kernel. This includes function interfaces and variables useful to programmers who are writing device drivers, for example. On most systems, this section isn’t installed.
When you see a command followed by a number, it’s referring to the description of that command in that section of the manual. For example, man(1) refers to the entry in section one of the manual describing the man command.
In the image above, you see a reference to man(7). This means there’s more information about man in another section. When we first opened the man page, it displayed man(1). If you type only man with no section number, man searches all the sections in order, looking for an entry for the command you typed. Of course, it found man(1) before man(7).
If you want to force man to find an entry from a specific section, you have to include the section number on the command line.
For example, we type the following to open the entry for man in section seven:
The manual opens to the man entry in section seven.
This man page provides instructions for writing man pages. It describes the file format and macros you can use to do some of the work for you. The man(1) page in section one we looked at earlier described how to use man itself.
How to Find Entries in Sections
Normally, if you simply want to know how to use a command, you don’t have to give a section number. man will find the standard entry that describes how to use that command in section one of the manual. Sometimes, though, you do need to open a command entry in a particular section because you want different information.
You can easily find out which sections of the manual contain entries for a command. Each man page has a title and a short description. The -f (whatis) option searches the page titles and returns a list of matches.
For this example, we type the following:
The two man pages for man are listed together with their section numbers and short descriptions. Be careful, though—some entries have the same name, but describe different commands and functions.
For example, we type the following:
It appears that two entries were found for printf: the first in section one, and another in section three. However, these are different commands. The man page in section one describes the command line printf command, which formats output in the terminal window. The man page in section three describes the printf family of library functions in the C programming language.
It’s also possible to search through the short descriptions, as well as the page titles. To do so, you use the -k (apropos) option. This will also match occurrences of the search term inside other, longer, words.
We type the following:
Many of these commands are described in the same few man pages because their core functionality is mainly the same. The man page for vprintf describes the functionality of 10 of the commands listed in the image above.
You can leverage this functionality to search for information related to what you’re trying to achieve, even if you don’t know the name of the command you want to use.
Let’s say you want to change the password of a user account. We can search for any commands that mention “user” in the man page titles or descriptions. We can then pipe it through grep to look for entries that contain “password.”
To do this, we type the following:
Because we enclosed the word “user” in single quotes and included a space at the end, it will only find matches for “user,” not “users.” A quick glance through the search results shows us the likely candidate is passwd.
Because it’s a section one man page and we don’t need to include the section number in the command, we type the following:
Say we need a command that counts the number of words in a text file. We type the following to see whether something like that exists:
To find out everything there is to know about counting words, we type this command:
Speaking of wc, we can also use the -k (apropos) option with a single period (.) as the search target, which will match everything. If we pipe that through wc and use the -l (lines) option, it’ll tell us how many man pages there are on the computer.
To do all of this, we type the following command:
There are 6,706 man pages on this Ubuntu computer, but don’t be surprised if the number is different on yours. It can vary depending on which software packages and utilities you have on your machine, and which man pages were pre-installed.
Searching In a man Page
You can also search forward or backward from your current position inside a man page.
For this example, we type the following to open the man page for the history command:
To search forward, we press the forward slash (/), and then type the word “event.” The search target appears at the bottom of the terminal window, and we press Enter to start the search.
The window displays the first result of any matches found, and they’re highlighted.
Press “n” to move from result to result toward the bottom of the page. To search backward through the man page, press “N”; this will move you back to the top of the page.
To toggle the highlighting on and off, press Esc+U.
If you’re near the bottom of the man page and want to search upward, press the question mark (?), and then type the search term. We searched for “entry.”
Again, any matching results are highlighted.
To search for the next matching result, press “n” to move toward the beginning of the man page. Press “N” to go to the previous matching result and move toward the end of the man page.
There’s another way you can search a man page. It hides all lines that don’t contain a match to your search term, so it’s best to use line numbers with this technique.
If we type “-N” and hit Enter, we can see the line numbers in the man page.
We press the ampersand (&), type our search term (number), and then hit Enter.
Only the lines that contain our search term are displayed.
It’s easy to skim these and spot any that look interesting. We think line 292 looks promising, so we want to go to that section of the man page and check it out.
To see all the lines again, we hit the ampersand (&), and then press Enter.
We type “292,” and then “g” to go to that line.
As soon as we type “g,” we’re taken to line 292 (which is why the “g” doesn’t appear in the image above). Line 292 is then displayed at the top of the terminal window.
You can press “-n” and hit Enter to remove the line numbers.
Read the Fabulous Manual
There’s a wealth of information in the man pages. Even with commands you think you know well, it’s a safe bet there are other options you’ve never heard of.
You’ll also definitely find commands you didn’t know existed. With so many different ways to search and track down information, it’s awesome to have it all at your fingertips.
