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 36.\" 37.Dd June 9, 1993 38.Dt SETLOCALE 3 39.Os 40.Sh NAME 41.Nm setlocale , 42.Nm localeconv 43.Nd natural language formatting for C 44.Sh SYNOPSIS 45.Fd #include <locale.h> 46.Ft char * 47.Fn setlocale "int category" "const char *locale" 48.Ft struct lconv * 49.Fn localeconv "void" 50.Sh DESCRIPTION 51The 52.Fn setlocale 53function sets the C library's notion 54of natural language formatting style 55for particular sets of routines. 56Each such style is called a 57.Sq locale 58and is invoked using an appropriate name passed as a C string. 59The 60.Fn localeconv 61routine returns the current locale's parameters 62for formatting numbers. 63.Pp 64The 65.Fn setlocale 66function recognizes several categories of routines. 67These are the categories and the sets of routines they select: 68.Pp 69.Bl -tag -width LC_MONETARY 70.It Dv LC_ALL 71Set the entire locale generically. 72.It Dv LC_COLLATE 73Set a locale for string collation routines. 74This controls alphabetic ordering in 75.Fn strcoll 76and 77.Fn strxfrm . 78.It Dv LC_CTYPE 79Set a locale for the 80.Xr ctype 3 , 81.Xr mbrune 3 , 82.Xr multibyte 3 83and 84.Xr rune 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}; 160.Ed 161.Pp 162The individual fields have the following meanings: 163.Pp 164.Bl -tag -width mon_decimal_point 165.It Fa decimal_point 166The decimal point character, except for currency values. 167.It Fa thousands_sep 168The separator between groups of digits 169before the decimal point, except for currency values. 170.It Fa grouping 171The sizes of the groups of digits, except for currency values. 172This is a pointer to a vector of integers, each of size 173.Va char , 174representing group size from low order digit groups 175to high order (right to left). 176The list may be terminated with 0 or 177.Dv CHAR_MAX . 178If the list is terminated with 0, 179the last group size before the 0 is repeated to account for all the digits. 180If the list is terminated with 181.Dv CHAR_MAX , 182no more grouping is performed. 183.It Fa int_curr_symbol 184The standardized international currency symbol. 185.It Fa currency_symbol 186The local currency symbol. 187.It Fa mon_decimal_point 188The decimal point character for currency values. 189.It Fa mon_thousands_sep 190The separator for digit groups in currency values. 191.It Fa mon_grouping 192Like 193.Fa grouping 194but for currency values. 195.It Fa positive_sign 196The character used to denote nonnegative currency values, 197usually the empty string. 198.It Fa negative_sign 199The character used to denote negative currency values, 200usually a minus sign. 201.It Fa int_frac_digits 202The number of digits after the decimal point 203in an international-style currency value. 204.It Fa frac_digits 205The number of digits after the decimal point 206in the local style for currency values. 207.It Fa p_cs_precedes 2081 if the currency symbol precedes the currency value 209for nonnegative values, 0 if it follows. 210.It Fa p_sep_by_space 2111 if a space is inserted between the currency symbol 212and the currency value for nonnegative values, 0 otherwise. 213.It Fa n_cs_precedes 214Like 215.Fa p_cs_precedes 216but for negative values. 217.It Fa n_sep_by_space 218Like 219.Fa p_sep_by_space 220but for negative values. 221.It Fa p_sign_posn 222The location of the 223.Fa positive_sign 224with respect to a nonnegative quantity and the 225.Fa currency_symbol , 226coded as follows: 227.Bl -tag -width 3n -compact 228.It Li 0 229Parentheses around the entire string. 230.It Li 1 231Before the string. 232.It Li 2 233After the string. 234.It Li 3 235Just before 236.Fa currency_symbol . 237.It Li 4 238Just after 239.Fa currency_symbol . 240.El 241.It Fa n_sign_posn 242Like 243.Fa p_sign_posn 244but for negative currency values. 245.El 246.Pp 247Unless mentioned above, 248an empty string as a value for a field 249indicates a zero length result or 250a value that is not in the current locale. 251A 252.Dv CHAR_MAX 253result similarly denotes an unavailable value. 254.Sh "RETURN VALUES 255The 256.Fn setlocale 257function returns 258.Dv NULL 259and fails to change the locale 260if the given combination of 261.Fa category 262and 263.Fa locale 264makes no sense. 265The 266.Fn localeconv 267function returns a pointer to a static object 268which may be altered by later calls to 269.Fn setlocale 270or 271.Fn localeconv . 272.Sh FILES 273.Bl -tag -width /usr/share/locale/locale/category -compact 274.It Pa $PATH_LOCALE/ Ns Em locale/category 275.It Pa /usr/share/locale/ Ns Em locale/category 276locale file for the locale 277.Em locale 278and the category 279.Em category . 280.El 281.Sh "SEE ALSO 282.Xr colldef 1 , 283.Xr mklocale 1 , 284.Xr mbrune 3 , 285.Xr multibyte 3 , 286.Xr rune 3 , 287.Xr strcoll 3 , 288.Xr strxfrm 3 , 289.Xr euc 4 , 290.Xr utf2 4 291.Sh STANDARDS 292The 293.Fn setlocale 294and 295.Fn localeconv 296functions conform to 297.St -ansiC . 298.Sh HISTORY 299The 300.Fn setlocale 301and 302.Fn localeconv 303functions first appeared in 304.Bx 4.4 . 305.Sh BUGS 306The current implementation supports only the 307.Li "\&""C"" 308and 309.Li "\&""POSIX"" 310locales for all but the 311.Dv LC_COLLATE , 312.Dv LC_CTYPE , 313and 314.Dv LC_TIME 315categories. 316.Pp 317In spite of the gnarly currency support in 318.Fn localeconv , 319the standards don't include any functions 320for generalized currency formatting. 321.Pp 322Use of 323.Dv LC_MONETARY 324could lead to misleading results until we have a real time currency 325conversion function. 326.Dv LC_NUMERIC 327and 328.Dv LC_TIME 329are personal choices and should not be wrapped up with the other categories. 330