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.1 (Berkeley) 03/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 55and 56.Xr multibyte 3 57functions. 58This controls recognition of upper and lower case, 59alphabetic or non-alphabetic characters, 60and so on. 61.It Dv LC_MONETARY 62Set a locale for formatting monetary values; 63this affects the 64.Fn localeconv 65function. 66.It Dv LC_NUMERIC 67Set a locale for formatting numbers. 68This controls the formatting of decimal points 69in input and output of floating point numbers 70in functions such as 71.Fn printf 72and 73.Fn scanf , 74as well as values returned by 75.Fn localeconv . 76.It Dv LC_TIME 77Set a locale for formatting dates and times using the 78.Fn strftime 79function. 80.El 81.Pp 82Only two locales are defined by default, 83the empty string 84.Li "\&""\|"" 85which denotes the native environment, and the 86.Li "\&""C"" 87locale, which denotes the C language environment. 88A 89.Fa locale 90argument of 91.Dv NULL 92causes 93.Fn setlocale 94to return the current locale. 95By default, C programs start in the 96.Li "\&""C"" 97locale. 98The only function in the library that sets the locale is 99.Fn setlocale ; 100the locale is never changed as a side effect of some other routine. 101.Pp 102The 103.Fn localeconv 104function returns a pointer to a structure 105which provides parameters for formatting numbers, 106especially currency values: 107.Bd -literal -offset indent 108struct lconv { 109 char *decimal_point; 110 char *thousands_sep; 111 char *grouping; 112 char *int_curr_symbol; 113 char *currency_symbol; 114 char *mon_decimal_point; 115 char *mon_thousands_sep; 116 char *mon_grouping; 117 char *positive_sign; 118 char *negative_sign; 119 char int_frac_digits; 120 char frac_digits; 121 char p_cs_precedes; 122 char p_sep_by_space; 123 char n_cs_precedes; 124 char n_sep_by_space; 125 char p_sign_posn; 126 char n_sign_posn; 127}; 128.Ed 129.Pp 130The individual fields have the following meanings: 131.Pp 132.Bl -tag -width mon_decimal_point 133.It Fa decimal_point 134The decimal point character, except for currency values. 135.It Fa thousands_sep 136The separator between groups of digits 137before the decimal point, except for currency values. 138.It Fa grouping 139The sizes of the groups of digits, except for currency values. 140This is a pointer to a vector of integers, each of size 141.Va char , 142representing group size from low order digit groups 143to high order (right to left). 144The list may be terminated with 0 or 145.Dv CHAR_MAX . 146If the list is terminated with 0, 147the last group size before the 0 is repeated to account for all the digits. 148If the list is terminated with 149.Dv CHAR_MAX , 150no more grouping is performed. 151.It Fa int_curr_symbol 152The standardized international currency symbol. 153.It Fa currency_symbol 154The local currency symbol. 155.It Fa mon_decimal_point 156The decimal point character for currency values. 157.It Fa mon_thousands_sep 158The separator for digit groups in currency values. 159.It Fa mon_grouping 160Like 161.Fa grouping 162but for currency values. 163.It Fa positive_sign 164The character used to denote nonnegative currency values, 165usually the empty string. 166.It Fa negative_sign 167The character used to denote negative currency values, 168usually a minus sign. 169.It Fa int_frac_digits 170The number of digits after the decimal point 171in an international-style currency value. 172.It Fa frac_digits 173The number of digits after the decimal point 174in the local style for currency values. 175.It Fa p_cs_precedes 1761 if the currency symbol precedes the currency value 177for nonnegative values, 0 if it follows. 178.It Fa p_sep_by_space 1791 if a space is inserted between the currency symbol 180and the currency value for nonnegative values, 0 otherwise. 181.It Fa n_cs_precedes 182Like 183.Fa p_cs_precedes 184but for negative values. 185.It Fa n_sep_by_space 186Like 187.Fa p_sep_by_space 188but for negative values. 189.It Fa p_sign_posn 190The location of the 191.Fa positive_sign 192with respect to a nonnegative quantity and the 193.Fa currency_symbol , 194coded as follows: 195.Bl -tag -width 3n -compact 196.It Li 0 197Parentheses around the entire string. 198.It Li 1 199Before the string. 200.It Li 2 201After the string. 202.It Li 3 203Just before 204.Fa currency_symbol . 205.It Li 4 206Just after 207.Fa currency_symbol . 208.El 209.It Fa n_sign_posn 210Like 211.Fa p_sign_posn 212but for negative currency values. 213.El 214.Pp 215Unless mentioned above, 216an empty string as a value for a field 217indicates a zero length result or 218a value that is not in the current locale. 219A 220.Dv CHAR_MAX 221result similarly denotes an unavailable value. 222.Sh "RETURN VALUES 223The 224.Fn setlocale 225function returns 226.Dv NULL 227and fails to change the locale 228if the given combination of 229.Fa category 230and 231.Fa locale 232makes no sense. 233The 234.Fn localeconv 235function returns a pointer to a static object 236which may be altered by later calls to 237.Fn setlocale 238or 239.Fn localeconv . 240.Sh "SEE ALSO 241.Xr multibyte 3 , 242.Xr strcoll 3 , 243.Xr strxfrm 3 244.Sh STANDARDS 245The 246.Fn setlocale 247and 248.Fn localeconv 249functions conform to 250.St -ansiC . 251.Sh HISTORY 252The 253.Fn setlocale 254and 255.Fn localeconv 256functions are 257.Ud 258.Sh BUGS 259The current implementation supports only the 260.Li "\&""C"" 261locale. 262Categories and environment variables are ignored. 263.Pp 264In spite of the gnarly currency support in 265.Fn localeconv , 266the standards don't include any functions 267for generalized currency formatting. 268