Unix™ Systems Programming [Electronic resources] : Communication, Concurrency, and Threads نسخه متنی

A.1 Manual Pages

The programs in this book are based on the Single UNIX Specification, Version 3. We refer to this specification by its IEEE name, POSIX. Essentially identical documents have been published by three standards organizations, the IEEE [49, 50, 51, 52], ISO/IEC [57], and the Open Group [89]. The IEEE and ISO/IEC publish print and electronic versions of the standard that are available for a fee. The Open Group publishes the standard on CD-ROM, but this organization also makes the standard freely available on their web site, http://www.UNIX-systems.org/single_unix_specification/. You must register the first time you enter the web site, but it is open to the public at no charge. The standard is organized into the following four parts.

1. Base Definitions: general terms and concepts, header files

2. System Interfaces: definitions of functions

3. Shell and Utilities: definitions of commands

4. Rationale: discussion of historical information and why features were or were not included in the standard

Use section 2 of the standard to find out about system calls and library functions such as pipe and socket. Look in section 3 for information about commands, such as ls and cat, that can be executed from the shell.

Most UNIX systems have online documentation called the man pages. Here, "man" stands for "manual" as in system manual. The man utility displays these pages of online documentation in a readable format.

SYNOPSIS
man [-k] name
POSIX:Shell and Utilities

Unfortunately, the standard does not require much functionality from the manual facility. If name is a standard utility, the standard requires only that a message describing its syntax, options and operands be displayed. The -k option lists the summaries of manual entries that contain name.

Most UNIX implementations divide the manual pages into sections, with typical section numbers shown in Section 4.2. Most implementations of man provide an option called -a to display all manual entries and an option called -s or -S to display only entries from a given section for the manual.

Example A.1

The following command can be used under Solaris to display the manual entry for write from section 2.

man -s 2 write

Under Linux or Mac OS X the corresponding command is the following.

man -S 2 write

Figure A.1 shows the typical output of the man utility when the man tee command executes. The first line or header line of the man page gives the name of the command followed in parentheses by the man page section number. The tee(1) in Figure A.1 refers to the tee command described in section 1 of the man pages. Do not try to execute tee(1). The (1) suffix is not part of the command name, rather it is a man page section indicator.

Figure A.1 Typical man page listing for the tee command.

tee(1)                    User Commands                   tee(1)
NAME
tee - duplicate standard output
SYNOPSIS
tee [ -ai ] [ file ... ]
DESCRIPTION
The tee utility shall copy standard input to standard
output, making a copy in zero or more files. The tee utility
shall not buffer output. The options determine if the
specified files are overwritten or appended to.
OPTIONS
The following options shall be supported.
-a Append the output to the files rather than overwriting them.
-i Ignore the SIGINT signal.
OPERANDS
The following operands are supported:
file  A pathname of an output file. Processing of at least
13 file operands shall be supported.
ENVIRONMENT VARIABLES
...
EXIT STATUS
The following exit values are returned:
0     The standard input was successfully copied to all output files.
>0 The number of files that could not be opened or whose
status could not be obtained.
APPLICATION USAGE
The tee utility is usually used in a pipeline, to make a
copy of the output of some utility.
The file operand is technically optional, but tee is no more
useful than cat when none is specified.
EXAMPLES
Save an unsorted intermediate form of the data in a pipeline:
... | tee unsorted | sort > sorted
SEE ALSO
cat(1), attributes(5), environ(5)

Each man page covers some aspect of UNIX (e.g., a command, a utility, a library call). The individual man pages are organized into sections like the tee man page of Figure A.1. Some common section titles are given in Table A.2.

The name section of a man page lists the names of the items described on that man page. The man pages contain information about many types of items. The man page on write(1) describes a command, and the man page on write(2) describes a library function. The two write entries have completely different purposes. Look at the synopsis section to determine which write you want. The synopsis summarizes how a command or function is invoked. The synopsis for a library function has function prototypes along with the required header files. The write(2) function is called from a C program. In contrast, write(1) is executed from the command prompt or from a shell script.

In addition to the standard documents and manual pages, many UNIX vendors make detailed documentation accessible through the Web. Sun provides documentation at http://docs.sun.com. The Linux Documentation Project web page, http://tldp.org/, has the Linux manual pages, HOWTO guides and other information. Apple provides documentation for Mac OS X on their developer's web site, http://developer.apple.com.