A guide to discovering documentation (and other valuables) on your Linux system.
So, you decided to see what all the fuss was about. You installed Linux, logged in to your own Unix machine, and are ready to race. Hmmm, strange prompt:
george:~#
It's not quite C:>: but it can't be that hard. You put in a floppy disk and type:
george:~# dir a: ls: a:: No such file or directory
The commands and output of commands in this article assume you are using the bash shell. Also, you do not type in the prompt.
“I wonder how you look at floppies?” You type help at the prompt and get a screen full of cryptic command templates. Nothing on dir though. Ah! There in the second column it is—dirs. “No problem,” you think, as you confidently type:
george:~# dirs a:
...and get dirs: unknown option: a:. “Oh, that's right,” you mutter, “Unix doesn't have a: and c: drives. help again, and let's have a closer look. Here we go, it says: help [pattern...] so you enter:
george:~# help dir dirs: dirs [-l] Display the list of currently remembered directories. Directories find their way onto the list with the `pushd' command; you can get back up through the list with the `popd' command. The -l flag specifies that `dirs' should not print shorthand versions of directories which are relative to your home directory. This means that `~/bin' might be displayed as /homes/bfox/bin
Getting a bit puzzled now you try:
george:~# dir total 1 lrwxrwxrwx 1 root root 8 Aug 2 21:39 INSTALL -> /var/adm/ lrwxrwxrwx 1 root root 14 Aug 2 21:39 linux -> /usr/src/linux/ drwx------ 2 root root 1024 Aug 3 18:05 mail/
Phew, something works. What does it all mean though? Different colours, arrows, your login name is there twice on each file and you still don't know how to list what's on a floppy. In fact, you're starting to wonder why you thought this Linux thing was a good idea in the first place.
If Linux is your first foray into the Unix world then you're at a bit of a disadvantage compared to starting out on a commercial system: no manuals. Fortunately, Unix has a long history of carrying its documentation on-line. In fact, the first system I worked on, about eleven years ago, normally shipped with only the vendor-specific manuals in printed form and the majority of the documentation on-line. So here's a few tips on how to discover what you need to know without a set of printed manuals. A whistle-stop tour of man, apropos, whatis, more or less, ls and find. Where to look for information on Usenet other than comp.os.linux.help and where to look for information off Usenet, as well as in Linux Journal.
First stop is the helpful trinity of man, apropos and whatis. The most essential of these three is man. man is your access to the on-line manual set. apropos is a keywork searching tool for the manual set, and whatis is a quick reference to commands. man also has the ability to do both the keyword searching of apropos and the quick reference of whatis.
The best way to start is to try typing:
george:~# man man
which is asking the on-line manual for the manual page on itself. The header of the ”man“ man page has ”man(1)“ followed by a NAME entry, a SYNOPSIS entry and then the description. The NAME entry gives the name and a short description of the things explained on this man page. The SYNOPSIS is a template for running the command which shows the required format, the options, and the parameters. The DESCRIPTION entry is the detailed description of the command, its calling conventions, options, parameters, and other details. Near the end of the man page are two very useful sections, the SEE ALSO and where appropriate the FILES section. The SEE ALSO section lists other man pages which are relevant to the one you have just looked up. The FILES section lists files which are relevant to the command you are looking at, for instance, configuration files.
There are three very useful options to the man program. They are -a, -f, and -k. The -a option tells the man program to not stop looking for pages at the first one it finds, but to scan all the man page sections and present you with all the relevant pages. You're probably now wondering what those sections are and why they exist. The man pages themselves can help us out with that one.
If you recall, when you typed man man the resulting man page was headed ”man(1)“. This means the page was found in section one of the manual. If you now enter:
george:~# man -a man
you will be presented with the ”man(1)“ man page again. Now type q to leave the man page viewer. Instead of being put back to the prompt, you will be given another man page to view, which is headed ”man(7)“. This is a description of the way to create man pages and is from section seven. On about the third screen of ”man(7)“ is a list of the various man sections. If you knew that you just wanted to see the page on how to create man pages, you could bypass the ”man(1)“ page by entering:
george:~# man 7 man
If you remember the name of a command but can't remember what it does, the whatis command (or man -f) is what you need. These commands search a special ”whatis“ database and return a list of matches with a short description.
george:~# whatis man man (1) - Format and display the on-line manual pages man (7) - Macros to format man pages man.config (5) - Configuration data for man
In this case, it also got us a pointer to another man-related man page on which we can do a man man.config or man 5 man.config.
Often you'll know what you want to do, but won't know the command name. To do a keyword search of the ”whatis“ database, you can use either the apropos command or man -k. For example, to find out how to copy a file, neither man copy nor whatis copy are of any help. Using either apropos copy or man -k copy returns 22 lines of matches, including the entry cp(1) - Copy files.
Another valuable way of finding information is to ”cruise the filesystem“. The tools you need are cd, ls, and either more or less. Another valuable little helper is the command find.
What do I mean by ”cruise the filesystem“? It just means to look through the filesystem for interesting files, reading any text files, and looking at the man pages for any executable files. You use ls to list the files and directories, cd to move into interesting looking directories, and the pager programs more and less to read any text files. So on my system I can cd /usr and one of the directories which I see in the ls output is called doc. When I do an ls doc, I see one of the directories is faq. I do an ls doc/faq and see one of the directories is called howto. An ls of the howto directory shows me that it's got a collection of Linux HOWTO documents. I cd /usr/doc/faq/howto and then I can, for example, more README or less Mail-HOWTO.
What about executables? Let's take an example a friend of mine had. He was having a look around when an ls /bin came up with a program called dialog. Thinking it looked interesting, he did a man dialog and found it was a program for creating dialog boxes for use in shell scripts. About three days later a Linux Journal arrived with an article on dialog boxes. I still want to know why my copy of man doesn't automatically cause Linux Journal articles to be written.
One important caveat about cruising a filesystem: don't randomly execute programs. Murphy's Law indicates that only data that's important and hard to replace will be lost when you try some innocuous-looking program. Find and read the man pages before trying the program. If there are no man pages, then look for other documentation. Use the find command to help you search for more information; it is a powerful and flexible command, allowing you to do searches through a filesystem on a number of file attributes. I'll just give you an example of searching by name. I can look for any filenames with the string readme in them and print the names on my screen with the following construct:
george:~# find / -iname `*readme*' -print
where find is the command, / is the place to start the search, -iname means do a case-insensitive filename search on the following string (*readme*) and -print means to display the result. If I were doing a case- sensitive search, I would replace -iname with -name.
Why don't I just do all my looking with the find command? You build a better roadmap of your system by walking the directories, and you find things you didn't know to search for. How can you get find to search for the HOWTO documents when you don't know such documents exist?
A warning on the Linux documentation: all the documentation is provided by volunteer efforts and, since many people find writing documentation not as much fun as writing programs, inevitably there will be times when the on-line documentation isn't complete. There may be a program without a man page or other documentation. The documentation may be out of date, or there may be inaccuracies. So be prepared for some inconsistencies. Another thing to be aware of is that the placement of files in a distribution is entirely up to the person creating the distribution. Where they think the files should be, which is how it's documented in the man page, may not be where they actually are in your distribution. The name of the file is unlikely to have been changed, so it's simple enough to use find to resolve such differences.
Programs for which there are no man pages aren't so simple. However, Linux is a type of Unix. There are many books published on Unix and most of those would be relevant to a Linux system. There are books on learning to use Unix, Unix reference books, and Unix system administration books from publishers such as O'Reilly and Associates, The Waite Group, and others. In addition I would strongly recommend one of SSC's Unix command summaries. These summaries are like having your ”whatis" database extended to include both the synopsis and the options from the man page and to have them printed out.
If you have access to Usenet news, then you probably already look at one or more of the Linux discussion groups. In addition to those groups, there are many other Unix discussion groups in the comp.unix hierarchy. There are regular postings to news.answers of many Unix FAQs (Frequently Asked Questions); in particular, there is a Unix books FAQ. There are newsgroups on news readers (news.software.readers), on editors (comp.editors, comp.emacs), on mail (comp.mail hierarchy), and many other topics, so don't limit yourself to just the comp.os.linux groups.
Oh, and if you still can't get that directory listing on your A: drive, here's a hint: man mount.
