[Prev] [Contents] [Next]

Pthread API Reference

API Introduction

Header files

#include <pthread.h>
#include <sched.h>

Preprocessor Values

An application compiling for Pthreads must define the preprocessor value _MULTI_THREADED before any C statements (including header files), and especially before the pthread.h header file. Use the DEFINE keyword on the compilation command or, use the #define statement in the C source modules before including the pthread.h header file.

CRTCMOD library/module DEFINE(_MULTI_THREADED)
OR
#define _MULTI_THREADED

Primitive data types

The Pthread types and functions follow the following naming conventions. If the type of object is not a thread, object represents the type of object, action is an operation to be performed on the object, np or NP indicates that the name or symbol is a non portable extension to the API set, and PURPOSE indicates the use or purpose of the symbol.

types
pthread[_object][_np]_t
functions
pthread[_object]_action[_np]
Constants and Macros
PTHREAD_PURPOSE[_NP]
type Description
pthread_attr_t Thread creation attribute
pthread_cleanup_entry_np_t Cancelation cleanup handler entry
pthread_condattr_t Condition variable creation attribute
pthread_cond_t Condition Variable synchronization primitive
pthread_joinoption_np_t Options structure for extensions to pthread_join()
pthread_key_t Thread local storage key
pthread_mutexattr_t Mutex creation attribute
pthread_mutex_t Mutex (Mutual exclusion) synchronization primitive
pthread_once_t Once time initialization control variable
pthread_option_np_t Pthread run-time options structure
pthread_rwlockattr_t Read/Write lock attribute
pthread_rwlock_t Read/Write synchronization primitive
pthread_t Pthread handle
pthread_id_np_t Thread ID. For use as an integral type.
struct sched_param Scheduling parameters (priority and policy)

After creating the primitive objects of type pthread_cond_t and pthread_mutex_t using the appropriate initialization functions, those objects must not be copied or moved to a new location. If the condition variable or mutex is copied or moved to a new location, the new primitive object will be invalid and unable to be used. Attempts to use the new object will result in the EINVAL error.

Function prototypes

All functions except for pthread_exit(), pthread_getspecific(), pthread_self(), pthread_test_exit_np(), pthread_is_multithreaded_np()and pthread_getconcurrency() return an errno value to indicate failure, or 0 to indicate success.

Thread Attributes
Attribute Default value supported values
detachstate PTHREAD_CREATE_JOINABLE PTHREAD_CREATE_JOINABLE PTHREAD_CREATE_DETACHED
schedparam SCHED_OTHER with priority equal to PRIORITY_DEFAULT (0) SCHED_OTHER with priority <= PTHREAD_PRIO_MAX and priority >= PTHREAD_PRIO_MIN
contentionscope PTHREAD_SCOPE_SYSTEM PTHREAD_SCOPE_SYSTEM
inheritsched PTHREAD_EXPLICIT_SCHED, priority equal PRIORITY_DEFAULT (0) PTHREAD_EXPLICIT_SCHED or PTHREAD_INHERIT_SCHED
schedpolicy SCHED_OTHER SCHED_OTHER

int pthread_attr_destroy(pthread_attr_t *attr);
Destroy the thread creation attribute

int pthread_attr_getdetachstate(const pthread_attr_t *attr,
                                int *detachstate);
Get the detachstate from the thread creation attribute

int pthread_attr_getinheritsched(pthread_attr_t *attr,
                                 int *inheritsched);
Get the inheritsched attribute.

int pthread_attr_getschedparam(const pthread_attr_t *attr,
                               struct sched_param *param);
Get the schedparam attribute from the thread creation attribute. SCHED_OTHER with the thread priority is returned.

int pthread_attr_init(pthread_attr_t *attr);
Initialize the thread creation attribute

int pthread_attr_setdetachstate(pthread_attr_t *attr,
                                int detachstate);
Set the detachstate in the thread creation attribute to one of PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

int pthread_attr_setinheritsched(pthread_attr_t *attr,
                                 int inheritsched);
Set the inheritsched attribute to one of PTHREAD_EXPLICIT_SCHED or PTHREAD_INHERIT_SCHED.

int pthread_attr_setschedparam(pthread_attr_t *attr,
                               const struct sched_param *param);
Set the scheduling parameters in the thread creation attribute. Set only a policy of SCHED_OTHER with priority <= PTHREAD_PRIO_MAX and priority >= PTHREAD_PRIO_MIN.

Thread Management

int pthread_clear_exit_np(void);
Clear the current exit status and exiting state of the thread.
This function is not portable.

int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
                   void *(*start_routine)(void *), void *arg);
Create a thread with the specified thread attributes. Attribute of NULL indicates default attributes.
The AS/400 implementation does not set a hard limit on the number of threads that can be created. PTHREAD_THREADS_MAX macro is implemented as a function call, and will return different values depending on the administrative setting of the maximum number of threads for the process. The default is NO MAX and has the numeric value of 2147483647 (0x7FFFFFFF). Realistically, the number of threads is limited by the amount of storage available to the job.

int pthread_delay_np(const struct timespec *interval);
Delay the calling thread for the time interval specified.
This function is not portable.

int pthread_detach(pthread_t thread);
Set the detachstate of a thread to PTHREAD_CREATE_DETACHED, allowing resources to be freed if/when the thread terminates.

int pthread_equal(pthread_t thread1, pthread_t thread2);
Compare two Pthread handles

void pthread_exit(void *status);
Terminate the calling thread and provide status to any joiners

int pthread_extendedjoin_np(pthread_t thread, void **status,
                            pthread_joinoption_np_t *options);
Provides an extension to the normal pthread_join() semantics. Allow the application to specify options like the amount of time before time-out occurs, or whether the API should do an implicit detach operation or not.
This function is not portable.

int pthread_getconcurrency(void);
Get the concurrency level set for the process.
The concurrency level is not used by the OS/400 implementation.

void pthread_getpthreadoption_np(pthread_option_np_t *option);
Get the pthreads run-time option value for the specified option. The specified option must be one of: PTHREAD_OPTION_POOL_NP, PTHREAD_OPTION_POOL_CURRENT_NP, PTHREAD_OPTION_THREAD_CAPABLE_NP.

int pthread_getschedparam(pthread_t thread, int *policy,
                          struct sched_param *param);
Get the scheduling parameters of the specified thread. SCHED_OTHER with the thread priority is returned.

pthread_id_np_t pthread_getthreadid_np(void);
Get the calling threads unique 64 bit integral thread id in two 32 bit integers.
This function is not portable.

int pthread_getunique_np(pthread_t thread, pthread_id_np_t *id);
Get the target threads unique 64 bit integral thread id in two 32 bit integers.
This function is not portable.

int pthread_is_multithreaded_np(pthread_t thread, void **status);
Returns true (>0) if there is more than one thread in the process, false (0) otherwise. Adding 1 to the number returned represents the total number of threads in the process at the time of the call.
This function is not portable.

int pthread_join(pthread_t thread, void **status);
Wait for a thread to terminate, return its status and free its resources.
If the target thread was canceled, PTHREAD_CANCELED will be returned as its status. If the target thread ended as a result of an unhandled OS/400 exception or other proprietary OS/400 mechanism, the status of PTHREAD_EXCEPTION_NP will be returned.

int pthread_join_np(pthread_t thread, void **status);
Wait for a thread to terminate, return its status and leave its resources available.
This function is not portable.
If the target thread was canceled, PTHREAD_CANCELED will be returned as its status. If the target thread ended as a result of an unhandled OS/400 exception or other proprietary OS/400 mechanism, the status of PTHREAD_EXCEPTION_NP will be returned.

int pthread_once(pthread_once_t *once_control,
                 void (*init_routine)(void));
Perform one time initialization if once_control is equal to PTHREAD_ONCE_INIT.

pthread_t pthread_self(void);
Return the Pthread handle of the calling thread.

int pthread_setconcurrency(void);
Set the concurrency level set for the process.
The concurrency level is not used by the OS/400 implementation.

void pthread_setpthreadoption_np(pthread_option_np_t *option);
Set the pthreads run-time options value or take action for the specified option. The specified option must be one of: PTHREAD_OPTION_POOL_NP.

int pthread_setschedparam(pthread_t thread, int policy,
                          const struct sched_param *param);
Set the scheduling parameters of the specified thread. Set only a policy of SCHED_OTHER with priority <= PTHREAD_PRIO_MAX and priority >= PTHREAD_PRIO_MIN.

int sched_yield(void);
Yield the processor to an active, ready to run thread of the same or higher priority.

Thread Cancelation

Cancel State Cancel Type Cancelation Action
PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_ASYNCHRONOUS Cancel the thread immediately and asynchronously
PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_DEFERRED defer cancelation until a cancelation point is encountered
PTHREAD_CANCEL_DISABLE PTHREAD_CANCEL_ASYNCHRONOUS defer cancelation until the cancel state changed to enabled
PTHREAD_CANCEL_DISABLE PTHREAD_CANCEL_DEFERRED defer cancelation until the cancel state changed to enabled

The default thread cancelation action is `defer cancelation until a cancelation point'. i.e. cancel state equal to PTHREAD_CANCEL_ENABLE, cancel type equal to PTHREAD_CANCEL_DEFERRED.

The following functions are cancelation points: pthread_join(), pthread_join_np(), pthread_testcancel(), pthread_cond_wait(), pthread_cond_timedwait(), pthread_delay_np().

int pthread_cancel(pthread_t thread);
Cancel the specified thread.
pthread_cancel() makes status of PTHREAD_CANCELED available as the target threads exit status.

It is recommended that your application not use asynchronous thread cancelation via the pthread_setcanceltype() function. See the common user errors section of this document for more information.

void pthread_cleanup_peek_np(pthread_cleanup_entry_np_t *top);
Retrieve the cleanup handler on the top of the cancelation cleanup stack without removing it
This function is not portable.

void pthread_cleanup_pop(int execute);
Pop a cleanup handler off of the cancelation cleanup stack and optionally execute it.

void pthread_cleanup_push(void (*routine)(void *), void *arg);
Push a cancelation cleanup handler onto the cancelation cleanup stack.

int pthread_getcancelstate_np(int *cancelState);
Get the threads current cancelation state.
This function is not portable.

int pthread_setcancelstate(int state, int *oldstate);
Set the thread cancelation state of the specified thread to one of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

int pthread_setcanceltype(int type, int *oldtype);
Set the thread cancelation type of the specified thread to one of PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.
It is recommended that your application not use asynchronous thread cancelation via the PTHREAD_CANCEL_ASYNCHRONOUS option of pthread_setcanceltype(). See the common user errors section of this document for more information.

void pthread_testcancel(void);
Create a cancelation point for the calling thread. No operation if cancel state is equal to PTHREAD_CANCEL_DISABLE.

int pthread_test_exit_np(void **status);
Retrieve the current exit status of the thread. Returns one of PTHREAD_STATUS_ACTIVE_NP or PTHREAD_STATUS_EXIT_NP, sets the status if PTHREAD_STATUS_EXIT_NP is returned.
This function is not portable.

Thread Local Storage

void *pthread_getspecific(pthread_key_t key);
Retrieve this threads value associated with the thread local storage key.

int pthread_key_create(pthread_key_t *key,
                       void (*destructor)(void *));
Create a thread local storage key and possibly associate a destructor with it.
A maximum of PTHREAD_KEYS_MAX (256) thread local storage keys can be created in a process. When running data destructors, the destructor will be called a maximum of PTHREAD_DESTRUCTOR_ITERATIONS (4) times.

int pthread_key_delete(pthread_key_t key);
Delete a thread local storage key

int pthread_setspecific(pthread_key_t key, const void *value);
Set this threads value associated with the thread local storage key.

Mutex Attributes
Attribute Default value supported values
pshared PTHREAD_PROCESS_PRIVATE PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED
kind (non portable) PTHREAD_MUTEX_NONRECURSIVE_NP PTHREAD_MUTEX_NONRECURSIVE_NP or PTHREAD_MUTEX_RECURSIVE_NP
name (non portable) PTHREAD_DEFAULT_MUTEX_NAME_NP "QP0WMTX UNNAMED" Any name 15 characters or less. If not terminated by a null character, name is truncated to 15 characters.
type PTHREAD_MUTEX_DEFAULT (PTHREAD_MUTEX_NORMAL) PTHREAD_MUTEX_DEFAULT or PTHREAD_MUTEX_NORMAL or PTHREAD_MUTEX_RECURSIVE or PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_OWNERTERM_NP The PTHREAD_MUTEX_OWNERTERM_NP attribute value is non portable

int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
Destroy the mutex attributes object.

int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *attr,
                                int *kind);
Get the kind attribute.
This function is not portable.

int pthread_mutexattr_getname_np(const pthread_mutexattr_t *attr,
                                 char *name);
Get the name attribute.
This function is not portable.

int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr,
                                 int *pshared);
Get the pshared attribute

int pthread_mutexattr_gettype(pthread_mutexattr_t *attr, int *type);
Get the type attribute.

int pthread_mutexattr_init(pthread_mutexattr_t *attr);
Initialize the mutex attributes to the default values.

int pthread_mutexattr_setkind_np(const pthread_mutexattr_t *attr,
                                 int kind);
Set the kind attribute to one of PTHREAD_MUTEX_NONRECURSIVE_NP or PTHREAD_MUTEX_RECURSIVE_NP.
This function is not portable.

int pthread_mutexattr_setname_np(pthread_mutexattr_t *attr,
                                 const char *name);
Set the name attribute to the null terminated string specified.
This function is not portable.

int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
                                 int pshared);
Set the pshared attribute to one of PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
Set the type attribute to one of PTHREAD_MUTEX_DEFAULT, PTHREAD_MUTEX_NORMAL, PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_ERRORCHECK, or PTHREAD_MUTEX_OWNERTERM_NP.
The PTHREAD_MUTEX_OWNERTERM_NP type is not portable.

int pthread_set_mutexattr_default_np(int kind);
Set the default kind attribute for the current process to one of PTHREAD_MUTEX_NONRECURSIVE_NP or PTHREAD_MUTEX_RECURSIVE_NP. All subsequent mutexes created in the same process will have the specified default kind attribute. It is recommended that you do not use this function.
This function is not portable.

Mutexes

int pthread_mutex_destroy(pthread_mutex_t *mutex);
Destroy the mutex.

int pthread_mutex_init(pthread_mutex_t *mutex,
                       const pthread_mutexattr_t *attr);     OR
pthread_mutex_t   mutex = PTHREAD_MUTEX_INITIALIZER;
Initialize the mutex using the attributes specified. Attribute of NULL or initialization with the PTHREAD_MUTEX_INITIALIZER indicates the default mutex attributes.

int pthread_mutex_lock(pthread_mutex_t *mutex);
Lock the mutex.

int pthread_mutex_timedlock_np(pthread_mutex_t *mutex,
                               const struct timespec *deltatime);
Attempt to lock the mutex, time-out with the EBUSY error if the call waits for the delta time specified.
This function is not portable.

int pthread_mutex_trylock(pthread_mutex_t *mutex);
Attempt to lock the mutex without blocking.

int pthread_mutex_unlock(pthread_mutex_t *mutex);
Unlock the mutex

int pthread_lock_global_np(void);
Lock a global mutex.
This function is not portable.

int pthread_unlock_global_np(void);
Unlock a global mutex.
This function is not portable.

Condition Variable Attributes
Attribute Default value supported values
pshared PTHREAD_PROCESS_PRIVATE PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED

int pthread_condattr_destroy(pthread_condattr_t *attr);
Destroy the named condition variable attributes object.

int pthread_condattr_init(pthread_condattr_t *attr);
Initialize a condition variable attributes object.

int pthread_condattr_getpshared(const pthread_condattr_t *attr,
                                int *pshared);
Get the pshared attribute.

int pthread_condattr_setpshared(const pthread_condattr_t *attr,
                                int pshared);
Set the pshared attribute to one of PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED.

Condition Variables

int pthread_cond_broadcast(pthread_cond_t *cond);
Wake up all waiters blocked on a condition.

int pthread_cond_destroy(pthread_cond_t *cond);
Destroy the condition variable.

int pthread_cond_init(pthread_cond_t *cond,
                      const pthread_condattr_t *attr);     OR
pthread_cond_t   cond = PTHREAD_COND_INITIALIZER;
Initialize the condition variable using the attributes specified. Attribute of NULL or initialization with the PTHREAD_COND_INITIALIZER indicates the default condition variable attributes.

int pthread_cond_signal(pthread_cond_t *cond);
Wake up at least one thread blocked on a condition.

int pthread_cond_timedwait(pthread_cond_t *cond,
                           pthread_mutex_t *mutex,
                           const struct timespec *abstime);
Go to sleep in a timed wait for a condition variable.

int pthread_cond_wait(pthread_cond_t *cond,
                      pthread_mutex_t *mutex);
Go to sleep in a wait for a condition variable

int pthread_get_expiration_np(const struct timespec *delta,
                              struct timespec *abstime);
Convert a delta timespec to an absolute timespec for possible subsequent use in pthread_cond_timedwait.
This function is not portable.

Read/Write Lock Attributes
Attribute Default value supported values
pshared PTHREAD_PROCESS_PRIVATE PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED

int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr);
Destroy the named read/write lock attributes object.

int pthread_rwlockattr_init(pthread_rwlockattr_t *attr);
Initialize a read/write lock attributes object.

int pthread_rwlockatttr_getpshared(const pthread_rwlockattr_t *attr,
                                   int *pshared);
Get the pshared attribute.

int pthread_rwlockatttr_setpshared(pthread_rwlockattr_t *attr,
                                   int pshared);
Set the pshared attribute to one of PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED.

Read/Write Lock

int pthread_rwlock_destroy(pthread_rwlock_t *rwlock);
Destroy the read/write lock.

int pthread_rwlock_init(pthread_rwlock_t *rwlock,
                        const pthread_rwlockattr_t *attr);      OR
pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;
Initialize the read/write lock using the attributes specified. Attribute of NULL or initialization with the PTHREAD_RWLOCK_INITIALIZER indicates the default read/write lock attributes.

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock);
Get a shared read lock on the read/write lock.

int pthread_rwlock_timedrdlock_np(pthread_rwlock_t *rwlock,
                                  const struct timespec *deltatime);
Attempt to get a shared read lock on the read/write lock, time-out with the EBUSY error if the call waits for the delta time specified.
This function is not portable.

int pthread_rwlock_timedwrlock_np(pthread_rwlock_t *rwlock,
                                  const struct timespec *deltatime);
Attempt to get an exclusive write lock on the read/write lock, time-out with the EBUSY error if the call waits for the delta time specified.
This function is not portable.

int pthread_rwlock_tryrdlock_np(pthread_rwlock_t *rwlock);
Attempt to get a shared read lock on the read/write lock, if the lock is currently held by another thread, return EBUSY.

int pthread_rwlock_trywrlock_np(pthread_rwlock_t *rwlock);
Attempt to get an exclusive write lock on the read/write lock, if the lock is currently held by another thread, return EBUSY.

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock);
Unlock the shared read or exclusive write lock held by the calling thread on the read/write lock.

int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock);
Get an exclusive write lock on the read/write lock.

Signals

int pthread_kill(pthread_t thread, int sig)
Deliver the signal sig to the thread specified.

int pthread_sigmask(int how, const sigset_t *set, sigset_t *oset);
Examine or change the calling threads signal blocking mask.

int pthread_signal_to_cancel_np(sigset_t *set, pthread_t *thread);
Deliver a cancel to the target thread when the first of the specified signals arrive.
This function is not portable.

Unsupported functions

The following functions are unsupported. They will fail with the ENOSYS error.
int pthread_atfork(void (*prepare)(void),
                   void (*parent)(void),
                   void (*child)(void));
int pthread_atfork_np(int *userstate,
                      void (*prepare)(void),
                      void (*parent)(void),
                      void (*child)(void));
int pthread_attr_getguardsize(const pthread_attr_t *attr,
                              size_t *guardsize);
int pthread_attr_getschedpolicy(pthread_attr_t *attr,
                                int *policy);
int pthread_attr_getscope(pthread_attr_t *attr,
                          int *contentionscope);
int pthread_attr_getstackaddr(const pthread_attr_t *attr,
                              void **stackaddr);
int pthread_attr_getstacksize(const pthread_attr_t *attr,
                              size_t *stacksize);
int pthread_attr_setguardsize(pthread_attr_t *attr,
                              size_t guardsize);
int pthread_attr_setschedpolicy(pthread_attr_t *attr,
                                int policy);
int pthread_attr_setscope(pthread_attr_t *attr,
                          int contentionscope);
int pthread_attr_setstackaddr(pthread_attr_t *attr,
                              void *stackaddr);
int pthread_attr_setstacksize(pthread_attr_t *attr,
                              size_t stacksize);
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr,
                                     int *prioceiling);
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr,
                                  int *protocol);
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr,
                                     int prioceiling);
int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
                                  int protocol);
int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex,
                                 int *prioceiling);
int pthread_mutex_setprioceiling(pthread_mutex_t *mutex,
                                 int prioceiling, int *oldceiling);

Feature Test Macros
Constant Description
_POSIX_THREADS Base threads
_POSIX_THREAD_ATTR_STACKADDR Stack address attribute. Not present in the OS/400 implementation.
_POSIX_THREAD_ATTR_STACKSIZE Stack size attribute. Not present in the OS/400 implementation.
_POSIX_THREAD_PRIORITY_SCHEDULING Thread priority scheduling. Not present in the OS/400 implementation.
_POSIX_THREAD_PRIO_INHERIT Mutex priority inheritance. Not present in the OS/400 implementation.
_POSIX_THREAD_PRIO_PROTECT Mutex priority ceiling. Not present in the OS/400 implementation.
_POSIX_THREAD_PROCESS_SHARED Synchronization primitives may be shared between processes.

The OS/400 implementation of pthreads defines the _POSIX_THREADS and _POSIX_THREAD_PROCESS_SHARED feature test macros.

Header files



[Prev] [Contents] [Next]
Copyright © 1998, IBM Corporation. All rights reserved.
Comments? Contact
rchthrds@us.ibm.com