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