Chapter 5

The On-line Manual

Introduction

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.

A manual page

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

$

Because it is so short 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.

Headings

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.

Conventions - [ ]

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.

Conventions - underlining

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!

Conventions - ...

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.

Conventions - OPTIONS

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 arguments.

Some commands have many options and sometimes some of them are incompatible with each other. For an example see the man page for ls.

Conventions - alternatives

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.

Following options

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.

Bare numeric options

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.

Linux

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.

GNU commands

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.

Which are you using?

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.

Unix vs Linux options

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.

Different versions

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.

Other sections

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.

Apropos

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.

More on the man command

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.

Linux info command

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!

QUESTIONS

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!

  1. 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:

    1. skip forward three pages

      Answer

      <space><space><space> OR 3<space>

      Hide

    2. skip back a page

      Answer

      b

      Hide

    3. 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.

      Hide

    4. skip to another line containing "Fred"

      Answer

      / OR n

      Note we didn't have to repeat "Fred".

      Hide

    5. skip to another line containing "Fred"

      Answer

      / OR n

      Hide

    6. quit more.

      Answer

      q

      Hide

  2. 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.

    Hide

  3. 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.

    Hide

    1. 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.

      Hide

    2. Use it to see all the man pages for ls.

      Answer

      $ man -a ls
      

      Hide

    3. 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.

      Hide

  4. 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".

    Hide

    1. -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.

      Hide

    2. -g
      

      Answer

      The same as -l, except that the owner is not printed

      Hide

    3. -x
      

      Answer

      Multi-column output with entries sorted across rather than down the page.

      Hide

    4. -1                     # (minus one)
      

      Answer

      Single column output. Note: the option was "minus one".

      Hide

    5. -l                     # (minus ell)
      

      Answer

      "long" format Note: the option was "minus ell".

      Hide

    1. Use tr to output one of your files with every letter "e" changed to an (upper case) "E".

      Answer

      $ tr e E < yourfile
      

      Hide

    2. 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.

      Hide

  5. 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 -.

    Hide

  6. How many commands are there to do with files?

    Answer

    244 on our system

    $ apropos files | wc -l
    244
    $
    

    Hide

  7. 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.

    Hide

  8. 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.

    Answer

    $ info info
    ...
    

    (And play for half an hour)

    Hide

ANSWERS

    1. <space><space><space> OR 3<space>

    2. b

    3. /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.

    4. / OR n

      Note we didn't have to repeat "Fred".

    5. / OR n

    6. q

  1. 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.

  2. $ man ls
    

    and count the options!

    I used:

    $ man ls | grep '^  *-' | wc -l
    58
    $
    

    to save my time.

    1. -a

      man has a man page like any other command! Read it and find -a.

    2. $ man -a ls
      
    3. 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.

  3. (For the following you will have to use:

    $ man ls
    

    and look in the "OPTIONS".

    1. 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.

    2. The same as -l, except that the owner is not printed

    3. Multi-column output with entries sorted across rather than down the page.

    4. Single column output. Note: the option was "minus one".

    5. "long" format Note: the option was "minus ell".

    1. $ tr e E < yourfile
      
    2. $ 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.

  4. $ 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 -.

  5. 244 on our system

    $ apropos files | wc -l
    244
    $
    
  6. $ 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.

  7. $ info info
    ...
    

    (And play for half an hour)