Learn › Linux Foundations › Getting Help
Final test: Chapter 3, Getting Help. Twenty-five objectives on a real Debian 12 server: man in nine forms including numbered sections, --help on five commands, whatis and man -f, apropos and man -k, and help for four builtins. Fifty minutes, graded from the commands you run.
This chapter covers the following topics:
What you already know: Chapter 1 defined the terminal, the shell and the prompt, and gave you whoami, hostname, pwd, echo, date, uname, uptime, clear and history. Chapter 2 gave you ls, cd and tree, and the idea of an option. This chapter teaches how to find out what any command does without leaving the terminal, so that every later chapter can send you to the manual.
Objectives
After this chapter you can:
The practice terminals in this chapter simulate the server admin@server1. Each one checks the single command it asks for, and nothing you type in them can break anything. Where a real terminal would open a page in the pager, the practice terminal shows the top of that page instead, as an 80-column window formats it. When you start the practice machine from the panel, the real server takes their place and the pager is real: q leaves it. The graded lab at the end runs on a real Debian 12 server, prepares the chapter environment when you launch it. Follow the startup progress on screen. It records practice with the commands you run. While the terminal connection stays open, the same shell carries across steps. A new connection can start a new shell; check your prompt before continuing. Nothing in this chapter depends on that: every command here reads the manual or a program's own help, and each one works from any directory on the machine.
Five questions before the material. A wrong answer costs nothing: the explanation states the fact and names the section that teaches it.
>>> The manual pages used in this chapter are installed on this server and work with no network. They document the installed packages, but if a page and a program disagree, check the program's own output too. man opens a page. Section 3.2.
>>> The manual is divided into numbered sections by kind of thing: section 1 holds commands, section 5 holds file formats. passwd exists in both, and the number picks the one you want. Section 3.5.
>>> man and whatis both start from a name. apropos starts from a word and returns every page whose name or description contains it. Section 3.7.
>>> The programs demonstrated here answer --help with usage and options in the terminal, then stop instead of doing their usual work. Other programs can handle the option differently, so check the result. Section 3.8.
>>> On this server, man cd does not open a dedicated page. cd is a Bash builtin, and help cd describes it directly. The man bash page also describes Bash builtins together. Section 3.9.
You remember that ls lists files. Now you want to include names that start with a dot, such as .bashrc. Which option does that, and how can you check it without guessing?
Start with a command you know. A manual page is an installed document about a command, a file format or a concept. man ls opens the page about ls. It reads documentation; it does not list your files or change them.
Read for one answer. You do not need to read the whole page. We will find the option for dot-prefixed names, read what it does, then try it and compare the result with plain ls.
Know how to get back. The page opens in a pager, a program for reading long text one screen at a time. Press q to close it and return to the shell prompt.
First we will practise opening, moving through and leaving a page. Later, a different question will introduce each of the other help tools. There is no need to memorise five commands before using the first one.
These pages are already installed on this Debian practice machine, so they work without internet access. Other machines may not have the same documentation installed.
The command has two parts: man asks for documentation; ls names the page to open.
Before you open it: will man ls show your home directory, or instructions for using ls? Say which you expect and why.
On this machine, man shows the document through the pager less. While the page is open, keys go to that reader. They are not new shell commands.
Look at the bottom line for the page name and a help or quit reminder. Press q when you want the shell prompt back. You can always reopen the same page with man ls.
Start with three keys. You will use them on the next step's real practice machine.
Press these keys on their own while the page is open. Do not type their names at the shell prompt or add Enter.
Once you can leave the page comfortably, try a search: type /--all and press Enter. The slash starts a search; --all is the text to find. Press n for the next match if needed. This will take you to the option we want to investigate.
The command examples below can show the beginning of a manual page. To practise the pager keys and inspect your own files, start the practice machine. These keys are not checked by the command examples.
Open the page for ls. Check whether its NAME line matches the purpose you predicted:
prompt: admin@server1:~$ answer: man ls output: LS(1) User Commands 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 -cftuvSUX nor --sort is speci‐ fied.
Mandatory arguments to long options are mandatory for short options too.
-a, --all do not ignore entries starting with .
-A, --almost-all do not list implied . and ..
--author with -l, print the author of each file
-b, --escape print C-style escapes for nongraphic characters
--block-size=SIZE with -l, scale sizes by SIZE when printing them; e.g., '--block-size=M'; see SIZE format below
-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, newest first
-C list entries by columns hint: Section 3.2. The manual tool, then the name ls. Press q to leave the page.
The example shows the beginning of the documentation. Under NAME, ls - list directory contents identifies the command. It is a description of ls, not a listing of your files.
Try the full question on your practice machine. While man ls is open, search for /--all and press Enter. Read the matching option's description. Which names do you expect ls -a to include that plain ls leaves out?
Press q. At the returned shell prompt, run ls, then ls -a, in the same directory. Compare the names. Dot-prefixed entries such as .bashrc are the evidence to look for; the exact list depends on your directory. . and .. may appear too, as you saw in Chapter 2.
The manual gave you a reason to choose -a, and the second listing lets you check that choice. Neither command changes your files. If you wanted the ordinary listing, leaving the command as ls would be appropriate.
This extra practice uses your real terminal. The command example above checks only man ls, not your explanation or the comparison.
A long manual page is easier to use when you know where to look. In the ls page you just opened:
ls and says it lists directory contents.ls [OPTION]... [FILE]....-a.Read the synopsis as a pattern. ls is literal. [OPTION] means an option is optional; [FILE] means a file or directory argument is optional. Each ... means the part before it can repeat. Replace the placeholders with real values; do not type the brackets or dots.
For example, ls fits the pattern with nothing added. ls -a adds one option. ls -a /etc adds an option and a directory. Those are familiar forms from Chapter 2.
Pages for file formats and concepts can use different headings. Find the part that answers your question; you do not need to read every section.
Open the page for tree. Its SYNOPSIS is long, so look for just the directory argument and the -L option you used in Chapter 2:
prompt: admin@server1:~$ answer: man tree output: TREE(1) General Commands Manual TREE(1)
NAME tree - list contents of directories in a tree-like format.
SYNOPSIS tree [-acdfghilnpqrstuvxACDFJQNSUX] [-L level [-R]] [-H baseHREF] [-T title] [-o filename] [-P pattern] [-I pattern] [--gitignore] [--git‐ file[=]file] [--matchdirs] [--metafirst] [--ignore-case] [--nolinks] [--hintro[=]file] [--houtro[=]file] [--inodes] [--device] [--sort[=]name] [--dirsfirst] [--filesfirst] [--filelimit #] [--si] [--du] [--prune] [--charset[=]X] [--timefmt[=]format] [--fromfile] [--fflinks] [--info] [--infofile[=]file] [--noreport] [--version] [--help] [--] [directory ...]
DESCRIPTION Tree is a recursive directory listing program that produces a depth in‐ dented listing of files, which is colorized ala dircolors if the LS_COLORS environment variable is set and output is to tty. With no arguments, tree lists the files in the current directory. When direc‐ tory arguments are given, tree lists all the files and/or directories found in the given directories each in turn. Upon completion of list‐ ing all files/directories found, tree returns the total number of files and/or directories listed.
By default, when a symbolic link is encountered, the path that the sym‐ bolic link refers to is printed after the name of the link in the for‐ mat:
name -> real-path hint: Section 3.3. The manual tool, then the name tree, the drawing command from Chapter 2.
This SYNOPSIS groups many single-letter options and then lists longer forms. At the end, [directory ...] means tree can take zero or more directory paths, which is why bare tree in Section 2.7 worked.
The -L option you used in Exercise 2-36 appears as [-L level [-R]]: -L followed by a depth you supply, with -R optional inside that form. To learn what -R does, find its entry in DESCRIPTION instead of guessing from the notation.
The middle of the first line is the name of the manual volume the page belongs to, and each page sets that name itself: User Commands for ls, General Commands Manual for tree. The (1) beside each page name identifies section 1. Press q to leave.
The manual has a page about man. It documents the options man accepts and the sections of the manual, and it is the page to read once when the layout of the manual is new:
prompt: admin@server1:~$ answer: man man output: MAN(1) Manual pager utils MAN(1)
NAME man - an interface to the system reference manuals
SYNOPSIS man [man options] [[section] page ...] ... man -k [apropos options] regexp ... man -K [man options] [section] term ... man -f [whatis options] page ... man -l [man options] file ... man -w|-W [man options] page ...
DESCRIPTION man is the system's manual pager. Each page argument given to man is normally the name of a program, utility or function. The manual page associated with each of these arguments is then found and displayed. A section, if provided, will direct man to look only in that section of the manual. The default action is to search in all of the available sections following a pre-defined order (see DEFAULTS), and to show only the first page found, even if page exists in several sections.
The table below shows the section numbers of the manual followed by the types of pages they contain.
1 Executable programs or shell commands 2 System calls (functions provided by the kernel) 3 Library calls (functions within program libraries) 4 Special files (usually found in /dev) 5 File formats and conventions, e.g. /etc/passwd hint: Section 3.4. The manual tool, then its own name, man.
MAN(1): the manual itself is a command in section 1. Its SYNOPSIS shows several ways to call it, one per line. The first, man [man options] [[section] page ...], is the shape this chapter uses: an optional section number, then one or more page names.
The -f line is Section 3.6 and the -k line is Section 3.7. Further down, the DESCRIPTION starts the table of sections that Section 3.5 completes: 1 for programs, 2 for system calls, 3 for library calls, 4 for special files, 5 for file formats. Press q to leave.
Section 1 also holds a page named intro, an introduction to using the command line written for someone who has never used one:
prompt: admin@server1:~$ answer: man intro ||| man 1 intro output: intro(1) General Commands Manual intro(1)
NAME intro - introduction to user commands
DESCRIPTION Section 1 of the manual describes user commands and tools, for example, file manipulation tools, shells, compilers, web browsers, file and im‐ age viewers and editors, and so on.
NOTES Linux is a flavor of UNIX, and as a first approximation all user com‐ mands under UNIX work precisely the same under Linux (and FreeBSD and lots of other UNIX-like systems).
Under Linux, there are GUIs (graphical user interfaces), where you can point and click and drag, and hopefully get work done without first reading lots of documentation. The traditional UNIX environment is a CLI (command line interface), where you type commands to tell the com‐ puter what to do. That is faster and more powerful, but requires find‐ ing out what the commands are. Below a bare minimum, to get started.
Login In order to start working, you probably first have to open a session by giving your username and password. The program login(1) now starts a shell (command interpreter) for you. In case of a graphical login, you get a screen with menus or icons and a mouse click will start a shell in a window. See also xterm(1).
The shell One types commands to the shell, the command interpreter. It is not built-in, but is just a program and you can change your shell. Every‐ body has their own favorite one. The standard one is called sh. See also ash(1), bash(1), chsh(1), csh(1), dash(1), ksh(1), zsh(1).
A session might go like:
knuth login: aeb Password: ******** $ date hint: Section 3.4. The manual tool, then the page name intro, which lives in section 1.
On this server, intro(1) walks through logging in, the shell, the prompt, and a first session in plain words. It covers the ground of Chapters 1 and 2. Other installations may not include this page. Press q to leave.
Suppose you want to understand /etc/passwd, a file you will read in Chapter 4. There is also a command named passwd, which changes passwords. How does the manual distinguish the two?
It groups pages into numbered sections. For now, remember this pair:
man 1 passwd describes the password-changing command.man 5 passwd describes how to read the fields in /etc/passwd.The section goes between man and the page name. In the page heading, PASSWD(1) or PASSWD(5) tells you which document you opened. Reading either page does not run passwd or change an account.
Predict: if you leave out the number, can man show both documents at once? On this machine it opens the first match in its configured search order, which starts with section 1. The next three exercises compare the default, an explicit section 1, and section 5.
Other sections group other kinds of documentation. Section 7 includes overviews; section 8 includes administration commands. You can look up the full list in man man when you need it. A page's section is not proof that your account has permission to run its comman
Practice Chapter 3. Getting Help: man, whatis, apropos, --help and help in a real Linux terminal at The Linux Camp. Progress is verified automatically as you type commands on the machine.