command.

Team-FLY

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 .

Base Definitions: general terms and concepts, header files
System Interfaces: definitions of functions
Shell and Utilities: definitions of commands
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 Table A.1. The first three sections are of most interest to us. Most implementations of man display only the information about the first occurrence of an entry. For example, write of section 1 is a command that can be executed from the shell to send a message to a terminal of another user . Users of this book would probably be more interested in the write description of section 2, which is the library function described 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.

Table A.1. Typical sections numbers for UNIX man pages.

section	contents
1	user commands
2	system calls
3	C library functions
4	devices and network interfaces
5	file formats
6	games and demos
7	environments, tables and `troff` macros
8	system maintenance

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.

Table A.2. Typical sections of a UNIX man page.

section title	contents
`HEADER`	title for the individual man page
`NAME`	one-line summary
`SYNOPSIS`	description of usage
`EXIT STATUS`	values returned on exit from a command
`DESCRIPTION`	discussion of what the command or function does
`RETURN VALUES`	possible return values
`ERRORS`	summary of `errno` values and conditions for errors
`FILES`	list of the system files that the command or function uses
`SEE ALSO`	list of related commands or additional sections of the manual
`ENVIRONMENT`	list of relevant environment variables
`NOTES`	information on unusual usage or implementation features
`BUGS`	list of known bugs and caveats

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.