7. Reading the Man Pages#
There’s an old joke that goes the only command you need to know in linux is man, and hopefully by the end of this chapter you’ll understand why.
What are man pages? What is documentation?
7.1. Documentation, Documentation, Documentation#
Remember when we said writing good documentation is essential to developing durable, usable software? No? Well, writing good documentation is essential to developing durable, usable software. Want proof? Look no further than the linux man pages.
Linux man pages are a type of documentation, written content that can explain how software or a technology works. Documentation can be written for all aspects of a technology’s life from its usage, to its development, to its maintenance. In this case, the man pages are written as user-oriented documentation—a manual, if you will—and its users are not necessarily consumers, but software developers themselves.
It’s important to consider man pages within the broader context of software documentation.
Documentation is written content that helps explain how some code or technology should be used. Linux has it’s own built in documentation, called the man pages (man being short for manual).
Image Source: https://wiki.gentoo.org/wiki/Man_page
7.2. Man, oh man! (Dissecting the man command)#
So how do we get there? They only show up if you ask for them. And they work just like the tools we learned in our command line chapter.
By using man [ name of the command ]
So, if you wanted to look at ls’s man page, you would type
man ls
There are 281,555 (non-unique) man pages floating around in the Unix & Linux commands man pages set. This means Unix has basically has a built in manual, that you can use at any time, explaining the use of each command, and ways to manipulate that command’s behavior through options.
7.3. Reading the Man Page#
So… now that we’ve gotten to a man page, (reminder: man your-desired-command) how do we read a man page?
After you type your command, linux will display the page that you requested. The first thing you might notice about the page is that there is a LOT of writing. Remember how we said linux man pages are an example of good documentation? Well, they’re also extensive. And while it may seem daunting, each man page is clearly and uniformly organized into specific parts, once you understand the organization behind man pages, you will have a much easier time wading through them.
Every man page is broken up into at least six distinct parts: Let’s break it down.
Section Name |
Description |
|---|---|
NAME |
A given command’s name and short description |
SYNOPSIS |
A given command’s proper syntax |
DESCRIPTION |
A full explanation of how a given command works |
OPTIONS |
Optional parameters for a given command and their descriptions |
EXAMPLES |
Command line and script examples of the given command |
SEE ALSO |
Related man pages to the given command |
For example:
This is what grep’s manpage would look like:
Image Source: https://unix.stackexchange.com/questions/630687/how-to-pipe-manpage-to-grep
Other possible sections of some man pages include ENVIRONMENT, EXIT STATUS, COMPATIBILITY, and more!
7.4. Talkin’ about Options#
Options let you manipulate the behavior of specific commands. Say you want to delete a directory without having to confirm if it’s ok with your system ( which can get tedious, albeit a little unsafe… ), instead of just using rm, you would use rm -rf, with the -r standing for recursive and -f standing for with force (no annoying asking!). This option lets you use the command in a more useful and custom way. Another example of this you may have seen is ls -la list all the hidden files in a directory.
Most options use a - or – followed by a letter. The man pages specify what letters can be used as options, and what the modified behavior is.
So, now, how do we read the options?
7.5. Syntax to Know#
Optional Arguments
When an argument is optional, it’s usually enclosed in square brackets. And sometimes there might be multiple optional arguments, and each will have their own set of square brackets.
Let’s look at an example, using the command ping, that tests the reachability of a host:
ping [-c count] [-t ttl] host
As we can see here, host is required, while -c count and -t ttl are optional!
Mutually Exclusive Arguments
Some argument’s can’t operate at the same time. You have to choose one option, rather than both. This means that they are mutually exclusive.
Curly braces show that the arguments are mutually exclusive. Multiple mutually exclusive options can be separated by a pipe (|).
Let’s look at an example, you can choose either --silent or --verbose, because the two options are conflicting:
{--silent|--verbose}
Arguments That Can Repeat
Use three dots (…) without spaces (an ellipsis) to indicate that an argument can be repeated multiple times.
Let’s look at another example, looking at the man page for ln, which links files:
ln [OPTION]... TARGET
So, it could look like…
ln file1 file2 file3 target_directory/
Because the ... tells us we can have multiple arguments.
Uppercase vs Lowercase
A reminder that options are case sensitive!
Short Options vs Long Options
Single-letter options that are preceded by a minus sign (-). The case of the letter is important, as different options have different effects. For example, -e and -E are different options. These are referred to as short options. Long options are made up of two hyphens followed by one or more lowercase alphanumeric words. Hyphens separate the words. So, rather than dealing with letters which can get cryptic and confusing, you have the option to have a longer but more clear option.
For instance: ls -a vs ls --all
Flags vs Options
A Stackoverflow user defines the difference between them here: “A flag is a type of option, an option of boolean type, and is always false by default (e.g. –verbose, –quiet, –all, –long, etc).
An option tells the function how to act (e.g. -a, -l, –verbose, –output , -name , -c , etc), whist an arguments tells the function what to act on/from (e.g. *, file1, hostname, database).”
Inverse flags
These are flags with the opposite behaviour, that are mutually exclusive. Often based off the behaviour if other flags because they are inverse. They begin with –no-. For example, –sort and –no-sort.
Image Source: https://www.zdnet.com/article/what-are-man-pages-and-why-are-they-important-to-your-linux-education/
7.6. How to exit a man page#
Finished reading a command’s documentation? Use the Q key to return to the command line!
Image Source: https://www.reddit.com/r/unixporn/comments/2b9pfl/procedurally_colored_man_pages_every_man_page_has/
7.7. Now You Try!#
So how do we read a man page? So you’ve correctly typed in your man command. Now what? Well, unless the man pages are abjectly broken, linux will display the page that you requested. The first thing you might notice about the page is that there is a LOT of writing. Remember how we said linux man pages are an example of good documentation? Well, they’re also extensive, which means they are detailed. And while extensive is a daunting word, each man page is clearly and uniformly organized into specific parts, kind of like a scientific article. Just like with a scientific article, once you understand the organization behind man pages, you will have a much easier time wading through them.
Every man page is broken up into at least six distinct parts:
Find the man pages’ man page. You heard me. Type man man in your command line and see what happens!
man man
We promise the result is not as goofy as you’d think! Happy exploring!