Programming with POSIX® Threads

• By defining compile-time symbolic constants in the header file. The symbolic constant may be omitted from when the limit is at least as large as the required minimum, but cannot be determined at compile time, for example, if it depends on available memory space. You can test for these symbolic constants using #ifdef or #ifndef preprocessor conditionals.

• By returning a positive nonzero value when the sysconf function is called with the associated sysconf symbol.

You might, for example, design your application to rely on no more than 64 threads, if the conformance documents showed that three out of the four systems

Run-time invariant values,	Description
sysconf symbol name
PTHREAD_DESTRUCTOR_ITERATIONS _SC_THREAD_DESTRUCTOR_ITERATIONS	Maximum number of attempts to destroy a thread's thread-specific data on termination (must be at least 4).
PTHREAD_KEYS_MAX _SC_THREAD_KEYS_MAX	Maximum number of thread-specific data keys available per process (must be at least 128).
PTHREAD_STACK_MIN _SC_THREAD_STACK_MIN	Minimum supported stack size for a thread.
PTHREAD_THREADS_MAX _SC_THREAD_THREADS_MAX	Maximum number of threads supported per process (must be at least 64).
TABLE 9.2POSIX 1003.1 c-1995 limits

you wish to support do not support additional threads. Or you might prefer to write conditional code that relies on the value of the PTHREAD_THREADS_MAX symbolic constant (if defined) or call sysconf to determine the limit at run time.

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.1Mini-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.

9.3.1 Error detection and reporting