pthread_create

Creates a thread object and thread.

Syntax

pthread_create( thread, attr, start_routine, arg );

Argument Data Type Access

thread opaque pthread_t write attr opaque pthread_attr_t read start_routine procedure read arg opaque pthread_addr_t read

C Binding

int
pthread_create (
pthread_t *thread,
pthread_attr_t attr,
pthread_startroutine_t start_routine,
pthread_addr_t arg);

Arguments

thread: Thread object created.
attr: Thread attributes object that defines the characteristics of the thread being created. If you specify pthread_attr_default, default attributes are used.
start_routine: Function executed as the new thread's start routine.
arg: Address value copied and passed to the thread's start routine.

Description

This routine creates a thread object and 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. A thread object defines and controls the executing thread.

Calling this routine sets into motion the following actions:

An internal thread object is created to describe the thread.
The associated executable thread is created with attributes specified by the attr argument (or with default attributes if pthread_attr_default is specified).
The thread argument receives the new thread.
The start_routine function is called.

A thread is created in the ready state and therefore might immediately begin executing the function specified by the start_routine argument. The newly created thread may preempt its creator if the new thread follows the SCHED_RR or SCHED_ FIFO scheduling policy or has a priority higher than the creating thread, or both. Otherwise, the new thread begins running at its turn, which might also be before pthread_create returns.

The new thread's scheduling policy and priority are, by default, inherited from the creating thread-the scheduling policy and priority set in the attributes object are ignored. To create a thread using the scheduling policy and priority set in the attributes object, you must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched.

The start_routine is passed a copy of the arg argument. The value of the arg argument is specified by the calling application code.

The thread object exists until the pthread_detach routine is called or the thread terminates, whichever occurs last.

Synchronization between the caller of pthread_create and the newly created thread is done through the use of the pthread_join routine (or any other mutexes or condition variables they agree to use).

Return Values

If an error condition occurs, no thread is created, the contents of thread are undefined, and this routine returns -1 and sets errno to the corresponding error value. Possible return values are as follows:

Return Error Description

0 Successful completion. -1 [EAGAIN] The system lacks the necessary resources to create another thread. The system-imposed limit on the total number of threads under execution by a single user is exceeded. -1 [ENOMEM] Insufficient memory exists to create the thread attributes object. This is not a temporary condition.