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