usr/src/man/man3c/pthread_exit.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
  44 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH PTHREAD_EXIT 3C "Nov 2, 2007"
  48 .SH NAME
  49 pthread_exit \- terminate calling thread
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
  54 #include <pthread.h>
  55
  56 \fBvoid\fR \fBpthread_exit\fR(\fBvoid *\fR\fIvalue_ptr\fR);
  57 .fi
  58
  59 .SH DESCRIPTION
  60 .sp
  61 .LP
  62 The \fBpthread_exit()\fR function terminates the calling thread, in a similar
  63 way that \fBexit\fR(3C) terminates the calling process. If the thread is not
  64 detached, the exit status specified by  \fIvalue_ptr\fR is made  available to
  65 any successful join with the terminating thread. See \fBpthread_join\fR(3C).
  66 Any cancellation cleanup handlers that have been pushed and not yet popped are
  67 popped in the reverse order that they were pushed and then executed. After all
  68 cancellation cleanup handlers have been executed, if the thread has any
  69 thread-specific data, appropriate destructor functions will be called in an
  70 unspecified order. Thread termination does not release any application visible
  71 process resources, including, but not limited to, mutexes and file descriptors,
  72 nor does it perform any process level cleanup actions, including, but not
  73 limited to, calling any \fBatexit()\fR routines that might exist.
  74 .sp
  75 .LP
  76 An exiting thread runs with all signals blocked. All thread termination
  77 functions, including cancellation cleanup handlers and thread-specific data
  78 destructor functions, are called with all signals blocked.
  79 .sp
  80 .LP
  81 An implicit call to \fBpthread_exit()\fR is made when a thread other than the
  82 thread in which \fBmain()\fR was first invoked returns from the start routine
  83 that was used to create it. The function's return value serves as the thread's
  84 exit status.
  85 .sp
  86 .LP
  87 The behavior of \fBpthread_exit()\fR is undefined if called from a cancellation
  88 cleanup handler or destructor function that was invoked as a result of either
  89 an implicit or explicit call to \fBpthread_exit()\fR.
  90 .sp
  91 .LP
  92 After a thread has terminated, the result of access to local (auto) variables
  93 of the thread is undefined. Thus, references to local variables of the exiting
  94 thread should not be used for the \fBpthread_exit()\fR \fIvalue_ptr\fR
  95 parameter value.
  96 .sp
  97 .LP
  98 The process exits with an exit status of  \fB0\fR after the last thread has
  99 been terminated. The behavior is as if the implementation called \fBexit()\fR
 100 with a \fB0\fR argument at thread termination time.
 101 .SH RETURN VALUES
 102 .sp
 103 .LP
 104 The \fBpthread_exit()\fR function cannot return to its caller.
 105 .SH ERRORS
 106 .sp
 107 .LP
 108 No errors are defined.
 109 .SH ATTRIBUTES
 110 .sp
 111 .LP
 112 See \fBattributes\fR(5) for descriptions of the following attributes:
 113 .sp
 114
 115 .sp
 116 .TS
 117 box;
 118 c | c
 119 l | l .
 120 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 121 _
 122 Interface Stability     Committed
 123 _
 124 MT-Level        MT-Safe
 125 _
 126 Standard        See \fBstandards\fR(5).
 127 .TE
 128
 129 .SH SEE ALSO
 130 .sp
 131 .LP
 132 \fBexit\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C),
 133 \fBpthread_join\fR(3C), \fBpthread_key_create\fR(3C), \fBattributes\fR(5),
 134 \fBstandards\fR(5)