## 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 .

If the start_func returns, the effect shall be as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status.

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:

Attribute | Description
stackaddr | Sets a pointer to the thread's stack
stacksize | Sets the size of the thread's stack
priority | Sets ranking within the policy (scheduling class)
detachstate | Sets the detach state of the thread
policy | Ignored

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, NULL, start_func, NULL);

This would have the same effect as:

            pthread_attr_t attr;

            pthread_attr_init(&attr);
            pthread_create(&tid, &attr, start_func, NULL);

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.

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
  pointer attr is not inited.
EINVAL
  stack_size attribute is set and less than PTHREAD_STACK_MIN.
ENOMEM
  Not enough memory was available to create the new thread.

## SEE ALSO

pthread_attr_init(), pthread_exit()

#### Home page (Kernel)

## < Copyright Rowebots Research Inc. and Multiprocessor Toolsmiths Inc. 1987-2018 >