> For the complete documentation index, see [llms.txt](https://man.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://man.bsdcn.org/pthread/pthread.3.md). # pthread(3) `pthread` — POSIX 线程函数 ## 名称 `pthread` ## 库 Lb libpthread ## 概要 `#include ` ## 描述 POSIX 线程是一组支持在同一进程中具有多个控制流（称为*线程*）的应用程序的函数。多线程用于提升程序性能。 POSIX 线程函数在本节中按以下分组进行总结： * 线程例程 * 属性对象例程 * 互斥锁例程 * 条件变量例程 * 读写锁例程 * 线程特定上下文例程 * 清理例程 POSIX 线程函数的 FreeBSD 扩展在 [pthread\_np(3)](/pthread/pthread_np.3.md) 中总结。 ### 线程例程 **Xo** Ft int Fo pthread\_create `pthread_t *thread const pthread_attr_t *attr` `void **start_routinevoid * void *arg` Fc Xc 创建一个新的执行线程。 **Xo** Ft int Fn pthread\_cancel pthread\_t thread Xc 取消一个线程的执行。 **Xo** Ft int Fn pthread\_detach pthread\_t thread Xc 标记一个线程以便删除。 **Xo** Ft int Fn pthread\_equal pthread\_t t1 pthread\_t t2 Xc 比较两个线程 ID。 **Xo** Ft void Fn pthread\_exit void \*value\_ptr Xc 终止调用线程。 **Xo** Ft int Fn pthread\_join pthread\_t thread void \*\*value\_ptr Xc 使调用线程等待指定线程终止。 **Xo** Ft int Fn pthread\_kill pthread\_t thread int sig Xc 向指定线程发送信号。 **Xo** Ft int Fn pthread\_once pthread\_once\_t \*once\_control void \*init\_routinevoid Xc 调用初始化例程一次。 **Xo** Ft pthread\_t Fn pthread\_self void Xc 返回调用线程的线程 ID。 **Xo** Ft int Fn pthread\_setcancelstate int state int \*oldstate Xc 设置当前线程的可取消状态。 **Xo** Ft int Fn pthread\_setcanceltype int type int \*oldtype Xc 设置当前线程的可取消类型。 **Xo** Ft void Fn pthread\_testcancel void Xc 在调用线程中创建一个取消点。 **Xo** Ft void Fn pthread\_yield void Xc 允许调度器运行其他线程而非当前线程。 ### 属性对象例程 **Xo** Ft int Fn pthread\_attr\_destroy pthread\_attr\_t \*attr Xc 销毁线程属性对象。 **Xo** Ft int Fo pthread\_attr\_getinheritsched `const pthread_attr_t *attr int *inheritsched` Fc Xc 从线程属性对象中获取继承调度属性。 **Xo** Ft int Fo pthread\_attr\_getschedparam `const pthread_attr_t *attr struct sched_param *param` Fc Xc 从线程属性对象中获取调度参数属性。 **Xo** Ft int Fn pthread\_attr\_getschedpolicy const pthread\_attr\_t \*attr int \*policy Xc 从线程属性对象中获取调度策略属性。 **Xo** Ft int Fn pthread\_attr\_getscope const pthread\_attr\_t \*attr int \*contentionscope Xc 从线程属性对象中获取竞争范围属性。 **Xo** Ft int Fn pthread\_attr\_getstacksize const pthread\_attr\_t \*attr size\_t \*stacksize Xc 从线程属性对象中获取栈大小属性。 **Xo** Ft int Fn pthread\_attr\_getstackaddr const pthread\_attr\_t \*attr void \*\*stackaddr Xc 从线程属性对象中获取栈地址属性。 **Xo** Ft int Fn pthread\_attr\_getdetachstate const pthread\_attr\_t \*attr int \*detachstate Xc 从线程属性对象中获取分离状态属性。 **Xo** Ft int Fn pthread\_attr\_init pthread\_attr\_t \*attr Xc 以默认值初始化线程属性对象。 **Xo** Ft int Fn pthread\_attr\_setinheritsched pthread\_attr\_t \*attr int inheritsched Xc 在线程属性对象中设置继承调度属性。 **Xo** Ft int Fo pthread\_attr\_setschedparam `pthread_attr_t *attr const struct sched_param *param` Fc Xc 在线程属性对象中设置调度参数属性。 **Xo** Ft int Fn pthread\_attr\_setschedpolicy pthread\_attr\_t \*attr int policy Xc 在线程属性对象中设置调度策略属性。 **Xo** Ft int Fn pthread\_attr\_setscope pthread\_attr\_t \*attr int contentionscope Xc 在线程属性对象中设置竞争范围属性。 **Xo** Ft int Fn pthread\_attr\_setstacksize pthread\_attr\_t \*attr size\_t stacksize Xc 在线程属性对象中设置栈大小属性。 **Xo** Ft int Fn pthread\_attr\_setstackaddr pthread\_attr\_t \*attr void \*stackaddr Xc 在线程属性对象中设置栈地址属性。 **Xo** Ft int Fn pthread\_attr\_setdetachstate pthread\_attr\_t \*attr int detachstate Xc 在线程属性对象中设置分离状态。 ### 互斥锁例程 **Xo** Ft int Fn pthread\_mutexattr\_destroy pthread\_mutexattr\_t \*attr Xc 销毁互斥锁属性对象。 **Xo** Ft int Fn pthread\_mutexattr\_getprioceiling const pthread\_mutexattr\_t \*restrict attr int \*restrict ceiling Xc 获取互斥锁属性对象的优先级上限属性。 **Xo** Ft int Fn pthread\_mutexattr\_getprotocol const pthread\_mutexattr\_t \*restrict attr int \*restrict protocol Xc 获取互斥锁属性对象的协议属性。 **Xo** Ft int Fn pthread\_mutexattr\_gettype const pthread\_mutexattr\_t \*restrict attr int \*restrict type Xc 获取指定互斥锁属性对象中的互斥锁类型属性。 **Xo** Ft int Fn pthread\_mutexattr\_init pthread\_mutexattr\_t \*attr Xc 以默认值初始化互斥锁属性对象。 **Xo** Ft int Fn pthread\_mutexattr\_setprioceiling pthread\_mutexattr\_t \*attr int ceiling Xc 设置互斥锁属性对象的优先级上限属性。 **Xo** Ft int Fn pthread\_mutexattr\_setprotocol pthread\_mutexattr\_t \*attr int protocol Xc 设置互斥锁属性对象的协议属性。 **Xo** Ft int Fn pthread\_mutexattr\_settype pthread\_mutexattr\_t \*attr int type Xc 设置创建互斥锁时使用的互斥锁类型属性。 **Xo** Ft int Fn pthread\_mutex\_destroy pthread\_mutex\_t \*mutex Xc 销毁互斥锁。 **Xo** Ft int Fo pthread\_mutex\_init `pthread_mutex_t *mutex const pthread_mutexattr_t *attr` Fc Xc 以指定属性初始化互斥锁。 **Xo** Ft int Fn pthread\_mutex\_lock pthread\_mutex\_t \*mutex Xc 锁定互斥锁并阻塞直至其可用。 **Xo** Ft int Fo pthread\_mutex\_timedlock `pthread_mutex_t *mutex const struct timespec *abstime` Fc Xc 锁定互斥锁并阻塞直至其可用或超时。 **Xo** Ft int Fn pthread\_mutex\_trylock pthread\_mutex\_t \*mutex Xc 尝试锁定互斥锁，但如果互斥锁已被其他线程（包括当前线程）锁定，则不阻塞。 **Xo** Ft int Fn pthread\_mutex\_unlock pthread\_mutex\_t \*mutex Xc 解锁互斥锁。 ### 条件变量例程 **Xo** Ft int Fn pthread\_condattr\_destroy pthread\_condattr\_t \*attr Xc 销毁条件变量属性对象。 **Xo** Ft int Fn pthread\_condattr\_init pthread\_condattr\_t \*attr Xc 以默认值初始化条件变量属性对象。 **Xo** Ft int Fn pthread\_cond\_broadcast pthread\_cond\_t \*cond Xc 唤醒当前在指定条件变量上阻塞的所有线程。 **Xo** Ft int Fn pthread\_cond\_destroy pthread\_cond\_t \*cond Xc 销毁条件变量。 **Xo** Ft int Fn pthread\_cond\_init pthread\_cond\_t \*cond const pthread\_condattr\_t \*attr Xc 以指定属性初始化条件变量。 **Xo** Ft int Fn pthread\_cond\_signal pthread\_cond\_t \*cond Xc 唤醒至少一个在指定条件变量上阻塞的线程。 **Xo** Ft int Fo pthread\_cond\_timedwait `pthread_cond_t *cond pthread_mutex_t *mutex` `const struct timespec *abstime` Fc Xc 解锁指定互斥锁，等待条件的时间不超过指定时长，然后重新锁定互斥锁。 **Xo** Ft int Fn pthread\_cond\_wait pthread\_cond\_t \* pthread\_mutex\_t \*mutex Xc 解锁指定互斥锁，等待条件，然后重新锁定互斥锁。 ### 读写锁例程 **Xo** Ft int Fn pthread\_rwlock\_destroy pthread\_rwlock\_t \*lock Xc 销毁读写锁对象。 **Xo** Ft int Fo pthread\_rwlock\_init `pthread_rwlock_t *lock const pthread_rwlockattr_t *attr` Fc Xc 初始化读写锁对象。 **Xo** Ft int Fn pthread\_rwlock\_rdlock pthread\_rwlock\_t \*lock Xc 以读模式锁定读写锁，阻塞直至获得锁。 **Xo** Ft int Fn pthread\_rwlock\_tryrdlock pthread\_rwlock\_t \*lock Xc 尝试以读模式锁定读写锁，如果锁不可用则不阻塞。 **Xo** Ft int Fn pthread\_rwlock\_trywrlock pthread\_rwlock\_t \*lock Xc 尝试以写模式锁定读写锁，如果锁不可用则不阻塞。 **Xo** Ft int Fn pthread\_rwlock\_unlock pthread\_rwlock\_t \*lock Xc 解锁读写锁。 **Xo** Ft int Fn pthread\_rwlock\_wrlock pthread\_rwlock\_t \*lock Xc 以写模式锁定读写锁，阻塞直至获得锁。 **Xo** Ft int Fn pthread\_rwlockattr\_destroy pthread\_rwlockattr\_t \*attr Xc 销毁读写锁属性对象。 **Xo** Ft int Fo pthread\_rwlockattr\_getpshared `const pthread_rwlockattr_t *attr int *pshared` Fc Xc 获取读写锁属性对象的进程共享设置。 **Xo** Ft int Fn pthread\_rwlockattr\_init pthread\_rwlockattr\_t \*attr Xc 初始化读写锁属性对象。 **Xo** Ft int Fn pthread\_rwlockattr\_setpshared pthread\_rwlockattr\_t \*attr int pshared Xc 设置读写锁属性对象的进程共享设置。 ### 线程特定上下文例程 **Xo** Ft int Fn pthread\_key\_create pthread\_key\_t \*key void \*routinevoid \* Xc 创建线程特定数据键。 **Xo** Ft int Fn pthread\_key\_delete pthread\_key\_t key Xc 删除线程特定数据键。 **Xo** Ft void \* Fn pthread\_getspecific pthread\_key\_t key Xc 获取指定键的线程特定值。 **Xo** Ft int Fn pthread\_setspecific pthread\_key\_t key const void \*value\_ptr Xc 设置指定键的线程特定值。 ### 清理例程 **Xo** Ft int Fo pthread\_atfork `void *preparevoid` `void *parentvoid` `void *childvoid` Fc Xc 注册 fork 处理程序。 **Xo** Ft void Fn pthread\_cleanup\_pop int execute Xc 弹出调用线程取消清理栈顶的例程，并可选择调用它。 **Xo** Ft void Fn pthread\_cleanup\_push void \*routinevoid \* void \*routine\_arg Xc 将指定的取消清理处理程序压入调用线程的取消清理栈。 ## 实现说明 当前 FreeBSD 的 POSIX 线程实现内置于 Lb libthr 库中。它包含线程安全版本的 Lb libc 函数以及线程函数。多线程应用程序与此库链接。 ## 参见 libthr(3), [pthread\_atfork(3)](/pthread/pthread_atfork.3.md), [pthread\_attr(3)](/pthread/pthread_attr.3.md), [pthread\_cancel(3)](/pthread/pthread_cancel.3.md), [pthread\_cleanup\_pop(3)](/pthread/pthread_cleanup_pop.3.md), [pthread\_cleanup\_push(3)](/pthread/pthread_cleanup_push.3.md), [pthread\_cond\_broadcast(3)](/pthread/pthread_cond_broadcast.3.md), [pthread\_cond\_destroy(3)](/pthread/pthread_cond_destroy.3.md), [pthread\_cond\_init(3)](/pthread/pthread_cond_init.3.md), [pthread\_cond\_signal(3)](/pthread/pthread_cond_signal.3.md), [pthread\_cond\_timedwait(3)](/pthread/pthread_cond_timedwait.3.md), [pthread\_cond\_wait(3)](/pthread/pthread_cond_wait.3.md), pthread\_condattr\_destroy(3), pthread\_condattr\_init(3), [pthread\_create(3)](/pthread/pthread_create.3.md), [pthread\_detach(3)](/pthread/pthread_detach.3.md), [pthread\_equal(3)](/pthread/pthread_equal.3.md), [pthread\_exit(3)](/pthread/pthread_exit.3.md), [pthread\_getspecific(3)](/pthread/pthread_getspecific.3.md), [pthread\_join(3)](/pthread/pthread_join.3.md), [pthread\_key\_delete(3)](/pthread/pthread_key_delete.3.md), [pthread\_kill(3)](/pthread/pthread_kill.3.md), [pthread\_mutex\_destroy(3)](/pthread/pthread_mutex_destroy.3.md), [pthread\_mutex\_init(3)](/pthread/pthread_mutex_init.3.md), [pthread\_mutex\_lock(3)](/pthread/pthread_mutex_lock.3.md), [pthread\_mutex\_trylock(3)](/pthread/pthread_mutex_trylock.3.md), [pthread\_mutex\_unlock(3)](/pthread/pthread_mutex_unlock.3.md), pthread\_mutexattr\_destroy(3), pthread\_mutexattr\_getprioceiling(3), pthread\_mutexattr\_getprotocol(3), pthread\_mutexattr\_gettype(3), pthread\_mutexattr\_init(3), pthread\_mutexattr\_setprioceiling(3), pthread\_mutexattr\_setprotocol(3), pthread\_mutexattr\_settype(3), [pthread\_np(3)](/pthread/pthread_np.3.md), [pthread\_once(3)](/pthread/pthread_once.3.md), [pthread\_rwlock\_destroy(3)](/pthread/pthread_rwlock_destroy.3.md), [pthread\_rwlock\_init(3)](/pthread/pthread_rwlock_init.3.md), [pthread\_rwlock\_rdlock(3)](/pthread/pthread_rwlock_rdlock.3.md), [pthread\_rwlock\_unlock(3)](/pthread/pthread_rwlock_unlock.3.md), [pthread\_rwlock\_wrlock(3)](/pthread/pthread_rwlock_wrlock.3.md), [pthread\_rwlockattr\_destroy(3)](/pthread/pthread_rwlockattr_destroy.3.md), [pthread\_rwlockattr\_getpshared(3)](/pthread/pthread_rwlockattr_getpshared.3.md), [pthread\_rwlockattr\_init(3)](/pthread/pthread_rwlockattr_init.3.md), [pthread\_rwlockattr\_setpshared(3)](/pthread/pthread_rwlockattr_setpshared.3.md), [pthread\_self(3)](/pthread/pthread_self.3.md), pthread\_setcancelstate(3), pthread\_setcanceltype(3), [pthread\_setspecific(3)](/pthread/pthread_setspecific.3.md), [pthread\_testcancel(3)](/pthread/pthread_testcancel.3.md) ## 标准 带有 `pthread_` 前缀且不含 `_np` 后缀、或带 `pthread_rwlock` 前缀的函数遵循 ISO/IEC 9945-1:1996 ("POSIX.1") 标准。 带有 `pthread_` 前缀和 `_np` 后缀的函数是 POSIX 线程的非可移植扩展。 带有 `pthread_rwlock` 前缀的函数是由 The Open Group 作为 -susv2 的一部分创建的扩展。