LinuxQuestions.org
Help answer threads with 0 replies.
Go Back   LinuxQuestions.org > Blogs > hazel
User Name
Password

Notices


Rate this Entry

How to read man pages

Posted 01-10-2020 at 11:50 AM by hazel
Updated 01-16-2020 at 05:48 AM by hazel

The Problem
Linux newbies tend to find man pages somewhat offputting. That may be because they are very concentrated, compressing a large amount of information into a small, highly-formatted package. They go back conceptually to the original UNIX Programmers' Manual, which was designed for experts who just wanted to bone up on something occasionally.

When the GNU people were creating GNU/Linux, they included man pages but also provided an alternative called info pages. This was designed to be more informal and uses a primitive form of hypertext adapted for use in a text console. There is no mouse support; you navigate by using certain keys. It seems that people in general did not find the user interface to info intuitive and there was no requirement for developers to provide info pages in their packages, whereas every package was required to contain a man page. So the info system has rather languished, while man pages are still going strong.

Man pages become easier to read when you get used to the way information is set out in them. Not all possible paragraphs occur in all pages, but there is a set of commonly used ones that you are almost bound to find and they always occur in the same order.

How man pages are organised
There are eight sections in the manual. The division is not by subject but by the type of entity being described:
  1. User commands. These are commands that anyone might use to get work done. Graphical as well as cli commands are included.
  2. System calls. These are C functions that are of interest to programmers but not ordinary users. They allow programs to invoke the help of the kernel for a variety of tasks such as hardware access or file access.
  3. C library subroutines. Again, these are of interest to programmers only. All Linux programs use the C library (glibc) and therefore use these functions. Some of them are more programmer-friendly wrappers for system calls. Others deal with tasks like arithmetic and string processing.
  4. Devices. Devices are defined as anything that the kernel can read from or write to. Some of the best known ones are described here.
  5. File formats. Here you will find recipes for all the most important system files in Linux. These files mostly reside in the /etc directory and are editable by the root user. It is good practice to check for a man page and read it before carrying out an edit.
  6. Games. Not a large section!
  7. Miscellaneous. If it doesn't fit in anywhere else, it goes here.
  8. System administration. Commands that are usually used by system administrators, and most of them require root access to work.

If you look at the lists in a graphical man page viewer like xman, you may notice that a lot of the user commands in section 1 have the same names as system calls in section 2. This happens when a command is basically just a wrapper around a system call, allowing the work to be done from the shell. However this seldom causes problems for the user of man pages because the man command always prints out the first match that it finds to the requested page name. Thus user commands in section 1) will always take precedence over system calls in section 2). If you actually want to read the page for the system call, you can override the default behaviour by specifying section 2, for example "man 2 rmdir".

Reading the individual man page
A typical man page will contain the following paragraphs:
  • NAME. Always present. As well as the name of the item, this section always contains a brief description of what it does. Sometimes two or more closely related commands or functions will share a man page. In that case the NAME section will describe both of them.
  • SYNOPSIS. Present for commands and functions. This section shows how the command or function is invoked. It typically shows the name followed by all the possible arguments that it can take. Arguments in square brackets are optional. Arguments separated by a | symbol are alternatives. Anything in italics represents a placeholder for a user-defined argument. For functions, this section also shows the header that must be included in order to use the function in a program.
  • DESCRIPTION. Always present. A loosely formatted description of what the entity is for and how to use it. When looking at a man page for the first time, you should read the NAME first and then this paragraph. You will not be able to make sense of the SYNOPSIS until you have a basic understanding of what a command does.
  • OPTIONS. This paragraph is usually present for commands. It unpacks the SYNOPSIS paragraph, listing all the command line options and what they do. Where there are alternatives, the default is usually stated. Some man pages put this material in the DESCRIPTION paragraph.
  • RETURNS. For functions only. Gives the possible return values.
  • AUTHOR. Usually present for commands and functions. Self-explanatory.
  • BUGS. Self-explanatory where present.
  • SEE ALSO. Lists other man pages that are related to this one. Worth following up.
Other man-related commands
  • whatis followed by any man page name will print out the NAME paragraph of the corresponding page, which contains a brief description of what the command does.
  • apropos followed by a keyword will print out all NAME paragraphs of man pages that contain that keyword. This is a good way to find out if there is a man page that deals with a particular subject.
Posted in For newbies
Views 1354 Comments 2
« Prev     Main     Next »
Total Comments 2

Comments

  1. Old Comment
    Thank you for making the Man Page more understandable.
    Posted 01-10-2020 at 10:43 PM by greencedar greencedar is offline
  2. Old Comment
    Thank you, Hazel. This is a good start at shining a light on the man pages.
    Posted 01-11-2020 at 11:52 PM by Mikech Mikech is offline
 

  



All times are GMT -5. The time now is 02:37 AM.

Main Menu
Advertisement
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration