Linux - Read, and Use System Documentation

In this blog, we will see how to read, and use system documentation in Linux. There will be many commands we will use in Linux. And each command has a lot of command-line switches. For example, let’s look at the ls command that lets us see what files and directories we have on the computer.

ls -a

is used to show us all entries, even “hidden” files and directories.

ls -l

shows us a long listing format, where we can see more useful data: file creation time, user that owns the file, permissions, and so on.

How are we supposed to remember -a and -l?

As we use a command over and over again, we’ll learn everything about it and memorize what each option like -l or -a does. But in the beginning, we might forget about these options after just one or two uses. That’s why Linux gives you multiple ways to access “help manuals” and documentation, right at the command line.

Want to gain a deeper understanding of Linux's main concepts? Watch this video.

Now, let's see how we can access the help manuals.

–help

Let’s say you want to see that long listing format with ls, to get a look at file permissions. But you forgot what the correct option was. Was it -p for permissions? We can get a quick reminder with:

ls --help

This will show us a lot of output. But if we scroll up, we’ll find what we’re looking for

You can see how command-line options are sorted alphabetically and described with a short text. That’s why –help will very often be helpful when we forget about these options (and we definitely will, as there are so so many of them for each command).

Manual Pages with man command

–help will usually show a condensed form of help, very short explanations. For ls, that’s ok, as it’s a very simple command. Other commands, however, are very complex and we need to read longer explanations to understand what they do and how we use them.

Let’s take journalctl as an example, a command that lets us read system logs.

journalctl --help

will show us this:

We’ll notice that this opens in a slightly different way (look at “lines 1-27”) in the bottom left corner. This opened up in what Linux calls a “pager”. It’s simply a “text viewer” of sorts that lets us scroll up and down with our arrow keys or PAGE UP, PAGE DOWN. To exit this help page, press q.

All important commands in Linux have their own manuals or “man pages”. To access a command’s manual enter “man name_of_command”. In our case, we’d use:

man journalctl

Now we get:

• Short description of what the command does in NAME.
• General syntax of command in SYNOPSIS
• Detailed description of command, how it works, and so on, in DESCRIPTION.
• Detailed descriptions of command line options in OPTIONS.
• And some manual pages even have some EXAMPLES near the end of the manual.

Sometimes, you will have two man pages with the same name. Example:

printf is a command. But printf is also a function that can be used by programmers.

Manual pages can fall into one of these categories (sections):

If you want to read the man page about printf, the command, you tell man you want to consult printf from section 1, like this

man 1 printf

If you want to read about printf, the function, you tell man you want to look at section 3

man 3 printf

It’s useful to know that during online exams, the Linux Foundation will let you use man and –help. Try to use –help if you forgot a command-line option as that gives you the fastest results. Diving deep into a manual page will eat up more time.

But this is all good and well when we know what command we want to explore. But what if we can’t even remember the name of the command that we need to use?

Searching for Commands that Do Something (apropos/man -k)

Imagine you forgot the name of the command that lets you create a new directory. How would you search for it?

apropos is a command that lets you search through man pages. It looks at the short descriptions of each man page and tries to see if it matches the text we entered. For example, with the next line, we can search for all man pages that have the word “director” in their short descriptions. We’ll use “director” and not “directory”. “director” will match commands that contain the word “directory” but also the ones that contain “directories”. So we keep it more generic this way.

apropos director

apropos relies on a database. A program has to refresh it periodically. Since we just started this virtual machine, the database hasn’t been created yet. We can create it manually with:

sudo mandb

On servers that have already run for days, there should be no need to do this, as it will be done automatically.

Now the apropos command should work:

apropos director

But those are a lot of entries which makes it hard to spot what we’re looking for. You see, apropos doesn’t just list commands. It also lists some other things we don’t need, currently. We see stuff like (2). That signals that that entry is in section 2 of the man pages (system calls provided by the Linux kernel). That’s just too advanced for our purposes. Commands will be found in categories (sections) 1 and 8. We can tell apropos to only filter out results that lead to commands from these categories. We do this by using the -s option, followed by a list of the categories we need.

apropos -s 1,8 director

And we can spot what we were looking for

Notice how mkdir’s description contains the word “directories”. If we’d used the word “directory” in our apropos search, this command wouldn’t have appeared since “directory” wouldn’t have matched “directories”. Something to keep in mind when you want to make your searches as open as possible, to match more stuff.

Tab for Suggestions or Autocompletion

Although this is not technically system documentation, it can still be helpful. Many commands have suggestions on what you can type next. For example, try this. Type

systemctl

add a space after the command (don’t press ENTER) and now press TAB twice.

You get a huge list of suggestions. This can help you figure out what your options for that command are. Although you should not always rely on it. It’s not necessary that absolutely all options are included in this suggestion list.

Another thing is you’ll save a lot of time with autocompletion. Type

systemc

press TAB

you get:

systemctl 

now add to that:

systemctl list-dep

press TAB

endencies will get added at the end and you get: systemctl list-dependencies. This is TAB autocompletion and many commands support it. When you press TAB once, if your command interpreter can figure out what you want to do, it will automatically fill in the letters. If there are many autocomplete options and it can’t figure out which one you want, press TAB again and it will show the list of suggestions we observed earlier. These will be huge timesavers in the long run, and they might even help you in the exam, to shave off a few seconds here and there, which might add up and let you explore an extra question or two.

TAB suggestions and auto-completion also work for filenames or directory names. Try

ls /u TAB

ls /usr/ TAB TAB

Now we can see directories available in /usr/ without even needing to explore this directory with “ls” beforehand. And if we have a long filename like “wordpress_archive.tgz” we might be able to just type “wor“, press TAB, and that long name will be autocompleted.

To learn more about Linux checkout our hands-on Linux course here

To get free hands-on experience on System Administration and DevOps tasks please check out our KodeKloud Engineer program here