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'.
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 with 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 <email@example.com>. 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
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:
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:
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:
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.
Please forward any kudos, comments, corrections, or suggestions to Norman Robinson. Thanks go to everyone for their comments, critcism, and I specifically thank Bill Shotts for his fine work on LinuxCommand and Mark Whitis for his valuable feedback.
Copyright © 2001, 2003 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 Texts.
Linux® is a registered trademark of Linus Torvalds.