pthread_create Subroutine



Purpose

Creates a new thread, initializes its attributes, and makes it runnable.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

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

Description

The pthread_create subroutine creates a new thread and initializes
its attributes using the thread attributes object specified by the
attr parameter. The new thread inherits its creating thread's signal
mask; but any pending signal of the creating thread will be cleared
for the new thread.

Note:	The number of threads per process is defined in the pthread.h
file as 512.

The new thread is made runnable, and will start executing the start_routine
routine, with the parameter specified by the arg parameter. The arg
parameter is a void pointer; it can reference any kind of data. It
is not recommended to cast this pointer into a scalar data type (int
for example), because the casts may not be portable.

After thread creation, the thread attributes object can be reused
to create another thread, or deleted.

The thread terminates in the following cases:

*	The thread returned from its starting routine (the main routine
for the initial thread)

*	The thread called the pthread_exit subroutine

*	The thread was canceled

*	The thread received a signal that terminated it

*	The entire process is terminated due to a call to either the
exec or exit subroutines.

Note:	The pthread.h header file must be the first included file of
each source file using the threads library.

Parameters

thread	Points to where the thread ID will be stored.

attr	Specifies the thread attributes object to use in creating the
thread. If the value is NULL, the default attributes values will be
used.

start_routine	Points to the routine to be executed by the thread.

arg	Points to the single argument to be passed to the start_routine
routine.

Return Values

Upon successful completion, the new thread's ID is returned via the
thread parameter, and 0 is returned. Otherwise, an error code is returned.

Error Codes

The pthread_create subroutine is unsuccessful if the following is
true:

EAGAIN	The system does not have sufficient resources to create another
thread.

EINVAL	The thread or attr parameters are not valid.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_attr_init subroutine, pthread_attr_destroy subroutine,
pthread_exit subroutine, pthread_cancel subroutine, pthread_kill subroutine,
pthread_self subroutine, pthread_once subroutine.

Creating Threads.

Threads Library Quick Reference.