A.2. Manual Page Format
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 void perror(const char *s); <-- 2 #include 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 apros or man -k command.
(2) Syntactical informationinclude 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 man -k (know) query for a specific topic is made. [2] The man -k pipe command returns all manual page summaries for any item (system call, library function, etc.) that contains the term pipe . For example, linux$ man -k pipe fifo (4) - first-in first-out special file, named pipe funzip (1) - filter for extracting from a ZIP archive in a pipe IO::Pipe (3pm)- supply object methods for pipes mkfifo (1) - make FIFOs (named pipes) mkfifo (3) - make a FIFO special file (a named pipe) open (n) - Open a file-based or command pipeline channel perlipc (1) - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores) pipe (2) - create pipe On most systems, man -k is equivalent to using the apropos utility, (i.e., man -k pipe returns the information as apropos pipe ). |
|
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 perror library function has the following SYNOPSIS: #include void perror(const char *s); #include const char *sys_errlist[]; int sys_nerr; This indicates that to use perror , the header file stdio.h must be included. The perror call accepts a single argument, s , which is a pointer to a constant of type char . The return value for perror is of type void , indicating it does not return a value. Additionally, the SYNOPSIS indicates that if we want to make use of the external list of errors referenced by sys_errlist or the external variable sys_nerr (that has the number of possible errors), we should include the file errno.h . Be sure to note arguments that are pointers (references). These arguments must reference the correct data type (e.g., char , int , etc.). If information is to be passed to the system call or library function, the referenced object must be set to the proper initial value. In addition, if information is to be returned via the reference, the programmer must allocate sufficient space for the referenced item prior to the call. |
|
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 errno is set. |
|
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., errno is set), this entry lists the error codes generated by the system call or library function if it fails. A short explanation of how to interpret each error code is given. |
|
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 -k command option for man uses the windex database, which is created by running the catman program. If the system administrator has not run this program, or the windex database is out of date, the -k option for man will not work correctly.
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.