1.\" Copyright (c) 1993 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Donn Seeley at BSDI. 6.\" 7.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)setlocale.3 5.2 (Berkeley) 06/02/93 10.\" 11.Dd 12.Dt SETLOCALE 3 13.Os 14.Sh NAME 15.Nm setlocale , 16.Nm localeconv 17.Nd natural language formatting for C 18.Sh SYNOPSIS 19.Fd #include <locale.h> 20.Ft char * 21.Fn setlocale "int category" "const char *locale" 22.Ft struct lconv * 23.Fn localeconv "void" 24.Sh DESCRIPTION 25The 26.Fn setlocale 27function sets the C library's notion 28of natural language formatting style 29for particular sets of routines. 30Each such style is called a 31.Sq locale 32and is invoked using an appropriate name passed as a C string. 33The 34.Fn localeconv 35routine returns the current locale's parameters 36for formatting numbers. 37.Pp 38The 39.Fn setlocale 40function recognizes several categories of routines. 41These are the categories and the sets of routines they select: 42.Pp 43.Bl -tag -width LC_MONETARY 44.It Dv LC_ALL 45Set the entire locale generically. 46.It Dv LC_COLLATE 47Set a locale for string collation routines. 48This controls alphabetic ordering in 49.Fn strcoll 50and 51.Fn strxfrm . 52.It Dv LC_CTYPE 53Set a locale for the 54.Xr ctype 3 , 55.Xr mbrune 3 , 56.Xr multibyte 3 57and 58.Xr rune 3 59functions. 60This controls recognition of upper and lower case, 61alphabetic or non-alphabetic characters, 62and so on. The real work is done by the 63.Fn setrunelocale 64function. 65.It Dv LC_MONETARY 66Set a locale for formatting monetary values; 67this affects the 68.Fn localeconv 69function. 70.It Dv LC_NUMERIC 71Set a locale for formatting numbers. 72This controls the formatting of decimal points 73in input and output of floating point numbers 74in functions such as 75.Fn printf 76and 77.Fn scanf , 78as well as values returned by 79.Fn localeconv . 80.It Dv LC_TIME 81Set a locale for formatting dates and times using the 82.Fn strftime 83function. 84.El 85.Pp 86Only three locales are defined by default, 87the empty string 88.Li "\&""\|"" 89which denotes the native environment, and the 90.Li "\&""C"" 91and 92.LI "\&""POSIX"" 93locales, which denote the C language environment. 94A 95.Fa locale 96argument of 97.Dv NULL 98causes 99.Fn setlocale 100to return the current locale. 101By default, C programs start in the 102.Li "\&""C"" 103locale. 104The only function in the library that sets the locale is 105.Fn setlocale ; 106the locale is never changed as a side effect of some other routine. 107.Pp 108The 109.Fn localeconv 110function returns a pointer to a structure 111which provides parameters for formatting numbers, 112especially currency values: 113.Bd -literal -offset indent 114struct lconv { 115 char *decimal_point; 116 char *thousands_sep; 117 char *grouping; 118 char *int_curr_symbol; 119 char *currency_symbol; 120 char *mon_decimal_point; 121 char *mon_thousands_sep; 122 char *mon_grouping; 123 char *positive_sign; 124 char *negative_sign; 125 char int_frac_digits; 126 char frac_digits; 127 char p_cs_precedes; 128 char p_sep_by_space; 129 char n_cs_precedes; 130 char n_sep_by_space; 131 char p_sign_posn; 132 char n_sign_posn; 133}; 134.Ed 135.Pp 136The individual fields have the following meanings: 137.Pp 138.Bl -tag -width mon_decimal_point 139.It Fa decimal_point 140The decimal point character, except for currency values. 141.It Fa thousands_sep 142The separator between groups of digits 143before the decimal point, except for currency values. 144.It Fa grouping 145The sizes of the groups of digits, except for currency values. 146This is a pointer to a vector of integers, each of size 147.Va char , 148representing group size from low order digit groups 149to high order (right to left). 150The list may be terminated with 0 or 151.Dv CHAR_MAX . 152If the list is terminated with 0, 153the last group size before the 0 is repeated to account for all the digits. 154If the list is terminated with 155.Dv CHAR_MAX , 156no more grouping is performed. 157.It Fa int_curr_symbol 158The standardized international currency symbol. 159.It Fa currency_symbol 160The local currency symbol. 161.It Fa mon_decimal_point 162The decimal point character for currency values. 163.It Fa mon_thousands_sep 164The separator for digit groups in currency values. 165.It Fa mon_grouping 166Like 167.Fa grouping 168but for currency values. 169.It Fa positive_sign 170The character used to denote nonnegative currency values, 171usually the empty string. 172.It Fa negative_sign 173The character used to denote negative currency values, 174usually a minus sign. 175.It Fa int_frac_digits 176The number of digits after the decimal point 177in an international-style currency value. 178.It Fa frac_digits 179The number of digits after the decimal point 180in the local style for currency values. 181.It Fa p_cs_precedes 1821 if the currency symbol precedes the currency value 183for nonnegative values, 0 if it follows. 184.It Fa p_sep_by_space 1851 if a space is inserted between the currency symbol 186and the currency value for nonnegative values, 0 otherwise. 187.It Fa n_cs_precedes 188Like 189.Fa p_cs_precedes 190but for negative values. 191.It Fa n_sep_by_space 192Like 193.Fa p_sep_by_space 194but for negative values. 195.It Fa p_sign_posn 196The location of the 197.Fa positive_sign 198with respect to a nonnegative quantity and the 199.Fa currency_symbol , 200coded as follows: 201.Bl -tag -width 3n -compact 202.It Li 0 203Parentheses around the entire string. 204.It Li 1 205Before the string. 206.It Li 2 207After the string. 208.It Li 3 209Just before 210.Fa currency_symbol . 211.It Li 4 212Just after 213.Fa currency_symbol . 214.El 215.It Fa n_sign_posn 216Like 217.Fa p_sign_posn 218but for negative currency values. 219.El 220.Pp 221Unless mentioned above, 222an empty string as a value for a field 223indicates a zero length result or 224a value that is not in the current locale. 225A 226.Dv CHAR_MAX 227result similarly denotes an unavailable value. 228.Sh "RETURN VALUES 229The 230.Fn setlocale 231function returns 232.Dv NULL 233and fails to change the locale 234if the given combination of 235.Fa category 236and 237.Fa locale 238makes no sense. 239The 240.Fn localeconv 241function returns a pointer to a static object 242which may be altered by later calls to 243.Fn setlocale 244or 245.Fn localeconv . 246.Sh FILES 247.Bl -tag -width /usr/share/locale/locale/category -compact 248.It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP 249.It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP 250locale file for the locale \fIlocale\fP 251and the category \fIcategory\fP. 252.El 253.Sh "SEE ALSO 254.Xr euc 4 , 255.Xr mbrune 3 , 256.Xr multibyte 3 , 257.Xr rune 3 , 258.Xr strcoll 3 , 259.Xr strxfrm 3 , 260.Xr utf2 4 261.Sh STANDARDS 262The 263.Fn setlocale 264and 265.Fn localeconv 266functions conform to 267.St -ansiC . 268.Sh HISTORY 269The 270.Fn setlocale 271and 272.Fn localeconv 273functions are 274.Ud 275.Sh BUGS 276The current implementation supports only the 277.Li "\&""C"" 278and 279.Li "\&""POSIX"" 280locales for all but the LC_CTYPE locale. 281.Pp 282In spite of the gnarly currency support in 283.Fn localeconv , 284the standards don't include any functions 285for generalized currency formatting. 286.Pp 287.Dv LC_COLLATE 288does not make sense for many languages. 289Use of 290.Dv LC_MONETARY 291could lead to misleading results until we have a real time currency 292conversion function. 293.Dv LC_NUMERIC 294and 295.Dv LC_TIME 296are personal choices and should not be wrapped up with the other categories. 297