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