| 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) |