1.\" $NetBSD: pthread.3,v 1.16 2016/11/24 12:19:28 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 November 22, 2016 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 47The 48.Nm 49library provides an implementation of the standard 50.Tn POSIX 51threads library. 52.Pp 53The 54.Nx 55implementation is based on 1:1 thread model, therefore each 56.Nm 57has a kernel thread, called a light-weight process (LWP). 58.Pp 59Note that the system private thread interfaces upon which the 60.Nm 61library is built are subject to change without notice. 62In order to remain compatible with future 63.Nx 64releases, programs must be linked against the dynamic version of the 65thread library. 66Statically linked programs using the 67.Tn POSIX 68threads framework may not work when run on a future version of the system. 69.Sh FUNCTIONS 70The following functions comprise the core of the 71.Nm 72library: 73.Bl -column -offset indent "pthread_barrier_destroy(3)" "XXX" 74.It Sy Function Ta Sy Description 75.It Xr pthread_attr 3 Ta thread attribute operations 76.It Xr pthread_barrier_destroy 3 Ta destroy a barrier 77.It Xr pthread_barrier_init 3 Ta create a barrier 78.It Xr pthread_barrier_wait 3 Ta wait for a barrier 79.It Xr pthread_barrierattr 3 Ta barrier attribute operations 80.It Xr pthread_cancel 3 Ta cancel the execution of a thread 81.It Xr pthread_cleanup_push 3 Ta add or remove cleanup functions 82.It Xr pthread_cond_broadcast 3 Ta unblock one or more threads 83.It Xr pthread_cond_destroy 3 Ta destroy a condition variable 84.It Xr pthread_cond_init 3 Ta create a condition variable 85.It Xr pthread_cond_wait 3 Ta wait for a condition variable 86.It Xr pthread_condattr 3 Ta condition attribute operations 87.It Xr pthread_create 3 Ta create a new thread 88.It Xr pthread_detach 3 Ta detach a thread 89.It Xr pthread_equal 3 Ta compare thread identifiers 90.It Xr pthread_exit 3 Ta terminate the calling thread 91.It Xr pthread_getspecific 3 Ta get a thread-specific data value 92.It Xr pthread_join 3 Ta wait for thread termination 93.It Xr pthread_key_create 3 Ta thread-specific data key creation 94.It Xr pthread_key_delete 3 Ta delete a thread-specific data key 95.It Xr pthread_kill 3 Ta send a signal to a specific thread 96.It Xr pthread_mutex_destroy 3 Ta free a mutex 97.It Xr pthread_mutex_init 3 Ta create a mutex 98.It Xr pthread_mutex_lock 3 Ta acquire a lock on a mutex 99.It Xr pthread_mutex_unlock 3 Ta unlock a mutex 100.It Xr pthread_mutexattr 3 Ta mutex attribute operations 101.It Xr pthread_once 3 Ta dynamic package initialization 102.It Xr pthread_rwlock_destroy 3 Ta destroy a read/write lock 103.It Xr pthread_rwlock_init 3 Ta initialize a read/write lock 104.It Xr pthread_rwlock_rdlock 3 Ta acquire a read/write lock for reading 105.It Xr pthread_rwlock_unlock 3 Ta release a read/write lock 106.It Xr pthread_rwlock_wrlock 3 Ta acquire a read/write lock for writing 107.It Xr pthread_rwlockattr 3 Ta read/write lock attribute operations 108.It Xr pthread_schedparam 3 Ta thread scheduling manipulation 109.It Xr pthread_self 3 Ta get the ID of the calling thread 110.It Xr pthread_setspecific 3 Ta get a thread-specific data value 111.It Xr pthread_sigmask 3 Ta manipulate a thread's signal mask 112.It Xr pthread_spin_destroy 3 Ta destroy a spin lock 113.It Xr pthread_spin_init 3 Ta initialize a spin lock 114.It Xr pthread_spin_lock 3 Ta acquire a spin lock 115.It Xr pthread_spin_unlock 3 Ta release a spin lock 116.It Xr pthread_testcancel 3 Ta set cancelability state 117.El 118.Sh ENVIRONMENT 119The following environment variables affect the behavior of the library: 120.Bl -tag -width "XXX" 121.It Ev PTHREAD_DIAGASSERT 122Possible values are any combinations of: 123.Pp 124.Bl -tag -width "X " -offset 1n -compact 125.It Em A 126Report errors to application by error return, but do not abort. 127.It Em a 128Abort on errors, creating a core dump for further debugging. 129.It Em E 130Do not log errors to stdout. 131.It Em e 132Log errors to stdout. 133.It Em L 134Do not log errors via 135.Xr syslogd 8 . 136.It Em l 137Log errors via 138.Xr syslogd 8 . 139.El 140.Pp 141If not set in the environment, the 142.Nm 143library behaves as if 144.Em AEL 145has been specified. 146.It Ev PTHREAD_STACKSIZE 147Integer value giving the stack size in kilobytes. 148This allows to set a smaller stack size than the default stack size. 149The default stack size is the current limit on the stack size as 150set with the shell's command to change limits 151.Ic ( limit 152for 153.Xr csh 1 , 154or 155.Ic ulimit 156for 157.Xr sh 1 ) . 158.El 159.Sh SEE ALSO 160.Xr pthread_dbg 3 161.Rs 162.%A David R. Butenhof 163.%T Programming with POSIX(R) Threads 164.%D 1997 165.%I Addison-Wesley 166.Re 167.Sh STANDARDS 168The 169.Nm 170library conforms to 171.St -p1003.1-2001 . 172.Sh CAVEATS 173Due to limitations in the current pthread implementation, 174.Xr makecontext 3 175and 176.Xr sigaltstack 2 177should not be used in programs which link against the 178.Nm 179library (whether threads are used or not). 180