pthread(3)pthread(3)NAME
pthread, pthread_intro - Introduction to POSIX Threads
DESCRIPTION
DECthreads, a multithreading run-time library, provides a set of inter‐
faces for building multithreaded programs. The POSIX threads interface
provides routines that implement the IEEE Std 1003.1c-1995, POSIX Sys‐
tem Application Program Interface, also known as POSIX Standard 1003.1c
or POSIX.1c.
This version of DECthreads also includes additional routines specified
in the document X/Open CAE Specification, System Interfaces and Head‐
ers, Issue 5 published by the Open Group. The additional routines sup‐
port creating and operating on read-write locks and defining mutexes,
condition variables, and read-write locks as shareable across pro‐
cesses, via those objects' “pshared” attribute.
Note that POSIX Standard 1003.1c now supersedes the POSIX draft stan‐
dard 1003.4a. Users of previous versions of DECthreads should be aware
that applications based on the POSIX draft standard 1003.4a/D4 inter‐
face (also known as the “d4” interface or “DCE threads”) require sig‐
nificant modifications to be upgraded to the POSIX threads interface.
See the discussion in the Guide to DECthreads.
The Guide to DECthreads describes important considerations for threaded
application development, particularly for the Tru64 UNIX operating sys‐
tem.
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 the DECthreads POSIX threads interface, a programmer can create
more than one thread 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 objects such as mutexes, condi‐
tion variables, and read-write locks ensure that data objects shared
among threads are accessed correctly. DECthreads provides routines that
allow you to create and use these synchronization objects. Mutexes,
condition variables, and read-write locks are discussed in the Guide to
DECthreads.
DECthreads POSIX threads interface routines whose names have the _np
suffix are not portable. That is, such a routine might operate differ‐
ently, or might not be available, in other vendor implementations of
POSIX Standard 1003.1c.
For users of the Compaq C and C++ compilers, compile a multithreaded
application as follows:
cc -c myprog.c -pthread
For users of C and C++ compilers without support for the -pthread
switch, you must ensure that the C preprocessor symbol _REENTRANT is
defined before including any system header file. One way to accomplish
this is to compile the application as follows:
cc -c myprog.c -D_REENTRANT
For users of the Compaq C and C++ compilers, when linking your multi‐
threaded application that use DECthreads, include only the -pthread
switch in the linker command line. Note that this switch also directs
the linker to search for thread-reentrant variants (named with the “_r”
suffix) of any libraries it searches.
For users of other language environments or C and C++ compilers that do
not support the -pthread linker switch, include these switches at the
end of the linker command line:
ld -o myprog myprog.o -lpthread -lexc -lc crt0.o
or
gcc -o myprog myprog.o -lpthread -lexc
In this case, the -lpthread and -lexc switches direct the linker
explicitly to use the DECthreads run-time and exception-handling
libraries. These switches must immediately precede the -lc switch (if
specified), which directs the linker to use the libc run-time library.
If your application also requires specific thread-reentrant variants of
libraries (such as the C run-time libraries), your linker command line
must explicitly identify them or a search path for them.
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, you must use the Ladebug debugger (or other
thread-aware debugger, such as TotalView) for debugging DECthreads-
based multithreaded applications.
You can also use the Visual Threads tool for troubleshooting and debug‐
ging a multithreaded application. Visual Threads is part of the Devel‐
oper's Toolkit product.
DECthreads POSIX threads interface routines are grouped in the follow‐
ing functional categories: General threads routines Thread attributes
object routines Thread cancellation routines Thread priority, concur‐
rency, and scheduling routines Thread-specific data routines Mutex rou‐
tines Mutex attributes object routines Condition variable routines Con‐
dition variable attributes object routines Read-write lock routines
Read-write lock attributes object routines
Other DECthreads Pthread routines implement nonportable extensions to
POSIX Standard 1003.1c. These routines are grouped into these func‐
tional categories: Thread execution routines Thread attributes object
routines Thread-specific data routines DECthreads global mutex routines
Mutex routines Mutex attributes object routines Condition variable rou‐
tines Read-write lock routines Processor subset object routines DEC‐
threads 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 when its thread termi‐
nates. Compares one thread identifier to another. Terminates the
calling thread. Causes the calling thread to wait for the termination
of another thread and to detach it. Delivers a signal to a specified
thread. Calls an initialization routine to be executed only once.
Obtains the identifier of the calling thread. Examines or changes the
calling thread's signal mask.
Thread Attributes Object Routines
Destroys a thread attributes object. Obtains the detachstate attribute
of the specified thread attributes object. Obtains the guardsize
attribute of the specified thread attributes object. (Supersedes
pthread_attr_getguardsize_np.) Obtains the inherit scheduling
attribute of the specified thread attributes object. Obtains 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. (See
also pthread_attr_getstackaddr_np.) Obtains the stacksize attribute of
the specified thread attributes object. Initializes a thread
attributes object. Changes the detachstate attribute of the specified
thread attributes object. Changes the guardsize attribute of the spec‐
ified thread attributes object. (Supersedes pthread_attr_setguard‐
size_np.) Changes the inherit scheduling attribute of the specified
thread attributes object. Changes the values of the parameters associ‐
ated with the scheduling policy attribute of the specified thread
attributes object. Changes the scheduling policy attribute of the
specified thread attributes object. Changes the contention scope
attribute of the specified thread attributes object. Changes the
stackaddr attribute of the specified thread attributes object. (See
also pthread_attr_setstackaddr_np.) Changes the stacksize attribute of
the specified thread attributes object.
Thread Cancelation Routines
Requests that a thread terminate its execution. Removes a cleanup han‐
dler routine from the calling thread's cleanup stack and optionally
executes it. Establishes a cleanup handler routine to be executed when
the calling thread exits or is canceled. Sets the calling thread's
cancelability state. Sets the calling thread's cancelability type.
Requests delivery of any pending cancellation requests to the calling
thread.
Thread Priority, Concurrency, and Scheduling Routines
Obtains the current concurrency level hint parameter for the calling
thread's process. Obtains the current scheduling policy and scheduling
parameters of a thread. Changes the current concurrency level hint for
the calling thread's 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. Deletes a thread-specific
data key. Sets the thread-specific data value associated with the
specified key for the calling thread.
Mutex Routines
Destroys a mutex object. Initializes a mutex object with attributes in
the specified mutex attributes object. Locks an unlocked mutex; if
already locked, the caller waits for the mutex to become available.
Attempts to lock a mutex; returns immediately if mutex is already
locked. Unlocks a locked mutex.
Mutex Attributes Object Routines
Initializes a mutex attributes object. Destroys a mutex attributes
object. Obtains the process-shared attribute of the specified mutex
attributes object. Obtains the mutex type attribute of the specified
mutex attributes object. (Supersedes pthread_mutexattr_gettype_np.)
Changes the process-shared attribute of the specified mutex attributes
object. Changes the mutex type attribute of the specified mutex
attributes object. (Supersedes pthread_mutexattr_settype_np.)
Condition Variable Routines
Wakes all threads waiting on a condition variable. Destroys a condi‐
tion variable object. Initializes a condition variable object. 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 signaled or broadcast. Causes a thread to wait for a condition
variable to be signaled or broadcast.
Condition Variable Attributes Object Routines
Destroys a condition variable attributes object. Obtains the process-
shared attribute of the specified condition variable attributes object.
Initializes a condition variable attributes object. Changes the
process-shared attribute of the specified condition variable attributes
object.
Read-Write Lock Routines
Destroys a read-write lock object. Initializes a read-write lock
object. Acquires a read-write lock for read access, after waiting if
necessary. Attempts to acquire, without waiting, a read-write lock for
read access. Attempts to acquire, without waiting, a read-write lock
for write access. Releases one acquisition by the calling thread of a
read-write lock for read access or write access. Acquires a read-write
lock for write access, after waiting if necessary.
Read-Write Lock Attributes Object Routines
Destroys a read-write lock attributes object. Obtains the process-
shared attribute of the specified read-write lock attributes object.
Initializes a read-write lock attributes object. Changes the process-
shared attribute of the specified read-write lock attributes object.
Non-Portable Extensions: Thread Execution Routines
Causes a thread to delay execution. Obtains a value representing a
desired expiration time. Obtains the object name of the specified
thread object. Obtains a thread's sequence number. Changes the object
name of the specified thread object.
Non-Portable Extensions: Thread Attributes Object Routines
Obtains the object name attribute of the specified thread attributes
object. Obtains the processor subset attribute of the specified thread
attributes object. Obtains the stackaddr attribute of the specified
thread attributes object as low address and size. (See also
pthread_attr_getstackaddr.) Changes the object name attribute of the
specified thread attributes object. Changes the processor subset
attribute of the specified thread attributes object. Changes the
stackaddr attribute of the specified thread attributes object by speci‐
fying low address and size. (See also pthread_attr_setstackaddr.)
Non-Portable Extensions: Thread-Specific Data Routines
Obtains the object name of a thread-specific data key object. Changes
the object name of a thread-specific data key object.
Non-Portable Extensions: DECthreads Global Mutex Routines
Locks the DECthreads global mutex if it is unlocked. Unlocks the DEC‐
threads global mutex if it is locked.
Non-Portable Extensions: Mutex Routines
Obtains the object name of a mutex object. Changes the object name of
a mutex object.
Non-Portable Extensions: Condition Variable Routines
Obtains the object name of a condition variable object. Changes the
object name of a condition variable object. Wakes one thread that is
waiting on a condition variable (called from interrupt level only).
Wakes one thread that is waiting on the specified condition variable
(called from interrupt level only).
Non-Portable Extensions: Read-Write Lock Routines
Obtains the object name of a read-write lock object. Changes the
object name of a read-write lock object.
Non-Portable Extensions: Processor Subset Object Routines
Stores the combined CPU resource descriptions from two processor subset
objects into a third. Destroys a processor subset object. Determines
whether the CPU resource descriptions of two processor subset objects
are equivalent. Obtains CPU resource information in a thread object
and stores it in the specified processor subset object. Initializes a
processor subset object based on a processor subset attributes object.
Returns the number of processors described in the specified processor
subset object. Stores the CPU resource descriptions from a processor
subset object into a thread object. Sets the contents of two processor
subset objects by splitting the contents of a third.
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.
Non-Portable Extensions: Thread Priority, Concurrency, and Scheduling Rou‐
tines
Notifies the scheduler that the current thread is willing to release
its processor to other threads of the same or higher priority.
pthread(3)