> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/man/pthread/pthread.3.md).

# pthread.3

`pthread` — POSIX 线程函数

## 名称

`pthread`

## 库

Lb libpthread

## 概要

`#include <pthread.h>`

## 描述

POSIX 线程是一组支持在同一进程中具有多个控制流（称为*线程*）的应用程序的函数。多线程用于提升程序性能。

POSIX 线程函数在本节中按以下分组进行总结：

* 线程例程
* 属性对象例程
* 互斥锁例程
* 条件变量例程
* 读写锁例程
* 线程特定上下文例程
* 清理例程

POSIX 线程函数的 FreeBSD 扩展在 [pthread\_np(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/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)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_atfork.3.md), [pthread\_attr(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_attr.3.md), [pthread\_cancel(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cancel.3.md), [pthread\_cleanup\_pop(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cleanup_pop.3.md), [pthread\_cleanup\_push(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cleanup_push.3.md), [pthread\_cond\_broadcast(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_broadcast.3.md), [pthread\_cond\_destroy(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_destroy.3.md), [pthread\_cond\_init(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_init.3.md), [pthread\_cond\_signal(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_signal.3.md), [pthread\_cond\_timedwait(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_timedwait.3.md), [pthread\_cond\_wait(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_cond_wait.3.md), pthread\_condattr\_destroy(3), pthread\_condattr\_init(3), [pthread\_create(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_create.3.md), [pthread\_detach(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_detach.3.md), [pthread\_equal(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_equal.3.md), [pthread\_exit(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_exit.3.md), [pthread\_getspecific(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_getspecific.3.md), [pthread\_join(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_join.3.md), [pthread\_key\_delete(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_key_delete.3.md), [pthread\_kill(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_kill.3.md), [pthread\_mutex\_destroy(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_mutex_destroy.3.md), [pthread\_mutex\_init(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_mutex_init.3.md), [pthread\_mutex\_lock(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_mutex_lock.3.md), [pthread\_mutex\_trylock(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_mutex_trylock.3.md), [pthread\_mutex\_unlock(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/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)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_np.3.md), [pthread\_once(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_once.3.md), [pthread\_rwlock\_destroy(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_rwlock_destroy.3.md), [pthread\_rwlock\_init(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_rwlock_init.3.md), [pthread\_rwlock\_rdlock(3)](/man/pthread/pthread_rwlock_rdlock.3.md), [pthread\_rwlock\_unlock(3)](/man/pthread/pthread_rwlock_unlock.3.md), [pthread\_rwlock\_wrlock(3)](/man/pthread/pthread_rwlock_wrlock.3.md), [pthread\_rwlockattr\_destroy(3)](/man/pthread/pthread_rwlockattr_destroy.3.md), [pthread\_rwlockattr\_getpshared(3)](/man/pthread/pthread_rwlockattr_getpshared.3.md), [pthread\_rwlockattr\_init(3)](/man/pthread/pthread_rwlockattr_init.3.md), [pthread\_rwlockattr\_setpshared(3)](/man/pthread/pthread_rwlockattr_setpshared.3.md), [pthread\_self(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_self.3.md), pthread\_setcancelstate(3), pthread\_setcanceltype(3), [pthread\_setspecific(3)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man3/pthread_setspecific.3.md), [pthread\_testcancel(3)](/man/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 的一部分创建的扩展。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/man/pthread/pthread.3.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.