man3p/pthread_exit.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "PTHREAD_EXIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" pthread_exit
   4 .SH NAME
   5 pthread_exit \- thread termination
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <pthread.h>
   9 .br
  10 .sp
  11 void pthread_exit(void *\fP\fIvalue_ptr\fP\fB); \fP
  12 \fB
  13 .br
  14 \fP
  15 .SH DESCRIPTION
  16 .LP
  17 The \fIpthread_exit\fP() function shall terminate the calling thread
  18 and make the value \fIvalue_ptr\fP available to any
  19 successful join with the terminating thread. Any cancellation cleanup
  20 handlers that have been pushed and not yet popped shall be
  21 popped in the reverse order that they were pushed and then executed.
  22 After all cancellation cleanup handlers have been executed, if
  23 the thread has any thread-specific data, appropriate destructor functions
  24 shall be called in an unspecified order. Thread
  25 termination does not release any application visible process resources,
  26 including, but not limited to, mutexes and file
  27 descriptors, nor does it perform any process-level cleanup actions,
  28 including, but not limited to, calling any \fIatexit\fP() routines
  29 that may exist.
  30 .LP
  31 An implicit call to \fIpthread_exit\fP() is made when a thread other
  32 than the thread in which \fImain\fP() was first invoked
  33 returns from the start routine that was used to create it. The function's
  34 return value shall serve as the thread's exit status.
  35 .LP
  36 The behavior of \fIpthread_exit\fP() is undefined if called from a
  37 cancellation cleanup handler or destructor function that was
  38 invoked as a result of either an implicit or explicit call to \fIpthread_exit\fP().
  39 .LP
  40 After a thread has terminated, the result of access to local (auto)
  41 variables of the thread is undefined. Thus, references to
  42 local variables of the exiting thread should not be used for the \fIpthread_exit\fP()
  43 \fIvalue_ptr\fP parameter value.
  44 .LP
  45 The process shall exit with an exit status of 0 after the last thread
  46 has been terminated. The behavior shall be as if the
  47 implementation called \fIexit\fP() with a zero argument at thread
  48 termination time.
  49 .SH RETURN VALUE
  50 .LP
  51 The \fIpthread_exit\fP() function cannot return to its caller.
  52 .SH ERRORS
  53 .LP
  54 No errors are defined.
  55 .LP
  56 \fIThe following sections are informative.\fP
  57 .SH EXAMPLES
  58 .LP
  59 None.
  60 .SH APPLICATION USAGE
  61 .LP
  62 None.
  63 .SH RATIONALE
  64 .LP
  65 The normal mechanism by which a thread terminates is to return from
  66 the routine that was specified in the \fIpthread_create\fP() call
  67 that started it. The \fIpthread_exit\fP() function provides
  68 the capability for a thread to terminate without requiring a return
  69 from the start routine of that thread, thereby providing a
  70 function analogous to \fIexit\fP().
  71 .LP
  72 Regardless of the method of thread termination, any cancellation cleanup
  73 handlers that have been pushed and not yet popped are
  74 executed, and the destructors for any existing thread-specific data
  75 are executed. This volume of IEEE\ Std\ 1003.1-2001
  76 requires that cancellation cleanup handlers be popped and called in
  77 order. After all cancellation cleanup handlers have been
  78 executed, thread-specific data destructors are called, in an unspecified
  79 order, for each item of thread-specific data that exists
  80 in the thread. This ordering is necessary because cancellation cleanup
  81 handlers may rely on thread-specific data.
  82 .LP
  83 As the meaning of the status is determined by the application (except
  84 when the thread has been canceled, in which case it is
  85 PTHREAD_CANCELED), the implementation has no idea what an illegal
  86 status value is, which is why no address error checking is
  87 done.
  88 .SH FUTURE DIRECTIONS
  89 .LP
  90 None.
  91 .SH SEE ALSO
  92 .LP
  93 \fIexit\fP() , \fIpthread_create\fP() , \fIpthread_join\fP() , the
  94 Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
  95 .SH COPYRIGHT
  96 Portions of this text are reprinted and reproduced in electronic form
  97 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  98 -- Portable Operating System Interface (POSIX), The Open Group Base
  99 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 100 Electrical and Electronics Engineers, Inc and The Open Group. In the
 101 event of any discrepancy between this version and the original IEEE and
 102 The Open Group Standard, the original IEEE and The Open Group Standard
 103 is the referee document. The original Standard can be obtained online at
 104 http://www.opengroup.org/unix/online.html .