lib/libc/locale/setlocale.3

   1 .\"     $NetBSD: src/lib/libc/locale/setlocale.3,v 1.21 2004/01/24 16:58:54 wiz Exp $
   2 .\"     $DragonFly: src/lib/libc/locale/setlocale.3,v 1.3 2005/03/12 00:18:01 joerg Exp $
   3 .\"
   4 .\" Copyright (c) 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to Berkeley by
   8 .\" Donn Seeley at BSDI.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)setlocale.3 8.1 (Berkeley) 6/9/93
  35 .\"
  36 .Dd May 30, 2003
  37 .Dt SETLOCALE 3
  38 .Os
  39 .Sh NAME
  40 .Nm setlocale ,
  41 .Nm localeconv
  42 .Nd natural language formatting for C
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In locale.h
  47 .Ft char *
  48 .Fn setlocale "int category" "const char *locale"
  49 .Ft struct lconv *
  50 .Fn localeconv "void"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn setlocale
  54 function sets the C library's notion
  55 of natural language formatting style
  56 for particular sets of routines.
  57 Each such style is called a
  58 .Sq locale
  59 and is invoked using an appropriate name passed as a C string.
  60 The
  61 .Fn localeconv
  62 routine returns the current locale's parameters
  63 for formatting numbers.
  64 .Pp
  65 The
  66 .Fn setlocale
  67 function recognizes several categories of routines.
  68 These are the categories and the sets of routines they select:
  69 .Bl -tag -width LC_MONETARY
  70 .It Dv LC_ALL
  71 Set the entire locale generically.
  72 .It Dv LC_COLLATE
  73 Set a locale for string collation routines.
  74 This controls alphabetic ordering in
  75 .Fn strcoll
  76 and
  77 .Fn strxfrm .
  78 .It Dv LC_CTYPE
  79 Set a locale for the
  80 .Xr ctype 3
  81 functions.
  82 This controls recognition of upper and lower case,
  83 alphabetic or non-alphabetic characters,
  84 and so on.
  85 The real work is done by the
  86 .Fn setrunelocale
  87 function.
  88 .It Dv LC_MESSAGES
  89 Set a locale for message catalogs.
  90 This controls the selection of message catalogs by the
  91 .Xr catgets 3
  92 and
  93 .Xr gettext 3
  94 families of functions.
  95 .It Dv LC_MONETARY
  96 Set a locale for formatting monetary values;
  97 this affects the
  98 .Fn localeconv
  99 function.
 100 .It Dv LC_NUMERIC
 101 Set a locale for formatting numbers.
 102 This controls the formatting of decimal points
 103 in input and output of floating point numbers
 104 in functions such as
 105 .Fn printf
 106 and
 107 .Fn scanf ,
 108 as well as values returned by
 109 .Fn localeconv .
 110 .It Dv LC_TIME
 111 Set a locale for formatting dates and times using the
 112 .Fn strftime
 113 function.
 114 .El
 115 .Pp
 116 Only three locales are defined by default,
 117 the empty string
 118 .Li "\&""\|""
 119 which denotes the native environment, and the
 120 .Li "\&""C""
 121 and
 122 .Li "\&""POSIX""
 123 locales, which denote the C language environment.
 124 A
 125 .Fa locale
 126 argument of
 127 .Dv NULL
 128 causes
 129 .Fn setlocale
 130 to return the current locale.
 131 By default, C programs start in the
 132 .Li "\&""C""
 133 locale.
 134 The format of the locale string is described in
 135 .Xr nls 7 .
 136 .Pp
 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 Changing the setting of
 142 .Dv LC_MESSAGES
 143 has no effect on catalogs that have already been opened by
 144 .Xr catopen 3 .
 145 .Pp
 146 The
 147 .Fn localeconv
 148 function returns a pointer to a structure
 149 which provides parameters for formatting numbers,
 150 especially currency values:
 151 .Bd -literal -offset indent
 152 struct lconv {
 153         char    *decimal_point;
 154         char    *thousands_sep;
 155         char    *grouping;
 156         char    *int_curr_symbol;
 157         char    *currency_symbol;
 158         char    *mon_decimal_point;
 159         char    *mon_thousands_sep;
 160         char    *mon_grouping;
 161         char    *positive_sign;
 162         char    *negative_sign;
 163         char    int_frac_digits;
 164         char    frac_digits;
 165         char    p_cs_precedes;
 166         char    p_sep_by_space;
 167         char    n_cs_precedes;
 168         char    n_sep_by_space;
 169         char    p_sign_posn;
 170         char    n_sign_posn;
 171         char    int_p_cs_precedes;
 172         char    int_n_cs_precedes;
 173         char    int_p_sep_by_space;
 174         char    int_n_sep_by_space;
 175         char    int_p_sign_posn;
 176         char    int_n_sign_posn;
 177 };
 178 .Ed
 179 .Pp
 180 The individual fields have the following meanings:
 181 .Bl -tag -width int_p_sep_by_space
 182 .It Fa decimal_point
 183 The decimal point character, except for monetary values.
 184 .It Fa thousands_sep
 185 The separator between groups of digits
 186 before the decimal point, except for monetary values.
 187 .It Fa grouping
 188 The sizes of the groups of digits, except for monetary values.
 189 This is a pointer to a vector of integers, each of size
 190 .Va char ,
 191 representing group size from low order digit groups
 192 to high order (right to left).
 193 The list may be terminated with 0 or
 194 .Dv CHAR_MAX .
 195 If the list is terminated with 0,
 196 the last group size before the 0 is repeated to account for all the digits.
 197 If the list is terminated with
 198 .Dv CHAR_MAX ,
 199 no more grouping is performed.
 200 .It Fa int_curr_symbol
 201 The standardized (ISO 4217:1995) international currency symbol.
 202 .It Fa currency_symbol
 203 The local currency symbol.
 204 .It Fa mon_decimal_point
 205 The decimal point character for monetary values.
 206 .It Fa mon_thousands_sep
 207 The separator for digit groups in monetary values.
 208 .It Fa mon_grouping
 209 Like
 210 .Fa grouping
 211 but for monetary values.
 212 .It Fa positive_sign
 213 The character used to denote nonnegative monetary values,
 214 usually the empty string.
 215 .It Fa negative_sign
 216 The character used to denote negative monetary values,
 217 usually a minus sign.
 218 .It Fa int_frac_digits
 219 The number of digits after the decimal point
 220 in an internationally formatted monetary value.
 221 .It Fa frac_digits
 222 The number of digits after the decimal point
 223 in an locally formatted monetary value.
 224 .It Fa p_cs_precedes
 225 1 if the currency symbol precedes the monetary value
 226 for nonnegative values, 0 if it follows.
 227 .It Fa p_sep_by_space
 228 1 if a space is inserted between the currency symbol
 229 and the monetary value for nonnegative values, 0 otherwise.
 230 .It Fa n_cs_precedes
 231 Like
 232 .Fa p_cs_precedes
 233 but for negative values.
 234 .It Fa n_sep_by_space
 235 Like
 236 .Fa p_sep_by_space
 237 but for negative values.
 238 .It Fa p_sign_posn
 239 The location of the
 240 .Fa positive_sign
 241 with respect to a nonnegative quantity and the
 242 .Fa currency_symbol .
 243 .It Fa n_sign_posn
 244 Like
 245 .Fa p_sign_posn
 246 but for negative currency values.
 247 .It Fa int_p_cs_precedes
 248 1 if the currency symbol precedes the internationally
 249 formatted monetary value for nonnegative values, 0 if it follows.
 250 .It Fa int_n_cs_precedes
 251 Like
 252 .Fa int_p_cs_precedes
 253 but for negative values.
 254 .It Fa int_p_sep_by_space
 255 1 if a space is inserted between the currency symbol
 256 and the internationally formatted monetary value for
 257 nonnegative values, 0 otherwise.
 258 .It Fa int_n_sep_by_space
 259 Like
 260 .Fa int_p_sep_by_space
 261 but for negative values.
 262 .It Fa int_p_sign_posn
 263 The location of the
 264 .Fa positive_sign
 265 with respect to a nonnegative quantity and the
 266 .Fa currency_symbol ,
 267 for internationally formatted nonnegative monetary values.
 268 .It Fa int_n_sign_posn
 269 Like
 270 .Fa int_p_sign_posn
 271 but for negative values.
 272 .El
 273 .Pp
 274 The positional parameters in
 275 .Fa p_sign_posn ,
 276 .Fa n_sign_posn ,
 277 .Fa int_p_sign_posn
 278 and
 279 .Fa int_n_sign_posn
 280 are encoded as follows:
 281 .Bl -tag -width 3n -compact
 282 .It Li 0
 283 Parentheses around the entire string.
 284 .It Li 1
 285 Before the string.
 286 .It Li 2
 287 After the string.
 288 .It Li 3
 289 Just before
 290 .Fa currency_symbol .
 291 .It Li 4
 292 Just after
 293 .Fa currency_symbol .
 294 .El
 295 .Pp
 296 Unless mentioned above,
 297 an empty string as a value for a field
 298 indicates a zero length result or
 299 a value that is not in the current locale.
 300 A
 301 .Dv CHAR_MAX
 302 result similarly denotes an unavailable value.
 303 .Sh RETURN VALUES
 304 The
 305 .Fn setlocale
 306 function returns
 307 .Dv NULL
 308 and fails to change the locale
 309 if the given combination of
 310 .Fa category
 311 and
 312 .Fa locale
 313 makes no sense.
 314 The
 315 .Fn localeconv
 316 function returns a pointer to a static object
 317 which may be altered by later calls to
 318 .Fn setlocale
 319 or
 320 .Fn localeconv .
 321 .Sh EXAMPLES
 322 The following code illustrates how a program can initialize the
 323 international environment for one language, while selectively
 324 modifying the program's locale such that regular expressions and
 325 string operations can be applied to text recorded in a different
 326 language:
 327 .Bd -literal
 328         setlocale(LC_ALL, "de");
 329         setlocale(LC_COLLATE, "fr");
 330 .Ed
 331 .Pp
 332 When a process is started, its current locale is set to the C or POSIX
 333 locale.
 334 An internationalized program that depends on locale data not defined in
 335 the C or POSIX locale must invoke the setlocale subroutine in the
 336 following manner before using any of the locale-specific information:
 337 .Bd -literal
 338         setlocale(LC_ALL, "");
 339 .Ed
 340 .\" .Sh FILES                                                   XXX
 341 .\" .Bl -tag -width /usr/share/locale/locale/category -compact  XXX
 342 .\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP             XXX
 343 .\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP        XXX
 344 .\" locale file for the locale \fIlocale\fP                     XXX
 345 .\" and the category \fIcategory\fP.                            XXX
 346 .\" .El
 347 .Sh SEE ALSO
 348 .Xr catopen 3 ,
 349 .Xr gettext 3 ,
 350 .Xr nl_langinfo 3 ,
 351 .Xr nls 7
 352 .\" .Xr strcoll 3 ,                                             XXX
 353 .\" .Xr strxfrm 3                                               XXX
 354 .Sh STANDARDS
 355 The
 356 .Fn setlocale
 357 and
 358 .Fn localeconv
 359 functions conform to
 360 .St -ansiC
 361 and
 362 .St -isoC-90 .
 363 .Pp
 364 The
 365 .Fa int_p_cs_precedes ,
 366 .Fa int_n_cs_precedes ,
 367 .Fa int_p_sep_by_space ,
 368 .Fa int_n_sep_by_space ,
 369 .Fa int_p_sign_posn
 370 and
 371 .Fa int_n_sign_posn
 372 members of
 373 .Ft struct lconv
 374 were introduced in
 375 .St -isoC-99 .
 376 .Sh HISTORY
 377 The
 378 .Fn setlocale
 379 and
 380 .Fn localeconv
 381 functions first appeared in
 382 .Bx 4.4 .
 383 .Sh BUGS
 384 The current implementation supports only the
 385 .Li "\&""C""
 386 and
 387 .Li "\&""POSIX""
 388 locales for all but the
 389 .Dv LC_CTYPE
 390 locale.
 391 .Pp
 392 In spite of the gnarly currency support in
 393 .Fn localeconv ,
 394 the standards don't include any functions
 395 for generalized currency formatting.
 396 .Pp
 397 .Dv LC_COLLATE
 398 does not make sense for many languages.
 399 Use of
 400 .Dv LC_MONETARY
 401 could lead to misleading results until we have a real time currency
 402 conversion function.
 403 .Dv LC_NUMERIC
 404 and
 405 .Dv LC_TIME
 406 are personal choices and should not be wrapped up with the other categories.
 407 .Pp
 408 Multibyte locales aren't supported for static binaries.