TlsGetValue 函数（processthreadsapi.h）

项目
11/18/2024

检索指定 TLS 索引的调用线程本地存储（TLS）槽中的值。进程的每个线程都有自己的每个 TLS 索引的槽。

语法

LPVOID TlsGetValue(
  [in] DWORD dwTlsIndex
);

参数

[in] dwTlsIndex

由 TlsAlloc 函数分配的 TLS 索引。

返回值

如果函数成功，则返回值是存储在与指定索引关联的调用线程的 TLS 槽中的值。如果 dwTlsIndex 是由成功调用 tlsAlloc分配的有效索引，则此函数始终成功。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

存储在 TLS 槽中的数据可以具有值 0，因为它仍具有其初始值，或者由于线程调用了 TlsSetValue 函数，且值为 0。因此，如果返回值为 0，则必须在确定函数失败之前检查 GetLastError 是否返回 ERROR_SUCCESS。如果 GetLastError 返回 ERROR_SUCCESS，则函数已成功，TLS 槽中存储的数据为 0。否则，函数已失败。

返回失败 SetLastError 故障调用指示的函数。它们通常不会在成功时调用 setLastError 。 TlsGetValue 函数是此常规规则的例外。 TlsGetValue 函数调用 SetLastError，以在线程成功时清除线程的最后一个错误。这允许检查零值的无错误检索。

言论

Windows 8.1、Windows Server 2012 R2，Windows 10 版本 1507：Windows 8.1、Windows Server 2012 R2 和 Windows 10 版本 1507 上的 Windows 应用商店应用支持此功能。当 Windows 应用商店应用调用此函数时，它将替换为对 FlsGetValue的内联调用。有关函数文档，请参阅 FlsGetValue。

Windows 10 版本 1511 和 Windows 10 版本 1607：此函数对通用 Windows 平台（UWP）应用完全受支持，不再替换为对 FlsGetValue的内联调用。

TLS 索引通常由 TlsAlloc 函数在进程或 DLL 初始化期间分配。分配 TLS 索引后，进程的每个线程都可以使用它来访问该索引的自己的 TLS 槽。线程在调用 TlsSetValue 中指定 TLS 索引，以在其槽中存储值。线程在后续调用中指定相同的索引，TlsGetValue 检索存储的值。

TlsGetValue 以速度作为主要目标实现。该函数执行最少的参数验证和错误检查。具体而言，如果 dwTlsIndex 的范围为 0 到（TLS_MINIMUM_AVAILABLE– 1），则成功。由程序员决定，确保索引有效，线程在调用 TlsGetValue之前调用 TlsSetValue。

TlsGetValue 始终设置线程的最后一个错误。在某些情况下，应用程序（例如具有支持 malloc 的自定义堆）可能需要调用 GetLastError，然后再调用 TlsGetValue 以保存线程的最后一个错误（后跟 SetLastError 还原保存的错误）。遗憾的是，这可能会在某些 CPU 上产生一些不平凡的性能成本。

Windows 11 24H2 及更高版本： 使用 TlsGetValue2 函数，该函数与 TlsGetValue 相同，只不过它未设置线程的最后一个错误。调用 TlsGetValue2 的应用程序应避免将 0 用作有效值，因为无法调用 GetLastError 来检查 TlsGetValue2 是否失败。

例子

有关示例，请参阅使用线程本地存储或在 Dynamic-Link 库中使用线程本地存储。

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	processthreadsapi.h （包括 Windows Vista 上的 Windows.h、Windows 7、Windows Server 2008 Windows Server 2008 R2）
库	Kernel32.lib;Windows Phone 8.1 上的 WindowsPhoneCore.lib
DLL	Windows Phone 8.1 上的 KernelBase.dll;Kernel32.dll