While they're not all well-advertised, there are actually a variety of means of getting
help under Unix. The most important and reliable of these are `man'
pages. Man pages correspond to online manuals for programs, file formats, functions,
system calls, and so forth. You might have asked a UNIX question on a newsgroup only
to get back as a reply RTFMP ( Read The "Fantastic" Man Pages ). If you've
never read one before, the best way to start is by typing 'man man' at
the command line.
Of course, while man pages are a vast improvement over the online
documentation of most other OSes, they suffer from many failings:
That said, they're still better and more comprehensive than the alternatives. We'll try to address the first three failings in this document.
Man pages are the standard documentation for every Unix; you're sure to come across a reference before too long of the form:
<command>(N)
Where N is a number from 1-9, possibly followed by a letter. Here's an example we'll pick apart ( note: this example does not apply to all UNIX's but should be taken as general form )
% 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)
Here's the breakdown of our example.
MKDIR(1) USER COMMANDS MKDIR(1)
This means that the MKDIR command is
documented under that name, in section (1) given within
parentheses.
The section may be necessary in case there are multiple man pages for the same name. In
the example above there are man pages called 'mkdir' in both sections (1) and (2v). If
unspecified, man will give you the first manpage it finds. The -f
option will show you all the available man pages for a given name.
The same effect can be achieved by using the command whatis
instead of man
%whatis mkdir
AND
%man -f mkdir
are synonymous. You should be able to get a description of each section (they vary from Unix to Unix) by doing
%man SECTION# intro
Continuing with the breakdown of the mkdir man page.
NAME mkdir - make a directory
The name of the command and a brief description.
SYNOPSIS mkdir [ -p ] dirname...
This discribes the various flags and the proper format the command requires. The flag in this instance is -p and the syntax requires a directory name to follow. ( note: most flags are optional )
DESCRIPTION mkdir creates directories. Standard entries,`.', for the directory itself, and `..' for its parent, are made automat-ically...
A full fledged description of what the command will do including all of the flags.
SEE ALSO chmod(1V), rm(1), mkdir(2v), umask(2V)
Suggestions of other commands that are somehow related.
apropos / man -k / man -kr
One invocation of man that you'll likely come to be very familiar with is the man
-k (keyword) option. This function is also available by
running apropos (1), i.e. man -k and apropos
are equivalent. It lets you search the database of man page summaries to look for a
keyword
that might be mentionned in them.
Suppose we were looking for utilities to manipulate postscript documents. We
would either do
%man -k postscript
or
%apropos postscript
This produces a list, with summaries, of man pages which are likely to be related to your topic. If you were looking for something less specific, say programs associated with databases, you would probably want to use less and/or grep to filter and view the output.
%man -k postscript | less
The output may produce many screens of data.
Note, these commands search the database which in most cases must be built by the system administrators, a task which is sometimes forgotten. If you can't find what you are looking for and you believe it's there, try doing
%man -u man
under Linux followed by your search, or
%man -F
under Solaris. SunOS has no such option. Before trying this, make sure your
MANPATH variable is set correctly.
There can be several hierarchies of man pages, depending on the system. On most of our
systems, at least the following directories exist: /usr/man, /usr/local/man. In addition,
there will be one for X programs (/usr/X11/man, /usr/local/X11/man, or /usr/openwin/man)
and likely one for SOCS-specific man pages (/usr/socs/man).
man searches the environment variable MANPATH (a
colon-seperated list of directories like the PATH variable) for man pages. If you
have hacked your script files or staff screwed up, the MANPATH could be wrong. The command
whereis may be able to help here. whereis will locate
the binary, source and manual page files for a command. For example: ( note: this
specific example should not be taken as generic under Unix but only as a illustration of
possible results )
%whereis man
Alternatively, you can just try the quick-and-dirty method of running grep (1) in the man directories you think might contain the command you are looking for; note that man pages are not stored in plain text format so the output may not be always readable. If you find the string you are looking for in a file located in MANDIR/man#, do
%man -M MANDIR # filename
to view the corresponding man page.
Ok, you have tried the suggestions given above to locate man pages, and still have not
had any luck. It's quite possible there is no man page corresponding to what you're
looking for - either because the tool or functionality you're searching for isn't
installed on the system or because it has no man page installed (the latter is far more
common under Linux than elsewhere).
Let's suppose that you're especially determined because you "know"
that the command exists - it does something, just not quite what you want. Rather than get
irate at the undocumented command, first make sure that it is actually a program that
deserves a man page; here's an algorithmic approach to looking for a command's help file.
If you're running ksh or bash (you'll know if you are),
first do
%type -t CMD
For any other shell, do
%which CMD
This will tell you what kind of command you're dealing with.
If it says CMD is a 'builtin', then do 'help CMD' (bash only) or
read your shell's manual page. ~(Note that tcsh - except under Linux - doesn't document
all of its builtins since most are identical to csh's; I suggest looking in csh's man page
first if you are somewhere other than Linux-land.)~
If you're told that CMD is an 'alias', then do
%alias CMD
and repeat this procedure from the beginning with the first word that alias returns. If
you are told that CMD is a function ( not in csh ), do
%typeset -f CMD
to see its definition; from there you are on your own.
If you are given a path, then you may be justified in being irate. Or maybe the
documentation is in another format; keep reading.
You have a couple of options here, depending on whether you mind wasting a full page of
paper for each page of text. We recommend printing man pages at least half-size, as you're
unlikely to return to them a month later.
The simplest thing and most portable to do (though alternatives exist) is
%man -t MANPAGE > Manpage.ps
( Note: only works unaided under Linux )
This will produce a file called Manpage.ps in your current directory, which you can
then use psnup (1) under SunOS to print 2- or 4- pages to a physical
page.
Unfortunately, while the -t parameter is itself portable to virtually all
man implementations, the output is not. Under Linux, the above works fine. Under
SunOS and Solaris, you have to do some preparation first: define the environment variable TCAT
to be 'cat' and TROFF to be '/usr/local/bin/groff -man'. Furthermore, the
GROFF_TYPESETTER variable must be set to 'ps'.
If you have trouble getting psnup to work or don't feel like fooling around with it, you
can always work with text instead. This isn't ~quite~ text, as it still has bolding and
underlining and so forth, but a2ps(1) understands it, as does less(1).
%man MANPAGE|a2ps -m >MANPAGE.ps
You don't have to produce the ps file if you don't like, of course - if you're confident
that it'll work the first time, replace the '>MANPAGE.ps' with '|lpr -Pprinter-name'.
Personally, I recommend previewing the output with ghostview (1)
beforehand.
Not all documentation is located in the manpages. The shells sometimes have online help, as do various other programs, especially graphical ones.
Other major online help systems include:
Info isn't really complex enough to deserve describing in detail. In brief, you can read
info pages within emacs using 'C-h i' ('info') or from
the command line using the command
% info
Online help and a tutorial on the info system are available from within both interfaces. Don't discount info pages; although they are used mainly by GNU software, this includes such hugely useful info pages as gdb, gcc, emacs, gawk, and make. Perl and bash also have info pages, though the information is available by other means as well in their cases.
Only available under Linux, and often not terribly interesting, as a well-behaved package will provide documentation that can be integrated with the major help systems. Still, there is a lot there, and should definitely be considered if you cannot find what you are looking for elsewhere. Of particular interest are the docs for xv, debian, vim, wget, pqp, pine, libq++ and hsc.
Files contained here will generally be of three types: HTML, postscript, or plan text ( ASCII ). We will make the assumption that you know how to deal with these formats. Use the information in this document to find help and read up on lynx(1), ghostview(1), and less(1)
These are more common to the servers, though they may exist on Linux machines as well. Software packages are commonly installed into
/usr/local/pkgs/PKGNAME-VER#
and a link to that directory is created as
/usr/local/pkgs/PKGNAME
Sometimes there is documentation to be found there. Documentation which is located in /usr/doc/PKGNAME on Linux will be in these directories on the servers, though they may get linked or copied into the other directories mentionned above ( /usr/local/doc, /usr/share, /usr/local/share )
Much Perl documentation is embedded with the source modules themselves. To access it, you can usually do
%perldoc MODULENAME
and a man page will be generated for you.
While it should probably be a last resort, the source IS always the most current and sometimes the only documentation available for a particular package. This is usually not installed on the system unless it cannot be compiled: For example, Perl scripts and Lisp source are both interpreted, and so the program is the source. Whether or not the program you are trying to learn more about is written in a compiled or interpreted language./usr/include and /usr/local/include may have very useful files to help.