In Linux, if you ever need help regarding a command, all you need to do is to open its man page. But what if a situation arises wherein the requirement is to quickly search the names and descriptions of all available man pages? Well, Linux has got your covered, as there exists a command dubbed apropos that does exactly this for you.

In this tutorial, we will discuss the basics of apropos using some easy to understand examples. But before we do that, it's worth mentioning that all examples here have been tested on an Ubuntu 16.04 LTS machine.

Linux apropos command

The apropos command searches manual page names and descriptions for a user-supplied keyword. Following is its syntax:

apropos [OPTIONS] keyword ...

And here's what the tool's man page says about it:

Each manual page has a short description available within it. apropos searches the descriptions for instances of keyword.

keyword is usually a regular expression, as if (-r) was used, or may contain wildcards (-w), or match the exact keyword (-e). Using these options, it may be necessary to quote the keyword or escape (\) the special characters to stop the shell from interpreting them.

The standard matching rules allow matches to be made against the page name and word boundaries in the description.

The database searched by apropos is updated by the mandb program. Depending on your installation, this may be run by a periodic cron job, or may need to be run manually after new manual pages have been installed.

Following are some Q&A-styled examples that should give you a good idea on how the apropos command works.

Q1. How to use apropos?

Basic usage is simple. Just pass the keyword you want to search as input to the apropos command.

Q2. How to make apropos search for exact keywords?

By default, the input you pass to the apropos command isn't searched exactly. For example, if you pass 'who' as an input, you'll also see the tool producing results containing words like 'whoami'.

So this isn't an exact search. However, you can force apropos to search for exact keywords by using the -e or --exact command line options.

So now you see that only those entries that exactly match 'who' were displayed in the output.

Q3. How to make apropos display entries matching all keywords?

If you pass multiple keywords as input to the apropos command, the tool will output entries that match/contain at least one of the keywords. However, if you want apropos to produce only those entries that match/contain all keywords, then use the -a command line option.

For example, here's the output of an apropos command without the -a option:

And here's the output with -a option enabled:

Q4. How to force apropos to not trim output?

As you'd have seen in output in previous Q&As, the tool trims entries if they are too long. For example, see the highlighted line in the following output:

However, if you want, you can force apropos to produce complete lines in output, something which you can do using the -l command line option.

Q5. How to interpret apropos exit status?

The apropos command produces four different exit status: 0, 1, 2, and 16. Here's what each of these represents:

0 Successful program execution.

1 Usage, syntax or configuration file error.

2 Operational error.

16 Nothing was found that matched the criteria specified

Conclusion

Depending on your work profile, you might not require the apropos command on daily basis, but as you'd have understood by now, it could be a lifesaver in certain situations. We've discussed some use command line options here. To know more about the tool, head to its man page.

About Himanshu Arora

Himanshu Arora has been working on Linux since 2007. He carries professional experience in system level programming, networking protocols, and command line. In addition to HowtoForge, Himanshu's work has also been featured in some of world's other leading publications including Computerworld, IBM DeveloperWorks, and Linux Journal.