1.\" $NetBSD: src/lib/libc/locale/setlocale.3,v 1.21 2004/01/24 16:58:54 wiz Exp $ 2.\" $DragonFly: src/lib/libc/locale/setlocale.3,v 1.3 2005/03/12 00:18:01 joerg Exp $ 3.\" 4.\" Copyright (c) 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Donn Seeley at BSDI. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 35.\" 36.Dd May 30, 2003 37.Dt SETLOCALE 3 38.Os 39.Sh NAME 40.Nm setlocale , 41.Nm localeconv 42.Nd natural language formatting for C 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In 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.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 81functions. 82This controls recognition of upper and lower case, 83alphabetic or non-alphabetic characters, 84and so on. 85The real work is done by the 86.Fn setrunelocale 87function. 88.It Dv LC_MESSAGES 89Set a locale for message catalogs. 90This controls the selection of message catalogs by the 91.Xr catgets 3 92and 93.Xr gettext 3 94families of functions. 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 format of the locale string is described in 135.Xr nls 7 . 136.Pp 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 141Changing the setting of 142.Dv LC_MESSAGES 143has no effect on catalogs that have already been opened by 144.Xr catopen 3 . 145.Pp 146The 147.Fn localeconv 148function returns a pointer to a structure 149which provides parameters for formatting numbers, 150especially currency values: 151.Bd -literal -offset indent 152struct lconv { 153 char *decimal_point; 154 char *thousands_sep; 155 char *grouping; 156 char *int_curr_symbol; 157 char *currency_symbol; 158 char *mon_decimal_point; 159 char *mon_thousands_sep; 160 char *mon_grouping; 161 char *positive_sign; 162 char *negative_sign; 163 char int_frac_digits; 164 char frac_digits; 165 char p_cs_precedes; 166 char p_sep_by_space; 167 char n_cs_precedes; 168 char n_sep_by_space; 169 char p_sign_posn; 170 char n_sign_posn; 171 char int_p_cs_precedes; 172 char int_n_cs_precedes; 173 char int_p_sep_by_space; 174 char int_n_sep_by_space; 175 char int_p_sign_posn; 176 char int_n_sign_posn; 177}; 178.Ed 179.Pp 180The individual fields have the following meanings: 181.Bl -tag -width int_p_sep_by_space 182.It Fa decimal_point 183The decimal point character, except for monetary values. 184.It Fa thousands_sep 185The separator between groups of digits 186before the decimal point, except for monetary values. 187.It Fa grouping 188The sizes of the groups of digits, except for monetary values. 189This is a pointer to a vector of integers, each of size 190.Va char , 191representing group size from low order digit groups 192to high order (right to left). 193The list may be terminated with 0 or 194.Dv CHAR_MAX . 195If the list is terminated with 0, 196the last group size before the 0 is repeated to account for all the digits. 197If the list is terminated with 198.Dv CHAR_MAX , 199no more grouping is performed. 200.It Fa int_curr_symbol 201The standardized (ISO 4217:1995) international currency symbol. 202.It Fa currency_symbol 203The local currency symbol. 204.It Fa mon_decimal_point 205The decimal point character for monetary values. 206.It Fa mon_thousands_sep 207The separator for digit groups in monetary values. 208.It Fa mon_grouping 209Like 210.Fa grouping 211but for monetary values. 212.It Fa positive_sign 213The character used to denote nonnegative monetary values, 214usually the empty string. 215.It Fa negative_sign 216The character used to denote negative monetary values, 217usually a minus sign. 218.It Fa int_frac_digits 219The number of digits after the decimal point 220in an internationally formatted monetary value. 221.It Fa frac_digits 222The number of digits after the decimal point 223in an locally formatted monetary value. 224.It Fa p_cs_precedes 2251 if the currency symbol precedes the monetary value 226for nonnegative values, 0 if it follows. 227.It Fa p_sep_by_space 2281 if a space is inserted between the currency symbol 229and the monetary value for nonnegative values, 0 otherwise. 230.It Fa n_cs_precedes 231Like 232.Fa p_cs_precedes 233but for negative values. 234.It Fa n_sep_by_space 235Like 236.Fa p_sep_by_space 237but for negative values. 238.It Fa p_sign_posn 239The location of the 240.Fa positive_sign 241with respect to a nonnegative quantity and the 242.Fa currency_symbol . 243.It Fa n_sign_posn 244Like 245.Fa p_sign_posn 246but for negative currency values. 247.It Fa int_p_cs_precedes 2481 if the currency symbol precedes the internationally 249formatted monetary value for nonnegative values, 0 if it follows. 250.It Fa int_n_cs_precedes 251Like 252.Fa int_p_cs_precedes 253but for negative values. 254.It Fa int_p_sep_by_space 2551 if a space is inserted between the currency symbol 256and the internationally formatted monetary value for 257nonnegative values, 0 otherwise. 258.It Fa int_n_sep_by_space 259Like 260.Fa int_p_sep_by_space 261but for negative values. 262.It Fa int_p_sign_posn 263The location of the 264.Fa positive_sign 265with respect to a nonnegative quantity and the 266.Fa currency_symbol , 267for internationally formatted nonnegative monetary values. 268.It Fa int_n_sign_posn 269Like 270.Fa int_p_sign_posn 271but for negative values. 272.El 273.Pp 274The positional parameters in 275.Fa p_sign_posn , 276.Fa n_sign_posn , 277.Fa int_p_sign_posn 278and 279.Fa int_n_sign_posn 280are encoded as follows: 281.Bl -tag -width 3n -compact 282.It Li 0 283Parentheses around the entire string. 284.It Li 1 285Before the string. 286.It Li 2 287After the string. 288.It Li 3 289Just before 290.Fa currency_symbol . 291.It Li 4 292Just after 293.Fa currency_symbol . 294.El 295.Pp 296Unless mentioned above, 297an empty string as a value for a field 298indicates a zero length result or 299a value that is not in the current locale. 300A 301.Dv CHAR_MAX 302result similarly denotes an unavailable value. 303.Sh RETURN VALUES 304The 305.Fn setlocale 306function returns 307.Dv NULL 308and fails to change the locale 309if the given combination of 310.Fa category 311and 312.Fa locale 313makes no sense. 314The 315.Fn localeconv 316function returns a pointer to a static object 317which may be altered by later calls to 318.Fn setlocale 319or 320.Fn localeconv . 321.Sh EXAMPLES 322The following code illustrates how a program can initialize the 323international environment for one language, while selectively 324modifying the program's locale such that regular expressions and 325string operations can be applied to text recorded in a different 326language: 327.Bd -literal 328 setlocale(LC_ALL, "de"); 329 setlocale(LC_COLLATE, "fr"); 330.Ed 331.Pp 332When a process is started, its current locale is set to the C or POSIX 333locale. 334An internationalized program that depends on locale data not defined in 335the C or POSIX locale must invoke the setlocale subroutine in the 336following manner before using any of the locale-specific information: 337.Bd -literal 338 setlocale(LC_ALL, ""); 339.Ed 340.\" .Sh FILES XXX 341.\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX 342.\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX 343.\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX 344.\" locale file for the locale \fIlocale\fP XXX 345.\" and the category \fIcategory\fP. XXX 346.\" .El 347.Sh SEE ALSO 348.Xr catopen 3 , 349.Xr gettext 3 , 350.Xr nl_langinfo 3 , 351.Xr nls 7 352.\" .Xr strcoll 3 , XXX 353.\" .Xr strxfrm 3 XXX 354.Sh STANDARDS 355The 356.Fn setlocale 357and 358.Fn localeconv 359functions conform to 360.St -ansiC 361and 362.St -isoC-90 . 363.Pp 364The 365.Fa int_p_cs_precedes , 366.Fa int_n_cs_precedes , 367.Fa int_p_sep_by_space , 368.Fa int_n_sep_by_space , 369.Fa int_p_sign_posn 370and 371.Fa int_n_sign_posn 372members of 373.Ft struct lconv 374were introduced in 375.St -isoC-99 . 376.Sh HISTORY 377The 378.Fn setlocale 379and 380.Fn localeconv 381functions first appeared in 382.Bx 4.4 . 383.Sh BUGS 384The current implementation supports only the 385.Li "\&""C"" 386and 387.Li "\&""POSIX"" 388locales for all but the 389.Dv LC_CTYPE 390locale. 391.Pp 392In spite of the gnarly currency support in 393.Fn localeconv , 394the standards don't include any functions 395for generalized currency formatting. 396.Pp 397.Dv LC_COLLATE 398does not make sense for many languages. 399Use of 400.Dv LC_MONETARY 401could lead to misleading results until we have a real time currency 402conversion function. 403.Dv LC_NUMERIC 404and 405.Dv LC_TIME 406are personal choices and should not be wrapped up with the other categories. 407.Pp 408Multibyte locales aren't supported for static binaries. 409