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 use a 1-to-1 implementation, where every thread is independently scheduled by the kernel.

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
-   Barrier Routines
-   Cleanup Routines
-   Condition Variable Routines
-   Mutex Routines
-   Non Portable Extensions
-   Per-Thread Context Routines
-   Read/Write Lock Routines
-   Spinlock 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_getstack()
    Get stackaddr and stacksize attributes.
pthread_attr_setstack()
    Set stackaddr and stacksize attributes.
pthread_attr_getstackaddr()
    Get stackaddr attribute.
pthread_attr_setstackaddr()
    Set stackaddr attribute.
pthread_attr_getstacksize()
    Get stacksize attribute.
pthread_attr_setstacksize()
    Set stacksize attribute.
pthread_attr_getguardsize()
    Get guardsize attribute.
pthread_attr_setguardsize()
    Set guardsize attribute.

  Barrier Routines
The functions available are as follows:

pthread_barrier_init()
    Initialize a barrier object.
pthread_barrier_destroy()
    Destroy a barrier object.
pthread_barrier_wait()
    Synchronize at a barrier.
pthread_barrierattr_init()
    Initialize a barrier's attribute object.
pthread_barrierattr_destroy()
    Destroy a barrier's attribute object.
pthread_barrierattr_getpshared()
    Get the process-shared attribute of the barrier attribute's object.
pthread_barrierattr_setpshared()
    Set the process-shared attribute of the barrier attribute's object.

  Cleanup Routines
The functions available are as follows:

pthread_atfork()
    Register fork handlers.
pthread_cleanup_pop()
    Call the first cleanup routine.
pthread_cleanup_push()
    Add a cleanup function for thread exit.

  Condition Variable Routines
The functions available are as follows:

pthread_cond_init()
    Create a condition variable.
pthread_cond_destroy()
    Destroy a condition variable.
pthread_cond_broadcast()
    Unblock all threads waiting for a condition variable.
pthread_cond_signal()
    Unblock a thread waiting for a condition variable.
pthread_cond_timedwait()
    Wait on a condition variable until a specific point in time.
pthread_cond_wait()
    Wait on a condition variable.
pthread_condattr_init()
    Initialise a condition variable attribute object.
pthread_condattr_destroy()
    Destroy a condition variable attribute object.
pthread_condattr_getclock()
    Get clock attribute.
pthread_condattr_setclock()
    Set clock attribute.

  Mutex Routines
The functions available are as follows:

pthread_mutex_init()
    Create a mutex.
pthread_mutex_destroy()
    Free resources allocated for a mutex.
pthread_mutex_lock()
    Lock a mutex.
pthread_mutex_timedlock()
    Attempt to lock a mutex before a specific point in time.
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_get_name_np()
    Get the name of a thread.
pthread_stackseg_np()
    Return stack size and location.
pthread_yield()
    Yield control of the current thread.

  Per-Thread Context Routines
The functions available are as follows:

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

  Read/Write Lock Routines
The functions available are as follows:

pthread_rwlock_init()
    Initialise a read/write lock.
pthread_rwlock_destroy()
    Destroy a read/write lock.
pthread_rwlock_rdlock()
    Acquire a read/write lock for reading.
pthread_rwlock_timedrdlock()
    Attempt to acquire a read/write lock for reading before a specific point in time.
pthread_rwlock_tryrdlock()
    Attempt to acquire a read/write lock for reading without blocking.
pthread_rwlock_wrlock()
    Acquire a read/write lock for writing.
pthread_rwlock_timedwrlock()
    Attempt to acquire a read/write lock for writing before a specific point in time.
pthread_rwlock_trywrlock()
    Attempt to acquire a read/write lock for writing without blocking.
pthread_rwlock_unlock()
    Release a read/write lock.
pthread_rwlockattr_init()
    Initialise a read/write lock.
pthread_rwlockattr_destroy()
    Destroy a read/write lock.
pthread_rwlockattr_getpshared()
    Get the process shared attribute.
pthread_rwlockattr_setpshared()
    Set the process shared attribute.

  Spinlock Routines
The functions available are as follows:

pthread_spin_init()
    Initialize a spinlock object.
pthread_spin_destroy()
    Destroy a spinlock object.
pthread_spin_lock()
    Lock a spinlock object.
pthread_spin_trylock()
    Attempt to lock a spinlock without blocking.
pthread_spin_unlock()
    Unlock a spinlock object.

  Thread Routines
The functions available are as follows:

pthread_create()
    Create a new thread.
pthread_cancel()
    Cancel execution of a 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_setcancelstate()
    Set cancelability state.
pthread_setcanceltype()
    Set cancelability state.
pthread_testcancel()
    Set cancelability state.
pthread_sigmask()
    Examine/change a thread's signal mask.
pthread_getcpuclockid()
    Get a CPU time clock for a thread.

  Thread stacks
Each thread has 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 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 from stack overflow for a thread, you should use sigaltstack(2) in that thread.

  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(), lgammal(), localeconv(), localtime(), lrand48(), mrand48(), nftw(), nl_langinfo(), putc_unlocked(), putchar_unlocked(), putenv(), rand(), readdir(), setenv(), setgrent(), setkey(), setpwent(), strerror(), strsignal(), strtok(), ttyname(), unsetenv(), wcstombs(), wctomb()

The ctermid() and tmpnam() functions are not thread-safe when passed a NULL argument. The wcrtomb(), wcsrtombs(), and wcsnrtombs() functions are not thread-safe when passed a NULL ps argument.

ENVIRONMENT

RTHREAD_DEBUG
    Enables debugging output when set to a positive number, with larger numbers generating more verbose output.

SEE ALSO
intro(3), pthread_atfork(3), pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3), pthread_attr_setstack(3), pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3), pthread_barrier_init(3), pthread_barrier_wait(3), pthread_barrierattr_getpshared(3), pthread_barrierattr_init(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_condattr_init(3), pthread_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3), pthread_get_name_np(3), pthread_getcpuclockid(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_unlock(3), pthread_mutexattr(3), pthread_once(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_spin_init(3), pthread_spin_lock(3), pthread_spin_unlock(3), pthread_stackseg_np(3), pthread_testcancel(3), pthread_yield(3)

STANDARDS
The thread library provides functions that conform to p1003.1-96 and various later versions of (“POSIX”). Consult the manpages for the individual functions for details.

HISTORY
This 1-to-1 implementation of the pthreads API initially appeared in OpenBSD 3.9 under the name “librthread” as an alternative to the pure-userspace (N-to-1) implementation. In OpenBSD 5.2 it became the default implementation and was renamed to “libpthread”.

AUTHORS
-nosplit Ted Unangst <tedu@openbsd.org>, Kurt Miller <kurt@openbsd.org>, Marco S Hyman <marc@openbsd.org>, Otto Moerbeek <otto@openbsd.org>, and Philip Guenther <guenther@openbsd.org>.