proc.5: Remove duplicated /proc/[pid]/gid_map entry
[man-pages.git] / man7 / locale.7
blob2959c4ff7a2bd6b2d7cb9a9ebba089bad55b9987
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 .\" %%%LICENSE_START(VERBATIM)
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.
13 .\"
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.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
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 .\"
31 .TH LOCALE 7  2021-03-22 "Linux" "Linux Programmer's Manual"
32 .SH NAME
33 locale \- description of multilanguage support
34 .SH SYNOPSIS
35 .nf
36 .B #include <locale.h>
37 .fi
38 .SH DESCRIPTION
39 A locale is a set of language and cultural rules.
40 These cover aspects
41 such as language for messages, different character sets, lexicographic
42 conventions, and so on.
43 A program needs to be able to determine its locale
44 and act accordingly to be portable to different cultures.
45 .PP
46 The header
47 .I <locale.h>
48 declares data types, functions, and macros which are useful in this
49 task.
50 .PP
51 The functions it declares are
52 .BR setlocale (3)
53 to set the current locale, and
54 .BR localeconv (3)
55 to get information about number formatting.
56 .PP
57 There are different categories for locale information a program might
58 need; they are declared as macros.
59 Using them as the first argument
60 to the
61 .BR setlocale (3)
62 function, it is possible to set one of these to the desired locale:
63 .TP
64 .BR LC_ADDRESS " (GNU extension, since glibc 2.2)"
65 .\" See ISO/IEC Technical Report 14652
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
75 (language name, in the language of the locale),
76 which return strings such as "Deutschland" and "Deutsch"
77 (for German-language locales).
78 (Other element names are listed in
79 .IR <langinfo.h> .)
80 .TP
81 .B LC_COLLATE
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
87 .BR strcoll (3)
88 and
89 .BR strxfrm (3),
90 which are used to compare strings in the local alphabet.
91 For example,
92 the German sharp s is sorted as "ss".
93 .TP
94 .B LC_CTYPE
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.
98 On glibc systems, this category also determines
99 the character transliteration rules for
100 .BR iconv (1)
102 .BR iconv (3).
103 It changes the behavior of the character handling and
104 classification functions, such as
105 .BR isupper (3)
107 .BR toupper (3),
108 and the multibyte character functions such as
109 .BR mblen (3)
111 .BR wctomb (3).
113 .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
114 .\" See ISO/IEC Technical Report 14652
115 Change settings that relate to the metadata for the locale.
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)
122 .B _NL_IDENTIFICATION_TERRITORY
123 (geographical territory to which this locale document applies),
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> .)
129 .B LC_MONETARY
130 This category determines the formatting used for
131 monetary-related numeric values.
132 This changes the information returned by
133 .BR localeconv (3),
134 which describes the way numbers are usually printed, with details such
135 as decimal point versus decimal comma.
136 This information is internally
137 used by the function
138 .BR strfmon (3).
140 .B LC_MESSAGES
141 This category affects the language in which messages are displayed
142 and what an affirmative or negative answer looks like.
143 The GNU C library contains the
144 .BR gettext (3),
145 .BR ngettext (3),
147 .BR rpmatch (3)
148 functions to ease the use of this information.
149 The GNU gettext family of
150 functions also obey the environment variable
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""" .
155 This category also affects the behavior of
156 .BR catopen (3).
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).
168 .BR LC_NAME " (GNU extension, since glibc 2.2)"
169 .\" See ISO/IEC Technical Report 14652
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)
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> .)
184 .B LC_NUMERIC
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
191 .BR printf (3),
192 .BR scanf (3),
194 .BR strtod (3).
195 This information can also be read with the
196 .BR localeconv (3)
197 function.
199 .BR LC_PAPER " (GNU extension, since glibc 2.2)"
200 .\" See ISO/IEC Technical Report 14652
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
208 .B _NL_PAPER_HEIGHT
209 elements, which return
210 .I int
211 values specifying the dimensions in millimeters.
213 .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
214 .\" See ISO/IEC Technical Report 14652
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> .)
225 .B LC_TIME
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
228 12-hour clock used in the United States.
229 The setting of this category affects the behavior of functions such as
230 .BR strftime (3)
232 .BR strptime (3).
234 .B LC_ALL
235 All of the above.
237 If the second argument to
238 .BR setlocale (3)
239 is an empty string,
240 .IR """""" ,
241 for the default locale, it is determined using the following steps:
242 .IP 1. 3
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.
258 Values about local numeric formatting is made available in a
259 .I struct lconv
260 returned by the
261 .BR localeconv (3)
262 function, which has the following declaration:
264 .in +4n
266 struct lconv {
268     /* Numeric (nonmonetary) information */
270     char *decimal_point;     /* Radix character */
271     char *thousands_sep;     /* Separator for digit groups to left
272                                 of radix character */
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. */
281     /* Remaining fields are for monetary information */
283     char *int_curr_symbol;   /* First three chars are a currency
284                                 symbol from ISO 4217.  Fourth char
285                                 is the separator.  Fifth char
286                                 is \(aq\e0\(aq. */
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 */
293     char  int_frac_digits;   /* International fractional digits */
294     char  frac_digits;       /* Local fractional digits */
295     char  p_cs_precedes;     /* 1 if currency_symbol precedes a
296                                 positive value, 0 if succeeds */
297     char  p_sep_by_space;    /* 1 if a space separates
298                                 currency_symbol from a positive
299                                 value */
300     char  n_cs_precedes;     /* 1 if currency_symbol precedes a
301                                 negative value, 0 if succeeds */
302     char  n_sep_by_space;    /* 1 if a space separates
303                                 currency_symbol from a negative
304                                 value */
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;
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.
320 These extensions are designed to address the problem that
321 the traditional locale APIs do not mix well with multithreaded applications
322 and with applications that must deal with multiple locales.
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),
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.
337 .SH ENVIRONMENT
338 The following environment variable is used by
339 .BR newlocale (3)
341 .BR setlocale (3),
342 and thus affects all unprivileged localized programs:
344 .B LOCPATH
345 A list of pathnames, separated by colons (\(aq:\(aq),
346 that should be used to find locale data.
347 If this variable is set,
348 only the individual compiled locale data files from
349 .B LOCPATH
350 and the system default locale data path are used;
351 any available locale archives are not used (see
352 .BR localedef (1)).
353 The individual compiled locale data files are searched for under
354 subdirectories which depend on the currently used locale.
355 For example, when
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 ,
365 .IR en .
366 .SH FILES
368 .I /usr/lib/locale/locale\-archive
369 Usual default locale archive location.
371 .I /usr/lib/locale
372 Usual default path for compiled individual locale files.
373 .SH CONFORMING TO
374 POSIX.1-2001.
376 .\" The GNU gettext functions are specified in LI18NUX2000.
377 .SH SEE ALSO
378 .BR iconv (1),
379 .BR locale (1),
380 .BR localedef (1),
381 .BR catopen (3),
382 .BR gettext (3),
383 .BR iconv (3),
384 .BR localeconv (3),
385 .BR mbstowcs (3),
386 .BR newlocale (3),
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),
394 .BR strxfrm (3),
395 .BR uselocale (3),
396 .BR wcstombs (3),
397 .BR locale (5),
398 .BR charsets (7),
399 .BR unicode (7),
400 .BR utf\-8 (7)