These functions are the thread equivalents of fork
, exit
,
and wait
.
pthread_create
creates a new thread of control that executes concurrently with the calling thread. The new thread calls the function start_routine, passing it arg as first argument. The new thread terminates either explicitly, by callingpthread_exit
, or implicitly, by returning from the start_routine function. The latter case is equivalent to callingpthread_exit
with the result returned by start_routine as exit code.The attr argument specifies thread attributes to be applied to the new thread. See Thread Attributes, for details. The attr argument can also be
NULL
, in which case default attributes are used: the created thread is joinable (not detached) and has an ordinary (not realtime) scheduling policy.On success, the identifier of the newly created thread is stored in the location pointed by the thread argument, and a 0 is returned. On error, a non-zero error code is returned.
This function may return the following errors:
EAGAIN
- Not enough system resources to create a process for the new thread, or more than
PTHREAD_THREADS_MAX
threads are already active.
pthread_exit
terminates the execution of the calling thread. All cleanup handlers (see Cleanup Handlers) that have been set for the calling thread withpthread_cleanup_push
are executed in reverse order (the most recently pushed handler is executed first). Finalization functions for thread-specific data are then called for all keys that have non-NULL
values associated with them in the calling thread (see Thread-Specific Data). Finally, execution of the calling thread is stopped.The retval argument is the return value of the thread. It can be retrieved from another thread using
pthread_join
.The
pthread_exit
function never returns.
pthread_cancel
sends a cancellation request to the thread denoted by the thread argument. If there is no such thread,pthread_cancel
fails and returnsESRCH
. Otherwise it returns 0. See Cancellation, for details.
pthread_join
suspends the execution of the calling thread until the thread identified by th terminates, either by callingpthread_exit
or by being canceled.If thread_return is not
NULL
, the return value of th is stored in the location pointed to by thread_return. The return value of th is either the argument it gave topthread_exit
, orPTHREAD_CANCELED
if th was canceled.The joined thread
th
must be in the joinable state: it must not have been detached usingpthread_detach
or thePTHREAD_CREATE_DETACHED
attribute topthread_create
.When a joinable thread terminates, its memory resources (thread descriptor and stack) are not deallocated until another thread performs
pthread_join
on it. Therefore,pthread_join
must be called once for each joinable thread created to avoid memory leaks.At most one thread can wait for the termination of a given thread. Calling
pthread_join
on a thread th on which another thread is already waiting for termination returns an error.
pthread_join
is a cancellation point. If a thread is canceled while suspended inpthread_join
, the thread execution resumes immediately and the cancellation is executed without waiting for the th thread to terminate. If cancellation occurs duringpthread_join
, the th thread remains not joined.On success, the return value of th is stored in the location pointed to by thread_return, and 0 is returned. On error, one of the following values is returned:
ESRCH
- No thread could be found corresponding to that specified by th.
EINVAL
- The th thread has been detached, or another thread is already waiting on termination of th.
EDEADLK
- The th argument refers to the calling thread.