Up: Locale

### 9.1 `setlocale`, `localeconv`—select or query locale

Synopsis

         #include <locale.h>
         char *setlocale(int category, const char *locale);
         lconv *localeconv(void);

         char *_setlocale_r(void *reent,
             int category, const char *locale);
         lconv *_localeconv_r(void *reent);

Description
`setlocale` is the facility defined by ANSI C to condition the execution environment for international collating and formatting information; `localeconv` reports on the settings of the current locale.

This is a minimal implementation, supporting only the required `"POSIX"` and `"C"` values for locale; strings representing other locales are not honored unless _MB_CAPABLE is defined.

If _MB_CAPABLE is defined, POSIX locale strings are allowed, following the form

language[_TERRITORY][.charset][@modifier]

`"language"` is a two character string per ISO 639. `"TERRITORY"` is a country code per ISO 3166. For `"charset"` and `"modifier"` see below.

Additionally to the POSIX specifier, seven extensions are supported for backward compatibility with older implementations using newlib: `"C-UTF-8"`, `"C-JIS"`, `"C-eucJP"`, `"C-SJIS"`, `C-KOI8-R`, `C-KOI8-U`, `"C-ISO-8859-x"` with 1 <= x <= 15, or `"C-CPxxx"` with xxx in [437, 720, 737, 775, 850, 852, 855, 857, 858, 862, 866, 874, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258].

Instead of `"C-"`, you can specify also `"C."`. Both variations allow to specify language neutral locales while using other charsets than ASCII, for instance `"C.UTF-8"`, which keeps all settings as in the C locale, but uses the UTF-8 charset.

Even when using POSIX locale strings, the only charsets allowed are `"UTF-8"`, `"JIS"`, `"EUCJP"`, `"SJIS"`, `KOI8-R`, `KOI8-U`, `"ISO-8859-x"` with 1 <= x <= 15, or `"CPxxx"` with xxx in [437, 720, 737, 775, 850, 852, 855, 857, 858, 862, 866, 874, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258]. Charsets are case insensitive. For instance, `"EUCJP"` and `"eucJP"` are equivalent. `"UTF-8"` can also be written without dash, as in `"UTF8"` or `"utf8"`.

(`""` is also accepted; if given, the settings are read from the corresponding LC_* environment variables and $LANG according to POSIX rules.

Under Cygwin, this implementation additionally supports the charsets `"GBK"`, `"eucKR"`, and `"Big5"`.

This implementation also supports a single modifier, `"cjknarrow"`. Any other modifier is ignored. `"cjknarrow"`, in conjunction with one of the language specifiers `"ja"`, `"ko"`, and `"zh"` specifies how the functions `wcwidth` and `wcswidth` handle characters from the "CJK Ambiguous Width" character class described in http://www.unicode.org/unicode/reports/tr11/. Usually these characters have a width of 1, unless you specify one of the aforementioned languages, in which case these characters have a width of 2. By specifying the `"cjknarrow"` modifier, these characters will have a width of one in the languages `"ja"`, `"ko"`, and `"zh"` as well.

If you use `NULL` as the locale argument, `setlocale` returns a pointer to the string representing the current locale. The acceptable values for category are defined in ``locale.h`' as macros beginning with `"LC_"`.

`localeconv` returns a pointer to a structure (also defined in ``locale.h`') describing the locale-specific conventions currently in effect.

`_localeconv_r` and `_setlocale_r` are reentrant versions of `localeconv` and `setlocale` respectively. The extra argument reent is a pointer to a reentrancy structure.

Returns
A successful call to `setlocale` returns a pointer to a string associated with the specified category for the new locale. The string returned by `setlocale` is such that a subsequent call using that string will restore that category (or all categories in case of LC_ALL), to that state. The application shall not modify the string returned which may be overwritten by a subsequent call to `setlocale`. On error, `setlocale` returns `NULL`.

`localeconv` returns a pointer to a structure of type `lconv`, which describes the formatting and collating conventions in effect (in this implementation, always those of the C locale).

Portability
ANSI C requires `setlocale`, but the only locale required across all implementations is the C locale.