Annotation of src/lib/libc/locale/setlocale.3, Revision 1.15
1.15 ! gmcgarry 1: .\" $NetBSD: setlocale.3,v 1.14 2002/10/01 17:02:57 wiz Exp $
1.2 kleink 2: .\"
1.1 perry 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. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the University of
20: .\" California, Berkeley and its contributors.
21: .\" 4. Neither the name of the University nor the names of its contributors
22: .\" may be used to endorse or promote products derived from this software
23: .\" without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35: .\" SUCH DAMAGE.
36: .\"
37: .\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
38: .\"
39: .Dd June 9, 1993
40: .Dt SETLOCALE 3
1.6 garbled 41: .Os
1.1 perry 42: .Sh NAME
43: .Nm setlocale ,
44: .Nm localeconv
45: .Nd natural language formatting for C
1.4 perry 46: .Sh LIBRARY
47: .Lb libc
1.1 perry 48: .Sh SYNOPSIS
1.12 ross 49: .Fd #include \*[Lt]locale.h\*[Gt]
1.1 perry 50: .Ft char *
51: .Fn setlocale "int category" "const char *locale"
52: .Ft struct lconv *
53: .Fn localeconv "void"
54: .Sh DESCRIPTION
55: The
56: .Fn setlocale
57: function sets the C library's notion
58: of natural language formatting style
59: for particular sets of routines.
60: Each such style is called a
61: .Sq locale
62: and is invoked using an appropriate name passed as a C string.
63: The
64: .Fn localeconv
65: routine returns the current locale's parameters
66: for formatting numbers.
67: .Pp
68: The
69: .Fn setlocale
70: function recognizes several categories of routines.
71: These are the categories and the sets of routines they select:
72: .Pp
73: .Bl -tag -width LC_MONETARY
74: .It Dv LC_ALL
75: Set the entire locale generically.
76: .It Dv LC_COLLATE
77: Set a locale for string collation routines.
78: This controls alphabetic ordering in
79: .Fn strcoll
80: and
81: .Fn strxfrm .
82: .It Dv LC_CTYPE
83: Set a locale for the
1.2 kleink 84: .Xr ctype 3
1.1 perry 85: functions.
86: This controls recognition of upper and lower case,
87: alphabetic or non-alphabetic characters,
1.14 wiz 88: and so on.
89: The real work is done by the
1.1 perry 90: .Fn setrunelocale
91: function.
92: .It Dv LC_MONETARY
93: Set a locale for formatting monetary values;
94: this affects the
95: .Fn localeconv
96: function.
97: .It Dv LC_NUMERIC
98: Set a locale for formatting numbers.
99: This controls the formatting of decimal points
100: in input and output of floating point numbers
101: in functions such as
102: .Fn printf
103: and
104: .Fn scanf ,
105: as well as values returned by
106: .Fn localeconv .
107: .It Dv LC_TIME
108: Set a locale for formatting dates and times using the
109: .Fn strftime
110: function.
111: .El
112: .Pp
113: Only three locales are defined by default,
114: the empty string
115: .Li "\&""\|""
116: which denotes the native environment, and the
117: .Li "\&""C""
118: and
1.5 fair 119: .Li "\&""POSIX""
1.1 perry 120: locales, which denote the C language environment.
121: A
122: .Fa locale
123: argument of
124: .Dv NULL
125: causes
126: .Fn setlocale
127: to return the current locale.
128: By default, C programs start in the
129: .Li "\&""C""
130: locale.
1.15 ! gmcgarry 131: The format of the locale string is described in
! 132: .Xr nls 7 .
! 133: .Pp
1.1 perry 134: The only function in the library that sets the locale is
135: .Fn setlocale ;
136: the locale is never changed as a side effect of some other routine.
137: .Pp
1.15 ! gmcgarry 138: .Pp
! 139: Changing the setting of LC_MESSAGES has no effect on catalogs that
! 140: have already been opened by
! 141: .Xr catopen 3 .
! 142: .Pp
1.1 perry 143: The
144: .Fn localeconv
145: function returns a pointer to a structure
146: which provides parameters for formatting numbers,
147: especially currency values:
148: .Bd -literal -offset indent
149: struct lconv {
150: char *decimal_point;
151: char *thousands_sep;
152: char *grouping;
153: char *int_curr_symbol;
154: char *currency_symbol;
155: char *mon_decimal_point;
156: char *mon_thousands_sep;
157: char *mon_grouping;
158: char *positive_sign;
159: char *negative_sign;
160: char int_frac_digits;
161: char frac_digits;
162: char p_cs_precedes;
163: char p_sep_by_space;
164: char n_cs_precedes;
165: char n_sep_by_space;
166: char p_sign_posn;
167: char n_sign_posn;
1.8 kleink 168: char int_p_cs_precedes;
169: char int_n_cs_precedes;
170: char int_p_sep_by_space;
171: char int_n_sep_by_space;
172: char int_p_sign_posn;
173: char int_n_sign_posn;
1.1 perry 174: };
175: .Ed
176: .Pp
177: The individual fields have the following meanings:
178: .Pp
1.8 kleink 179: .Bl -tag -width int_p_sep_by_space
1.1 perry 180: .It Fa decimal_point
1.8 kleink 181: The decimal point character, except for monetary values.
1.1 perry 182: .It Fa thousands_sep
183: The separator between groups of digits
1.8 kleink 184: before the decimal point, except for monetary values.
1.1 perry 185: .It Fa grouping
1.8 kleink 186: The sizes of the groups of digits, except for monetary values.
1.1 perry 187: This is a pointer to a vector of integers, each of size
188: .Va char ,
189: representing group size from low order digit groups
190: to high order (right to left).
191: The list may be terminated with 0 or
192: .Dv CHAR_MAX .
193: If the list is terminated with 0,
194: the last group size before the 0 is repeated to account for all the digits.
195: If the list is terminated with
196: .Dv CHAR_MAX ,
197: no more grouping is performed.
198: .It Fa int_curr_symbol
1.8 kleink 199: The standardized (ISO 4217:1995) international currency symbol.
1.1 perry 200: .It Fa currency_symbol
201: The local currency symbol.
202: .It Fa mon_decimal_point
1.8 kleink 203: The decimal point character for monetary values.
1.1 perry 204: .It Fa mon_thousands_sep
1.8 kleink 205: The separator for digit groups in monetary values.
1.1 perry 206: .It Fa mon_grouping
207: Like
208: .Fa grouping
1.8 kleink 209: but for monetary values.
1.1 perry 210: .It Fa positive_sign
1.8 kleink 211: The character used to denote nonnegative monetary values,
1.1 perry 212: usually the empty string.
213: .It Fa negative_sign
1.8 kleink 214: The character used to denote negative monetary values,
1.1 perry 215: usually a minus sign.
216: .It Fa int_frac_digits
217: The number of digits after the decimal point
1.8 kleink 218: in an internationally formatted monetary value.
1.1 perry 219: .It Fa frac_digits
220: The number of digits after the decimal point
1.8 kleink 221: in an locally formatted monetary value.
1.1 perry 222: .It Fa p_cs_precedes
1.8 kleink 223: 1 if the currency symbol precedes the monetary value
1.1 perry 224: for nonnegative values, 0 if it follows.
225: .It Fa p_sep_by_space
226: 1 if a space is inserted between the currency symbol
1.8 kleink 227: and the monetary value for nonnegative values, 0 otherwise.
1.1 perry 228: .It Fa n_cs_precedes
229: Like
230: .Fa p_cs_precedes
231: but for negative values.
232: .It Fa n_sep_by_space
233: Like
234: .Fa p_sep_by_space
235: but for negative values.
236: .It Fa p_sign_posn
237: The location of the
238: .Fa positive_sign
239: with respect to a nonnegative quantity and the
1.8 kleink 240: .Fa currency_symbol .
241: .It Fa n_sign_posn
242: Like
243: .Fa p_sign_posn
244: but for negative currency values.
245: .It Fa int_p_cs_precedes
246: 1 if the currency symbol precedes the internationally
247: formatted monetary value for nonnegative values, 0 if it follows.
248: .It Fa int_n_cs_precedes
249: Like
250: .Fa int_p_cs_precedes
251: but for negative values.
252: .It Fa int_p_sep_by_space
253: 1 if a space is inserted between the currency symbol
254: and the internationally formatted monetary value for
255: nonnegative values, 0 otherwise.
256: .It Fa int_n_sep_by_space
257: Like
258: .Fa int_p_sep_by_space
259: but for negative values.
260: .It Fa int_p_sign_posn
261: The location of the
262: .Fa positive_sign
263: with respect to a nonnegative quantity and the
1.1 perry 264: .Fa currency_symbol ,
1.8 kleink 265: for internationally formatted nonnegative monetary values.
266: .It Fa int_n_sign_posn
267: Like
268: .Fa int_p_sign_posn
269: but for negative values.
270: .El
271: .Pp
272: The positional parameters in
273: .Fa p_sign_posn ,
274: .Fa n_sign_posn ,
275: .Fa int_p_sign_posn
276: and
277: .Fa int_n_sign_posn
278: are encoded as follows:
1.1 perry 279: .Bl -tag -width 3n -compact
280: .It Li 0
281: Parentheses around the entire string.
282: .It Li 1
283: Before the string.
284: .It Li 2
285: After the string.
286: .It Li 3
287: Just before
288: .Fa currency_symbol .
289: .It Li 4
290: Just after
291: .Fa currency_symbol .
292: .El
293: .Pp
294: Unless mentioned above,
295: an empty string as a value for a field
296: indicates a zero length result or
297: a value that is not in the current locale.
298: A
299: .Dv CHAR_MAX
300: result similarly denotes an unavailable value.
1.11 uwe 301: .Sh RETURN VALUES
1.1 perry 302: The
303: .Fn setlocale
304: function returns
305: .Dv NULL
306: and fails to change the locale
307: if the given combination of
308: .Fa category
309: and
310: .Fa locale
311: makes no sense.
312: The
313: .Fn localeconv
314: function returns a pointer to a static object
315: which may be altered by later calls to
316: .Fn setlocale
317: or
318: .Fn localeconv .
1.15 ! gmcgarry 319: .Sh EXAMPLES
! 320: The following code illustrates how a program can initialize the
! 321: international environment for one language, while selectively
! 322: modifying the program's locale such that regular expressions and
! 323: string operations can be applied to text recorded in a different
! 324: language:
! 325: .Bd -literal
! 326: setlocale(LC_ALL, "de");
! 327: setlocale(LC_COLLATE, "fr");
! 328: .Ed
! 329: .Pp
! 330: When a process is started, its current locale is set to the C or POSIX
! 331: locale. An internationalized program that depends on locale data not
! 332: defined in the C or POSIX locale must invoke the setlocale subroutine
! 333: in the following manner before using any of the locale-specific
! 334: information:
! 335: .Bd -literal
! 336: setlocale(LC_ALL, "");
! 337: .Ed
1.2 kleink 338: .\" .Sh FILES XXX
339: .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
340: .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX
341: .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX
342: .\" locale file for the locale \fIlocale\fP XXX
343: .\" and the category \fIcategory\fP. XXX
344: .\" .El
1.7 kleink 345: .Sh SEE ALSO
1.15 ! gmcgarry 346: .Xr catopen 3 ,
! 347: .Xr nl_langinfo 3 ,
! 348: .Xr nls 7
1.2 kleink 349: .\" .Xr strcoll 3 , XXX
350: .\" .Xr strxfrm 3 XXX
1.1 perry 351: .Sh STANDARDS
352: The
353: .Fn setlocale
354: and
355: .Fn localeconv
356: functions conform to
1.9 jdolecek 357: .St -ansiC
358: and
1.10 kleink 359: .St -isoC90 .
1.8 kleink 360: .Pp
361: The
362: .Fa int_p_cs_precedes ,
363: .Fa int_n_cs_precedes ,
364: .Fa int_p_sep_by_space ,
365: .Fa int_n_sep_by_space ,
366: .Fa int_p_sign_posn
367: and
368: .Fa int_n_sign_posn
369: members of
370: .Ft struct lconv
371: were introduced in
372: .St -isoC99 .
1.1 perry 373: .Sh HISTORY
374: The
375: .Fn setlocale
376: and
377: .Fn localeconv
1.2 kleink 378: functions first appeared in
379: .Bx 4.4 .
1.1 perry 380: .Sh BUGS
381: The current implementation supports only the
382: .Li "\&""C""
383: and
384: .Li "\&""POSIX""
385: locales for all but the LC_CTYPE locale.
386: .Pp
387: In spite of the gnarly currency support in
388: .Fn localeconv ,
389: the standards don't include any functions
390: for generalized currency formatting.
391: .Pp
392: .Dv LC_COLLATE
393: does not make sense for many languages.
394: Use of
395: .Dv LC_MONETARY
396: could lead to misleading results until we have a real time currency
397: conversion function.
398: .Dv LC_NUMERIC
399: and
400: .Dv LC_TIME
401: are personal choices and should not be wrapped up with the other categories.
1.13 yamt 402: .Pp
403: Multibyte locales aren't supported for static binaries.
CVSweb <webmaster@jp.NetBSD.org>