.\" $OpenBSD: pthreads.3,v 1.18 2002/05/01 08:03:30 mpech Exp $ .\" David Leonard , 1998. Public domain. .Dd August 17, 1998 .Dt PTHREADS 3 .Os .Sh NAME .Nm pthreads .Nd POSIX 1003.1c thread interface .Sh DESCRIPTION A thread is a flow of control within a process. Each thread represents a minimal amount of state; normally just the cpu state and a signal mask. All other process state (such as memory, file descriptors) is shared among all of the threads in the process. .Pp In .Ox , threads are implemented in a user-level library. A program using these routines must be linked with the .Fl pthread option. .Pp The .Dv SIGINFO signal can be sent to a threaded process to have the library show the state of all of its threads. The information is sent to the process' controlling tty and describes each thread's ID, state (see .Sx Thread states ) , current priority, flags (see .Sx Thread flags ) , signal mask, and name (as set by .Xr pthread_set_name_np 3 ) . If the environment variable .Ev PTHREAD_DEBUG is defined additional information is displayed. .Ss Thread states Threads can be in one of these states: .Bl -tag -offset indent -width Dv -compact .It cond_wait Executing .Xr pthread_cond_wait 3 or .Xr pthread_cond_timedwait 3 . .It dead Waiting for resource deallocation by the thread garbage collector. .It deadlock Waiting for a resource held by the thread itself. .It fdlr_wait File descriptor read lock wait. .It fdlw_wait File descriptor write lock wait. .It fdr_wait Executing one of .Xr accept 2 , .Xr read 2 , .Xr readv 2 , .Xr recvfrom 2 , .Xr recvmsg 2 . .It fdw_wait Executing one of .Xr connect 2 , .Xr sendmsg 2 , .Xr sendto 2 , .Xr write 2 , .Xr writev 2 . .It file_wait Executing .Xr flockfile 3 or similar. .It join Executing .Xr pthread_join 3 . .It mutex_wait Executing .Xr pthread_mutex_lock 3 . .It poll_wait Executing .Xr poll 2 . .It running Scheduled for, or engaged in, program execution. .It select_wait Executing .Xr select 2 . .It sigsuspend Executing .Xr sigsuspend 2 . .It sigwait Executing .Xr sigwait 3 . .It sleep_wait Executing .Xr sleep 3 or .Xr nanosleep 2 . .It spinblock Waiting for a machine-level atomic lock. .It suspended Suspended with .Xr pthread_suspend_np 3 . .It wait_wait Executing .Xr wait4 2 or similar. .El .Ss Thread flags The first three flags are one of: .Bl -tag -offset indent -width 3en -compact .It "p" Private, system thread (e.g., the garbage collector). .It "E, C, or c" Thread is exiting (E), has a cancellation pending (C) (see .Xr pthread_cancel 3 ) , or is at a cancellation point (c). .It "t" Thread is being traced. .El The next 7 flags refer to thread attributes: .Bl -tag -offset indent -width 3en -compact .It "C" Thread is in the .Dv CONDQ . .It "R" Thread is in the .Dv WORKQ . .It "W" Thread is in the .Dv WAITQ . .It "P" Thread is in the .Dv PRIOQ . .It "d" Thread has been detached (see .Xr pthread_detach 3 ) . .It "i" Thread inherits scheduler properties. .It "f" Thread will save floating point context. .El .Ss Scheduling algorithm The scheduling algorithm used by the user-level thread library is roughly as follows: .Bl -enum -compact .It Threads each have a time slice credit which is debited by the actual time the thread spends in running. Freshly scheduled threads are given a time slice credit of 100000 usec. .It Give an incremental priority update to run-enabled threads that have not run since the last time that an incremental priority update was given to them. .It Choose the next run-enabled thread with the highest priority, that became inactive least recently, and has the largest remaining time slice. .El .Pp When all threads are blocked, the process also blocks. When there are no threads remaining, the process terminates with an exit code of zero. .Ss Thread stacks Each thread has (or should have) a different stack, whether it be provided by a user attribute, or provided automatically by the system. If a thread overflows its stack, unpredictable results may occur. System-allocated stacks (including that of the initial thread) are typically allocated in such a way that a .Dv SIGSEGV signal is delivered to the process when a stack overflows. .Pp Signals handlers are normally run on the stack of the currently executing thread. Hence, if you want to handle the .Dv SIGSEGV signal, you should make use of .Xr sigaltstack 2 or .Xr sigprocmask 2 . .Sh ENVIRONMENT .Bl -tag -width "PTHREAD_DEBUG" .It Ev PTHREAD_DEBUG Enables verbose .Dv SIGINFO signal output. .It Ev LIBC_R_DEBUG Display thread status every time the garbage collection thread runs, approximately once every 10 seconds. The status display verbosity is controled by the .Ev PTHREAD_DEBUG environment variable. .El .Sh SEE ALSO .Xr pthread_cleanup_pop 3 , .Xr pthread_cleanup_push 3 , .Xr pthread_cond_broadcast 3 , .Xr pthread_cond_destroy 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_signal 3 , .Xr pthread_cond_timedwait 3 , .Xr pthread_cond_wait 3 , .Xr pthread_create 3 , .Xr pthread_detach 3 , .Xr pthread_equal 3 , .Xr pthread_exit 3 , .Xr pthread_getspecific 3 , .Xr pthread_join 3 , .Xr pthread_key_create 3 , .Xr pthread_key_delete 3 , .Xr pthread_kill 3 , .Xr pthread_mutex_destroy 3 , .Xr pthread_mutex_init 3 , .Xr pthread_mutex_lock 3 , .Xr pthread_mutex_trylock 3 , .Xr pthread_mutex_unlock 3 , .Xr pthread_once 3 , .Xr pthread_rwlock_destroy 3 , .Xr pthread_rwlock_init 3 , .Xr pthread_rwlock_rdlock 3 , .Xr pthread_rwlock_unlock 3 , .Xr pthread_rwlock_wrlock 3 , .Xr pthread_rwlockattr_destroy 3 , .Xr pthread_rwlockattr_getpshared 3 , .Xr pthread_rwlockattr_init 3 , .Xr pthread_rwlockattr_setpshared 3 , .Xr pthread_self 3 , .Xr pthread_setspecific 3 .Sh STANDARDS The user-level thread library provides functions that conform to ISO/IEC 9945-1 ANSI/IEEE .Pq Dq Tn POSIX Std 1003.1 Second Edition 1996-07-12. .Sh AUTHORS John Birrell .Pa ( jb@freebsd.org ) wrote the majority of the user level thread library. .\" David Leonard did a fair bit too, but is far too modest. .Sh BUGS The library contains a scheduler that uses the process virtual interval timer to pre-empt running threads. This means that using .Xr setitimer 2 to alter the process virtual timer will have undefined effects. The .Dv SIGVTALRM will never be delivered to threads in a process. .Pp Some pthread functions fail to work correctly when linked using the .Fl g option to .Xr cc 1 or .Xr gcc 1 . The problems do not occur when linked using the .Fl ggdb option.