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  2021-03-22 "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 On glibc systems, this category also determines
  99 the character transliteration rules for
 100 .BR iconv (1)
 101 and
 102 .BR iconv (3).
 103 It changes the behavior of the character handling and
 104 classification functions, such as
 105 .BR isupper (3)
 106 and
 107 .BR toupper (3),
 108 and the multibyte character functions such as
 109 .BR mblen (3)
 110 or
 111 .BR wctomb (3).
 112 .TP
 113 .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
 114 .\" See ISO/IEC Technical Report 14652
 115 Change settings that relate to the metadata for the locale.
 116 Applications that need this information can use
 117 .BR nl_langinfo (3)
 118 to retrieve nonstandard elements, such as
 119 .B _NL_IDENTIFICATION_TITLE
 120 (title of this locale document)
 121 and
 122 .B _NL_IDENTIFICATION_TERRITORY
 123 (geographical territory to which this locale document applies),
 124 which might return strings such as "English locale for the USA"
 125 and "USA".
 126 (Other element names are listed in
 127 .IR <langinfo.h> .)
 128 .TP
 129 .B LC_MONETARY
 130 This category determines the formatting used for
 131 monetary-related numeric values.
 132 This changes the information returned by
 133 .BR localeconv (3),
 134 which describes the way numbers are usually printed, with details such
 135 as decimal point versus decimal comma.
 136 This information is internally
 137 used by the function
 138 .BR strfmon (3).
 139 .TP
 140 .B LC_MESSAGES
 141 This category affects the language in which messages are displayed
 142 and what an affirmative or negative answer looks like.
 143 The GNU C library contains the
 144 .BR gettext (3),
 145 .BR ngettext (3),
 146 and
 147 .BR rpmatch (3)
 148 functions to ease the use of this information.
 149 The GNU gettext family of
 150 functions also obey the environment variable
 151 .BR LANGUAGE
 152 (containing a colon-separated list of locales)
 153 if the category is set to a valid locale other than
 154 .BR """C""" .
 155 This category also affects the behavior of
 156 .BR catopen (3).
 157 .TP
 158 .BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)"
 159 Change the settings relating to the measurement system in the locale
 160 (i.e., metric versus US customary units).
 161 Applications can use
 162 .BR nl_langinfo (3)
 163 to retrieve the nonstandard
 164 .B _NL_MEASUREMENT_MEASUREMENT
 165 element, which returns a pointer to a character
 166 that has the value 1 (metric) or 2 (US customary units).
 167 .TP
 168 .BR LC_NAME " (GNU extension, since glibc 2.2)"
 169 .\" See ISO/IEC Technical Report 14652
 170 Change settings that describe the formats used to address persons.
 171 Applications that need this information can use
 172 .BR nl_langinfo (3)
 173 to retrieve nonstandard elements, such as
 174 .B _NL_NAME_NAME_MR
 175 (general salutation for men)
 176 and
 177 .B _NL_NAME_NAME_MS
 178 (general salutation for women)
 179 elements, which return strings such as "Herr" and "Frau"
 180 (for German-language locales).
 181 (Other element names are listed in
 182 .IR <langinfo.h> .)
 183 .TP
 184 .B LC_NUMERIC
 185 This category determines the formatting rules used for nonmonetary
 186 numeric values\(emfor example,
 187 the thousands separator and the radix character
 188 (a period in most English-speaking countries,
 189 but a comma in many other regions).
 190 It affects functions such as
 191 .BR printf (3),
 192 .BR scanf (3),
 193 and
 194 .BR strtod (3).
 195 This information can also be read with the
 196 .BR localeconv (3)
 197 function.
 198 .TP
 199 .BR LC_PAPER " (GNU extension, since glibc 2.2)"
 200 .\" See ISO/IEC Technical Report 14652
 201 Change the settings relating to the dimensions of the standard paper size
 202 (e.g., US letter versus A4).
 203 Applications that need the dimensions can obtain them by using
 204 .BR nl_langinfo (3)
 205 to retrieve the nonstandard
 206 .B _NL_PAPER_WIDTH
 207 and
 208 .B _NL_PAPER_HEIGHT
 209 elements, which return
 210 .I int
 211 values specifying the dimensions in millimeters.
 212 .TP
 213 .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
 214 .\" See ISO/IEC Technical Report 14652
 215 Change settings that describe the formats to be used with telephone services.
 216 Applications that need this information can use
 217 .BR nl_langinfo (3)
 218 to retrieve nonstandard elements, such as
 219 .B _NL_TELEPHONE_INT_PREFIX
 220 (international prefix used to call numbers in this locale),
 221 which returns a string such as "49" (for Germany).
 222 (Other element names are listed in
 223 .IR <langinfo.h> .)
 224 .TP
 225 .B LC_TIME
 226 This category governs the formatting used for date and time values.
 227 For example, most of Europe uses a 24-hour clock versus the
 228 12-hour clock used in the United States.
 229 The setting of this category affects the behavior of functions such as
 230 .BR strftime (3)
 231 and
 232 .BR strptime (3).
 233 .TP
 234 .B LC_ALL
 235 All of the above.
 236 .PP
 237 If the second argument to
 238 .BR setlocale (3)
 239 is an empty string,
 240 .IR """""" ,
 241 for the default locale, it is determined using the following steps:
 242 .IP 1. 3
 243 If there is a non-null environment variable
 244 .BR LC_ALL ,
 245 the value of
 246 .B LC_ALL
 247 is used.
 248 .IP 2.
 249 If an environment variable with the same name as one of the categories
 250 above exists and is non-null, its value is used for that category.
 251 .IP 3.
 252 If there is a non-null environment variable
 253 .BR LANG ,
 254 the value of
 255 .B LANG
 256 is used.
 257 .PP
 258 Values about local numeric formatting is made available in a
 259 .I struct lconv
 260 returned by the
 261 .BR localeconv (3)
 262 function, which has the following declaration:
 263 .PP
 264 .in +4n
 265 .EX
 266 struct lconv {
 267
 268     /* Numeric (nonmonetary) information */
 269
 270     char *decimal_point;     /* Radix character */
 271     char *thousands_sep;     /* Separator for digit groups to left
 272                                 of radix character */
 273     char *grouping;     /* Each element is the number of digits in
 274                            a group; elements with higher indices
 275                            are further left.  An element with value
 276                            CHAR_MAX means that no further grouping
 277                            is done.  An element with value 0 means
 278                            that the previous element is used for
 279                            all groups further left. */
 280
 281     /* Remaining fields are for monetary information */
 282
 283     char *int_curr_symbol;   /* First three chars are a currency
 284                                 symbol from ISO 4217.  Fourth char
 285                                 is the separator.  Fifth char
 286                                 is \(aq\e0\(aq. */
 287     char *currency_symbol;   /* Local currency symbol */
 288     char *mon_decimal_point; /* Radix character */
 289     char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
 290     char *mon_grouping;      /* Like \fIgrouping\fP above */
 291     char *positive_sign;     /* Sign for positive values */
 292     char *negative_sign;     /* Sign for negative values */
 293     char  int_frac_digits;   /* International fractional digits */
 294     char  frac_digits;       /* Local fractional digits */
 295     char  p_cs_precedes;     /* 1 if currency_symbol precedes a
 296                                 positive value, 0 if succeeds */
 297     char  p_sep_by_space;    /* 1 if a space separates
 298                                 currency_symbol from a positive
 299                                 value */
 300     char  n_cs_precedes;     /* 1 if currency_symbol precedes a
 301                                 negative value, 0 if succeeds */
 302     char  n_sep_by_space;    /* 1 if a space separates
 303                                 currency_symbol from a negative
 304                                 value */
 305     /* Positive and negative sign positions:
 306        0 Parentheses surround the quantity and currency_symbol.
 307        1 The sign string precedes the quantity and currency_symbol.
 308        2 The sign string succeeds the quantity and currency_symbol.
 309        3 The sign string immediately precedes the currency_symbol.
 310        4 The sign string immediately succeeds the currency_symbol. */
 311     char  p_sign_posn;
 312     char  n_sign_posn;
 313 };
 314 .EE
 315 .in
 316 .SS POSIX.1-2008 extensions to the locale API
 317 POSIX.1-2008 standardized a number of extensions to the locale API,
 318 based on implementations that first appeared in version 2.3
 319 of the GNU C library.
 320 These extensions are designed to address the problem that
 321 the traditional locale APIs do not mix well with multithreaded applications
 322 and with applications that must deal with multiple locales.
 323 .PP
 324 The extensions take the form of new functions for creating and
 325 manipulating locale objects
 326 .RB ( newlocale (3),
 327 .BR freelocale (3),
 328 .BR duplocale (3),
 329 and
 330 .BR uselocale (3))
 331 and various new library functions with the suffix "_l" (e.g.,
 332 .BR toupper_l (3))
 333 that extend the traditional locale-dependent APIs (e.g.,
 334 .BR toupper (3))
 335 to allow the specification of a locale object that should apply when
 336 executing the function.
 337 .SH ENVIRONMENT
 338 The following environment variable is used by
 339 .BR newlocale (3)
 340 and
 341 .BR setlocale (3),
 342 and thus affects all unprivileged localized programs:
 343 .TP
 344 .B LOCPATH
 345 A list of pathnames, separated by colons (\(aq:\(aq),
 346 that should be used to find locale data.
 347 If this variable is set,
 348 only the individual compiled locale data files from
 349 .B LOCPATH
 350 and the system default locale data path are used;
 351 any available locale archives are not used (see
 352 .BR localedef (1)).
 353 The individual compiled locale data files are searched for under
 354 subdirectories which depend on the currently used locale.
 355 For example, when
 356 .I en_GB.UTF\-8
 357 is used for a category, the following subdirectories are searched for,
 358 in this order:
 359 .IR en_GB.UTF\-8 ,
 360 .IR en_GB.utf8 ,
 361 .IR en_GB ,
 362 .IR en.UTF\-8 ,
 363 .IR en.utf8 ,
 364 and
 365 .IR en .
 366 .SH FILES
 367 .TP
 368 .I /usr/lib/locale/locale\-archive
 369 Usual default locale archive location.
 370 .TP
 371 .I /usr/lib/locale
 372 Usual default path for compiled individual locale files.
 373 .SH CONFORMING TO
 374 POSIX.1-2001.
 375 .\"
 376 .\" The GNU gettext functions are specified in LI18NUX2000.
 377 .SH SEE ALSO
 378 .BR iconv (1),
 379 .BR locale (1),
 380 .BR localedef (1),
 381 .BR catopen (3),
 382 .BR gettext (3),
 383 .BR iconv (3),
 384 .BR localeconv (3),
 385 .BR mbstowcs (3),
 386 .BR newlocale (3),
 387 .BR ngettext (3),
 388 .BR nl_langinfo (3),
 389 .BR rpmatch (3),
 390 .BR setlocale (3),
 391 .BR strcoll (3),
 392 .BR strfmon (3),
 393 .BR strftime (3),
 394 .BR strxfrm (3),
 395 .BR uselocale (3),
 396 .BR wcstombs (3),
 397 .BR locale (5),
 398 .BR charsets (7),
 399 .BR unicode (7),
 400 .BR utf\-8 (7)