The online manual pages found in Linux provide a wealth of information. The manual pages are loosely grouped by category into the following sections:
User commands and application programs.
System calls. A complete list of system calls can be found at the end of this appendix.
Library functions—these functions do not directly invoke kernel primitives.
Devices.
File formats.
Games and demonstrations.
Special conventions and protocols, character set standards, the standard file system layout, and a variety of other miscellaneous things.
Administrative and privileged commands available only to the superuser.
Device drivers and kernel interfaces.
New.
There are a variety of ways to access manual page information. The most standard approach is to use the man utility on the command line. For example, almost every section has a manual page called intro that provides an overview of the section. To obtain the proper intro manual page for a section, the section number is passed on the command line when the man command is invoked. For example, the intro manual page for Section 2 (system calls) is specified as
linux$ man 2 intro
On the command line a manual page can be sent to the printer using the command sequence
linux$ man 2 intro | col -b | lp
In this sequence the output of the man command is piped to the col utility. This utility, when passed the -b option, filters out any backspaces and outputs only the last character written to each column position. The output of the col utility is then piped to lp for printing.
Another approach is to use the info utility. This program, which is a document-reading utility, helps to facilitate manual page navigation and access to related topics. The command line sequence
linux$ info info
brings up the manual page on the info utility. On our Linux system this brings up the following screen.
File: info.info, Node: Top, Next: Getting Started, Up: (dir) Info: An Introduction ********************* Info is a program, which you are using now, for reading documentation of computer programs. The GNU Project distributes most of its on-line manuals in the Info format, so you need a program called "Info reader" to read the manuals. One of such programs you are using now. If you are new to Info and want to learn how to use it, type the command 'h' now. It brings you to a programmed instruction sequence. To learn advanced Info commands, type 'n' twice. This brings you to 'Info for Experts', skipping over the 'Getting Started' chapter. * Menu: * Getting Started:: Getting started using an Info reader. * Advanced Info:: Advanced commands within Info. * Creating an Info File:: How to make your own Info file. * Index:: An index of topics, commands, and variables.
Entering the letter h at this first screen displays the basics of how to use this utility. Entering the letter q quits (exit) the info utility.
Even another approach is to use xman, the X Window System manual browser. For example, on our Linux system entering the command sequence
linux$ setenv MANPATH /mit/kit/man:/usr/share/man linux$ xhost+ linux$ xman &
assigns the environment variable MANPATH (used by xman) the directory locations to be searched,[1] disables access control (allowing X Window clients to connect from any host), and invokes xman, placing it in the background. On the client a small X Window similar to the one below is displayed.
Selecting [Help] displays a window with online help, [Quit] terminates service, and [Manual Page] displays a window containing a manual page browser. Entering [Ctrl] + [S] after selecting [Manual Page] generates a text entry box where the name of a specific command can be entered.
The file /etc/man.config is a text based file that holds the default customization specifications for the man utility. Contained in this file are a variety of uppercase identifiers which are assigned values. These identifiers parallel corresponding environment variables used by the man utility. The values assigned to the identifiers in the man.config file act as the default values if the corresponding environment variable has not been set. Aside from MANPATH another item of passing interest is the value assigned to MANSECT. MANSECT stipulates which manual sections are to be searched and their order. On our system when initially configured MANSECT is set to:
MANSECT 1:8:2:3:4:5:6:7:9:tcl:n:l:p:o
This is fine from an administrative viewpoint. However, if you are doing a great deal of programming you might want to change the default order by moving section 8 (administrative and privileged commands) further back in the sequence and placing section 2 (system calls) and 3 (library functions) nearer the front. One such rearrangement would be:
MANSECT 3:2:1:4:5:6:7:8:9:tcl:n:l:p:o
Individual manual pages, as viewed with the man command, follow a somewhat standard format. A typical manual page (perror found in Section 3) is shown below.
PERROR(3) Library functions PERROR(3) NAME perror - print a system error message <-- 1 SYNOPSIS #include <stdio.h> void perror(const char *s); <-- 2 #include <errno.h> const char *sys_errlist[]; int sys_nerr; DESCRIPTION The routine perror() produces a message on the standard error output, de- scribing the last error encountered during a call to a system or library function. First (if s is not NULL and *s is not NUL) the argument string s is printed, followed by a colon and a blank. Then the message and a new- line. <-- 3 . | . | . <-- 3 that errno is undefined after a successful library call: this call may well change this variable, even though it succeeds, for example because it in- ternally used some other library function that failed. Thus, if a failing call is not immediately followed by a call to perror, the value of errno should be saved. CONFORMING TO ANSI C, BSD 4.3, POSIX, X/OPEN <-- 4 SEE ALSO strerror(3) <-- 5 <-- 6 2001-12-14 PERROR(3)
(1)A brief summary-often is the same information returned by the
aprosorman-kcommand.(2)Syntactical information—include files, external variables, function prototype, function return data type, parameter data types, and so on. This is a key section. Special attention should be paid to arguments passed as a reference.
(3)A detailed narration of what this system call or library function does.
(4)As provided, the standards this system call or library function meets.
(5)Other related system calls and/or library functions.
(6)Last update .
Across the top of the manual page is a title line. Following the title line is a series of subdivisions delineated by uppercase labels. The subdivisions common to most (but not all) system call sand library function manual pages are
NAME | The name of the item is followed by a brief description. The description is often similar to, if not the same as, the description returned when a linux$ man -k pipe fifo (4) - first-in first-out special file, On most systems, |
SYNOPSIS | This provides the syntactical information for the correct use of the item. In the case of a system call or library function, the requisite include file(s), external variables referenced, and prototype are given. The data type of the return value of the system call or library function can be obtained from the prototype definition. For example, the manual page for the #include <stdio.h> void perror(const char *s); #include <errno.h> const char *sys_errlist[]; int sys_nerr; This indicates that to use |
DESCRIPTION | This subdivision contains a detailed narration of what the system call or library function does. |
RETURN VALUE | The value(s) the system call or library function returns and how to interpret them. The RETURN VALUE entry should indicate whether or not |
CONFORMING TO | The standard(s) to which the system call or library function conforms. Typically the standards are abbreviated, such as SVr4, SVID, POSIX, X/OPEN, or BSD 4.3. On occasion a specific option for compilation and/or the definition of a specific constant (such as _GNU_SOURCE) is noted. |
ERRORS | When present (i.e., |
FILES | Files accessed or modified by the system call or library function. |
SEE ALSO | Other items of interest, such as related system calls or library functions. |
NOTES | A catchall containing additional pertinent information that does not fall into any particular category. |
LINUX NOTES | Notes specific to the Linux implementation. |
AUTHORS | A list of authors (often with their email address). |
[2] The | |
named pipe
funzip (1) - filter for extracting from a ZIP
There are several other manual page divisions that surface on an infrequent basis. These, like those above, are usually self-explanatory (e.g., OPTIONS, EXAMPLE, BUGS, HISTORY, WARNINGS, DIAGNOSTICS, etc.). On occasion, small flashes of self-deprecating humor are encountered. The following is from the manual page on the system command tune2fs (used for tuning a second extended file system in Linux) “We haven't found any bugs yet. That doesn't mean there aren't any....” Unfortunately, as things become more standardized, such frivolities are becoming less common.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[1] Things get a bit dicey here as they vary somewhat from system to system. Check the file /etc/man.config for specifics about the content of the MANPATH variable. In any case, when using xman, be sure to add /mit/kit/man to the directories to be searched.