]>
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 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 13 | .\" |
fea681da MK |
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. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
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 | .\" | |
4b8c67d9 | 31 | .TH LOCALE 7 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 32 | .SH NAME |
f68512e9 | 33 | locale \- description of multilanguage support |
fea681da MK |
34 | .SH SYNOPSIS |
35 | .nf | |
36 | .B #include <locale.h> | |
37 | .fi | |
38 | .SH DESCRIPTION | |
c13182ef MK |
39 | A locale is a set of language and cultural rules. |
40 | These cover aspects | |
3f1c1b0a | 41 | such as language for messages, different character sets, lexicographic |
004e0245 | 42 | conventions, and so on. |
c13182ef | 43 | A program needs to be able to determine its locale |
fea681da MK |
44 | and act accordingly to be portable to different cultures. |
45 | .PP | |
46 | The header | |
bd12ab88 | 47 | .I <locale.h> |
fea681da MK |
48 | declares data types, functions and macros which are useful in this |
49 | task. | |
50 | .PP | |
51 | The functions it declares are | |
63f6a20a | 52 | .BR setlocale (3) |
fea681da | 53 | to set the current locale, and |
63f6a20a | 54 | .BR localeconv (3) |
fea681da MK |
55 | to get information about number formatting. |
56 | .PP | |
8d63e6ec | 57 | There are different categories for locale information a program might |
c13182ef MK |
58 | need; they are declared as macros. |
59 | Using them as the first argument | |
fea681da | 60 | to the |
63f6a20a | 61 | .BR setlocale (3) |
fea681da MK |
62 | function, it is possible to set one of these to the desired locale: |
63 | .TP | |
798f7baf | 64 | .BR LC_ADDRESS " (GNU extension, since glibc 2.2)" |
de0f9c1c | 65 | .\" See ISO/IEC Technical Report 14652 |
798f7baf MK |
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 | |
ebb55337 MK |
75 | (language name, in the language of the locale), |
76 | which return strings such as "Deutschland" and "Deutsch" | |
798f7baf MK |
77 | (for German-language locales). |
78 | (Other element names are listed in | |
79 | .IR <langinfo.h> .) | |
80 | .TP | |
fea681da | 81 | .B LC_COLLATE |
d099bdc5 MK |
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 | |
63f6a20a | 87 | .BR strcoll (3) |
fea681da | 88 | and |
63f6a20a | 89 | .BR strxfrm (3), |
c13182ef MK |
90 | which are used to compare strings in the local alphabet. |
91 | For example, | |
fea681da MK |
92 | the German sharp s is sorted as "ss". |
93 | .TP | |
94 | .B LC_CTYPE | |
d099bdc5 MK |
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. | |
c42df710 MK |
98 | On glibc systems, this category also determines |
99 | the character transliteration rules for | |
3d6d6fac MM |
100 | .BR iconv (1) |
101 | and | |
102 | .BR iconv (3). | |
d099bdc5 | 103 | It changes the behavior of the character handling and |
fea681da | 104 | classification functions, such as |
63f6a20a | 105 | .BR isupper (3) |
fea681da | 106 | and |
63f6a20a | 107 | .BR toupper (3), |
ae03dc66 | 108 | and the multibyte character functions such as |
63f6a20a | 109 | .BR mblen (3) |
fea681da | 110 | or |
63f6a20a | 111 | .BR wctomb (3). |
fea681da | 112 | .TP |
5f49682e | 113 | .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)" |
de0f9c1c | 114 | .\" See ISO/IEC Technical Report 14652 |
f360dbe8 | 115 | Change settings that relate to the metadata for the locale. |
5f49682e MK |
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 | |
f360dbe8 | 123 | (geographical territory to which this locale document applies), |
5f49682e MK |
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 | |
fea681da | 129 | .B LC_MONETARY |
d099bdc5 MK |
130 | This category determines the formatting used for |
131 | monetary-related numeric values. | |
fb844405 | 132 | This changes the information returned by |
d099bdc5 | 133 | .BR localeconv (3), |
fea681da | 134 | which describes the way numbers are usually printed, with details such |
c13182ef MK |
135 | as decimal point versus decimal comma. |
136 | This information is internally | |
fea681da | 137 | used by the function |
63f6a20a | 138 | .BR strfmon (3). |
fea681da MK |
139 | .TP |
140 | .B LC_MESSAGES | |
d099bdc5 MK |
141 | This category affects the language in which messages are displayed |
142 | and what an affirmative or negative answer looks like. | |
0eb0bdd2 | 143 | The GNU C library contains the |
63f6a20a MK |
144 | .BR gettext (3), |
145 | .BR ngettext (3), | |
fea681da | 146 | and |
63f6a20a | 147 | .BR rpmatch (3) |
a33c5137 | 148 | functions to ease the use of this information. |
c13182ef | 149 | The GNU gettext family of |
fea681da | 150 | functions also obey the environment variable |
97aec57c MK |
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""" . | |
d099bdc5 MK |
155 | This category also affects the behavior of |
156 | .BR catopen (3). | |
fea681da | 157 | .TP |
7c57cb80 MK |
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 | |
ba5e9ef3 | 168 | .BR LC_NAME " (GNU extension, since glibc 2.2)" |
de0f9c1c | 169 | .\" See ISO/IEC Technical Report 14652 |
ba5e9ef3 MK |
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 | |
fea681da | 184 | .B LC_NUMERIC |
d099bdc5 MK |
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 | |
6cecebf1 | 191 | .BR printf (3), |
d099bdc5 | 192 | .BR scanf (3), |
fea681da | 193 | and |
d099bdc5 | 194 | .BR strtod (3). |
c13182ef | 195 | This information can also be read with the |
63f6a20a | 196 | .BR localeconv (3) |
fea681da MK |
197 | function. |
198 | .TP | |
0b65297e | 199 | .BR LC_PAPER " (GNU extension, since glibc 2.2)" |
de0f9c1c | 200 | .\" See ISO/IEC Technical Report 14652 |
0b65297e MK |
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 | |
1c598039 | 213 | .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)" |
de0f9c1c | 214 | .\" See ISO/IEC Technical Report 14652 |
1c598039 MK |
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 | |
fea681da | 225 | .B LC_TIME |
d099bdc5 MK |
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 | |
2706f299 | 228 | 12-hour clock used in the United States. |
b5450631 | 229 | The setting of this category affects the behavior of functions such as |
d099bdc5 MK |
230 | .BR strftime (3) |
231 | and | |
232 | .BR strptime (3). | |
fea681da MK |
233 | .TP |
234 | .B LC_ALL | |
235 | All of the above. | |
236 | .PP | |
237 | If the second argument to | |
63f6a20a | 238 | .BR setlocale (3) |
47e067e5 | 239 | is an empty string, |
44449eb9 | 240 | .IR """""" , |
fea681da | 241 | for the default locale, it is determined using the following steps: |
445e4cb0 | 242 | .IP 1. 3 |
fea681da MK |
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 | |
8478ee02 | 259 | .I struct lconv |
fea681da | 260 | returned by the |
63f6a20a | 261 | .BR localeconv (3) |
fea681da | 262 | function, which has the following declaration: |
9c40f2b9 MK |
263 | .PP |
264 | .in +4n | |
265 | .EX | |
f6fa37d1 | 266 | struct lconv { |
65b4e14d | 267 | |
b4b78977 | 268 | /* Numeric (nonmonetary) information */ |
fea681da | 269 | |
088a639b MK |
270 | char *decimal_point; /* Radix character */ |
271 | char *thousands_sep; /* Separator for digit groups to left | |
272 | of radix character */ | |
3cf30efc MK |
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. */ | |
9fb1e24a | 280 | |
088a639b | 281 | /* Remaining fields are for monetary information */ |
9fb1e24a | 282 | |
3cf30efc MK |
283 | char *int_curr_symbol; /* First three chars are a currency |
284 | symbol from ISO 4217. Fourth char | |
285 | is the separator. Fifth char | |
d1a71985 | 286 | is \(aq\e0\(aq. */ |
088a639b MK |
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 */ | |
84c517a4 | 293 | char int_frac_digits; /* International fractional digits */ |
088a639b MK |
294 | char frac_digits; /* Local fractional digits */ |
295 | char p_cs_precedes; /* 1 if currency_symbol precedes a | |
296 | positive value, 0 if succeeds */ | |
3cf30efc MK |
297 | char p_sep_by_space; /* 1 if a space separates |
298 | currency_symbol from a positive | |
299 | value */ | |
088a639b MK |
300 | char n_cs_precedes; /* 1 if currency_symbol precedes a |
301 | negative value, 0 if succeeds */ | |
3cf30efc MK |
302 | char n_sep_by_space; /* 1 if a space separates |
303 | currency_symbol from a negative | |
304 | value */ | |
088a639b MK |
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; | |
fea681da | 313 | }; |
b8302363 | 314 | .EE |
088a639b | 315 | .in |
4aeed369 MK |
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. | |
89851a00 | 320 | These extensions are designed to address the problem that |
2fa99a62 | 321 | the traditional locale APIs do not mix well with multithreaded applications |
4aeed369 | 322 | and with applications that must deal with multiple locales. |
5711c04f | 323 | .PP |
4aeed369 MK |
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. | |
cd2b4f6e | 337 | .SH ENVIRONMENT |
b331e0d0 MK |
338 | The following environment variable is used by |
339 | .BR newlocale (3) | |
340 | and | |
341 | .BR setlocale (3), | |
c5466970 | 342 | and thus affects all unprivileged localized programs: |
cd2b4f6e MM |
343 | .TP |
344 | .B LOCPATH | |
9fb49a3a MK |
345 | A list of pathnames, separated by colons (\(aq:\(aq), |
346 | that should be used to find locale data. | |
476cab32 MK |
347 | If this variable is set, |
348 | only the individual compiled locale data files from | |
cd2b4f6e | 349 | .I LOCPATH |
c5466970 MM |
350 | and the system default locale data path are used; |
351 | any available locale archives are not used (see | |
352 | .BR localedef (1)). | |
476cab32 | 353 | The individual compiled locale data files are searched for under |
c5466970 MM |
354 | subdirectories which depend on the currently used locale. |
355 | For example, when | |
859476f7 MM |
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 . | |
c5466970 MM |
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. | |
47297adb | 373 | .SH CONFORMING TO |
a7fadb55 | 374 | POSIX.1-2001. |
89851a00 | 375 | .\" |
2fa99a62 | 376 | .\" The GNU gettext functions are specified in LI18NUX2000. |
47297adb | 377 | .SH SEE ALSO |
3d6d6fac | 378 | .BR iconv (1), |
fea681da MK |
379 | .BR locale (1), |
380 | .BR localedef (1), | |
5be6f51f | 381 | .BR catopen (3), |
fea681da | 382 | .BR gettext (3), |
3d6d6fac | 383 | .BR iconv (3), |
fea681da | 384 | .BR localeconv (3), |
713167dc | 385 | .BR mbstowcs (3), |
a8de62de | 386 | .BR newlocale (3), |
fea681da MK |
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), | |
6985a63a | 394 | .BR strxfrm (3), |
a8de62de | 395 | .BR uselocale (3), |
713167dc | 396 | .BR wcstombs (3), |
66aa7615 MM |
397 | .BR locale (5), |
398 | .BR charsets (7), | |
399 | .BR unicode (7), | |
400 | .BR utf-8 (7) |