NAME

pthread_create – thread creation

SYNOPSIS

#include <pthread.h>

int pthread_create(pthread_t *new_thread_ID,

          const pthread_attr_t *attr,

          void * (*start_func )(void *),

          void *arg );

DESCRIPTION

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.

Attributes

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:

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_attr_init(&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.

GLOBALS

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.

RETURN VALUES

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

ERRORS

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

EINVAL

stack_base attribute is not NULL and stack_size attribute is less than PTHREAD_STACK_MIN.

EINVAL

stack_base attribute is NULL and stack_size attribute is not zero and is less than PTHREAD_STACK_MIN.

EINVAL

priority attribute is greater than PTHREAD_MAX_PRIORITY.

ENOMEM

Not enough memory was available to create the new thread.

SEE ALSO

pthread_attr_init(), pthread_exit()