--------------------------------------------------------------------------------
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume
                                       1
--------------------------------------------------------------------------------

pthread_create Subroutine

Purpose

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

Library

Threads Library (libpthreads.a)

Syntax

#include 

int pthread_create (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.

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:

  o The thread returned from its starting routine (the main routine for the
    initial thread)
  o The thread called the pthread_exit subroutine
  o The thread was canceled
  o The thread received a signal that terminated it
  o 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. Otherwise, the -D_THREAD_SAFE
        compilation flag should be used, or the cc_r compiler used. In this case,
        the flag is automatically set.

When multiple threads are created in a process, the FULL_CORE flag is set for all
signals. This means that if a core file is produced, it will be much bigger than
a single_threaded application. This is necessary to debug multiple-threaded
processes.

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

If successful, the pthread_create function returns zero. Otherwise, an error
number is returned to indicate the error.

Error Codes

The pthread_create function will fail if:

EAGAIN The system lacked the necessary resources to create another thread, or the
system-imposed limit on the total number of threads in a process
PTHREAD_THREADS_MAX would be exceeded.

EINVAL The value specified by attr is invalid.

EPERM The caller does not have appropriate permission to set the required
scheduling parameters or scheduling policy.

The pthread_create function will not return an error code of EINTR.

Implementation Specifics

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

When a process uses the pthread_create function, and thus becomes multi-threaded,
the FULL_CORE flag is enabled for all signals. If a signal is received whose
action is to terminate the process with a core dump, a full dump (usually much
larger than a regular dump) will be produced. This is necessary so that
multi-threaded programs can be debugged with the dbx command.

The following piece of psuedo-code is an example of how to avoid getting a full
core. Please note that in this case, debug will not be possible. It may be easier
to limit the size of the core with the ulimit command.
struct sigaction siga;

siga.sa_handler = SIG_DFL;

siga.sa_flags = SA_RESTART;

SIGINITSET(siga.as_mask);

sigaction(, &siga, NULL);

Related Information

The core file format.

The dbx and ulimit commands.

The pthread_attr_init subroutine, pthread_attr_destroy subroutine, pthread_exit
subroutine, pthread_cancel subroutine, pthread_kill subroutine, pthread_self
subroutine, pthread_once subroutine, pthread_join subroutine, fork subroutine,
and the pthread.h file.

Creating Threads in AIX Version 4.3 General Programming Concepts: Writing and
Debugging Programs.

Threads Library Quick Reference in AIX Version 4.3 General Programming Concepts:
Writing and Debugging Programs.
--------------------------------------------------------------------------------