=================================================== Searching for items in the Unix manual pages (RTFM) =================================================== -Ian! D. Allen - idallen@idallen.ca - www.idallen.com Unix/Linux/BSD/OSX help files are called "man pages" (manual pages). The usual way to access to man pages is via the "man" command. First, we need to know how manual pages are displayed. Displaying manual pages using "less" or "more" ---------------------------------------------- The pages of the manual are displayed using a standard "pagination" program such as "less" or "more". You will see one screen of the manual followed by a prompt at the bottom of your terminal screen. You can type the characters 'h' or '?' to get a list of possible commands that the pagination program can do. Common commands are 'q' (quit) or space to go to the next page. Searching for text within a manual page --------------------------------------- Because manual pages are usually paginated using a standard pagination program such as "less" or "more", you can use all the features of the pagination program to search inside the manual page, including the search feature (usually bound to the slash key '/'). Follow the help directions in the prompt at the bottom of your screen as you read the manual page, or try "man less" or "man more" at the shell prompt. Using the "man" command ----------------------- The arguments to the "man" command must be command names or topics, e.g. $ man man $ man date $ man ls $ man intro A useful Unix start page is: "man intro" (Unix command introduction) 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.: $ man mkdir (You cannot say "man mkdir -p". You must look for "-p" in the mkdir man page.) Some man pages are incomplete ----------------------------- Some man pages are incomplete summaries of the master GNU "TexInfo" pages that are available via the "info" command. This means the man page doesn't have all the information you might need, and you'll have to use the "info" or "pinfo" commands to see the full details. This is awkward, since the "info" command is hard to use. Install and use "pinfo" if you must; this documentation format pre-dates the WWW and is awkward to navigate. 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 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 files e.g. null,fifo,zero,hd Section 5 - file formats e.g. passwd,group,resolv.conf $ man passwd # gives passwd command syntax from section 1 $ man 5 passwd # gives /etc/passwd file format from section 5 Searching for manual pages -------------------------- 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. The output of this search is not paginated, so often, if there are many results, you want to pipe the output into a pagination program such as "less". Finding a keyword (e.g. 'name') in the title lines of manual pages: $ man -k name | less The "|" character is the Unix "pipe" special character (often SHIFT-\). Finding only pages in section (1) of the manual using "grep" to search: $ man -k name | grep '(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 grep command. Finding only pages that are *not* in section (1) of the manual: $ man -k name | grep -v '(1)' | less Note the use of the "-v" option to the "grep" 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 | grep '(1)' | grep -v 'directory' | less "man -k" works the same way as the "apropos" command: $ apropos name | grep '(1)' | grep -v 'directory' | less If "less" is not available, use "more" in place of "less" to paginate large output. Make sure you protect the characters used in the grep pattern (the first argument to grep) from expansion or processing by the shell by surrounding the grep pattern (the first argument) by single quotes. Some commands have internal help -------------------------------- On the 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. -- | Ian! D. Allen - 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/