1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
2 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
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>
31 .\" FIXME Document LOCPATH;
32 .\" see http://sourceware.org/bugzilla/show_bug.cgi?id=174
33 .\" Is removed for SUID/SGID programs (see sysdeps/generic/unsecvars.h)
34 .TH LOCALE 7 2014-03-18 "Linux" "Linux Programmer's Manual"
36 locale \- description of multilanguage support
39 .B #include <locale.h>
42 A locale is a set of language and cultural rules.
44 such as language for messages, different character sets, lexicographic
45 conventions, and so on.
46 A program needs to be able to determine its locale
47 and act accordingly to be portable to different cultures.
51 declares data types, functions and macros which are useful in this
54 The functions it declares are
56 to set the current locale, and
58 to get information about number formatting.
60 There are different categories for locale information a program might
61 need; they are declared as macros.
62 Using them as the first argument
65 function, it is possible to set one of these to the desired locale:
67 .BR LC_ADDRESS " (GNU extension, since glibc 2.2)"
68 .\" See ISO/IEC Technical Report 14652
69 Change settings that describe the formats (e.g., postal addresses)
70 used to describe locations and geography-related items.
71 Applications that need this information can use
73 to retrieve nonstandard elements, such as
74 .B _NL_ADDRESS_COUNTRY_NAME
75 (country name, in the language of the locale)
77 .B _NL_ADDRESS_LANG_NAME
78 (language name, in the language of the locale),
79 which return strings such as "Deutschland" and "Deutsch"
80 (for German-language locales).
81 (Other element names are listed in
85 This is used to change the behavior of the functions
89 which are used to compare strings in the local alphabet.
91 the German sharp s is sorted as "ss".
94 This changes the behavior of the character handling and
95 classification functions, such as
99 and the multibyte character functions such as
104 .BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
105 .\" See ISO/IEC Technical Report 14652
106 Change settings that relate to the metadata for the locale.
107 Applications that need this information can use
109 to retrieve nonstandard elements, such as
110 .B _NL_IDENTIFICATION_TITLE
111 (title of this locale document)
113 .B _NL_IDENTIFICATION_TERRITORY
114 (geographical territory to which this locale document applies),
115 which might return strings such as "English locale for the USA"
117 (Other element names are listed in
121 This changes the information returned by
123 which describes the way numbers are usually printed, with details such
124 as decimal point versus decimal comma.
125 This information is internally
130 This changes the language messages are displayed in and what an affirmative or
131 negative answer looks like.
132 The GNU C-library contains the
137 functions to ease the use of this information.
138 The GNU gettext family of
139 functions also obey the environment variable
141 (containing a colon-separated list of locales)
142 if the category is set to a valid locale other than
145 .BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)"
146 Change the settings relating to the measurement system in the locale
147 (i.e., metric versus US customary units).
150 to retrieve the nonstandard
151 .B _NL_MEASUREMENT_MEASUREMENT
152 element, which returns a pointer to a character
153 that has the value 1 (metric) or 2 (US customary units).
155 .BR LC_NAME " (GNU extension, since glibc 2.2)"
156 .\" See ISO/IEC Technical Report 14652
157 Change settings that describe the formats used to address persons.
158 Applications that need this information can use
160 to retrieve nonstandard elements, such as
162 (general salutation for men)
165 (general salutation for women)
166 elements, which return strings such as "Herr" and "Frau"
167 (for German-language locales).
168 (Other element names are listed in
172 This changes the information used by the
176 family of functions, when they are advised to use the locale settings.
177 This information can also be read with the
181 .BR LC_PAPER " (GNU extension, since glibc 2.2)"
182 .\" See ISO/IEC Technical Report 14652
183 Change the settings relating to the dimensions of the standard paper size
184 (e.g., US letter versus A4).
185 Applications that need the dimensions can obtain them by using
187 to retrieve the nonstandard
191 elements, which return
193 values specifying the dimensions in millimeters.
195 .BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
196 .\" See ISO/IEC Technical Report 14652
197 Change settings that describe the formats to be used with telephone services.
198 Applications that need this information can use
200 to retrieve nonstandard elements, such as
201 .B _NL_TELEPHONE_INT_PREFIX
202 (international prefix used to call numbers in this locale),
203 which returns a string such as "49" (for Germany).
204 (Other element names are listed in
208 This changes the behavior of the
210 function to display the current time in a locally acceptable form; for
211 example, most of Europe uses a 24-hour clock versus the
212 12-hour clock used in the United States.
217 If the second argument to
221 for the default locale, it is determined using the following steps:
223 If there is a non-null environment variable
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.
232 If there is a non-null environment variable
238 Values about local numeric formatting is made available in a
242 function, which has the following declaration:
248 /* Numeric (nonmonetary) information */
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 a
254 group; elements with higher indices are
255 further left. An element with value CHAR_MAX
256 means that no further grouping is done. An
257 element with value 0 means that the previous
258 element is used for all groups further left. */
260 /* Remaining fields are for monetary information */
262 char *int_curr_symbol; /* First three chars are a currency symbol
263 from ISO 4217. Fourth char is the
264 separator. Fifth char is \(aq\\0\(aq. */
265 char *currency_symbol; /* Local currency symbol */
266 char *mon_decimal_point; /* Radix character */
267 char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
268 char *mon_grouping; /* Like \fIgrouping\fP above */
269 char *positive_sign; /* Sign for positive values */
270 char *negative_sign; /* Sign for negative values */
271 char int_frac_digits; /* International fractional digits */
272 char frac_digits; /* Local fractional digits */
273 char p_cs_precedes; /* 1 if currency_symbol precedes a
274 positive value, 0 if succeeds */
275 char p_sep_by_space; /* 1 if a space separates currency_symbol
276 from a positive value */
277 char n_cs_precedes; /* 1 if currency_symbol precedes a
278 negative value, 0 if succeeds */
279 char n_sep_by_space; /* 1 if a space separates currency_symbol
280 from a negative value */
281 /* Positive and negative sign positions:
282 0 Parentheses surround the quantity and currency_symbol.
283 1 The sign string precedes the quantity and currency_symbol.
284 2 The sign string succeeds the quantity and currency_symbol.
285 3 The sign string immediately precedes the currency_symbol.
286 4 The sign string immediately succeeds the currency_symbol. */
292 .SS POSIX.1-2008 extensions to the locale API
293 POSIX.1-2008 standardized a number of extensions to the locale API,
294 based on implementations that first appeared in version 2.3
295 of the GNU C library.
296 These extensions are designed to address the problem that
297 the traditional locale APIs do not mix well with multithreaded applications
298 and with applications that must deal with multiple locales.
300 The extensions take the form of new functions for creating and
301 manipulating locale objects
307 and various new library functions with the suffix "_l" (e.g.,
309 that extend the traditional locale-dependent APIs (e.g.,
311 to allow the specification of a locale object that should apply when
312 executing the function.
316 .\" The GNU gettext functions are specified in LI18NUX2000.
337 This page is part of release 3.67 of the Linux
340 A description of the project,
341 information about reporting bugs,
342 and the latest version of this page,
344 \%http://www.kernel.org/doc/man\-pages/.