| blob | ddb99c175141b877f3fec70e04226a9de2ec232c |
1 .\" $NetBSD: setlocale.3,v 1.20 2003/09/08 17:54:31 wiz Exp $
2 .\"
3 .\" Copyright (c) 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Donn Seeley at BSDI.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
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.
20 .\"
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
31 .\" SUCH DAMAGE.
32 .\"
33 .\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
34 .\"
35 .Dd May 30, 2003
36 .Dt SETLOCALE 3
37 .Os
38 .Sh NAME
39 .Nm setlocale ,
40 .Nm localeconv
41 .Nd natural language formatting for C
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In locale.h
46 .Ft char *
47 .Fn setlocale "int category" "const char *locale"
48 .Ft struct lconv *
49 .Fn localeconv "void"
50 .Sh DESCRIPTION
51 The
52 .Fn setlocale
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
57 .Sq locale
58 and is invoked using an appropriate name passed as a C string.
59 The
60 .Fn localeconv
61 routine returns the current locale's parameters
62 for formatting numbers.
63 .Pp
64 The
65 .Fn setlocale
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
69 .It Dv LC_ALL
70 Set the entire locale generically.
71 .It Dv LC_COLLATE
72 Set a locale for string collation routines.
73 This controls alphabetic ordering in
74 .Fn strcoll
75 and
76 .Fn strxfrm .
77 .It Dv LC_CTYPE
78 Set a locale for the
79 .Xr ctype 3
80 functions.
81 This controls recognition of upper and lower case,
82 alphabetic or non-alphabetic characters,
83 and so on.
84 The real work is done by the
85 .Fn setrunelocale
86 function.
87 .It Dv LC_MESSAGES
88 Set a locale for message catalogs.
89 This controls the selection of message catalogs by the
90 .Xr catgets 3
91 and
92 .Xr gettext 3
93 families of functions.
94 .It Dv LC_MONETARY
95 Set a locale for formatting monetary values;
96 this affects the
97 .Fn localeconv
98 function.
99 .It Dv LC_NUMERIC
100 Set a locale for formatting numbers.
101 This controls the formatting of decimal points
102 in input and output of floating point numbers
103 in functions such as
104 .Fn printf
105 and
106 .Fn scanf ,
107 as well as values returned by
108 .Fn localeconv .
109 .It Dv LC_TIME
110 Set a locale for formatting dates and times using the
111 .Fn strftime
112 function.
113 .El
114 .Pp
115 Only three locales are defined by default,
116 the empty string
117 .Li "\&""\|""
118 which denotes the native environment, and the
119 .Li "\&""C""
120 and
121 .Li "\&""POSIX""
122 locales, which denote the C language environment.
123 A
124 .Fa locale
125 argument of
126 .Dv NULL
127 causes
128 .Fn setlocale
129 to return the current locale.
130 By default, C programs start in the
131 .Li "\&""C""
132 locale.
133 The format of the locale string is described in
134 .Xr nls 7 .
135 .Pp
136 The only function in the library that sets the locale is
137 .Fn setlocale ;
138 the locale is never changed as a side effect of some other routine.
139 .Pp
140 Changing the setting of
141 .Dv LC_MESSAGES
142 has no effect on catalogs that have already been opened by
143 .Xr catopen 3 .
144 .Pp
145 The
146 .Fn localeconv
147 function returns a pointer to a structure
148 which provides parameters for formatting numbers,
149 especially currency values:
150 .Bd -literal -offset indent
151 struct lconv {
152 char *decimal_point;
153 char *thousands_sep;
154 char *grouping;
155 char *int_curr_symbol;
156 char *currency_symbol;
157 char *mon_decimal_point;
158 char *mon_thousands_sep;
159 char *mon_grouping;
160 char *positive_sign;
161 char *negative_sign;
162 char int_frac_digits;
163 char frac_digits;
164 char p_cs_precedes;
165 char p_sep_by_space;
166 char n_cs_precedes;
167 char n_sep_by_space;
168 char p_sign_posn;
169 char n_sign_posn;
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;
176 };
177 .Ed
178 .Pp
179 The individual fields have the following meanings:
180 .Bl -tag -width int_p_sep_by_space
181 .It Fa decimal_point
182 The decimal point character, except for monetary values.
183 .It Fa thousands_sep
184 The separator between groups of digits
185 before the decimal point, except for monetary values.
186 .It Fa grouping
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
189 .Va char ,
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
193 .Dv CHAR_MAX .
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
197 .Dv CHAR_MAX ,
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.
207 .It Fa mon_grouping
208 Like
209 .Fa grouping
210 but for monetary values.
211 .It Fa positive_sign
212 The character used to denote nonnegative monetary values,
213 usually the empty string.
214 .It Fa negative_sign
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.
220 .It Fa frac_digits
221 The number of digits after the decimal point
222 in an locally formatted monetary value.
223 .It Fa p_cs_precedes
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.
229 .It Fa n_cs_precedes
230 Like
231 .Fa p_cs_precedes
232 but for negative values.
233 .It Fa n_sep_by_space
234 Like
235 .Fa p_sep_by_space
236 but for negative values.
237 .It Fa p_sign_posn
238 The location of the
239 .Fa positive_sign
240 with respect to a nonnegative quantity and the
241 .Fa currency_symbol .
242 .It Fa n_sign_posn
243 Like
244 .Fa p_sign_posn
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
250 Like
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
258 Like
259 .Fa int_p_sep_by_space
260 but for negative values.
261 .It Fa int_p_sign_posn
262 The location of the
263 .Fa positive_sign
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
268 Like
269 .Fa int_p_sign_posn
270 but for negative values.
271 .El
272 .Pp
273 The positional parameters in
274 .Fa p_sign_posn ,
275 .Fa n_sign_posn ,
276 .Fa int_p_sign_posn
277 and
278 .Fa int_n_sign_posn
279 are encoded as follows:
280 .Bl -tag -width 3n -compact
281 .It Li 0
282 Parentheses around the entire string.
283 .It Li 1
284 Before the string.
285 .It Li 2
286 After the string.
287 .It Li 3
288 Just before
289 .Fa currency_symbol .
290 .It Li 4
291 Just after
292 .Fa currency_symbol .
293 .El
294 .Pp
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.
299 A
300 .Dv CHAR_MAX
301 result similarly denotes an unavailable value.
302 .Sh RETURN VALUES
303 The
304 .Fn setlocale
305 function returns
306 .Dv NULL
307 and fails to change the locale
308 if the given combination of
309 .Fa category
310 and
311 .Fa locale
312 makes no sense.
313 The
314 .Fn localeconv
315 function returns a pointer to a static object
316 which may be altered by later calls to
317 .Fn setlocale
318 or
319 .Fn localeconv .
320 .Sh EXAMPLES
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
325 language:
326 .Bd -literal
327 setlocale(LC_ALL, "de");
328 setlocale(LC_COLLATE, "fr");
329 .Ed
330 .Pp
331 When a process is started, its current locale is set to the C or POSIX
332 locale.
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:
336 .Bd -literal
337 setlocale(LC_ALL, "");
338 .Ed
339 .\" .Sh FILES XXX
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
345 .\" .El
346 .Sh SEE ALSO
347 .Xr catopen 3 ,
348 .Xr gettext 3 ,
349 .Xr nl_langinfo 3 ,
350 .Xr nls 7
351 .\" .Xr strcoll 3 , XXX
352 .\" .Xr strxfrm 3 XXX
353 .Sh STANDARDS
354 The
355 .Fn setlocale
356 and
357 .Fn localeconv
358 functions conform to
359 .St -ansiC
360 and
361 .St -isoC-90 .
362 .Pp
363 The
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 ,
368 .Fa int_p_sign_posn
369 and
370 .Fa int_n_sign_posn
371 members of
372 .Ft struct lconv
373 were introduced in
374 .St -isoC-99 .
375 .Sh HISTORY
376 The
377 .Fn setlocale
378 and
379 .Fn localeconv
380 functions first appeared in
381 .Bx 4.4 .
382 .Sh BUGS
383 The current implementation supports only the
384 .Li "\&""C""
385 and
386 .Li "\&""POSIX""
387 locales for all but the
388 .Dv LC_CTYPE
389 locale.
390 .Pp
391 In spite of the gnarly currency support in
392 .Fn localeconv ,
393 the standards don't include any functions
394 for generalized currency formatting.
395 .Pp
396 .Dv LC_COLLATE
397 does not make sense for many languages.
398 Use of
399 .Dv LC_MONETARY
400 could lead to misleading results until we have a real time currency
401 conversion function.
402 .Dv LC_NUMERIC
403 and
404 .Dv LC_TIME
405 are personal choices and should not be wrapped up with the other categories.
406 .Pp
407 Multibyte locales aren't supported for static binaries.