1LOCALE(7) Linux Programmer's Manual LOCALE(7)
2
6 locale - description of multilanguage support
7
9 #include <locale.h>
10
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 The header <locale.h> declares data types, functions, and macros which
18 are useful in this task.
19 The functions it declares are setlocale(3) to set the current locale,
21 and localeconv(3) to get information about number formatting.
22 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 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 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 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 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 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 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 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 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 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 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 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 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 LC_ALL All of the above.
132 If the second argument to setlocale(3) is an empty string, "", for the
134 default locale, it is determined using the following steps:
135 1. If there is a non-null environment variable LC_ALL, the value of
137 LC_ALL is used.
138 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 3. If there is a non-null environment variable LANG, the value of LANG
144 is used.
145 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 struct lconv {
151 /* Numeric (nonmonetary) information */
153 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 /* Remaining fields are for monetary information */
166 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 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 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
214 The following environment variable is used by newlocale(3) and setlo‐
215 cale(3), and thus affects all unprivileged localized programs:
216 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
230 /usr/lib/locale/locale-archive
231 Usual default locale archive location.
232 /usr/lib/locale
234 Usual default path for compiled individual locale files.
235
237 POSIX.1-2001.
238
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
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/.
251Linux 2021-03-22 LOCALE(7)