Third party cookies may be stored when visiting this site. Please see the cookie information.

PenguinTutor YouTube Channel

Linux Documentation and Help Reference Guide

There is a wealth of information available to Linux users and administrators. Some of this is official information created by the groups responsible for the application, and others (including this tutorial) are created by others not directly involved in that particular project. In addition there are also many different community led sources, as well as commercial books and support packages.

Man Pages

The universal help tool for Linux and UNIX commands are the Manual Pages, or better known as the man pages. The man pages are normally read using the man command, which is usually run from the shell prompt. These are particularly useful for command line programs where you can check the syntax and then run the command from the same shell. You can even get more help on man by looking at the "man" man page!

If you know the page that you want help on (e.g. a command name) then enter man followed by the page / command will show the appropriate page.

For example to get help on the pg command type:

man pg

this shows:

PG(1) User Commands PG(1) 
 
NAME 
pg - browse pagewise through text files 
 
SYNOPSIS 
pg [-number] [-p string] [-cefnrs] [+line] [+/pattern/] [file...] 
 
DESCRIPTION 
pg displays a text file on a CRT one screenful at once. After each 
page, a prompt is displayed. The user may then either press the new 
line key to view the next page or one of the keys described below. 
 
If no filename is given on the command line, pg reads from standard 
input. If standard output is not a terminal, pg acts like cat(1) but 
precedes each file with its name if there is more than one. 
 
If input comes from a pipe, pg stores the data in a buffer file while 
reading to make navigation possible. 

The manual pages cover more than the commands you run at the shell, they also hold subroutines that could have the same name as commands. Also there may be commands with the same name but different actions depending upon the aspect of the system it works on. The man pages are actually split into 8 different types. These can be accessed by putting the number before the command.

The format of this is

man x page

where x is the section number (see list later), and page is the name of the command, file, or library you are looking for help on. There are some options that can also be included.

Man Sections

The man pages are split into sections. These sections are:

  • 1 User commands/li>
  • System calls
  • 3 Library functions
  • 4 Devices and device drivers
  • 5 File formats
  • 6 Games
  • 7 Miscellaneous
  • 8 System and operation

This means that there can be different man pages with the same page nanme, but different section number.

The man files are all held within the directories listed in the $MANPATH environment variable. This is normally /usr/man for the operating system commands and /usr/local/man for any additional commands, but additional paths can be added if required.

Typically each command registered with man will have the following information:

  1. Name - The title and a one line description
  2. Synopsis - The syntax used
  3. Description - Information on the function and usage of the command. This normally includes examples.
  4. Files - Any associated files
  5. See also - Any related information (other man pages)
  6. Bugs - Known Bugs or odd behaviour experienced

Finding the Command

If you don't know what the name of the command is then you can use the -k option to find the commands that perform a certain function. For example if you need to find a directory listing you could try a search on the word list.

man -k list

One of the pages shows the following [my highlighting]

listen (2) - listen for connections on a socket 
listres (1) - list resources in widgets 
locale-gen (8) - compile a list of locale definition files 
lorder (1) - list dependencies for object files 
ls (1) - list directory contents 
lsattr (1) - list file attributes on a Linux second extended file s... 
lsblk (8) - list block devices 
lshal (1) - list HAL devices 
lshw (1) - list hardware 
lsinitramfs (8) - list content of an initramfs image 
lsof (8) - list open files 
lspci (8) - list all PCI devices 

the ls command is the one that we were looking for.

When you run the man command with the -k option for the first time, you may be told that you have to create the whatis database. The reason for this is that for speed purposes the reverse lookup information is held in a database file called the "whatis database", or cat pages. This is done by issuing the command catman –w . This may need to be done by root to have the appropriate permissions.

$ man -k list 
man: 0703-310 file man not found. 
Create the whatis database using the <catman -w> command

Another command similar to using man with the -k option is apropos. To search for a command that performs a list function try:

apropos list

This also uses the whatis database so may also need the catman command to be run.

Asking the Command for Help

Another way of obtaining help for what a command is or what it does is to use the help switch. Although there is no official standard for how to call the commands help page the most common switch is --help, other switches in common use include -? and -h

For example

pg --help

would show the command options available for the pg command. The --help option is not necessarily as comprehensive as using the man pages. Often the --help switch will give a list of the available options only, compare this to the man display earlier.

$ pg --help  
Usage: pg [-Number] [-p String] [-cefns] [+LineNumber] [+/Pattern/]  
[File...]

The --help option has been around the longest and is usually implemented. However some commands support a -h option instead.

Most commands will support both the above however if one doesn't work you could try the other, which may work. Some commands also give the help information if you do not format the command properly, although you should not rely on this unless you know the consequences.

Finding the Command - which and whereis

Other useful commands are "which" and "whereis", which are used to locate a particular program (or specific files) on the disk.

The which command lists which command will be run if you enter the specified command. For example running which echo gives:

$ which echo

/bin/echo 

This says that if you run the command echo then it will use the one found in the /bin directory. This can be a useful tool if you end up with multiple versions of the same program installed. It will show the one that is being run from the command line.

The other command whereis searches for source files and man pages in addition to the command names, and prints them all. If you have two versions of the same program in the search path then it will show where both are so that you can identify which is the current one.

$ whereis echo

echo: /bin/echo /usr/share/man/man1/echo.1.gz 

This example shows the location of the program file, and the location of the associated man page.

The Linux Documentation Project - HOWTOs

The Linux Documentation Project (http://www.tldp.org) is a web site dedicate to collecting documentation about Linux. It is best known for the collection of HOWTOs which provide subject related guides. These guides give information about the subject as well as specific examples to help you get started.

Other Raspberry Pi Projects and tutorials

Previous Raspberry Pi Linux computer for learning programming
Raspberry Pi Linux computer for learning programming
Next Command line basics reference guide
Command line basics reference guide