1 .\" $NetBSD: setlocale.3,v 1.21 2004/01/24 16:58:54 wiz Exp $
4 .\" The Regents of the University of California. All rights reserved.
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Donn Seeley at BSDI.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
41 .Nd natural language formatting for C
47 .Fn setlocale "int category" "const char *locale"
53 function sets the C library's notion
54 of natural language formatting style
55 for particular sets of routines.
56 Each such style is called a
58 and is invoked using an appropriate name passed as a C string.
61 routine returns the current locale's parameters
62 for formatting numbers.
66 function recognizes several categories of routines.
67 These are the categories and the sets of routines they select:
68 .Bl -tag -width LC_MONETARY
70 Set the entire locale generically.
72 Set a locale for string collation routines.
73 This controls alphabetic ordering in
81 This controls recognition of upper and lower case,
82 alphabetic or non-alphabetic characters,
84 The real work is done by the
88 Set a locale for message catalogs.
89 This controls the selection of message catalogs by the
93 families of functions.
95 Set a locale for formatting monetary values;
100 Set a locale for formatting numbers.
101 This controls the formatting of decimal points
102 in input and output of floating point numbers
107 as well as values returned by
110 Set a locale for formatting dates and times using the
115 Only three locales are defined by default,
118 which denotes the native environment, and the
122 locales, which denote the C language environment.
129 to return the current locale.
130 By default, C programs start in the
133 The format of the locale string is described in
136 The only function in the library that sets the locale is
138 the locale is never changed as a side effect of some other routine.
140 Changing the setting of
142 has no effect on catalogs that have already been opened by
147 function returns a pointer to a structure
148 which provides parameters for formatting numbers,
149 especially currency values:
150 .Bd -literal -offset indent
155 char *int_curr_symbol;
156 char *currency_symbol;
157 char *mon_decimal_point;
158 char *mon_thousands_sep;
162 char int_frac_digits;
170 char int_p_cs_precedes;
171 char int_n_cs_precedes;
172 char int_p_sep_by_space;
173 char int_n_sep_by_space;
174 char int_p_sign_posn;
175 char int_n_sign_posn;
179 The individual fields have the following meanings:
180 .Bl -tag -width int_p_sep_by_space
182 The decimal point character, except for monetary values.
184 The separator between groups of digits
185 before the decimal point, except for monetary values.
187 The sizes of the groups of digits, except for monetary values.
188 This is a pointer to a vector of integers, each of size
190 representing group size from low order digit groups
191 to high order (right to left).
192 The list may be terminated with 0 or
194 If the list is terminated with 0,
195 the last group size before the 0 is repeated to account for all the digits.
196 If the list is terminated with
198 no more grouping is performed.
199 .It Fa int_curr_symbol
200 The standardized (ISO 4217:1995) international currency symbol.
201 .It Fa currency_symbol
202 The local currency symbol.
203 .It Fa mon_decimal_point
204 The decimal point character for monetary values.
205 .It Fa mon_thousands_sep
206 The separator for digit groups in monetary values.
210 but for monetary values.
212 The character used to denote nonnegative monetary values,
213 usually the empty string.
215 The character used to denote negative monetary values,
216 usually a minus sign.
217 .It Fa int_frac_digits
218 The number of digits after the decimal point
219 in an internationally formatted monetary value.
221 The number of digits after the decimal point
222 in an locally formatted monetary value.
224 1 if the currency symbol precedes the monetary value
225 for nonnegative values, 0 if it follows.
226 .It Fa p_sep_by_space
227 1 if a space is inserted between the currency symbol
228 and the monetary value for nonnegative values, 0 otherwise.
232 but for negative values.
233 .It Fa n_sep_by_space
236 but for negative values.
240 with respect to a nonnegative quantity and the
241 .Fa currency_symbol .
245 but for negative currency values.
246 .It Fa int_p_cs_precedes
247 1 if the currency symbol precedes the internationally
248 formatted monetary value for nonnegative values, 0 if it follows.
249 .It Fa int_n_cs_precedes
251 .Fa int_p_cs_precedes
252 but for negative values.
253 .It Fa int_p_sep_by_space
254 1 if a space is inserted between the currency symbol
255 and the internationally formatted monetary value for
256 nonnegative values, 0 otherwise.
257 .It Fa int_n_sep_by_space
259 .Fa int_p_sep_by_space
260 but for negative values.
261 .It Fa int_p_sign_posn
264 with respect to a nonnegative quantity and the
265 .Fa currency_symbol ,
266 for internationally formatted nonnegative monetary values.
267 .It Fa int_n_sign_posn
270 but for negative values.
273 The positional parameters in
279 are encoded as follows:
280 .Bl -tag -width 3n -compact
282 Parentheses around the entire string.
289 .Fa currency_symbol .
292 .Fa currency_symbol .
295 Unless mentioned above,
296 an empty string as a value for a field
297 indicates a zero length result or
298 a value that is not in the current locale.
301 result similarly denotes an unavailable value.
307 and fails to change the locale
308 if the given combination of
315 function returns a pointer to a static object
316 which may be altered by later calls to
321 The following code illustrates how a program can initialize the
322 international environment for one language, while selectively
323 modifying the program's locale such that regular expressions and
324 string operations can be applied to text recorded in a different
327 setlocale(LC_ALL, "de");
328 setlocale(LC_COLLATE, "fr");
331 When a process is started, its current locale is set to the C or POSIX
333 An internationalized program that depends on locale data not defined in
334 the C or POSIX locale must invoke the setlocale subroutine in the
335 following manner before using any of the locale-specific information:
337 setlocale(LC_ALL, "");
340 .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
341 .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX
342 .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX
343 .\" locale file for the locale \fIlocale\fP XXX
344 .\" and the category \fIcategory\fP. XXX
351 .\" .Xr strcoll 3 , XXX
352 .\" .Xr strxfrm 3 XXX
364 .Fa int_p_cs_precedes ,
365 .Fa int_n_cs_precedes ,
366 .Fa int_p_sep_by_space ,
367 .Fa int_n_sep_by_space ,
380 functions first appeared in
383 The current implementation supports only the
387 locales for all but the
391 In spite of the gnarly currency support in
393 the standards don't include any functions
394 for generalized currency formatting.
397 does not make sense for many languages.
400 could lead to misleading results until we have a real time currency
405 are personal choices and should not be wrapped up with the other categories.
407 Multibyte locales aren't supported for static binaries.