Reading Man Pages

by Norman Robinson

Help! I have no idea what this command does!

Many OS's provide you with documentation or a help system. Linux command line programs generally come with their own documentation too; manual pages or man pages for short. Although many of today's Linux Distributions come preconfigured with a graphic user interface (GUI), sooner or later you will want to use many of the command line (or shell) tools. Linux has origins in the command line, and there can be many times when you will not be running a GUI. On some systems, such as a dedicated server, you may not have a GUI installed at all. Linux provides you with many command line tools to manipulate files. Some of these tools are simple to learn, and yet complex enough that you will not remember all the commands for them. While learning about the command line programs in Linux, you may not have the benefit of any mentoring- no one to show you about man pages - or you just want to learn by yourself. In order to help you understand these command line tools, you will want to use the man command for help on using specific commands.

So what are Man pages then?

Manual pages are a descriptive help system that sometimes contains procedural help ("How do I..?") and sometimes the reason the command itself was created (the goal of the program). The command to format and view these manual pages is called man. Talk enough about them and you will eventually call them 'man pages.'

If you have used DOS in any of its forms, you may have typed commands followed by "/?" or "help" command, e.g., "help dir" or "dir /?". If you have used a GUI you may have pressed the 'F1' key for help. Usually the program will offer help on whatever portion of the program you are trying to use or whatever place your cursor was located when you pressed 'F1'. Sometimes a simple help window is shown and you are given the option to type in keywords or select a topic to read. Knowing what you want to find help on assists you in finding the exact information you need.

When using the command line you do not really have a keyword search, the ability to browse a topic, or even a real help system. This is an drawback of man pages; they do not provide a indexed, searchable system to find information. You have to ask for the manual page on specific commands. Manual pages are also generally not tutorial in nature. Some commands are so simple that they do not need explaining. Other commands are complex and too technical to be easily understood without using them. Manual pages were generally written by the person(s) that wrote the program themselves - they are descriptive enough to be of assistance, but not intended to be full documentation. Don't let the idea that man pages aren't full documentation or a tutorial deter you. Most commands have simple uses and you can easily understand how they function. Once you understand how to use the man pages, you will be on the way to a better understanding of how to make your computer do what you want.

Looking at the right information.

Just a quick hint: make sure you have the correct manual page. Linux has many short commands that are only one mistaken-key-press away from each other. Seems silly to point it out - until you mistakenly type 'man ld' instead of 'man ls'.

Definitions:

Man pages come from various sources and although most are similar, the man page formats aren't entirely consistent. Man pages can contain tables, mathematical equations, and bibliographic references. Man pages are the work of various people doing their best to describe the commands and their usage. A testament to simplicy and usability, tens of thousands of pages of documenation exist, viewable in a common file format, usable via command line, or easily printed without minimal effort.

Some man pages have headings that other man pages do not; however, I have pulled the most common headings out and will attempt to define them for you. I have provided a link to a specific example of man page syntax behind every definition.

Let's start by examining the man page for the 'ls' command. Browse down and take a look at the information - I will begin explaining how to read it below.


LS(1) FSF                          LS(1)


NAME

       ls - list directory contents

SYNOPSIS

       ls [OPTION]... [FILE]...

DESCRIPTION

       List information about the FILEs (the current directory by
       default).  Sort entries alphabetically if none of -cftuSUX
       nor --sort.

       -a, --all
              do not hide entries starting with .

       -A, --almost-all
              do not list implied . and ..

       -b, --escape
              print octal escapes for nongraphic characters

       --block-size=SIZE
              use SIZE-byte blocks

       -B, --ignore-backups
              do not list implied entries ending with ~

       -c     with  -lt:  sort  by, and show, ctime (time of last
              modification of file status information)

              with -l: show ctime and  sort  by  name  otherwise:
              sort by ctime

       -C     list entries by columns

       --color[=WHEN]
              control  whether  color is used to distinguish file
              types.  WHEN may be `never', `always', or `auto'

       -d, --directory
              list directory entries instead of contents

       -D, --dired
              generate output designed for Emacs' dired mode

       -f     do not sort, enable -aU, disable -lst

       -F, --classify
              append indicator (one of */=@|) to entries

       --format=WORD
              across -x, commas -m, horizontal -x, long -l,  sin
              gle-column -1, verbose -l, vertical -C

       --full-time
              list both full date and full time

       -g     (ignored)

       -G, --no-group
              inhibit display of group information

       -h, --human-readable
              print sizes in human readable format (e.g., 1K 234M
              2G)

       -H, --si
              likewise, but use powers of 1000 not 1024

       --indicator-style=WORD append indicator with style WORD to
       entry names:
              none (default), classify (-F), file-type (-p)

       -i, --inode
              print index number of each file

       -I, --ignore=PATTERN
              do not list implied entries matching shell PATTERN

       -k, --kilobytes
              like --block-size=1024

       -l     use a long listing format

       -L, --dereference
              list entries pointed to by symbolic links

       -m     fill width with a comma separated list of entries

       -n, --numeric-uid-gid
              list numeric UIDs and GIDs instead of names

       -N, --literal
              print raw entry names  (don't  treat  e.g.  control
              characters specially)

       -o     use long listing format without group info

       -p, --file-type
              append indicator (one of /=@|) to entries

       -q, --hide-control-chars
              print ? instead of non graphic characters

       --show-control-chars
              show  non  graphic characters as-is (default unless
              program is `ls' and output is a terminal)

       -Q, --quote-name
              enclose entry names in double quotes

       --quoting-style=WORD
              use quoting style WORD for  entry  names:  literal,
              locale, shell, shell-always, c, escape

       -r, --reverse
              reverse order while sorting

       -R, --recursive
              list subdirectories recursively

       -s, --size
              print size of each file, in blocks

       -S     sort by file size

       --sort=WORD
              extension -X, none -U, size -S, time -t, version -v

              status -c, time -t, atime -u, access -u, use -u

       --time=WORD
              show time as WORD  instead  of  modification  time:
              atime,  access, use, ctime or status; use specified
              time as sort key if --sort=time

       -t     sort by modification time

       -T, --tabsize=COLS
              assume tab stops at each COLS instead of 8

       -u     with -lt: sort by, and show, access time  with  -l:
              show  access  time and sort by name otherwise: sort
              by access time

       -U     do not sort; list entries in directory order

       -v     sort by version

       -w, --width=COLS
              assume screen width instead of current value

       -x     list entries by lines instead of by columns

       -X     sort alphabetically by entry extension

       -1     list one file per line

       --help display this help and exit

       --version
              output version information and exit

       By default, color is not  used  to  distinguish  types  of
       files.   That  is equivalent to using --color=none.  Using
       the --color option without the optional WHEN  argument  is
       equivalent  to  using  --color=always.  With --color=auto,
       color codes are output only if  standard  output  is  con
       nected to a terminal (tty).

AUTHOR

       Written by Richard Stallman and David MacKenzie.

REPORTING BUGS

       Report bugs to <bug-fileutils@gnu.org>.

COPYRIGHT

       Copyright © 1999 Free Software Foundation, Inc.
       This  is  free software; see the source for copying condi
       tions.  There is NO warranty; not even for MERCHANTABILITY
       or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       The  full  documentation for ls is maintained as a Texinfo
       manual.   If  the  info  and  ls  programs  are   properly
       installed at your site, the command

              info ls

       should give you access to the complete manual.

The above is exactly what you would see it if you typed man ls into your shell and hit return.

The "LS(1)" is the command you have searched for and the number in parentheses shows you what section of the man page you are viewing.

The (1) indicates that this page is found in section 1 of the manual. Section 1 traditionally contains pages for commands supplied with the operating system.

Man page sections are:
     (1)     User Commands
     (2)     System Calls
     (3)     Library functions
     (4)     Devices
     (5)     File formats
     (6)     Games and Amusements
     (7)     Conventions and Miscellany
     (8)     System Administration and Priveledged Commands
     (L)     Local. Some programs install their man pages into this section instead of (1)
     (N)     TCL commands

To get an introduction to each section you can try typing 'man, the section, intro' i.e., "man 1 intro".

The "FSF" indicates this was written by the Free Software Foundation, Inc. (FSF). This position orginally contained the text "UNIX Programmers Manual". Various different UNIX systems put the name of the particular unix system (such as SOLARIS, AIX, HPUX, BSD, SGI, etc.) in this position.

The "NAME" heading is the name of the command itself. If you were in a shell and typed this, you would execute or run the command itself. The other part of the "NAME" heading is a short description of what the command does - usually one sentence (or less).

The "SYNOPSIS" or outline, describing how the command is supposed to be used. The synopsis is shown using the command followed by [OPTION]... [FILE]...

The "OPTIONS" Brackets "[" and "]" indicate that this modifier is not needed, but can be used. Any one of the above can be followed by a "..." which tells you that they can be used one or more times. You should not take the examples literally. As mentioned, the "[" and "]" indicate there are options that are not required. The "..." means that you have one or more times you can use these options. You would not type ls [OPTION]... [FILE]... exactly or you would get an error ls: [OPTION]... No such file or directory and ls: [FILE]... No such file or directory". I will read it as a sentence; type the ls command, optionally followed by one or more options you may want, optionally followed by one or more file names you want. Since both the OPTIONs and FILEs are optional, you don't have to type any of them at all - just type ls and press enter!

Go to your shell and type ls now. You should see a list of all files in your directory. If you don't have any files, this could be very boring! One of the concepts in Learning the Shell was absolute pathnames. If you type ls / you will see your root directory, which includes "bin, dev, home, lost_found, opt, root, tmp, var, etc", and other directories. In looking at the man page you typed, the ls command without [OPTIONS]... but with a specific [FILE]. Yes, "/" is a file! Don't let this to confuse you. Take a look a these examples;

ls [OPTIONS]... [FILE]...

could be re-written:

Form	Example	Description
`ls`	`ls`	Should list all your files in the directory you are currently in; who knows what files you may have?
`ls [OPTIONS][FILE]`	`ls -a /`	Lists all files (including hidden files) in your / directory.
`ls [OPTIONS][FILE]`	`ls -a /home`	Lists all files (including hidden files) in the /home directory
`ls [OPTIONS] [FILE]`	`ls -a-l /home`	Lists all files in long format (including hidden files) in the /home directory
`ls [OPTIONS] [FILE] [FILE]`	`ls -a-l / /home`	Lists all files in long format (including hidden files) in the / and in the /home directory

DESCRIPTIONs gives a more detailed definition of the command, sometimes highlighting specific functions of the command mentioned, as well as providing the OPTIONs available for the command.

OPTIONs are preceeded by hyphens, and you can either specify them individually if you leave a space inbetween ( ls -a -l /home) or altogether ( ls -al /home ) if you leave out any intervening spaces. And, as we have repeatedly seen, the "FILE" Brackets "[" and "]" indicate that the flag is optional. Sometimes a pipe "|" is used to separate options that are exclusive from one or the other. An example would be the mount command showing that you can specify either a device or directory; device | dir. The pipe is also used to indicate options that equate to each other. This can be seen in the man page for consolechars; a specific example would be [-V|--version]. You could either type -V *OR* --version to get the same effect.

All of the above can be combined to indicate optional commands that can be used in an either/or scenario. Examples like tar shows you a man page that looks confusing. Don't worry too much about it right now. Take the time to start small. A look at clear might settle your nerves! You may have also noticed that the list of options available to you is in ALPHABETICAL ORDER. Most man pages list their options in alphabetical order - I believe to make it easier to reference a specific option if you know what that option is, but have forgotten exactly what it does. At any rate, it is important to note that because of the alphabetical order, you might first see options that are not frequently used.

Sometimes sections are not consistantly ordered after the NAME, SYNOPSIS, and DESCRIPTION is given, but I have listed the most common man page Sections below:

AUTHORS: the people who created or assisted in the creation of the command.
BUGS: lists any know defects or shortcoming of the programs. Sometimes they aren't failures of the tool, but rather peculiarities of implementation.
ENVIRONMENT: Describes any variables that might be needed or specific versions of the shell that may be needed for the command to operate.
EXAMPLES or NOTES: An illustration of how to use the command including general notes.
REPORTING BUGS: If you find any problems with the command, this tells you where you should report the defects or problems you are having with the command.
COPYRIGHT: The person or organization that holds the copyright to this information; usually a disclaimer that this is free software without warranty.
SEE ALSO: Other commands that are related to this command. This relationship is not always clear, but usually other commands mentioned here are used in conjunction with this command. This section also frequently mentions any other documentation related to this command.

Remember, manual pages are not designed to be a help system, but they do provide descriptions of the commands themselves. You have to know which page to look for or know how to search for the correct page. Manual pages aren't designed to be a tutorial on how to use the commands. They are a reference that frequently explains how the command functions so that you can easily understand its use. There is usually help available from the commands themselves by executing the command with the "--help" option. Try typing in ls --help and see what I mean. Beginning users are encouraged to type ls --help | less. Although it might be beyond your comfort level now, if you acquire the source code to programs you can frequently find similar information in the READMEs that accompany the programs.

For even more information, you should now be able to type man ls and press enter. If you learn best by example, you can log into your command line and try using the ls command with all the options listed above, or bring up the man page on your system. Since this document is targeted at fairly new users, this bears mentioning; do not use your root account to experiment with unfamiliar commands - your root account will allow you permission to modify anything in your system! Log in with your own user account before experimenting, and understand what the commands do by reading the man page before executing them. I would suggest browsing the excellent SuperMan pages hosted on LinuxCommand.org, which might give you more insight into your Linux system.