1 .\" $NetBSD: src/lib/libc/locale/setlocale.3,v 1.21 2004/01/24 16:58:54 wiz Exp $
2 .\" $DragonFly: src/lib/libc/locale/setlocale.3,v 1.5 2008/10/06 21:21:30 swildner Exp $
5 .\" The Regents of the University of California. All rights reserved.
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Donn Seeley at BSDI.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
42 .Nd natural language formatting for C
48 .Fn setlocale "int category" "const char *locale"
54 function sets the C library's notion
55 of natural language formatting style
56 for particular sets of routines.
57 Each such style is called a
59 and is invoked using an appropriate name passed as a C string.
62 routine returns the current locale's parameters
63 for formatting numbers.
67 function recognizes several categories of routines.
68 These are the categories and the sets of routines they select:
69 .Bl -tag -width LC_MONETARY
71 Set the entire locale generically.
73 Set a locale for string collation routines.
74 This controls alphabetic ordering in
82 This controls recognition of upper and lower case,
83 alphabetic or non-alphabetic characters,
85 The real work is done by the
86 .Fn _xpg4_setrunelocale
89 Set a locale for message catalogs.
90 This controls the selection of message catalogs by the
94 families of functions.
96 Set a locale for formatting monetary values;
101 Set a locale for formatting numbers.
102 This controls the formatting of decimal points
103 in input and output of floating point numbers
108 as well as values returned by
111 Set a locale for formatting dates and times using the
116 Only three locales are defined by default,
119 which denotes the native environment, and the
123 locales, which denote the C language environment.
130 to return the current locale.
131 By default, C programs start in the
134 The format of the locale string is described in
137 The only function in the library that sets the locale is
139 the locale is never changed as a side effect of some other routine.
141 Changing the setting of
143 has no effect on catalogs that have already been opened by
148 function returns a pointer to a structure
149 which provides parameters for formatting numbers,
150 especially currency values:
151 .Bd -literal -offset indent
156 char *int_curr_symbol;
157 char *currency_symbol;
158 char *mon_decimal_point;
159 char *mon_thousands_sep;
163 char int_frac_digits;
171 char int_p_cs_precedes;
172 char int_n_cs_precedes;
173 char int_p_sep_by_space;
174 char int_n_sep_by_space;
175 char int_p_sign_posn;
176 char int_n_sign_posn;
180 The individual fields have the following meanings:
181 .Bl -tag -width int_p_sep_by_space
183 The decimal point character, except for monetary values.
185 The separator between groups of digits
186 before the decimal point, except for monetary values.
188 The sizes of the groups of digits, except for monetary values.
189 This is a pointer to a vector of integers, each of size
191 representing group size from low order digit groups
192 to high order (right to left).
193 The list may be terminated with 0 or
195 If the list is terminated with 0,
196 the last group size before the 0 is repeated to account for all the digits.
197 If the list is terminated with
199 no more grouping is performed.
200 .It Fa int_curr_symbol
201 The standardized (ISO 4217:1995) international currency symbol.
202 .It Fa currency_symbol
203 The local currency symbol.
204 .It Fa mon_decimal_point
205 The decimal point character for monetary values.
206 .It Fa mon_thousands_sep
207 The separator for digit groups in monetary values.
211 but for monetary values.
213 The character used to denote nonnegative monetary values,
214 usually the empty string.
216 The character used to denote negative monetary values,
217 usually a minus sign.
218 .It Fa int_frac_digits
219 The number of digits after the decimal point
220 in an internationally formatted monetary value.
222 The number of digits after the decimal point
223 in an locally formatted monetary value.
225 1 if the currency symbol precedes the monetary value
226 for nonnegative values, 0 if it follows.
227 .It Fa p_sep_by_space
228 1 if a space is inserted between the currency symbol
229 and the monetary value for nonnegative values, 0 otherwise.
233 but for negative values.
234 .It Fa n_sep_by_space
237 but for negative values.
241 with respect to a nonnegative quantity and the
242 .Fa currency_symbol .
246 but for negative currency values.
247 .It Fa int_p_cs_precedes
248 1 if the currency symbol precedes the internationally
249 formatted monetary value for nonnegative values, 0 if it follows.
250 .It Fa int_n_cs_precedes
252 .Fa int_p_cs_precedes
253 but for negative values.
254 .It Fa int_p_sep_by_space
255 1 if a space is inserted between the currency symbol
256 and the internationally formatted monetary value for
257 nonnegative values, 0 otherwise.
258 .It Fa int_n_sep_by_space
260 .Fa int_p_sep_by_space
261 but for negative values.
262 .It Fa int_p_sign_posn
265 with respect to a nonnegative quantity and the
266 .Fa currency_symbol ,
267 for internationally formatted nonnegative monetary values.
268 .It Fa int_n_sign_posn
271 but for negative values.
274 The positional parameters in
280 are encoded as follows:
281 .Bl -tag -width 3n -compact
283 Parentheses around the entire string.
290 .Fa currency_symbol .
293 .Fa currency_symbol .
296 Unless mentioned above,
297 an empty string as a value for a field
298 indicates a zero length result or
299 a value that is not in the current locale.
302 result similarly denotes an unavailable value.
308 and fails to change the locale
309 if the given combination of
316 function returns a pointer to a static object
317 which may be altered by later calls to
322 The following code illustrates how a program can initialize the
323 international environment for one language, while selectively
324 modifying the program's locale such that regular expressions and
325 string operations can be applied to text recorded in a different
328 setlocale(LC_ALL, "de");
329 setlocale(LC_COLLATE, "fr");
332 When a process is started, its current locale is set to the C or POSIX
334 An internationalized program that depends on locale data not defined in
335 the C or POSIX locale must invoke the setlocale subroutine in the
336 following manner before using any of the locale-specific information:
338 setlocale(LC_ALL, "");
341 .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
342 .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX
343 .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX
344 .\" locale file for the locale \fIlocale\fP XXX
345 .\" and the category \fIcategory\fP. XXX
349 .Xr gettext 3 Pq Pa pkgsrc/devel/gettext ,
353 .\" .Xr strcoll 3 , XXX
354 .\" .Xr strxfrm 3 XXX
366 .Fa int_p_cs_precedes ,
367 .Fa int_n_cs_precedes ,
368 .Fa int_p_sep_by_space ,
369 .Fa int_n_sep_by_space ,
382 functions first appeared in
385 The current implementation supports only the
389 locales for all but the
393 In spite of the gnarly currency support in
395 the standards don't include any functions
396 for generalized currency formatting.
399 does not make sense for many languages.
402 could lead to misleading results until we have a real time currency
407 are personal choices and should not be wrapped up with the other categories.
409 Multibyte locales aren't supported for static binaries.