setlocale
, localeconv
—select or query locale#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.