pthread_create(3)pthread_create(3)NAMEpthread_create - Creates a thread
SYNOPSIS
#include <pthread.h>
int pthread_create(
pthread_t *thread,
const pthread_attr_t *attr,
void * (*start_routine)(void *),
void *arg );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
Location for thread object to be created. Thread attributes object
that defines the characteristics of the thread being created. If you
specify NULL, default attributes are used. Function executed as the
new thread's start routine. Address value copied and passed to the
thread's start routine.
DESCRIPTION
This routine creates a thread. A thread is a single, sequential flow
of control within a program. It is the active execution of a designated
routine, including any nested routine invocations.
Successful execution of this routine includes the following actions:
DECthreads creates a thread object to describe and control the thread.
The thread object includes a thread environment block (TEB) that pro‐
grams can use, with care. (See the <sys/types.h> header file on Tru64
UNIX, or the pthread.h header file on other DECthreads platforms.) The
thread argument receives an identifier for the new thread. An exe‐
cutable thread is created with attributes specified by the attr argu‐
ment (or with default attributes if NULL is specified).
Thread Creation
DECthreads creates a thread in the “ready” state and prepares the
thread to begin executing its start routine, the function passed to
pthread_create(3) as the start_routine argument. Depending on the pres‐
ence of other threads and their scheduling and priority attributes, the
new thread might start executing immediately. The new thread can also
preempt its creator, depending on the two threads' respective schedul‐
ing and priority attributes. The caller of pthread_create(3) can syn‐
chronize with the new thread using the pthread_join(3) routine or using
any mutually agreed upon mutexes or condition variables.
For the duration of the new thread's existence, DECthreads maintains
and manages the thread object and other thread state overhead. A thread
“exists” until it is both terminated and detached. A thread is detached
when created if the detachstate attribute of its thread object is set
to PTHREAD_CREATE_DETACHED. It is also detached after any thread
returns successfully from calling pthread_detach(3) or pthread_join(3)
for the thread. Termination is explained in the next section (see
Thread Termination).
DECthreads assigns each new thread a thread identifier, which DEC‐
threads writes into the address specified as the pthread_create(3) rou‐
tine's thread argument. DECthreads writes the new thread's thread iden‐
tifier before the new thread executes.
By default, the new thread's scheduling policy and priority are inher‐
ited from the creating thread--that is, by default, the pthread_cre‐
ate(3) routine ignores the scheduling policy and priority set in the
specified thread attributes object. Thus, to create a thread that is
subject to the scheduling policy and priority set in the specified
thread attributes object, before calling pthread_create(3) your program
must use the pthread_attr_setinheritsched(3) routine to set the inherit
thread attributes object's scheduling attribute to
PTHREAD_EXPLICIT_SCHED.
On Tru64 UNIX, the signal state of the new thread is initialized as
follows: The signal mask is inherited from the creating thread. The
set of signals pending for the new thread is empty.
If pthread_create(3) fails, no new thread is created, and the contents
of the location referenced by thread are undefined.
Thread Termination
A thread terminates when one of the following events occurs: The thread
returns from its start routine. The thread calls the pthread_exit(3)
routine. The thread is canceled.
When a thread terminates, DECthreads performs these actions: DECthreads
writes a return value (if one is available) into the terminated
thread's thread object, as follows: If the thread has been canceled,
DECthreads writes the value PTHREAD_CANCELED into the thread's thread
object. If the thread terminated by returning from its start routine,
DECthreads copies the return value from the start routine (if one is
available) into the thread's thread object. Alternatively, if the
thread explicitly called pthread_exit(3), DECthreads stores the value
received in the value_ptr argument (from pthread_exit(3)) into the
thread's thread object. Another thread can obtain this return value by
joining with the terminated thread (using pthread_join(3)). If the
thread terminated by returning from its start routine normally and the
start routine does not provide a return value, the results obtained by
joining with that thread are unpredictable. If the termination results
from a cancellation request or a call to pthread_exit(3), DECthreads
calls, in turn, each cleanup handler that this thread declared (using
pthread_cleanup_push(3)) and that is not yet removed (using
pthread_cleanup_pop(3)). (DECthreads also transfers control to any
appropriate CATCH, CATCH_ALL, or FINALLY blocks. DECthreads calls the
terminated thread's most recently pushed cleanup handler first. For
C++ programmers: At normal exit from a thread, your program will call
the appropriate destructor functions, just as if an exception had been
raised. To exit the terminated thread due to a call to
pthread_exit(3), DECthreads raises the pthread_exit_e exception. To
exit the terminated thread due to cancellation, DECthreads raises the
pthread_cancel_e exception. Your program can use the DECthreads excep‐
tion package to operate on the generated exception. (In particular,
note that the practice of using CATCH handlers in place of
pthread_cleanup_push(3) is not portable.) For each of the terminated
thread's thread-specific data keys that has a non-NULL value: DEC‐
threads sets the thread's value for the corresponding key to NULL. In
turn, DECthreads calls each thread-specific data destructor function in
this multithreaded process's list of destructors. DECthreads repeats
this step until all thread-specific data values in the thread are NULL,
or for up to a number of iterations equal to PTHREAD_DESTRUCTOR_ITERA‐
TIONS. This destroys all thread-specific data associated with the ter‐
minated thread. DECthreads awakens the thread (if there is one) that
is currently waiting to join with the terminated thread. That is, DEC‐
threads awakens the thread that is waiting in a call to
pthread_join(3). If the thread is already detached, DECthreads
destroys its thread object. Otherwise, the thread continues to exist
until detached or joined with.
RETURN VALUES
If an error condition occurs, no thread is created, the contents of
thread are undefined, and this routine returns an integer value indi‐
cating the type of error. Possible return values are as follows: Suc‐
cessful completion. The system lacks the necessary resources to create
another thread, or the system-imposed limit on the total number of
threads under execution by a single user is exceeded. The value speci‐
fied by attr is invalid. Insufficient memory exists to create a
thread. The caller does not have the appropriate permission to create
a thread with the specified attributes.
ERRORS
None
SEE ALSO
Functions: pthread_atfork(3), pthread_attr_destroy(3),
pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_set‐
inheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setsched‐
policy(3), pthread_attr_setstacksize(3), pthread_cancel(3),
pthread_detach(3), pthread_exit(3), pthread_join(3)
Manuals: Guide to DECthreads and Programmer's Guide
pthread_create(3)