pthread.3: Update the IMPLEMENTATION NOTES to the current state of affairs.
[dragonfly.git] / lib / libpthread / pthread.3
CommitLineData
984263bc
MD
1.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by John Birrell.
15.\" 4. Neither the name of the author nor the names of any co-contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
15acf97d 31.\" $FreeBSD: src/share/man/man3/pthread.3,v 1.33 2009/04/01 08:08:25 trhodes Exp $
984263bc 32.\"
d55e7aa5 33.Dd April 8, 2010
984263bc
MD
34.Dt PTHREAD 3
35.Os
36.Sh NAME
37.Nm pthread
38.Nd POSIX thread functions
1bc160bc 39.Sh LIBRARY
183d29cf 40.Lb libpthread
984263bc
MD
41.Sh SYNOPSIS
42.In pthread.h
43.Sh DESCRIPTION
44POSIX threads are a set of functions that support applications with
45requirements for multiple flows of control, called
15acf97d 46.Em threads ,
984263bc
MD
47within a process.
48Multithreading is used to improve the performance of a
49program.
50.Pp
51The POSIX thread functions are summarized in this section in the following
52groups:
15acf97d
SW
53.Pp
54.Bl -bullet -offset indent -compact
984263bc
MD
55.It
56Thread Routines
57.It
58Attribute Object Routines
59.It
60Mutex Routines
61.It
62Condition Variable Routines
63.It
64Read/Write Lock Routines
65.It
66Per-Thread Context Routines
67.It
68Cleanup Routines
69.El
15acf97d
SW
70.Ss Thread Routines
71.Bl -tag -width indent
984263bc
MD
72.It Xo
73.Ft int
15acf97d
SW
74.Fo pthread_create
75.Fa "pthread_t *thread" "const pthread_attr_t *attr"
76.Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg"
77.Fc
984263bc
MD
78.Xc
79Creates a new thread of execution.
80.It Xo
81.Ft int
82.Fn pthread_cancel "pthread_t thread"
83.Xc
84Cancels execution of a thread.
85.It Xo
86.Ft int
87.Fn pthread_detach "pthread_t thread"
88.Xc
89Marks a thread for deletion.
90.It Xo
91.Ft int
92.Fn pthread_equal "pthread_t t1" "pthread_t t2"
93.Xc
94Compares two thread IDs.
95.It Xo
96.Ft void
97.Fn pthread_exit "void *value_ptr"
98.Xc
99Terminates the calling thread.
100.It Xo
101.Ft int
102.Fn pthread_join "pthread_t thread" "void **value_ptr"
103.Xc
104Causes the calling thread to wait for the termination of the specified thread.
105.It Xo
106.Ft int
107.Fn pthread_kill "pthread_t thread" "int sig"
108.Xc
109Delivers a signal to a specified thread.
110.It Xo
111.Ft int
15acf97d 112.Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]"
984263bc
MD
113.Xc
114Calls an initialization routine once.
115.It Xo
116.Ft pthread_t
117.Fn pthread_self void
118.Xc
119Returns the thread ID of the calling thread.
120.It Xo
121.Ft int
122.Fn pthread_setcancelstate "int state" "int *oldstate"
123.Xc
124Sets the current thread's cancelability state.
125.It Xo
126.Ft int
127.Fn pthread_setcanceltype "int type" "int *oldtype"
128.Xc
129Sets the current thread's cancelability type.
130.It Xo
131.Ft void
132.Fn pthread_testcancel void
133.Xc
134Creates a cancellation point in the calling thread.
135.It Xo
136.Ft void
137.Fn pthread_yield void
138.Xc
139Allows the scheduler to run another thread instead of the current one.
140.El
15acf97d
SW
141.Ss Attribute Object Routines
142.Bl -tag -width indent
984263bc
MD
143.It Xo
144.Ft int
145.Fn pthread_attr_destroy "pthread_attr_t *attr"
146.Xc
147Destroy a thread attributes object.
148.It Xo
149.Ft int
15acf97d
SW
150.Fo pthread_attr_getinheritsched
151.Fa "const pthread_attr_t *attr" "int *inheritsched"
152.Fc
984263bc
MD
153.Xc
154Get the inherit scheduling attribute from a thread attributes object.
155.It Xo
156.Ft int
15acf97d
SW
157.Fo pthread_attr_getschedparam
158.Fa "const pthread_attr_t *attr" "struct sched_param *param"
159.Fc
984263bc
MD
160.Xc
161Get the scheduling parameter attribute from a thread attributes object.
162.It Xo
163.Ft int
164.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
165.Xc
166Get the scheduling policy attribute from a thread attributes object.
167.It Xo
168.Ft int
169.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
170.Xc
171Get the contention scope attribute from a thread attributes object.
172.It Xo
173.Ft int
174.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
175.Xc
176Get the stack size attribute from a thread attributes object.
177.It Xo
178.Ft int
179.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
180.Xc
181Get the stack address attribute from a thread attributes object.
182.It Xo
183.Ft int
184.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
185.Xc
186Get the detach state attribute from a thread attributes object.
187.It Xo
188.Ft int
189.Fn pthread_attr_init "pthread_attr_t *attr"
190.Xc
191Initialize a thread attributes object with default values.
192.It Xo
193.Ft int
194.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
195.Xc
196Set the inherit scheduling attribute in a thread attributes object.
197.It Xo
198.Ft int
15acf97d
SW
199.Fo pthread_attr_setschedparam
200.Fa "pthread_attr_t *attr" "const struct sched_param *param"
201.Fc
984263bc
MD
202.Xc
203Set the scheduling parameter attribute in a thread attributes object.
204.It Xo
205.Ft int
206.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
207.Xc
208Set the scheduling policy attribute in a thread attributes object.
209.It Xo
210.Ft int
211.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
212.Xc
213Set the contention scope attribute in a thread attributes object.
214.It Xo
215.Ft int
216.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
217.Xc
218Set the stack size attribute in a thread attributes object.
219.It Xo
220.Ft int
221.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
222.Xc
223Set the stack address attribute in a thread attributes object.
224.It Xo
225.Ft int
226.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
227.Xc
228Set the detach state in a thread attributes object.
229.El
15acf97d
SW
230.Ss Mutex Routines
231.Bl -tag -width indent
984263bc
MD
232.It Xo
233.Ft int
234.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
235.Xc
236Destroy a mutex attributes object.
237.It Xo
238.Ft int
239.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
240.Xc
241Obtain priority ceiling attribute of mutex attribute object.
242.It Xo
243.Ft int
244.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
245.Xc
246Obtain protocol attribute of mutex attribute object.
247.It Xo
248.Ft int
249.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
250.Xc
251Obtain the mutex type attribute in the specified mutex attributes object.
252.It Xo
253.Ft int
254.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
255.Xc
256Initialize a mutex attributes object with default values.
257.It Xo
258.Ft int
259.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
260.Xc
261Set priority ceiling attribute of mutex attribute object.
262.It Xo
263.Ft int
264.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
265.Xc
266Set protocol attribute of mutex attribute object.
267.It Xo
268.Ft int
269.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
270.Xc
271Set the mutex type attribute that is used when a mutex is created.
272.It Xo
273.Ft int
274.Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
275.Xc
276Destroy a mutex.
277.It Xo
278.Ft int
15acf97d
SW
279.Fo pthread_mutex_init
280.Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
281.Fc
984263bc
MD
282.Xc
283Initialize a mutex with specified attributes.
284.It Xo
285.Ft int
286.Fn pthread_mutex_lock "pthread_mutex_t *mutex"
287.Xc
288Lock a mutex and block until it becomes available.
289.It Xo
290.Ft int
15acf97d
SW
291.Fo pthread_mutex_timedlock
292.Fa "pthread_mutex_t *mutex" "const struct timespec *abstime"
293.Fc
294.Xc
295Lock a mutex and block until it becomes available or until the timeout expires.
296.It Xo
297.Ft int
984263bc
MD
298.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
299.Xc
15acf97d 300Try to lock a mutex, but do not block if the mutex is locked by another thread,
984263bc
MD
301including the current thread.
302.It Xo
303.Ft int
304.Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
305.Xc
306Unlock a mutex.
307.El
15acf97d
SW
308.Ss Condition Variable Routines
309.Bl -tag -width indent
984263bc
MD
310.It Xo
311.Ft int
312.Fn pthread_condattr_destroy "pthread_condattr_t *attr"
313.Xc
314Destroy a condition variable attributes object.
315.It Xo
316.Ft int
317.Fn pthread_condattr_init "pthread_condattr_t *attr"
318.Xc
319Initialize a condition variable attributes object with default values.
320.It Xo
321.Ft int
322.Fn pthread_cond_broadcast "pthread_cond_t *cond"
323.Xc
324Unblock all threads currently blocked on the specified condition variable.
325.It Xo
326.Ft int
327.Fn pthread_cond_destroy "pthread_cond_t *cond"
328.Xc
329Destroy a condition variable.
330.It Xo
331.Ft int
332.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
333.Xc
334Initialize a condition variable with specified attributes.
335.It Xo
336.Ft int
337.Fn pthread_cond_signal "pthread_cond_t *cond"
338.Xc
339Unblock at least one of the threads blocked on the specified condition variable.
340.It Xo
341.Ft int
15acf97d
SW
342.Fo pthread_cond_timedwait
343.Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex"
344.Fa "const struct timespec *abstime"
345.Fc
984263bc 346.Xc
15acf97d
SW
347Wait no longer than the specified time for a condition
348and lock the specified mutex.
984263bc
MD
349.It Xo
350.Ft int
351.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
352.Xc
353Wait for a condition and lock the specified mutex.
354.El
15acf97d
SW
355.Ss Read/Write Lock Routines
356.Bl -tag -width indent
984263bc
MD
357.It Xo
358.Ft int
359.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
360.Xc
361Destroy a read/write lock object.
362.It Xo
363.Ft int
15acf97d
SW
364.Fo pthread_rwlock_init
365.Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
366.Fc
984263bc
MD
367.Xc
368Initialize a read/write lock object.
369.It Xo
370.Ft int
371.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
372.Xc
373Lock a read/write lock for reading, blocking until the lock can be
374acquired.
375.It Xo
376.Ft int
377.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
378.Xc
379Attempt to lock a read/write lock for reading, without blocking if the
380lock is unavailable.
381.It Xo
382.Ft int
383.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
384.Xc
385Attempt to lock a read/write lock for writing, without blocking if the
386lock is unavailable.
387.It Xo
388.Ft int
389.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
390.Xc
391Unlock a read/write lock.
392.It Xo
393.Ft int
394.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
395.Xc
396Lock a read/write lock for writing, blocking until the lock can be
397acquired.
398.It Xo
399.Ft int
400.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
401.Xc
402Destroy a read/write lock attribute object.
403.It Xo
404.Ft int
15acf97d
SW
405.Fo pthread_rwlockattr_getpshared
406.Fa "const pthread_rwlockattr_t *attr" "int *pshared"
407.Fc
984263bc
MD
408.Xc
409Retrieve the process shared setting for the read/write lock attribute
410object.
411.It Xo
412.Ft int
413.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
414.Xc
415Initialize a read/write lock attribute object.
416.It Xo
417.Ft int
418.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
419.Xc
420Set the process shared setting for the read/write lock attribute object.
421.El
15acf97d
SW
422.Ss Per-Thread Context Routines
423.Bl -tag -width indent
984263bc
MD
424.It Xo
425.Ft int
15acf97d 426.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]"
984263bc
MD
427.Xc
428Create a thread-specific data key.
429.It Xo
430.Ft int
431.Fn pthread_key_delete "pthread_key_t key"
432.Xc
433Delete a thread-specific data key.
434.It Xo
435.Ft "void *"
436.Fn pthread_getspecific "pthread_key_t key"
437.Xc
438Get the thread-specific value for the specified key.
439.It Xo
440.Ft int
441.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
442.Xc
443Set the thread-specific value for the specified key.
444.El
15acf97d
SW
445.Ss Cleanup Routines
446.Bl -tag -width indent
447.It Xo
448.Ft int
449.Fo pthread_atfork
450.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]"
451.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]"
452.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]"
453.Fc
454.Xc
455Register fork handlers
984263bc
MD
456.It Xo
457.Ft void
458.Fn pthread_cleanup_pop "int execute"
459.Xc
460Remove the routine at the top of the calling thread's cancellation cleanup
461stack and optionally invoke it.
462.It Xo
463.Ft void
15acf97d 464.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg"
984263bc
MD
465.Xc
466Push the specified cancellation cleanup handler onto the calling thread's
467cancellation stack.
468.El
15acf97d 469.Sh IMPLEMENTATION NOTES
984263bc 470The current
9bb2a92d 471.Dx
984263bc 472POSIX thread implementation is built in the library
d55e7aa5 473.Sy libthread_xu
984263bc 474which contains both thread-safe libc functions and the thread functions.
d55e7aa5
SW
475Another thread library,
476.Sy libc_r ,
477is available for testing purposes.
478.Pp
479In
480.Dx ,
481it is possible to switch the threading library used by dynamically linked
482binaries at execution time by re-linking
483.Pa /usr/lib/libpthread.so.x
484to a different library in
485.Pa /usr/lib/thread .
486At link time,
487.Xr ld 1
488reads the
489.Sy SONAME
490of
491.Pa libpthread.so ,
492which is set to
493.Pa libpthread.so.0
494(or a higher major, if there were ABI changes).
495For normal libraries
496.Pa libfoo.so
497is usually a symlink to
498.Pa libfoo.so.3
499which also has its
500.Sy SONAME
501set to
502.Pa libfoo.so.3 ,
503so that if
504.Pa libfoo.so.4
505is installed, programs will still continue to use
506.Pa libfoo.so.3
507and not follow the symlink
508.Pa libfoo.so
509to the newer (and possibly incompatible)
510.Pa libfoo.so.4 .
511What we do for
512.Pa libpthread.so
513is approximately the opposite:
514.Pa libpthread.so
515is not a symlink but nevertheless has its
516.Sy SONAME
517set to
518.Pa libpthread.so.0 .
519.Pa libpthread.so.0 ,
520however, is a symlink to the threading library of the user's choice.
521The linker will use the default threading library which
522.Pa libpthread.so
523is linked to, but the runtime linker will instead follow the symlink.
524.Pp
525.Pa libc.so
526defines all pthread functions as weak symbols except for
527.Fn pthread_create
528(which is defined by libpthread.so.x to satisfy
529.Xr ld 1 ) .
530At execution time,
531.Xr rtld 1
532will resolve all these references to the strong symbols from the thread
533library.
984263bc
MD
534.Pp
535By default,
d55e7aa5
SW
536.Sy libc_r
537is built as part of a 'make buildworld'.
538To disable the build of
984263bc 539.Fa libc_r
d55e7aa5
SW
540you must supply the '-DNO_LIBC_R' option to
541.Xr make 1
542(or set it in
543.Xr make.conf ) .
544.Pp
545Another
546.Xr make.conf 5
547option,
548.Va THREAD_LIB ,
549can be used to override the system's default threading library.
984263bc
MD
550.Pp
551A
1724cfca
HP
552.Dx
553specific option exists in
554.Xr gcc 1
555to simplify the linking of threaded processes.
d55e7aa5 556.Nm gcc Fl pthread
984263bc 557links a threaded process against
d55e7aa5 558.Pa libthread.so
984263bc
MD
559instead of
560.Fa libc .
561.Sh SEE ALSO
15acf97d
SW
562.Xr pthread_atfork 3 ,
563.Xr pthread_cancel 3 ,
984263bc
MD
564.Xr pthread_cleanup_pop 3 ,
565.Xr pthread_cleanup_push 3 ,
15acf97d
SW
566.Xr pthread_condattr_destroy 3 ,
567.Xr pthread_condattr_init 3 ,
984263bc
MD
568.Xr pthread_cond_broadcast 3 ,
569.Xr pthread_cond_destroy 3 ,
570.Xr pthread_cond_init 3 ,
571.Xr pthread_cond_signal 3 ,
572.Xr pthread_cond_timedwait 3 ,
573.Xr pthread_cond_wait 3 ,
984263bc
MD
574.Xr pthread_create 3 ,
575.Xr pthread_detach 3 ,
576.Xr pthread_equal 3 ,
577.Xr pthread_exit 3 ,
578.Xr pthread_getspecific 3 ,
579.Xr pthread_join 3 ,
580.Xr pthread_key_delete 3 ,
581.Xr pthread_kill 3 ,
984263bc
MD
582.Xr pthread_mutexattr_destroy 3 ,
583.Xr pthread_mutexattr_getprioceiling 3 ,
584.Xr pthread_mutexattr_getprotocol 3 ,
585.Xr pthread_mutexattr_gettype 3 ,
586.Xr pthread_mutexattr_init 3 ,
587.Xr pthread_mutexattr_setprioceiling 3 ,
588.Xr pthread_mutexattr_setprotocol 3 ,
589.Xr pthread_mutexattr_settype 3 ,
15acf97d
SW
590.Xr pthread_mutex_destroy 3 ,
591.Xr pthread_mutex_init 3 ,
592.Xr pthread_mutex_lock 3 ,
593.Xr pthread_mutex_trylock 3 ,
594.Xr pthread_mutex_unlock 3 ,
984263bc
MD
595.Xr pthread_once 3 ,
596.Xr pthread_rwlockattr_destroy 3 ,
597.Xr pthread_rwlockattr_getpshared 3 ,
598.Xr pthread_rwlockattr_init 3 ,
599.Xr pthread_rwlockattr_setpshared 3 ,
600.Xr pthread_rwlock_destroy 3 ,
601.Xr pthread_rwlock_init 3 ,
602.Xr pthread_rwlock_rdlock 3 ,
603.Xr pthread_rwlock_unlock 3 ,
604.Xr pthread_rwlock_wrlock 3 ,
605.Xr pthread_self 3 ,
606.Xr pthread_setcancelstate 3 ,
607.Xr pthread_setcanceltype 3 ,
608.Xr pthread_setspecific 3 ,
609.Xr pthread_testcancel 3
610.Sh STANDARDS
15acf97d
SW
611The functions with the
612.Nm pthread_
984263bc 613prefix and not
15acf97d 614.Nm _np
984263bc 615suffix or
15acf97d 616.Nm pthread_rwlock
984263bc
MD
617prefix conform to
618.St -p1003.1-96 .
619.Pp
15acf97d
SW
620The functions with the
621.Nm pthread_
984263bc 622prefix and
15acf97d 623.Nm _np
984263bc
MD
624suffix are non-portable extensions to POSIX threads.
625.Pp
15acf97d
SW
626The functions with the
627.Nm pthread_rwlock
984263bc
MD
628prefix are extensions created by The Open Group as part of the
629.St -susv2 .