--- name: "xlocale" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd", "macos"] url: "https://new.carta.tech/xlocale" --- # xlocale(3) Thread-safe extended locale support ## NAME **xlocale** – Thread-safe extended locale support ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** ## DESCRIPTION The extended locale support includes a set of functions for setting thread-local locales, as well convenience functions for performing locale-aware calls with a specified locale. The core of the xlocale API is the *locale\_t* type. This is an opaque type encapsulating a locale. Instances of this can be either set as the locale for a specific thread or passed directly to the *\_l* suffixed variants of various standard C functions. Two special *locale\_t* values are available: - NULL refers to the current locale for the thread, or to the global locale if no locale has been set for this thread. - LC\_GLOBAL\_LOCALE refers to the global locale. The global locale is the locale set with the [setlocale(3)](/setlocale/3.md) function. ## SEE ALSO [duplocale(3)](/duplocale/3.md), [freelocale(3)](/freelocale/3.md), [localeconv(3)](/localeconv/3.md), [newlocale(3)](/newlocale/3.md), [querylocale(3)](/querylocale/3.md), [uselocale(3)](/uselocale/3.md) ## CONVENIENCE FUNCTIONS The xlocale API includes a number of *\_l* suffixed convenience functions. These are variants of standard C functions that have been modified to take an explicit *locale\_t* parameter as the final argument or, in the case of variadic functions, as an additional argument directly before the format string. Each of these functions accepts either NULL or LC\_GLOBAL\_LOCALE. In these functions, NULL refers to the C locale, rather than the thread's current locale. If you wish to use the thread's current locale, then use the unsuffixed version of the function. These functions are exposed by including ⟨xlocale.h⟩ *after* including the relevant headers for the standard variant. For example, the [strtol\_l(3)](/strtol_l/3.md) function is exposed by including ⟨xlocale.h⟩ after ⟨stdlib.h⟩, which defines [strtol(3)](/strtol/3.md). For reference, a complete list of the locale-aware functions that are available in this form, along with the headers that expose them, is provided here: - In wctype.h [iswalnum\_l(3)](/iswalnum_l/3.md), [iswalpha\_l(3)](/iswalpha_l/3.md), [iswcntrl\_l(3)](/iswcntrl_l/3.md), [iswctype\_l(3)](/iswctype_l/3.md), [iswdigit\_l(3)](/iswdigit_l/3.md), [iswgraph\_l(3)](/iswgraph_l/3.md), [iswlower\_l(3)](/iswlower_l/3.md), [iswprint\_l(3)](/iswprint_l/3.md), [iswpunct\_l(3)](/iswpunct_l/3.md), [iswspace\_l(3)](/iswspace_l/3.md), [iswupper\_l(3)](/iswupper_l/3.md), [iswxdigit\_l(3)](/iswxdigit_l/3.md), [towlower\_l(3)](/towlower_l/3.md), [towupper\_l(3)](/towupper_l/3.md), [wctype\_l(3)](/wctype_l/3.md), - In ctype.h [digittoint\_l(3)](/digittoint_l/3.md), [isalnum\_l(3)](/isalnum_l/3.md), [isalpha\_l(3)](/isalpha_l/3.md), [isblank\_l(3)](/isblank_l/3.md), [iscntrl\_l(3)](/iscntrl_l/3.md), [isdigit\_l(3)](/isdigit_l/3.md), [isgraph\_l(3)](/isgraph_l/3.md), [ishexnumber\_l(3)](/ishexnumber_l/3.md), [isideogram\_l(3)](/isideogram_l/3.md), [islower\_l(3)](/islower_l/3.md), [isnumber\_l(3)](/isnumber_l/3.md), [isphonogram\_l(3)](/isphonogram_l/3.md), [isprint\_l(3)](/isprint_l/3.md), [ispunct\_l(3)](/ispunct_l/3.md), [isrune\_l(3)](/isrune_l/3.md), [isspace\_l(3)](/isspace_l/3.md), [isspecial\_l(3)](/isspecial_l/3.md), [isupper\_l(3)](/isupper_l/3.md), [isxdigit\_l(3)](/isxdigit_l/3.md), [tolower\_l(3)](/tolower_l/3.md), [toupper\_l(3)](/toupper_l/3.md) - In inttypes.h strtoimax\_l(3), strtoumax\_l(3), wcstoimax\_l(3), wcstoumax\_l(3) - In langinfo.h [nl\_langinfo\_l(3)](/nl_langinfo_l/3.md) - In monetary.h [strfmon\_l(3)](/strfmon_l/3.md) - In stdio.h [asprintf\_l(3)](/asprintf_l/3.md), [fprintf\_l(3)](/fprintf_l/3.md), [fscanf\_l(3)](/fscanf_l/3.md), [printf\_l(3)](/printf_l/3.md), [scanf\_l(3)](/scanf_l/3.md), [snprintf\_l(3)](/snprintf_l/3.md), [sprintf\_l(3)](/sprintf_l/3.md), [sscanf\_l(3)](/sscanf_l/3.md), [vasprintf\_l(3)](/vasprintf_l/3.md), [vfprintf\_l(3)](/vfprintf_l/3.md), [vfscanf\_l(3)](/vfscanf_l/3.md), [vprintf\_l(3)](/vprintf_l/3.md), [vscanf\_l(3)](/vscanf_l/3.md), [vsnprintf\_l(3)](/vsnprintf_l/3.md), [vsprintf\_l(3)](/vsprintf_l/3.md), [vsscanf\_l(3)](/vsscanf_l/3.md) - In stdlib.h mblen\_l(3), mbstowcs\_l(3), mbtowc\_l(3), [strtod\_l(3)](/strtod_l/3.md), strtof\_l(3), [strtol\_l(3)](/strtol_l/3.md), strtold\_l(3), strtoll\_l(3), strtoul\_l(3), strtoull\_l(3), wcstombs\_l(3), wctomb\_l(3) - In string.h [strcoll\_l(3)](/strcoll_l/3.md), [strxfrm\_l(3)](/strxfrm_l/3.md), [strcasecmp\_l(3)](/strcasecmp_l/3.md), [strcasestr\_l(3)](/strcasestr_l/3.md), [strncasecmp\_l(3)](/strncasecmp_l/3.md) - In time.h [strftime\_l(3)](/strftime_l/3.md) [strptime\_l(3)](/strptime_l/3.md) - In 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)](/getwc_l/3.md), getwchar\_l(3), mbrlen\_l(3), mbrtowc\_l(3), mbsinit\_l(3), mbsnrtowcs\_l(3), mbsrtowcs\_l(3), [putwc\_l(3)](/putwc_l/3.md), 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)](/wcstod_l/3.md), wcstof\_l(3), [wcstol\_l(3)](/wcstol_l/3.md), 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)](/wprintf_l/3.md), [wscanf\_l(3)](/wscanf_l/3.md) - In wctype.h [iswblank\_l(3)](/iswblank_l/3.md), [iswhexnumber\_l(3)](/iswhexnumber_l/3.md), [iswideogram\_l(3)](/iswideogram_l/3.md), [iswnumber\_l(3)](/iswnumber_l/3.md), [iswphonogram\_l(3)](/iswphonogram_l/3.md), [iswrune\_l(3)](/iswrune_l/3.md), [iswspecial\_l(3)](/iswspecial_l/3.md), [nextwctype\_l(3)](/nextwctype_l/3.md), [towctrans\_l(3)](/towctrans_l/3.md), [wctrans\_l(3)](/wctrans_l/3.md) - In xlocale.h [localeconv\_l(3)](/localeconv_l/3.md) ## STANDARDS The functions conform to IEEE Std 1003.1-2008 (“POSIX.1”). ## HISTORY The xlocale APIs first appeared in Darwin 8.0. This implementation was written by David Chisnall, under sponsorship from the FreeBSD Foundation and first appeared in FreeBSD 9.1. ## CAVEATS The [setlocale(3)](/setlocale/3.md) function, and others in the family, refer to the global locale. Other functions that depend on the locale, however, will take the thread-local locale if one has been set. This means that the idiom of setting the locale using [setlocale(3)](/setlocale/3.md), calling a locale-dependent function, and then restoring the locale will not have the expected behavior if the current thread has had a locale set using [uselocale(3)](/uselocale/3.md). You should avoid this idiom and prefer to use the *\_l* suffixed versions instead.