1.\" $NetBSD: setlocale.3,v 1.23 2022/12/31 14:35:56 nia 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 December 31, 2022 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. 84.It Dv LC_MESSAGES 85Set a locale for message catalogs. 86This controls the selection of message catalogs by the 87.Xr catgets 3 88and 89.Xr gettext 3 90families of functions. 91.It Dv LC_MONETARY 92Set a locale for formatting monetary values; 93this affects the 94.Fn localeconv 95function. 96.It Dv LC_NUMERIC 97Set a locale for formatting numbers. 98This controls the formatting of decimal points 99in input and output of floating point numbers 100in functions such as 101.Fn printf 102and 103.Fn scanf , 104as well as values returned by 105.Fn localeconv . 106.It Dv LC_TIME 107Set a locale for formatting dates and times using the 108.Fn strftime 109function. 110.El 111.Pp 112Only three locales are defined by default, 113the empty string 114.Li "\&""\|"" 115which denotes the native environment, and the 116.Li "\&""C"" 117and 118.Li "\&""POSIX"" 119locales, which denote the C language environment. 120A 121.Fa locale 122argument of 123.Dv NULL 124causes 125.Fn setlocale 126to return the current locale. 127By default, C programs start in the 128.Li "\&""C"" 129locale. 130The format of the locale string is described in 131.Xr nls 7 . 132.Pp 133The only function in the library that sets the locale is 134.Fn setlocale ; 135the locale is never changed as a side effect of some other routine. 136.Pp 137Changing the setting of 138.Dv LC_MESSAGES 139has no effect on catalogs that have already been opened by 140.Xr catopen 3 . 141.Pp 142The 143.Fn localeconv 144function returns a pointer to a structure 145which provides parameters for formatting numbers, 146especially currency values: 147.Bd -literal -offset indent 148struct lconv { 149 char *decimal_point; 150 char *thousands_sep; 151 char *grouping; 152 char *int_curr_symbol; 153 char *currency_symbol; 154 char *mon_decimal_point; 155 char *mon_thousands_sep; 156 char *mon_grouping; 157 char *positive_sign; 158 char *negative_sign; 159 char int_frac_digits; 160 char frac_digits; 161 char p_cs_precedes; 162 char p_sep_by_space; 163 char n_cs_precedes; 164 char n_sep_by_space; 165 char p_sign_posn; 166 char n_sign_posn; 167 char int_p_cs_precedes; 168 char int_n_cs_precedes; 169 char int_p_sep_by_space; 170 char int_n_sep_by_space; 171 char int_p_sign_posn; 172 char int_n_sign_posn; 173}; 174.Ed 175.Pp 176The individual fields have the following meanings: 177.Bl -tag -width int_p_sep_by_space 178.It Fa decimal_point 179The decimal point character, except for monetary values. 180.It Fa thousands_sep 181The separator between groups of digits 182before the decimal point, except for monetary values. 183.It Fa grouping 184The sizes of the groups of digits, except for monetary 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 (ISO 4217:1995) international currency symbol. 198.It Fa currency_symbol 199The local currency symbol. 200.It Fa mon_decimal_point 201The decimal point character for monetary values. 202.It Fa mon_thousands_sep 203The separator for digit groups in monetary values. 204.It Fa mon_grouping 205Like 206.Fa grouping 207but for monetary values. 208.It Fa positive_sign 209The character used to denote nonnegative monetary values, 210usually the empty string. 211.It Fa negative_sign 212The character used to denote negative monetary values, 213usually a minus sign. 214.It Fa int_frac_digits 215The number of digits after the decimal point 216in an internationally formatted monetary value. 217.It Fa frac_digits 218The number of digits after the decimal point 219in an locally formatted monetary value. 220.It Fa p_cs_precedes 2211 if the currency symbol precedes the monetary 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 monetary 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 . 239.It Fa n_sign_posn 240Like 241.Fa p_sign_posn 242but for negative currency values. 243.It Fa int_p_cs_precedes 2441 if the currency symbol precedes the internationally 245formatted monetary value for nonnegative values, 0 if it follows. 246.It Fa int_n_cs_precedes 247Like 248.Fa int_p_cs_precedes 249but for negative values. 250.It Fa int_p_sep_by_space 2511 if a space is inserted between the currency symbol 252and the internationally formatted monetary value for 253nonnegative values, 0 otherwise. 254.It Fa int_n_sep_by_space 255Like 256.Fa int_p_sep_by_space 257but for negative values. 258.It Fa int_p_sign_posn 259The location of the 260.Fa positive_sign 261with respect to a nonnegative quantity and the 262.Fa currency_symbol , 263for internationally formatted nonnegative monetary values. 264.It Fa int_n_sign_posn 265Like 266.Fa int_p_sign_posn 267but for negative values. 268.El 269.Pp 270The positional parameters in 271.Fa p_sign_posn , 272.Fa n_sign_posn , 273.Fa int_p_sign_posn 274and 275.Fa int_n_sign_posn 276are encoded as follows: 277.Bl -tag -width 3n -compact 278.It Li 0 279Parentheses around the entire string. 280.It Li 1 281Before the string. 282.It Li 2 283After the string. 284.It Li 3 285Just before 286.Fa currency_symbol . 287.It Li 4 288Just after 289.Fa currency_symbol . 290.El 291.Pp 292Unless mentioned above, 293an empty string as a value for a field 294indicates a zero length result or 295a value that is not in the current locale. 296A 297.Dv CHAR_MAX 298result similarly denotes an unavailable value. 299.Sh RETURN VALUES 300The 301.Fn setlocale 302function returns 303.Dv NULL 304and fails to change the locale 305if the given combination of 306.Fa category 307and 308.Fa locale 309makes no sense. 310The 311.Fn localeconv 312function returns a pointer to a static object 313which may be altered by later calls to 314.Fn setlocale 315or 316.Fn localeconv . 317.Pp 318Currently, 319.Fn setlocale 320returns 321.Dv NULL 322and fails to change the locale when 323.Dv LC_COLLATE 324is modified independently of other values. 325.Sh EXAMPLES 326The following code illustrates how a program can initialize the 327international environment for one language, while selectively 328modifying the program's locale such that regular expressions and 329string operations can be applied to text recorded in a different 330language: 331.Bd -literal 332 setlocale(LC_ALL, "de"); 333 setlocale(LC_NUMERIC, "C"); 334.Ed 335.Pp 336When a process is started, its current locale is set to the C or POSIX 337locale. 338An internationalized program that depends on locale data not defined in 339the C or POSIX locale must invoke the setlocale subroutine in the 340following manner before using any of the locale-specific information: 341.Bd -literal 342 setlocale(LC_ALL, ""); 343.Ed 344.Sh FILES 345The use of multibyte locales requires shared libraries located in 346.Pa /usr/lib/i18n . 347.\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX 348.\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX 349.\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX 350.\" locale file for the locale \fIlocale\fP XXX 351.\" and the category \fIcategory\fP. XXX 352.\" .El 353.Sh SEE ALSO 354.Xr catopen 3 , 355.Xr gettext 3 , 356.Xr nl_langinfo 3 , 357.Xr nls 7 358.\" .Xr strcoll 3 , XXX 359.\" .Xr strxfrm 3 XXX 360.Sh STANDARDS 361The 362.Fn setlocale 363and 364.Fn localeconv 365functions conform to 366.St -ansiC 367and 368.St -isoC-90 . 369.Pp 370The 371.Fa int_p_cs_precedes , 372.Fa int_n_cs_precedes , 373.Fa int_p_sep_by_space , 374.Fa int_n_sep_by_space , 375.Fa int_p_sign_posn 376and 377.Fa int_n_sign_posn 378members of 379.Ft struct lconv 380were introduced in 381.St -isoC-99 . 382.Sh HISTORY 383The 384.Fn setlocale 385and 386.Fn localeconv 387functions first appeared in 388.Bx 4.4 . 389.Sh BUGS 390In spite of the gnarly currency support in 391.Fn localeconv , 392the standards don't include any functions 393for generalized currency formatting. 394.Pp 395.Dv LC_COLLATE 396is unimplemented (but does not make sense for many languages). 397Use of 398.Dv LC_MONETARY 399could lead to misleading results until we have a real time currency 400conversion function. 401.Dv LC_NUMERIC 402and 403.Dv LC_TIME 404are personal choices and should not be wrapped up with the other categories. 405.Pp 406Multibyte locales aren't supported for static binaries. 407