% Searching for items in the Unix manual pages (RTFM) % Ian! D. Allen -- -- [www.idallen.com] % Fall 2014 - September to December 2014 - Updated 2018-10-04 17:44 EDT - [Course Home Page] - [Course Outline] - [All Weeks] - [Plain Text] The Unix manual pages (RTFM) ============================ Unix-like operating systems -- including Linux, BSD, and OSX -- have command-line help files called "**man** pages" (manual pages). The usual way to access to **man** pages is via the `man` command. You may be told to `RTFM` which means `Read the F*** Manual`. That's what this page is about. First, we need to know how manual pages are displayed on your screen. Displaying manual pages using `less` ==================================== When you type `man something` at a Linux shell prompt, the pages of the manual are displayed one-at-a-time using a standard "pagination" program named `less`. For example, try: $ man date You will see one screen of the manual followed by a `Manual page` prompt at the bottom of your terminal screen. You can type the characters `h` or `?` to get a list of possible commands that the `less` pagination program can do. Typing `q` will return you from the help screen back to the manual page itself. Typing `q` again will quit the `man` program and return you to your shell prompt. Common commands you use in the `less` program are `q` (quit) and *SPACE BAR* to go to the next page. A `b` goes back one page. If you forget how to use `less`, ask for the help screen by typing `?` or `h` at the `Manual page` prompt. Try these now. > If `less` is not available to paginate the output, the `man` command uses > `more` in place of `less`. The `more` and `less` commands are more-or-less > the same, with `less` having more features. You can also look at [Linux man pages online], though this is a generic set of manual pages that may or may not apply to the commands on the version of Linux that you are running. Searching for text within a manual page ======================================= Because manual pages are usually paginated using a standard pagination program such as `less`, you can use all the features of the pagination program to search inside the manual page, including the text search feature that is usually bound to the slash key `/`. For example, bring up the man page for the `ls` command (`man ls`) and then at the `Manual page` prompt at the bottom of your screen search for the three words `long listing format` by typing a slash followed by the words you want to search for, followed by the `ENTER` kay: /long listing format You will instantly skip forward to the `-l` option description that makes the `ls` command give a long listing output format: -l use a long listing format You can use the `n` key to repeat a search if the first thing you find isn't what you are looking for. Try searching for the word `file` and use the `n` key repeatedly to find each line containing the word. If you forget how to use these features, simply follow the help directions in the prompt at the bottom of your screen as you read the manual page, or try `man less` at the shell prompt for more information on the `less` pagination program itself. Using the `man` command -- `man man` and `man intro` ==================================================== > You may find the short web resource [Using Man Pages] useful for > understanding the format of manual pages. The arguments to the `man` command must be single command names or topics, e.g. $ man date $ man ls $ man intro $ man man A useful start page and command introduction is: `man intro`\ The introduction summarizes these important topics: - The shell - Pathnames and the current directory - Directories - Getting information Looking up options to commands ------------------------------ If you want to know what the `-p` option to the `mkdir` command does, look in the man page for the `mkdir` command, i.e. you must type: $ man mkdir You cannot say `man mkdir -p` nor can you type `man -p`. You must open `man mkdir` and do a text search for the `-p` option in the `mkdir` man page. You can use the slash (`/`) character to text search for the option name inside the man page and `n` to search again. Some basic "coreutils" man pages are incomplete =============================================== Some basic GNU/Linux "coreutils" manual pages are incomplete summaries of the master GNU **TexInfo** documentation pages; these pages have a **SEE ALSO** section at the bottom saying *The full documentation for \[this command\] is maintained as a Texinfo manual.* This means these man pages are very terse and don't have all the information about commands that you might need. You can find a list of these basic "coreutils" commands here: The full TexInfo documentation is readable online using the old `info` or `pinfo` commands, but these commands pre-date HTML and are hard to learn and use. You can try to learn to use the `info` or `pinfo` commands, or you can read the documentation online in easy-to-read HTML form. You can find the full documentation for most of the basic ("core") Linux commands online at in the online manual The Manual has sections ======================= The Unix manual has "sections". The man command searches sections in a particular order and finds the first matching man page (which may not be in the section you want). Specify the section number first to see a page in a particular section, e.g.:   `man 5 passwd` Useful sections (for details, try `man 1 intro`, `man 2 intro`, etc.): - Section 1 -- user commands e.g. `date, who, ls` - Section 8 -- super-user and admin commands e.g. `useradd, ifconfig` - Section 2 -- kernel system calls e.g. `read(), write()` - Section 3 -- library function calls e.g. `fread(), fwrite()` - Section 4 -- special and device files e.g. `null, fifo, zero, hd` - Section 5 -- file formats e.g. `passwd, group, resolv.conf` See how the section number changes what information you get: $ man passwd # gives passwd command syntax from section 1 $ man 5 passwd # gives /etc/passwd file format from section 5 Searching for manual pages: `man -k` and `apropos` ================================================== Sometimes you don't know what manual page you want. You can search all the title lines (and only the title lines) using the '`-k`' (keyword) option to the `man` command, followed by a single keyword: $ man -k keyword The output of this search is not paginated, so often, if there are many results, you want to pipe the output of `man -k` into a pagination program such as `less`: $ man -k keyword | less The `|` character is the Unix "pipe" special character (often `SHIFT-\`). The `man -k` command works the same way as the `apropos` command: $ man -k keyword | less $ apropos keyword | less They are the same command. Using fgrep to filter search results ------------------------------------ Often, you get pages you don't want in the output of `man -k`. You can pipe the output of `man -k` into the `grep` or `fgrep` programs to select output that is more useful. To see only pages in section `(1)` of the manual (only the commands): $ man -k name | fgrep '(1)' | less Note the use of single quotes to protect the special characters (in this case, parentheses) from the Unix shell. Until you know what characters are safe, always single-quote the first argument to the `fgrep` command. > The `fgrep` command is the same as the `grep -F` command and option; > it runs `grep` using fixed strings (not patterns) as the search strings. > Until you know how to use `grep` patterns, always use `fgrep`. To find only pages that are *not* in section (1) of the manual: $ man -k name | fgrep -v '(1)' | less Note the use of the `-v` option to the `fgrep` command (RTFM). Finding pages containing "name" in the title, that are in section (1), that do not contain the string "directory" in the title: $ man -k name | fgrep '(1)' | fgrep -v 'directory' | less The `man -k` command works the same way as the `apropos` command: $ apropos name | fgrep '(1)' | fgrep -v 'directory' | less Make sure you protect the characters used in the `fgrep` pattern (the first argument to `fgrep`) from expansion or processing by the shell by surrounding the `fgrep` pattern (the first argument) by single quotes. Some commands have internal help as well as man pages ===================================================== On the old Microsoft DOS command line, commands print internal help by using the `/?` command line switch. Under Unix, you can try giving an argument of `--help` or `-help`, or `-h`. Not all commands have internal help. Be careful not to try unknown options such as `-h` on commands that might have serious side-effects -- the `-h` might do things you don't want it to do. Check the man page for what `-h` means before trying it with a command. Reading manual pages `SYNOPSIS` Line(s) ======================================= To understand how to read the syntax of the **SYNOPSIS** section of a manual page, see the *following conventions* lines in the **DESCRIPTION** section of the man page for the `man` command. Using `man man` you can learn what conventions apply to the **SYNOPSIS** section. (You can search for `following conventions` in the man page.) Answer these questions about the **SYNOPSIS** section of a man page: 1. What does **bold** text mean? 2. What does *italic* (underlined, on terminals) text mean? 3. What do square brackets `[]` around something mean? 4. What does the pipe or OR-bar symbol `|` (SHIFT-`\`) mean? 5. What do three dots (ellipsis) `...` mean? Use the above answers to do this exercise: Exercise: reading the SYNOPSIS section -------------------------------------- Given this small excerpt from the **SYNOPSIS** section of `man man`: `SYNOPSIS`\       **man** **-K** \[**-w**\|**-W**\] \[**-S** *list*\] \[**-i**\|**-I**\] \[**`--`regex**\] \[*section*\] *term* ... Which of these command lines has valid syntax, based on the above **SYNOPSIS**? 1. `man foo` 2. `man 3 foo` 3. `man -K foo` 4. `man -K -w -W foo` 5. `man -K -w foo` 6. `man -K -W foo` 7. `man -K -S foo` 8. `man -K -S 1,2,3 foo` 9. `man -K -i -I foo` 10. `man -K -W -i foo` 11. `man -K --regex foo` 12. `man -K --regex 3 foo` 13. `man -K -w -I --regex 3 foo` 14. `man -K -w -S 1,2,3 -W -i -I --regex 3 foo` Correct answers (valid syntax): `3, 5, 6, 8, 10, 11, 12, 13`  \ All the other command lines are not a valid syntax, given the above SYNOPSIS. Comic: XKCD on "man pages" ========================== ![[XKCD man page]][1] -- | Ian! D. Allen, BA, MMath - idallen@idallen.ca - Ottawa, Ontario, Canada | Home Page: http://idallen.com/ Contact Improv: http://contactimprov.ca/ | College professor (Free/Libre GNU+Linux) at: http://teaching.idallen.com/ | Defend digital freedom: http://eff.org/ and have fun: http://fools.ca/ [Plain Text] - plain text version of this page in [Pandoc Markdown] format [www.idallen.com]: http://www.idallen.com/ [Course Home Page]: .. [Course Outline]: course_outline.pdf [All Weeks]: indexcgi.cgi [Plain Text]: 140_man_page_RTFM.txt [Linux man pages online]: http://man7.org/linux/man-pages/index.html [Using Man Pages]: http://opensource.com/article/17/7/using-man-pages [XKCD man page]: http://xkcd.com/1692/ [1]: https://imgs.xkcd.com/comics/man_page.png "http://xkcd.com/1692/" [Pandoc Markdown]: http://johnmacfarlane.net/pandoc/