xref: /freebsd/share/man/man3/pthread.3 (revision 6b7b2d80ed4d728d3ffd12c422e57798c1b63a84)
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.\"
31.\" $FreeBSD$
32.\"
33.Dd August 12, 2014
34.Dt PTHREAD 3
35.Os
36.Sh NAME
37.Nm pthread
38.Nd POSIX thread functions
39.Sh LIBRARY
40.Lb libpthread
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
46.Em threads ,
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:
53.Pp
54.Bl -bullet -offset indent -compact
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
70.Ss Thread Routines
71.Bl -tag -width indent
72.It Xo
73.Ft int
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
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
112.Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]"
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
141.Ss Attribute Object Routines
142.Bl -tag -width indent
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
150.Fo pthread_attr_getinheritsched
151.Fa "const pthread_attr_t *attr" "int *inheritsched"
152.Fc
153.Xc
154Get the inherit scheduling attribute from a thread attributes object.
155.It Xo
156.Ft int
157.Fo pthread_attr_getschedparam
158.Fa "const pthread_attr_t *attr" "struct sched_param *param"
159.Fc
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
199.Fo pthread_attr_setschedparam
200.Fa "pthread_attr_t *attr" "const struct sched_param *param"
201.Fc
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
230.Ss Mutex Routines
231.Bl -tag -width indent
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
279.Fo pthread_mutex_init
280.Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
281.Fc
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
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
298.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
299.Xc
300Try to lock a mutex, but do not block if the mutex is locked by another thread,
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
308.Ss Condition Variable Routines
309.Bl -tag -width indent
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
342.Fo pthread_cond_timedwait
343.Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex"
344.Fa "const struct timespec *abstime"
345.Fc
346.Xc
347Unlock the specified mutex, wait no longer than the specified time for
348a condition, and then relock the mutex.
349.It Xo
350.Ft int
351.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
352.Xc
353Unlock the specified mutex, wait for a condition, and relock the mutex.
354.El
355.Ss Read/Write Lock Routines
356.Bl -tag -width indent
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
364.Fo pthread_rwlock_init
365.Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
366.Fc
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
405.Fo pthread_rwlockattr_getpshared
406.Fa "const pthread_rwlockattr_t *attr" "int *pshared"
407.Fc
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
422.Ss Per-Thread Context Routines
423.Bl -tag -width indent
424.It Xo
425.Ft int
426.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]"
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
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.
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
464.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg"
465.Xc
466Push the specified cancellation cleanup handler onto the calling thread's
467cancellation stack.
468.El
469.Sh IMPLEMENTATION NOTES
470The current
471.Fx
472POSIX thread implementation is built into the
473.Lb libthr
474library.
475It contains thread-safe versions of
476.Lb libc
477functions and the thread functions.
478Threaded applications are linked with this library.
479.Sh SEE ALSO
480.Xr libthr 3 ,
481.Xr pthread_affinity_np 3 ,
482.Xr pthread_atfork 3 ,
483.Xr pthread_attr 3 ,
484.Xr pthread_cancel 3 ,
485.Xr pthread_cleanup_pop 3 ,
486.Xr pthread_cleanup_push 3 ,
487.Xr pthread_cond_broadcast 3 ,
488.Xr pthread_cond_destroy 3 ,
489.Xr pthread_cond_init 3 ,
490.Xr pthread_cond_signal 3 ,
491.Xr pthread_cond_timedwait 3 ,
492.Xr pthread_cond_wait 3 ,
493.Xr pthread_condattr_destroy 3 ,
494.Xr pthread_condattr_init 3 ,
495.Xr pthread_create 3 ,
496.Xr pthread_detach 3 ,
497.Xr pthread_equal 3 ,
498.Xr pthread_exit 3 ,
499.Xr pthread_getspecific 3 ,
500.Xr pthread_join 3 ,
501.Xr pthread_key_delete 3 ,
502.Xr pthread_kill 3 ,
503.Xr pthread_mutex_destroy 3 ,
504.Xr pthread_mutex_init 3 ,
505.Xr pthread_mutex_lock 3 ,
506.Xr pthread_mutex_trylock 3 ,
507.Xr pthread_mutex_unlock 3 ,
508.Xr pthread_mutexattr_destroy 3 ,
509.Xr pthread_mutexattr_getprioceiling 3 ,
510.Xr pthread_mutexattr_getprotocol 3 ,
511.Xr pthread_mutexattr_gettype 3 ,
512.Xr pthread_mutexattr_init 3 ,
513.Xr pthread_mutexattr_setprioceiling 3 ,
514.Xr pthread_mutexattr_setprotocol 3 ,
515.Xr pthread_mutexattr_settype 3 ,
516.Xr pthread_once 3 ,
517.Xr pthread_rwlock_destroy 3 ,
518.Xr pthread_rwlock_init 3 ,
519.Xr pthread_rwlock_rdlock 3 ,
520.Xr pthread_rwlock_unlock 3 ,
521.Xr pthread_rwlock_wrlock 3 ,
522.Xr pthread_rwlockattr_destroy 3 ,
523.Xr pthread_rwlockattr_getpshared 3 ,
524.Xr pthread_rwlockattr_init 3 ,
525.Xr pthread_rwlockattr_setpshared 3 ,
526.Xr pthread_self 3 ,
527.Xr pthread_setcancelstate 3 ,
528.Xr pthread_setcanceltype 3 ,
529.Xr pthread_setspecific 3 ,
530.Xr pthread_testcancel 3
531.Sh STANDARDS
532The functions with the
533.Nm pthread_
534prefix and not
535.Nm _np
536suffix or
537.Nm pthread_rwlock
538prefix conform to
539.St -p1003.1-96 .
540.Pp
541The functions with the
542.Nm pthread_
543prefix and
544.Nm _np
545suffix are non-portable extensions to POSIX threads.
546.Pp
547The functions with the
548.Nm pthread_rwlock
549prefix are extensions created by The Open Group as part of the
550.St -susv2 .
551