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.

The man pages are a great resource that should be the first place to look if you have a problem on Linux.

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) simply enter man followed by the component name.

The man command will display 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, just 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 on your system is good because they should correspond to the version of the software that you actually have installed. However there are also various online sources for man pages including Ubuntu man pages and the Linux man-pages project.

Manual Sections

The manual, or man pages, is divided into sections. You will normally find there are 8 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 (usually found in /dev
  5. File formats and conventions eg /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 this 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 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 name of the command and the section of the manual that you’re currently looking at. Then there are a number of sections which a man page could include, some of the common ones our 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 verbose explanation of the subject including explaining syntax and options in detail.

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 will typically list what package the page is associated with, the date the page was written and (as at the top) 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 simply 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! Simple type an exclamation point (!) followed by the command. This will run the command in a shell and then let you return by pressing <enter>

Command execution example

If you’re learning about the ‘ls’ command and want to quickly 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 would be 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 a number of 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 can be used in a similar way to the man pages. For example, to find the ‘info’ page about ‘man’ you simply 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 will 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 here.