Debian Codegraph @

upstream/debian-unstable/man7/locale.7

raw
1 .\" Copyright 1993, Thomas Koenig <[email protected]>
2 .\" Copyright 2014, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH locale 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 locale \- description of multilanguage support
10 .SH SYNOPSIS
11 .nf
12 .B #include <locale.h>
13 .fi
14 .SH DESCRIPTION
15 A locale is a set of language and cultural rules.
16 These cover aspects
17 such as language for messages, different character sets, lexicographic
18 conventions, and so on.
19 A program needs to be able to determine its locale
20 and act accordingly to be portable to different cultures.
21 .P
22 The header
23 .I <locale.h>
24 declares data types, functions, and macros which are useful in this
25 task.
26 .P
27 The functions it declares are
28 .BR setlocale (3)
29 to set the current locale, and
30 .BR localeconv (3)
31 to get information about number formatting.
32 .P
33 There are different categories for locale information a program might need;
34 they are declared as macros.
35 Using them as the first argument to
36 .BR setlocale (3),
37 it is possible to set one of these to the desired locale:
38 .TP
39 .BR LC_ADDRESS " (GNU extension, since glibc 2.2)"
40 .\" See ISO/IEC Technical Report 14652
41 Change settings that describe the formats (e.g., postal addresses)
42 used to describe locations and geography-related items.
43 Applications that need this information can use
44 .BR nl_langinfo (3)
45 to retrieve nonstandard elements, such as
46 .B _NL_ADDRESS_COUNTRY_NAME
47 (country name, in the language of the locale)
48 and
49 .B _NL_ADDRESS_LANG_NAME
50 (language name, in the language of the locale),
51 which return strings such as "Deutschland" and "Deutsch"
52 (for German-language locales).
53 (Other element names are listed in
54 .IR <langinfo.h> .)
55 .TP
56 .B LC_COLLATE
57 This category governs the collation rules used for
58 sorting and regular expressions,
59 including character equivalence classes and
60 multicharacter collating elements.
61 This locale category changes the behavior of the functions
62 .BR strcoll (3)
63 and
64 .BR strxfrm (3),
65 which are used to compare strings in the local alphabet.
66 For example,
67 the German sharp s is sorted as "ss".
68 .TP
69 .B LC_CTYPE
70 This category determines the interpretation of byte sequences as characters
71 (e.g., single versus multibyte characters), character classifications
72 (e.g., alphabetic or digit), and the behavior of character classes.
73 On glibc systems, this category also determines
74 the character transliteration rules for
75 .BR iconv (1)
76 and
77 .BR iconv (3).
78 It changes the behavior of the character handling and
79 classification functions, such as
80 .BR isupper (3)
81 and
82 .BR toupper (3),
83 and the multibyte character functions such as
84 .BR mblen (3)
85 or
86 .BR wctomb (3).
87 .TP
88 .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
89 .\" See ISO/IEC Technical Report 14652
90 Change settings that relate to the metadata for the locale.
91 Applications that need this information can use
92 .BR nl_langinfo (3)
93 to retrieve nonstandard elements, such as
94 .B _NL_IDENTIFICATION_TITLE
95 (title of this locale document)
96 and
97 .B _NL_IDENTIFICATION_TERRITORY
98 (geographical territory to which this locale document applies),
99 which might return strings such as "English locale for the USA"
100 and "USA".
101 (Other element names are listed in
102 .IR <langinfo.h> .)
103 .TP
104 .B LC_MONETARY
105 This category determines the formatting used for
106 monetary-related numeric values.
107 This changes the information returned by
108 .BR localeconv (3),
109 which describes the way numbers are usually printed, with details such
110 as decimal point versus decimal comma.
111 This information is internally
112 used by the function
113 .BR strfmon (3).
114 .TP
115 .B LC_MESSAGES
116 This category affects the language in which messages are displayed
117 and what an affirmative or negative answer looks like.
118 The GNU C library contains the
119 .BR gettext (3),
120 .BR ngettext (3),
121 and
122 .BR rpmatch (3)
123 functions to ease the use of this information.
124 The GNU gettext family of
125 functions also obey the environment variable
126 .B LANGUAGE
127 (containing a colon-separated list of locales)
128 if the category is set to a valid locale other than
129 .BR \[dq]C\[dq] .
130 This category also affects the behavior of
131 .BR catopen (3).
132 .TP
133 .BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)"
134 Change the settings relating to the measurement system in the locale
135 (i.e., metric versus US customary units).
136 Applications can use
137 .BR nl_langinfo (3)
138 to retrieve the nonstandard
139 .B _NL_MEASUREMENT_MEASUREMENT
140 element, which returns a pointer to a character
141 that has the value 1 (metric) or 2 (US customary units).
142 .TP
143 .BR LC_NAME " (GNU extension, since glibc 2.2)"
144 .\" See ISO/IEC Technical Report 14652
145 Change settings that describe the formats used to address persons.
146 Applications that need this information can use
147 .BR nl_langinfo (3)
148 to retrieve nonstandard elements, such as
149 .B _NL_NAME_NAME_MR
150 (general salutation for men)
151 and
152 .B _NL_NAME_NAME_MS
153 (general salutation for women)
154 elements, which return strings such as "Herr" and "Frau"
155 (for German-language locales).
156 (Other element names are listed in
157 .IR <langinfo.h> .)
158 .TP
159 .B LC_NUMERIC
160 This category determines the formatting rules used for nonmonetary
161 numeric values\[em]for example,
162 the thousands separator and the radix character
163 (a period in most English-speaking countries,
164 but a comma in many other regions).
165 It affects functions such as
166 .BR printf (3),
167 .BR scanf (3),
168 and
169 .BR strtod (3).
170 This information can also be read with the
171 .BR localeconv (3)
172 function.
173 .TP
174 .BR LC_PAPER " (GNU extension, since glibc 2.2)"
175 .\" See ISO/IEC Technical Report 14652
176 Change the settings relating to the dimensions of the standard paper size
177 (e.g., US letter versus A4).
178 Applications that need the dimensions can obtain them by using
179 .BR nl_langinfo (3)
180 to retrieve the nonstandard
181 .B _NL_PAPER_WIDTH
182 and
183 .B _NL_PAPER_HEIGHT
184 elements, which return
185 .I int
186 values specifying the dimensions in millimeters.
187 .TP
188 .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
189 .\" See ISO/IEC Technical Report 14652
190 Change settings that describe the formats to be used with telephone services.
191 Applications that need this information can use
192 .BR nl_langinfo (3)
193 to retrieve nonstandard elements, such as
194 .B _NL_TELEPHONE_INT_PREFIX
195 (international prefix used to call numbers in this locale),
196 which returns a string such as "49" (for Germany).
197 (Other element names are listed in
198 .IR <langinfo.h> .)
199 .TP
200 .B LC_TIME
201 This category governs the formatting used for date and time values.
202 For example, most of Europe uses a 24-hour clock versus the
203 12-hour clock used in the United States.
204 The setting of this category affects the behavior of functions such as
205 .BR strftime (3)
206 and
207 .BR strptime (3).
208 .TP
209 .B LC_ALL
210 All of the above.
211 .P
212 If the second argument to
213 .BR setlocale (3)
214 is an empty string,
215 .IR \[dq]\[dq] ,
216 for the default locale, it is determined using the following steps:
217 .IP (1) 5
218 If there is a non-null environment variable
219 .BR LC_ALL ,
220 the value of
221 .B LC_ALL
222 is used.
223 .IP (2)
224 If an environment variable with the same name as one of the categories
225 above exists and is non-null, its value is used for that category.
226 .IP (3)
227 If there is a non-null environment variable
228 .BR LANG ,
229 the value of
230 .B LANG
231 is used.
232 .P
233 Values about local numeric formatting is made available in a
234 .I struct lconv
235 returned by the
236 .BR localeconv (3)
237 function, which has the following declaration:
238 .P
239 .in +4n
240 .EX
241 struct lconv {
242 \&
243 /* Numeric (nonmonetary) information */
244 \&
245 char *decimal_point; /* Radix character */
246 char *thousands_sep; /* Separator for digit groups to left
247 of radix character */
248 char *grouping; /* Each element is the number of digits in
249 a group; elements with higher indices
250 are further left. An element with value
251 CHAR_MAX means that no further grouping
252 is done. An element with value 0 means
253 that the previous element is used for
254 all groups further left. */
255 \&
256 /* Remaining fields are for monetary information */
257 \&
258 char *int_curr_symbol; /* First three chars are a currency
259 symbol from ISO 4217. Fourth char
260 is the separator. Fifth char
261 is \[aq]\[rs]0\[aq]. */
262 char *currency_symbol; /* Local currency symbol */
263 char *mon_decimal_point; /* Radix character */
264 char *mon_thousands_sep; /* Like \f[I]thousands_sep\f[] above */
265 char *mon_grouping; /* Like \f[I]grouping\f[] above */
266 char *positive_sign; /* Sign for positive values */
267 char *negative_sign; /* Sign for negative values */
268 char int_frac_digits; /* International fractional digits */
269 char frac_digits; /* Local fractional digits */
270 char p_cs_precedes; /* 1 if currency_symbol precedes a
271 positive value, 0 if succeeds */
272 char p_sep_by_space; /* 1 if a space separates
273 currency_symbol from a positive
274 value */
275 char n_cs_precedes; /* 1 if currency_symbol precedes a
276 negative value, 0 if succeeds */
277 char n_sep_by_space; /* 1 if a space separates
278 currency_symbol from a negative
279 value */
280 /* Positive and negative sign positions:
281 0 Parentheses surround the quantity and currency_symbol.
282 1 The sign string precedes the quantity and currency_symbol.
283 2 The sign string succeeds the quantity and currency_symbol.
284 3 The sign string immediately precedes the currency_symbol.
285 4 The sign string immediately succeeds the currency_symbol. */
286 char p_sign_posn;
287 char n_sign_posn;
288 };
289 .EE
290 .in
291 .SS POSIX.1-2008 extensions to the locale API
292 POSIX.1-2008 standardized a number of extensions to the locale API,
293 based on implementations that first appeared in glibc 2.3.
294 These extensions are designed to address the problem that
295 the traditional locale APIs do not mix well with multithreaded applications
296 and with applications that must deal with multiple locales.
297 .P
298 The extensions take the form of new functions for creating and
299 manipulating locale objects
300 .RB ( newlocale (3),
301 .BR freelocale (3),
302 .BR duplocale (3),
303 and
304 .BR uselocale (3))
305 and various new library functions with the suffix "_l" (e.g.,
306 .BR toupper_l (3))
307 that extend the traditional locale-dependent APIs (e.g.,
308 .BR toupper (3))
309 to allow the specification of a locale object that should apply when
310 executing the function.
311 .SH ENVIRONMENT
312 The following environment variable is used by
313 .BR newlocale (3)
314 and
315 .BR setlocale (3),
316 and thus affects all unprivileged localized programs:
317 .TP
318 .B LOCPATH
319 A list of pathnames, separated by colons (\[aq]:\[aq]),
320 that should be used to find locale data.
321 If this variable is set,
322 only the individual compiled locale data files from
323 .B LOCPATH
324 and the system default locale data path are used;
325 any available locale archives are not used (see
326 .BR localedef (1)).
327 The individual compiled locale data files are searched for under
328 subdirectories which depend on the currently used locale.
329 For example, when
330 .I en_GB.UTF\-8
331 is used for a category, the following subdirectories are searched for,
332 in this order:
333 .IR en_GB.UTF\-8 ,
334 .IR en_GB.utf8 ,
335 .IR en_GB ,
336 .IR en.UTF\-8 ,
337 .IR en.utf8 ,
338 and
339 .IR en .
340 .SH FILES
341 .TP
342 .I /usr/lib/locale/locale\-archive
343 Usual default locale archive location.
344 .TP
345 .I /usr/lib/locale
346 Usual default path for compiled individual locale files.
347 .SH STANDARDS
348 POSIX.1-2001.
349 .\"
350 .\" The GNU gettext functions are specified in LI18NUX2000.
351 .SH SEE ALSO
352 .BR iconv (1),
353 .BR locale (1),
354 .BR localedef (1),
355 .BR catopen (3),
356 .BR gettext (3),
357 .BR iconv (3),
358 .BR localeconv (3),
359 .BR mbstowcs (3),
360 .BR newlocale (3),
361 .BR ngettext (3),
362 .BR nl_langinfo (3),
363 .BR rpmatch (3),
364 .BR setlocale (3),
365 .BR strcoll (3),
366 .BR strfmon (3),
367 .BR strftime (3),
368 .BR strxfrm (3),
369 .BR uselocale (3),
370 .BR wcstombs (3),
371 .BR locale (5),
372 .BR charsets (7),
373 .BR unicode (7),
374 .BR utf\-8 (7)