1LOCALE(7)                  Linux Programmer's Manual                 LOCALE(7)
2
3
4

NAME

6       locale - description of multilanguage support
7

SYNOPSIS

9       #include <locale.h>
10

DESCRIPTION

12       A  locale is a set of language and cultural rules.  These cover aspects
13       such as language for messages, different character sets,  lexicographic
14       conventions,  and  so  on.  A program needs to be able to determine its
15       locale and act accordingly to be portable to different cultures.
16
17       The header <locale.h> declares data types, functions, and macros  which
18       are useful in this task.
19
20       The  functions  it declares are setlocale(3) to set the current locale,
21       and localeconv(3) to get information about number formatting.
22
23       There are different categories for locale information a  program  might
24       need; they are declared as macros.  Using them as the first argument to
25       the setlocale(3) function, it is possible to set one of  these  to  the
26       desired locale:
27
28       LC_ADDRESS (GNU extension, since glibc 2.2)
29              Change  settings  that  describe  the  formats (e.g., postal ad‐
30              dresses) used to describe locations and geography-related items.
31              Applications  that  need this information can use nl_langinfo(3)
32              to retrieve  nonstandard  elements,  such  as  _NL_ADDRESS_COUN‐
33              TRY_NAME  (country  name,  in  the  language  of the locale) and
34              _NL_ADDRESS_LANG_NAME (language name, in the language of the lo‐
35              cale),  which return strings such as "Deutschland" and "Deutsch"
36              (for German-language locales).  (Other element names are  listed
37              in <langinfo.h>.)
38
39       LC_COLLATE
40              This  category  governs the collation rules used for sorting and
41              regular expressions, including character equivalence classes and
42              multicharacter collating elements.  This locale category changes
43              the behavior of the functions strcoll(3) and  strxfrm(3),  which
44              are used to compare strings in the local alphabet.  For example,
45              the German sharp s is sorted as "ss".
46
47       LC_CTYPE
48              This category determines the interpretation of byte sequences as
49              characters (e.g., single versus multibyte characters), character
50              classifications (e.g., alphabetic or digit), and the behavior of
51              character  classes.  On glibc systems, this category also deter‐
52              mines the  character  transliteration  rules  for  iconv(1)  and
53              iconv(3).  It changes the behavior of the character handling and
54              classification functions, such as isupper(3) and toupper(3), and
55              the multibyte character functions such as mblen(3) or wctomb(3).
56
57       LC_IDENTIFICATION (GNU extension, since glibc 2.2)
58              Change settings that relate to the metadata for the locale.  Ap‐
59              plications that need this information can use nl_langinfo(3)  to
60              retrieve  nonstandard elements, such as _NL_IDENTIFICATION_TITLE
61              (title of this locale document) and _NL_IDENTIFICATION_TERRITORY
62              (geographical  territory to which this locale document applies),
63              which might return strings such as "English locale for the  USA"
64              and "USA".  (Other element names are listed in <langinfo.h>.)
65
66       LC_MONETARY
67              This  category  determines  the formatting used for monetary-re‐
68              lated numeric values.  This changes the information returned  by
69              localeconv(3),  which  describes  the  way  numbers  are usually
70              printed, with details  such  as  decimal  point  versus  decimal
71              comma.   This  information  is  internally  used by the function
72              strfmon(3).
73
74       LC_MESSAGES
75              This category affects the language in which  messages  are  dis‐
76              played  and  what  an affirmative or negative answer looks like.
77              The GNU C library contains the gettext(3), ngettext(3), and  rp‐
78              match(3) functions to ease the use of this information.  The GNU
79              gettext family of functions also obey the  environment  variable
80              LANGUAGE  (containing  a colon-separated list of locales) if the
81              category is set to a valid locale other than "C".  This category
82              also affects the behavior of catopen(3).
83
84       LC_MEASUREMENT (GNU extension, since glibc 2.2)
85              Change  the  settings  relating to the measurement system in the
86              locale (i.e., metric versus US customary  units).   Applications
87              can  use nl_langinfo(3) to retrieve the nonstandard _NL_MEASURE‐
88              MENT_MEASUREMENT element, which returns a pointer to a character
89              that has the value 1 (metric) or 2 (US customary units).
90
91       LC_NAME (GNU extension, since glibc 2.2)
92              Change  settings  that describe the formats used to address per‐
93              sons.  Applications that need this information can use  nl_lang‐
94              info(3)    to    retrieve    nonstandard   elements,   such   as
95              _NL_NAME_NAME_MR    (general    salutation    for    men)    and
96              _NL_NAME_NAME_MS  (general salutation for women) elements, which
97              return strings such as "Herr" and  "Frau"  (for  German-language
98              locales).  (Other element names are listed in <langinfo.h>.)
99
100       LC_NUMERIC
101              This  category determines the formatting rules used for nonmone‐
102              tary numeric values—for example, the thousands separator and the
103              radix  character  (a  period in most English-speaking countries,
104              but a comma in many other regions).  It affects  functions  such
105              as  printf(3),  scanf(3),  and  strtod(3).  This information can
106              also be read with the localeconv(3) function.
107
108       LC_PAPER (GNU extension, since glibc 2.2)
109              Change the settings relating to the dimensions of  the  standard
110              paper  size (e.g., US letter versus A4).  Applications that need
111              the dimensions can obtain them by using  nl_langinfo(3)  to  re‐
112              trieve the nonstandard _NL_PAPER_WIDTH and _NL_PAPER_HEIGHT ele‐
113              ments, which return int values specifying the dimensions in mil‐
114              limeters.
115
116       LC_TELEPHONE (GNU extension, since glibc 2.2)
117              Change  settings that describe the formats to be used with tele‐
118              phone services.  Applications that need this information can use
119              nl_langinfo(3)   to   retrieve  nonstandard  elements,  such  as
120              _NL_TELEPHONE_INT_PREFIX (international prefix used to call num‐
121              bers  in  this locale), which returns a string such as "49" (for
122              Germany).  (Other element names are listed in <langinfo.h>.)
123
124       LC_TIME
125              This category governs the formatting used for date and time val‐
126              ues.   For  example,  most of Europe uses a 24-hour clock versus
127              the 12-hour clock used in the United  States.   The  setting  of
128              this  category  affects  the behavior of functions such as strf‐
129              time(3) and strptime(3).
130
131       LC_ALL All of the above.
132
133       If the second argument to setlocale(3) is an empty string, "", for  the
134       default locale, it is determined using the following steps:
135
136       1. If  there  is  a  non-null environment variable LC_ALL, the value of
137          LC_ALL is used.
138
139       2. If an environment variable with the same name as one  of  the  cate‐
140          gories above exists and is non-null, its value is used for that cat‐
141          egory.
142
143       3. If there is a non-null environment variable LANG, the value of  LANG
144          is used.
145
146       Values  about  local  numeric  formatting is made available in a struct
147       lconv returned by the localeconv(3) function, which has  the  following
148       declaration:
149
150           struct lconv {
151
152               /* Numeric (nonmonetary) information */
153
154               char *decimal_point;     /* Radix character */
155               char *thousands_sep;     /* Separator for digit groups to left
156                                           of radix character */
157               char *grouping;     /* Each element is the number of digits in
158                                      a group; elements with higher indices
159                                      are further left.  An element with value
160                                      CHAR_MAX means that no further grouping
161                                      is done.  An element with value 0 means
162                                      that the previous element is used for
163                                      all groups further left. */
164
165               /* Remaining fields are for monetary information */
166
167               char *int_curr_symbol;   /* First three chars are a currency
168                                           symbol from ISO 4217.  Fourth char
169                                           is the separator.  Fifth char
170                                           is '\0'. */
171               char *currency_symbol;   /* Local currency symbol */
172               char *mon_decimal_point; /* Radix character */
173               char *mon_thousands_sep; /* Like thousands_sep above */
174               char *mon_grouping;      /* Like grouping above */
175               char *positive_sign;     /* Sign for positive values */
176               char *negative_sign;     /* Sign for negative values */
177               char  int_frac_digits;   /* International fractional digits */
178               char  frac_digits;       /* Local fractional digits */
179               char  p_cs_precedes;     /* 1 if currency_symbol precedes a
180                                           positive value, 0 if succeeds */
181               char  p_sep_by_space;    /* 1 if a space separates
182                                           currency_symbol from a positive
183                                           value */
184               char  n_cs_precedes;     /* 1 if currency_symbol precedes a
185                                           negative value, 0 if succeeds */
186               char  n_sep_by_space;    /* 1 if a space separates
187                                           currency_symbol from a negative
188                                           value */
189               /* Positive and negative sign positions:
190                  0 Parentheses surround the quantity and currency_symbol.
191                  1 The sign string precedes the quantity and currency_symbol.
192                  2 The sign string succeeds the quantity and currency_symbol.
193                  3 The sign string immediately precedes the currency_symbol.
194                  4 The sign string immediately succeeds the currency_symbol. */
195               char  p_sign_posn;
196               char  n_sign_posn;
197           };
198
199   POSIX.1-2008 extensions to the locale API
200       POSIX.1-2008  standardized  a  number  of extensions to the locale API,
201       based on implementations that first appeared in version 2.3 of the  GNU
202       C  library.   These extensions are designed to address the problem that
203       the traditional locale APIs do not mix well with multithreaded applica‐
204       tions and with applications that must deal with multiple locales.
205
206       The  extensions take the form of new functions for creating and manipu‐
207       lating locale objects (newlocale(3), freelocale(3),  duplocale(3),  and
208       uselocale(3))  and  various  new library functions with the suffix "_l"
209       (e.g., toupper_l(3)) that extend the traditional locale-dependent  APIs
210       (e.g.,  toupper(3))  to allow the specification of a locale object that
211       should apply when executing the function.
212

ENVIRONMENT

214       The following environment variable is used by newlocale(3)  and  setlo‐
215       cale(3), and thus affects all unprivileged localized programs:
216
217       LOCPATH
218              A  list  of pathnames, separated by colons (':'), that should be
219              used to find locale data.  If this variable is set, only the in‐
220              dividual  compiled locale data files from LOCPATH and the system
221              default locale data path are used; any available locale archives
222              are not used (see localedef(1)).  The individual compiled locale
223              data files are searched for under subdirectories which depend on
224              the  currently  used  locale.   For example, when en_GB.UTF-8 is
225              used for a category, the following subdirectories  are  searched
226              for,  in  this  order: en_GB.UTF-8, en_GB.utf8, en_GB, en.UTF-8,
227              en.utf8, and en.
228

FILES

230       /usr/lib/locale/locale-archive
231              Usual default locale archive location.
232
233       /usr/lib/locale
234              Usual default path for compiled individual locale files.
235

CONFORMING TO

237       POSIX.1-2001.
238

SEE ALSO

240       iconv(1), locale(1), localedef(1),  catopen(3),  gettext(3),  iconv(3),
241       localeconv(3),  mbstowcs(3), newlocale(3), ngettext(3), nl_langinfo(3),
242       rpmatch(3),   setlocale(3),   strcoll(3),   strfmon(3),    strftime(3),
243       strxfrm(3),  uselocale(3),  wcstombs(3),  locale(5),  charsets(7), uni‐
244       code(7), utf-8(7)
245

COLOPHON

247       This page is part of release 5.13 of the Linux  man-pages  project.   A
248       description  of  the project, information about reporting bugs, and the
249       latest    version    of    this    page,    can     be     found     at
250       https://www.kernel.org/doc/man-pages/.
251
252
253
254Linux                             2021-03-22                         LOCALE(7)
Impressum