Programming with POSIX® Threads

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.2 POSIX 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.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.

9.3.1 Error detection and reporting

The POSIX standard distinguishes carefully between two categories of error:

1. Mandatory ('if occurs') errors involve circumstances beyond the control of the programmer. These errors must always be detected and reported by the system using a particular error code. If you cannot create a new thread because your process lacks sufficient virtual memory, then the implementation must always tell you. You can't possibly be expected to check whether there's enough memory before creating the thread—for one thing, you have no way to know how much memory would be required.

2. Optional ('if detected') errors are problems that are usually your mistake. You might try to lock a mutex that hadn't been initialized, for example, or try to unlock a mutex that's locked by another thread. Some systems may

not detect these errors, but they're still errors in your code, and you ought to be able to avoid them without help from the system.

While it would be 'nice' for the system to detect optional errors and return the appropriate error number, sometimes it takes a lot of time to check or is difficult to check reliably. It may be expensive, for example, for the system to determine the identity of the current thread. Systems may therefore not remember which thread locked a mutex, and would be unable to detect that the unlock was erroneous. It may not make sense to slow down the basic synchronization operations for correct programs just to make it a little easier to debug incorrect programs.

Systems may provide debugging modes where some or all of the optional errors are detected. Digital UNIX, for example, provides 'error check' mutexes and a 'metered' execution mode, where the ownership of mutexes is always tracked and optional errors in locking and unlocking mutexes are reported. The UNLX98 specification includes 'error check' mutexes (Section 10.1.2), so they will soon be available on most UNIX systems.