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