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. 180.It Fa thousands_sep 181The separator between groups of digits 182before the decimal point, except for currency values. 183.It Fa grouping 184The sizes of the groups of digits, except for currency values. 185This is a pointer to a vector of integers, each of size 186.Va char , 187representing group size from low order digit groups 188to high order (right to left). 189The list may be terminated with 0 or 190.Dv CHAR_MAX . 191If the list is terminated with 0, 192the last group size before the 0 is repeated to account for all the digits. 193If the list is terminated with 194.Dv CHAR_MAX , 195no more grouping is performed. 196.It Fa int_curr_symbol 197The standardized international currency symbol. 198.It Fa currency_symbol 199The local currency symbol. 200.It Fa mon_decimal_point 201The decimal point character for currency values. 202.It Fa mon_thousands_sep 203The separator for digit groups in currency values. 204.It Fa mon_grouping 205Like 206.Fa grouping 207but for currency values. 208.It Fa positive_sign 209The character used to denote nonnegative currency values, 210usually the empty string. 211.It Fa negative_sign 212The character used to denote negative currency values, 213usually a minus sign. 214.It Fa int_frac_digits 215The number of digits after the decimal point 216in an international-style currency value. 217.It Fa frac_digits 218The number of digits after the decimal point 219in the local style for currency values. 220.It Fa p_cs_precedes 2211 if the currency symbol precedes the currency value 222for nonnegative values, 0 if it follows. 223.It Fa p_sep_by_space 2241 if a space is inserted between the currency symbol 225and the currency value for nonnegative values, 0 otherwise. 226.It Fa n_cs_precedes 227Like 228.Fa p_cs_precedes 229but for negative values. 230.It Fa n_sep_by_space 231Like 232.Fa p_sep_by_space 233but for negative values. 234.It Fa p_sign_posn 235The location of the 236.Fa positive_sign 237with respect to a nonnegative quantity and the 238.Fa currency_symbol , 239coded as follows: 240.Bl -tag -width 3n -compact 241.It Li 0 242Parentheses around the entire string. 243.It Li 1 244Before the string. 245.It Li 2 246After the string. 247.It Li 3 248Just before 249.Fa currency_symbol . 250.It Li 4 251Just after 252.Fa currency_symbol . 253.El 254.It Fa n_sign_posn 255Like 256.Fa p_sign_posn 257but for negative currency values. 258.It Fa int_p_cs_precedes 259Same as 260.Fa p_cs_precedes , 261but for internationally formatted monetary quantities. 262.It Fa int_n_cs_precedes 263Same as 264.Fa n_cs_precedes , 265but for internationally formatted monetary quantities. 266.It Fa int_p_sep_by_space 267Same as 268.Fa p_sep_by_space , 269but for internationally formatted monetary quantities. 270.It Fa int_n_sep_by_space 271Same as 272.Fa n_sep_by_space , 273but for internationally formatted monetary quantities. 274.It Fa int_p_sign_posn 275Same as 276.Fa p_sign_posn , 277but for internationally formatted monetary quantities. 278.It Fa int_n_sign_posn 279Same as 280.Fa n_sign_posn , 281but for internationally formatted monetary quantities. 282.El 283.Pp 284Unless mentioned above, 285an empty string as a value for a field 286indicates a zero length result or 287a value that is not in the current locale. 288A 289.Dv CHAR_MAX 290result similarly denotes an unavailable value. 291.Sh RETURN VALUES 292Upon successful completion, 293.Fn setlocale 294returns the string associated with the specified 295.Fa category 296for the requested 297.Fa locale . 298The 299.Fn setlocale 300function returns 301.Dv NULL 302and fails to change the locale 303if the given combination of 304.Fa category 305and 306.Fa locale 307makes no sense. 308The 309.Fn localeconv 310function returns a pointer to a static object 311which may be altered by later calls to 312.Fn setlocale 313or 314.Fn localeconv . 315.Sh ERRORS 316No errors are defined. 317.Sh FILES 318.Bl -tag -width /usr/share/locale/locale/category -compact 319.It Pa $PATH_LOCALE/ Ns Em locale/category 320.It Pa /usr/share/locale/ Ns Em locale/category 321locale file for the locale 322.Em locale 323and the category 324.Em category . 325.El 326.Sh SEE ALSO 327.Xr colldef 1 , 328.Xr mklocale 1 , 329.Xr catopen 3 , 330.Xr ctype 3 , 331.Xr mbrune 3 , 332.Xr multibyte 3 , 333.Xr rune 3 , 334.Xr strcoll 3 , 335.Xr strxfrm 3 , 336.Xr euc 4 , 337.Xr utf2 4 , 338.Xr utf8 5 339.Sh STANDARDS 340The 341.Fn setlocale 342and 343.Fn localeconv 344functions conform to 345.St -isoC-99 . 346.Sh HISTORY 347The 348.Fn setlocale 349and 350.Fn localeconv 351functions first appeared in 352.Bx 4.4 . 353