pthread_create - thread creation


#include <pthread.h>

int pthread_create(pthread_t *new_thread_ID,
const pthread_attr_t *attr,
void * (*start_func )(void *),
void *arg );


Thread creation adds a new thread of control to the system.

A newly created thread shares global data with the other threads on the same node; however, it has its own set of attributes and private execution stack. The new thread inherits the calling thread's scheduling priority. Pending signals for a new thread are not inherited and will be empty.

The call to pthread_create() takes the address of a user-defined function, specified by start_func, which is the complete execution routine for the new thread. The new thread begins by calling the function start_func with one argument, arg . If more than one argument needs to be passed to start_func , the arguments can be packed into a structure, and the address of that structure can be passed to arg .

The start_func must never return. The results of returning from start_func are processor dependant and undefined. The routine pthread_exit() should be called to terminate a thread.

If the thread creation itself fails, a new thread is not created and the contents of the location referenced by the pointer to the new thread are undefined.


The configuration of a set of attributes defines the behavior of a thread. At creation, each attribute of a new thread may be user-defined or set to the default. All attributes are defined upon thread creation, however, some may be dynamically modified after creation.

The available attributes are:




Sets a pointer to the thread's stack


Sets the size of the thread's stack


Sets ranking within the policy (scheduling class)



pthread_create() creates a new thread with attributes defined by attr . Default attributes are used if attr is NULL. If any attributes specified by attr are changed in the attribute object prior to the call to pthread_create() , the new thread will acquire those changes. However, if any attributes specified by attr are changed after the call to pthread_create() , the attributes of existing threads will not be affected. Since pthread_create() can use an attribute object in its call, a user-defined thread creation must be preceded by a user-defined attribute object (see pthread_attr_init() ). Upon successful completion, and if the return value is not NULL, pthread_create() will store the ID of the created thread in the location referenced by new_thread_ID .

For the default creation attributes for pthread_create() , see pthread_attr_init().

Default thread creation:

        pthread_t tid;

        void *start_func(void *);

        pthread_create(&tid, 0, start_func, 0);

This would have the same effect as:

        pthread_attr_t attr;

        pthread_create(&tid, &attr, start_func, 0);

To customize the attributes for POSIX threads, see pthread_attr_init().

A new thread created with pthread_create() uses the stack specified by the stackaddr attribute, and the stack continues for the number of bytes specified by the stacksize attribute.


Several global variables affect thread creation. If pthreadStackFill is set, on thread creation the new threads stack is fills the stack with 'S' characters. Calls to pthread_stackinfo() can use this information to provide a high water mark for thread stack usage. By default pthreadStackFill is off.

The POSIX define PTHREAD_STACK_MIN points to the global variable pthreadStackMin. This defines the minimum stack size for the given processor.

If the stacksize attribute is zero, the variable pthreadStackDefault is used for the default stack size.


Zero indicates a successful return and a non-zero value indicates an error.


If any of the following conditions are detected, pthread_create() fails and returns the corresponding value:

stack_base attribute is not NULL and stack_size attribute is less than PTHREAD_STACK_MIN.
stack_base attribute is NULL and stack_size attribute is not zero and is less than PTHREAD_STACK_MIN.
priority attribute is greater than PTHREAD_MAX_PRIORITY.
Not enough memory was available to create the new thread.


pthread_attr_init(), pthread_exit()

Home page (Kernel)

< Copyright RoweBots Limited and Multiprocessor Toolsmiths Inc. 1987-2014 >