lib/libpthread/pthread_exit.3

   1 .\" $NetBSD: pthread_exit.3,v 1.3 2003/07/04 10:19:42 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  15 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  16 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  18 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  19 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  20 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  22 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  23 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
  27 .\" All rights reserved.
  28 .\"
  29 .\" Redistribution and use in source and binary forms, with or without
  30 .\" modification, are permitted provided that the following conditions
  31 .\" are met:
  32 .\" 1. Redistributions of source code must retain the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer.
  34 .\" 2. Redistributions in binary form must reproduce the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer in the
  36 .\"    documentation and/or other materials provided with the distribution.
  37 .\" 3. All advertising materials mentioning features or use of this software
  38 .\"    must display the following acknowledgement:
  39 .\"     This product includes software developed by John Birrell.
  40 .\" 4. Neither the name of the author nor the names of any co-contributors
  41 .\"    may be used to endorse or promote products derived from this software
  42 .\"    without specific prior written permission.
  43 .\"
  44 .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
  45 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  46 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  47 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  48 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  49 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  50 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  52 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  53 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  54 .\" SUCH DAMAGE.
  55 .\"
  56 .\" $FreeBSD: src/lib/libpthread/man/pthread_exit.3,v 1.16 2002/09/16 19:29:28 mini Exp $
  57 .\"
  58 .Dd January 30, 2003
  59 .Dt PTHREAD_EXIT 3
  60 .Os
  61 .Sh NAME
  62 .Nm pthread_exit
  63 .Nd terminate the calling thread
  64 .Sh LIBRARY
  65 .Lb libpthread
  66 .Sh SYNOPSIS
  67 .In pthread.h
  68 .Ft void
  69 .Fn pthread_exit "void *value_ptr"
  70 .Sh DESCRIPTION
  71 The
  72 .Fn pthread_exit
  73 function terminates the calling thread and makes the value
  74 .Fa value_ptr
  75 available to any successful join with the terminating thread.
  76 Any
  77 cancellation cleanup handlers that have been pushed and are not yet popped
  78 are popped in the reverse order that they were pushed and then executed.
  79 After all cancellation handlers have been executed, if the thread has any
  80 thread-specific data, appropriate destructor functions are called in an
  81 unspecified order.
  82 Thread termination does not release any application
  83 visible process resources, including, but not limited to, mutexes and
  84 file descriptors, nor does it perform any process level cleanup
  85 actions, including, but not limited to, calling
  86 .Fn atexit
  87 routines that may exist.
  88 .Pp
  89 An implicit call to
  90 .Fn pthread_exit
  91 is made when a thread other than the thread in which
  92 .Fn main
  93 was first invoked returns from the start routine that was used to create
  94 it.
  95 The function's return value serves as the thread's exit status.
  96 .Pp
  97 The behavior of
  98 .Fn pthread_exit
  99 is undefined if called from a cancellation handler or destructor function
 100 that was invoked as the result of an implicit or explicit call to
 101 .Fn pthread_exit .
 102 .Pp
 103 After a thread has terminated, the result of access to local (auto)
 104 variables of the thread is undefined.
 105 Thus, references to local variables
 106 of the exiting thread should not be used for the
 107 .Fn pthread_exit
 108 .Fa value_ptr
 109 parameter value.
 110 .Pp
 111 The process will exit with an exit status of 0 after the last thread has
 112 been terminated.
 113 The behavior is as if the implementation called
 114 .Fn exit
 115 with a zero argument at thread termination time.
 116 .Sh RETURN VALUES
 117 The
 118 .Fn pthread_exit
 119 function cannot return to its caller.
 120 .Sh ERRORS
 121 None.
 122 .Sh SEE ALSO
 123 .Xr _exit 2 ,
 124 .Xr exit 3 ,
 125 .Xr pthread_create 3 ,
 126 .Xr pthread_join 3
 127 .Sh STANDARDS
 128 .Fn pthread_exit
 129 conforms to
 130 .St -p1003.1-96 .