*** UNIX MANUAL PAGE BROWSER ***

pthread(3) Library Functions Manual pthread(3) NAME pthread, pthread_intro - Introduction to POSIX Threads (Pthreads) DESCRIPTION DECthreads, DIGITAL's multithreading run-time library, provides a set of interfaces for building multithreaded programs. One of these inter- faces provides routines (with the prefix pthread_) that implement the IEEE Std 1003.1c-1995, POSIX System Application Program Interface, also known as POSIX Standard 1003.1c or POSIX.1c. Note that POSIX Standard 1003.1c now supersedes the POSIX draft standard 1003.4a. A thread is a single, sequential flow of control within a program. Within a single thread, there is a single point of execution. Most traditional programs consist of a single thread. Using DECthreads, a programmer can create more than one threads within a program. Threads execute concurrently, and, within a multithreaded program, there are at any time multiple points of execution. The threads in a given process execute within (and share) a single address space. Therefore, threads read and write the same memory locations. Synchronization elements such as mutexes and condition variables ensure that the shared memory is accessed correctly. DECthreads provides rou- tines that allow you to create and use these synchronization elements. Mutexes and condition variables are discussed in the Guide to DEC- threads. Users of previous versions of DECthreads should be aware that applica- tions consistent with the P1003.4a/D4 interface require significant modifications to be upgraded to the DECthreads pthread (POSIX.1c) in- terface. See the discussion in the Guide to DECthreads. Routine names ending with the _np suffix denote that the routine is "not portable." That is, such a routine might not be available in other vendor implementations of POSIX 1003.1c. Compile a multithreaded application using shared versions of libmach and libpthread as follows: cc -o myprog myprog.c -pthread If you use a compiler front-end or other (not C) language environment that does not support the -pthread compilation switch, you must use the -D_REENTRANT compilation switch. When linking your multithreaded application, include these switches: -lpthread -lexc Each C module that utilizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. Note that previous versions of DECthreads provided a DECthreads-spe- cific debugging interface. However, for this version and future ver- sions of DECthreads, we recommend the use of the DIGITAL UNIX Ladebug debugger for debugging DECthreads-based multithreaded applications. The Guide to DECthreads describes important considerations for threaded application development, particularly for the DIGITAL UNIX operating system. The pthread interface routines are grouped in the following functional categories: General threads routines Thread attributes object routines Thread cancelation routines Thread priority, concurrency, and schedul- ing routines Thread-specific data routines Mutex routines Mutex attrib- utes object routines Condition variable routines Condition variable at- tribute object routines DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these functional categories: Thread execution routines Thread attributes rou- tines DECthreads global mutex routines Mutex attributes routines Condi- tion variable routines DECthreads exception object routines General Threads Routines Declares fork handler routines to be called. Creates a thread object and thread. Marks a thread object for deletion. Compares one thread identifier to another thread identifier. Terminates the calling thread. Causes the calling thread to wait for the termination of a specified thread and detach it. Delivers a signal to a specified thread. Calls an initialization routine to be executed only once. Ob- tains the identifier of the current thread. Examines or changes the calling thread's signal mask. Thread Attributes Object Routines Destroys a thread attributes object. Obtains the detachstate attribute from the specified thread attributes object. Obtains the guardsize at- tribute of the specified thread attributes object. Obtains the inherit scheduling attribute from the specified thread attributes object. Ob- tains the scheduling parameters for an attribute of the specified thread attributes object. Obtains the scheduling policy attribute of the specified thread attributes object. Obtains the contention-scope attribute of the specified thread attributes object. Obtains the stackaddr attribute of the specified thread attributes object. Obtains the stacksize attribute of the specified thread attributes object. Initializes a thread attributes object. Changes the detachstate at- tribute in the specified thread attributes object. Changes the guard- size attribute of the specified thread attributes object. Changes the inherit scheduling attribute of the specified thread attributes object. Changes the values of the parameters associated with the scheduling policy attribute of the specified thread attributes object. Changes the scheduling policy attribute of the specified thread attributes ob- ject. Changes the stackaddr attribute in the specified thread attrib- utes object. Changes the stacksize attribute in the specified thread attributes object. Thread Cancelation Routines Allows a thread to request that it, or another thread, terminate execu- tion. Removes a cleanup handler routine from the top of the cleanup stack and optionally executes it. Establishes a cleanup handler rou- tine to be executed when the thread exits or is canceled. Sets the current thread's cancelability state. Sets the current thread's cance- lability type. Requests delivery of any pending cancelation request to the current thread. Thread Priority, Concurrency, and Scheduling Routines Obtains the current concurrency level parameter for the process. Ob- tains the current scheduling policy and scheduling parameters of a thread. Obtains a thread sequence number. Changes the current concur- rency level parameter for the process. Changes the current scheduling policy and scheduling parameters of a thread. Thread-Specific Data Routines Obtains the thread-specific data associated with the specified key. Generates a unique thread-specific data key. Sets the thread-specific data value associated with the specified key for the current thread. Deletes a thread-specific data key. Mutex Routines Destroys a mutex. Initializes a mutex with attributes specified by the attributes argument. Locks an unlocked mutex; if locked, the caller waits for the mutex to become available. Attempts to lock a mutex; re- turns immediately if mutex is already locked. Unlocks a locked mutex. Mutex Attributes Object Routines Initializes a mutex attributes object. Destroys a mutex attributes ob- ject. Obtains the mutex type attribute of a mutex attributes object. Changes the mutex type attribute of a mutex attributes object. Condition Variable Routines Wakes all threads waiting on a condition variable. Destroys a condi- tion variable. Initializes a condition variable. Wakes at least one thread that is waiting on a condition variable. Causes a thread to wait for a specified period of time for a condition variable to be sig- naled or broadcasted. Causes a thread to wait for a condition variable to be signaled or broadcasted. Condition Variable Attributes Object Routines Destroys a condition variable attributes object. Initializes a condi- tion variable attributes object. Non-Portable Extensions: Thread Execution Routines Causes a thread to delay execution. Obtains a value representing a de- sired expiration time. Obtains the thread sequence number. Non-Portable Extensions: Thread Attributes Routines Obtains the guardsize attribute of the specified thread attributes ob- ject. Changes the guardsize attribute of the specified thread attrib- utes object. Non-Portable Extensions: DECthreads Global Mutex Routines Locks the DECthreads global mutex if it is unlocked. Unlocks the DEC- threads lobal mutex if it is locked. Non-Portable Extensions: Mutex Attributes Routines Obtains the mutex type attribute of a mutex attributes object. Changes the mutex type attribute of a mutex attributes object. Non-Portable Extensions: Condition Variable Routines Wakes one thread that is waiting on a condition variable (called from interrupt level only). Non-Portable Extensions: DECthreads Exception Object Routines Obtains a system-defined error status from a DECthreads status excep- tion object. Determines whether two DECthreads exception objects are identical. Produces a message that reports what a specified DECthreads status exception object represents. Imports a system-defined error status into a DECthreads address exception object. delim off delim off pthread(3)