1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Donn Seeley at BSDI. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93 36.\" $FreeBSD$ 37.\" 38.Dd June 9, 1993 39.Dt SETLOCALE 3 40.Os 41.Sh NAME 42.Nm setlocale , 43.Nm localeconv 44.Nd natural language formatting for C 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In locale.h 49.Ft char * 50.Fn setlocale "int category" "const char *locale" 51.Ft struct lconv * 52.Fn localeconv "void" 53.Sh DESCRIPTION 54The 55.Fn setlocale 56function sets the C library's notion 57of natural language formatting style 58for particular sets of routines. 59Each such style is called a 60.Sq locale 61and is invoked using an appropriate name passed as a C string. 62The 63.Fn localeconv 64routine returns the current locale's parameters 65for formatting numbers. 66.Pp 67The 68.Fn setlocale 69function recognizes several categories of routines. 70These are the categories and the sets of routines they select: 71.Pp 72.Bl -tag -width LC_MONETARY 73.It Dv LC_ALL 74Set the entire locale generically. 75.It Dv LC_COLLATE 76Set a locale for string collation routines. 77This controls alphabetic ordering in 78.Fn strcoll 79and 80.Fn strxfrm . 81.It Dv LC_CTYPE 82Set a locale for the 83.Xr ctype 3 , 84.Xr mbrune 3 , 85.Xr multibyte 3 86and 87.Xr rune 3 88functions. 89This controls recognition of upper and lower case, 90alphabetic or non-alphabetic characters, 91and so on. The real work is done by the 92.Fn setrunelocale 93function. 94.It Dv LC_MESSAGES 95Set a locale for message catalogs, see 96.Xr catopen 3 97function. 98.It Dv LC_MONETARY 99Set a locale for formatting monetary values; 100this affects the 101.Fn localeconv 102function. 103.It Dv LC_NUMERIC 104Set a locale for formatting numbers. 105This controls the formatting of decimal points 106in input and output of floating point numbers 107in functions such as 108.Fn printf 109and 110.Fn scanf , 111as well as values returned by 112.Fn localeconv . 113.It Dv LC_TIME 114Set a locale for formatting dates and times using the 115.Fn strftime 116function. 117.El 118.Pp 119Only three locales are defined by default, 120the empty string 121.Li "\&""\|"" 122which denotes the native environment, and the 123.Li "\&""C"" 124and 125.Li "\&""POSIX"" 126locales, which denote the C language environment. 127A 128.Fa locale 129argument of 130.Dv NULL 131causes 132.Fn setlocale 133to return the current locale. 134By default, C programs start in the 135.Li "\&""C"" 136locale. 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 141The 142.Fn localeconv 143function returns a pointer to a structure 144which provides parameters for formatting numbers, 145especially currency values: 146.Bd -literal -offset indent 147struct lconv { 148 char *decimal_point; 149 char *thousands_sep; 150 char *grouping; 151 char *int_curr_symbol; 152 char *currency_symbol; 153 char *mon_decimal_point; 154 char *mon_thousands_sep; 155 char *mon_grouping; 156 char *positive_sign; 157 char *negative_sign; 158 char int_frac_digits; 159 char frac_digits; 160 char p_cs_precedes; 161 char p_sep_by_space; 162 char n_cs_precedes; 163 char n_sep_by_space; 164 char p_sign_posn; 165 char n_sign_posn; 166}; 167.Ed 168.Pp 169The individual fields have the following meanings: 170.Pp 171.Bl -tag -width mon_decimal_point 172.It Fa decimal_point 173The decimal point character, except for currency values. 174.It Fa thousands_sep 175The separator between groups of digits 176before the decimal point, except for currency values. 177.It Fa grouping 178The sizes of the groups of digits, except for currency values. 179This is a pointer to a vector of integers, each of size 180.Va char , 181representing group size from low order digit groups 182to high order (right to left). 183The list may be terminated with 0 or 184.Dv CHAR_MAX . 185If the list is terminated with 0, 186the last group size before the 0 is repeated to account for all the digits. 187If the list is terminated with 188.Dv CHAR_MAX , 189no more grouping is performed. 190.It Fa int_curr_symbol 191The standardized international currency symbol. 192.It Fa currency_symbol 193The local currency symbol. 194.It Fa mon_decimal_point 195The decimal point character for currency values. 196.It Fa mon_thousands_sep 197The separator for digit groups in currency values. 198.It Fa mon_grouping 199Like 200.Fa grouping 201but for currency values. 202.It Fa positive_sign 203The character used to denote nonnegative currency values, 204usually the empty string. 205.It Fa negative_sign 206The character used to denote negative currency values, 207usually a minus sign. 208.It Fa int_frac_digits 209The number of digits after the decimal point 210in an international-style currency value. 211.It Fa frac_digits 212The number of digits after the decimal point 213in the local style for currency values. 214.It Fa p_cs_precedes 2151 if the currency symbol precedes the currency value 216for nonnegative values, 0 if it follows. 217.It Fa p_sep_by_space 2181 if a space is inserted between the currency symbol 219and the currency value for nonnegative values, 0 otherwise. 220.It Fa n_cs_precedes 221Like 222.Fa p_cs_precedes 223but for negative values. 224.It Fa n_sep_by_space 225Like 226.Fa p_sep_by_space 227but for negative values. 228.It Fa p_sign_posn 229The location of the 230.Fa positive_sign 231with respect to a nonnegative quantity and the 232.Fa currency_symbol , 233coded as follows: 234.Bl -tag -width 3n -compact 235.It Li 0 236Parentheses around the entire string. 237.It Li 1 238Before the string. 239.It Li 2 240After the string. 241.It Li 3 242Just before 243.Fa currency_symbol . 244.It Li 4 245Just after 246.Fa currency_symbol . 247.El 248.It Fa n_sign_posn 249Like 250.Fa p_sign_posn 251but for negative currency values. 252.El 253.Pp 254Unless mentioned above, 255an empty string as a value for a field 256indicates a zero length result or 257a value that is not in the current locale. 258A 259.Dv CHAR_MAX 260result similarly denotes an unavailable value. 261.Sh RETURN VALUES 262Upon successful completion, 263.Fn setlocale 264returns the string associated with the specified 265.Fa category 266for the requested 267.Fa locale . 268The 269.Fn setlocale 270function returns 271.Dv NULL 272and fails to change the locale 273if the given combination of 274.Fa category 275and 276.Fa locale 277makes no sense. 278The 279.Fn localeconv 280function returns a pointer to a static object 281which may be altered by later calls to 282.Fn setlocale 283or 284.Fn localeconv . 285.Sh FILES 286.Bl -tag -width /usr/share/locale/locale/category -compact 287.It Pa $PATH_LOCALE/ Ns Em locale/category 288.It Pa /usr/share/locale/ Ns Em locale/category 289locale file for the locale 290.Em locale 291and the category 292.Em category . 293.El 294.Sh SEE ALSO 295.Xr colldef 1 , 296.Xr mklocale 1 , 297.Xr catopen 3 , 298.Xr ctype 3 , 299.Xr mbrune 3 , 300.Xr multibyte 3 , 301.Xr rune 3 , 302.Xr strcoll 3 , 303.Xr strxfrm 3 , 304.Xr euc 4 , 305.Xr utf2 4 306.Sh STANDARDS 307The 308.Fn setlocale 309and 310.Fn localeconv 311functions conform to 312.St -isoC . 313.Sh HISTORY 314The 315.Fn setlocale 316and 317.Fn localeconv 318functions first appeared in 319.Bx 4.4 . 320