.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PTHREAD_EXIT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" pthread_exit 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
pthread_exit \- thread termination
.SH SYNOPSIS
.LP
\fB#include <pthread.h>
.br
.sp
void pthread_exit(void *\fP\fIvalue_ptr\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIpthread_exit\fP() function shall terminate the calling thread
and make the value \fIvalue_ptr\fP available to any
successful join with the terminating thread. Any cancellation cleanup
handlers that have been pushed and not yet popped shall be
popped in the reverse order that they were pushed and then executed.
After all cancellation cleanup handlers have been executed, if
the thread has any thread-specific data, appropriate destructor functions
shall be called in an unspecified order. Thread
termination does not release any application visible process resources,
including, but not limited to, mutexes and file
descriptors, nor does it perform any process-level cleanup actions,
including, but not limited to, calling any \fIatexit\fP() routines
that may exist.
.LP
An implicit call to \fIpthread_exit\fP() is made when a thread other
than the thread in which \fImain\fP() was first invoked
returns from the start routine that was used to create it. The function's
return value shall serve as the thread's exit status.
.LP
The behavior of \fIpthread_exit\fP() is undefined if called from a
cancellation cleanup handler or destructor function that was
invoked as a result of either an implicit or explicit call to \fIpthread_exit\fP().
.LP
After a thread has terminated, the result of access to local (auto)
variables of the thread is undefined. Thus, references to
local variables of the exiting thread should not be used for the \fIpthread_exit\fP()
\fIvalue_ptr\fP parameter value.
.LP
The process shall exit with an exit status of 0 after the last thread
has been terminated. The behavior shall be as if the
implementation called \fIexit\fP() with a zero argument at thread
termination time.
.SH RETURN VALUE
.LP
The \fIpthread_exit\fP() function cannot return to its caller.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
The normal mechanism by which a thread terminates is to return from
the routine that was specified in the \fIpthread_create\fP() call
that started it. The \fIpthread_exit\fP() function provides
the capability for a thread to terminate without requiring a return
from the start routine of that thread, thereby providing a
function analogous to \fIexit\fP().
.LP
Regardless of the method of thread termination, any cancellation cleanup
handlers that have been pushed and not yet popped are
executed, and the destructors for any existing thread-specific data
are executed. This volume of IEEE\ Std\ 1003.1-2001
requires that cancellation cleanup handlers be popped and called in
order. After all cancellation cleanup handlers have been
executed, thread-specific data destructors are called, in an unspecified
order, for each item of thread-specific data that exists
in the thread. This ordering is necessary because cancellation cleanup
handlers may rely on thread-specific data.
.LP
As the meaning of the status is determined by the application (except
when the thread has been canceled, in which case it is
PTHREAD_CANCELED), the implementation has no idea what an illegal
status value is, which is why no address error checking is
done.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIexit\fP(), \fIpthread_create\fP(), \fIpthread_join\fP(), the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .