Annotation of src/lib/libc/locale/setlocale.3, Revision 1.3
1.3 ! kleink 1: .\" $NetBSD: setlocale.3,v 1.2 1997/07/12 19:13:12 kleink 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.3 ! kleink 41: .Os NetBSD
1.1 perry 42: .Sh NAME
43: .Nm setlocale ,
44: .Nm localeconv
45: .Nd natural language formatting for C
46: .Sh SYNOPSIS
47: .Fd #include <locale.h>
48: .Ft char *
49: .Fn setlocale "int category" "const char *locale"
50: .Ft struct lconv *
51: .Fn localeconv "void"
52: .Sh DESCRIPTION
53: The
54: .Fn setlocale
55: function sets the C library's notion
56: of natural language formatting style
57: for particular sets of routines.
58: Each such style is called a
59: .Sq locale
60: and is invoked using an appropriate name passed as a C string.
61: The
62: .Fn localeconv
63: routine returns the current locale's parameters
64: for formatting numbers.
65: .Pp
66: The
67: .Fn setlocale
68: function recognizes several categories of routines.
69: These are the categories and the sets of routines they select:
70: .Pp
71: .Bl -tag -width LC_MONETARY
72: .It Dv LC_ALL
73: Set the entire locale generically.
74: .It Dv LC_COLLATE
75: Set a locale for string collation routines.
76: This controls alphabetic ordering in
77: .Fn strcoll
78: and
79: .Fn strxfrm .
80: .It Dv LC_CTYPE
81: Set a locale for the
1.2 kleink 82: .Xr ctype 3
1.1 perry 83: functions.
84: This controls recognition of upper and lower case,
85: alphabetic or non-alphabetic characters,
86: and so on. The real work is done by the
87: .Fn setrunelocale
88: function.
89: .It Dv LC_MONETARY
90: Set a locale for formatting monetary values;
91: this affects the
92: .Fn localeconv
93: function.
94: .It Dv LC_NUMERIC
95: Set a locale for formatting numbers.
96: This controls the formatting of decimal points
97: in input and output of floating point numbers
98: in functions such as
99: .Fn printf
100: and
101: .Fn scanf ,
102: as well as values returned by
103: .Fn localeconv .
104: .It Dv LC_TIME
105: Set a locale for formatting dates and times using the
106: .Fn strftime
107: function.
108: .El
109: .Pp
110: Only three locales are defined by default,
111: the empty string
112: .Li "\&""\|""
113: which denotes the native environment, and the
114: .Li "\&""C""
115: and
116: .LI "\&""POSIX""
117: locales, which denote the C language environment.
118: A
119: .Fa locale
120: argument of
121: .Dv NULL
122: causes
123: .Fn setlocale
124: to return the current locale.
125: By default, C programs start in the
126: .Li "\&""C""
127: locale.
128: The only function in the library that sets the locale is
129: .Fn setlocale ;
130: the locale is never changed as a side effect of some other routine.
131: .Pp
132: The
133: .Fn localeconv
134: function returns a pointer to a structure
135: which provides parameters for formatting numbers,
136: especially currency values:
137: .Bd -literal -offset indent
138: struct lconv {
139: char *decimal_point;
140: char *thousands_sep;
141: char *grouping;
142: char *int_curr_symbol;
143: char *currency_symbol;
144: char *mon_decimal_point;
145: char *mon_thousands_sep;
146: char *mon_grouping;
147: char *positive_sign;
148: char *negative_sign;
149: char int_frac_digits;
150: char frac_digits;
151: char p_cs_precedes;
152: char p_sep_by_space;
153: char n_cs_precedes;
154: char n_sep_by_space;
155: char p_sign_posn;
156: char n_sign_posn;
157: };
158: .Ed
159: .Pp
160: The individual fields have the following meanings:
161: .Pp
162: .Bl -tag -width mon_decimal_point
163: .It Fa decimal_point
164: The decimal point character, except for currency values.
165: .It Fa thousands_sep
166: The separator between groups of digits
167: before the decimal point, except for currency values.
168: .It Fa grouping
169: The sizes of the groups of digits, except for currency values.
170: This is a pointer to a vector of integers, each of size
171: .Va char ,
172: representing group size from low order digit groups
173: to high order (right to left).
174: The list may be terminated with 0 or
175: .Dv CHAR_MAX .
176: If the list is terminated with 0,
177: the last group size before the 0 is repeated to account for all the digits.
178: If the list is terminated with
179: .Dv CHAR_MAX ,
180: no more grouping is performed.
181: .It Fa int_curr_symbol
182: The standardized international currency symbol.
183: .It Fa currency_symbol
184: The local currency symbol.
185: .It Fa mon_decimal_point
186: The decimal point character for currency values.
187: .It Fa mon_thousands_sep
188: The separator for digit groups in currency values.
189: .It Fa mon_grouping
190: Like
191: .Fa grouping
192: but for currency values.
193: .It Fa positive_sign
194: The character used to denote nonnegative currency values,
195: usually the empty string.
196: .It Fa negative_sign
197: The character used to denote negative currency values,
198: usually a minus sign.
199: .It Fa int_frac_digits
200: The number of digits after the decimal point
201: in an international-style currency value.
202: .It Fa frac_digits
203: The number of digits after the decimal point
204: in the local style for currency values.
205: .It Fa p_cs_precedes
206: 1 if the currency symbol precedes the currency value
207: for nonnegative values, 0 if it follows.
208: .It Fa p_sep_by_space
209: 1 if a space is inserted between the currency symbol
210: and the currency value for nonnegative values, 0 otherwise.
211: .It Fa n_cs_precedes
212: Like
213: .Fa p_cs_precedes
214: but for negative values.
215: .It Fa n_sep_by_space
216: Like
217: .Fa p_sep_by_space
218: but for negative values.
219: .It Fa p_sign_posn
220: The location of the
221: .Fa positive_sign
222: with respect to a nonnegative quantity and the
223: .Fa currency_symbol ,
224: coded as follows:
225: .Bl -tag -width 3n -compact
226: .It Li 0
227: Parentheses around the entire string.
228: .It Li 1
229: Before the string.
230: .It Li 2
231: After the string.
232: .It Li 3
233: Just before
234: .Fa currency_symbol .
235: .It Li 4
236: Just after
237: .Fa currency_symbol .
238: .El
239: .It Fa n_sign_posn
240: Like
241: .Fa p_sign_posn
242: but for negative currency values.
243: .El
244: .Pp
245: Unless mentioned above,
246: an empty string as a value for a field
247: indicates a zero length result or
248: a value that is not in the current locale.
249: A
250: .Dv CHAR_MAX
251: result similarly denotes an unavailable value.
252: .Sh "RETURN VALUES
253: The
254: .Fn setlocale
255: function returns
256: .Dv NULL
257: and fails to change the locale
258: if the given combination of
259: .Fa category
260: and
261: .Fa locale
262: makes no sense.
263: The
264: .Fn localeconv
265: function returns a pointer to a static object
266: which may be altered by later calls to
267: .Fn setlocale
268: or
269: .Fn localeconv .
1.2 kleink 270: .\" .Sh FILES XXX
271: .\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
272: .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX
273: .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX
274: .\" locale file for the locale \fIlocale\fP XXX
275: .\" and the category \fIcategory\fP. XXX
276: .\" .El
277: .\" .Sh "SEE ALSO
278: .\" .Xr strcoll 3 , XXX
279: .\" .Xr strxfrm 3 XXX
1.1 perry 280: .Sh STANDARDS
281: The
282: .Fn setlocale
283: and
284: .Fn localeconv
285: functions conform to
286: .St -ansiC .
287: .Sh HISTORY
288: The
289: .Fn setlocale
290: and
291: .Fn localeconv
1.2 kleink 292: functions first appeared in
293: .Bx 4.4 .
1.1 perry 294: .Sh BUGS
295: The current implementation supports only the
296: .Li "\&""C""
297: and
298: .Li "\&""POSIX""
299: locales for all but the LC_CTYPE locale.
300: .Pp
301: In spite of the gnarly currency support in
302: .Fn localeconv ,
303: the standards don't include any functions
304: for generalized currency formatting.
305: .Pp
306: .Dv LC_COLLATE
307: does not make sense for many languages.
308: Use of
309: .Dv LC_MONETARY
310: could lead to misleading results until we have a real time currency
311: conversion function.
312: .Dv LC_NUMERIC
313: and
314: .Dv LC_TIME
315: are personal choices and should not be wrapped up with the other categories.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to setlocale.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / locale