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