Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PTHREADS(3)	       FreeBSD Library Functions 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 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	ob-
				       ject.
     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 spe-
				  cific	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 ob-
				  ject.
     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 spe-
					 cific 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 at-
     tribute, or provided automatically	by the system.	If a thread overflows
     its stack,	unpredictable results may occur.  System-allocated stacks (in-
     cluding 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 over-
     flow 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(), hde-
     stroy(), 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(), str-
     tok(), 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 ISO/IEC 9945-1:1996
     ("POSIX.1") and various later versions of ("POSIX").  Please 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
     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>.

FreeBSD	13.0		       February	4, 2019			  FreeBSD 13.0

NAME | DESCRIPTION | ENVIRONMENT | SEE ALSO | STANDARDS | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pthreads&sektion=3&manpath=OpenBSD+6.9>

home | help