Mac OS X Manual Page For pthread(3) (original) (raw)

PTHREAD(3) BSD Library Functions Manual PTHREAD(3)

NAME pthread -- POSIX thread functions

SYNOPSIS #include <pthread.h>

DESCRIPTION POSIX threads are a set of functions that support applications with requirements for multiple flows of control, called threads, within a process. Multithreading is used to improve the performance of a program.

 The POSIX thread functions are summarized in this section in the follow-ing following
 ing groups:

       **oo**   Thread Routines

       **oo**   Attribute Object Routines

       **oo**   Mutex Routines

       **oo**   Condition Variable Routines

       **oo**   Read/Write Lock Routines

       **oo**   Per-Thread Context Routines

       **oo**   Cleanup Routines

THREAD ROUTINES int pthread_create(pthread**_*t thread, const pthreadattr**t *attr, void (start_**routine)(void *), void *arg) Creates a new thread of execution.

 int **pthread_detach**(pthread**_**t thread)
                    Marks a thread for deletion.

 int **pthread_equal**(pthread**_**t t1, pthread**_**t t2)
                    Compares two thread IDs.

 void **pthread_exit**(void *value**_**ptr)
                    Terminates the calling thread.

 int **pthread_join**(pthread**_**t thread, void **value**_**ptr)
                    Causes the calling thread to wait for the termination
                    of the specified thread.

 int **pthread_cancel**(pthread**_**t thread)
                    Cancels execution of a thread.

 int **pthread_once**(pthread**_**once**_**t *once**_**control, void
                    (*init**_**routine)(void))
                    Calls an initialization routine once.

 pthread**_**t **pthread_self**(void)
                    Returns the thread ID of the calling thread.

 int **pthread_atfork**(void (*prepare)(void), void (*parent)(void), void
                    (*child)(void))
                    Registers handlers to be called before and after
                    **fork**()

ATTRIBUTE OBJECT ROUTINES int pthread_attr_destroy(pthread**_attr_**t *attr) Destroy a thread attributes object.

 int **pthread_attr_getinheritsched**(const pthread**_**attr**_**t *attr, int
                    *inheritsched)
                    Get the inherit scheduling attribute from a thread
                    attributes object.

 int **pthread_attr_getschedparam**(const pthread**_**attr**_**t *attr, struct
                    sched**_**param *param)
                    Get the scheduling parameter attribute from a thread
                    attributes object.

 int **pthread_attr_getschedpolicy**(const pthread**_**attr**_**t *attr, int *policy)
                    Get the scheduling policy attribute from a thread
                    attributes object.

 int **pthread_attr_getscope**(const pthread**_**attr**_**t *attr, int
                    *contentionscope)
                    Get the contention scope attribute from a thread
                    attributes object.

 int **pthread_attr_getstacksize**(const pthread**_**attr**_**t *attr, size**_**t
                    *stacksize)
                    Get the stack size attribute from a thread attributes
                    object.

 int **pthread_attr_getstackaddr**(const pthread**_**attr**_**t *attr, void
                    **stackaddr)
                    Get the stack address attribute from a thread
                    attributes object.

 int **pthread_attr_getdetachstate**(const pthread**_**attr**_**t *attr, int
                    *detachstate)
                    Get the detach state attribute from a thread
                    attributes object.

 int **pthread_attr_init**(pthread**_**attr**_**t *attr)
                    Initialize a thread attributes object with default
                    values.

 int **pthread_attr_setinheritsched**(pthread**_**attr**_**t *attr, int inheritsched)
                    Set the inherit scheduling attribute in a thread
                    attributes object.

 int **pthread_attr_setschedparam**(pthread**_**attr**_**t *attr, const struct
                    sched**_**param *param)
                    Set the scheduling parameter attribute in a thread
                    attributes object.

 int **pthread_attr_setschedpolicy**(pthread**_**attr**_**t *attr, int policy)
                    Set the scheduling policy attribute in a thread
                    attributes object.

 int **pthread_attr_setscope**(pthread**_**attr**_**t *attr, int contentionscope)
                    Set the contention scope attribute in a thread
                    attributes object.

 int **pthread_attr_setstacksize**(pthread**_**attr**_**t *attr, size**_**t stacksize)
                    Set the stack size attribute in a thread attributes
                    object.

 int **pthread_attr_setstackaddr**(pthread**_**attr**_**t *attr, void *stackaddr)
                    Set the stack address attribute in a thread attributes
                    object.

 int **pthread_attr_setdetachstate**(pthread**_**attr**_**t *attr, int detachstate)
                    Set the detach state in a thread attributes object.

MUTEX ROUTINES int pthread_mutexattr_destroy(pthread**_mutexattr_**t *attr) Destroy a mutex attributes object.

 int **pthread_mutexattr_init**(pthread**_**mutexattr**_**t *attr)
                    Initialize a mutex attributes object with default val-ues. values.
                    ues.

 int **pthread_mutex_destroy**(pthread**_**mutex**_**t *mutex)
                    Destroy a mutex.

 int **pthread_mutex_init**(pthread**_**mutex**_**t *mutex, const pthread**_**mutexattr**_**t
                    *attr)
                    Initialize a mutex with specified attributes.

 int **pthread_mutex_lock**(pthread**_**mutex**_**t *mutex)
                    Lock a mutex and block until it becomes available.

 int **pthread_mutex_trylock**(pthread**_**mutex**_**t *mutex)
                    Try to lock a mutex, but don't block if the mutex is
                    locked by another thread, including the current
                    thread.

 int **pthread_mutex_unlock**(pthread**_**mutex**_**t *mutex)
                    Unlock a mutex.

CONDITION VARIABLE ROUTINES int pthread_condattr_init(pthread**_condattr_**t *attr) Initialize a condition variable attributes object with default values.

 int **pthread_condattr_destroy**(pthread**_**condattr**_**t *attr)
                    Destroy a condition variable attributes object.

 int **pthread_cond_broadcast**(pthread**_**cond**_**t *cond)
                    Unblock all threads currently blocked on the specified
                    condition variable.

 int **pthread_cond_destroy**(pthread**_**cond**_**t *cond)
                    Destroy a condition variable.

 int **pthread_cond_init**(pthread**_**cond**_**t *cond, const pthread**_**condattr**_**t
                    *attr)
                    Initialize a condition variable with specified
                    attributes.

 int **pthread_cond_signal**(pthread**_**cond**_**t *cond)
                    Unblock at least one of the threads blocked on the
                    specified condition variable.

 int **pthread_cond_timedwait**(pthread**_**cond**_**t *cond, pthread**_**mutex**_**t *mutex,
                    const struct timespec *abstime)
                    Wait no longer than the specified time for a condition
                    and lock the specified mutex.

 int **pthread_cond_wait**(pthread**_**cond**_**t *, pthread**_**mutex**_**t *mutex)
                    Wait for a condition and lock the specified mutex.

READ/WRITE LOCK ROUTINES int pthread_rwlock_destroy(pthread**_rwlock_**t *lock) Destroy a read/write lock object.

 int **pthread_rwlock_init**(pthread**_**rwlock**_**t *lock, const
                    pthread**_**rwlockattr**_**t *attr)
                    Initialize a read/write lock object.

 int **pthread_rwlock_rdlock**(pthread**_**rwlock**_**t *lock)
                    Lock a read/write lock for reading, blocking until the
                    lock can be acquired.

 int **pthread_rwlock_tryrdlock**(pthread**_**rwlock**_**t *lock)
                    Attempt to lock a read/write lock for reading, without
                    blocking if the lock is unavailable.

 int **pthread_rwlock_trywrlock**(pthread**_**rwlock**_**t *lock)
                    Attempt to lock a read/write lock for writing, without
                    blocking if the lock is unavailable.

 int **pthread_rwlock_unlock**(pthread**_**rwlock**_**t *lock)
                    Unlock a read/write lock.

 int **pthread_rwlock_wrlock**(pthread**_**rwlock**_**t *lock)
                    Lock a read/write lock for writing, blocking until the
                    lock can be acquired.

 int **pthread_rwlockattr_destroy**(pthread**_**rwlockattr**_**t *attr)
                    Destroy a read/write lock attribute object.

 int **pthread_rwlockattr_getpshared**(const pthread**_**rwlockattr**_**t *attr, int
                    *pshared)
                    Retrieve the process shared setting for the read/write
                    lock attribute object.

 int **pthread_rwlockattr_init**(pthread**_**rwlockattr**_**t *attr)
                    Initialize a read/write lock attribute object.

 int **pthread_rwlockattr_setpshared**(pthread**_**rwlockattr**_**t *attr, int
                    pshared)
                    Set the process shared setting for the read/write lock
                    attribute object.

PER-THREAD CONTEXT ROUTINES int pthread_key_create(pthread**_key_**t *key, void (*routine)(void *)) Create a thread-specific data key.

 int **pthread_key_delete**(pthread**_**key**_**t key)
                    Delete a thread-specific data key.

 void * **pthread_getspecific**(pthread**_**key**_**t key)
                    Get the thread-specific value for the specified key.

 int **pthread_setspecific**(pthread**_**key**_**t key, const void *value**_**ptr)
                    Set the thread-specific value for the specified key.

CLEANUP ROUTINES void pthread_cleanup_pop(int execute) Remove the routine at the top of the calling thread's cancellation cleanup stack and optionally invoke it.

 void **pthread_cleanup_push**(void (*routine)(void *), void *routine**_**arg)
                    Push the specified cancellation cleanup handler onto
                    the calling thread's cancellation stack.

INSTALLATION The default system libraries include pthread functions. No additional libraries or CFLAGS are necessary to use this API.

SEE ALSO 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_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3), pthread_getspecific(3), pthread_join(3), pthread_key_delete(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_trylock(3), pthread_mutex_unlock(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_self(3), pthread_setspecific(3)

STANDARDS The functions in libc with the pthread**_** prefix and not **_np suffix or pthread_**rwlock prefix conform to ISO/IEC 9945-1:1996 (``POSIX.1'').

 The functions in libc with the pthread**_** prefix and **_**np suffix are non-portable nonportable
 portable extensions to POSIX threads.

 The functions in libc with the pthread**_**rwlock prefix are extensions cre-ated created
 ated by The Open Group as part of the Version 2 of the Single UNIX
 Specification (``SUSv2'').

Darwin November 5, 2001 Darwin