4.4BSD/usr/share/man/cat3/setlocale.0
SETLOCALE(3) BSD Programmer's Manual SETLOCALE(3)
NNAAMMEE
sseettllooccaallee, llooccaalleeccoonnvv - natural language formatting for C
SSYYNNOOPPSSIISS
##iinncclluuddee <<llooccaallee..hh>>
_c_h_a_r _*
sseettllooccaallee(_i_n_t _c_a_t_e_g_o_r_y, _c_o_n_s_t _c_h_a_r _*_l_o_c_a_l_e);
_s_t_r_u_c_t _l_c_o_n_v _*
llooccaalleeccoonnvv(_v_o_i_d);
DDEESSCCRRIIPPTTIIOONN
The sseettllooccaallee() function sets the C library's notion of natural language
formatting style for particular sets of routines. Each such style is
called a `locale' and is invoked using an appropriate name passed as a C
string. The llooccaalleeccoonnvv() routine returns the current locale's parameters
for formatting numbers.
The sseettllooccaallee() function recognizes several categories of routines.
These are the categories and the sets of routines they select:
LC_ALL Set the entire locale generically.
LC_COLLATE Set a locale for string collation routines. This controls
alphabetic ordering in ssttrrccoollll() and ssttrrxxffrrmm().
LC_CTYPE Set a locale for the ctype(3), mbrune(3), multibyte(3) and
rune(3) functions. This controls recognition of upper and
lower case, alphabetic or non-alphabetic characters, and so
on. The real work is done by the sseettrruunneellooccaallee() function.
LC_MONETARY Set a locale for formatting monetary values; this affects
the llooccaalleeccoonnvv() function.
LC_NUMERIC Set a locale for formatting numbers. This controls the for-
matting of decimal points in input and output of floating
point numbers in functions such as pprriinnttff() and ssccaannff(), as
well as values returned by llooccaalleeccoonnvv().
LC_TIME Set a locale for formatting dates and times using the
ssttrrffttiimmee() function.
Only three locales are defined by default, the empty string "" which de-
notes the native environment, and the "C" and locales, which denote the C
language environment. A _l_o_c_a_l_e argument of NULL causes sseettllooccaallee() to
return the current locale. By default, C programs start in the "C" lo-
cale. The only function in the library that sets the locale is
sseettllooccaallee(); the locale is never changed as a side effect of some other
routine.
The llooccaalleeccoonnvv() function returns a pointer to a structure which provides
parameters for formatting numbers, especially currency values:
struct lconv {
char *decimal_point;
char *thousands_sep;
char *grouping;
char *int_curr_symbol;
char *currency_symbol;
char *mon_decimal_point;
char *mon_thousands_sep;
char *mon_grouping;
char *positive_sign;
char *negative_sign;
char int_frac_digits;
char frac_digits;
char p_cs_precedes;
char p_sep_by_space;
char n_cs_precedes;
char n_sep_by_space;
char p_sign_posn;
char n_sign_posn;
};
The individual fields have the following meanings:
_d_e_c_i_m_a_l___p_o_i_n_t The decimal point character, except for currency val-
ues.
_t_h_o_u_s_a_n_d_s___s_e_p The separator between groups of digits before the dec-
imal point, except for currency values.
_g_r_o_u_p_i_n_g The sizes of the groups of digits, except for currency
values. This is a pointer to a vector of integers,
each of size _c_h_a_r, representing group size from low
order digit groups to high order (right to left). The
list may be terminated with 0 or CHAR_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 with CHAR_MAX, no more grouping is
performed.
_i_n_t___c_u_r_r___s_y_m_b_o_l The standardized international currency symbol.
_c_u_r_r_e_n_c_y___s_y_m_b_o_l The local currency symbol.
_m_o_n___d_e_c_i_m_a_l___p_o_i_n_t The decimal point character for currency values.
_m_o_n___t_h_o_u_s_a_n_d_s___s_e_p The separator for digit groups in currency values.
_m_o_n___g_r_o_u_p_i_n_g Like _g_r_o_u_p_i_n_g but for currency values.
_p_o_s_i_t_i_v_e___s_i_g_n The character used to denote nonnegative currency val-
ues, usually the empty string.
_n_e_g_a_t_i_v_e___s_i_g_n The character used to denote negative currency values,
usually a minus sign.
_i_n_t___f_r_a_c___d_i_g_i_t_s The number of digits after the decimal point in an in-
ternational-style currency value.
_f_r_a_c___d_i_g_i_t_s The number of digits after the decimal point in the
local style for currency values.
_p___c_s___p_r_e_c_e_d_e_s 1 if the currency symbol precedes the currency value
for nonnegative values, 0 if it follows.
_p___s_e_p___b_y___s_p_a_c_e 1 if a space is inserted between the currency symbol
and the currency value for nonnegative values, 0 oth-
erwise.
_n___c_s___p_r_e_c_e_d_e_s Like _p___c_s___p_r_e_c_e_d_e_s but for negative values.
_n___s_e_p___b_y___s_p_a_c_e Like _p___s_e_p___b_y___s_p_a_c_e but for negative values.
_p___s_i_g_n___p_o_s_n The location of the _p_o_s_i_t_i_v_e___s_i_g_n with respect to a
nonnegative quantity and the _c_u_r_r_e_n_c_y___s_y_m_b_o_l, coded as
follows:
0 Parentheses around the entire string.
1 Before the string.
2 After the string.
3 Just before _c_u_r_r_e_n_c_y___s_y_m_b_o_l.
4 Just after _c_u_r_r_e_n_c_y___s_y_m_b_o_l.
_n___s_i_g_n___p_o_s_n Like _p___s_i_g_n___p_o_s_n but for negative currency values.
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.
RREETTUURRNN VVAALLUUEESS
The sseettllooccaallee() function returns NULL and fails to change the locale if
the given combination of _c_a_t_e_g_o_r_y and _l_o_c_a_l_e makes no sense. The
llooccaalleeccoonnvv() function returns a pointer to a static object which may be
altered by later calls to sseettllooccaallee() or llooccaalleeccoonnvv().
FFIILLEESS
$PATH_LOCALE/_l_o_c_a_l_e/_c_a_t_e_g_o_r_y
/usr/share/locale/_l_o_c_a_l_e/_c_a_t_e_g_o_r_y locale file for the locale _l_o_c_a_l_e and
the category _c_a_t_e_g_o_r_y.
SSEEEE AALLSSOO
euc(4), mbrune(3), multibyte(3), rune(3), strcoll(3), strxfrm(3),
utf2(4)
SSTTAANNDDAARRDDSS
The sseettllooccaallee() and llooccaalleeccoonnvv() functions conform to ANSI C X3.159-1989
(``ANSI C '').
HHIISSTTOORRYY
The sseettllooccaallee() and llooccaalleeccoonnvv() functions first appeared in 4.4BSD.
BBUUGGSS
The current implementation supports only the "C" and "POSIX" locales for
all but the LC_CTYPE locale.
In spite of the gnarly currency support in llooccaalleeccoonnvv(), the standards
don't include any functions for generalized currency formatting.
LC_COLLATE does not make sense for many languages. Use of LC_MONETARY
could lead to misleading results until we have a real time currency con-
version function. LC_NUMERIC and LC_TIME are personal choices and should
not be wrapped up with the other categories.
4.4BSD June 9, 1993 3