http://homepages.shu.ac.uk/~cmsps/unix/man.html
Last updated: Thursday 05 April 2012 at 17:45
On-line documentation is one of the big ideas in Unix; it has become the norm. Today, users expect a system's documentation to be available at the workstation.
The Unix programmers' manual was originally printed on paper like any other but, since it had been typeset under Unix, it made more sense to look at the machine readable version than to find a heavy manual and search for the right page.
The manual is organised in sections with the Unix commands in section
one;
each entry starts on a new page.
The
man
command is used to display one manual entry at a time.
If the entry is from section one of the manual
then it is for a command that we can enter via the keyboard.
Here is the
man
command displaying one of the shortest
man
pages on my system:
$ man cal CAL(1) USER COMMANDS CAL(1) NAME cal - display a calendar SYNOPSIS cal [ [ month ] year ] DESCRIPTION cal displays a calendar for the specified year. If a month is also specified, a calendar for that month only is displayed. If neither is specified, a calendar for the present month is printed. year can be between 1 and 9999. Be aware that `cal 78' refers to the early Christian era, not the 20th century. Also, the year is always considered to start in January, even though this is historically naive. month is a number between 1 and 12. The calendar produced is that for England and her colonies. Try September 1752. Sun Release 4.1 Last change: 9 September 1987 1 $
You can't tell from the above but the manual pages are displayed by
more
so you get chance to page through them leisurely.
The manual pages are designed to be printed on pages 66 lines long;
if we bear that in mind, the
format of the output makes more sense.
The last line shown is a page footer with a page number at the right
hand side.
The first line is a page header.
In the header,
CAL
is the name of the command and
(1)
tells us the manual section number.
USER COMMANDS
is the title of the manual section.
The manual pages themselves are arranged in sections with headings
in capital letters.
The headings vary from one
man
page to another but all commands have
the sections shown above.
NAME
gives the name of the command, a dash
and a brief description of the command.
If the manual page has more than one command on it, both will be shown
separated by a comma.
For an example see the
man
page for
rm
which documents
rmdir
as well.
DESCRIPTION
describes what the command does.
SYNOPSIS
is the most important part of the
man
page as it shows the exact format for typing the command.
There are several conventions that we need to know to make
sense of them.
Some, but not all,
man
pages have an
EXAMPLES
section.
This is usually very helpful, but it is,
almost aways, devoted to the more complicated uses of the command.
First, brackets
([])
are used to indicate optional parts.
So in the above, everything after
cal
is optional.
If we wish, we can add a
month
and a
year
but the
month
itself is bracketed showing it is optional.
Therefore, these:
cal cal 1752 cal 9 1752
are all valid uses of the command.
Secondly,
cal
was
not
underlined in the
SYNOPSIS
, and
month
and
year
were; they are also underlined throughout the
man
page.
The convention is that non-underlined text is to be typed as shown but
underlined items are intended
to be replaced by appropriate values.
Which is why we typed
cal 9 1752
and not:
cal month year
in the previous example!
The third convention is the use of ellipses
(...)
to show that we may repeat something.
We can see them in the following:
$ man tee TEE(1) USER COMMANDS TEE(1) NAME tee - replicate the standard output SYNOPSIS tee [ -ai ] [ filename ] ... DESCRIPTION tee transcribes the standard input to the standard output and makes copies in the filenames. OPTIONS -a Append the output to the filenames rather than overwriting them. -i Ignore interrupts. ... $
The ellipsis after
filename
shows that we could put as many file names as we want.
The
man
page above also shows the use of options;
they modify the behaviour of commands.
Because it is bracketed, it looks as if we could
put
-ai
in our command.
This is true but it is not the whole story.
Because options are so common, they are not shown fully bracketed:
tee [ -a ] [ -i ] [ -ai ] etc . .
as we would expect from the earlier convention.
Instead they usually have a single set of brackets and we
have to remember that we can select
one or more
of the letters shown and don't have to use them in order.
Valid options for
tee
are:
-a -i -ai -ia -i -a -a -i
The effect of each option is described in the
OPTIONS
section of the manual page.
Notice the position of the options. They usually have to be between the command and the rest of the parameters.
Some commands have many options and sometimes some of them
are incompatible with each other.
For an example see the
man
page for
ls.
Sometimes there are alternatives in the
SYNOPSIS
part of the
man
page.
For example, this is the start of the
man
page for the
head
command:
HEAD(1) USER COMMANDS HEAD(1)
NAME
head - display first few lines of files
SYNOPSIS
head [ -number | -n number ] [ filename... ]
DESCRIPTION
The head utility copies the first number of lines of each
filename to the standard output. If no filename is given,
The vertical bar (|) character indicates that
-number
and
-n number
are alternatives;
we can have one or the other.
Actually, since they are bracketed together, they are optional and
we could also have neither.
As a matter of fact,
head
only has one option -
the number of lines it is to display -
but there are two notations for specifying it.
The second one (-n number) is more routine, with the option being denoted by a letter.
What is new about it, is that the option itself
(n) is
followed
by a value
(15).
Using that notation, these:
head -n 15 head -n15
are equally acceptable ways of telling
head
to display 15 lines of its input.
Not all options are specified with a letter;
this is shown by
head's first
option (-number).
Notice that in the
man
page,
number
is underlined while
-
and
-n
weren't, indicating
number
should be replaced with an appropriate value.
Therefore, this:
head -15
is another way to display 15 lines.
You might be tempted to skip this section if you don't use Linux. Do not skip it! Even if your computer runs Unix, it might actually be running Linux commands. To see how that can be, we need a little history lesson.
Many years ago, Richard Stallman set up the Free Software Foundation (FSF). It's main project was called GNU, standing for GNU's Not Unix. The idea was to write a free operating system which externally looked like and behaved like Unix.
Rather than writing the kernel of the operating system first, they
chose to write the commands -- programs like
cp,
mv
and
rm
and all the rest.
They also wrote C and C++ compilers.
These tools were so good that many Unix system administrators downloaded
them and used them instead of the programs provided by the suppliers
of their systems.
Today, few manufacturers bother to supply C and C++ compilers because people
prefer to use
gcc
and
g++
-- the GNU C and C++ compilers.
Many years later, Linus Torvalds wrote the kernel which became known as
Linux.
This was facilitated by the availability of
gcc.
Also, the Linux kernel without any commands would be no use to people who
have work to do.
So, what people call Linux should more fairly be called
GNU Linux.
Many
of the utility programs that come with distributions from firms like
Redhat and Suse are the ones written and maintained by the FSF.
It is those GNU commands that are described next.
How is it possible to be running the GNU version of a command
and not realising it?
The answer is that the GNU variant behaves
exactly
like the Unix one and has the
same options.
However, the GNU versions have extra options which begin with two dashes
(--) rather than one.
Also, the extra options have longer names, not just a single letter.
Some of the extra options are simply more readable versions
of the usual single-letter options -- very handy for making scripts
self-documenting.
Of course, some of them are genuine extras.
Taking
ls
as our example, it has
--all
corresponding to the
-a
option.
As well as
-b, it has
--escape.
Two of the genuine extras are:
--help
and
--version.
These two are, in fact, common to all the GNU file utilities.
The first displays a very brief guide to the options;
the second tells you which version is being used.
Using the
--version
option is a convenient way of finding out if you are using the
GNU commands.
Trying it on my machine:
$ rm --version
rm (fileutils) 4.1
Written by Paul Rubin, David MacKenzie,
Richard Stallman, and Jim Meyering.
Copyright (C) 2001 Free Software Foundation, Inc.
This is free software; see the source for copying
conditions. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
$
As you see, my system administrator has installed, at least, the GNU
version of
rm.
There is a difference in the use of the two kinds of option.
The Unix style can be run together so that the options for the
tee
command, shown earlier, can be given like this:
... tee -ai ...
With Linux style options, we cannot run them together. We must use:
... tee --append --ignore-interrupts ...
(The ellipses above are used to show that
tee
isn't used as a command on its own;
it is usually used in a pipeline.)
As suggested above, many Linux users use the Unix style when typing commands interactively but use the Linux style in scripts because it is more readable and self-documenting.
Often there are different versions of a particular command available. In that case the manual will contains headings such as:
SYSTEM V DESCRIPTION BSD DESCRIPTION
These two headings mean the System Five version of Unix and
the Berkeley version respectively; they are the two main varieties
of Unix and many systems hold both versions of the commands that
differ.
For example, the System Five
echo
command differs from the Berkeley
echo
command.
If your system offers both,
each version will probably be described under the appropriate heading.
Also, there may be two completely different commands with the same name.
In such cases the synopsis may give a full path-name for the command to
differentiate between them.
As an example,
rsh
is either a remote shell or a restricted shell.
On my machine the
man
page for the latter has
/usr/lib/rsh
in the
SYNOPSIS
section.
We have seen that section one of the Unix manual contains the Unix commands. Here is a contents list for the other main sections of the manual:
(2) System Calls
(3) Subroutines
(4) Devices
(5) File Formats
(6) Games
(7) Miscellaneous
(8) Sys. Administration
Some systems may not have some of the listed sections and may contain extra ones. Many systems have sub-sections with titles such as 1b, 1c and 1m.
Only section one and its sub-sections concern us. As users of Unix, we need to know what is in the other sections so that we know we can safely ignore them.
There is a big problem with the
man
command - you have to know the name of the command to read its
man
page!
What do we do if we know what we want to do but don't know which
Unix command to use?
The answer is to use the
apropos
command.
Apropos is French for "to do with".
So if we wish to compare two files we might try this:
$ apropos file
.environ environ (4) - user-preference variables files for AT&T FACE
... 432 lines edited out
zcat compress (1) - compress, uncompress files or display expanded files
$
The command looks through all the
NAME
sections in the manual
pages and displays the ones that contain the word or phrase
we want.
The output is in three columns.
The first is not much use and is not
provided on all systems; it tells us about the file that the manual page
is held in.
The next two columns show the name of the
man
page entry and its section within the manual followed by a dash and the
brief description.
As you can see, counting the ones I edited out, there were 434 manual
entries which contained
file.
We need to be a bit more specific.
Suppose we try:
$ apropos compare
bcmp bcmp (9f) - compare two byte arrays
cmp cmp (1) - compare two files
infocmp infocmp (1m) - compare or print out terminfo descriptions
sccs-sccsdiff sccs-sccsdiff (1) - compare two versions of an SCCS file
sccsdiff sccs-sccsdiff (1) - compare two versions of an SCCS file
strcmp strcmp (9f) - compare two null terminated strings.
strncmp strcmp (9f) - compare two null terminated strings.
$
This is more useful.
Ignoring the entries from section
9f, there are four possible commands and one of those is listed twice.
The next thing to do would be to use:
$ man cmp
to look at the
man
page for
cmp
to check that it does what we want and to find out how to use it.
There is much more to the
man
command than we have seen here.
How do you find out about it?
Use
man man
of course.
The X Window System provides a better way of reading the manual. It can be started like this:
$ xman &
3104
$
Don't worry about the ampersand
(&) and the number - we'll find out about those later.
The command should create
a small window like the one below:
+----- xman -----+ | Manual Browser | | | | Help Quit | | Manual Page | +----------------+ DIAGRAM OF XMAN TOP-BOX
The window is known as the
xman topbox.
If you click on the
Help
button you get the
man
page for
xman
thrown on the screen in another window.
You can scroll through it using the scroll-bar or you can page
forwards or backwards using the "space" and "b" keys.
The pages displayed by
xman
are usually more readable as they have more than one font and
have better highlighting.
The pages displayed by
xman
look like this:
+-------+--------+- Manual Page ---------------------+ |Options|Sections| The current manual page is: xman. | +-+-----+--------+-----------------------------------+ | | | | | Manual page window | | | | | | | | | | | | | +-+--------------------------------------------------+ DIAGRAM OF XMAN'S MANUAL PAGE
The most useful way to use
xman
is to use the
Options
button to choose
Show Both Screens
so that page is split into two like this:
+-------+--------+ Manual Page ----------------------+ |Options|Sections| The current manual page is: xman. | +-+-----+--------+-----------------------------------+ | | | | | Directory window | | | | +-+------------------------------------------------O-+ <-- slider | | | | | Manual page window | | | | | | | +-+--------------------------------------------------+ DIAGRAM OF XMAN'S BOTH SCREEN OPTION
The slider can be moved up and down with the mouse to vary the size of the two windows. The top window shows a list of manual page names. If we click on one of them, it is show in the lower window. Each window has a scroll-bar so we can browse through the available commands.
The quickest way to a particular manual page is to
place the cursor over the
xman topbox
or over the
xman
page and to type Control-S to get a search window like this:
+---- search ----------------+ | Type string to search for: | | | | ^ | | Manual Page Apropos | +----------------------------+ DIAGRAM OF XMAN'S SEARCH WINDOW
If you type the name of a command and press "return"
the manual page is displayed.
If, instead of typing "return", you click on
Apropos
you get a list of possible commands.
To remove a manual page from the screen you have to choose
Remove This ManPage
from the
Options
menu.
A slight complication with Linux is that often, when reading a manual
page, you find that it might not be the latest most complete documentation
and are referred to the
info
or texinfo.
The
info
command was intended to be GNU's replacement for the
man
command.
It works in full-screen mode -- you move the cursor to an item and
press the return key to descend into the item.
It isn't difficult to use but isn't as easy as
man.
To find how to use it, try:
$ info info
However, only do it if you have at least 15 minutes to spare!
The answers to the following questions aren't important in themselves.
The crucial bit is whether or not you can work out the answers on your
own by reading the
man
pages and doing a little judicious experimenting!
The
man
command sends its output through
more
so, let's get up to speed with it by using the following command:
$ more /etc/passwd
.....
.....
Even using the space-bar rather than the enter key it will take a while to page
to the end of that file! Type a question mark (?) to see
more's interactive keyboard commands. Now:
skip forward three pages
Answer
<space><space><space> OR 3<space>
skip back a page
Answer
b
skip to a line containing "Fred"
Answer
/Fred
Note: the found line is left as the third one on the screen.
Note: a trailing "/" would prevent the search from working. That is, "/Fred/" is wrong.
Note:
<regular expression>
in
more's on-line help means type a regular expression.
"Fred" is a very simple regular expression.
skip to another line containing "Fred"
Answer
/ OR n
Note we didn't have to repeat "Fred".
skip to another line containing "Fred"
Answer
/ OR n
quit
more.
Answer
q
Which version of
ls
are we using now -- Unix or GNU?
Answer
You are using the GNU version if
man ls
shows an option of
--all
as well as
-a.
Or, if
ls --version
and
ls --help
both operate properly.
Neither would work with any Unix version of the command.
How many options does the
ls
command have? Nothing clever needed
yet, you'll just have to count or guesstimate them!
Answer
$ man ls
and count the options!
I used:
$ man ls | grep '^ *-' | wc -l
58
$
to save my time.
Which one of
man's options lets you see the
man
pages for
all
versions of a command?
Answer
-a
man
has a
man
page like any other command!
Read it and find
-a.
Use it to see all the
man
pages for
ls.
Answer
$ man -a ls
How many were there?
Answer
Four on our system.
You should have noticed that there were three "pages"
for three versions of
ls. The super-observant would also
have noticed that one of the "pages" describes two versions
of
ls.
What does the manual say is the effect of the following
ls
options?
Answer
(For the following you will have to use:
$ man ls
and look in the "OPTIONS".
-F
Answer
Put a slash (/) after each filename if the file is a directory, an asterisk (*) if the file is executable, and an at sign (@) if the file is a symbolic link.
-g
Answer
The same as
-l, except that the owner is not printed
-x
Answer
Multi-column output with entries sorted across rather than down the page.
-1 # (minus one)
Answer
Single column output. Note: the option was "minus one".
-l # (minus ell)
Answer
"long" format Note: the option was "minus ell".
Use
tr
to output one of your files with every letter "e"
changed to an (upper case) "E".
Answer
$ tr e E < yourfile
How would you change all vowels (aeiou) to upper case?
Answer
$ tr aeiou AEIOU < yourfile
Notice that
tr's
man
page doesn't mention file names; it only
talks about standard input. You have to use input/output
redirection with it.
Don't be dis-heartened if you took ages, or couldn't do this one!
The
man
page for
tr
is one of the worst-written ones there
is. It is not easy to see how to do simple stuff. However, the
trick is to try the simplest use -- ignoring the options unless it
turns out that you really need them.
How would you use
find
to check if you have a file over 300
characters in any of your directories?
Answer
$ find . -size +300c -print
After
man find
I used "/size" to find the option. Happily, it turned out to be
-size.
Finding about
+
and
-
with values is hard; without them you only get the
exact
size, age or whatever.
I used "/greater" to find about
+
and
-.
How many commands are there to do with files?
Answer
244 on our system
$ apropos files | wc -l
244
$
Which command would you use to change the ownership of a file? Who is allowed to change the ownership of files? Why?
Answer
$ apropos owner
OR
$ apropos ownership
should lead you to:
chown
Only root (the super-user) is allowed to change ownership. If ordinary users could do it they could trap other people or incriminate them.
On Windows, administrators can't do it either, so they can't look at your files without you knowing. However ordinary Windows users can take ownership of another's file if they have been allowed to by the owner.
Check out
xman, especially the "Show Both Screens" facility and
the searching (^S) facility.
If you have the
info
command installed, learn how to use it.
If you are using Linux, you probably have it. If not, you may have it; your administrator might have installed the GNU commands.
<space><space><space> OR 3<space>
b
/Fred
Note: the found line is left as the third one on the screen.
Note: a trailing "/" would prevent the search from working. That is, "/Fred/" is wrong.
Note:
<regular expression>
in
more's on-line help means type a regular expression.
"Fred" is a very simple regular expression.
/ OR n
Note we didn't have to repeat "Fred".
/ OR n
q
You are using the GNU version if
man ls
shows an option of
--all
as well as
-a.
Or, if
ls --version
and
ls --help
both operate properly.
Neither would work with any Unix version of the command.
$ man ls
and count the options!
I used:
$ man ls | grep '^ *-' | wc -l
58
$
to save my time.
-a
man
has a
man
page like any other command!
Read it and find
-a.
$ man -a ls
Four on our system.
You should have noticed that there were three "pages"
for three versions of
ls. The super-observant would also
have noticed that one of the "pages" describes two versions
of
ls.
(For the following you will have to use:
$ man ls
and look in the "OPTIONS".
Put a slash (/) after each filename if the file is a directory, an asterisk (*) if the file is executable, and an at sign (@) if the file is a symbolic link.
The same as
-l, except that the owner is not printed
Multi-column output with entries sorted across rather than down the page.
Single column output. Note: the option was "minus one".
"long" format Note: the option was "minus ell".
$ tr e E < yourfile
$ tr aeiou AEIOU < yourfile
Notice that
tr's
man
page doesn't mention file names; it only
talks about standard input. You have to use input/output
redirection with it.
Don't be dis-heartened if you took ages, or couldn't do this one!
The
man
page for
tr
is one of the worst-written ones there
is. It is not easy to see how to do simple stuff. However, the
trick is to try the simplest use -- ignoring the options unless it
turns out that you really need them.
$ find . -size +300c -print
After
man find
I used "/size" to find the option. Happily, it turned out to be
-size.
Finding about
+
and
-
with values is hard; without them you only get the
exact
size, age or whatever.
I used "/greater" to find about
+
and
-.
244 on our system
$ apropos files | wc -l
244
$
$ apropos owner
OR
$ apropos ownership
should lead you to:
chown
Only root (the super-user) is allowed to change ownership. If ordinary users could do it they could trap other people or incriminate them.
On Windows, administrators can't do it either, so they can't look at your files without you knowing. However ordinary Windows users can take ownership of another's file if they have been allowed to by the owner.
If you checked out the
xman
command, you might have been
surprised that the output looked the same as with
man
or even worse.
That happens if using an X-terminal emulator on a PC that doesn't
have the correct fonts installed.
Text that is underlined in
man's output, and should be in an italic font in
xman
's output, is in plain text.
$ info info
...
(And play for half an hour)
http://homepages.shu.ac.uk/~cmsps/unix/man.html
Last updated: Thursday 05 April 2012 at 17:45