locale/setlocale.3

   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: src/lib/libc/locale/setlocale.3,v 1.15.2.5 2001/12/14 18:33:55 ru Exp $
  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
  54 The
  55 .Fn setlocale
  56 function sets the C library's notion
  57 of natural language formatting style
  58 for particular sets of routines.
  59 Each such style is called a
  60 .Sq locale
  61 and is invoked using an appropriate name passed as a C string.
  62 The
  63 .Fn localeconv
  64 routine returns the current locale's parameters
  65 for formatting numbers.
  66 .Pp
  67 The
  68 .Fn setlocale
  69 function recognizes several categories of routines.
  70 These are the categories and the sets of routines they select:
  71 .Pp
  72 .Bl -tag -width LC_MONETARY
  73 .It Dv LC_ALL
  74 Set the entire locale generically.
  75 .It Dv LC_COLLATE
  76 Set a locale for string collation routines.
  77 This controls alphabetic ordering in
  78 .Fn strcoll
  79 and
  80 .Fn strxfrm .
  81 .It Dv LC_CTYPE
  82 Set a locale for the
  83 .Xr ctype 3 ,
  84 .Xr mbrune 3 ,
  85 .Xr multibyte 3
  86 and
  87 .Xr rune 3
  88 functions.
  89 This controls recognition of upper and lower case,
  90 alphabetic or non-alphabetic characters,
  91 and so on.  The real work is done by the
  92 .Fn setrunelocale
  93 function.
  94 .It Dv LC_MESSAGES
  95 Set a locale for message catalogs, see
  96 .Xr catopen 3
  97 function.
  98 .It Dv LC_MONETARY
  99 Set a locale for formatting monetary values;
 100 this affects the
 101 .Fn localeconv
 102 function.
 103 .It Dv LC_NUMERIC
 104 Set a locale for formatting numbers.
 105 This controls the formatting of decimal points
 106 in input and output of floating point numbers
 107 in functions such as
 108 .Fn printf
 109 and
 110 .Fn scanf ,
 111 as well as values returned by
 112 .Fn localeconv .
 113 .It Dv LC_TIME
 114 Set a locale for formatting dates and times using the
 115 .Fn strftime
 116 function.
 117 .El
 118 .Pp
 119 Only three locales are defined by default,
 120 the empty string
 121 .Li "\&""\|""
 122 which denotes the native environment, and the
 123 .Li "\&""C""
 124 and
 125 .Li "\&""POSIX""
 126 locales, which denote the C language environment.
 127 A
 128 .Fa locale
 129 argument of
 130 .Dv NULL
 131 causes
 132 .Fn setlocale
 133 to return the current locale.
 134 By default, C programs start in the
 135 .Li "\&""C""
 136 locale.
 137 The only function in the library that sets the locale is
 138 .Fn setlocale ;
 139 the locale is never changed as a side effect of some other routine.
 140 .Pp
 141 The
 142 .Fn localeconv
 143 function returns a pointer to a structure
 144 which provides parameters for formatting numbers,
 145 especially currency values:
 146 .Bd -literal -offset indent
 147 struct 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
 169 The individual fields have the following meanings:
 170 .Pp
 171 .Bl -tag -width mon_decimal_point
 172 .It Fa decimal_point
 173 The decimal point character, except for currency values.
 174 .It Fa thousands_sep
 175 The separator between groups of digits
 176 before the decimal point, except for currency values.
 177 .It Fa grouping
 178 The sizes of the groups of digits, except for currency values.
 179 This is a pointer to a vector of integers, each of size
 180 .Va char ,
 181 representing group size from low order digit groups
 182 to high order (right to left).
 183 The list may be terminated with 0 or
 184 .Dv CHAR_MAX .
 185 If the list is terminated with 0,
 186 the last group size before the 0 is repeated to account for all the digits.
 187 If the list is terminated with
 188 .Dv CHAR_MAX ,
 189 no more grouping is performed.
 190 .It Fa int_curr_symbol
 191 The standardized international currency symbol.
 192 .It Fa currency_symbol
 193 The local currency symbol.
 194 .It Fa mon_decimal_point
 195 The decimal point character for currency values.
 196 .It Fa mon_thousands_sep
 197 The separator for digit groups in currency values.
 198 .It Fa mon_grouping
 199 Like
 200 .Fa grouping
 201 but for currency values.
 202 .It Fa positive_sign
 203 The character used to denote nonnegative currency values,
 204 usually the empty string.
 205 .It Fa negative_sign
 206 The character used to denote negative currency values,
 207 usually a minus sign.
 208 .It Fa int_frac_digits
 209 The number of digits after the decimal point
 210 in an international-style currency value.
 211 .It Fa frac_digits
 212 The number of digits after the decimal point
 213 in the local style for currency values.
 214 .It Fa p_cs_precedes
 215 1 if the currency symbol precedes the currency value
 216 for nonnegative values, 0 if it follows.
 217 .It Fa p_sep_by_space
 218 1 if a space is inserted between the currency symbol
 219 and the currency value for nonnegative values, 0 otherwise.
 220 .It Fa n_cs_precedes
 221 Like
 222 .Fa p_cs_precedes
 223 but for negative values.
 224 .It Fa n_sep_by_space
 225 Like
 226 .Fa p_sep_by_space
 227 but for negative values.
 228 .It Fa p_sign_posn
 229 The location of the
 230 .Fa positive_sign
 231 with respect to a nonnegative quantity and the
 232 .Fa currency_symbol ,
 233 coded as follows:
 234 .Bl -tag -width 3n -compact
 235 .It Li 0
 236 Parentheses around the entire string.
 237 .It Li 1
 238 Before the string.
 239 .It Li 2
 240 After the string.
 241 .It Li 3
 242 Just before
 243 .Fa currency_symbol .
 244 .It Li 4
 245 Just after
 246 .Fa currency_symbol .
 247 .El
 248 .It Fa n_sign_posn
 249 Like
 250 .Fa p_sign_posn
 251 but for negative currency values.
 252 .El
 253 .Pp
 254 Unless mentioned above,
 255 an empty string as a value for a field
 256 indicates a zero length result or
 257 a value that is not in the current locale.
 258 A
 259 .Dv CHAR_MAX
 260 result similarly denotes an unavailable value.
 261 .Sh RETURN VALUES
 262 The
 263 .Fn setlocale
 264 function returns
 265 .Dv NULL
 266 and fails to change the locale
 267 if the given combination of
 268 .Fa category
 269 and
 270 .Fa locale
 271 makes no sense.
 272 The
 273 .Fn localeconv
 274 function returns a pointer to a static object
 275 which may be altered by later calls to
 276 .Fn setlocale
 277 or
 278 .Fn localeconv .
 279 .Sh FILES
 280 .Bl -tag -width /usr/share/locale/locale/category -compact
 281 .It Pa $PATH_LOCALE/ Ns Em locale/category
 282 .It Pa /usr/share/locale/ Ns Em locale/category
 283 locale file for the locale
 284 .Em locale
 285 and the category
 286 .Em category .
 287 .El
 288 .Sh SEE ALSO
 289 .Xr colldef 1 ,
 290 .Xr mklocale 1 ,
 291 .Xr catopen 3 ,
 292 .Xr ctype 3 ,
 293 .Xr mbrune 3 ,
 294 .Xr multibyte 3 ,
 295 .Xr rune 3 ,
 296 .Xr strcoll 3 ,
 297 .Xr strxfrm 3 ,
 298 .Xr euc 4 ,
 299 .Xr utf2 4
 300 .Sh STANDARDS
 301 The
 302 .Fn setlocale
 303 and
 304 .Fn localeconv
 305 functions conform to
 306 .St -isoC .
 307 .Sh HISTORY
 308 The
 309 .Fn setlocale
 310 and
 311 .Fn localeconv
 312 functions first appeared in
 313 .Bx 4.4 .
 314 .Sh BUGS
 315 The current implementation supports only the
 316 .Li "\&""C""
 317 and
 318 .Li "\&""POSIX""
 319 locales for all but the
 320 .Dv LC_COLLATE ,
 321 .Dv LC_CTYPE ,
 322 and
 323 .Dv LC_TIME
 324 categories.
 325 .Pp
 326 In spite of the gnarly currency support in
 327 .Fn localeconv ,
 328 the standards don't include any functions
 329 for generalized currency formatting.
 330 .Pp
 331 Use of
 332 .Dv LC_MONETARY
 333 could lead to misleading results until we have a real time currency
 334 conversion function.
 335 .Dv LC_NUMERIC
 336 and
 337 .Dv LC_TIME
 338 are personal choices and should not be wrapped up with the other categories.