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