1. Introduction
Manual pages in Linux are useful since they serve as a vital standard resource of information. However, at times, we might need to go through many different manual pages to find the required information. That’s where the search option comes in.
In this tutorial, we’ll explore how to search all available Linux manual pages. First, we’ll cover the apropos command. After that, we’ll discuss the man command to search Linux manuals. Lastly, we’ll explore how to use grep with man to search the manual pages.
2. The apropos Command
The apropos command searches manual pages and descriptions. After that, the result is shown on the screen. We can use this command to search the manual pages.
2.1. apropos Examples
For instance, if we want to search for a term across all sections of the manual pages, we use that term with the apropos command:
$ apropos compare
[ (1) - check file types and compare values
bcmp (3) - compare byte sequences
diff (1) - compare files line by line
…
In the above command, we search for the word compare, so apropos looks for all manual pages that mention compare in their name or description.
Alternatively, if we want to search for the exact phrase, we can enclose it in the quotation marks:
$ apropos "remove file"
git-rm (1) - Remove files from the working tree and the index
rm (1) - remove files or directories
We can also use apropos to interpret each keyword as a regular expression using the -r option:
$ apropos -r '^printf'
printf (1) - format and print data
printf (3) - formatted output conversion
In addition, we can search in a particular section using the apropos command. For instance, to search for the delete function in section 1 of the manual, we add the –s 1 option:
$ apropos -s 1 delete
git-branch (1) - List, create, or delete branches
git-replace (1) - Create, list, and delete refs to replace objects
git-symbolic-ref (1) - Read, modify, and delete symbolic refs
shred (1) - overwrite a file to hide its contents, and optionally delete it
tr (1) - translate or delete characters
Thus, the -s 1 option restricts the search to section 1 of the manual, which includes commands that users can run from the command line.
2.2. Limitation of apropos
While the apropos command is handy for finding keywords within the descriptions of manual pages, it has its limitations. It primarily restricts searches to these results. To elaborate, apropos may not cover all instances of a keyword within the manual pages.
For instance, let’s consider the scenario where we search for viminfo:
$ apropos viminfo
viminfo: nothing appropriate
Despite viminfo being a valid term within the vim manual, apropos produces no results. Also, the results may include entries that aren’t directly related to what we’re looking for because they match descriptions.
To illustrate, let’s see an excerpt from the vim manual that provides detailed information about the viminfo file:
…
-i {viminfo}
When using the viminfo file, use {viminfo} instead of the default
viminfo file. If {viminfo} is equal to "NONE" (all uppercase), no
viminfo file will be read or written.
viminfo The viminfo file is used to store:
- The command line history.
- The search string history.
- The input-line history.
- Contents of registers.
- Marks for several files.
- File marks, pointing to locations in files.
…
Thus, this is where a more thorough search method becomes essential.
3. Using the man Command
While apropos helps in finding commands and topics related to a keyword, man provides whole and detailed manual pages. In particular, these pages describe the functionality, usage, options, and examples for each command or function.
Furthermore, man offers comprehensive documentation that can help troubleshoot issues of a command. Lastly, all of the functionality works without needing external resources such as network access. This is useful in environments where the Internet connection is restricted.
3.1. Using the –global-apropos Option
The man command offers a powerful feature for thorough searching across all manual pages. By using the -K or –global-apropos option, we can search through all the content of all manual pages.
For instance, for the detailed search on viminfo, we use the -K option:
$ man -K viminfo
This opens the manual page in a new window.
In addition, to search for the term viminfo across all manual pages and display the paths to the relevant pages, we use the -w flag:
$ man -wK viminfo
/usr/share/man/man1/vim.1.gz
…
/usr/share/man/man1/vim.1.gz
/usr/share/man/man1/run-one.1.gz
…
The -w option provides an overview of each displayed manual page.
3.2. Using the grep Command
We can also pipe the man command output to the grep command to search for specific patterns within the man pages.
For example, to search for the -X option within the curl manual page, we pipe man to grep:
$ man curl | grep -- '-X'
See also -d, --data and -X, --request.
Note: When combined with -X, --request, this option can be used to send a UIDL command instead
…
See also -X, --request.
curl --request-target "*" -X OPTIONS https://example.com
…
-X, --request <method>
want to make a proper HEAD request, using -X HEAD will not suffice. We use the -I, --head option.
…
The — double dash indicates the end of options, ensuring grep interprets -X as the search pattern. Alternatively, we can use -e to specify the pattern instead of —:
$ man curl | grep -e '-X'
See also -d, --data and -X, --request.
…
See also -X, --request.
…
Furthermore, to quickly find documentation related to the -X option and read the lines following that information, we specify parts of the manual pages:
$ man curl | grep -A 20 -- '-X'
See also -d, --data and -X, --request.
-g, --globoff
…
The above command uses man and grep to display specific parts of the manual page for -X in the curl command. As before, the grep -A 20 — ‘-X’ part of the command is used to search for the string -X. Notably, the -A 20 option in grep specifies that 20 lines of context after the matching line should also be shown.
In addition, the — signifies the end of command options and the beginning of positional parameters. This ensures that -X is interpreted as a search string. By using this command, we extract a detailed section of the manual that explains the usage of the -X option.
4. Conclusion
In this article, we covered how to search the entirety of the Linux manual page database. To begin with, we discussed the apropos command, followed by its limitations. Lastly, we covered the man command.
While apropos assists in locating relevant manual entries based on keywords, it may return irrelevant results. On the other hand, the man command provides in-depth documentation that we can use to fully understand commands and concepts.