MirOS Manual: pthreads(3)

PTHREADS(3)                BSD Programmer's Manual                 PTHREADS(3)

NAME

     pthreads - POSIX 1003.1c thread interface

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.

     In OpenBSD, threads are implemented in a user-level library. A program
     using these routines must be linked with the -pthread option.

     The 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 pro-
     cess' controlling tty and describes each thread's ID, state (see Thread
     states), current priority, flags (see Thread flags), signal mask, and
     name (as set by pthread_set_name_np(3)). If the environment variable
     PTHREAD_DEBUG is defined additional information is displayed.

     For the purpose of this document, the functions available are grouped in
     the following categories. For further information, see the individual man
     page for each function.

           -   Attribute Object Routines
           -   Cancellation Routines
           -   Condition Variable Routines
           -   Data Management Routines
           -   Mutex Routines
           -   Non Portable Extensions
           -   Read/Write Lock Routines
           -   Thread Routines

Attribute Object Routines

     The functions available are as follows:

     pthread_attr_init()            Initialise a threads attribute object.
     pthread_attr_destroy()         Destroy a threads attribute object.
     pthread_attr_getdetachstate()  Get detachstate attribute.
     pthread_attr_setdetachstate()  Set detachstate attribute.
     pthread_attr_getstackaddr()    Get stackaddr attribute.
     pthread_attr_setstackaddr()    Set stackaddr attribute.
     pthread_attr_getstacksize()    Get stacksize attribute.
     pthread_attr_setstacksize()    Set stacksize attribute.

Cancellation Routines

     The functions available are as follows:

     pthread_cancel()          Cancel execution of a thread.
     pthread_cleanup_pop()     Call the first cleanup routine.
     pthread_cleanup_push()    Add a cleanup function for thread exit.
     pthread_setcancelstate()  Set cancelability state.
     pthread_setcanceltype()   Set cancelability state.
     pthread_testcancel()      Set cancelability state.

Condition Variable Routines

     The functions available are as follows:

     pthread_cond_broadcast()  Unblock all threads waiting for a condition
                               variable.
     pthread_cond_destroy()    Destroy a condition variable.
     pthread_cond_init()       Create a condition variable.
     pthread_cond_signal()     Unblock a thread waiting for a condition vari-
                               able.
     pthread_cond_timedwait()  Wait on a condition variable for a specific
                               amount of time.
     pthread_cond_wait()       Wait on a condition variable.

Data Management Routines

     The functions available are as follows:

     pthread_getspecific()  Get a thread-specific data value.
     pthread_setspecific()  Set a thread-specific data value.
     pthread_key_create()   Thread-specific data key creation.
     pthread_key_delete()   Delete a thread-specific data key.

Mutex Routines

     The functions available are as follows:

     pthread_mutex_destroy()             Free resources allocated for a mutex.
     pthread_mutex_init()                Create a mutex.
     pthread_mutex_lock()                Lock a mutex.
     pthread_mutex_trylock()             Attempt to lock a mutex without
                                         blocking.
     pthread_mutex_unlock()              Unlock a mutex.
     pthread_mutexattr_init()            Mutex attribute operations.
     pthread_mutexattr_destroy()         Mutex attribute operations.
     pthread_mutexattr_getprioceiling()  Mutex attribute operations.
     pthread_mutexattr_setprioceiling()  Mutex attribute operations.
     pthread_mutexattr_getprotocol()     Mutex attribute operations.
     pthread_mutexattr_setprotocol()     Mutex attribute operations.
     pthread_mutexattr_gettype()         Mutex attribute operations.
     pthread_mutexattr_settype()         Mutex attribute operations.

Non Portable Extensions

     The functions available are as follows:

     pthread_main_np()         Identify the main thread.
     pthread_set_name_np()     Set the name of a thread.
     pthread_single_np()       Switch thread scheduling mode.
     pthread_multi_np()        Switch thread scheduling mode.
     pthread_stackseg_np()     Return stack size and location.
     pthread_suspend_np()      Suspend given thread.
     pthread_suspend_all_np()  Suspend all threads except current thread.
     pthread_resume_np()       Resumes given thread.
     pthread_resume_all_np()   Resumes all suspended threads.
     pthread_yield()           Yield control of the current thread.

Read/Write Lock Routines

     The functions available are as follows:

     pthread_rwlock_destroy()         Destroy a read/write lock.
     pthread_rwlock_init()            Initialise a read/write lock.
     pthread_rwlock_rdlock()          Acquire a read/write lock for reading.
     pthread_rwlock_unlock()          Release a read/write lock.
     pthread_rwlock_wrlock()          Acquire a read/write lock for writing.
     pthread_rwlockattr_destroy()     Destroy a read/write lock.
     pthread_rwlockattr_getpshared()  Get the process shared attribute.
     pthread_rwlockattr_init()        Initialise a read/write lock.
     pthread_rwlockattr_setpshared()  Set the process shared attribute.

Thread Routines

     The functions available are as follows:

     pthread_create()          Create a new thread.
     pthread_detach()          Detach a thread.
     pthread_equal()           Compare thread IDs.
     pthread_exit()            Terminate the calling thread.
     pthread_getconcurrency()  Get level of concurrency.
     pthread_setconcurrency()  Set level of concurrency.
     pthread_join()            Wait for thread termination.
     pthread_kill()            Send a signal to a specific thread.
     pthread_once()            Dynamic package initialisation.
     pthread_self()            Get the calling thread's ID.
     pthread_sigmask()         Examine/change a thread's signal mask.

Thread states

     Threads can be in one of these states:

           cond_wait     Executing pthread_cond_wait(3) or
                         pthread_cond_timedwait(3).
           dead          Waiting for resource deallocation by the thread gar-
                         bage collector.
           deadlock      Waiting for a resource held by the thread itself.
           fdlr_wait     File descriptor read lock wait.
           fdlw_wait     File descriptor write lock wait.
           fdr_wait      Executing one of accept(2), read(2), readv(2),
                         recvfrom(2), recvmsg(2).
           fdw_wait      Executing one of connect(2), sendmsg(2), sendto(2),
                         write(2), writev(2).
           file_wait     Executing flockfile(3) or similar.
           join          Executing pthread_join(3).
           mutex_wait    Executing pthread_mutex_lock(3).
           poll_wait     Executing poll(2).
           running       Scheduled for, or engaged in, program execution.
           select_wait   Executing select(2).
           sigsuspend    Executing sigsuspend(2).
           sigwait       Executing sigwait(3).
           sleep_wait    Executing sleep(3) or nanosleep(2).
           spinblock     Waiting for a machine-level atomic lock.
           suspended     Suspended with pthread_suspend_np(3) or
                         pthread_suspend_all_np(3).
           wait_wait     Executing wait4(2) or similar.

Thread flags

     The first three flags are one of:

           p    Private, system thread (e.g., the garbage collector).
           E, C, or c
                Thread is exiting (E), has a cancellation pending (C) (see
                pthread_cancel(3)), or is at a cancellation point (c).
           t    Thread is being traced.

     The next 7 flags refer to thread attributes:

           C    Thread is in the CONDQ.
           R    Thread is in the WORKQ.
           W    Thread is in the WAITQ.
           P    Thread is in the PRIOQ.
           d    Thread has been detached (see pthread_detach(3)).
           i    Thread inherits scheduler properties.
           f    Thread will save floating point context.

Scheduling algorithm

     The scheduling algorithm used by the user-level thread library is roughly
     as follows:

     1.   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.
     2.   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.
     3.   Choose the next run-enabled thread with the highest priority, that
          became inactive least recently, and has the largest remaining time
          slice.

     When all threads are blocked, the process also blocks. When there are no
     threads remaining, the process terminates with an exit code of zero.

Thread stacks

     Each thread has (or should have) a different stack, whether it be provid-
     ed 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 al-
     located in such a way that a SIGSEGV signal is delivered to the process
     when a stack overflows.

     Signals handlers are normally run on the stack of the currently executing
     thread. Hence, if you want to handle the SIGSEGV signal, you should make
     use of sigaltstack(2) or sigprocmask(2).

Thread safety

     The following functions are not thread safe:

     asctime(), basename(), catgets(), crypt(), ctime(), dbm_clearerr(),
     dbm_close(), dbm_delete(), dbm_error(), dbm_fetch(), dbm_firstkey(),
     dbm_nextkey(), dbm_open(), dbm_store(), dirname(), dlerror(), drand48(),
     ecvt(), encrypt(), endgrent(), endpwent(), fcvt(), ftw(), gcvt(),
     getc_unlocked(), getchar_unlocked(), getenv(), getgrent(), getgrgid(),
     getgrnam(), gethostbyaddr(), gethostbyname(), gethostent(), getlogin(),
     getnetbyaddr(), getnetbyname(), getnetent(), getopt(), getprotobyname(),
     getprotobynumber(), getprotoent(), getpwent(), getpwnam(), getpwuid(),
     getservbyname(), getservbyport(), getservent(), gmtime(), hcreate(),
     hdestroy(), hsearch(), inet_ntoa(), l64a(), lgamma(), lgammaf(), lo-
     caleconv(), localtime(), lrand48(), mrand48(), nftw(), nl_langinfo(),
     putc_unlocked(), putchar_unlocked(), putenv(), rand(), readdir(),
     setenv(), setgrent(), setkey(), setpwent(), strerror(), strtok(),
     ttyname(), unsetenv(),

     The ctermid() and tmpnam() functions are not thread safe when passed a
     NULL argument.

ENVIRONMENT

     PTHREAD_DEBUG     Enables verbose SIGINFO signal output.

     LIBPTHREAD_DEBUG  Display thread status every time the garbage collection
                       thread runs, approximately once every 10 seconds. The
                       status display verbosity is controlled by the
                       PTHREAD_DEBUG environment variable.

SEE ALSO

     pthread_attr_init(3), pthread_attr_setdetachstate(3),
     pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
     pthread_cancel(3), pthread_cleanup_pop(3), pthread_cleanup_push(3),
     pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3),
     pthread_cond_signal(3), pthread_cond_timedwait(3), pthread_cond_wait(3),
     pthread_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3),
     pthread_getspecific(3), pthread_join(3), pthread_key_create(3),
     pthread_key_delete(3), pthread_kill(3), pthread_main_np(3),
     pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3),
     pthread_mutex_trylock(3), pthread_mutex_unlock(3), pthread_mutexattr(3),
     pthread_once(3), pthread_resume_all_np(3), pthread_resume_np(3),
     pthread_rwlock_destroy(3), pthread_rwlock_init(3),
     pthread_rwlock_rdlock(3), pthread_rwlock_unlock(3),
     pthread_rwlock_wrlock(3), pthread_rwlockattr_destroy(3),
     pthread_rwlockattr_getpshared(3), pthread_rwlockattr_init(3),
     pthread_rwlockattr_setpshared(3), pthread_schedparam(3), pthread_self(3),
     pthread_set_name_np(3), pthread_setspecific(3), pthread_sigmask(3),
     pthread_single_np(3), pthread_stackseg_np(3), pthread_suspend_all_np(3),
     pthread_suspend_np(3), pthread_testcancel(3), pthread_yield(3)

STANDARDS

     The user-level thread library provides functions that conform to ISO/IEC
     9945-1 ANSI/IEEE ("POSIX") Std 1003.1 Second Edition 1996-07-12.

AUTHORS

     John Birrell (jb@freebsd.org) wrote the majority of the user level thread
     library.

BUGS

     The library contains a scheduler that uses the process virtual interval
     timer to pre-empt running threads. This means that using setitimer(2) to
     alter the process virtual timer will have undefined effects. The
     SIGVTALRM will never be delivered to threads in a process.

     Some pthread functions fail to work correctly when linked using the -g
     option to cc(1) or gcc(1). The problems do not occur when linked using
     the -ggdb option.

MirOS BSD #10-current          August 17, 1998                               4

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.