SETLOCALE(3) NEWLIB SETLOCALE(3)NAME
10.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 execu‐
tion environment for international collating and formatting informa‐
tion; `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, follow‐
ing the form
language[_TERRITORY][.charset][@modifier]
`"language"' is a two character string per ISO 639, or, if not
available for a given language, a three character string per ISO 639-3.
`"TERRITORY"' is a country code per ISO 3166. For `"charset"' and
`"modifier"' see below.
Additionally to the POSIX specifier, the following extension is sup‐
ported for backward compatibility with older implementations using
newlib: `"C-charset"'. Instead of `"C-"', you can also specify `"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.
The following charsets are recognized: `"UTF-8"', `"JIS"',
`"EUCJP"', `"SJIS"', `"KOI8-R"', `"KOI8-U"', `"GEORGIAN-PS"',
`"PT154"', `"TIS-620"', `"ISO-8859-x"' with 1 <= x <= 16, or `"CPxxx"'
with xxx in [437, 720, 737, 775, 850, 852, 855, 857, 858, 862, 866,
874, 932, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257, 1258].
Charsets are case insensitive. For instance, `"EUCJP"' and
`"eucJP"' are equivalent. Charset names with dashes can also be writ‐
ten without dashes, as in `"UTF8"', `"iso88591"' or `"koi8r"'.
`"EUCJP"' and `"EUCKR"' are also recognized with dash, `"EUC-JP"' and
`"EUC-KR"'.
Full support for all of the above charsets requires that newlib has
been build with multibyte support and support for all ISO and Windows
Codepage. Otherwise all singlebyte charsets are simply mapped to
ASCII. Right now, only newlib for Cygwin is built with full charset
support by default. Under Cygwin, this implementation additionally
supports the charsets `"GBK"', `"GB2312"', `"eucCN"', `"eucKR"', and
`"Big5"'. Cygwin does not support `"JIS"'.
Cygwin additionally supports locales from the file
/usr/share/locale/locale.alias.
(`""' is also accepted; if given, the settings are read from the
corresponding LC_* environment variables and $LANG according to POSIX
rules.
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.uni‐
code.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 `"cjknar‐
row"' modifier, these characters will have a width of one in the lan‐
guages `"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 associ‐
ated 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.
SEE ALSOsetlocale is part of the library. The full documentation for is main‐
tained as a Texinfo manual. If info and are properly installed at your
site, the command
info
will give you access to the complete manual.
NEWLIB April 2010 SETLOCALE(3)
