— Function: int pthread_create (pthread_t * thread, pthread_attr_t * attr, void * (*start_routine)(void *), void * arg)

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 calling pthread_exit, or implicitly, by returning from the start_routine function. The latter case is equivalent to calling pthread_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.

— Function: void pthread_exit (void *retval)

pthread_exit terminates the execution of the calling thread. All cleanup handlers (see Cleanup Handlers) that have been set for the calling thread with pthread_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.

— Function: int pthread_cancel (pthread_t thread)

pthread_cancel sends a cancellation request to the thread denoted by the thread argument. If there is no such thread, pthread_cancel fails and returns ESRCH. Otherwise it returns 0. See Cancellation, for details.

— Function: int pthread_join (pthread_t th, void **thread_return)

pthread_join suspends the execution of the calling thread until the thread identified by th terminates, either by calling pthread_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 to pthread_exit, or PTHREAD_CANCELED if th was canceled.

The joined thread th must be in the joinable state: it must not have been detached using pthread_detach or the PTHREAD_CREATE_DETACHED attribute to pthread_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 in pthread_join, the thread execution resumes immediately and the cancellation is executed without waiting for the th thread to terminate. If cancellation occurs during pthread_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.