Click this button to go to the index for this section.

pthread(3)
NAME
  pthread, pthread_intro - Introduction to POSIX Threads (Pthreads)

DESCRIPTION
  DECthreads, DIGITAL's multithreading run-time library, provides a set of
  interfaces for building multithreaded programs. One of these interfaces
  provides routines (with the prefix pthread_) that implement the IEEE Std
  1003.1c-1995, POSIX System Application Program Interface, also known as
  POSIX Standard 1003.1c or POSIX.1c.  Note that POSIX Standard 1003.1c now
  supersedes the POSIX draft standard 1003.4a.

  A thread is a single, sequential flow of control within a program.  Within
  a single thread, there is a single point of execution.  Most traditional
  programs consist of a single thread.

  Using DECthreads, a programmer can create more than one threads within a
  program.  Threads execute concurrently, and, within a multithreaded
  program, there are at any time multiple points of execution.	The threads
  in a given process execute within (and share) a single address space.
  Therefore, threads read and write the same memory locations.
  Synchronization elements such as mutexes and condition variables ensure
  that the shared memory is accessed correctly.	 DECthreads provides routines
  that allow you to create and use these synchronization elements.  Mutexes
  and condition variables are discussed in the Guide to DECthreads.

  Users of previous versions of DECthreads should be aware that applications
  consistent with the P1003.4a/D4 interface require significant modifications
  to be upgraded to the DECthreads pthread (POSIX.1c) interface.  See the
  discussion in the Guide to DECthreads.

  Routine names ending with the _np suffix denote that the routine is "not
  portable."  That is, such a routine might not be available in other vendor
  implementations of POSIX 1003.1c.

  Compile a multithreaded application using shared versions of libmach and
  libpthread as follows:

   cc -o myprog myprog.c -pthread

  If you use a compiler front-end or other (not C) language environment that
  does not support the -pthread compilation switch, you must use the -
  D_REENTRANT compilation switch.

  When linking your multithreaded application, include these switches:

   -lpthread -lexc

  Each C module that utilizes DECthreads exceptions must include the
  pthread_exception.h header file. The Guide to DECthreads describes the use
  of DECthreads exceptions.


  Note that previous versions of DECthreads provided a DECthreads-specific
  debugging interface.	However, for this version and future versions of
  DECthreads, we recommend the use of the DIGITAL UNIX Ladebug debugger for
  debugging DECthreads-based multithreaded applications.


  The Guide to DECthreads describes important considerations for threaded
  application development, particularly for the DIGITAL UNIX operating
  system.

  The pthread interface routines are grouped in the following functional
  categories:

    ·  General threads routines

    ·  Thread attributes object routines

    ·  Thread cancelation routines

    ·  Thread priority, concurrency, and scheduling routines

    ·  Thread-specific data routines

    ·  Mutex routines

    ·  Mutex attributes object routines

    ·  Condition variable routines

    ·  Condition variable attribute object routines

  DECthreads also provides routines that implement nonportable extensions to
  the POSIX 1003.1c standard.  These routines are grouped into these
  functional categories:

    ·  Thread execution routines

    ·  Thread attributes routines

    ·  DECthreads global mutex routines

    ·  Mutex attributes routines

    ·  Condition variable routines

    ·  DECthreads exception object routines


  General Threads Routines


  pthread_atfork
		Declares fork handler routines to be called.

  pthread_create
		Creates a thread object and thread.

  pthread_detach
		Marks a thread object for deletion.

  pthread_equal Compares one thread identifier to another thread identifier.

  pthread_exit	Terminates the calling thread.

  pthread_join	Causes the calling thread to wait for the termination of a
		specified thread and detach it.

  pthread_kill	Delivers a signal to a specified thread.

  pthread_once	Calls an initialization routine to be executed only once.

  pthread_self	Obtains the identifier of the current thread.

  pthread_sigmask
		Examines or changes the calling thread's signal mask.


  Thread Attributes Object Routines


  pthread_attr_destroy
		Destroys a thread attributes object.

  pthread_attr_getdetachstate
		Obtains the detachstate attribute from the specified thread
		attributes object.

  pthread_attr_getguardsize
		Obtains the guardsize attribute of the specified thread
		attributes object.

  pthread_attr_getinheritsched
		Obtains the inherit scheduling attribute from the specified
		thread attributes object.

  pthread_attr_getschedparam
		Obtains the scheduling parameters for an attribute of the
		specified thread attributes object.

  pthread_attr_getschedpolicy
		Obtains the scheduling policy attribute of the specified
		thread attributes object.

  pthread_attr_getscope
		Obtains the contention-scope attribute of the specified
		thread attributes object.

  pthread_attr_getstackaddr
		Obtains the stackaddr attribute of the specified thread
		attributes object.

  pthread_attr_getstacksize
		Obtains the stacksize attribute of the specified thread
		attributes object.

  pthread_attr_init
		Initializes a thread attributes object.

  pthread_attr_setdetachstate
		Changes the detachstate attribute in the specified thread
		attributes object.

  pthread_attr_setguardsize
		Changes the guardsize attribute of the specified thread
		attributes object.

  pthread_attr_setinheritsched
		Changes the inherit scheduling attribute of the specified
		thread attributes object.

  pthread_attr_setschedparam
		Changes the values of the parameters associated with the
		scheduling policy attribute of the specified thread
		attributes object.

  pthread_attr_setschedpolicy
		Changes the scheduling policy attribute of the specified
		thread attributes object.

  pthread_attr_setstackaddr
		Changes the stackaddr attribute in the specified thread
		attributes object.

  pthread_attr_setstacksize
		Changes the stacksize attribute in the specified thread
		attributes object.


  Thread Cancelation Routines


  pthread_cancel
		Allows a thread to request that it, or another thread,
		terminate execution.

  pthread_cleanup_pop
		Removes a cleanup handler routine from the top of the cleanup
		stack and optionally executes it.

  pthread_cleanup_push
		Establishes a cleanup handler routine to be executed when the
		thread exits or is canceled.

  pthread_setcancelstate
		Sets the current thread's cancelability state.

  pthread_setcanceltype
		Sets the current thread's cancelability type.

  pthread_testcancel
		Requests delivery of any pending cancelation request to the
		current thread.


  Thread Priority, Concurrency, and Scheduling Routines


  pthread_getconcurrency
		Obtains the current concurrency level parameter for the
		process.

  pthread_getschedparam
		Obtains the current scheduling policy and scheduling
		parameters of a thread.

  pthread_getsequence_np
		Obtains a thread sequence number.

  pthread_setconcurrency
		Changes the current concurrency level parameter for the
		process.

  pthread_setschedparam
		Changes the current scheduling policy and scheduling
		parameters of a thread.



  Thread-Specific Data Routines


  pthread_getspecific
		Obtains the thread-specific data associated with the
		specified key.

  pthread_key_create
		Generates a unique thread-specific data key.

  pthread_setspecific
		Sets the thread-specific data value associated with the
		specified key for the current thread.

  pthread_key_delete
		Deletes a thread-specific data key.


  Mutex Routines


  pthread_mutex_destroy
		Destroys a mutex.

  pthread_mutex_init
		Initializes a mutex with attributes specified by the
		attributes argument.

  pthread_mutex_lock
		Locks an unlocked mutex; if locked, the caller waits for the
		mutex to become available.

  pthread_mutex_trylock
		Attempts to lock a mutex; returns immediately if mutex is
		already locked.

  pthread_mutex_unlock
		Unlocks a locked mutex.


  Mutex Attributes Object Routines


  pthread_mutexattr_init
		Initializes a mutex attributes object.

  pthread_mutexattr_destroy
		Destroys a mutex attributes object.

  pthread_mutexattr_gettype
		Obtains the mutex type attribute of a mutex attributes
		object.

  pthread_mutexattr_settype
		Changes the mutex type attribute of a mutex attributes
		object.


  Condition Variable Routines


  pthread_cond_broadcast
		Wakes all threads waiting on a condition variable.

  pthread_cond_destroy
		Destroys a condition variable.

  pthread_cond_init
		Initializes a condition variable.

  pthread_cond_signal
		Wakes at least one thread that is waiting on a condition
		variable.

  pthread_cond_timedwait
		Causes a thread to wait for a specified period of time for a
		condition variable to be signaled or broadcasted.

  pthread_cond_wait
		Causes a thread to wait for a condition variable to be
		signaled or broadcasted.


  Condition Variable Attributes Object Routines


  pthread_condattr_destroy
		Destroys a condition variable attributes object.

  pthread_condattr_init
		Initializes a condition variable attributes object.


  Non-Portable Extensions: Thread Execution Routines


  pthread_delay_np
		Causes a thread to delay execution.

  pthread_get_expiration_np
		Obtains a value representing a desired expiration time.

  pthread_getsequence_np
		Obtains the thread sequence number.


  Non-Portable Extensions: Thread Attributes Routines


  pthread_attr_getguardsize_np
		Obtains the guardsize attribute of the specified thread
		attributes object.

  pthread_attr_setguardsize_np
		Changes the guardsize attribute of the specified thread
		attributes object.


  Non-Portable Extensions: DECthreads Global Mutex Routines


  pthread_lock_global_np
		Locks the DECthreads global mutex if it is unlocked.

  pthread_unlock_global_np
		Unlocks the DECthreads lobal mutex if it is locked.


  Non-Portable Extensions: Mutex Attributes Routines


  pthread_mutexattr_gettype_np
		Obtains the mutex type attribute of a mutex attributes
		object.

  pthread_mutexattr_settype_np
		Changes the mutex type attribute of a mutex attributes
		object.


  Non-Portable Extensions: Condition Variable Routines


  pthread_cond_signal_int_np
		Wakes one thread that is waiting on a condition variable
		(called from interrupt level only).


  Non-Portable Extensions: DECthreads Exception Object Routines


  pthread_exc_get_status_np
		Obtains a system-defined error status from a DECthreads
		status exception object.

  pthread_exc_matches_np
		Determines whether two DECthreads exception objects are
		identical.

  pthread_exc_report_np
		Produces a message that reports what a specified DECthreads
		status exception object represents.

  pthread_exc_set_status_np
		Imports a system-defined error status into a DECthreads
		address exception object.