---
name: "xlocale"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["freebsd", "macos"]
url: "https://new.carta.tech/xlocale"
---

# xlocale(3)

Extended locale support.

## NAME

**xlocale** – Extended locale support.

## LIBRARY

Standard C Library (libc, -lc)

## DESCRIPTION

Include ⟨xlocale.h⟩ for extended locale support. It can be used alone or with the POSIX locale API in ⟨locale.h⟩.

The extended locale, or "xlocale" API consists of five basic routines, which are documented separately: [duplocale(3)](/duplocale/3.md), [freelocale(3)](/freelocale/3.md), [newlocale(3)](/newlocale/3.md), [querylocale(3)](/querylocale/3.md), and [uselocale(3)](/uselocale/3.md). For each of these routines, if a NULL *locale\_t* is given, the current locale is used.

In addition, ⟨xlocale.h⟩ defines a few macros:

- LC\_GLOBAL\_LOCALE - A special *locale\_t* value that corresponds to the global, process-wide locale.

- LC\_C\_LOCALE - A special *locale\_t* value that corresponds to the C, system locale.

- MB\_CUR\_MAX - This macro is traditionally defined as an integer containing the value of the longest multi-byte string that a single-wide character in the global locale can translate into. With extended locales, this macro is replaced with a function that returns the value of the longest multi-byte string that a single-wide character in the current locale (per-thread or global) can translate into.

- MB\_CUR\_MAX\_L(loc) - This macro is equivalent to MB\_CUR\_MAX, except that it may be passed a specific locale directly.

## CAVEATS

The POSIX [setlocale(3)](/setlocale/3.md) function only affects the global locale, so using it when a per-thread locale is in effect will not change locale behavior for that thread. However, it will change behavior for threads with no per-thread locale in effect. #ifdef UNIFDEF\_LEGACY\_RUNE\_APIS

The routines defined in ⟨rune.h⟩ are deprecated, and may not be fully consistent with the xlocale API. Of particular note is **setinvalidrune**(), which would normally modify the value in the global locale. Since this value resides in a sub-structure of *locale\_t* and sub-structures may be shared by multiple locales, **setinvalidrune**() has been modified to make a copy of the sub-structure. This prevents it from affecting other locales. #endif /\* UNIFDEF\_LEGACY\_RUNE\_APIS \*/

## 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 also includes "convenience functions": functions that can be executed using a given locale, rather than the current locale. These functions all take one extra *locale\_t* argument at the end of the traditional argument list, except in the case of variable-argument functions, in which case the extra argument comes before the format string. If a NULL *locale\_t* is passed, the C locale will be used.

For completeness, the convenience functions are listed here (organized by the header file that contains the original function).

- ⟨\_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)

- ⟨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)

- ⟨inttypes.h⟩

  strtoimax\_l(3), strtoumax\_l(3), wcstoimax\_l(3), wcstoumax\_l(3)

- ⟨langinfo.h⟩

  [nl\_langinfo\_l(3)](/nl_langinfo_l/3.md)

- ⟨monetary.h⟩

  [strfmon\_l(3)](/strfmon_l/3.md)

- ⟨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)

- ⟨stdlib.h⟩

  atof\_l(3), atoi\_l(3), atol\_l(3), atoll\_l(3), 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), strtoq\_l(3), strtoul\_l(3), strtoull\_l(3), strtouq\_l(3), wcstombs\_l(3), wctomb\_l(3)

- ⟨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)

- ⟨time.h⟩

  [strftime\_l(3)](/strftime_l/3.md), [strptime\_l(3)](/strptime_l/3.md)

- ⟨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)

- ⟨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)

- ⟨xlocale.h⟩

  [localeconv\_l(3)](/localeconv_l/3.md)