3 Getting help from the system itself

In this chapter you’ll be introduced to:

3.1 The manual pages

The original UNIX Programmer’s Manual documents the sytem divided into nine sections: Section 1 deals with the commands for the end user, the commands we discuss in this course. Incidentally games too were a part of the system, section 6 contains information on games. The remaining sections handle details which are aimed for the programmer and the system administrator. This documentation was always a part of the system.

The man program searches, formats, and displays the information contained in those manual pages. Because many topics have a lot of information, output is piped through a terminal pager program for convenient viewing one page at a time; at the same time the information is formatted for a good visual display. You can call man just by giving the name of the program which would like to know more about. For example:

$ man uname 
UNAME(1)                         User Commands                        UNAME(1) 
  uname  print system information 
  uname [OPTION]... 
  Print certain system information.  With no OPTION, same as s. 
  a, all 
    print all information, in the following order, except omit 
    and i if unknown: 
  s, kernelname 
    print the kernel name 

The output says that the page is from section 1 ’User Commands’ and explains its usage.

Note that the man pages have a well defined structure, part of which is listed in next table. Thanks to their structure the man pages can be automatically converted to HTML, to book form or to graphical help programs. You will encounter them if you continue working in the shell after the course, but during this course we expect you to refer the local man pages with the help of man.

Item Description

SYNOPSIS Command usage along with the optional and non-optional arguments
DESCRIPTIONDetails on how to use the command and and explanation of each section
EXAMPLE Examples of how to use the command
FILES Files that have to be available for this command to work
SEE ALSO Commands that are similar in purpose
DIAGNOSTICSExplanation of error messages
WARNINGS Things to be careful about when using the command
BUGS Known problems and suggested improvements

For reading long manual pages on screen man delivers them through a pager, which depends on the Unix flavour. The pager used in Linux is called less. You navigate in less with single key strokes: f, Ctrl+f or space bar to scroll page-wise forward or b, Ctrl+b, or Shift+space to scroll back and ’q’ for quit. The key ’h’ gives your the the full list of commands.

Another useful key is / (forward slash), the search key. Often all you need to know is what a specific option of a command does, for example what ’uname -s’ really means. In such cases just call ’man uname’ and then press / - s. If the first hit is not the one you were looking for, keep on pressing n (for next).

Exercise. Call the man pages of the commands you already know and note down options you find interesting. Don’t forget ’man man’ too!

By default the man command prints only the dedicated page specifically about the topic. You can broaden this to view all man pages containing a particular string in their name by using the -f option. The following dialog shows that there is only one date command whereas there are two time commands.

$ man f date 
date (1)      print or set the system date and time 
$ man f time 
time (7)      overview of time and timers 
time (2)      get time in seconds

You select the section of the manual by giving its number as an optin:

$ man 2 time 
TIME(2)               Linux Programmer’s Manual              TIME(2) 
  time  get time in seconds 
$ man 7 time 
TIME(7)               Linux Programmer’s Manual              TIME(7) 
  time  overview of time and timers 

You get the same effect of ’man -f’ by the command whatis.

$ whatis time 
time (7)      overview of time and timers 
time (2)      get time in seconds

A common problem with the man command is that you need to know the name of the command you want to know more about. The -k option broaden the search by including all commands whose description contains the search string:

$ man f  user 
user: nothing appropriate. 
$ man k user 
adduser.conf (5)  configuration file for adduser(8) and addgroup(8) 
deluser.conf (5)  configuration file for deluser(8) and delgroup(8) 

The apropos command is equivalent to ’man -k’:

$ apropos user 
adduser.conf (5)  configuration file for adduser(8) and addgroup(8) 
deluser.conf (5)  configuration file for deluser(8) and delgroup(8) 

3.2 GNU info

The GNU Project distributes most of its on-line manuals in the Info format, which is more free-form than man pages. Functionally, the GNU Info System resembles man in many ways. However, topics are connected using links (even though its design predates the World Wide Web). There are two primary Info readers: the text-based program info designed just for this purpose and the ’info’ package in GNU Emacs, which supports using a mouse. In this course we look at info only.

Typing ’info’ in a terminal with no arguments displays an index of the available topics. You can browse through the topic list using the regular movement keys: arrows, Page-Up, and Page-Down.

You can view the documentation for a particular topic by typing ’info topic’. The system then searches for the topic in all available info files. Some useful keys are: h for help, and Enter to select a menu item and q for quit.

The topic which you view in the info page is called a node. Nodes are similar to sections and subsections in written documentation. You can move between nodes or view each node sequentially. Each node may contain menus and linked subtopics, or items.

Items can be compared to Internet hyperlinks. They are identified by an asterisk (*) at the beginning of the item name. Named items (outside a menu) are identified with double-colons (::) at the end of the item name. Items can refer to other nodes within the file or to other files. The folloing table lists the basic keystrokes for moving between nodes.


n Go to the next node
p Go to the previous node
u Move one node up in the index

3.3 The help option

The third source of Linux documentation is to use the help option.

Most commands have short help screen available which can be viewed using the –help or the -h option along with the command or application. For example, to learn more about the uname command, you can run:

$ uname help 
Usage: uname [OPTION]... 
Print certain system information. With no OPTION, same as s. 
  a, all            print all information, in the following 
                         order, except omit p and i if unknown: 
  s, kernelname    print the kernel name 
  n, nodename       print the network node hostname 

The help option is useful as a quick reference and it displays information faster than the man or info pages.

3.4 The help command

Some popular shell commands (such as echo) silently run their own built-in versions of system programs or utilities, because it is more efficient to do so. To view a synopsis of these built-in commands, you can use the help command of the shell.

$ help time 
time: time [p] pipeline 
 Report time consumed by pipeline’s execution. 
 Execute PIPELINE and print a summary of the real time, user 
 CPU time, and system CPU time spent executing PIPELINE when 
 it terminates. 
   p  print the timing summary in the portable Posix format 

To get a list of the available topics, just run help. For these built-in commands, help performs the same basic function as the -h and –help arguments (which we will discuss shortly) perform for stand-alone programs.

3.5 Command completion, command history

Most of the Unix shells have a feature called command completion. If for example you know only the beginning of a command, let’s say ’up’ for ’uptime’, you can type ’up’ and then press the Tab-key. Since there are many commands which starts with ’up’ the shell will not react. Press the Tab-kay a second time and it will list all the available commands which start with ’up’.

On the other hand, if what you typed unique, the shell will immediately complete the command once you press the Tab-kay.

The same thing with file names. You can start typing a file name and then press Tab for the shell to complete it.

Another very useful feature to minimize typing is the command history. In its simplest form, just press the Up-arrow for the shell to bring the stack of previous commands one-by-one.

3.6 Assignment for the week

Take the test in the course platform:

Allowed material: You are allowed to consult only the course lecture note and the help built in to the shell of the Raspberry Pi you are working in.

Hint: You can open two terminals to your training computer at the same time. In one you can consult the built-in documentation and in the other test your answers to the questions.