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