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

pthread_exit Subroutine

Purpose

Terminates the calling thread.

Library

Threads Library (libpthreads.a)

Syntax

#include 

void pthread_exit (void *value_ptr);

Description

The pthread_exit subroutine terminates the calling thread safely, and stores a
termination status for any thread that may join the calling thread. The
termination status is always 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. This subroutine never returns.

Unlike the exit subroutine, the pthread_exit subroutine does not close files.
Thus any file opened and used only by the calling thread must be closed before
calling this subroutine. It is also important to note that the pthread_exit
subroutine frees any thread-specific data, including the thread's stack. Any data
allocated on the stack becomes invalid, since the stack is freed and the
corresponding memory may be reused by another thread. Therefore, thread
synchronization objects (mutexes and condition variables) allocated on a thread's
stack must be destroyed before the thread calls the pthread_exit subroutine.

Returning from the initial routine of a thread implicitly calls the pthread_exit
subroutine, using the return value as parameter.

If the thread is not detached, its resources, including the thread ID, the
termination status, the thread-specific data, and its storage, are all maintained
until the thread is detached or the process terminates.

If another thread joins the calling thread, that thread wakes up immediately, and
the calling thread is automatically detached.

If the thread is detached, the cleanup routines are popped from their stack and
executed. Then the destructor routines from the thread-specific data are
executed. Finally, the storage of the thread is reclaimed and its ID is freed for
reuse.

Terminating the initial thread by calling this subroutine does not terminate the
process, it just terminates the initial thread. However, if all the threads in
the process are terminated, the process is terminated by implicitly calling the
exit subroutine with a return code of 0 if the last thread is detached, or 1
otherwise.

    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.

Parameters

status Points to an optional termination status, used by joining threads. If no
termination status is desired, its value should be NULL.

Return Values

The pthread_exit function cannot return to its caller.

Errors

No errors are defined.

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

Implementation Specifics

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

Related Information

The pthread_cleanup_push subroutine, pthread_cleanup_pop subroutine,
pthread_key_create subroutine, pthread_create subroutine, pthread_join
subroutine, pthread_cancel subroutine, exit subroutine, the pthread.h file.

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