[unix-history] / usr / share / man / cat3 / setlocale.0

SETLOCALE(3)                BSD Programmer's Manual               SETLOCALE(3)

N\bNA\bAM\bME\bE
     s\bse\bet\btl\blo\boc\bca\bal\ble\be, l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv - natural language formatting for C

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<l\blo\boc\bca\bal\ble\be.\b.h\bh>\b>

     _\bc_\bh_\ba_\br _\b*
     s\bse\bet\btl\blo\boc\bca\bal\ble\be(_\bi_\bn_\bt _\bc_\ba_\bt_\be_\bg_\bo_\br_\by, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bo_\bc_\ba_\bl_\be);

     _\bs_\bt_\br_\bu_\bc_\bt _\bl_\bc_\bo_\bn_\bv _\b*
     l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(_\bv_\bo_\bi_\bd);

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     The s\bse\bet\btl\blo\boc\bca\bal\ble\be() 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 l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() routine returns the current locale's parameters
     for formatting numbers.

     The s\bse\bet\btl\blo\boc\bca\bal\ble\be() 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 s\bst\btr\brc\bco\bol\bll\bl() and s\bst\btr\brx\bxf\bfr\brm\bm().

     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 s\bse\bet\btr\bru\bun\bne\bel\blo\boc\bca\bal\ble\be() function.

     LC_MONETARY  Set a locale for formatting monetary values; this affects
                  the l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() 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 p\bpr\bri\bin\bnt\btf\bf() and s\bsc\bca\ban\bnf\bf(), as
                  well as values returned by l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv().

     LC_TIME      Set a locale for formatting dates and times using the
                  s\bst\btr\brf\bft\bti\bim\bme\be() 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 _\bl_\bo_\bc_\ba_\bl_\be argument of NULL causes s\bse\bet\btl\blo\boc\bca\bal\ble\be() 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
     s\bse\bet\btl\blo\boc\bca\bal\ble\be(); the locale is never changed as a side effect of some other
     routine.

     The l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() 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:

     _\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt      The decimal point character, except for currency val-
                        ues.

     _\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp      The separator between groups of digits before the dec-
                        imal point, except for currency values.

     _\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg           The sizes of the groups of digits, except for currency
                        values.  This is a pointer to a vector of integers,
                        each of size _\bc_\bh_\ba_\br, 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.

     _\bi_\bn_\bt_\b__\bc_\bu_\br_\br_\b__\bs_\by_\bm_\bb_\bo_\bl    The standardized international currency symbol.

     _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl    The local currency symbol.

     _\bm_\bo_\bn_\b__\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt  The decimal point character for currency values.

     _\bm_\bo_\bn_\b__\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp  The separator for digit groups in currency values.

     _\bm_\bo_\bn_\b__\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg       Like _\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg but for currency values.

     _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn      The character used to denote nonnegative currency val-
                        ues, usually the empty string.

     _\bn_\be_\bg_\ba_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn      The character used to denote negative currency values,
                        usually a minus sign.

     _\bi_\bn_\bt_\b__\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs    The number of digits after the decimal point in an in-
                        ternational-style currency value.

     _\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs        The number of digits after the decimal point in the
                        local style for currency values.

     _\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs      1 if the currency symbol precedes the currency value
                        for nonnegative values, 0 if it follows.

     _\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be     1 if a space is inserted between the currency symbol
                        and the currency value for nonnegative values, 0 oth-
                        erwise.

     _\bn_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs      Like _\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs but for negative values.

     _\bn_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be     Like _\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be but for negative values.

     _\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn        The location of the _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn with respect to a
                        nonnegative quantity and the _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl, coded as

                        follows:
                        0    Parentheses around the entire string.
                        1    Before the string.
                        2    After the string.
                        3    Just before _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl.
                        4    Just after _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl.

     _\bn_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn        Like _\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn 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.

R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
     The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function returns NULL and fails to change the locale if
     the given combination of _\bc_\ba_\bt_\be_\bg_\bo_\br_\by and _\bl_\bo_\bc_\ba_\bl_\be makes no sense.  The
     l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function returns a pointer to a static object which may be
     altered by later calls to s\bse\bet\btl\blo\boc\bca\bal\ble\be() or l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv().

F\bFI\bIL\bLE\bES\bS
     $PATH_LOCALE/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by
     /usr/share/locale/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by  locale file for the locale _\bl_\bo_\bc_\ba_\bl_\be and
                                        the category _\bc_\ba_\bt_\be_\bg_\bo_\br_\by.

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
     euc(4),  mbrune(3),  multibyte(3),  rune(3),  strcoll(3),  strxfrm(3),
     utf2(4)

S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS
     The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions conform to ANSI C X3.159-1989
     (``ANSI C '').

H\bHI\bIS\bST\bTO\bOR\bRY\bY
     The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions first appeared in 4.4BSD.

B\bBU\bUG\bGS\bS
     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 l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(), 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
Commit	Line	Data
8bb980a3 C	1	SETLOCALE(3) BSD Programmer's Manual SETLOCALE(3)
	2
	3	N\bNA\bAM\bME\bE
	4	s\bse\bet\btl\blo\boc\bca\bal\ble\be, l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv - natural language formatting for C
	5
	6	S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
	7	#\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<l\blo\boc\bca\bal\ble\be.\b.h\bh>\b>
	8
	9	_\bc_\bh_\ba_\br _\b*
	10	s\bse\bet\btl\blo\boc\bca\bal\ble\be(_\bi_\bn_\bt _\bc_\ba_\bt_\be_\bg_\bo_\br_\by, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bo_\bc_\ba_\bl_\be);
	11
	12	_\bs_\bt_\br_\bu_\bc_\bt _\bl_\bc_\bo_\bn_\bv _\b*
	13	l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(_\bv_\bo_\bi_\bd);
	14
	15	D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
	16	The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function sets the C library's notion of natural language
	17	formatting style for particular sets of routines. Each such style is
	18	called a `locale' and is invoked using an appropriate name passed as a C
	19	string. The l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() routine returns the current locale's parameters
	20	for formatting numbers.
	21
	22	The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function recognizes several categories of routines.
	23	These are the categories and the sets of routines they select:
	24
	25	LC_ALL Set the entire locale generically.
	26
	27	LC_COLLATE Set a locale for string collation routines. This controls
	28	alphabetic ordering in s\bst\btr\brc\bco\bol\bll\bl() and s\bst\btr\brx\bxf\bfr\brm\bm().
	29
	30	LC_CTYPE Set a locale for the ctype(3), mbrune(3), multibyte(3) and
	31	rune(3) functions. This controls recognition of upper and
	32	lower case, alphabetic or non-alphabetic characters, and so
	33	on. The real work is done by the s\bse\bet\btr\bru\bun\bne\bel\blo\boc\bca\bal\ble\be() function.
	34
	35	LC_MONETARY Set a locale for formatting monetary values; this affects
	36	the l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function.
	37
	38	LC_NUMERIC Set a locale for formatting numbers. This controls the for-
	39	matting of decimal points in input and output of floating
	40	point numbers in functions such as p\bpr\bri\bin\bnt\btf\bf() and s\bsc\bca\ban\bnf\bf(), as
	41	well as values returned by l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv().
	42
	43	LC_TIME Set a locale for formatting dates and times using the
	44	s\bst\btr\brf\bft\bti\bim\bme\be() function.
	45
	46	Only three locales are defined by default, the empty string "" which de-
	47	notes the native environment, and the "C" and locales, which denote the C
	48	language environment. A _\bl_\bo_\bc_\ba_\bl_\be argument of NULL causes s\bse\bet\btl\blo\boc\bca\bal\ble\be() to
	49	return the current locale. By default, C programs start in the "C" lo-
	50	cale. The only function in the library that sets the locale is
	51	s\bse\bet\btl\blo\boc\bca\bal\ble\be(); the locale is never changed as a side effect of some other
	52	routine.
	53
	54	The l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function returns a pointer to a structure which provides
	55	parameters for formatting numbers, especially currency values:
	56
	57	struct lconv {
	58	char *decimal_point;
	59	char *thousands_sep;
	60	char *grouping;
	61	char *int_curr_symbol;
	62	char *currency_symbol;
	63	char *mon_decimal_point;
	64	char *mon_thousands_sep;
65	char *mon_grouping;
66	char *positive_sign;
67	char *negative_sign;
68	char int_frac_digits;
69	char frac_digits;
70	char p_cs_precedes;
71	char p_sep_by_space;
72	char n_cs_precedes;
73	char n_sep_by_space;
74	char p_sign_posn;
75	char n_sign_posn;
76	};
77
78	The individual fields have the following meanings:
79
80	_\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt The decimal point character, except for currency val-
81	ues.
82
83	_\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp The separator between groups of digits before the dec-
84	imal point, except for currency values.
85
86	_\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg The sizes of the groups of digits, except for currency
87	values. This is a pointer to a vector of integers,
88	each of size _\bc_\bh_\ba_\br, representing group size from low
89	order digit groups to high order (right to left). The
90	list may be terminated with 0 or CHAR_MAX. If the list
91	is terminated with 0, the last group size before the 0
92	is repeated to account for all the digits. If the
93	list is terminated with CHAR_MAX, no more grouping is
94	performed.
95
96	_\bi_\bn_\bt_\b__\bc_\bu_\br_\br_\b__\bs_\by_\bm_\bb_\bo_\bl The standardized international currency symbol.
97
98	_\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl The local currency symbol.
99
100	_\bm_\bo_\bn_\b__\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt The decimal point character for currency values.
101
102	_\bm_\bo_\bn_\b__\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp The separator for digit groups in currency values.
103
104	_\bm_\bo_\bn_\b__\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg Like _\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg but for currency values.
105
106	_\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn The character used to denote nonnegative currency val-
107	ues, usually the empty string.
108
109	_\bn_\be_\bg_\ba_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn The character used to denote negative currency values,
110	usually a minus sign.
111
112	_\bi_\bn_\bt_\b__\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs The number of digits after the decimal point in an in-
113	ternational-style currency value.
114
115	_\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs The number of digits after the decimal point in the
116	local style for currency values.
117
118	_\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs 1 if the currency symbol precedes the currency value
119	for nonnegative values, 0 if it follows.
120
121	_\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be 1 if a space is inserted between the currency symbol
122	and the currency value for nonnegative values, 0 oth-
123	erwise.
124
125	_\bn_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs Like _\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs but for negative values.
126
127	_\bn_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be Like _\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be but for negative values.
128
129	_\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn The location of the _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn with respect to a
130	nonnegative quantity and the _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl, coded as
131
132	follows:
133	0 Parentheses around the entire string.
134	1 Before the string.
135	2 After the string.
136	3 Just before _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl.
137	4 Just after _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl.
138
139	_\bn_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn Like _\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn but for negative currency values.
140
141	Unless mentioned above, an empty string as a value for a field indicates
142	a zero length result or a value that is not in the current locale. A
143	CHAR_MAX result similarly denotes an unavailable value.
144
145	R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
146	The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function returns NULL and fails to change the locale if
147	the given combination of _\bc_\ba_\bt_\be_\bg_\bo_\br_\by and _\bl_\bo_\bc_\ba_\bl_\be makes no sense. The
148	l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function returns a pointer to a static object which may be
149	altered by later calls to s\bse\bet\btl\blo\boc\bca\bal\ble\be() or l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv().
150
151	F\bFI\bIL\bLE\bES\bS
152	$PATH_LOCALE/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by
153	/usr/share/locale/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by locale file for the locale _\bl_\bo_\bc_\ba_\bl_\be and
154	the category _\bc_\ba_\bt_\be_\bg_\bo_\br_\by.
155
156	S\bSE\bEE\bE A\bAL\bLS\bSO\bO
157	euc(4), mbrune(3), multibyte(3), rune(3), strcoll(3), strxfrm(3),
158	utf2(4)
159
160	S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS
161	The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions conform to ANSI C X3.159-1989
162	(``ANSI C '').
163
164	H\bHI\bIS\bST\bTO\bOR\bRY\bY
165	The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions first appeared in 4.4BSD.
166
167	B\bBU\bUG\bGS\bS
168	The current implementation supports only the "C" and "POSIX" locales for
169	all but the LC_CTYPE locale.
170
171	In spite of the gnarly currency support in l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(), the standards
172	don't include any functions for generalized currency formatting.
173
174	LC_COLLATE does not make sense for many languages. Use of LC_MONETARY
175	could lead to misleading results until we have a real time currency con-
176	version function. LC_NUMERIC and LC_TIME are personal choices and should
177	not be wrapped up with the other categories.
178
179	4.4BSD June 9, 1993 3