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 .\"
  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 Upon successful completion,
 263 .Fn setlocale
 264 returns the string associated with the specified
 265 .Fa category
 266 for the requested
 267 .Fa locale .
 268 The
 269 .Fn setlocale
 270 function returns
 271 .Dv NULL
 272 and fails to change the locale
 273 if the given combination of
 274 .Fa category
 275 and
 276 .Fa locale
 277 makes no sense.
 278 The
 279 .Fn localeconv
 280 function returns a pointer to a static object
 281 which may be altered by later calls to
 282 .Fn setlocale
 283 or
 284 .Fn localeconv .
 285 .Sh ERRORS
 286 No errors are defined.
 287 .Sh FILES
 288 .Bl -tag -width /usr/share/locale/locale/category -compact
 289 .It Pa $PATH_LOCALE/ Ns Em locale/category
 290 .It Pa /usr/share/locale/ Ns Em locale/category
 291 locale file for the locale
 292 .Em locale
 293 and the category
 294 .Em category .
 295 .El
 296 .Sh SEE ALSO
 297 .Xr colldef 1 ,
 298 .Xr mklocale 1 ,
 299 .Xr catopen 3 ,
 300 .Xr ctype 3 ,
 301 .Xr mbrune 3 ,
 302 .Xr multibyte 3 ,
 303 .Xr rune 3 ,
 304 .Xr strcoll 3 ,
 305 .Xr strxfrm 3 ,
 306 .Xr euc 4 ,
 307 .Xr utf2 4
 308 .Sh STANDARDS
 309 The
 310 .Fn setlocale
 311 and
 312 .Fn localeconv
 313 functions conform to
 314 .St -isoC .
 315 .Sh HISTORY
 316 The
 317 .Fn setlocale
 318 and
 319 .Fn localeconv
 320 functions first appeared in
 321 .Bx 4.4 .