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.

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.

man -s 2 write

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.

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.

The C compiler, cc, translates a collection of C source programs and object files into either an executable file or an object file. On your system, the compiler may have another name, such as gcc. The cc command may be a symbolic link to another executable.

Compilation proceeds in stages. In the first stage, a preprocessor expands macros and includes header files. The compiler then makes several passes to translate the code, first to the assembly language of the target machine and then into machine code. The result is an object module, which has machine code and tables of unresolved references. The final stage of compilation links a collection of object modules together to form the executable module with all references resolved. An executable file is ready to be loaded and run. The executable contains exactly one main function.

cc -o mine mine.c

void serr(char *msg);

int main(void) {
   serr("This program does not do much
");
   return 0;
}

cc -o mine mine.c minelib.c

cc -c mine.c

cc -o mine mine.o minelib.o

cc -o mystuff my.c mylib.c
mystuff

#include <stdio.h>
static int num;
void changenum(void);

#include "myinc.h"
int main (void) {
   num = 10;
   changenum();
   printf("num is %d
", num);
   return 0;
}

#include "myinc.h"
void changenum(void) {
   num = 20;
}

#include "myinc.h"

cc -o mylog mylog.c -lm

cc -o my my.o -lm mylib.o

#ifndef ETIME
#define ETIME ETIMEDOUT
#endif

cc -D_GNU_SOURCE -o myprog myprog.c

#define _GNU_SOURCE 1

#ifndef REENTRANCY
#define REENTRANCY_NONE
#endif

#if REENTRANCY==REENTRANT_NONE
   /* default code using gethostbyname and gethostbyaddr */
#elif REENTRANCY==REENTRANT_R
   /* code using gethostbyname_r and gethostbyaddr_r */
#elif REENTRANCY==REENTRANT_MUTEX
   /* code using mutex locks */
#elfi REENTRANCY==REENTRANT_POSIX
   /* code using getnameinfo and getaddrinfo */
#endif

cc -DREENTRANCY=REENTRANT_POSIX -o client client.c restart.c uiciname.c uici.c

The make utility, which allows users to incrementally recompile a collection of program modules, is convenient and helps avoid mistakes. To use make, you must specify dependencies among modules in a description file. The make utility uses the description file to see if anything needs updating.

The description file specifies dependency relationships that exist between targets and other components. Lines starting with # are comments. The dependencies in the description file have the following form.

target:          components
TAB              rule

The first line is called a dependency, and the second line is called a rule. The first character on a rule line in a description file must be the TAB character. A dependency may be followed by one or more rule lines.

The default description filenames are makefile and Makefile. When the user types make with no additional arguments, the make utility looks for makefile or Makefile in the current directory to use as its description file.

mine:   mine.o minelib.o
        cc -o mine mine.o minelib.o

Figure A.2. A dependency graph for the makefile of Example A.18.

my:     my.o mylib.o
        cc -o my my.o mylib.o

my.o:   my.c myinc.h
        cc -c my.c

mylib.o:  mylib.c myinc.h
        cc -c mylib.c

NAME = value

Whenever $(NAME) appears in the description file, make substitutes value before processing. Do not use tabs in macros.

OPTS = -g

my:     my.c  my.h
        cc $(OPTS) -o my my.c

make my

make -f mymake target1

This section discusses the lint utility, debuggers, the truss utility and profiling.

lintall:
           lint my.c mylib.c > my.lint

implicitly declared to return int:
    (14) strtok

(5) warning: variable may be used before set: p

char *p;
scanf("%s", p);

cc -g -o my my.c

dbx my

(dbx)

unable to open file

truss dvips -f t.dvi |& grep psfonts.map

open("./psfonts.map", O_RDONLY, 0666)         Err#2 ENOENT
open("/usr/local/tex/dvips/psfonts.map", O_RDONLY, 0666) Err#2 ENOENT

Programmers are often confused about the meaning of the keyword static, in part because C uses the word two different ways. The main points to remember are the following.

These rules are based on C’s notion of scope of an identifier and linkage, which we now discuss.

According to the ISO C standard, “An identifier can denote an object; a function; a tag or member of a structure, union, or enumeration; a typedef name; a label name; a macro name; or a macro parameter.” [56, section 6.2.1] Here, we mainly discuss identifiers that are associated with variables and functions.

An identifier can be used only in a region of program text called its scope. If two different entities are designated by the same identifier, their scopes must be disjoint, or one scope must be completely contained in the other. In the inner scope, the other entity is hidden and cannot be referenced by that identifier.

The scope begins at the identifier declaration. If the declaration occurs inside a block, the identifier has block scope and the scope ends at the end of the block. If the declaration occurs outside any block, the identifier has file scope, and the scope ends at the end of the file in which it is declared.

Identifiers declared more than once may refer to the same object because of linkage. Each identifier has a linkage class of external, internal or none. Declarations in a program of a particular identifier with external linkage refer to the same entity. Declarations in a file of a particular identifier with internal linkage represent the same entity. Each declaration of an identifier with no linkage represents a unique entity.

An identifier representing a function has external linkage by default. This means that it can be referenced in any file of the program. Referencing it in a file other than the one in which it is defined requires a function prototype. You can hide a function from other files by giving it internal linkage, using the static qualifier.

An identifier representing an object (such as a variable) has a linkage class related to its storage class, also called storage duration. The storage duration determines the lifetime of the object, the portion of the program execution for which storage is guaranteed to be reserved for the object. There are three storage durations: static, automatic and allocated. Allocated objects have a lifetime that begins with a successful malloc or related function and ends when the object is explicitly freed or the program terminates. The lifetimes of other objects are determined by the declaration of the corresponding identifier.

An identifier of an object declared outside any block has static storage class. Objects with static storage class have a lifetime that is the duration of the program. They are initialized once and retain their last stored value. If no explicit initialization is given in the declaration, they are initialized to 0. As with functions, these identifiers have external linkage by default but can be given internal linkage by means of the static qualifier.

An identifier of an object declared inside a block has no linkage. Each identifier denotes a unique object. These identifiers have automatic storage duration by default. Objects with automatic storage class have a lifetime that begins when execution enters the block and ends when execution exits the block. These objects are not initialized by default and do not necessarily retain their last stored value after execution exits the block. If the block is entered through recursion or with multiple threads, each entry into the block creates a distinct object. A variable with automatic storage class is called an automatic variable.

An identifier of an object declared inside a block can be given static storage duration with the static qualifier. The object then has a lifetime that is the duration of the program and retains its last stored value. If the block is entered through recursion or multiple threads, the same object is used.

Objects with identifiers having static storage duration are often called static variables; those with identifiers having automatic storage duration are called automatic variables.

As described above, the static qualifier can affect either the storage class or linkage class of an object depending on the context. When static is applied to a function, it always changes its linkage class from the default of external to internal. Functions do not have a storage duration. For objects declared inside a block, the linkage class is always none and static changes the storage class from automatic to static. For objects declared outside any block, the storage class is always static and the static specifier changes the linkage class from external to internal. These rules are summarized in Table A.3.

UNIX SYSTEM V: A Practical Guide, 3rd ed., by Sobell [108] is an up-to-date reference on using the UNIX utilities. UNIX System Administration Handbook, 3rd ed., by Nemeth et al. [86] is an excellent and readable introduction to many of the configuration issues involved in setting up UNIX systems. O’Reilly Press has individual books on many of the topics in this appendix including emacs [20], the libraries [27], lint [28], make [120], and vi [69].