pthread_create() — Create a thread

Standards

Format

#define _OPEN_THREADS
#include <pthread.h>

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

SUSV3

#define _UNIX03_THREADS 
#include <pthread.h>
int pthread_create(pthread_t * __restrict__thread, 
                   const pthread_attr_t *attr, 
                   void *(*start_routine) (void *arg), 
                   void * __restrict__arg);

General description

Creates a new thread within a process, with attributes defined by the thread attribute object, attr, that is created by pthread_attr_init().

If attr is NULL, the default attributes are used. See pthread_attr_init() — Initialize a thread attribute object for a description of the thread attributes and their defaults. If the attributes specified by attr are changed later, the thread's attributes are not affected.

pthread_t is the data type used to uniquely identify a thread. It is returned by pthread_create() and used by the application in function calls that require a thread identifier.

The thread is created running start_routine, with arg as the only argument. If pthread_create() completes successfully, thread will contain the ID of the created thread. If it fails, no new thread is created, and the contents of the location referenced by thread are undefined.

System default for the thread limit in a process is set by MAXTHREADS in the BPXPRMxx parmlib member.

The maximum number of threads is dependent upon the size of the private area below 16M. pthread_create() inspects this address space before creating a new thread. A realistic limit is 200 to 400 threads.

Special behavior for C++: Because C and C++ linkage conventions are incompatible, pthread_create() cannot receive a C++ function pointer as the start routine function pointer If you attempt to pass a C++ function pointer to pthread_create(), the compiler will flag it as an error. You can pass a C or C++ function to pthread_create() by declaring it as extern "C".

The started thread provides a boundary with respect to the scope of try-throw-catch processing. A throw done in the start routine or a function called by the start routine causes stack unwinding up to and including the start routine (or until caught). The stack unwinding will not go beyond the start routine back into the thread creator. If the exception is not caught, terminate() is called.

The exception stack (for try-throw-catch) are thread-based. The throw of a condition, or re-throw of a condition by a thread does not affect exception processing on another thread, unless the condition is not caught.

Returned value

If successful, pthread_create() returns 0.

Special behavior for Single UNIX Specification, Version 3: If unsuccessful, pthread_create() returns an error number to indicate the error.

Example

/* CELEBP27 */
#define _OPEN_THREADS
#include <pthread.h>
#include <stdlib.h>
#include <stdio.h>
void *thread(void *arg) {
  char *ret;
  printf("thread() entered with argument '%s'\n", arg);
  if ((ret = (char*) malloc(20)) == NULL) {
    perror("malloc() error");
    exit(2);
  }
  strcpy(ret, "This is a test");
  pthread_exit(ret);
}

main() {
  pthread_t thid;
  void *ret;

  if (pthread_create(&thid, NULL, thread, "thread 1") != 0) {
    perror("pthread_create() error");
    exit(1);
  }

  if (pthread_join(thid, &ret) != 0) {
    perror("pthread_create() error");
    exit(3);
  }

  printf("thread exited with '%s'\n", ret);
}

thread() entered with argument 'thread 1'
thread exited with 'This is a test'

Related information

• pthread.h
• pthread_exit() — Exit a thread
• pthread_join() — Wait for a thread to end