The Linux Programming Interface

1420 Appendix E

7. Overview, conventions, protocols, and miscellany: overviews of various topics, and
   various pages on network protocols and sockets programming.


8. System administration commands: commands that are for use mainly by the
   superuser.

In some cases, there are manual pages in different sections with the same name.

For example, there is a section 1 manual page for the chmod command and a sec-

tion 2 manual page for the chmod() system call. To distinguish manual pages with

the same name, we enclose the section number in parentheses after the name—for

example, chmod(1) and chmod(2). To display the manual page from a particular section,

we can insert the section number into the man command:

$ man 2 chmod

The manual pages for system calls and library functions are divided into a number

of parts, which usually include the following:

z Name: the name of the function, accompanied by a one-line description. The

following command can be used to obtain a list of all manual pages whose one-

line description contains the specified string:

$ man -k string

This is useful if we can’t remember or don’t know exactly which manual page

we’re looking for.

z Synopsis: the C prototype of the function. This identifies the type and order of

the function’s arguments, as well as the type of value returned by the function.

In most cases, a list of header files precedes the function prototype. These

header files define macros and C types needed for use with this function, as

well as the function prototype itself, and should be included in a program

using this function.

z Description: a description of what the function does.

z Return value: a description of the range of values returned by the function,

including how the function informs the caller of an error.

z Errors: a list of the possible errno values that are returned in the event of an error.

z Conforming to: a description of the various UNIX standards to which the func-

tion conforms. This gives us an idea of how portable this function is to other

UNIX implementations and also identifies Linux-specific aspects of the function.

z Bugs: a description of things that are broken or that don’t work as they should.

Although some of the later commercial UNIX implementations have pre-

ferred more marketable euphemisms, from early times, the UNIX manual

pages called a bug a bug. Linux continues the tradition. Sometimes these “bugs”

are philosophical, simply describing ways in which things could be improved, or

warning about special or unexpected (but otherwise intended) behaviors.

z Notes: miscellaneous additional notes on the function.

z See also: a list of manual pages for related functions and commands.