Getting Help
Throughout this book, the focus is on the most important and valuable flags and options for the commands covered. That's all well and good, but how do you find out about the other alternatives that might actually work better for your use? That's where the UNIX “man” pages come in. You will learn how to browse them to find the information desired.
Task 1.1: Man Pages, UNIX Online Reference
 | It's not news to you that UNIX is a very complex operating system, with hundreds of commands that can be combined to execute thousands of possible actions. Most commands have a considerable number of options, and all seem to have some subtlety or other that it's important to know. But how do you figure all this out? You need to look up commands in the UNIX online documentation set. Containing purely reference materials, the UNIX man pages (man is short for manual) cover every command available. |
To search for a man page, enter man followed by the name of the command to find. Many sites also have a table of contents for the man pages (it's called a whatis database, for obscure historical reasons). You can use the all-important -k flag for keyword searches, to find the name of a command if you know what it should do but you just can't remember what it's called. The -k option will give you a list of manual pages that refer to the keyword you specify.
 | A command performs a basic task, which can be modified by adding flags to the end of the command when you enter it on the command line. These flags are described in the man pages. For example, to use the -k flag for man, enter this: % man -k
|
The UNIX man pages are organized into nine sections, as shown in Table 1.1. This table is organized for System V, but it generally holds true for Berkeley systems too, with these few changes: BSD has I/O and special files in Section 4, administrative files in Section 5, and miscellaneous files in Section 7. Some BSD systems also split user commands into further categories: Section 1C for intersystem communications and Section 1G for commands used primarily for graphics and computer-aided design. Man pages in different sections may have the same name, so you may need to specify in which section to find the page. In addition, sometimes you'll be looking for a user-level command and find a match in section 2 or 3. Those aren't what you seek; they're specifically for UNIX programmers, as you can see in the table.
The mkdir man page is succinct and exemplary:% man mkdir MKDIR(1) DYNIX Programmer's Manual MKDIR(1) NAME mkdir - make a directory SYNOPSIS mkdir dirname ... DESCRIPTION Mkdir creates specified directories in mode 777. Standard entries, `.', for the directory itself, and `..' for its parent, are made automatically. Mkdir requires write permission in the parent directory. SEE ALSO rmdir(1) Revision 1.4.2.2 88/08/13 1 %The very first line of the output tells me that it's found the mkdir command in Section 1 (user commands) of the man pages, with the middle phrase, DYNIX Programmer's Manual, indicating that I'm running on a version of UNIX called DYNIX. The NAME section always details the name of the command and a one-line summary of what it does. SYNOPSIS explains how to use the command, including all possible command flags and options.
DESCRIPTION is where all the meaningful information is, and it can run on for dozens of pages, explaining how complex commands like csh or vi work. SEE ALSO suggests other commands that are related in some way. The Revision line at the bottom is different on each version of man, and it indicates the last time, presumably, that this document was revised.
The same man page from a Sun workstation is quite different:
% man mkdir MKDIR(1) USER COMMANDS MKDIR(1) NAME mkdir - make a directory SYNOPSIS mkdir [ -p ] dirname... DESCRIPTION mkdir creates directories. Standard entries, `.', for the directory itself, and `..' for its parent, are made automat- ically. The -p flag allows missing parent directories to be created as needed. With the exception of the set-gid bit, the current umask(2V) setting determines the mode in which directories are created. The new directory inherits the set-gid bit of the parent directory. Modes may be modified after creation by using chmod(1V). mkdir requires write permission in the parent directory. SEE ALSO chmod(1V), rm(1), mkdir(2V), umask(2V) Sun Release 4.1 Last change: 22 August 1989 1 %Notice that there's a new flag in this version of mkdir, the -p flag. More importantly, note that the flag is shown in square brackets within the SYNOPSIS section. By convention, square brackets in this section mean that the flag is optional. You can see that the engineers at Sun have a very different idea about what other commands might be worth viewing!
One thing I always forget on Sun systems is the command that lets me format a floppy disk. That's exactly where the apropos command comes in handy:
% apropos floppy fd (4S) - disk driver for Floppy Disk Controllers %That's not quite what I want, unfortunately. Because it's in Section 4 (note that the word in parentheses is 4S, not 1), this document will describe the disk driver rather than any command to work with floppy disks.
I can look up the disk command instead:
% man -k disk acctdisk, acctdusg, accton, acctwtmp (8) - overview of accounting and miscellaneous accounting commands add_client (8) - create a diskless network bootable NFS client on a server chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily,prtacct, runacct, shutacct, startup, turnacct (8) - shell procedures for accounting client (8) - add or remove diskless Sun386i systems df (1V) - report free disk space on file systems diskusg (8) - generate disk accounting data by user dkctl (8) - control special disk operations dkinfo (8) - report information about a disk's geometry and partitioning dkio (4S) - generic disk control operations du (1L) - summarize disk usage du (1V) - display the number of disk blocks used per directory or file fastboot, fasthalt (8) - reboot/halt the system while disabling disk checking fd (4S) - disk driver for Floppy Disk Controllers fdformat (1) - format diskettes for use with SunOS format (8S) - disk partitioning and maintenance utility fsync (2) - synchronize a file's in-core state with that on disk fusage (8) - RFS disk access profiler id (4S) - disk driver for IPI disk controllers installboot (8S) - install bootblocks in a disk partition pnpboot, pnp.s386 (8C) - pnp diskless boot service quota (1) - display a user's disk quota and usage quotactl (2) - manipulate disk quotas root (4S) - pseudo-driver for Sun386i root disk sd (4S) - driver for SCSI disk devices sync (1) - update the super block; force changed blocks to the disk xd (4S) - Disk driver for Xylogics 7053 SMD Disk Controller xy (4S) - Disk driver for Xylogics 450 and 451 SMD Disk Controllers %This yields quite a few choices! To trim the list down to just those that are in Section 1 (the user commands section), I use grep:
% man -k disk | grep '(1' df (1V) - report free disk space on file systems du (1L) - summarize disk usage du (1V) - display the number of disk blocks used per directory or file fdformat (1) - format diskettes for use with SunOS quota (1) - display a user's disk quota and usage sync (1) - update the super block; force changed blocks to the disk %That's better! The command I was looking for is fdformat.
 | Notice the |
character at the beginning of some of the lines in this example. This character does not appear on your screen. It's a typographical convention used in the book because the number of characters that can be displayed by UNIX on a line of your screen is greater than the number of characters that can appear (legibly) on a line in this book. The To learn a single snippet of information about a UNIX command, you can check to see whether your system has the whatis utility. You can even ask it to describe itself (a bit of a philosophical conundrum):
% whatis whatis whatis (1) - display a one-line summary about a keyword %In fact, this is the line from the NAME field of the relevant man page. The whatis command is different from the apropos command because it considers only command names rather than all words in the command description line:
% whatis cd cd (1) - change working directory %Now see what apropos does:
% apropos cd bcd, ppt (6) - convert to antique media cd (1) - change working directory cdplayer (6) - CD-ROM audio demo program cdromio (4S) - CDROM control operations draw, bdraw, cdraw (6) - interactive graphics drawing fcdcmd, fcd (1) - change client's current working directory in the FSP database getacinfo, getacdir, getacflg, getacmin, setac, endac (3) - get audit control file information ipallocd (8C) - Ethernet-to-IP address allocator mp, madd, msub, mult, mdiv, mcmp, min, mout, pow, gcd, rpow, itom, xtom, mtox, mfree (3X) - multiple precision integer arithmetic rexecd, in.rexecd (8C) - remote execution server sccs-cdc, cdc (1) - change the delta commentary of an SCCS delta sr (4S) - driver for CDROM SCSI controller termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed (3V) - get and set terminal attributes, line control, get and set baud rate, get and set terminal foreground process group ID tin, rtin, cdtin, tind (1) - A threaded Netnews reader uid_allocd, gid_allocd (8C) - UID and GID allocator daemons %One problem with man is that it really isn't too sophisticated. As you can see in the example in step 4, apropos (which, recall, is man -k) lists a line more than once if more than one man page match the specified pattern. You can create your own apropos alias to improve the command:
% alias apropos "man -k !* | uniq" % apropos cd bcd, ppt (6) - convert to antique media cd (1) - change working directory cdplayer (6) - CD-ROM audio demo program cdromio (4S) - CDROM control operations draw, bdraw, cdraw (6) - interactive graphics drawing fcdcmd, fcd (1) - change client's current working directory in the FSP database getacinfo, getacdir, getacflg, getacmin, setac, endac (3) - get audit control file information ipallocd (8C) - Ethernet-to-IP address allocator mp, madd, msub, mult, mdiv, mcmp, min, mout, pow, gcd, rpow, itom, xtom, mtox, mfree (3X) - multiple precision integer arithmetic rexecd, in.rexecd (8C) - remote execution server sccs-cdc, cdc (1) - change the delta commentary of an SCCS delta sr (4S) - driver for CDROM SCSI controller termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed (3V) - get and set terminal attributes, line control, get and set baud rate, get and set terminal foreground process group ID tin, rtin, cdtin, tind (1) - A threaded Netnews reader uid_allocd, gid_allocd (8C) - UID and GID allocator daemons %
That's better, but I'd like to have the command tell me about only user commands because I don't care much about file formats, games, or miscellaneous commands when I'm looking for a command. I'll try this:
% alias apropos "man -k !* | uniq | grep 1" % apropos cd cd (1) - change working directory fcdcmd, fcd (1) - change client's current working directory in the FSP database sccs-cdc, cdc (1) - change the delta commentary of an SCCS delta tin, rtin, cdtin, tind (1) - A threaded Netnews reader %
That's much better.
I'd like to look up one more command—sort—before I'm done here.
% man sort SORT(1) DYNIX Programmer's Manual SORT(1) NAME sort - sort or merge files SYNOPSIS sort [ -mubdfinrtx ] [ +pos1 [ -pos2 ] ] ... [ -o name ] [ -T directory ] [ name ] ... DESCRIPTION Sort sorts lines of all the named files together and writes the result on the standard output. The name `-' means the standard input. If no input files are named, the standard input is sorted. The default sort key is an entire line. Default ordering is lexicographic by bytes in machine collating sequence. The ordering is affected globally by the following options, one or more of which may appear. b Ignore leading blanks (spaces and tabs) in field com- --More-- _
On almost every system, the man command feeds output through the more program so that information won't scroll by faster than you can read it. You also can save the output of a man command to a file if you'd like to study the information in detail. To save this particular manual entry to the file sort.manpage, you could use man sort > sort.manpage.
Notice in the sort man page that there are many options to the sort command (certainly more than discussed in this book). As you learn UNIX, if you find areas about which you'd like more information, or if you need a capability that doesn't seem to be available, check the man page. There just might be a flag for what you seek.
 | UNIX was one of the very first operating systems to include online documentation. The man pages are an invaluable reference. Most of them are poorly written, unfortunately, and precious few include examples of actual usage. However, as a quick reminder of flags and options, or as an easy way to find out the capabilities of a command, man is great. I encourage you to explore the man pages and perhaps even read the man page on the man command itself. |
Task 1.2: Other Ways to Find Help in UNIX
 | The man pages are really the best way to learn about what's going on with UNIX commands, but some alternatives also can prove helpful. Some systems have a help command. Many UNIX utilities make information available with the -h or -? flag too. Finally, one trick you can try is to feed a set of gibberish flags to a command, which sometimes generates an error and a helpful message reminding you what possible options the command accepts. |
At the University Tech Computing Center, the support team has installed a help command:% help Look in a printed manual, if you can, for general help. You should have someone show you some things and then read one of the tutorial papers (e.g., UNIX for Beginners or An Introduction to the C Shell) to get started. Printed manuals covering all aspects of Unix are on sale at the bookstore. Most of the material in the printed manuals is also available online via "man" and similar commands; for instance: apropos keyword - lists commands relevant to keyword whatis filename - lists commands involving filename man command - prints out the manual entry for a command help command - prints out the pocket guide entry for a command are helpful;other basic commands are: cat - display a file on the screen date - print the date and time du - summarize disk space usage edit - text editor (beginner) ex - text editor (intermediate) finger - user information lookup program learn - interactive self-paced tutorial on Unix --More(40%)-- _Your system might have something similar.
Some commands offer helpful output if you specify the -h flag:
% ls -h usage: ls [ -acdfgilqrstu1ACLFR ] name ... %Then again, others don't:
% ls -h Global.Software Mail/ Src/ history.usenet.Z Interactive.Unix News/ bin/ testme %A few commands offer lots of output when you use the -h flag:
% elm -h Possible Starting Arguments for ELM program: arg Meaning -a Arrow - use the arrow pointer regardless -c Checkalias - check the given aliases only -dn Debug - set debug level to 'n' -fx Folder - read folder 'x' rather than incoming mailbox -h Help - give this list of options -k Keypad - enable HP 2622 terminal keyboard -K Keypad&softkeys - enable use of softkeys + "-k" -m Menu - Turn off menu, using more of the screen -sx Subject 'x' - for batchmailing -V Enable sendmail voyeur mode. -v Print out ELM version information. -w Supress warning messages... -z Zero - don't enter ELM if no mail is pending %Unfortunately, there isn't a command flag common to all UNIX utilities that lists the possible command flags.
Sometimes you can obtain help from a program by incurring its wrath. You can specify a set of flags that are impossible, unavailable, or just plain puzzling. I always use -xyz because they're uncommon flags:
% man -xyz man: unknown option `-x', use `-h' for helpOkay, I'll try it:
% man -h man: usage [-S | -t | -w] [-ac] [-m path] [-M path] [section] pages man: usage -k [-ac] [-m path] [-M path] [section] keywords man: usage -f [-ac] [-m path] [-M path] [section] names man: usage -h man: usage -V a display all manpages for names c cat (rather than page) manual pages f find whatis entries for pages by these names names names to search for in whatis h print this help message k find whatis entries by keywords keywords keywords to search for in whatis m path add to the standard man path directories M path override standard man path directories S display only SYNOPSIS section of pages t find the source (rather than the formatted page) V show version information w only output which pages we would display section section for the manual to search pages pages to locate %For every command that does something marginally helpful, there are a half-dozen commands that give useless, and amusingly different, output for these flags:
% bc -xyz unrecognizable argument % cal -xyz Bad argument % file -xyz -xyz: No such file or directory % grep -xyz grep: unknown flag %
You can't rely on programs to be helpful about themselves, but you can rely on the man page being available for just about everything on the system.
 | As much as I'd like to tell you that there is a wide variety of useful and interesting information available within UNIX on the commands therein, in reality, UNIX has man pages but precious little else. Furthermore, some commands installed locally might not even have man page entries, which leaves you to puzzle out how they work. If you encounter commands that are undocumented, I recommend that you ask your system administrator or vendor what's going on and why there's no further information on the program. |
Some vendors are addressing this problem in innovative, if somewhat limited, ways. Sun Microsystems, for example, offers its complete documentation set, including all tutorials, user guides, and man pages, on a single CD-ROM. AnswerBook, as it's called, is helpful but has some limitations, not the least of which is that you must have a CD-ROM drive and keep the disk in the drive at all times.