Reading Man Pages
by Norman Robinson
Help! I have no idea what this command
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 crude 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, i.e., "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 helps you find 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
weakness 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 try
to type 'man ls', mistakenly type 'man ld', realize
there is such a program, and you've been reading
about the wrong manual page!
Man pages are not at all standardized. They
developed as the commands themselves developed and
sometimes were not updated. Man pages are the work
of various people doing their best to describe the
commands and their usage. The man pages themselves
aren't consistently formatted. 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 the
behind every definition.
Lets start by examining the man page for the
'ls' command. Browse down an take a look at the
information - I will begin explaining how to read
LS(1) FSF LS(1)
ls - list directory contents
ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by
default). Sort entries alphabetically if none of -cftuSUX
do not hide entries starting with .
do not list implied . and ..
print octal escapes for nongraphic characters
use SIZE-byte blocks
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
control whether color is used to distinguish file
types. WHEN may be `never', `always', or `auto'
list directory entries instead of contents
generate output designed for Emacs' dired mode
-f do not sort, enable -aU, disable -lst
append indicator (one of */=@|) to entries
across -x, commas -m, horizontal -x, long -l, sin
gle-column -1, verbose -l, vertical -C
list both full date and full time
inhibit display of group information
print sizes in human readable format (e.g., 1K 234M
likewise, but use powers of 1000 not 1024
--indicator-style=WORD append indicator with style WORD to
none (default), classify (-F), file-type (-p)
print index number of each file
do not list implied entries matching shell PATTERN
-l use a long listing format
list entries pointed to by symbolic links
-m fill width with a comma separated list of entries
list numeric UIDs and GIDs instead of names
print raw entry names (don't treat e.g. control
-o use long listing format without group info
append indicator (one of /=@|) to entries
print ? instead of non graphic characters
show non graphic characters as-is (default unless
program is `ls' and output is a terminal)
enclose entry names in double quotes
use quoting style WORD for entry names: literal,
locale, shell, shell-always, c, escape
reverse order while sorting
list subdirectories recursively
print size of each file, in blocks
-S sort by file size
extension -X, none -U, size -S, time -t, version -v
status -c, time -t, atime -u, access -u, use -u
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
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
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
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).
Written by Richard Stallman and David MacKenzie.
Report bugs to <firstname.lastname@example.org>.
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.
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
should give you access to the complete manual.
The above is exactly how 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 parenthesis shows you what
section of the man page you are viewing. I believe
the "FSF" indicates this was written by the Free
Software Foundation, Inc. (FSF) Other commands not
written by the FSF do not have this heading.
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
The "SYNOPSIS" or outline, describing how the
command is supposed to be used. The synopsis is
shown using the command followed by [OPTION]...
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
could be re-written:
Should list all your files in the
directory you are currently in; who knows
what files you may have?
Lists all files (including hidden files)
in your / directory.
Lists all files (including hidden files)
in the /home directory
Lists all files in long format (including
hidden files) in the /home directory
||ls -a-l /
Lists all files in long format (including
hidden files) in the / and in the /home
DESCRIPTIONs give a more detailed definition of
the command, sometimes highlighting specific
functions of the command mentioned, as well as
providing the OPTIONs available for the
OPTIONs are frequently separated by hyphens ( ls
-a-l /home) and you can either specify them
individually 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 mountcommand 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 a 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
are 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
Sections are sometimes not consistantly ordered
after the NAME, SYNOPSIS, and DESCRIPTION is given,
but I have listed the most common man page Sections
- 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 failure of
the tool, but rather peculiarities of
- ENVIRONMENT; Describes any variables that
might be needed or specific versions of the shell
that may be needed for the command to
- 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
- 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 but frequently
explain how the command functions so that you can
easily understand their use. There is usually help
from the commands themselves by executing the
command and then a " --help". 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 README's that accompany
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
it 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 might give you more insight into
your Linux system.
Please forward any kudos, comments, corrections,
or suggestions to Norman
Robinson. While doing the research necessary
for this document I decided to begin work on
resolving some of the problems with man pages as a
help system. If you are interested please visit Project
Neanderthal and help if you are able.
Copyright © 2001 Norman B. Robinson.
Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU
Free Documentation License, Version 1.1 or any
later version published by the Free Software
Foundation; with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover
Previous | Top