Книга: Programming with POSIX® Threads

9.3 POSIX1003.1c-1995 interfaces

The interfaces are sorted by functional categories: threads, mutexes, and so forth. Within each category, the interfaces are listed in alphabetical order. Figure 9.1 describes the format of the entries.

First, the header entry (1) shows the name of the interface. If the interface is an optional feature of Pthreads, then the name of the feature-test macro for that

FIGURE9.1 Mini-reference format

option is shown at the end of the line, in brackets. The interface pthread_ mutexattr_getpshared, for example, is an option under the _POSIX_THREAD_ PROCESS_SHARED feature.

The prototype entry (2) shows the full C language prototype for the interface, describing how to call the function, with all argument types.

The description entry (3) gives a brief synopsis of the interface. In this case, the purpose of the interface is to specify whether mutexes created using the attributes object can be shared between multiple processes.

Functions with arguments that have symbolic values, like pshared in this example, will include a table (4) that describes each possible value. The default value of the argument (the state of a new thread, or the default value of an attribute in a new attributes object, in this case PTHREAD_PROCESS_PRIVATE) is indicated by showing the name in bold.

The references entry (5) gives cross-references to the primary sections of this book that discuss the interface, or other closely related interfaces.

The headers entry (6) shows the header files needed to compile code using the function. If more than one header is shown, you need all of them.

The errors entry (7) describes each of the possible error numbers returned by the interface; Because Pthreads distinguishes between mandatory error detection ("if occurs" in POSIX terms) and optional error detection ("if detected" in POSIX terms), the errors that an interface must report (if they occur) are shown in bold (see Section 9.3.1 for details on Pthreads errors).

The hint entry (8) gives a single, and inevitably oversimplified, philosophical comment regarding the interface. Some hints point out common errors in using the interface; others describe something about the designers' intended use of the interface, or some fundamental restriction of the interface. In pthread_mutexattr_ getpshared, for example, the hint points out that a mutex created to be "process shared" must be allocated in shared memory that's accessible by all participating processes.

Оглавление книги