Add an ffs(5) manual page.
[dragonfly.git] / share / man / man3 / pthread.3
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: src/share/man/man3/pthread.3,v 1.12.2.6 2002/03/25 08:28:18 maxim Exp $
32 .\" $DragonFly: src/share/man/man3/pthread.3,v 1.5 2007/09/14 19:47:03 swildner Exp $
33 .\"
34 .Dd September 10, 1998
35 .Dt PTHREAD 3
36 .Os
37 .Sh NAME
38 .Nm pthread
39 .Nd POSIX thread functions
40 .Sh LIBRARY
41 .Lb libc_r
42 .Sh SYNOPSIS
43 .In pthread.h
44 .Sh DESCRIPTION
45 POSIX threads are a set of functions that support applications with
46 requirements for multiple flows of control, called
47 .Fa threads ,
48 within a process.
49 Multithreading is used to improve the performance of a
50 program.
51 .Pp
52 The POSIX thread functions are summarized in this section in the following
53 groups:
54 .Bl -bullet -offset indent
55 .It
56 Thread Routines
57 .It
58 Attribute Object Routines
59 .It
60 Mutex Routines
61 .It
62 Condition Variable Routines
63 .It
64 Read/Write Lock Routines
65 .It
66 Per-Thread Context Routines
67 .It
68 Cleanup Routines
69 .El
70 .Sh THREAD ROUTINES
71 .Bl -tag -width Er
72 .It Xo
73 .Ft int
74 .Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
75 .Xc
76 Creates a new thread of execution.
77 .It Xo
78 .Ft int
79 .Fn pthread_cancel "pthread_t thread"
80 .Xc
81 Cancels execution of a thread.
82 .It Xo
83 .Ft int
84 .Fn pthread_detach "pthread_t thread"
85 .Xc
86 Marks a thread for deletion.
87 .It Xo
88 .Ft int
89 .Fn pthread_equal "pthread_t t1" "pthread_t t2"
90 .Xc
91 Compares two thread IDs.
92 .It Xo
93 .Ft void
94 .Fn pthread_exit "void *value_ptr"
95 .Xc
96 Terminates the calling thread.
97 .It Xo
98 .Ft int
99 .Fn pthread_join "pthread_t thread" "void **value_ptr"
100 .Xc
101 Causes the calling thread to wait for the termination of the specified thread.
102 .It Xo
103 .Ft int
104 .Fn pthread_kill "pthread_t thread" "int sig"
105 .Xc
106 Delivers a signal to a specified thread.
107 .It Xo
108 .Ft int
109 .Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
110 .Xc
111 Calls an initialization routine once.
112 .It Xo
113 .Ft pthread_t
114 .Fn pthread_self void
115 .Xc
116 Returns the thread ID of the calling thread.
117 .It Xo
118 .Ft int
119 .Fn pthread_setcancelstate "int state" "int *oldstate"
120 .Xc
121 Sets the current thread's cancelability state.
122 .It Xo
123 .Ft int
124 .Fn pthread_setcanceltype "int type" "int *oldtype"
125 .Xc
126 Sets the current thread's cancelability type.
127 .It Xo
128 .Ft void
129 .Fn pthread_testcancel void
130 .Xc
131 Creates a cancellation point in the calling thread.
132 .It Xo
133 .Ft void
134 .Fn pthread_yield void
135 .Xc
136 Allows the scheduler to run another thread instead of the current one.
137 .El
138 .Sh ATTRIBUTE OBJECT ROUTINES
139 .Bl -tag -width Er
140 .It Xo
141 .Ft int
142 .Fn pthread_attr_destroy "pthread_attr_t *attr"
143 .Xc
144 Destroy a thread attributes object.
145 .It Xo
146 .Ft int
147 .Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched"
148 .Xc
149 Get the inherit scheduling attribute from a thread attributes object.
150 .It Xo
151 .Ft int
152 .Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param"
153 .Xc
154 Get the scheduling parameter attribute from a thread attributes object.
155 .It Xo
156 .Ft int
157 .Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy"
158 .Xc
159 Get the scheduling policy attribute from a thread attributes object.
160 .It Xo
161 .Ft int
162 .Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope"
163 .Xc
164 Get the contention scope attribute from a thread attributes object.
165 .It Xo
166 .Ft int
167 .Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize"
168 .Xc
169 Get the stack size attribute from a thread attributes object.
170 .It Xo
171 .Ft int
172 .Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr"
173 .Xc
174 Get the stack address attribute from a thread attributes object.
175 .It Xo
176 .Ft int
177 .Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate"
178 .Xc
179 Get the detach state attribute from a thread attributes object.
180 .It Xo
181 .Ft int
182 .Fn pthread_attr_init "pthread_attr_t *attr"
183 .Xc
184 Initialize a thread attributes object with default values.
185 .It Xo
186 .Ft int
187 .Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
188 .Xc
189 Set the inherit scheduling attribute in a thread attributes object.
190 .It Xo
191 .Ft int
192 .Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param"
193 .Xc
194 Set the scheduling parameter attribute in a thread attributes object.
195 .It Xo
196 .Ft int
197 .Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
198 .Xc
199 Set the scheduling policy attribute in a thread attributes object.
200 .It Xo
201 .Ft int
202 .Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
203 .Xc
204 Set the contention scope attribute in a thread attributes object.
205 .It Xo
206 .Ft int
207 .Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
208 .Xc
209 Set the stack size attribute in a thread attributes object.
210 .It Xo
211 .Ft int
212 .Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
213 .Xc
214 Set the stack address attribute in a thread attributes object.
215 .It Xo
216 .Ft int
217 .Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
218 .Xc
219 Set the detach state in a thread attributes object.
220 .El
221 .Sh MUTEX ROUTINES
222 .Bl -tag -width Er
223 .It Xo
224 .Ft int
225 .Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
226 .Xc
227 Destroy a mutex attributes object.
228 .It Xo
229 .Ft int
230 .Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling"
231 .Xc
232 Obtain priority ceiling attribute of mutex attribute object.
233 .It Xo
234 .Ft int
235 .Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
236 .Xc
237 Obtain protocol attribute of mutex attribute object.
238 .It Xo
239 .Ft int
240 .Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
241 .Xc
242 Obtain the mutex type attribute in the specified mutex attributes object.
243 .It Xo
244 .Ft int
245 .Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
246 .Xc
247 Initialize a mutex attributes object with default values.
248 .It Xo
249 .Ft int
250 .Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling"
251 .Xc
252 Set priority ceiling attribute of mutex attribute object.
253 .It Xo
254 .Ft int
255 .Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
256 .Xc
257 Set protocol attribute of mutex attribute object.
258 .It Xo
259 .Ft int
260 .Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
261 .Xc
262 Set the mutex type attribute that is used when a mutex is created.
263 .It Xo
264 .Ft int
265 .Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
266 .Xc
267 Destroy a mutex.
268 .It Xo
269 .Ft int
270 .Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
271 .Xc
272 Initialize a mutex with specified attributes.
273 .It Xo
274 .Ft int
275 .Fn pthread_mutex_lock "pthread_mutex_t *mutex"
276 .Xc
277 Lock a mutex and block until it becomes available.
278 .It Xo
279 .Ft int
280 .Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
281 .Xc
282 Try to lock a mutex, but don't block if the mutex is locked by another thread,
283 including the current thread.
284 .It Xo
285 .Ft int
286 .Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
287 .Xc
288 Unlock a mutex.
289 .El
290 .Sh CONDITION VARIABLE ROUTINES
291 .Bl -tag -width Er
292 .It Xo
293 .Ft int
294 .Fn pthread_condattr_destroy "pthread_condattr_t *attr"
295 .Xc
296 Destroy a condition variable attributes object.
297 .It Xo
298 .Ft int
299 .Fn pthread_condattr_init "pthread_condattr_t *attr"
300 .Xc
301 Initialize a condition variable attributes object with default values.
302 .It Xo
303 .Ft int
304 .Fn pthread_cond_broadcast "pthread_cond_t *cond"
305 .Xc
306 Unblock all threads currently blocked on the specified condition variable.
307 .It Xo
308 .Ft int
309 .Fn pthread_cond_destroy "pthread_cond_t *cond"
310 .Xc
311 Destroy a condition variable.
312 .It Xo
313 .Ft int
314 .Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
315 .Xc
316 Initialize a condition variable with specified attributes.
317 .It Xo
318 .Ft int
319 .Fn pthread_cond_signal "pthread_cond_t *cond"
320 .Xc
321 Unblock at least one of the threads blocked on the specified condition variable.
322 .It Xo
323 .Ft int
324 .Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
325 .Xc
326 Wait no longer than the specified time for a condition and lock the specified mutex.
327 .It Xo
328 .Ft int
329 .Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
330 .Xc
331 Wait for a condition and lock the specified mutex.
332 .El
333 .Sh READ/WRITE LOCK ROUTINES
334 .Bl -tag -width Er
335 .It Xo
336 .Ft int
337 .Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
338 .Xc
339 Destroy a read/write lock object.
340 .It Xo
341 .Ft int
342 .Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
343 .Xc
344 Initialize a read/write lock object.
345 .It Xo
346 .Ft int
347 .Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
348 .Xc
349 Lock a read/write lock for reading, blocking until the lock can be
350 acquired.
351 .It Xo
352 .Ft int
353 .Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
354 .Xc
355 Attempt to lock a read/write lock for reading, without blocking if the
356 lock is unavailable.
357 .It Xo
358 .Ft int
359 .Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
360 .Xc
361 Attempt to lock a read/write lock for writing, without blocking if the
362 lock is unavailable.
363 .It Xo
364 .Ft int
365 .Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
366 .Xc
367 Unlock a read/write lock.
368 .It Xo
369 .Ft int
370 .Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
371 .Xc
372 Lock a read/write lock for writing, blocking until the lock can be
373 acquired.
374 .It Xo
375 .Ft int
376 .Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
377 .Xc
378 Destroy a read/write lock attribute object.
379 .It Xo
380 .Ft int
381 .Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared"
382 .Xc
383 Retrieve the process shared setting for the read/write lock attribute
384 object.
385 .It Xo
386 .Ft int
387 .Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
388 .Xc
389 Initialize a read/write lock attribute object.
390 .It Xo
391 .Ft int
392 .Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared"
393 .Xc
394 Set the process shared setting for the read/write lock attribute object.
395 .El
396 .Sh PER-THREAD CONTEXT ROUTINES
397 .Bl -tag -width Er
398 .It Xo
399 .Ft int
400 .Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
401 .Xc
402 Create a thread-specific data key.
403 .It Xo
404 .Ft int
405 .Fn pthread_key_delete "pthread_key_t key"
406 .Xc
407 Delete a thread-specific data key.
408 .It Xo
409 .Ft "void *"
410 .Fn pthread_getspecific "pthread_key_t key"
411 .Xc
412 Get the thread-specific value for the specified key.
413 .It Xo
414 .Ft int
415 .Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
416 .Xc
417 Set the thread-specific value for the specified key.
418 .El
419 .Sh CLEANUP ROUTINES
420 .Bl -tag -width Er
421 .It Xo
422 .Ft void
423 .Fn pthread_cleanup_pop "int execute"
424 .Xc
425 Remove the routine at the top of the calling thread's cancellation cleanup
426 stack and optionally invoke it.
427 .It Xo
428 .Ft void
429 .Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
430 .Xc
431 Push the specified cancellation cleanup handler onto the calling thread's
432 cancellation stack.
433 .El
434 .Sh INSTALLATION
435 The current
436 .Dx
437 POSIX thread implementation is built in the library
438 .Fa libc_r
439 which contains both thread-safe libc functions and the thread functions.
440 This library replaces
441 .Fa libc
442 for threaded applications.
443 .Pp
444 By default,
445 .Fa libc_r
446 is built as part of a 'make world'.  To disable the build of
447 .Fa libc_r
448 you must supply the '-DNOLIBC_R' option to
449 .Xr make 1 .
450 .Pp
451 A
452 .Fx
453 and
454 .Dx
455 specific option exists in
456 .Xr gcc 1
457 to simplify the linking of threaded processes.
458 .Fa gcc -pthread
459 links a threaded process against
460 .Fa libc_r
461 instead of
462 .Fa libc .
463 .Sh SEE ALSO
464 .Xr pthread_cleanup_pop 3 ,
465 .Xr pthread_cleanup_push 3 ,
466 .Xr pthread_cond_broadcast 3 ,
467 .Xr pthread_cond_destroy 3 ,
468 .Xr pthread_cond_init 3 ,
469 .Xr pthread_cond_signal 3 ,
470 .Xr pthread_cond_timedwait 3 ,
471 .Xr pthread_cond_wait 3 ,
472 .Xr pthread_condattr_destroy 3 ,
473 .Xr pthread_condattr_init 3 ,
474 .Xr pthread_create 3 ,
475 .Xr pthread_detach 3 ,
476 .Xr pthread_equal 3 ,
477 .Xr pthread_exit 3 ,
478 .Xr pthread_getspecific 3 ,
479 .Xr pthread_join 3 ,
480 .Xr pthread_key_delete 3 ,
481 .Xr pthread_kill 3 ,
482 .Xr pthread_mutex_destroy 3 ,
483 .Xr pthread_mutex_init 3 ,
484 .Xr pthread_mutex_lock 3 ,
485 .Xr pthread_mutex_trylock 3 ,
486 .Xr pthread_mutex_unlock 3 ,
487 .Xr pthread_mutexattr_destroy 3 ,
488 .Xr pthread_mutexattr_getprioceiling 3 ,
489 .Xr pthread_mutexattr_getprotocol 3 ,
490 .Xr pthread_mutexattr_gettype 3 ,
491 .Xr pthread_mutexattr_init 3 ,
492 .Xr pthread_mutexattr_setprioceiling 3 ,
493 .Xr pthread_mutexattr_setprotocol 3 ,
494 .Xr pthread_mutexattr_settype 3 ,
495 .Xr pthread_once 3 ,
496 .Xr pthread_rwlockattr_destroy 3 ,
497 .Xr pthread_rwlockattr_getpshared 3 ,
498 .Xr pthread_rwlockattr_init 3 ,
499 .Xr pthread_rwlockattr_setpshared 3 ,
500 .Xr pthread_rwlock_destroy 3 ,
501 .Xr pthread_rwlock_init 3 ,
502 .Xr pthread_rwlock_rdlock 3 ,
503 .Xr pthread_rwlock_unlock 3 ,
504 .Xr pthread_rwlock_wrlock 3 ,
505 .Xr pthread_self 3 ,
506 .Xr pthread_setcancelstate 3 ,
507 .Xr pthread_setcanceltype 3 ,
508 .Xr pthread_setspecific 3 ,
509 .Xr pthread_testcancel 3
510 .Sh STANDARDS
511 The functions in
512 .Fa libc_r
513 with the
514 .Fa pthread_
515 prefix and not
516 .Fa _np
517 suffix or
518 .Fa pthread_rwlock
519 prefix conform to
520 .St -p1003.1-96 .
521 .Pp
522 The functions in libc_r with the
523 .Fa pthread_
524 prefix and
525 .Fa _np
526 suffix are non-portable extensions to POSIX threads.
527 .Pp
528 The functions in libc_r with the
529 .Fa pthread_rwlock
530 prefix are extensions created by The Open Group as part of the
531 .St -susv2 .