1.\" Copyright (c) 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Donn Seeley at BSDI.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
| 1.\" Copyright (c) 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Donn Seeley at BSDI.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
|
37.\"
38.Dd October 5, 2002
39.Dt SETLOCALE 3
40.Os
41.Sh NAME
42.Nm setlocale ,
43.Nm localeconv
44.Nd natural language formatting for C
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In locale.h
49.Ft char *
50.Fn setlocale "int category" "const char *locale"
51.Ft struct lconv *
52.Fn localeconv "void"
53.Sh DESCRIPTION
54The
55.Fn setlocale
56function sets the C library's notion
57of natural language formatting style
58for particular sets of routines.
59Each such style is called a
60.Sq locale
61and is invoked using an appropriate name passed as a C string.
62The
63.Fn localeconv
64routine returns the current locale's parameters
65for formatting numbers.
66.Pp
67The
68.Fn setlocale
69function recognizes several categories of routines.
70These are the categories and the sets of routines they select:
71.Pp
72.Bl -tag -width LC_MONETARY
73.It Dv LC_ALL
74Set the entire locale generically.
75.It Dv LC_COLLATE
76Set a locale for string collation routines.
77This controls alphabetic ordering in
78.Fn strcoll
79and
80.Fn strxfrm .
81.It Dv LC_CTYPE
82Set a locale for the
83.Xr ctype 3 ,
84.Xr mbrune 3 ,
85.Xr multibyte 3
86and
87.Xr rune 3
88functions.
89This controls recognition of upper and lower case,
90alphabetic or non-alphabetic characters,
91and so on. The real work is done by the
92.Fn setrunelocale
93function.
94.It Dv LC_MESSAGES
95Set a locale for message catalogs, see
96.Xr catopen 3
97function.
98.It Dv LC_MONETARY
99Set a locale for formatting monetary values;
100this affects the
101.Fn localeconv
102function.
103.It Dv LC_NUMERIC
104Set a locale for formatting numbers.
105This controls the formatting of decimal points
106in input and output of floating point numbers
107in functions such as
108.Fn printf
109and
110.Fn scanf ,
111as well as values returned by
112.Fn localeconv .
113.It Dv LC_TIME
114Set a locale for formatting dates and times using the
115.Fn strftime
116function.
117.El
118.Pp
119Only three locales are defined by default,
120the empty string
121.Li "\&""\|""
122which denotes the native environment, and the
123.Li "\&""C""
124and
125.Li "\&""POSIX""
126locales, which denote the C language environment.
127A
128.Fa locale
129argument of
130.Dv NULL
131causes
132.Fn setlocale
133to return the current locale.
134By default, C programs start in the
135.Li "\&""C""
136locale.
137The only function in the library that sets the locale is
138.Fn setlocale ;
139the locale is never changed as a side effect of some other routine.
140.Pp
141The
142.Fn localeconv
143function returns a pointer to a structure
144which provides parameters for formatting numbers,
145especially currency values:
146.Bd -literal -offset indent
147struct lconv {
148 char *decimal_point;
149 char *thousands_sep;
150 char *grouping;
151 char *int_curr_symbol;
152 char *currency_symbol;
153 char *mon_decimal_point;
154 char *mon_thousands_sep;
155 char *mon_grouping;
156 char *positive_sign;
157 char *negative_sign;
158 char int_frac_digits;
159 char frac_digits;
160 char p_cs_precedes;
161 char p_sep_by_space;
162 char n_cs_precedes;
163 char n_sep_by_space;
164 char p_sign_posn;
165 char n_sign_posn;
166 char int_p_cs_precedes;
167 char int_n_cs_precedes;
168 char int_p_sep_by_space;
169 char int_n_sep_by_space;
170 char int_p_sign_posn;
171 char int_n_sign_posn;
172};
173.Ed
174.Pp
175The individual fields have the following meanings:
176.Pp
177.Bl -tag -width mon_decimal_point
178.It Fa decimal_point
179The decimal point character, except for currency values.
180.It Fa thousands_sep
181The separator between groups of digits
182before the decimal point, except for currency values.
183.It Fa grouping
184The sizes of the groups of digits, except for currency values.
185This is a pointer to a vector of integers, each of size
186.Va char ,
187representing group size from low order digit groups
188to high order (right to left).
189The list may be terminated with 0 or
190.Dv CHAR_MAX .
191If the list is terminated with 0,
192the last group size before the 0 is repeated to account for all the digits.
193If the list is terminated with
194.Dv CHAR_MAX ,
195no more grouping is performed.
196.It Fa int_curr_symbol
197The standardized international currency symbol.
198.It Fa currency_symbol
199The local currency symbol.
200.It Fa mon_decimal_point
201The decimal point character for currency values.
202.It Fa mon_thousands_sep
203The separator for digit groups in currency values.
204.It Fa mon_grouping
205Like
206.Fa grouping
207but for currency values.
208.It Fa positive_sign
209The character used to denote nonnegative currency values,
210usually the empty string.
211.It Fa negative_sign
212The character used to denote negative currency values,
213usually a minus sign.
214.It Fa int_frac_digits
215The number of digits after the decimal point
216in an international-style currency value.
217.It Fa frac_digits
218The number of digits after the decimal point
219in the local style for currency values.
220.It Fa p_cs_precedes
2211 if the currency symbol precedes the currency value
222for nonnegative values, 0 if it follows.
223.It Fa p_sep_by_space
2241 if a space is inserted between the currency symbol
225and the currency value for nonnegative values, 0 otherwise.
226.It Fa n_cs_precedes
227Like
228.Fa p_cs_precedes
229but for negative values.
230.It Fa n_sep_by_space
231Like
232.Fa p_sep_by_space
233but for negative values.
234.It Fa p_sign_posn
235The location of the
236.Fa positive_sign
237with respect to a nonnegative quantity and the
238.Fa currency_symbol ,
239coded as follows:
240.Bl -tag -width 3n -compact
241.It Li 0
242Parentheses around the entire string.
243.It Li 1
244Before the string.
245.It Li 2
246After the string.
247.It Li 3
248Just before
249.Fa currency_symbol .
250.It Li 4
251Just after
252.Fa currency_symbol .
253.El
254.It Fa n_sign_posn
255Like
256.Fa p_sign_posn
257but for negative currency values.
258.It Fa int_p_cs_precedes
259Same as
260.Fa p_cs_precedes ,
261but for internationally formatted monetary quantities.
262.It Fa int_n_cs_precedes
263Same as
264.Fa n_cs_precedes ,
265but for internationally formatted monetary quantities.
266.It Fa int_p_sep_by_space
267Same as
268.Fa p_sep_by_space ,
269but for internationally formatted monetary quantities.
270.It Fa int_n_sep_by_space
271Same as
272.Fa n_sep_by_space ,
273but for internationally formatted monetary quantities.
274.It Fa int_p_sign_posn
275Same as
276.Fa p_sign_posn ,
277but for internationally formatted monetary quantities.
278.It Fa int_n_sign_posn
279Same as
280.Fa n_sign_posn ,
281but for internationally formatted monetary quantities.
282.El
283.Pp
284Unless mentioned above,
285an empty string as a value for a field
286indicates a zero length result or
287a value that is not in the current locale.
288A
289.Dv CHAR_MAX
290result similarly denotes an unavailable value.
291.Sh RETURN VALUES
292Upon successful completion,
293.Fn setlocale
294returns the string associated with the specified
295.Fa category
296for the requested
297.Fa locale .
298The
299.Fn setlocale
300function returns
301.Dv NULL
302and fails to change the locale
303if the given combination of
304.Fa category
305and
306.Fa locale
307makes no sense.
308The
309.Fn localeconv
310function returns a pointer to a static object
311which may be altered by later calls to
312.Fn setlocale
313or
314.Fn localeconv .
315.Sh ERRORS
316No errors are defined.
317.Sh FILES
318.Bl -tag -width /usr/share/locale/locale/category -compact
319.It Pa $PATH_LOCALE/ Ns Em locale/category
320.It Pa /usr/share/locale/ Ns Em locale/category
321locale file for the locale
322.Em locale
323and the category
324.Em category .
325.El
326.Sh SEE ALSO
327.Xr colldef 1 ,
328.Xr mklocale 1 ,
329.Xr catopen 3 ,
330.Xr ctype 3 ,
331.Xr mbrune 3 ,
332.Xr multibyte 3 ,
333.Xr rune 3 ,
334.Xr strcoll 3 ,
335.Xr strxfrm 3 ,
336.Xr euc 4 ,
| 37.\"
38.Dd October 5, 2002
39.Dt SETLOCALE 3
40.Os
41.Sh NAME
42.Nm setlocale ,
43.Nm localeconv
44.Nd natural language formatting for C
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In locale.h
49.Ft char *
50.Fn setlocale "int category" "const char *locale"
51.Ft struct lconv *
52.Fn localeconv "void"
53.Sh DESCRIPTION
54The
55.Fn setlocale
56function sets the C library's notion
57of natural language formatting style
58for particular sets of routines.
59Each such style is called a
60.Sq locale
61and is invoked using an appropriate name passed as a C string.
62The
63.Fn localeconv
64routine returns the current locale's parameters
65for formatting numbers.
66.Pp
67The
68.Fn setlocale
69function recognizes several categories of routines.
70These are the categories and the sets of routines they select:
71.Pp
72.Bl -tag -width LC_MONETARY
73.It Dv LC_ALL
74Set the entire locale generically.
75.It Dv LC_COLLATE
76Set a locale for string collation routines.
77This controls alphabetic ordering in
78.Fn strcoll
79and
80.Fn strxfrm .
81.It Dv LC_CTYPE
82Set a locale for the
83.Xr ctype 3 ,
84.Xr mbrune 3 ,
85.Xr multibyte 3
86and
87.Xr rune 3
88functions.
89This controls recognition of upper and lower case,
90alphabetic or non-alphabetic characters,
91and so on. The real work is done by the
92.Fn setrunelocale
93function.
94.It Dv LC_MESSAGES
95Set a locale for message catalogs, see
96.Xr catopen 3
97function.
98.It Dv LC_MONETARY
99Set a locale for formatting monetary values;
100this affects the
101.Fn localeconv
102function.
103.It Dv LC_NUMERIC
104Set a locale for formatting numbers.
105This controls the formatting of decimal points
106in input and output of floating point numbers
107in functions such as
108.Fn printf
109and
110.Fn scanf ,
111as well as values returned by
112.Fn localeconv .
113.It Dv LC_TIME
114Set a locale for formatting dates and times using the
115.Fn strftime
116function.
117.El
118.Pp
119Only three locales are defined by default,
120the empty string
121.Li "\&""\|""
122which denotes the native environment, and the
123.Li "\&""C""
124and
125.Li "\&""POSIX""
126locales, which denote the C language environment.
127A
128.Fa locale
129argument of
130.Dv NULL
131causes
132.Fn setlocale
133to return the current locale.
134By default, C programs start in the
135.Li "\&""C""
136locale.
137The only function in the library that sets the locale is
138.Fn setlocale ;
139the locale is never changed as a side effect of some other routine.
140.Pp
141The
142.Fn localeconv
143function returns a pointer to a structure
144which provides parameters for formatting numbers,
145especially currency values:
146.Bd -literal -offset indent
147struct lconv {
148 char *decimal_point;
149 char *thousands_sep;
150 char *grouping;
151 char *int_curr_symbol;
152 char *currency_symbol;
153 char *mon_decimal_point;
154 char *mon_thousands_sep;
155 char *mon_grouping;
156 char *positive_sign;
157 char *negative_sign;
158 char int_frac_digits;
159 char frac_digits;
160 char p_cs_precedes;
161 char p_sep_by_space;
162 char n_cs_precedes;
163 char n_sep_by_space;
164 char p_sign_posn;
165 char n_sign_posn;
166 char int_p_cs_precedes;
167 char int_n_cs_precedes;
168 char int_p_sep_by_space;
169 char int_n_sep_by_space;
170 char int_p_sign_posn;
171 char int_n_sign_posn;
172};
173.Ed
174.Pp
175The individual fields have the following meanings:
176.Pp
177.Bl -tag -width mon_decimal_point
178.It Fa decimal_point
179The decimal point character, except for currency values.
180.It Fa thousands_sep
181The separator between groups of digits
182before the decimal point, except for currency values.
183.It Fa grouping
184The sizes of the groups of digits, except for currency values.
185This is a pointer to a vector of integers, each of size
186.Va char ,
187representing group size from low order digit groups
188to high order (right to left).
189The list may be terminated with 0 or
190.Dv CHAR_MAX .
191If the list is terminated with 0,
192the last group size before the 0 is repeated to account for all the digits.
193If the list is terminated with
194.Dv CHAR_MAX ,
195no more grouping is performed.
196.It Fa int_curr_symbol
197The standardized international currency symbol.
198.It Fa currency_symbol
199The local currency symbol.
200.It Fa mon_decimal_point
201The decimal point character for currency values.
202.It Fa mon_thousands_sep
203The separator for digit groups in currency values.
204.It Fa mon_grouping
205Like
206.Fa grouping
207but for currency values.
208.It Fa positive_sign
209The character used to denote nonnegative currency values,
210usually the empty string.
211.It Fa negative_sign
212The character used to denote negative currency values,
213usually a minus sign.
214.It Fa int_frac_digits
215The number of digits after the decimal point
216in an international-style currency value.
217.It Fa frac_digits
218The number of digits after the decimal point
219in the local style for currency values.
220.It Fa p_cs_precedes
2211 if the currency symbol precedes the currency value
222for nonnegative values, 0 if it follows.
223.It Fa p_sep_by_space
2241 if a space is inserted between the currency symbol
225and the currency value for nonnegative values, 0 otherwise.
226.It Fa n_cs_precedes
227Like
228.Fa p_cs_precedes
229but for negative values.
230.It Fa n_sep_by_space
231Like
232.Fa p_sep_by_space
233but for negative values.
234.It Fa p_sign_posn
235The location of the
236.Fa positive_sign
237with respect to a nonnegative quantity and the
238.Fa currency_symbol ,
239coded as follows:
240.Bl -tag -width 3n -compact
241.It Li 0
242Parentheses around the entire string.
243.It Li 1
244Before the string.
245.It Li 2
246After the string.
247.It Li 3
248Just before
249.Fa currency_symbol .
250.It Li 4
251Just after
252.Fa currency_symbol .
253.El
254.It Fa n_sign_posn
255Like
256.Fa p_sign_posn
257but for negative currency values.
258.It Fa int_p_cs_precedes
259Same as
260.Fa p_cs_precedes ,
261but for internationally formatted monetary quantities.
262.It Fa int_n_cs_precedes
263Same as
264.Fa n_cs_precedes ,
265but for internationally formatted monetary quantities.
266.It Fa int_p_sep_by_space
267Same as
268.Fa p_sep_by_space ,
269but for internationally formatted monetary quantities.
270.It Fa int_n_sep_by_space
271Same as
272.Fa n_sep_by_space ,
273but for internationally formatted monetary quantities.
274.It Fa int_p_sign_posn
275Same as
276.Fa p_sign_posn ,
277but for internationally formatted monetary quantities.
278.It Fa int_n_sign_posn
279Same as
280.Fa n_sign_posn ,
281but for internationally formatted monetary quantities.
282.El
283.Pp
284Unless mentioned above,
285an empty string as a value for a field
286indicates a zero length result or
287a value that is not in the current locale.
288A
289.Dv CHAR_MAX
290result similarly denotes an unavailable value.
291.Sh RETURN VALUES
292Upon successful completion,
293.Fn setlocale
294returns the string associated with the specified
295.Fa category
296for the requested
297.Fa locale .
298The
299.Fn setlocale
300function returns
301.Dv NULL
302and fails to change the locale
303if the given combination of
304.Fa category
305and
306.Fa locale
307makes no sense.
308The
309.Fn localeconv
310function returns a pointer to a static object
311which may be altered by later calls to
312.Fn setlocale
313or
314.Fn localeconv .
315.Sh ERRORS
316No errors are defined.
317.Sh FILES
318.Bl -tag -width /usr/share/locale/locale/category -compact
319.It Pa $PATH_LOCALE/ Ns Em locale/category
320.It Pa /usr/share/locale/ Ns Em locale/category
321locale file for the locale
322.Em locale
323and the category
324.Em category .
325.El
326.Sh SEE ALSO
327.Xr colldef 1 ,
328.Xr mklocale 1 ,
329.Xr catopen 3 ,
330.Xr ctype 3 ,
331.Xr mbrune 3 ,
332.Xr multibyte 3 ,
333.Xr rune 3 ,
334.Xr strcoll 3 ,
335.Xr strxfrm 3 ,
336.Xr euc 4 ,
|