lib/libpthread/pthread.3

   1 .\"     $NetBSD: pthread.3,v 1.11 2009/04/16 18:37:30 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003, 2007, 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Hubert Feyrer <hubertf@NetBSD.org> and Thomas Klausner <wiz@NetBSD.org>.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd October 6, 2009
  31 .Dt PTHREAD 3
  32 .Os
  33 .Sh NAME
  34 .Nm pthread
  35 .Nd POSIX Threads Library
  36 .Sh LIBRARY
  37 .Lb libpthread
  38 .Sh SYNOPSIS
  39 .In pthread.h
  40 .Pp
  41 .Nm cc
  42 .Op Ar flags
  43 .Ar files
  44 .Fl lpthread
  45 .Op Ar libraries
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 library provides an implementation of the standard
  50 .Tn POSIX
  51 threads library.
  52 .Pp
  53 The
  54 .Nx
  55 implementation is based on 1:1 thread model, therefore each
  56 .Nm
  57 has a kernel thread, called a light-weight process (LWP).
  58 .Pp
  59 Note that the system private thread interfaces upon which the
  60 .Nm
  61 library is built are subject to change without notice.
  62 In order to remain compatible with future
  63 .Nx
  64 releases, programs must be linked against the dynamic version of the
  65 thread library.
  66 Statically linked programs using the
  67 .Tn POSIX
  68 threads framework may not work when run on a future version of the system.
  69 .Sh ENVIRONMENT
  70 .Bl -tag -width PTHREAD_DEBUGCOUNTERSXX
  71 .It Ev PTHREAD_DIAGASSERT
  72 Possible values are any combinations of:
  73 .Pp
  74 .Bl -tag -width ignoreXX -offset indent -compact
  75 .It Sy A
  76 Report errors to application by error return, but do not abort.
  77 .It Sy a
  78 Abort on errors, creating a core dump for further debugging.
  79 .It Sy E
  80 Do not log errors to stdout.
  81 .It Sy e
  82 Log errors to stdout.
  83 .It Sy L
  84 Do not log errors via
  85 .Xr syslogd 8 .
  86 .It Sy l
  87 Log errors via
  88 .Xr syslogd 8 .
  89 .El
  90 .Pp
  91 If not set in the environment, the
  92 .Nm
  93 library behaves as if
  94 .Sy AEL
  95 has been specified.
  96 .It Ev PTHREAD_STACKSIZE
  97 Integer value giving the stack size in kilobytes.
  98 This allows to set a smaller stack size than the default stack size.
  99 The default stack size is the current limit on the stack size as
 100 set with the shell's command to change limits
 101 .Ic ( limit
 102 for
 103 .Xr csh 1 ,
 104 or
 105 .Ic ulimit
 106 for
 107 .Xr sh 1 ) .
 108 .El
 109 .Sh SEE ALSO
 110 .Xr pthread_attr 3 ,
 111 .Xr pthread_barrier_destroy 3 ,
 112 .Xr pthread_barrier_init 3 ,
 113 .Xr pthread_barrier_wait 3 ,
 114 .Xr pthread_barrierattr 3 ,
 115 .Xr pthread_cancel 3 ,
 116 .Xr pthread_cleanup_push 3 ,
 117 .Xr pthread_cond_broadcast 3 ,
 118 .Xr pthread_cond_destroy 3 ,
 119 .Xr pthread_cond_init 3 ,
 120 .Xr pthread_cond_wait 3 ,
 121 .Xr pthread_condattr 3 ,
 122 .Xr pthread_create 3 ,
 123 .Xr pthread_detach 3 ,
 124 .Xr pthread_equal 3 ,
 125 .Xr pthread_exit 3 ,
 126 .Xr pthread_getspecific 3 ,
 127 .Xr pthread_join 3 ,
 128 .Xr pthread_key_create 3 ,
 129 .Xr pthread_key_delete 3 ,
 130 .Xr pthread_kill 3 ,
 131 .Xr pthread_mutex_destroy 3 ,
 132 .Xr pthread_mutex_init 3 ,
 133 .Xr pthread_mutex_lock 3 ,
 134 .Xr pthread_mutex_unlock 3 ,
 135 .Xr pthread_mutexattr 3 ,
 136 .Xr pthread_once 3 ,
 137 .Xr pthread_rwlock_destroy 3 ,
 138 .Xr pthread_rwlock_init 3 ,
 139 .Xr pthread_rwlock_rdlock 3 ,
 140 .Xr pthread_rwlock_unlock 3 ,
 141 .Xr pthread_rwlock_wrlock 3 ,
 142 .Xr pthread_rwlockattr 3 ,
 143 .Xr pthread_schedparam 3 ,
 144 .Xr pthread_self 3 ,
 145 .Xr pthread_setspecific 3 ,
 146 .Xr pthread_sigmask 3 ,
 147 .Xr pthread_spin_destroy 3 ,
 148 .Xr pthread_spin_init 3 ,
 149 .Xr pthread_spin_lock 3 ,
 150 .Xr pthread_spin_unlock 3 ,
 151 .Xr pthread_testcancel 3
 152 .Sh STANDARDS
 153 The
 154 .Nm
 155 library conforms to
 156 .St -p1003.1-2001 .
 157 .Sh CAVEATS
 158 Due to limitations in the current pthread implementation,
 159 .Xr makecontext 3
 160 and
 161 .Xr sigaltstack 2
 162 should not be used in programs which link against the
 163 .Nm
 164 library (whether threads are used or not).