*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> pthreads (3)              



NAME    [Toc]    [Back]

     pthreads - POSIX 1003.1c thread interface

DESCRIPTION    [Toc]    [Back]

     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
     process'  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
     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    [Toc]    [Back]
     The functions available are as follows:

     pthread_attr_init()              Initialise  a  threads  attribute object.
     pthread_attr_destroy()         Destroy a  threads  attribute
     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    [Toc]    [Back]
     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
     pthread_setcancelstate()  Set cancelability state.
     pthread_setcanceltype()   Set cancelability state.
     pthread_testcancel()      Set cancelability state.

   Condition Variable Routines    [Toc]    [Back]
     The functions available are as follows:

     pthread_cond_broadcast()  Unblock all threads waiting for  a
     pthread_cond_destroy()    Destroy a condition variable.
     pthread_cond_init()       Create a condition variable.
     pthread_cond_signal()      Unblock  a  thread  waiting for a
condition variable.

     pthread_cond_timedwait()  Wait on a condition variable for a
                               amount of time.
     pthread_cond_wait()       Wait on a condition variable.

   Data Management Routines    [Toc]    [Back]
     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    [Toc]    [Back]
     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
     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    [Toc]    [Back]
     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
     pthread_resume_np()       Resumes given thread.
     pthread_resume_all_np()   Resumes all suspended threads.
     pthread_yield()            Yield  control  of  the   current

   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
     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
     pthread_rwlockattr_setpshared()   Set the process shared attribute.

   Thread Routines    [Toc]    [Back]
     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
     pthread_once()            Dynamic package initialisation.
     pthread_self()            Get the calling thread's ID.
     pthread_sigmask()          Examine/change  a thread's signal

   Thread states    [Toc]    [Back]
     Threads can be in one of these states:

           cond_wait     Executing pthread_cond_wait(3) or
           dead          Waiting for resource deallocation by the
                         garbage 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),
                         recvfrom(2), recvmsg(2).
           fdw_wait      Executing one of connect(2), sendmsg(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
           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
           wait_wait     Executing wait4(2) or similar.

   Thread flags    [Toc]    [Back]
     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
           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    [Toc]    [Back]
     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

     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    [Toc]    [Back]
     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.
 stacks (including that of the  initial  thread)  are
typically allocated
  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    [Toc]    [Back]
     The following functions are not thread safe:

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

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

ENVIRONMENT    [Toc]    [Back]

     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
                       PTHREAD_DEBUG environment variable.

SEE ALSO    [Toc]    [Back]

     pthread_attr_init(3), pthread_attr_setdetachstate(3),
     pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
     pthread_cancel(3),                   pthread_cleanup_pop(3),
     pthread_cond_broadcast(3),          pthread_cond_destroy(3),
     pthread_cond_signal(3),           pthread_cond_timedwait(3),
     pthread_create(3),   pthread_detach(3),    pthread_equal(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_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_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),

STANDARDS    [Toc]    [Back]

     The user-level thread library provides functions  that  conform to ISO/IEC
     9945-1  ANSI/IEEE  (``POSIX'')  Std  1003.1  Second  Edition

AUTHORS    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     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.
     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.

OpenBSD     3.6                         August      17,      1998
[ Back ]
 Similar pages
Name OS Title
re_format OpenBSD POSIX 1003.2 regular expressions
regex Linux POSIX 1003.2 regular expressions
re_format FreeBSD POSIX 1003.2 regular expressions
POSIX IRIX Perl interface to IEEE Std 1003.1
pthread FreeBSD POSIX thread functions
pthreads IRIX introduction to POSIX thread characteristics
sigpending IRIX return set of signals pending for thread (POSIX)
termios Tru64 Defines the structure of the termios file, which provides the terminal interface for POSIX compatibi...
termios.h Tru64 Defines the structure of the termios file, which provides the terminal interface for POSIX compatibi...
pipcrm HP-UX remove a POSIX message queue or a POSIX named semaphore
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service