man7/locale.7

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sat Jul 24 17:28:34 1993 by Rik Faith <faith@cs.unc.edu>
  27 .\" Modified Sun Jun 01 17:16:34 1997 by Jochen Hein
  28 .\"   <jochen.hein@delphi.central.de>
  29 .\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible <bruno@clisp.org>
  30 .\"
  31 .TH LOCALE 7  2014-05-28 "Linux" "Linux Programmer's Manual"
  32 .SH NAME
  33 locale \- description of multilanguage support
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <locale.h>
  37 .fi
  38 .SH DESCRIPTION
  39 A locale is a set of language and cultural rules.
  40 These cover aspects
  41 such as language for messages, different character sets, lexicographic
  42 conventions, and so on.
  43 A program needs to be able to determine its locale
  44 and act accordingly to be portable to different cultures.
  45 .PP
  46 The header
  47 .I <locale.h>
  48 declares data types, functions and macros which are useful in this
  49 task.
  50 .PP
  51 The functions it declares are
  52 .BR setlocale (3)
  53 to set the current locale, and
  54 .BR localeconv (3)
  55 to get information about number formatting.
  56 .PP
  57 There are different categories for locale information a program might
  58 need; they are declared as macros.
  59 Using them as the first argument
  60 to the
  61 .BR setlocale (3)
  62 function, it is possible to set one of these to the desired locale:
  63 .TP
  64 .BR LC_ADDRESS " (GNU extension, since glibc 2.2)"
  65 .\" See ISO/IEC Technical Report 14652
  66 Change settings that describe the formats (e.g., postal addresses)
  67 used to describe locations and geography-related items.
  68 Applications that need this information can use
  69 .BR nl_langinfo (3)
  70 to retrieve nonstandard elements, such as
  71 .B _NL_ADDRESS_COUNTRY_NAME
  72 (country name, in the language of the locale)
  73 and
  74 .B _NL_ADDRESS_LANG_NAME
  75 (language name, in the language of the locale),
  76 which return strings such as "Deutschland" and "Deutsch"
  77 (for German-language locales).
  78 (Other element names are listed in
  79 .IR <langinfo.h> .)
  80 .TP
  81 .B LC_COLLATE
  82 This category governs the collation rules used for
  83 sorting and regular expressions,
  84 including character equivalence classes and
  85 multicharacter collating elements.
  86 This locale category changes the behavior of the functions
  87 .BR strcoll (3)
  88 and
  89 .BR strxfrm (3),
  90 which are used to compare strings in the local alphabet.
  91 For example,
  92 the German sharp s is sorted as "ss".
  93 .TP
  94 .B LC_CTYPE
  95 This category determines the interpretation of byte sequences as characters
  96 (e.g., single versus multibyte characters), character classifications
  97 (e.g., alphabetic or digit), and the behavior of character classes.
  98 It changes the behavior of the character handling and
  99 classification functions, such as
 100 .BR isupper (3)
 101 and
 102 .BR toupper (3),
 103 and the multibyte character functions such as
 104 .BR mblen (3)
 105 or
 106 .BR wctomb (3).
 107 .TP
 108 .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
 109 .\" See ISO/IEC Technical Report 14652
 110 Change settings that relate to the metadata for the locale.
 111 Applications that need this information can use
 112 .BR nl_langinfo (3)
 113 to retrieve nonstandard elements, such as
 114 .B _NL_IDENTIFICATION_TITLE
 115 (title of this locale document)
 116 and
 117 .B _NL_IDENTIFICATION_TERRITORY
 118 (geographical territory to which this locale document applies),
 119 which might return strings such as "English locale for the USA"
 120 and "USA".
 121 (Other element names are listed in
 122 .IR <langinfo.h> .)
 123 .TP
 124 .B LC_MONETARY
 125 This category determines the formatting used for
 126 monetary-related numeric values.
 127 This changes the information returned by
 128 .BR localeconv (3),
 129 which describes the way numbers are usually printed, with details such
 130 as decimal point versus decimal comma.
 131 This information is internally
 132 used by the function
 133 .BR strfmon (3).
 134 .TP
 135 .B LC_MESSAGES
 136 This category affects the language in which messages are displayed
 137 and what an affirmative or negative answer looks like.
 138 The GNU C library contains the
 139 .BR gettext (3),
 140 .BR ngettext (3),
 141 and
 142 .BR rpmatch (3)
 143 functions to ease the use of this information.
 144 The GNU gettext family of
 145 functions also obey the environment variable
 146 .BR LANGUAGE
 147 (containing a colon-separated list of locales)
 148 if the category is set to a valid locale other than
 149 .BR """C""" .
 150 This category also affects the behavior of
 151 .BR catopen (3).
 152 .TP
 153 .BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)"
 154 Change the settings relating to the measurement system in the locale
 155 (i.e., metric versus US customary units).
 156 Applications can use
 157 .BR nl_langinfo (3)
 158 to retrieve the nonstandard
 159 .B _NL_MEASUREMENT_MEASUREMENT
 160 element, which returns a pointer to a character
 161 that has the value 1 (metric) or 2 (US customary units).
 162 .TP
 163 .BR LC_NAME " (GNU extension, since glibc 2.2)"
 164 .\" See ISO/IEC Technical Report 14652
 165 Change settings that describe the formats used to address persons.
 166 Applications that need this information can use
 167 .BR nl_langinfo (3)
 168 to retrieve nonstandard elements, such as
 169 .B _NL_NAME_NAME_MR
 170 (general salutation for men)
 171 and
 172 .B _NL_NAME_NAME_MS
 173 (general salutation for women)
 174 elements, which return strings such as "Herr" and "Frau"
 175 (for German-language locales).
 176 (Other element names are listed in
 177 .IR <langinfo.h> .)
 178 .TP
 179 .B LC_NUMERIC
 180 This category determines the formatting rules used for nonmonetary
 181 numeric values\(emfor example,
 182 the thousands separator and the radix character
 183 (a period in most English-speaking countries,
 184 but a comma in many other regions).
 185 It affects functions such as
 186 .BR printf (3),
 187 .BR scanf (3),
 188 and
 189 .BR strtod (3).
 190 This information can also be read with the
 191 .BR localeconv (3)
 192 function.
 193 .TP
 194 .BR LC_PAPER " (GNU extension, since glibc 2.2)"
 195 .\" See ISO/IEC Technical Report 14652
 196 Change the settings relating to the dimensions of the standard paper size
 197 (e.g., US letter versus A4).
 198 Applications that need the dimensions can obtain them by using
 199 .BR nl_langinfo (3)
 200 to retrieve the nonstandard
 201 .B _NL_PAPER_WIDTH
 202 and
 203 .B _NL_PAPER_HEIGHT
 204 elements, which return
 205 .I int
 206 values specifying the dimensions in millimeters.
 207 .TP
 208 .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
 209 .\" See ISO/IEC Technical Report 14652
 210 Change settings that describe the formats to be used with telephone services.
 211 Applications that need this information can use
 212 .BR nl_langinfo (3)
 213 to retrieve nonstandard elements, such as
 214 .B _NL_TELEPHONE_INT_PREFIX
 215 (international prefix used to call numbers in this locale),
 216 which returns a string such as "49" (for Germany).
 217 (Other element names are listed in
 218 .IR <langinfo.h> .)
 219 .TP
 220 .B LC_TIME
 221 This category governs the formatting used for date and time values.
 222 For example, most of Europe uses a 24-hour clock versus the
 223 12-hour clock used in the United States.
 224 The setting of this category affects the behavior of functions such as
 225 .BR strftime (3)
 226 and
 227 .BR strptime (3).
 228 .TP
 229 .B LC_ALL
 230 All of the above.
 231 .PP
 232 If the second argument to
 233 .BR setlocale (3)
 234 is an empty string,
 235 .BR """""" ,
 236 for the default locale, it is determined using the following steps:
 237 .IP 1.
 238 If there is a non-null environment variable
 239 .BR LC_ALL ,
 240 the value of
 241 .B LC_ALL
 242 is used.
 243 .IP 2.
 244 If an environment variable with the same name as one of the categories
 245 above exists and is non-null, its value is used for that category.
 246 .IP 3.
 247 If there is a non-null environment variable
 248 .BR LANG ,
 249 the value of
 250 .B LANG
 251 is used.
 252 .PP
 253 Values about local numeric formatting is made available in a
 254 .I struct lconv
 255 returned by the
 256 .BR localeconv (3)
 257 function, which has the following declaration:
 258 .in +2n
 259 .nf
 260
 261 struct lconv {
 262
 263     /* Numeric (nonmonetary) information */
 264
 265     char *decimal_point;     /* Radix character */
 266     char *thousands_sep;     /* Separator for digit groups to left
 267                                 of radix character */
 268     char *grouping; /* Each element is the number of digits in a
 269                        group; elements with higher indices are
 270                        further left.  An element with value CHAR_MAX
 271                        means that no further grouping is done.  An
 272                        element with value 0 means that the previous
 273                        element is used for all groups further left. */
 274
 275     /* Remaining fields are for monetary information */
 276
 277     char *int_curr_symbol;   /* First three chars are a currency symbol
 278                                 from ISO 4217.  Fourth char is the
 279                                 separator.  Fifth char is \(aq\\0\(aq. */
 280     char *currency_symbol;   /* Local currency symbol */
 281     char *mon_decimal_point; /* Radix character */
 282     char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
 283     char *mon_grouping;      /* Like \fIgrouping\fP above */
 284     char *positive_sign;     /* Sign for positive values */
 285     char *negative_sign;     /* Sign for negative values */
 286     char  int_frac_digits;   /* International fractional digits */
 287     char  frac_digits;       /* Local fractional digits */
 288     char  p_cs_precedes;     /* 1 if currency_symbol precedes a
 289                                 positive value, 0 if succeeds */
 290     char  p_sep_by_space;    /* 1 if a space separates currency_symbol
 291                                 from a positive value */
 292     char  n_cs_precedes;     /* 1 if currency_symbol precedes a
 293                                 negative value, 0 if succeeds */
 294     char  n_sep_by_space;    /* 1 if a space separates currency_symbol
 295                                 from a negative value */
 296     /* Positive and negative sign positions:
 297        0 Parentheses surround the quantity and currency_symbol.
 298        1 The sign string precedes the quantity and currency_symbol.
 299        2 The sign string succeeds the quantity and currency_symbol.
 300        3 The sign string immediately precedes the currency_symbol.
 301        4 The sign string immediately succeeds the currency_symbol. */
 302     char  p_sign_posn;
 303     char  n_sign_posn;
 304 };
 305 .fi
 306 .in
 307 .SS POSIX.1-2008 extensions to the locale API
 308 POSIX.1-2008 standardized a number of extensions to the locale API,
 309 based on implementations that first appeared in version 2.3
 310 of the GNU C library.
 311 These extensions are designed to address the problem that
 312 the traditional locale APIs do not mix well with multithreaded applications
 313 and with applications that must deal with multiple locales.
 314
 315 The extensions take the form of new functions for creating and
 316 manipulating locale objects
 317 .RB ( newlocale (3),
 318 .BR freelocale (3),
 319 .BR duplocale (3),
 320 and
 321 .BR uselocale (3))
 322 and various new library functions with the suffix "_l" (e.g.,
 323 .BR toupper_l (3))
 324 that extend the traditional locale-dependent APIs (e.g.,
 325 .BR toupper (3))
 326 to allow the specification of a locale object that should apply when
 327 executing the function.
 328 .SH ENVIRONMENT
 329 The following environment variable is used by
 330 .BR newlocale (3)
 331 and
 332 .BR setlocale (3),
 333 and thus affects all localized programs:
 334 .TP
 335 .B LOCPATH
 336 A list of pathnames, separated by colons (\(aq:\(aq),
 337 that should be used to find locale data.
 338 If this variable is set, only the individual locale data files from
 339 .I LOCPATH
 340 and the system default locale data path are used; any available locale
 341 archives are not used. The individual locale data files are searched
 342 under subdirectories which depend on the currently used locale. For
 343 example, when
 344 .I en_GB.UTF-8
 345 is used for a category, the following subdirectories are searched for,
 346 in this order:
 347 .IR en_GB.UTF-8 ,
 348 .IR en_GB.utf8 ,
 349 .IR en_GB ,
 350 .IR en.UTF-8 ,
 351 .IR en.utf8 ,
 352 and
 353 .IR en .
 354 .SH CONFORMING TO
 355 POSIX.1-2001.
 356 .\"
 357 .\" The GNU gettext functions are specified in LI18NUX2000.
 358 .SH SEE ALSO
 359 .BR locale (1),
 360 .BR localedef (1),
 361 .BR catopen (3),
 362 .BR gettext (3),
 363 .BR localeconv (3),
 364 .BR mbstowcs (3),
 365 .BR newlocale (3),
 366 .BR ngettext (3),
 367 .BR nl_langinfo (3),
 368 .BR rpmatch (3),
 369 .BR setlocale (3),
 370 .BR strcoll (3),
 371 .BR strfmon (3),
 372 .BR strftime (3),
 373 .BR strxfrm (3),
 374 .BR uselocale (3),
 375 .BR wcstombs (3),
 376 .BR locale (5),
 377 .BR charsets (7),
 378 .BR unicode (7),
 379 .BR utf-8 (7)