| CONTENTS | |
The Unix operating system was one of the first to include online documentation. It's not the best in the world most users who haven't internalized the manual set curse it once a week but it has proven surprisingly resilient. What's particularly interesting about Unix's online documentation is that, unlike other early help systems, it isn't an adjunct to another set of printed documentation that contains the "real" truth. The online manual is complete, authoritative, and usually more current than any printed documentation.
The basis for Unix's online documentation is the man command. Most simply, you use it as follows:
% man topic
where topic is usually the name of some command; but it can also be the name of a system call, a library routine, an I/O device, or an administrative file (or file type). The output from man is usually sent to a pager like more, which allows you to page through the results.
There are several command-line options for the man command that can differ based on system. For instance, to look at a command within a specific section, on a System V machine use the -s "section" option, with the following format:
% man section topic % man -s section topic
For example, if you want to read documentation about the /etc/passwd file (rather than the passwd command) on a System V machine, give the command:
% man -s 4 passwd
This is an easy way to distinguish between topics with the same name, but in different sections. For other Unix systems, such as FreeBSD, the option to search a section could be something different, such as -S.
Another useful command-line option is the -k option, which is equivalent to the apropos command. This option searches database files for matches of a given keyword, returning the results. This is particularly helpful in finding commands that contain a specific keyword if you're not quite sure what the command is.
Your system may have a configuration file for man named /etc/man.config. If it does, reading it will show you the directories in which manpages are stored, the order in which manpages are searched by default, and more. Even if you don't have an /etc/man.config file, your man command may understand the MANPATH (Section 3.21) environment variable, a list of where man should search. You can set your own MANPATH, for example, to show manpages for local versions of commands before standard versions with the same name.
Your system may also have a different manual page system: info (Section 2.9).
ML and JP
whatis is almost identical to apropos or the use of man -k (Section 2.1), but it requires a command name as an argument rather than an arbitrary string. Why is this useful? Well, let's say you forget what cat (Section 12.2) does. On my system, apropos cat gives you several screenfuls of output. You may not want to read the entire manual page. But whatis cat gives you a nice one-line summary:
% whatis cat cat (1V) - concatenate and display
The whatis command is equivalent to man -f on most systems.
Before running whatis the first time on your system particularly if you're running a standalone machine using FreeBSD, Linux, or Darwin you'll want to run the makewhatis at /usr/libexec/makewhatis, which creates the whatis database by scanning the command names from the existing manpages.
ML
The whereis command helps you to locate the executable file, source code, and manual pages for a program. I use it primarily as a sanity check; if I type cat useless.txt and get the message "cat: command not found," I immediately try whereis cat. This gives me a lot of information about what went wrong: someone may have removed cat (Section 12.2) from the system, or my PATH (Section 35.6) environment variable may be set incorrectly, etc.
Output from whereis typically looks like this:
% whereis more cat: /bin/cat /usr/share/man/man1/cat.1.gz
This says that the executable file is /bin/cat and the manual page is /usr/share/man/man1/cat.1.gz.
whereis has a few options worth mentioning:
Only report the executable name
Only report the location of the manual page
Only search for source files
Only issue a report if any of the requested information (executable, manual page, source) is missing
There are other options for modifying the list of directories through which whereis searches; if you need these, check your manual pages. In addition, the functionality and flags for whereis can differ between versions of Unix. For instance, much of the basic functionality of the command was removed in version 4.4 of FreeBSD as well as Darwin. Again, the manual pages will show you this information.
ML and SP
When the other techniques in this chapter don't find the information you want, you can try searching the online manual page (Section 2.1) files. You'll probably have to wade through a lot of stuff that you don't want to see, but this method can work when nothing else does. As an example, you remember that there's some command for chopping columns out of a file. You try man -k or apropos, but it only mentions colrm and pr, and those aren't what you want. You'll usually be able to narrow your search to one or two manual page sections (Section 2.1); here, you know that user commands are in section 1. So you go to the manual pages and do a case-insensitive search through all the files for "column" or "chop":
% cd /usr/man/man1 % egrep -i 'column|chop' * awk.1:Add up first column, print sum and average: colrm.1:colrm \- remove characters from specified columns within each line ... cut.1:.IX cut "" "\fIcut\fP \(em remove columns from file" ...
It's cut! Notice that awk also handles columns, but apropos doesn't say so.
(I cheated on that example: there were other ways to find cut using the synonym apropos field instead of apropos column, for instance. But this method does work in tougher cases.) To search the manual page files, you'll need to know where they're stored. There are lots of possibilities. If your system has an /etc/man.config file, it'll probably tell you. Otherwise, the directories /usr/man or /usr/share/man are good places to look. If the command is local, try /usr/local/man and maybe /opt (a big tree where find (Section 9.4) can help). If your system has fast find or locate (Section 9.18), try searching for man or */man*.
Your manpage files may be compressed (Section 15.6). In that case, use grep (Section 13.2) with the -Z option, grep -Z.
You'll probably find subdirectories with names like man1, man2, . . . and/or cat1, cat2, . . . Directory names like manN will have unformatted source files for section N; the catN directories have formatted source files. Or you may just find files named command.N, where N is 1 for section 1, 2 for section 2, and so on.
There are two types of manpage files: unformatted (shown in Section 3.22) and formatted. The unformatted pages are easier to search because none of the words will have embedded backspace characters. The previous example shows how. The unformatted pages have nroff commands and macros in them, though, which can make searching and reading tougher.
To search formatted pages, you'll want to strip the embedded backspace characters. Otherwise, grep might miss the word you want because it was boldfaced or underlined with backspaces in it. In the following example, a shell loop (Section 28.9) applies a series of commands to each file. First, col -b removes the overstriking. grep does a search (case insensitive, as before). Because grep is reading its standard input, it doesn't know the filename, so a little sed command adds the name to the start of every line grep outputs.
$ cd /usr/man/cat1
$ for file in *
> do col -b < $file | grep -i column | sed "s/^/${file}:/"
> done
awk.1: Add up first column, print sum and average:
...
cut.1: Use cut to cut out columns from a table or fields from each
...
If your manpage files are compressed, replace col -b < $file with:
zcat $file | col -b
In Bourne shells, you can pipe the output of the loop to a pager (like less (Section 12.3)) to see the output a screenful at a time and quit (with q) when you're done. To do that, change the last line of the for loop to:
done | less
JP
Each computer on a network needs a name. On many Unix versions, the uname -n command shows you this name. On some systems, the command hostname or uuname -l (two us, lowercase L) may be what you want. If you use more than one system, the hostname is great to use in a shell prompt or any time you forget where you're logged in.
JP
Your system may have several versions of a particular command for instance, a BSD-compatible version in one directory and a System V-compatible version somewhere else (and you might have added a private version in your own bin directory (Section 7.4)). Which command you'll get depends on your PATH (Section 35.6) environment variable. It's often essential to know which version you're using. For example:
$ type sort sort is /bin/sort
tells me exactly which version of the sort program I'm using. (On one system I've used, there were two sorts; I had also defined an alias for sort.) If I want to see all versions, bash supports a -all option:
$ type -all sort sort is aliased to `TMPDIR=/var/tmp /bin/sort' sort is /bin/sort sort is /usr/5bin/sort
A similar command is whence.
But type and whence are built into shells and are also Unix-version dependent (not all Unix systems have them), so they won't work everywhere. The which command is usually external (Section 1.9), so it works everywhere although, because it isn't built into the shells, it can't always find out about aliases defined in your current shell. For example:
% which sort /usr/bin/sort
You'll find that which comes in handy in lots of other situations. I find that I'm always using which inside of backquotes to get a precise path. (whence and type may print extra text.) For example, when I was writing these articles, I started wondering whether or not man, apropos, and whatis were really the same executable. It's a simple question, but one I had never bothered to think about. There's one good way to find out:
% ls -li `which man` `which apropos` `which whatis` 102352 -rwxr-xr-x 3 root 24576 Feb 8 2001 /usr/ucb/apropos 102352 -rwxr-xr-x 3 root 24576 Feb 8 2001 /usr/ucb/man 102352 -rwxr-xr-x 3 root 24576 Feb 8 2001 /usr/ucb/whatis
What does this tell us? Well, within this system the three commands have the same file size, which means that they're likely to be identical; furthermore, each file has three links, meaning that each file has three names. The -i option confirms it; all three files have the same i-number. So, apropos, man, and whatis are just one executable file that has three hard links.
However, running the same command in another environment, such as in Darwin, results in a different output:
117804 -r-xr-xr-x 1 root wheel 14332 sep 2 2001 /usr/bin/apropos 117807 -r-xr-xr-x 1 root wheel 19020 sep 2 2001 /usr/bin/man 117808 -r-xr-xr-x 1 root wheel 14336 sep 2 2001 /usr/bin/whatis
In Darwin, the commands are separate entities.
A few System V implementations don't have a which command.
ML, JP, MAL, and SP
Each login session has its own tty (Section 24.6) a Unix device file that handles input and output for your terminal, window, etc. Each tty has its own filename. If you're logged on more than once and other users want to write or talk (Section 1.21) to you, they need to know which tty to use. If you have processes running on several ttys, you can tell which process is where.
To do that, run the tty command at a shell prompt in the window:
% tty /dev/tty07
You can tell other users to type write your-username tty07.
Most systems have different kinds of ttys: a few dialup terminals, some network ports for rlogin and telnet, etc. (Section 1.21). A system file like /etc/ttys lists which ttys are used for what. You can use this to make your login setup more automatic. For example, most network terminals on our computers have names like /dev/ttypx or /dev/pts/x, where x is a single digit or letter. I have a test in my .logout file (Section 4.17) that clears the screen on all ttys except network:
# Clear screen non-network ttys:
` ` Section 28.14
if ("`tty`" !~ /dev/ttyp?) then
clear
endif
(Of course, you don't need to clear the terminal screen if you're using an xterm window that you close when you log out.)
JP
The who command lists the users logged on to the system now. Here's an example of the output on my system:
% who
naylor ttyZ1 Nov 6 08:25
hal ttyp0 Oct 20 16:04 (zebra.ora.com:0.)
pmui ttyp1 Nov 4 17:21 (dud.ora.com:0.0)
jpeek ttyp2 Nov 5 23:08 (jpeek.com)
hal ttyp3 Oct 28 15:43 (zebra.ora.com:0.)
...
Each line shows a different terminal or window. The columns show the username logged on, the tty (Section 2.7) number, the login time, and, if the user is coming in via a network (Section 1.21), you'll see their location (in parentheses). The user hal is logged on twice, for instance.
It's handy to search the output of who with grep (Section 13.1) especially on systems with a lot of users. For example:
% who | grep "^hal " ...where is hal logged on? % who | grep "Nov 6" ...who logged on today?
-v Section 13.3
% who | grep -v "Nov 6" ...who logged on before today?
...
The GNU who, on the CD-ROM [see http://examples.oreilly.com/upt3], has more features than some other versions.
JP
An information system gaining popularity on the more lightweight Unix-based systems is info. It's particularly relevant for finding information within Linux and FreeBSD.
Unlike man which displays all information on a topic at once, usually routed through some form of paging system such as cat info is based on a hypertext like linkage between topic components. You connect to each of the subtopics using character-based commands and typing part or all of the subtopic title at least enough to distinguish one subtopic from another.
To use info, you type the command info followed by the Unix command about which you're trying to find information. For instance, to find out more about info itself, you would use the following command line:
info info
This will return the main info introduction page and a menu of subtopics such as:
Getting Started Advanced Info Creating an Info File
To access the subtopic, you type the letter m for menu, and then in the prompt that opens at the bottom of the screen, type enough of the letters to distinguish the subtopic menu item from any other. You don't have to complete the command: you can just type enough of the letters followed by a TAB to fill in the rest. Once the subtopic menu item has been filled in, hitting ENTER sends you to the information.
To learn more about using info, you can type the letter h when you're in info and no command line buffer is showing. This brings up basic information about the info command, including the commands you use within info to use the application. These letters are summarized in Table 2-1.
|
Command |
Action |
|---|---|
|
h |
To get help on using info |
|
m |
To access a subtopic menu item |
|
n |
To get to next related subtopic |
|
p |
To get to the previous related subtopic |
|
space |
To move forward in the display if it exceeds page size |
|
delete |
To move backward in the display if it exceeds page size |
|
Ctrl-l |
To clean up the display if it gets mangled |
|
b |
To get to the first page of the display |
|
? |
To get a list of info commands |
|
q |
To quit info |
|
d |
To return to highest level of info topics |
|
mEmacsreturn |
To access the Emacs manual |
|
s |
To search for string within current node |
Note that the letter commands are case insensitive: U works the same as u.
Use the d command to pull up the Directory node, the menu of info major topics. In fact, this is a good way to become familiar with info and its contained subtopics type d and then use the menu commands to explore each of the major subtopic areas.
For instance, from the Directory Node, typing m followed by typing strings into the command buffer pulls up the strings info node.
When using the info command, if the information doesn't fit within a page, header and footer information will provide you some details about the subtopic, such as the info file, node, and the next nodes within the hierarchy. For instance, when accessing information about man, depending on your system the header reads as follows:
File: *manpages*, Node:man, Up: (dir)
This translates to the info file manpages and the node for man. Typing the u will move you up to the dir info page. Within Emacs, use mouse button two to click on and access a subtopic.
The footer provides a summary of the header information and also provides the number of lines for the topic if the topic page extends past the current screen. To see more information, type the space to page through the topic, just as you do with man.
Much of the help information within info is pulled over as is from manpages and hasn't been converted to the hypertext format of info. Because of this, the use of the m command won't pull up any subtopic. You'll need to use the space key to access the additional information.
To search within an info node/page, type s and then type the search string into the command buffer. The cursor is moved to the first occurance of the string.
SP
| CONTENTS | |