--- name: "pthread" section: "3" platform: "macos" package: "libpthread" version: "539.100.4" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/pthread" --- # pthread(3) POSIX thread functions ## NAME **pthread** – POSIX thread functions ## SYNOPSIS **#include \** ## 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 following groups: - Thread Routines - Attribute Object Routines - Mutex Routines - Condition Variable Routines - Read/Write Lock Routines - Per-Thread Context Routines - Cleanup Routines ### Thread Routines - *int* **pthread\_create**(*pthread\_t \*thread*, *const pthread\_attr\_t \*attr*, *void \*\*start\_routinevoid \**, *void \*arg*) Creates a new thread of execution. - *int* **pthread\_cancel**(*pthread\_t thread*) Cancels execution of a thread. - *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\_kill**(*pthread\_t thread*, *int sig*) Delivers a signal to a specified thread. - *int* **pthread\_once**(*pthread\_once\_t \*once\_control*, *void \*init\_routinevoid*) Calls an initialization routine once. - *pthread\_t* **pthread\_self**(*void*) Returns the thread ID of the calling thread. - *int* **pthread\_setcancelstate**(*int state*, *int \*oldstate*) Sets the current thread's cancelability state. - *int* **pthread\_setcanceltype**(*int type*, *int \*oldtype*) Sets the current thread's cancelability type. - *void* **pthread\_testcancel**(*void*) Creates a cancellation point in the calling thread. ### 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\_getprioceiling**(*pthread\_mutexattr\_t \*attr*, *int \*ceiling*) Obtain priority ceiling attribute of mutex attribute object. - *int* **pthread\_mutexattr\_getprotocol**(*pthread\_mutexattr\_t \*attr*, *int \*protocol*) Obtain protocol attribute of mutex attribute object. - *int* **pthread\_mutexattr\_gettype**(*pthread\_mutexattr\_t \*attr*, *int \*type*) Obtain the mutex type attribute in the specified mutex attributes object. - *int* **pthread\_mutexattr\_init**(*pthread\_mutexattr\_t \*attr*) Initialize a mutex attributes object with default values. - *int* **pthread\_mutexattr\_setprioceiling**(*pthread\_mutexattr\_t \*attr*, *int ceiling*) Set priority ceiling attribute of mutex attribute object. - *int* **pthread\_mutexattr\_setprotocol**(*pthread\_mutexattr\_t \*attr*, *int protocol*) Set protocol attribute of mutex attribute object. - *int* **pthread\_mutexattr\_settype**(*pthread\_mutexattr\_t \*attr*, *int type*) Set the mutex type attribute that is used when a mutex is created. - *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 do not 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\_destroy**(*pthread\_condattr\_t \*attr*) Destroy a condition variable attributes object. - *int* **pthread\_condattr\_init**(*pthread\_condattr\_t \*attr*) Initialize a condition variable attributes object with default values. - *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*) Unlock the specified mutex, wait no longer than the specified time for a condition, and then relock the mutex. - *int* **pthread\_cond\_wait**(*pthread\_cond\_t \**, *pthread\_mutex\_t \*mutex*) Unlock the specified mutex, wait for a condition, and relock the 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 \*routinevoid \**) 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 - *int* **pthread\_atfork**(*void \*preparevoid*, *void \*parentvoid*, *void \*childvoid*) Register fork handlers. - *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 \*routinevoid \**, *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 these interfaces. ## SEE ALSO [pthread\_atfork(3)](/pthread_atfork/3.md), [pthread\_attr(3)](/pthread_attr/3.md), [pthread\_cancel(3)](/pthread_cancel/3.md), [pthread\_cleanup\_pop(3)](/pthread_cleanup_pop/3.md), [pthread\_cleanup\_push(3)](/pthread_cleanup_push/3.md), [pthread\_cond\_broadcast(3)](/pthread_cond_broadcast/3.md), [pthread\_cond\_destroy(3)](/pthread_cond_destroy/3.md), [pthread\_cond\_init(3)](/pthread_cond_init/3.md), [pthread\_cond\_signal(3)](/pthread_cond_signal/3.md), [pthread\_cond\_timedwait(3)](/pthread_cond_timedwait/3.md), [pthread\_cond\_wait(3)](/pthread_cond_wait/3.md), [pthread\_condattr(3)](/pthread_condattr/3.md), [pthread\_condattr\_destroy(3)](/pthread_condattr_destroy/3.md), [pthread\_condattr\_init(3)](/pthread_condattr_init/3.md), [pthread\_create(3)](/pthread_create/3.md), [pthread\_detach(3)](/pthread_detach/3.md), [pthread\_equal(3)](/pthread_equal/3.md), [pthread\_exit(3)](/pthread_exit/3.md), [pthread\_getschedparam(3)](/pthread_getschedparam/3.md), [pthread\_getspecific(3)](/pthread_getspecific/3.md), [pthread\_join(3)](/pthread_join/3.md), [pthread\_key\_create(3)](/pthread_key_create/3.md), [pthread\_key\_delete(3)](/pthread_key_delete/3.md), [pthread\_kill(3)](/pthread_kill/3.md), [pthread\_mutex\_destroy(3)](/pthread_mutex_destroy/3.md), [pthread\_mutex\_init(3)](/pthread_mutex_init/3.md), [pthread\_mutex\_lock(3)](/pthread_mutex_lock/3.md), [pthread\_mutex\_trylock(3)](/pthread_mutex_trylock/3.md), [pthread\_mutex\_unlock(3)](/pthread_mutex_unlock/3.md), [pthread\_mutexattr(3)](/pthread_mutexattr/3.md), [pthread\_mutexattr\_destroy(3)](/pthread_mutexattr_destroy/3.md), [pthread\_mutexattr\_getprioceiling(3)](/pthread_mutexattr_getprioceiling/3.md), [pthread\_mutexattr\_getprotocol(3)](/pthread_mutexattr_getprotocol/3.md), [pthread\_mutexattr\_gettype(3)](/pthread_mutexattr_gettype/3.md), [pthread\_mutexattr\_init(3)](/pthread_mutexattr_init/3.md), [pthread\_mutexattr\_setprioceiling(3)](/pthread_mutexattr_setprioceiling/3.md), [pthread\_mutexattr\_setprotocol(3)](/pthread_mutexattr_setprotocol/3.md), [pthread\_mutexattr\_settype(3)](/pthread_mutexattr_settype/3.md), [pthread\_once(3)](/pthread_once/3.md), [pthread\_rwlock\_destroy(3)](/pthread_rwlock_destroy/3.md), [pthread\_rwlock\_init(3)](/pthread_rwlock_init/3.md), [pthread\_rwlock\_rdlock(3)](/pthread_rwlock_rdlock/3.md), [pthread\_rwlock\_tryrdlock(3)](/pthread_rwlock_tryrdlock/3.md), [pthread\_rwlock\_trywrlock(3)](/pthread_rwlock_trywrlock/3.md), [pthread\_rwlock\_unlock(3)](/pthread_rwlock_unlock/3.md), [pthread\_rwlock\_wrlock(3)](/pthread_rwlock_wrlock/3.md), [pthread\_rwlockattr\_destroy(3)](/pthread_rwlockattr_destroy/3.md), [pthread\_rwlockattr\_getpshared(3)](/pthread_rwlockattr_getpshared/3.md), [pthread\_rwlockattr\_init(3)](/pthread_rwlockattr_init/3.md), [pthread\_rwlockattr\_setpshared(3)](/pthread_rwlockattr_setpshared/3.md), [pthread\_self(3)](/pthread_self/3.md), [pthread\_setcancelstate(3)](/pthread_setcancelstate/3.md), [pthread\_setcanceltype(3)](/pthread_setcanceltype/3.md), [pthread\_setspecific(3)](/pthread_setspecific/3.md), [pthread\_testcancel(3)](/pthread_testcancel/3.md) ## STANDARDS The functions with the **pthread\_** prefix and not **\_np** suffix or **pthread\_rwlock** prefix conform to ISO/IEC 9945-1:1996 (“POSIX.1”). The functions with the **pthread\_** prefix and **\_np** suffix are non-portable extensions to POSIX threads. The functions with the **pthread\_rwlock** prefix are extensions created by The Open Group as part of the Version 2 of the Single UNIX Specification (“SUSv2”).