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