How to use the man pages on Linux

Lesson

What are man pages

A 'man page' on Linux is a manual page which provides helpful documentation about an aspect of your system. There are man pages for programs, configuration settings and much more besides. When you install a new program on Linux, it should also include any relevant man pages so that you can find help to use the new tool. The man pages also contain plenty of information included about how to use and configure your Linux distribution – for example where configuration files are stored and how to use included tools/programs.

Accessing man pages

Linux makes manual pages for everything on your system easily accessible from the command line with the man command. To look up the man page for a particular component (program, tool, configuration file) enter man followed by the component name.

The man command will display the page in the terminal (typically using the less pager). You can scroll through the output with the arrow keys or by using the page up / page down keys. To leave the man page, type q for quit.

Example

To look up the man page for pwd (the print working directory command):

man pwd

Man pages online

The easiest way to find a man page for something on your Linux system is through the command line. Using the man pages included with your system is good because they should correspond to the version of the software that you have installed. However, there are also various online sources for man pages, including Ubuntu and the Linux man-pages project.

Manual Sections

The manual, or man pages, is divided into sections. You will generally find there are eight sections similar to the following.

1. Executable programs or shell commands
2. System calls (functions provided by the kernel
3. Library calls (functions within program libraries)
4. Special files
5. File formats and conventions (e.g. /etc/passwd)
6. Games
7. Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8. System administration commands (usually only for root)

This is from a system running Ubuntu.

You can confirm which sections are present on your system by looking up the man page for man itself:

man man

If you are looking for help on something in a particular section, then you can specify the section number as an argument to the command (before the name of the command). By default, the man command will return the page from the first section which that word appears in.

Section number example

There is information about printf in both section 1 and section 3; this is because it is both a command that a user can run at the terminal (section 1) and also a library function which a programmer can call.

$ man printf
    # displays the printf command page
$ man 3 printf
    # displays the printf library function page

How to read a man page

The man pages can be quite intimidating – lots to read and no pictures – but learning to love and understand them is an important skill. Many problems you will face on Linux can be solved by reading the manual!

The top line of the page will specify the command name and the section of the manual that you're currently looking at. Then there are several sections which a man page could include, some of the common ones are outlined below.

Name – The name of the command or feature covered and a one-line description.

Synopsis – A summary of usage and options.

Description – A more lengthy explanation of the subject, including information about syntax and options.

Options – Some pages may have a dedicated options section rather than listing them under description.

Examples – gives examples of common usage, such as popular combinations of options.

Files – describes any related files which are related to the command.

See Also – specifies related commands and where they are in the man pages. Sometimes this section will also suggest other places to find further help on the topic.

The bottom of the page will typically list what package the page is associated with, the date the page was written and the name and section of the page.

Move around the page

Under the hood, man uses the less 'pager' for displaying pages by default on most systems. Therefore, we can use shortcuts from less to navigate the page.

Arrow keys and page up / page down can be used to move around the page.

You can quickly jump to the top of the page by hitting the g key or to the bottom of the page by using <shift> + g.

Typing q will quit the page and return you to the shell.

Search within a page

Again, you can use the built-in functionality of less to search through a page.

• To search for a basic pattern, type forward-slash (/) followed by the pattern to search for.

• To look for the next occurrence of the pattern press the n key

• To find the previous occurrence press <shift> + n

• You can use 'regular expressions' for more complex search patterns

Searching within a page example

To search for the word 'human' in a man page, you type the following and hit enter.

/human

Testing a command

If you want to quickly test a command that you have read about in a man page and then return to the page, you can! Type an exclamation point (!) followed by the command. The command is then run in a shell, and then you can return by pressing <enter>.

Command execution example

If you're learning about the 'ls' command and want to test some of the available options, you could type the following from within man. Don't forget to hit the <return> key to run it and then again to return to the page.

!ls -lh

Searching the man pages

Sometimes you might be looking for a term which isn't the name of a whole page but is contained within a page. Or you may not know which sections of the manual a command is documented in.

Look in all the sections

You can use the -f option to return all sections a name occurs in. For example, there are entries for man in two different sections:

$ man -f man
man (1) - an interface to the on-line reference manuals
man (7) - macros to format man pages

You can achieve the same effect with the whatis command:

$ whatis passwd
passwd (1)           - change user password
passwd (1ssl)        - compute password hashes
passwd (5)           - the password file

You can learn more about the whatis command from the whatis man page.

apropos

To search the pages for a keyword, you can use apropos. The apropos utility searches through a database which includes the name and description of each manual page which is available. Using the '-koption withman` is equivalent to using apropos.

For example, apropos password (or man -k password) will return all entries which reference 'password' in the description of the command.

There are many additional options which you can use with apropos, for example:

-r or --regex to use regular expressions

-e or --exact to match keywords exactly

-a or --all to match all keywords as opposed to just matching any keyword.

Don't forget to use man apropos to learn more!

man vs info

There are other sources of documentation which you may also want to try. In particular, there is the info command. Info is another repository of system and software information that can be used in a similar way to the man pages. For example, to find the 'info' page about 'man' you use info man. The info pages generally have more thorough content, and it is a newer utility than man. Because 'man' is a more established tool, it contains entries for more topics.

There are plenty of other sources of information available: many GUI (Graphical User Interface) tools have some built-in help; command line tools typically have some help available by using '-h' or '—help' options; the Internet can help if you're still stuck.

Further information about using man and its alternatives can be found in the McGill School of Computer Science guide.

---

References

Learn more about this topic by checking out these references.

---

Other Lessons

Learn more by checking out these related lessons

---