Add Book to My BookshelfPurchase This Book Online

Appendix C - Pthreads Quick Reference

Pthreads Programming
Bradford Nichols, Dick Buttlar and Jacqueline Proulx Farrell
 Copyright 1996 O'Reilly & Associates, Inc.

Appendix C: Pthreads Quick Reference
In this appendix, we'll provide a brief listing of the C language bindings of the Pthreads library routines: 
pthread_atfork ( )
int pthread_atfork (
void (*prepare)(void),
void (*parent)(void),
void (*child)(void));
Declares procedures to be called before and after a fork call. The prepare fork handler runs in the parent process before the fork. After the fork, the parent handler runs in the parent process, and the child handler runs in the child process. 
pthread_attr_destroy( )
int pthread_attr_destroy (
pthread_attr_t *attr);
Destroys a thread attribute object. 
pthread_attr_getdetachstate( )
int pthread_attr_getdetachstate (
const pthread_attr_t *attr,
int *detachstate);
Obtains the setting of the detached state of a thread. 
pthread_attr_getinheritsched( )
int pthread_attr_getinheritsched (
const pthread_attr_t *attr,
int *inheritsched);
Obtains the setting of the scheduling inheritance of a thread. 
pthread_attr_getschedparam( )
int pthread_attr_getschedparam (
const pthread_attr_t *attr,
struct sched_param *param);
Obtains the parameters (for instance, the scheduling priority) associated with the scheduling policy attribute of a thread. 
pthread_attr_getschedpolicy( )
int pthread_attr_getschedpolicy (
const pthread_attr_t *attr,
int *policy);
Obtains the setting of the scheduling policy of a thread. 
pthread_attr_getscope( )
int pthread_attr_getscope (
const pthread_attr_t *attr,
int *scope);
Obtains the setting of the scheduling scope of a thread. 
pthread_attr_getstackaddr( )
int pthread_attr_getstackaddr (
const pthread_attr_t *attr,
void **stackaddr);
Obtains the stack address of a thread. 
pthread_attr_getstacksize( )
int pthread_attr_getstacksize (
const pthread_attr_t *attr,
size_t *stacksize);
Obtains the stack size of a thread.
pthread_attr_init( )
int pthread_attr_init (
pthread_attr_t *attr);
Initializes a thread attribute object. A thread specifies a thread attribute object in its calls to pthread_create to set the characteristics of newly created threads. 
pthread_attr_setdetachstate( )
int pthread_attr_setdetachstate (
pthread_attr_t *attr,
int detachstate);
Adjusts the detached state of a thread. A thread's detached state can be joinable (PTHREAD_CREATE_JOINABLE) or it can be detached (PTHREAD_CREATE_DETACHED).
pthread_attr_setinheritsched( )
int pthread_attr_setinheritsched (
pthread_attr_t *attr,
int inherit);
Adjusts the scheduling inheritance of a thread. A thread can inherit the scheduling policy and the parameters of its creator thread (PTHREAD_INHERIT_SCHED) or obtain them from the thread attribute object specified in the pthread_create call (PTHREAD_EXPLICIT_SCHED). 
pthread_attr_setschedparam( )
int pthread_attr_setschedparam (
pthread_attr_t *attr,
const struct sched_param *param);
Adjusts the parameters (for instance, the scheduling priority) associated with the scheduling policy of a thread. The scheduling priority parameter (as specified in the struct sched_param) depends upon the selected scheduling policy (SCHED_FIFO, SCHED_RR, or SCHED_OTHER). Use sched_get_priority_max and sched_get_priority_min to obtain the maximum and minimum priority settings for a given policy. 
pthread_attr_setschedpolicy( )
int pthread_attr_setschedpolicy (
pthread_attr_t *attr,
int policy);
Adjusts the scheduling policy of a thread. Pthreads defines the SCHED_FIFO, SCHED_RR, and SCHED_OTHER policies. 
pthread_attr_setscope( )
int pthread_attr_setscope (
pthread_attr_t *attr,
int scope);
Adjusts the scheduling scope of a thread. A thread can use system-scope scheduling (PTHREAD_SCOPE_SYSTEM), in which case the operating system compares the priorities of all runnable threads of all processes systemwide in order to select a thread to run on an available CPU. Alternatively, it can use process-scope scheduling (PTHREAD_SCOPE_PROCESS), in which case only the highest priority runnable thread in a process competes against the highest priority threads of other processes in the system's scheduling activity. 
pthread_attr_setstackaddr( )
int pthread_attr_setstackaddr (
pthread_attr_t *attr,
void *stackaddr);
Adjusts the stack address of a thread. 
pthread_attr_setstacksize( )
int pthread_attr_setstacksize (
pthread_attr_t *attr,
size_t stacksize);
Adjusts the stack size of a thread. The stack size must be greater than or equal to PTHREAD_STACK_MIN. 
pthread_cancel( )
int pthread_cancel (
pthread_t thread);
Cancels the specified thread. 
pthread_cleanup_pop( )
void pthread_cleanup_pop (
int execute);
Removes the routine from the top of a thread's cleanup stack, and if execute is nonzero, runs it. 
pthread_cleanup_push( )
void pthread_cleanup_push (
void (*routine)(void *),
void *arg);
Places a routine on the the top of a thread's cleanup stack, and  when the routine is called, ensures that the specified argument is passed to it. 
pthread_condattr_destroy( )
int pthread_condattr_destroy (
pthread_condattr_t *attr);
Destroys a condition variable attribute object. 
pthread_condattr_getpshared( )
int pthread_condattr_getpshared (
pthread_condattr_t *attr,
int *pshared);
Obtains the process-shared setting of a condition variable attribute object. 
pthread_condattr_init( )
int pthread_condattr_init (
pthread_condattr_t *attr);
Initializes a condition variable attribute object. A thread specifies a condition variable attribute object in its calls to pthread_cond_init to set the characteristics of new condition variables. 
pthread_condattr_setpshared( )
int pthread_condattr_setpshared (
pthread_condattr_t *attr,
int pshared);
Sets the process-shared attribute in a condition variable attribute object to either PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE. 
pthread_cond_broadcast( )
int pthread_cond_broadcast (
pthread_cond_t *cond);
Unblocks all threads that are waiting on a condition variable. 
pthread_cond_destroy( )
int pthread_cond_destroy (
pthread_cond_t *cond);
Destroys a condition variable. 
pthread_cond_init( )
int pthread_cond_init (
pthread_cond_t *cond,
const pthread_condattr_t *attr);
Initializes a condition variable with the attributes specified in the specified condition variable attribute object. If attr is NULL, the default attributes are used. 
pthread_cond_signal( )
int pthread_cond_signal(
pthread_cond_t *cond);
Unblocks at least one thread waiting on a condition variable. The scheduling priority determines which thread is awakened. 
pthread_cond_timedwait( )
int pthread_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);
Atomically unlocks the specified mutex, and places the calling thread into a wait state. When the specified condition variable is signaled or broadcast, or the system time is greater than or equal to abstime, this function reacquires the mutex and resumes its caller. 
pthread_cond_wait( )
int pthread_cond_wait (
pthread_cond_t *cond,
pthread_mutex_t *mutex);
Atomically unlocks the specified mutex, and places the calling thread into a wait state. When the specified condition variable is signaled or broadcasted, this function reacquires the mutex and resumes its caller. 
pthread_create( )
int pthread_create (
pthread_t *thread,
const pthread_attr_t *attr,
void *(*start_routine)(void *),
void *arg);
Creates a thread with the attributes specified in attr. If attr is NULL, the default attributes are used. The thread argument receives a thread handle for the new thread. The new thread starts execution in start_routine and is passed the single specified argument. 
pthread_detach( )
int pthread_detach (
pthread_t thread);
Marks a thread's internal data structures for deletion. When a detached thread terminates, the system reclaims the storage used for its thread object. 
pthread_equal( )
int pthread_equal (
pthread_t t1,
pthread_t t2);
Compares one thread handle to another thread handle. 
pthread_exit( )
void pthread_exit (
void *value);
Terminates the calling thread, returning the specified value to any thread that may have previously issued a pthread_join on the thread. 
pthread_getschedparam( )
int pthread_getschedparam (
pthread_t thread,
int *policy,
struct sched_param *param);
Obtains both the scheduling policy and scheduling parameters of an existing thread. (This function differs from the pthread_attr_getschedpolicy function and the pthread_attr_getschedparam function in that the latter functions return the policy and parameters that will be used whenever a new thread is created.) 
pthread_getspecific( )
void *pthread_getspecific (
pthread_key_t key);
Obtains the thread-specific data value associated with the specified key in the calling thread. 
pthread_join( )
int pthread_join (
pthread_t thread,
void **value_ptr);
Causes the calling thread to wait for the specified thread's termination. The value_ptr parameter receives the return value of the terminating thread. 
pthread_key_create( )
int pthread_key_create (
pthread_key_t *key,
void (*destructor)(void *));
Generates a unique thread-specific key that's visible to all threads in a process. Although different threads can use the same key, the value any thread associates with the key (by calling pthread_specific) are specific to that thread alone and persist for the life of that thread. When a thread terminates, its thread-specific data value is destroyed (but the key persists until pthread_key_destroy is called). If a destructor routine was specified for the key in the pthread_key_create call, it's then called in the thread's context with the thread-specific data value associated with the key as an argument. 
pthread_key_delete( )
int pthread_key_delete (
pthread_key_t key);
Deletes a thread-specific key. 
pthread_kill( )
int pthread_kill (
pthread_t thread,
int sig);
Delivers a signal to the specified thread. 
pthread_mutexattr_destroy( )
int pthread_mutexattr_destroy (
pthread_mutexattr_t *attr);
Destroys a mutex attribute object. 
pthread_mutexattr_getprioceiling( )
int pthread_mutexattr_getprioceiling (
pthread_mutexattr_t *attr,
int *prioceiling);
Obtains the priority ceiling of a mutex attribute object. 
pthread_mutexattr_getprotocol( )
int pthread_mutexattr_getprotocol(
pthread_mutexattr_t *attr,
int *protocol);
Obtains the protocol of a mutex attribute object. 
pthread_mutexattr_getpshared( )
int pthread_mutexattr_getpshared(
pthread_mutexattr_t *attr,
int *pshared);
Obtains the process-shared setting of a mutex attribute object. 
pthread_mutexattr_init( )
int pthread_mutexattr_init (
pthread_mutexattr_t *attr);
Initializes a mutex attribute object. A thread specifies a mutex attribute object in its calls to pthread_mutex_init to set the characteristics of new mutexes. 
pthread_mutexattr_setprioceiling( )
int pthread_mutexattr_setprioceiling (
pthread_mutexattr_t *attr,
int prioceiling);
Sets the priority ceiling attribute of a mutex attribute object. 
pthread_mutexattr_setprotocol( )
int pthread_mutexattr_setprotocol(
pthread_mutexattr_t *attr,
int protocol);
Sets the protocol attribute of a mutex attribute object. There are three valid settings: PTHREAD_PRIO_INHERIT, PTHREAD_PRIO_PROTECT, or PTHREAD_PRIO_NONE. 
pthread_mutexattr_setpshared( )
int pthread_mutexattr_setpshared(
pthread_mutexattr_t *attr,
int pshared);
Sets the process-shared attribute of a mutex attribute object to PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE. 
pthread_mutex_destroy( )
int pthread_mutex_destroy (
pthread_mutex_t *mutex);
Destroys a mutex. 
pthread_mutex_init( )
int pthread_mutex_init (
pthread_mutex_t *mutex,
const pthread_mutexattr_t *attr);
Initializes a mutex with the attributes specified in the specified mutex attribute object. If attr is NULL, the default attributes are used. 
pthread_mutex_lock( )
int pthread_mutex_lock (
pthread_mutex_t *mutex);
Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the thread that currently holds the mutex releases it. 
pthread_mutex_trylock( )
int pthread_mutex_trylock (
pthread_mutex_t *mutex);
Tries to lock a mutex. If the mutex is already locked, the calling thread returns without waiting for the mutex to be freed. 
pthread_mutex_unlock( )
int pthread_mutex_unlock (
pthread_mutex_t *mutex);
Unlocks a mutex. The scheduling priority determines which blocked thread is resumed. The resumed thread may or may not succeed in its next attempt to lock the mutex, depending upon whether another thread has locked the mutex in the interval between the thread's being resumed and its issuing the pthread_mutex_lock call. 
pthread_once( )
int pthread_once (
pthread_once_t *once_block,
void (*init_routine) (void);
Ensures that init_routine will run just once regardless of how many threads in a process call it. All threads issue calls to the routine by making identical pthread_once calls (with the same once_block and init_routine). The thread that first makes the pthread_once call succeeds in running the routine; subsequent pthread_once calls from other threads do not run the routine. 
pthread_self( )
pthread_t pthread_self (
void);
Obtains the thread handle of the calling thread. 
pthread_setcancelstate( )
int pthread_setcancelstate (
int state,
int *oldstate);
Sets a thread's cancelability state. You can enable a thread's cancellation by specifying the PTHREAD_CANCEL_ENABLE state, or disable it by specifying PTHREAD_CANCEL_DISABLE. 
pthread_setcanceltype( )
int pthread_setcanceltype (
int type,
int *oldtype);
Sets a thread's cancelability type. To allow a thread to receive cancellation orders only at defined cancellation points, you can specify the PTHREAD_CANCEL_DEFERRED type; this is the default. To allow a thread to be canceled at any point during its execution, you can specify PTHREAD_CANCEL_ASYNCHRONOUS. 
pthread_setschedparam( )
int pthread_setschedparam (
pthread_t thread,
int policy,
const struct sched_param *param);
Adjusts the scheduling policy and scheduling parameters of an existing thread. (This function differs from the functions pthread_attr_setschedpolicy and pthread_attr_setschedparam in that they set the policy and parameters that will be used whenever a new thread is created.) 
pthread_setspecific( )
int pthread_setspecific (
pthread_key_t key,
void *value);
Sets the thread-specific data value associated with the specified key in the calling thread. 
pthread_sigmask( )
int pthread_sigmask (
int how,
const sigset_t *set,
sigset_t *oset);
Examines or changes the calling thread's signal mask.
pthread_testcancel( )
void pthread_testcancel (
void);
Requests that any pending cancellation request be delivered to the calling thread.

Previous Section
Books24x7.com, Inc 2000   Feedback