> 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/locale/xlocale.3.md).

# xlocale(3)

`xlocale` — 线程安全的扩展 locale 支持

## 名称

`xlocale`

## 库

Lb libc

## 概要

`#include <xlocale.h>`

## 描述

扩展 locale 支持包含一组用于设置线程局部 locale 的函数，以及用于以指定 locale 执行 locale 相关调用的便利函数。

xlocale API 的核心是 `locale_t` 类型。这是一个封装 locale 的不透明类型。其实例既可以设置为特定线程的 locale，也可以直接传递给各种标准 C 函数的 `_l` 后缀变体。有两个特殊的 `locale_t` 值可用：

* NULL 引用该线程的当前 locale，若该线程未设置 locale 则引用全局 locale。
* LC\_GLOBAL\_LOCALE 引用全局 locale。

全局 locale 是通过 [setlocale(3)](/locale/setlocale.3.md) 函数设置的 locale。

## 参见

[duplocale(3)](/locale/duplocale.3.md), [freelocale(3)](/locale/freelocale.3.md), [localeconv(3)](/locale/localeconv.3.md), [newlocale(3)](/locale/newlocale.3.md), [querylocale(3)](/locale/querylocale.3.md), [uselocale(3)](/locale/uselocale.3.md)

## 便利函数

xlocale API 包含若干 `_l` 后缀的便利函数。这些函数是标准 C 函数的变体，经过修改以接受显式的 `locale_t` 参数作为最后一个参数；对于可变参数函数，则作为紧接在格式字符串之前的附加参数。这些函数均接受 NULL 或 LC\_GLOBAL\_LOCALE。在这些函数中，NULL 引用 C locale，而非线程的当前 locale。若希望使用线程的当前 locale，请使用不带后缀的函数版本。

通过在包含标准变体的相关头文件*之后*包含

`#include <xlocale.h>`

来暴露这些函数。例如，strtol\_l(3) 函数通过在包含

`#include <stdlib.h>`

（其定义了 strtol(3)）之后再包含

`#include <xlocale.h>`

来暴露。

供参考，此处列出以此形式提供的所有 locale 相关函数及其暴露它们的头文件：

**wctype.h** [iswalnum\_l(3)](/locale/iswalnum_l.3.md), iswalpha\_l(3), iswcntrl\_l(3), iswctype\_l(3), iswdigit\_l(3), iswgraph\_l(3), iswlower\_l(3), iswprint\_l(3), iswpunct\_l(3), iswspace\_l(3), iswupper\_l(3), iswxdigit\_l(3), towlower\_l(3), towupper\_l(3), wctype\_l(3),

**ctype.h** digittoint\_l(3), isalnum\_l(3), isalpha\_l(3), isblank\_l(3), iscntrl\_l(3), isdigit\_l(3), isgraph\_l(3), ishexnumber\_l(3), isideogram\_l(3), islower\_l(3), isnumber\_l(3), isphonogram\_l(3), isprint\_l(3), ispunct\_l(3), isrune\_l(3), isspace\_l(3), isspecial\_l(3), isupper\_l(3), isxdigit\_l(3), tolower\_l(3), toupper\_l(3)

**inttypes.h** strtoimax\_l(3), strtoumax\_l(3), wcstoimax\_l(3), wcstoumax\_l(3)

**langinfo.h** nl\_langinfo\_l(3)

**monetary.h** strfmon\_l(3)

**stdio.h** asprintf\_l(3), fprintf\_l(3), fscanf\_l(3), printf\_l(3), scanf\_l(3), snprintf\_l(3), sprintf\_l(3), sscanf\_l(3), vasprintf\_l(3), vfprintf\_l(3), vfscanf\_l(3), vprintf\_l(3), vscanf\_l(3), vsnprintf\_l(3), vsprintf\_l(3), vsscanf\_l(3)

**stdlib.h** mblen\_l(3), mbstowcs\_l(3), mbtowc\_l(3), strtod\_l(3), strtof\_l(3), strtol\_l(3), strtold\_l(3), strtoll\_l(3), strtoul\_l(3), strtoull\_l(3), wcstombs\_l(3), wctomb\_l(3)

**string.h** strcoll\_l(3), strxfrm\_l(3), strcasecmp\_l(3), strcasestr\_l(3), strncasecmp\_l(3)

**time.h** strftime\_l(3) strptime\_l(3)

**wchar.h** btowc\_l(3), fgetwc\_l(3), fgetws\_l(3), fputwc\_l(3), fputws\_l(3), fwprintf\_l(3), fwscanf\_l(3), getwc\_l(3), getwchar\_l(3), mbrlen\_l(3), mbrtowc\_l(3), mbsinit\_l(3), mbsnrtowcs\_l(3), mbsrtowcs\_l(3), putwc\_l(3), putwchar\_l(3), swprintf\_l(3), swscanf\_l(3), ungetwc\_l(3), vfwprintf\_l(3), vfwscanf\_l(3), vswprintf\_l(3), vswscanf\_l(3), vwprintf\_l(3), vwscanf\_l(3), wcrtomb\_l(3), wcscoll\_l(3), wcsftime\_l(3), wcsnrtombs\_l(3), wcsrtombs\_l(3), wcstod\_l(3), wcstof\_l(3), wcstol\_l(3), wcstold\_l(3), wcstoll\_l(3), wcstoul\_l(3), wcstoull\_l(3), wcswidth\_l(3), wcsxfrm\_l(3), wctob\_l(3), wcwidth\_l(3), wprintf\_l(3), wscanf\_l(3)

**wctype.h** iswblank\_l(3), iswhexnumber\_l(3), iswideogram\_l(3), iswnumber\_l(3), iswphonogram\_l(3), iswrune\_l(3), iswspecial\_l(3), nextwctype\_l(3), towctrans\_l(3), wctrans\_l(3)

**xlocale.h** localeconv\_l(3)

## 标准

这些函数遵循 IEEE Std 1003.1-2008 (“POSIX.1”)。

## 历史

xlocale API 首次出现于 Darwin 8.0。本实现由 David Chisnall 编写，由 FreeBSD Foundation 赞助，首次出现于 FreeBSD 9.1。

## 注意事项

[setlocale(3)](/locale/setlocale.3.md) 函数及其同族函数引用全局 locale。然而，其他依赖 locale 的函数在设置了线程局部 locale 时会使用该线程局部 locale。这意味着，若当前线程通过 [uselocale(3)](/locale/uselocale.3.md) 设置了 locale，则使用 [setlocale(3)](/locale/setlocale.3.md) 设置 locale、调用依赖 locale 的函数、再恢复 locale 的惯用法将不会产生预期行为。应避免这种惯用法，优先使用 `_l` 后缀版本。