> 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_key_create.3.md).

# pthread\_key\_create.3

`pthread_key_create` — 创建线程特定数据键

## 名称

`pthread_key_create`

## 库

libpthread

## 概要

```c
#include <pthread.h>

int
pthread_key_create(pthread_key_t *key, void (*destructor)(void *));
```

## 描述

`pthread_key_create` 函数创建一个对进程中所有线程可见的线程特定数据键。pthread\_key\_create 提供的键值是不透明对象，用于定位线程特定数据。虽然不同的线程可以使用相同的键值，但通过 [pthread\_setspecific(3)](/man/pthread/pthread_setspecific.3.md) 绑定到该键的值是按线程维护的，并在调用线程的生命周期内持续存在。

键创建时，所有活动线程中该新键关联的值为 NULL。线程创建时，新线程中所有已定义键关联的值为 NULL。

每个键值可选择关联一个析构函数。线程退出时，如果某个键值具有非 NULL 的析构函数指针，且该线程具有与该键关联的非 NULL 值，则以当前关联的值作为其唯一参数调用该指针所指向的函数。如果一个线程退出时有多个析构函数，析构函数的调用顺序未定义。

如果在为所有具有关联析构函数的非 NULL 值调用完所有析构函数之后，仍然存在一些具有关联析构函数的非 NULL 值，则重复该过程。如果在为未处理的非 NULL 值进行至少 `PTHREAD_DESTRUCTOR_ITERATIONS` 次析构函数调用迭代之后，仍然存在一些具有关联析构函数的非 NULL 值，实现将停止调用析构函数。

## 返回值

如果成功，`pthread_key_create` 函数会将新创建的键值存储在 `key` 指定的位置，并返回零；否则将返回一个错误号以指示错误。

## 错误

`pthread_key_create` 函数将在以下情况失败：

**`[EAGAIN]`** 系统缺乏必要的资源来创建另一个线程特定数据键，或超出系统对单个进程键总数 `PTHREAD_KEYS_MAX` 的限制。

**`[ENOMEM]`** 内存不足，无法创建键。

## 参见

[pthread\_getspecific(3)](/man/pthread/pthread_getspecific.3.md), [pthread\_key\_delete(3)](/man/pthread/pthread_key_delete.3.md), [pthread\_setspecific(3)](/man/pthread/pthread_setspecific.3.md)

## 标准

`pthread_key_create` 函数符合 ISO/IEC 9945-1:1996 ("POSIX.1") 规范。


---

# 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_key_create.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.