NAME
setlocale
,
localeconv
—
select character encoding
SYNOPSIS
#include
<locale.h>
char *
setlocale
(int
category, const char
*locale);
struct lconv *
localeconv
(void);
DESCRIPTION
The
setlocale
()
function sets and retrieves the active locale for the
current process. The locale modifies the behaviour of some functions in the
C library with respect to the character encoding, and on other operating
systems also with respect to some language and cultural conventions. For
more information about locales in general, see the
locale(1) manual page.
On OpenBSD, the only useful value for the
category is LC_CTYPE
. It sets
the locale used for character encoding, character classification, and case
conversion. For compatibility with natural language support in
packages(7), all other categories —
LC_COLLATE
, LC_MESSAGES
,
LC_MONETARY
, LC_NUMERIC
, and
LC_TIME
— can be set and retrieved, too, but
their values are ignored by the OpenBSD C library. A
category of LC_ALL
sets the entire locale
generically.
The syntax and semantics of the
locale argument are not standardized and vary among
operating systems. On OpenBSD, if the
locale string ends with ".UTF-8", the UTF-8
locale is selected; otherwise, the "C" locale is selected, which
uses the ASCII character set. If the locale contains a
dot but does not end with ".UTF-8",
setlocale
()
fails.
If locale is an empty string (""),
the value of the environment variable LC_ALL
, with a
fallback to the variable corresponding to category,
and with a further fallback to LANG
, is used
instead, as documented in the
locale(1) manual page.
If locale is NULL
,
the locale remains unchanged. This can be used to determine the currently
active locale.
By default, C programs start in the "C"
locale. The only function in the library that sets the locale is
setlocale
();
the locale is never changed as a side effect of some other routine.
The
localeconv
()
function returns a pointer to a static structure which provides parameters
for formatting numbers. On OpenBSD, nothing in the
returned structure ever changes.
It provides the following fields of type char *:
- decimal_point
- The decimal point character, except for currency values.
- thousands_sep
- The separator between groups of digits before the decimal point, except for currency values.
- grouping
- The sizes of the groups of digits, except for currency values. This is a
pointer to a vector of integers, each of size
char
, representing group size from low order digit groups to high order (right to left). The list may be terminated with 0 orCHAR_MAX
. If the list is terminated with 0, the last group size before the 0 is repeated to account for all the digits. If the list is terminated withCHAR_MAX
, no more grouping is performed. - int_curr_symbol
- The standardized international currency symbol.
- currency_symbol
- The local currency symbol.
- mon_decimal_point
- The decimal point character for currency values.
- mon_thousands_sep
- The separator for digit groups in currency values.
- mon_grouping
- Like grouping but for currency values.
- positive_sign
- The character used to denote non-negative currency values, usually the empty string.
- negative_sign
- The character used to denote negative currency values, usually a minus sign.
It also provides the following fields of type char:
- int_frac_digits
- The number of digits after the decimal point in an international-style currency value.
- frac_digits
- The number of digits after the decimal point in the local style for currency values.
- p_cs_precedes
- 1 if the currency symbol precedes the currency value for non-negative values, 0 if it follows.
- p_sep_by_space
- 1 if a space is inserted between the currency symbol and the currency value for non-negative values, 0 otherwise.
- n_cs_precedes
- Like p_cs_precedes but for negative values.
- n_sep_by_space
- Like p_sep_by_space but for negative values.
- p_sign_posn
- The location of the positive_sign with respect to a
non-negative quantity and the currency_symbol, coded
as follows:
0
- Parentheses around the entire string.
1
- Before the string.
2
- After the string.
3
- Just before currency_symbol.
4
- Just after currency_symbol.
- n_sign_posn
- Like p_sign_posn but for negative currency values.
- int_p_cs_precedes
- Like p_cs_precedes but for the international symbol.
- int_n_cs_precedes
- Like n_cs_precedes but for the international symbol.
- int_p_sep_by_space
- Like p_sep_by_space but for the international symbol.
- int_n_sep_by_space
- Like n_sep_by_space but for the international symbol.
- int_p_sign_posn
- Like p_sign_posn but for the international symbol.
- int_n_sign_posn
- Like n_sign_posn but for the international symbol.
Unless mentioned above, an empty string as a value for a field
indicates a zero length result or a value that is not in the current locale.
A CHAR_MAX
result similarly denotes an unavailable
value.
RETURN VALUES
In case of success, setlocale
() returns a
pointer to a static string describing the locale that is in force after the
call. Subsequent calls to setlocale
() may change the
content of the string. The format of the string is not standardized and
varies among operating systems.
On OpenBSD, if
setlocale
() was never called with a
non-NULL
locale argument, the
string "C" is returned. Otherwise, if the
category was not LC_ALL
or if
the locale is the same for all categories, a copy of the
locale argument is returned. Otherwise, the locales
for the six categories LC_COLLATE
,
LC_CTYPE
, LC_MESSAGES
,
LC_MONETARY
, LC_NUMERIC
,
LC_TIME
are concatenated in that order, with slash
(‘/
’) characters in between.
In case of failure, setlocale
() returns
NULL
. On OpenBSD, that can
only happen if the category is invalid, if a character
encoding other than UTF-8 is requested, if the requested
locale name is of excessive length, or if memory
allocation fails.
EXAMPLES
Calling
setlocale(LC_CTYPE,
"en_US.UTF-8");
at the beginning of a program selects the UTF-8 locale and returns "en_US.UTF-8". Calling
setlocale(LC_ALL, NULL);
right afterwards leaves the locale unchanged and returns "C/en_US.UTF-8/C/C/C/C".
STANDARDS
The setlocale
() and
localeconv
() functions conform to
ANSI X3.159-1989
(“ANSI C89”).
HISTORY
The setlocale
() and
localeconv
() functions first appeared in
4.4BSD.