]>
Commit | Line | Data |
---|---|---|
bf5a7247 | 1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
7c57cb80 | 2 | .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
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 | .\" | |
1d767b55 | 11 | .TH LOCALE 7 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da | 12 | .SH NAME |
f68512e9 | 13 | locale \- description of multilanguage support |
fea681da MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <locale.h> | |
17 | .fi | |
18 | .SH DESCRIPTION | |
c13182ef MK |
19 | A locale is a set of language and cultural rules. |
20 | These cover aspects | |
3f1c1b0a | 21 | such as language for messages, different character sets, lexicographic |
004e0245 | 22 | conventions, and so on. |
c13182ef | 23 | A program needs to be able to determine its locale |
fea681da MK |
24 | and act accordingly to be portable to different cultures. |
25 | .PP | |
26 | The header | |
bd12ab88 | 27 | .I <locale.h> |
735334d4 | 28 | declares data types, functions, and macros which are useful in this |
fea681da MK |
29 | task. |
30 | .PP | |
31 | The functions it declares are | |
63f6a20a | 32 | .BR setlocale (3) |
fea681da | 33 | to set the current locale, and |
63f6a20a | 34 | .BR localeconv (3) |
fea681da MK |
35 | to get information about number formatting. |
36 | .PP | |
8d63e6ec | 37 | There are different categories for locale information a program might |
c13182ef MK |
38 | need; they are declared as macros. |
39 | Using them as the first argument | |
fea681da | 40 | to the |
63f6a20a | 41 | .BR setlocale (3) |
fea681da MK |
42 | function, it is possible to set one of these to the desired locale: |
43 | .TP | |
798f7baf | 44 | .BR LC_ADDRESS " (GNU extension, since glibc 2.2)" |
de0f9c1c | 45 | .\" See ISO/IEC Technical Report 14652 |
798f7baf MK |
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 | |
ebb55337 MK |
55 | (language name, in the language of the locale), |
56 | which return strings such as "Deutschland" and "Deutsch" | |
798f7baf MK |
57 | (for German-language locales). |
58 | (Other element names are listed in | |
59 | .IR <langinfo.h> .) | |
60 | .TP | |
fea681da | 61 | .B LC_COLLATE |
d099bdc5 MK |
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 | |
63f6a20a | 67 | .BR strcoll (3) |
fea681da | 68 | and |
63f6a20a | 69 | .BR strxfrm (3), |
c13182ef MK |
70 | which are used to compare strings in the local alphabet. |
71 | For example, | |
fea681da MK |
72 | the German sharp s is sorted as "ss". |
73 | .TP | |
74 | .B LC_CTYPE | |
d099bdc5 MK |
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. | |
c42df710 MK |
78 | On glibc systems, this category also determines |
79 | the character transliteration rules for | |
3d6d6fac MM |
80 | .BR iconv (1) |
81 | and | |
82 | .BR iconv (3). | |
d099bdc5 | 83 | It changes the behavior of the character handling and |
fea681da | 84 | classification functions, such as |
63f6a20a | 85 | .BR isupper (3) |
fea681da | 86 | and |
63f6a20a | 87 | .BR toupper (3), |
ae03dc66 | 88 | and the multibyte character functions such as |
63f6a20a | 89 | .BR mblen (3) |
fea681da | 90 | or |
63f6a20a | 91 | .BR wctomb (3). |
fea681da | 92 | .TP |
5f49682e | 93 | .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)" |
de0f9c1c | 94 | .\" See ISO/IEC Technical Report 14652 |
f360dbe8 | 95 | Change settings that relate to the metadata for the locale. |
5f49682e MK |
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 | |
f360dbe8 | 103 | (geographical territory to which this locale document applies), |
5f49682e MK |
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 | |
fea681da | 109 | .B LC_MONETARY |
d099bdc5 MK |
110 | This category determines the formatting used for |
111 | monetary-related numeric values. | |
fb844405 | 112 | This changes the information returned by |
d099bdc5 | 113 | .BR localeconv (3), |
fea681da | 114 | which describes the way numbers are usually printed, with details such |
c13182ef MK |
115 | as decimal point versus decimal comma. |
116 | This information is internally | |
fea681da | 117 | used by the function |
63f6a20a | 118 | .BR strfmon (3). |
fea681da MK |
119 | .TP |
120 | .B LC_MESSAGES | |
d099bdc5 MK |
121 | This category affects the language in which messages are displayed |
122 | and what an affirmative or negative answer looks like. | |
0eb0bdd2 | 123 | The GNU C library contains the |
63f6a20a MK |
124 | .BR gettext (3), |
125 | .BR ngettext (3), | |
fea681da | 126 | and |
63f6a20a | 127 | .BR rpmatch (3) |
a33c5137 | 128 | functions to ease the use of this information. |
c13182ef | 129 | The GNU gettext family of |
fea681da | 130 | functions also obey the environment variable |
1ae6b2c7 | 131 | .B LANGUAGE |
97aec57c MK |
132 | (containing a colon-separated list of locales) |
133 | if the category is set to a valid locale other than | |
134 | .BR """C""" . | |
d099bdc5 MK |
135 | This category also affects the behavior of |
136 | .BR catopen (3). | |
fea681da | 137 | .TP |
7c57cb80 MK |
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 | |
ba5e9ef3 | 148 | .BR LC_NAME " (GNU extension, since glibc 2.2)" |
de0f9c1c | 149 | .\" See ISO/IEC Technical Report 14652 |
ba5e9ef3 MK |
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 | |
fea681da | 164 | .B LC_NUMERIC |
d099bdc5 MK |
165 | This category determines the formatting rules used for nonmonetary |
166 | numeric values\(emfor 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 | |
6cecebf1 | 171 | .BR printf (3), |
d099bdc5 | 172 | .BR scanf (3), |
fea681da | 173 | and |
d099bdc5 | 174 | .BR strtod (3). |
c13182ef | 175 | This information can also be read with the |
63f6a20a | 176 | .BR localeconv (3) |
fea681da MK |
177 | function. |
178 | .TP | |
0b65297e | 179 | .BR LC_PAPER " (GNU extension, since glibc 2.2)" |
de0f9c1c | 180 | .\" See ISO/IEC Technical Report 14652 |
0b65297e MK |
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 | |
1c598039 | 193 | .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)" |
de0f9c1c | 194 | .\" See ISO/IEC Technical Report 14652 |
1c598039 MK |
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 | |
fea681da | 205 | .B LC_TIME |
d099bdc5 MK |
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 | |
2706f299 | 208 | 12-hour clock used in the United States. |
b5450631 | 209 | The setting of this category affects the behavior of functions such as |
d099bdc5 MK |
210 | .BR strftime (3) |
211 | and | |
212 | .BR strptime (3). | |
fea681da MK |
213 | .TP |
214 | .B LC_ALL | |
215 | All of the above. | |
216 | .PP | |
217 | If the second argument to | |
63f6a20a | 218 | .BR setlocale (3) |
47e067e5 | 219 | is an empty string, |
44449eb9 | 220 | .IR """""" , |
fea681da | 221 | for the default locale, it is determined using the following steps: |
445e4cb0 | 222 | .IP 1. 3 |
fea681da MK |
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 | |
8478ee02 | 239 | .I struct lconv |
fea681da | 240 | returned by the |
63f6a20a | 241 | .BR localeconv (3) |
fea681da | 242 | function, which has the following declaration: |
9c40f2b9 MK |
243 | .PP |
244 | .in +4n | |
245 | .EX | |
f6fa37d1 | 246 | struct lconv { |
65b4e14d | 247 | |
b4b78977 | 248 | /* Numeric (nonmonetary) information */ |
fea681da | 249 | |
088a639b MK |
250 | char *decimal_point; /* Radix character */ |
251 | char *thousands_sep; /* Separator for digit groups to left | |
252 | of radix character */ | |
3cf30efc MK |
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. */ | |
9fb1e24a | 260 | |
088a639b | 261 | /* Remaining fields are for monetary information */ |
9fb1e24a | 262 | |
3cf30efc MK |
263 | char *int_curr_symbol; /* First three chars are a currency |
264 | symbol from ISO 4217. Fourth char | |
265 | is the separator. Fifth char | |
d1a71985 | 266 | is \(aq\e0\(aq. */ |
088a639b MK |
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 */ | |
84c517a4 | 273 | char int_frac_digits; /* International fractional digits */ |
088a639b MK |
274 | char frac_digits; /* Local fractional digits */ |
275 | char p_cs_precedes; /* 1 if currency_symbol precedes a | |
276 | positive value, 0 if succeeds */ | |
3cf30efc MK |
277 | char p_sep_by_space; /* 1 if a space separates |
278 | currency_symbol from a positive | |
279 | value */ | |
088a639b MK |
280 | char n_cs_precedes; /* 1 if currency_symbol precedes a |
281 | negative value, 0 if succeeds */ | |
3cf30efc MK |
282 | char n_sep_by_space; /* 1 if a space separates |
283 | currency_symbol from a negative | |
284 | value */ | |
088a639b MK |
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; | |
fea681da | 293 | }; |
b8302363 | 294 | .EE |
088a639b | 295 | .in |
4aeed369 MK |
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 version 2.3 | |
299 | of the GNU C library. | |
89851a00 | 300 | These extensions are designed to address the problem that |
2fa99a62 | 301 | the traditional locale APIs do not mix well with multithreaded applications |
4aeed369 | 302 | and with applications that must deal with multiple locales. |
5711c04f | 303 | .PP |
4aeed369 MK |
304 | The extensions take the form of new functions for creating and |
305 | manipulating locale objects | |
306 | .RB ( newlocale (3), | |
307 | .BR freelocale (3), | |
308 | .BR duplocale (3), | |
309 | and | |
310 | .BR uselocale (3)) | |
311 | and various new library functions with the suffix "_l" (e.g., | |
312 | .BR toupper_l (3)) | |
313 | that extend the traditional locale-dependent APIs (e.g., | |
314 | .BR toupper (3)) | |
315 | to allow the specification of a locale object that should apply when | |
316 | executing the function. | |
cd2b4f6e | 317 | .SH ENVIRONMENT |
b331e0d0 MK |
318 | The following environment variable is used by |
319 | .BR newlocale (3) | |
320 | and | |
321 | .BR setlocale (3), | |
c5466970 | 322 | and thus affects all unprivileged localized programs: |
cd2b4f6e MM |
323 | .TP |
324 | .B LOCPATH | |
9fb49a3a MK |
325 | A list of pathnames, separated by colons (\(aq:\(aq), |
326 | that should be used to find locale data. | |
476cab32 MK |
327 | If this variable is set, |
328 | only the individual compiled locale data files from | |
a6c67952 | 329 | .B LOCPATH |
c5466970 MM |
330 | and the system default locale data path are used; |
331 | any available locale archives are not used (see | |
332 | .BR localedef (1)). | |
476cab32 | 333 | The individual compiled locale data files are searched for under |
c5466970 MM |
334 | subdirectories which depend on the currently used locale. |
335 | For example, when | |
cd415e73 | 336 | .I en_GB.UTF\-8 |
859476f7 MM |
337 | is used for a category, the following subdirectories are searched for, |
338 | in this order: | |
cd415e73 | 339 | .IR en_GB.UTF\-8 , |
859476f7 MM |
340 | .IR en_GB.utf8 , |
341 | .IR en_GB , | |
cd415e73 | 342 | .IR en.UTF\-8 , |
859476f7 MM |
343 | .IR en.utf8 , |
344 | and | |
345 | .IR en . | |
c5466970 MM |
346 | .SH FILES |
347 | .TP | |
b49c2acb | 348 | .I /usr/lib/locale/locale\-archive |
c5466970 MM |
349 | Usual default locale archive location. |
350 | .TP | |
351 | .I /usr/lib/locale | |
352 | Usual default path for compiled individual locale files. | |
47297adb | 353 | .SH CONFORMING TO |
a7fadb55 | 354 | POSIX.1-2001. |
89851a00 | 355 | .\" |
2fa99a62 | 356 | .\" The GNU gettext functions are specified in LI18NUX2000. |
47297adb | 357 | .SH SEE ALSO |
3d6d6fac | 358 | .BR iconv (1), |
fea681da MK |
359 | .BR locale (1), |
360 | .BR localedef (1), | |
5be6f51f | 361 | .BR catopen (3), |
fea681da | 362 | .BR gettext (3), |
3d6d6fac | 363 | .BR iconv (3), |
fea681da | 364 | .BR localeconv (3), |
713167dc | 365 | .BR mbstowcs (3), |
a8de62de | 366 | .BR newlocale (3), |
fea681da MK |
367 | .BR ngettext (3), |
368 | .BR nl_langinfo (3), | |
369 | .BR rpmatch (3), | |
370 | .BR setlocale (3), | |
371 | .BR strcoll (3), | |
372 | .BR strfmon (3), | |
373 | .BR strftime (3), | |
6985a63a | 374 | .BR strxfrm (3), |
a8de62de | 375 | .BR uselocale (3), |
713167dc | 376 | .BR wcstombs (3), |
66aa7615 MM |
377 | .BR locale (5), |
378 | .BR charsets (7), | |
379 | .BR unicode (7), | |
28a4c58c | 380 | .BR utf\-8 (7) |