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