| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLLOCALE 1" |
| 58 |
.TH PERLLOCALE 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perllocale \- Perl locale handling (internationalization and localization) |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
In the beginning there was ASCII, the "American Standard Code for |
| 68 |
Information Interchange", which works quite well for Americans with |
| 69 |
their English alphabet and dollar-denominated currency (as long as they |
| 70 |
don't need the cents \f(CW\*(C`¢\*(C'\fR symbol, as it is not in ASCII)). But it |
| 71 |
doesn't work so well even for other English speakers, who may use |
| 72 |
different currencies, such as the pound sterling \f(CW\*(C`£\*(C'\fR (as the |
| 73 |
symbol for that currency is also not in ASCII); and it's hopelessly |
| 74 |
inadequate for many of the thousands of the world's other languages. |
| 75 |
.PP |
| 76 |
To address these deficiencies, the concept of locales was invented |
| 77 |
(formally the ISO C, XPG4, POSIX 1.c "locale system"). These allow for |
| 78 |
users to interface with their computer more according to their preferences. |
| 79 |
Applications were and are being written that use the locale mechanism. |
| 80 |
The process of making such an application take account of its users' |
| 81 |
preferences in these kinds of matters is called \fBinternationalization\fR |
| 82 |
(often abbreviated as \fBi18n\fR); telling such an application about a |
| 83 |
particular set of preferences is known as \fBlocalization\fR (\fBl10n\fR). |
| 84 |
.PP |
| 85 |
Perl has been extended to support certain types of locales available in |
| 86 |
the locale system. This is controlled per application by using one |
| 87 |
pragma, one function call, and several environment variables. |
| 88 |
.PP |
| 89 |
Perl supports single-byte locales that are supersets of ASCII, such as |
| 90 |
the ISO 8859 ones, and one multi-byte-type locale, UTF\-8 ones, described |
| 91 |
in the next paragraph. Perl doesn't support any other multi-byte |
| 92 |
locales, such as the ones for East Asian languages. |
| 93 |
.PP |
| 94 |
Unfortunately, there are quite a few deficiencies with the design (and |
| 95 |
often, the implementations) of locales. Unicode was invented (see |
| 96 |
perlunitut for an introduction to that) in part to address these |
| 97 |
design deficiencies, and nowadays, there is a series of "UTF\-8 |
| 98 |
locales", based on Unicode. These are locales whose character set is |
| 99 |
Unicode, encoded in UTF\-8. Starting in v5.20, Perl fully supports |
| 100 |
UTF\-8 locales, except for sorting and string comparisons like \f(CW\*(C`lt\*(C'\fR and |
| 101 |
\&\f(CW\*(C`ge\*(C'\fR. Starting in v5.26, Perl can handle these reasonably as well, |
| 102 |
depending on the platform's implementation. However, for earlier |
| 103 |
releases or for better control, use Unicode::Collate. |
| 104 |
.PP |
| 105 |
There are actually two slightly different types of UTF\-8 locales: one |
| 106 |
for Turkic languages and one for everything else. Starting in Perl |
| 107 |
v5.30, Perl detects UTF\-8 Turkic locales by their behaviour, and |
| 108 |
seamlessly handles both types; previously only the non-Turkic one was |
| 109 |
supported. The name of the locale is ignored; if your system has a |
| 110 |
\&\f(CW\*(C`tr_TR.UTF\-8\*(C'\fR locale and it doesn't behave like a Turkic locale, perl |
| 111 |
will treat it like a non-Turkic locale. |
| 112 |
.PP |
| 113 |
Perl continues to support the old non UTF\-8 locales as well. There are |
| 114 |
currently no UTF\-8 locales for EBCDIC platforms. |
| 115 |
.PP |
| 116 |
The perl interpreter is a C language program. At least stub locale |
| 117 |
support is required by the C language specification. So any instance of |
| 118 |
perl automatically has this. Later, the POSIX standard added more |
| 119 |
capabilities beyond the ones required by C. Perl supports these on the |
| 120 |
platforms where they are available. And Unicode supports a database of |
| 121 |
more types of information than the basic locale systems have. This |
| 122 |
database is called \f(CW\*(C`CLDR\*(C'\fR, the "Common Locale Data Repository", |
| 123 |
<http://cldr.unicode.org/>. There are various CPAN modules that |
| 124 |
provides access to this XML-encoded data, such as Locale::CLDR, |
| 125 |
CLDR::Number, and DateTime::Format::CLDR. |
| 126 |
.SH "WHAT IS A LOCALE" |
| 127 |
.IX Header "WHAT IS A LOCALE" |
| 128 |
A locale is a set of data that describes various aspects of how various |
| 129 |
communities in the world categorize their world. These categories are |
| 130 |
broken down into the following types (some of which include a brief |
| 131 |
note here): |
| 132 |
.ie n .IP "Category ""LC_NUMERIC"": Numeric formatting" 4 |
| 133 |
.el .IP "Category \f(CWLC_NUMERIC\fR: Numeric formatting" 4 |
| 134 |
.IX Item "Category LC_NUMERIC: Numeric formatting" |
| 135 |
This indicates how numbers should be formatted for human readability, |
| 136 |
for example the character used as the decimal point. |
| 137 |
.ie n .IP "Category ""LC_MONETARY"": Formatting of monetary amounts" 4 |
| 138 |
.el .IP "Category \f(CWLC_MONETARY\fR: Formatting of monetary amounts" 4 |
| 139 |
.IX Item "Category LC_MONETARY: Formatting of monetary amounts" |
| 140 |
|
| 141 |
.ie n .IP "Category ""LC_TIME"": Date/Time formatting" 4 |
| 142 |
.el .IP "Category \f(CWLC_TIME\fR: Date/Time formatting" 4 |
| 143 |
.IX Item "Category LC_TIME: Date/Time formatting" |
| 144 |
|
| 145 |
.ie n .IP "Category ""LC_COLLATE"": Collation" 4 |
| 146 |
.el .IP "Category \f(CWLC_COLLATE\fR: Collation" 4 |
| 147 |
.IX Item "Category LC_COLLATE: Collation" |
| 148 |
This indicates the ordering of letters for comparison and sorting. |
| 149 |
In Latin alphabets, for example, "b", generally follows "a". |
| 150 |
.ie n .IP "Category ""LC_CTYPE"": Character Types" 4 |
| 151 |
.el .IP "Category \f(CWLC_CTYPE\fR: Character Types" 4 |
| 152 |
.IX Item "Category LC_CTYPE: Character Types" |
| 153 |
This indicates, for example if a character is an uppercase letter. |
| 154 |
.ie n .IP "Category ""LC_MESSAGES"": Error and other messages" 4 |
| 155 |
.el .IP "Category \f(CWLC_MESSAGES\fR: Error and other messages" 4 |
| 156 |
.IX Item "Category LC_MESSAGES: Error and other messages" |
| 157 |
This is a POSIX extension beyond the basic C language required |
| 158 |
categories. On Windows and other non-POSIX platforms, perl uses |
| 159 |
workarounds to simulate it. |
| 160 |
.ie n .IP "Category ""LC_TIME"": Date/Time formatting" 4 |
| 161 |
.el .IP "Category \f(CWLC_TIME\fR: Date/Time formatting" 4 |
| 162 |
.IX Item "Category LC_TIME: Date/Time formatting" |
| 163 |
|
| 164 |
.ie n .IP "Category ""LC_ALL""" 4 |
| 165 |
.el .IP "Category \f(CWLC_ALL\fR" 4 |
| 166 |
.IX Item "Category LC_ALL" |
| 167 |
This is not an actual category, but a convenience short-hand to refer to |
| 168 |
all of the actual ones. |
| 169 |
.IP "Other categories" 4 |
| 170 |
.IX Item "Other categories" |
| 171 |
Some platforms have other categories, dealing with such things as |
| 172 |
measurement units and paper sizes. None of these are used directly by |
| 173 |
Perl, but outside operations that Perl interacts with may use |
| 174 |
these. See "Not within the scope of "use locale"" below. |
| 175 |
.PP |
| 176 |
More details on the categories used by Perl are given below in "LOCALE |
| 177 |
CATEGORIES". |
| 178 |
.PP |
| 179 |
Together, these categories go a long way towards being able to customize |
| 180 |
a single program to run in many different locations. And adding Unicode |
| 181 |
CLDR goes further. But there are deficiencies, so keep reading. |
| 182 |
.SH "PREPARING TO USE LOCALES" |
| 183 |
.IX Header "PREPARING TO USE LOCALES" |
| 184 |
Perl itself (outside the POSIX module) will not use locales unless |
| 185 |
specifically requested to (but |
| 186 |
again note that Perl may interact with code that does use them). Even |
| 187 |
if there is such a request, \fBall\fR of the following must be true |
| 188 |
for it to work properly: |
| 189 |
.IP \(bu 4 |
| 190 |
\&\fBPerl must believe that the locale system is supported\fR. If it does, |
| 191 |
\&\f(CW\*(C`perl \-V:d_setlocale\*(C'\fR will say that the value for \f(CW\*(C`d_setlocale\*(C'\fR is |
| 192 |
\&\f(CW\*(C`define\*(C'\fR. |
| 193 |
.IP \(bu 4 |
| 194 |
\&\fBDefinitions for the locales that you use must be installed\fR. All |
| 195 |
platforms that perl runs on are required to support at least one locale, |
| 196 |
named "C", which is essentially ASCII, and typical American preferences. |
| 197 |
.Sp |
| 198 |
Most platforms allow for additional locales, but these must be |
| 199 |
specifically installed. You, or your system administrator, must make |
| 200 |
sure that any locales you want are installed. The available locales, |
| 201 |
the location in which they are kept, and the manner in which they are |
| 202 |
installed all vary from system to system. Some systems provide only a |
| 203 |
few, hard-wired locales and do not allow more to be added. Others allow |
| 204 |
you to add "canned" locales provided by the system supplier. Still |
| 205 |
others allow you or the system administrator to define and add arbitrary |
| 206 |
locales. (You may have to ask your supplier to provide canned locales |
| 207 |
that are not delivered with your operating system.) Read your system |
| 208 |
documentation for further illumination. |
| 209 |
.PP |
| 210 |
If you want a Perl application to process and present your data |
| 211 |
according to a particular locale, the application code should include |
| 212 |
the \f(CW\*(C`use\ locale\*(C'\fR pragma (see "The "use locale" pragma") where |
| 213 |
appropriate, and \fBat least one\fR of the following must be true: |
| 214 |
.IP 1. 4 |
| 215 |
\&\fBThe locale-determining environment variables (see "ENVIRONMENT") |
| 216 |
must be correctly set up\fR at the time the application is started, either |
| 217 |
by yourself or by whomever set up your system account; or |
| 218 |
.IP 2. 4 |
| 219 |
\&\fBThe application must set its own locale\fR using the method described in |
| 220 |
"The setlocale function". |
| 221 |
.SH "USING LOCALES" |
| 222 |
.IX Header "USING LOCALES" |
| 223 |
.ie n .SS "The ""use locale"" pragma" |
| 224 |
.el .SS "The \f(CW""use locale""\fP pragma" |
| 225 |
.IX Subsection "The ""use locale"" pragma" |
| 226 |
By default, Perl itself (outside the POSIX module) |
| 227 |
ignores the current locale. The \f(CW\*(C`use\ locale\*(C'\fR |
| 228 |
pragma tells Perl to use the current locale for some operations. |
| 229 |
Starting in v5.16, there are optional parameters to this pragma, |
| 230 |
described below, which restrict which operations are affected by it. |
| 231 |
.PP |
| 232 |
Starting in Perl 5.28, this pragma may be used in |
| 233 |
multi-threaded applications on systems that have thread-safe |
| 234 |
locale ability. Some caveats apply, see "Multi-threaded" below. On |
| 235 |
systems without this capability, or in earlier Perls, do NOT use this |
| 236 |
pragma in scripts that have multiple threads active. The |
| 237 |
locale in these cases is not local to a single thread. Another thread |
| 238 |
may change the locale at any time, which could cause at a minimum that a |
| 239 |
given thread is operating in a locale it isn't expecting to be in. On |
| 240 |
some platforms, segfaults can also occur. The locale change need not be |
| 241 |
explicit; some operations cause perl itself to change the locale. You |
| 242 |
are vulnerable simply by having done a \f(CW"use\ locale"\fR. |
| 243 |
.PP |
| 244 |
The current locale is set at execution time by |
| 245 |
\&\fBsetlocale()\fR described below. If that function |
| 246 |
hasn't yet been called in the course of the program's execution, the |
| 247 |
current locale is that which was determined by the "ENVIRONMENT" in |
| 248 |
effect at the start of the program. |
| 249 |
If there is no valid environment, the current locale is whatever the |
| 250 |
system default has been set to. On POSIX systems, it is likely, but |
| 251 |
not necessarily, the "C" locale. On Windows, the default is set via the |
| 252 |
computer's \f(CW\*(C`Control\ Panel\->Regional\ and\ Language\ Options\*(C'\fR (or its |
| 253 |
current equivalent). |
| 254 |
.PP |
| 255 |
The operations that are affected by locale are: |
| 256 |
.ie n .IP "\fBNot within the scope of \fR\fB""use locale""\fR" 4 |
| 257 |
.el .IP "\fBNot within the scope of \fR\f(CB""use locale""\fR" 4 |
| 258 |
.IX Item "Not within the scope of ""use locale""" |
| 259 |
Only certain operations (all originating outside Perl) should be |
| 260 |
affected, as follows: |
| 261 |
.RS 4 |
| 262 |
.IP \(bu 4 |
| 263 |
The current locale is used when going outside of Perl with |
| 264 |
operations like \fBsystem()\fR or |
| 265 |
qx//, if those operations are |
| 266 |
locale-sensitive. |
| 267 |
.IP \(bu 4 |
| 268 |
Also Perl gives access to various C library functions through the |
| 269 |
POSIX module. Some of those functions are always affected by the |
| 270 |
current locale. For example, \f(CWPOSIX::strftime()\fR uses \f(CW\*(C`LC_TIME\*(C'\fR; |
| 271 |
\&\f(CWPOSIX::strtod()\fR uses \f(CW\*(C`LC_NUMERIC\*(C'\fR; \f(CWPOSIX::strcoll()\fR and |
| 272 |
\&\f(CWPOSIX::strxfrm()\fR use \f(CW\*(C`LC_COLLATE\*(C'\fR. All such functions |
| 273 |
will behave according to the current underlying locale, even if that |
| 274 |
locale isn't exposed to Perl space. |
| 275 |
.Sp |
| 276 |
This applies as well to I18N::Langinfo. |
| 277 |
.IP \(bu 4 |
| 278 |
XS modules for all categories but \f(CW\*(C`LC_NUMERIC\*(C'\fR get the underlying |
| 279 |
locale, and hence any C library functions they call will use that |
| 280 |
underlying locale. For more discussion, see |
| 281 |
"Dealing with locales" in perlclib. |
| 282 |
.RE |
| 283 |
.RS 4 |
| 284 |
.Sp |
| 285 |
Note that all C programs (including the perl interpreter, which is |
| 286 |
written in C) always have an underlying locale. That locale is the "C" |
| 287 |
locale unless changed by a call to \fBsetlocale()\fR. When Perl starts up, it changes the underlying locale to the |
| 288 |
one which is indicated by the "ENVIRONMENT". When using the POSIX |
| 289 |
module or writing XS code, it is important to keep in mind that the |
| 290 |
underlying locale may be something other than "C", even if the program |
| 291 |
hasn't explicitly changed it. |
| 292 |
.Sp |
| 293 |
|
| 294 |
.RE |
| 295 |
.ie n .IP "\fBLingering effects of \fR\fB""use\ locale""\fR" 4 |
| 296 |
.el .IP "\fBLingering effects of \fR\f(CBuse\ locale\fR" 4 |
| 297 |
.IX Item "Lingering effects of use locale" |
| 298 |
Certain Perl operations that are set-up within the scope of a |
| 299 |
\&\f(CW\*(C`use locale\*(C'\fR retain that effect even outside the scope. |
| 300 |
These include: |
| 301 |
.RS 4 |
| 302 |
.IP \(bu 4 |
| 303 |
The output format of a \fBwrite()\fR is determined by an |
| 304 |
earlier format declaration ("format" in perlfunc), so whether or not the |
| 305 |
output is affected by locale is determined by if the \f(CWformat()\fR is |
| 306 |
within the scope of a \f(CW\*(C`use locale\*(C'\fR, not whether the \f(CWwrite()\fR |
| 307 |
is. |
| 308 |
.IP \(bu 4 |
| 309 |
Regular expression patterns can be compiled using |
| 310 |
qr// with actual |
| 311 |
matching deferred to later. Again, it is whether or not the compilation |
| 312 |
was done within the scope of \f(CW\*(C`use locale\*(C'\fR that determines the match |
| 313 |
behavior, not if the matches are done within such a scope or not. |
| 314 |
.RE |
| 315 |
.RS 4 |
| 316 |
.Sp |
| 317 |
|
| 318 |
.RE |
| 319 |
.ie n .IP "\fBUnder \fR\fB""""use locale"";""\fR" 4 |
| 320 |
.el .IP "\fBUnder \fR\f(CB""use locale"";\fR" 4 |
| 321 |
.IX Item "Under ""use locale"";" |
| 322 |
.RS 4 |
| 323 |
.PD 0 |
| 324 |
.IP \(bu 4 |
| 325 |
.PD |
| 326 |
All the above operations |
| 327 |
.IP \(bu 4 |
| 328 |
\&\fBFormat declarations\fR ("format" in perlfunc) and hence any subsequent |
| 329 |
\&\f(CWwrite()\fRs use \f(CW\*(C`LC_NUMERIC\*(C'\fR. |
| 330 |
.IP \(bu 4 |
| 331 |
\&\fBstringification and output\fR use \f(CW\*(C`LC_NUMERIC\*(C'\fR. |
| 332 |
These include the results of |
| 333 |
\&\f(CWprint()\fR, |
| 334 |
\&\f(CWprintf()\fR, |
| 335 |
\&\f(CWsay()\fR, |
| 336 |
and |
| 337 |
\&\f(CWsprintf()\fR. |
| 338 |
.IP \(bu 4 |
| 339 |
\&\fBThe comparison operators\fR (\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`le\*(C'\fR, \f(CW\*(C`cmp\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, and \f(CW\*(C`gt\*(C'\fR) use |
| 340 |
\&\f(CW\*(C`LC_COLLATE\*(C'\fR. \f(CWsort()\fR is also affected if used without an |
| 341 |
explicit comparison function, because it uses \f(CW\*(C`cmp\*(C'\fR by default. |
| 342 |
.Sp |
| 343 |
\&\fBNote:\fR \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR are unaffected by locale: they always |
| 344 |
perform a char-by-char comparison of their scalar operands. What's |
| 345 |
more, if \f(CW\*(C`cmp\*(C'\fR finds that its operands are equal according to the |
| 346 |
collation sequence specified by the current locale, it goes on to |
| 347 |
perform a char-by-char comparison, and only returns \fI0\fR (equal) if the |
| 348 |
operands are char-for-char identical. If you really want to know whether |
| 349 |
two strings\-\-which \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR may consider different\-\-are equal |
| 350 |
as far as collation in the locale is concerned, see the discussion in |
| 351 |
"Category \f(CW\*(C`LC_COLLATE\*(C'\fR: Collation". |
| 352 |
.IP \(bu 4 |
| 353 |
\&\fBRegular expressions and case-modification functions\fR (\f(CWuc()\fR, \f(CWlc()\fR, |
| 354 |
\&\f(CWucfirst()\fR, and \f(CWlcfirst()\fR) use \f(CW\*(C`LC_CTYPE\*(C'\fR |
| 355 |
.IP \(bu 4 |
| 356 |
\&\fBThe variables \fR\f(CB$!\fR (and its synonyms \f(CW$ERRNO\fR and |
| 357 |
\&\f(CW$OS_ERROR\fR) \fBand\fR \f(CW$^E\fR> (and its synonym |
| 358 |
\&\f(CW$EXTENDED_OS_ERROR\fR) when used as strings use \f(CW\*(C`LC_MESSAGES\*(C'\fR On |
| 359 |
platforms that lack this category \f(CW\*(C`LC_CTYPE\*(C'\fR is used instead. |
| 360 |
.RE |
| 361 |
.RS 4 |
| 362 |
.RE |
| 363 |
.PP |
| 364 |
The default behavior is restored with the \f(CW\*(C`no\ locale\*(C'\fR pragma, or |
| 365 |
upon reaching the end of the block enclosing \f(CW\*(C`use locale\*(C'\fR. |
| 366 |
Note that \f(CW\*(C`use locale\*(C'\fR calls may be |
| 367 |
nested, and that what is in effect within an inner scope will revert to |
| 368 |
the outer scope's rules at the end of the inner scope. |
| 369 |
.PP |
| 370 |
The string result of any operation that uses locale |
| 371 |
information is tainted (if your perl supports taint checking), |
| 372 |
as it is possible for a locale to be untrustworthy. |
| 373 |
See "SECURITY". |
| 374 |
.PP |
| 375 |
Starting in Perl v5.16 in a very limited way, and more generally in |
| 376 |
v5.22, you can restrict which category or categories are enabled by this |
| 377 |
particular instance of the pragma by adding parameters to it. (This |
| 378 |
capability was to enable you to write code to work around deficiencies in |
| 379 |
perl's locale handling, which have since been corrected, so it is |
| 380 |
unlikely that new code will need to use it.) |
| 381 |
.PP |
| 382 |
For example, |
| 383 |
.PP |
| 384 |
.Vb 1 |
| 385 |
\& use locale qw(:ctype :numeric); |
| 386 |
.Ve |
| 387 |
.PP |
| 388 |
enables locale awareness within its scope of only those operations |
| 389 |
(listed above) that are affected by \f(CW\*(C`LC_CTYPE\*(C'\fR and \f(CW\*(C`LC_NUMERIC\*(C'\fR. |
| 390 |
.PP |
| 391 |
The possible categories are: \f(CW\*(C`:collate\*(C'\fR, \f(CW\*(C`:ctype\*(C'\fR, \f(CW\*(C`:messages\*(C'\fR, |
| 392 |
\&\f(CW\*(C`:monetary\*(C'\fR, \f(CW\*(C`:numeric\*(C'\fR, \f(CW\*(C`:time\*(C'\fR, and the pseudo category |
| 393 |
\&\f(CW\*(C`:characters\*(C'\fR (described below). |
| 394 |
.PP |
| 395 |
Thus you can say |
| 396 |
.PP |
| 397 |
.Vb 1 |
| 398 |
\& use locale \*(Aq:messages\*(Aq; |
| 399 |
.Ve |
| 400 |
.PP |
| 401 |
and only \f(CW"$!"\fR and \f(CW"$^E"\fR |
| 402 |
will be locale aware. Everything else is unaffected. |
| 403 |
.PP |
| 404 |
Since Perl doesn't currently do anything with the \f(CW\*(C`LC_MONETARY\*(C'\fR |
| 405 |
category, specifying \f(CW\*(C`:monetary\*(C'\fR does effectively nothing. Some |
| 406 |
systems have other categories, such as \f(CW\*(C`LC_PAPER\*(C'\fR, but the perl core |
| 407 |
doesn't do anything with them, and there is no way to specify |
| 408 |
them in this pragma's arguments. |
| 409 |
.PP |
| 410 |
You can also easily say to use all categories but one, by either, for |
| 411 |
example, |
| 412 |
.PP |
| 413 |
.Vb 2 |
| 414 |
\& use locale \*(Aq:!ctype\*(Aq; |
| 415 |
\& use locale \*(Aq:not_ctype\*(Aq; |
| 416 |
.Ve |
| 417 |
.PP |
| 418 |
both of which mean to enable locale awareness of all categories but |
| 419 |
\&\f(CW\*(C`LC_CTYPE\*(C'\fR. Only one category argument may be specified in a |
| 420 |
\&\f(CW\*(C`use\ locale\*(C'\fR if it is of the negated form. |
| 421 |
.PP |
| 422 |
Prior to v5.22 only one form of the pragma with arguments is available: |
| 423 |
.PP |
| 424 |
.Vb 1 |
| 425 |
\& use locale \*(Aq:not_characters\*(Aq; |
| 426 |
.Ve |
| 427 |
.PP |
| 428 |
(and you have to say \f(CW\*(C`not_\*(C'\fR; you can't use the bang \f(CW\*(C`!\*(C'\fR form). This |
| 429 |
pseudo category is a shorthand for specifying both \f(CW\*(C`:collate\*(C'\fR and |
| 430 |
\&\f(CW\*(C`:ctype\*(C'\fR. Hence, in the negated form, it is nearly the same thing as |
| 431 |
saying |
| 432 |
.PP |
| 433 |
.Vb 1 |
| 434 |
\& use locale qw(:messages :monetary :numeric :time); |
| 435 |
.Ve |
| 436 |
.PP |
| 437 |
We use the term "nearly", because \f(CW\*(C`:not_characters\*(C'\fR also turns on |
| 438 |
\&\f(CW\*(C`use\ feature\ \*(Aqunicode_strings\*(Aq\*(C'\fR within its scope. This form is |
| 439 |
less useful in v5.20 and later, and is described fully in |
| 440 |
"Unicode and UTF\-8", but briefly, it tells Perl to not use the |
| 441 |
character portions of the locale definition, that is the \f(CW\*(C`LC_CTYPE\*(C'\fR and |
| 442 |
\&\f(CW\*(C`LC_COLLATE\*(C'\fR categories. Instead it will use the native character set |
| 443 |
(extended by Unicode). When using this parameter, you are responsible |
| 444 |
for getting the external character set translated into the |
| 445 |
native/Unicode one (which it already will be if it is one of the |
| 446 |
increasingly popular UTF\-8 locales). There are convenient ways of doing |
| 447 |
this, as described in "Unicode and UTF\-8". |
| 448 |
.SS "The setlocale function" |
| 449 |
.IX Subsection "The setlocale function" |
| 450 |
WARNING! Prior to Perl 5.28 or on a system that does not support |
| 451 |
thread-safe locale operations, do NOT use this function in a |
| 452 |
thread. The locale will change in all other threads at the |
| 453 |
same time, and should your thread get paused by the operating system, |
| 454 |
and another started, that thread will not have the locale it is |
| 455 |
expecting. On some platforms, there can be a race leading to segfaults |
| 456 |
if two threads call this function nearly simultaneously. This warning |
| 457 |
does not apply on unthreaded builds, or on perls where |
| 458 |
\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR exists and is non-zero; namely Perl 5.28 and later |
| 459 |
unthreaded or compiled to be locale-thread-safe. On z/OS systems, this |
| 460 |
function becomes a no-op once any thread is started. Thus, on that |
| 461 |
system, you can set up the locale before creating any threads, and that |
| 462 |
locale will be the one in effect for the entire program. |
| 463 |
.PP |
| 464 |
Otherwise, you can switch locales as often as you wish at run time with |
| 465 |
the \f(CWPOSIX::setlocale()\fR function: |
| 466 |
.PP |
| 467 |
.Vb 6 |
| 468 |
\& # Import locale\-handling tool set from POSIX module. |
| 469 |
\& # This example uses: setlocale \-\- the function call |
| 470 |
\& # LC_CTYPE \-\- explained below |
| 471 |
\& # (Showing the testing for success/failure of operations is |
| 472 |
\& # omitted in these examples to avoid distracting from the main |
| 473 |
\& # point) |
| 474 |
\& |
| 475 |
\& use POSIX qw(locale_h); |
| 476 |
\& use locale; |
| 477 |
\& my $old_locale; |
| 478 |
\& |
| 479 |
\& # query and save the old locale |
| 480 |
\& $old_locale = setlocale(LC_CTYPE); |
| 481 |
\& |
| 482 |
\& setlocale(LC_CTYPE, "fr_CA.ISO8859\-1"); |
| 483 |
\& # LC_CTYPE now in locale "French, Canada, codeset ISO 8859\-1" |
| 484 |
\& |
| 485 |
\& setlocale(LC_CTYPE, ""); |
| 486 |
\& # LC_CTYPE now reset to the default defined by the |
| 487 |
\& # LC_ALL/LC_CTYPE/LANG environment variables, or to the system |
| 488 |
\& # default. See below for documentation. |
| 489 |
\& |
| 490 |
\& # restore the old locale |
| 491 |
\& setlocale(LC_CTYPE, $old_locale); |
| 492 |
.Ve |
| 493 |
.PP |
| 494 |
The first argument of \f(CWsetlocale()\fR gives the \fBcategory\fR, the second the |
| 495 |
\&\fBlocale\fR. The category tells in what aspect of data processing you |
| 496 |
want to apply locale-specific rules. Category names are discussed in |
| 497 |
"LOCALE CATEGORIES" and "ENVIRONMENT". The locale is the name of a |
| 498 |
collection of customization information corresponding to a particular |
| 499 |
combination of language, country or territory, and codeset. Read on for |
| 500 |
hints on the naming of locales: not all systems name locales as in the |
| 501 |
example. |
| 502 |
.PP |
| 503 |
If no second argument is provided and the category is something other |
| 504 |
than \f(CW\*(C`LC_ALL\*(C'\fR, the function returns a string naming the current locale |
| 505 |
for the category. You can use this value as the second argument in a |
| 506 |
subsequent call to \f(CWsetlocale()\fR, \fBbut\fR on some platforms the string |
| 507 |
is opaque, not something that most people would be able to decipher as |
| 508 |
to what locale it means. |
| 509 |
.PP |
| 510 |
If no second argument is provided and the category is \f(CW\*(C`LC_ALL\*(C'\fR, the |
| 511 |
result is implementation-dependent. It may be a string of |
| 512 |
concatenated locale names (separator also implementation-dependent) |
| 513 |
or a single locale name. Please consult your \fBsetlocale\fR\|(3) man page for |
| 514 |
details. |
| 515 |
.PP |
| 516 |
If a second argument is given and it corresponds to a valid locale, |
| 517 |
the locale for the category is set to that value, and the function |
| 518 |
returns the now-current locale value. You can then use this in yet |
| 519 |
another call to \f(CWsetlocale()\fR. (In some implementations, the return |
| 520 |
value may sometimes differ from the value you gave as the second |
| 521 |
argument\-\-think of it as an alias for the value you gave.) |
| 522 |
.PP |
| 523 |
As the example shows, if the second argument is an empty string, the |
| 524 |
category's locale is returned to the default specified by the |
| 525 |
corresponding environment variables. Generally, this results in a |
| 526 |
return to the default that was in force when Perl started up: changes |
| 527 |
to the environment made by the application after startup may or may not |
| 528 |
be noticed, depending on your system's C library. |
| 529 |
.PP |
| 530 |
Note that when a form of \f(CW\*(C`use locale\*(C'\fR that doesn't include all |
| 531 |
categories is specified, Perl ignores the excluded categories. |
| 532 |
.PP |
| 533 |
If \f(CWsetlocale()\fR fails for some reason (for example, an attempt to set |
| 534 |
to a locale unknown to the system), the locale for the category is not |
| 535 |
changed, and the function returns \f(CW\*(C`undef\*(C'\fR. |
| 536 |
.PP |
| 537 |
Starting in Perl 5.28, on multi-threaded perls compiled on systems that |
| 538 |
implement POSIX 2008 thread-safe locale operations, this function |
| 539 |
doesn't actually call the system \f(CW\*(C`setlocale\*(C'\fR. Instead those |
| 540 |
thread-safe operations are used to emulate the \f(CW\*(C`setlocale\*(C'\fR function, |
| 541 |
but in a thread-safe manner. |
| 542 |
.PP |
| 543 |
You can force the thread-safe locale operations to always be used (if |
| 544 |
available) by recompiling perl with |
| 545 |
.PP |
| 546 |
.Vb 1 |
| 547 |
\& \-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq |
| 548 |
.Ve |
| 549 |
.PP |
| 550 |
added to your call to \fIConfigure\fR. |
| 551 |
.PP |
| 552 |
For further information about the categories, consult \fBsetlocale\fR\|(3). |
| 553 |
.SS "Multi-threaded operation" |
| 554 |
.IX Subsection "Multi-threaded operation" |
| 555 |
Beginning in Perl 5.28, multi-threaded locale operation is supported on |
| 556 |
systems that implement either the POSIX 2008 or Windows-specific |
| 557 |
thread-safe locale operations. Many modern systems, such as various |
| 558 |
Unix variants do have this. Others, such as most *BSD\-derived variants, |
| 559 |
including Darwin, claim to have it, but are buggy as of May 2024, so |
| 560 |
Perl avoids their use. |
| 561 |
.PP |
| 562 |
You can tell if using locales is safe on your system by looking at the |
| 563 |
read-only variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR. The value is 1 if the |
| 564 |
perl is not threaded, or if it is using thread-safe locale operations. |
| 565 |
.PP |
| 566 |
Thread-safe operations are supported in Windows starting in Visual Studio |
| 567 |
2005, in cygwin, in MingW compiled to use UCRT (the Universal C Run Time |
| 568 |
library), and in systems compatible with POSIX 2008. |
| 569 |
\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR will be 0 on threaded builds on platforms that Perl |
| 570 |
knows to have buggy implementations. |
| 571 |
.PP |
| 572 |
Be aware that writing a multi-threaded application will not be portable |
| 573 |
to a platform which lacks the native thread-safe locale support. On |
| 574 |
systems that do have it, you automatically get this behavior for |
| 575 |
threaded perls, without having to do anything. If for some reason, you |
| 576 |
don't want to use this capability (perhaps the POSIX 2008 support turns |
| 577 |
out to be buggy on your system), you can manually compile Perl to use |
| 578 |
the old non-thread-safe implementation by passing the argument |
| 579 |
\&\f(CW\*(C`\-Accflags=\*(Aq\-DNO_THREAD_SAFE_LOCALE\*(Aq\*(C'\fR to \fIConfigure\fR. Except on |
| 580 |
Windows, this will continue to use certain of the POSIX 2008 functions |
| 581 |
in some situations. If these are buggy, you can pass the following to |
| 582 |
\&\fIConfigure\fR instead or additionally: |
| 583 |
\&\f(CW\*(C`\-Accflags=\*(Aq\-DNO_POSIX_2008_LOCALE\*(Aq\*(C'\fR. This will also keep the code |
| 584 |
from using thread-safe locales. |
| 585 |
\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR will be 0 on systems that turn off the thread-safe |
| 586 |
operations. |
| 587 |
.PP |
| 588 |
Normally on unthreaded builds, Perl uses the traditional \f(CWsetlocale()\fR |
| 589 |
to change the locale, and not the alternate POSIX 2008 thread-safe |
| 590 |
locale-changing functions. You can force the use of these on systems |
| 591 |
that have them by adding the \f(CW\*(C`\-Accflags=\*(Aq\-DUSE_THREAD_SAFE_LOCALE\*(Aq\*(C'\fR to |
| 592 |
\&\fIConfigure\fR. |
| 593 |
.PP |
| 594 |
The initial program is started up using the locale specified from the |
| 595 |
environment, as currently, described in "ENVIRONMENT". All newly |
| 596 |
created threads start with \f(CW\*(C`LC_ALL\*(C'\fR set to \f(CW"C"\fR. Each thread may |
| 597 |
use \f(CWPOSIX::setlocale()\fR to query or switch its locale at any time, |
| 598 |
without affecting any other thread. All locale-dependent operations |
| 599 |
automatically use their thread's locale. |
| 600 |
.PP |
| 601 |
This should be completely transparent to any applications written |
| 602 |
entirely in Perl (minus a few rarely encountered caveats given in the |
| 603 |
"Multi-threaded" section). Information for XS module writers is given |
| 604 |
in "Dealing with locales" in perlclib. |
| 605 |
.SS "Finding locales" |
| 606 |
.IX Subsection "Finding locales" |
| 607 |
For locales available in your system, consult also \fBsetlocale\fR\|(3) to |
| 608 |
see whether it leads to the list of available locales (search for the |
| 609 |
\&\fISEE ALSO\fR section). If that fails, try the following command lines: |
| 610 |
.PP |
| 611 |
.Vb 1 |
| 612 |
\& locale \-a |
| 613 |
\& |
| 614 |
\& nlsinfo |
| 615 |
\& |
| 616 |
\& ls /usr/lib/nls/loc |
| 617 |
\& |
| 618 |
\& ls /usr/lib/locale |
| 619 |
\& |
| 620 |
\& ls /usr/lib/nls |
| 621 |
\& |
| 622 |
\& ls /usr/share/locale |
| 623 |
.Ve |
| 624 |
.PP |
| 625 |
and see whether they list something resembling these |
| 626 |
.PP |
| 627 |
.Vb 7 |
| 628 |
\& en_US.ISO8859\-1 de_DE.ISO8859\-1 ru_RU.ISO8859\-5 |
| 629 |
\& en_US.iso88591 de_DE.iso88591 ru_RU.iso88595 |
| 630 |
\& en_US de_DE ru_RU |
| 631 |
\& en de ru |
| 632 |
\& english german russian |
| 633 |
\& english.iso88591 german.iso88591 russian.iso88595 |
| 634 |
\& english.roman8 russian.koi8r |
| 635 |
.Ve |
| 636 |
.PP |
| 637 |
Sadly, even though the calling interface for \f(CWsetlocale()\fR has been |
| 638 |
standardized, names of locales and the directories where the |
| 639 |
configuration resides have not been. The basic form of the name is |
| 640 |
\&\fIlanguage[_territory[.codeset]][@modifier]\fR. |
| 641 |
The \fIlanguage\fR and \fIcountry\fR |
| 642 |
are usually from the standards \fBISO 3166\fR and \fBISO 639\fR, the |
| 643 |
two-letter abbreviations for the countries and the languages of the |
| 644 |
world, respectively. The \fIcodeset\fR part often mentions some \fBISO |
| 645 |
8859\fR character set, the Latin codesets. For example, \f(CW\*(C`ISO 8859\-1\*(C'\fR |
| 646 |
is the so-called "Western European codeset" that can be used to encode |
| 647 |
most Western European languages adequately. Again, there are several |
| 648 |
ways to write even the name of that one standard. Lamentably. |
| 649 |
\&\fImodifier\fR is very individualized to the rest of the locale, naming |
| 650 |
some variant, such as a different currency symbol than the locale would |
| 651 |
normally contain. |
| 652 |
.PP |
| 653 |
Two special locales are worth particular mention: "C" and "POSIX". |
| 654 |
Currently these are effectively the same locale: the difference is |
| 655 |
mainly that the first one is defined by the C standard, the second by |
| 656 |
the POSIX standard. They define the \fBdefault locale\fR in which |
| 657 |
every program starts in the absence of locale information in its |
| 658 |
environment. (The \fIdefault\fR default locale, if you will.) Its language |
| 659 |
is (American) English and its character codeset ASCII or, rarely, a |
| 660 |
superset thereof (such as the "DEC Multinational Character Set |
| 661 |
(DEC-MCS)"). \fBWarning\fR. The C locale delivered by some vendors |
| 662 |
may not actually exactly match what the C standard calls for. So |
| 663 |
beware. |
| 664 |
.PP |
| 665 |
\&\fBNOTE\fR: Not all systems have the "POSIX" locale (not all systems are |
| 666 |
POSIX-conformant), so use "C" when you need explicitly to specify this |
| 667 |
default locale. |
| 668 |
.SS "LOCALE PROBLEMS" |
| 669 |
.IX Subsection "LOCALE PROBLEMS" |
| 670 |
You may encounter the following warning message at Perl startup: |
| 671 |
.PP |
| 672 |
.Vb 6 |
| 673 |
\& perl: warning: Setting locale failed. |
| 674 |
\& perl: warning: Please check that your locale settings: |
| 675 |
\& LC_ALL = "En_US", |
| 676 |
\& LANG = (unset) |
| 677 |
\& are supported and installed on your system. |
| 678 |
\& perl: warning: Falling back to the standard locale ("C"). |
| 679 |
.Ve |
| 680 |
.PP |
| 681 |
This means that your locale settings had \f(CW\*(C`LC_ALL\*(C'\fR set to "En_US" and |
| 682 |
LANG exists but has no value. Perl tried to believe you but could not. |
| 683 |
Instead, Perl gave up and fell back to the "C" locale, the default locale |
| 684 |
that is supposed to work no matter what. (On Windows, it first tries |
| 685 |
falling back to the system default locale.) This usually means your |
| 686 |
locale settings were wrong, they mention locales your system has never |
| 687 |
heard of, or the locale installation in your system has problems (for |
| 688 |
example, some system files are broken or missing). There are quick and |
| 689 |
temporary fixes to these problems, as well as more thorough and lasting |
| 690 |
fixes. |
| 691 |
.PP |
| 692 |
\fITesting for broken locales\fR |
| 693 |
.IX Subsection "Testing for broken locales" |
| 694 |
.PP |
| 695 |
If you are building Perl from source, the Perl test suite file |
| 696 |
\&\fIlib/locale.t\fR can be used to test the locales on your system. |
| 697 |
Setting the environment variable \f(CW\*(C`PERL_DEBUG_FULL_TEST\*(C'\fR to 1 |
| 698 |
will cause it to output detailed results. For example, on Linux, you |
| 699 |
could say |
| 700 |
.PP |
| 701 |
.Vb 1 |
| 702 |
\& PERL_DEBUG_FULL_TEST=1 ./perl \-T \-Ilib lib/locale.t > locale.log 2>&1 |
| 703 |
.Ve |
| 704 |
.PP |
| 705 |
Besides many other tests, it will test every locale it finds on your |
| 706 |
system to see if they conform to the POSIX standard. If any have |
| 707 |
errors, it will include a summary near the end of the output of which |
| 708 |
locales passed all its tests, and which failed, and why. |
| 709 |
.PP |
| 710 |
\fITemporarily fixing locale problems\fR |
| 711 |
.IX Subsection "Temporarily fixing locale problems" |
| 712 |
.PP |
| 713 |
The two quickest fixes are either to render Perl silent about any |
| 714 |
locale inconsistencies or to run Perl under the default locale "C". |
| 715 |
.PP |
| 716 |
Perl's moaning about locale problems can be silenced by setting the |
| 717 |
environment variable \f(CW\*(C`PERL_BADLANG\*(C'\fR to "0" or "". |
| 718 |
This method really just sweeps the problem under the carpet: you tell |
| 719 |
Perl to shut up even when Perl sees that something is wrong. Do not |
| 720 |
be surprised if later something locale-dependent misbehaves. |
| 721 |
.PP |
| 722 |
Perl can be run under the "C" locale by setting the environment |
| 723 |
variable \f(CW\*(C`LC_ALL\*(C'\fR to "C". This method is perhaps a bit more civilized |
| 724 |
than the \f(CW\*(C`PERL_BADLANG\*(C'\fR approach, but setting \f(CW\*(C`LC_ALL\*(C'\fR (or |
| 725 |
other locale variables) may affect other programs as well, not just |
| 726 |
Perl. In particular, external programs run from within Perl will see |
| 727 |
these changes. If you make the new settings permanent (read on), all |
| 728 |
programs you run see the changes. See "ENVIRONMENT" for |
| 729 |
the full list of relevant environment variables and "USING LOCALES" |
| 730 |
for their effects in Perl. Effects in other programs are |
| 731 |
easily deducible. For example, the variable \f(CW\*(C`LC_COLLATE\*(C'\fR may well affect |
| 732 |
your \fBsort\fR program (or whatever the program that arranges "records" |
| 733 |
alphabetically in your system is called). |
| 734 |
.PP |
| 735 |
You can test out changing these variables temporarily, and if the |
| 736 |
new settings seem to help, put those settings into your shell startup |
| 737 |
files. Consult your local documentation for the exact details. For |
| 738 |
Bourne-like shells (\fBsh\fR, \fBksh\fR, \fBbash\fR, \fBzsh\fR): |
| 739 |
.PP |
| 740 |
.Vb 2 |
| 741 |
\& LC_ALL=en_US.ISO8859\-1 |
| 742 |
\& export LC_ALL |
| 743 |
.Ve |
| 744 |
.PP |
| 745 |
This assumes that we saw the locale "en_US.ISO8859\-1" using the commands |
| 746 |
discussed above. We decided to try that instead of the above faulty |
| 747 |
locale "En_US". |
| 748 |
.PP |
| 749 |
And in Csh-ish shells (\fBcsh\fR, \fBtcsh\fR) |
| 750 |
.PP |
| 751 |
.Vb 1 |
| 752 |
\& setenv LC_ALL en_US.ISO8859\-1 |
| 753 |
.Ve |
| 754 |
.PP |
| 755 |
or if you have the "env" application you can do (in any shell) |
| 756 |
.PP |
| 757 |
.Vb 1 |
| 758 |
\& env LC_ALL=en_US.ISO8859\-1 perl ... |
| 759 |
.Ve |
| 760 |
.PP |
| 761 |
If you do not know what shell you have, consult your local |
| 762 |
helpdesk or the equivalent. |
| 763 |
.PP |
| 764 |
\fIPermanently fixing locale problems\fR |
| 765 |
.IX Subsection "Permanently fixing locale problems" |
| 766 |
.PP |
| 767 |
The slower but superior fixes are when you may be able to yourself |
| 768 |
fix the misconfiguration of your own environment variables. The |
| 769 |
mis(sing)configuration of the whole system's locales usually requires |
| 770 |
the help of your system administrator. |
| 771 |
.PP |
| 772 |
First, see earlier in this document about "Finding locales". That tells |
| 773 |
how to find which locales are really supported\-\-and more importantly, |
| 774 |
installed\-\-on your system. In our example error message, environment |
| 775 |
variables affecting the locale are listed in the order of decreasing |
| 776 |
importance (and unset variables do not matter). Therefore, having |
| 777 |
LC_ALL set to "En_US" must have been the bad choice, as shown by the |
| 778 |
error message. First try fixing locale settings listed first. |
| 779 |
.PP |
| 780 |
Second, if using the listed commands you see something \fBexactly\fR |
| 781 |
(prefix matches do not count and case usually counts) like "En_US" |
| 782 |
without the quotes, then you should be okay because you are using a |
| 783 |
locale name that should be installed and available in your system. |
| 784 |
In this case, see "Permanently fixing your system's locale configuration". |
| 785 |
.PP |
| 786 |
\fIPermanently fixing your system's locale configuration\fR |
| 787 |
.IX Subsection "Permanently fixing your system's locale configuration" |
| 788 |
.PP |
| 789 |
This is when you see something like: |
| 790 |
.PP |
| 791 |
.Vb 4 |
| 792 |
\& perl: warning: Please check that your locale settings: |
| 793 |
\& LC_ALL = "En_US", |
| 794 |
\& LANG = (unset) |
| 795 |
\& are supported and installed on your system. |
| 796 |
.Ve |
| 797 |
.PP |
| 798 |
but then cannot see that "En_US" listed by the above-mentioned |
| 799 |
commands. You may see things like "en_US.ISO8859\-1", but that isn't |
| 800 |
the same. In this case, try running under a locale |
| 801 |
that you can list and which somehow matches what you tried. The |
| 802 |
rules for matching locale names are a bit vague because |
| 803 |
standardization is weak in this area. See again the |
| 804 |
"Finding locales" about general rules. |
| 805 |
.PP |
| 806 |
\fIFixing system locale configuration\fR |
| 807 |
.IX Subsection "Fixing system locale configuration" |
| 808 |
.PP |
| 809 |
Contact a system administrator (preferably your own) and report the exact |
| 810 |
error message you get, and ask them to read this same documentation you |
| 811 |
are now reading. They should be able to check whether there is something |
| 812 |
wrong with the locale configuration of the system. The "Finding locales" |
| 813 |
section is unfortunately a bit vague about the exact commands and places |
| 814 |
because these things are not that standardized. |
| 815 |
.SS "The localeconv function" |
| 816 |
.IX Subsection "The localeconv function" |
| 817 |
The \f(CWPOSIX::localeconv()\fR function allows you to get particulars of the |
| 818 |
locale-dependent numeric formatting information specified by the current |
| 819 |
underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR and \f(CW\*(C`LC_MONETARY\*(C'\fR locales (regardless of |
| 820 |
whether called from within the scope of \f(CW\*(C`use\ locale\*(C'\fR or not). (If |
| 821 |
you just want the name of |
| 822 |
the current locale for a particular category, use \f(CWPOSIX::setlocale()\fR |
| 823 |
with a single parameter\-\-see "The setlocale function".) |
| 824 |
.PP |
| 825 |
.Vb 1 |
| 826 |
\& use POSIX qw(locale_h); |
| 827 |
\& |
| 828 |
\& # Get a reference to a hash of locale\-dependent info |
| 829 |
\& $locale_values = localeconv(); |
| 830 |
\& |
| 831 |
\& # Output sorted list of the values |
| 832 |
\& for (sort keys %$locale_values) { |
| 833 |
\& printf "%\-20s = %s\en", $_, $locale_values\->{$_} |
| 834 |
\& } |
| 835 |
.Ve |
| 836 |
.PP |
| 837 |
\&\f(CWlocaleconv()\fR takes no arguments, and returns \fBa reference to\fR a hash. |
| 838 |
The keys of this hash are variable names for formatting, such as |
| 839 |
\&\f(CW\*(C`decimal_point\*(C'\fR and \f(CW\*(C`thousands_sep\*(C'\fR. The values are the |
| 840 |
corresponding, er, values. See "localeconv" in POSIX for a longer |
| 841 |
example listing the categories an implementation might be expected to |
| 842 |
provide; some provide more and others fewer. You don't need an |
| 843 |
explicit \f(CW\*(C`use locale\*(C'\fR, because \f(CWlocaleconv()\fR always observes the |
| 844 |
current locale. |
| 845 |
.PP |
| 846 |
Here's a simple-minded example program that rewrites its command-line |
| 847 |
parameters as integers correctly formatted in the current locale: |
| 848 |
.PP |
| 849 |
.Vb 1 |
| 850 |
\& use POSIX qw(locale_h); |
| 851 |
\& |
| 852 |
\& # Get some of locale\*(Aqs numeric formatting parameters |
| 853 |
\& my ($thousands_sep, $grouping) = |
| 854 |
\& @{localeconv()}{\*(Aqthousands_sep\*(Aq, \*(Aqgrouping\*(Aq}; |
| 855 |
\& |
| 856 |
\& # Apply defaults if values are missing |
| 857 |
\& $thousands_sep = \*(Aq,\*(Aq unless $thousands_sep; |
| 858 |
\& |
| 859 |
\& # grouping and mon_grouping are packed lists |
| 860 |
\& # of small integers (characters) telling the |
| 861 |
\& # grouping (thousand_seps and mon_thousand_seps |
| 862 |
\& # being the group dividers) of numbers and |
| 863 |
\& # monetary quantities. The integers\*(Aq meanings: |
| 864 |
\& # 255 means no more grouping, 0 means repeat |
| 865 |
\& # the previous grouping, 1\-254 means use that |
| 866 |
\& # as the current grouping. Grouping goes from |
| 867 |
\& # right to left (low to high digits). In the |
| 868 |
\& # below we cheat slightly by never using anything |
| 869 |
\& # else than the first grouping (whatever that is). |
| 870 |
\& if ($grouping) { |
| 871 |
\& @grouping = unpack("C*", $grouping); |
| 872 |
\& } else { |
| 873 |
\& @grouping = (3); |
| 874 |
\& } |
| 875 |
\& |
| 876 |
\& # Format command line params for current locale |
| 877 |
\& for (@ARGV) { |
| 878 |
\& $_ = int; # Chop non\-integer part |
| 879 |
\& 1 while |
| 880 |
\& s/(\ed)(\ed{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/; |
| 881 |
\& print "$_"; |
| 882 |
\& } |
| 883 |
\& print "\en"; |
| 884 |
.Ve |
| 885 |
.PP |
| 886 |
Note that if the platform doesn't have \f(CW\*(C`LC_NUMERIC\*(C'\fR and/or |
| 887 |
\&\f(CW\*(C`LC_MONETARY\*(C'\fR available or enabled, the corresponding elements of the |
| 888 |
hash will be missing. |
| 889 |
.SS I18N::Langinfo |
| 890 |
.IX Subsection "I18N::Langinfo" |
| 891 |
Another interface for querying locale-dependent information is the |
| 892 |
\&\f(CWI18N::Langinfo::langinfo()\fR function. |
| 893 |
.PP |
| 894 |
The following example will import the \f(CWlanginfo()\fR function itself and |
| 895 |
three constants to be used as arguments to \f(CWlanginfo()\fR: a constant for |
| 896 |
the abbreviated first day of the week (the numbering starts from |
| 897 |
Sunday = 1) and two more constants for the affirmative and negative |
| 898 |
answers for a yes/no question in the current locale. |
| 899 |
.PP |
| 900 |
.Vb 1 |
| 901 |
\& use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR); |
| 902 |
\& |
| 903 |
\& my ($abday_1, $yesstr, $nostr) |
| 904 |
\& = map { langinfo } qw(ABDAY_1 YESSTR NOSTR); |
| 905 |
\& |
| 906 |
\& print "$abday_1? [$yesstr/$nostr] "; |
| 907 |
.Ve |
| 908 |
.PP |
| 909 |
In other words, in the "C" (or English) locale the above will probably |
| 910 |
print something like: |
| 911 |
.PP |
| 912 |
.Vb 1 |
| 913 |
\& Sun? [yes/no] |
| 914 |
.Ve |
| 915 |
.PP |
| 916 |
See I18N::Langinfo for more information. |
| 917 |
.SH "LOCALE CATEGORIES" |
| 918 |
.IX Header "LOCALE CATEGORIES" |
| 919 |
The following subsections describe basic locale categories. Beyond these, |
| 920 |
some combination categories allow manipulation of more than one |
| 921 |
basic category at a time. See "ENVIRONMENT" for a discussion of these. |
| 922 |
.ie n .SS "Category ""LC_COLLATE"": Collation: Text Comparisons and Sorting" |
| 923 |
.el .SS "Category \f(CWLC_COLLATE\fP: Collation: Text Comparisons and Sorting" |
| 924 |
.IX Subsection "Category LC_COLLATE: Collation: Text Comparisons and Sorting" |
| 925 |
In the scope of a \f(CW\*(C`use\ locale\*(C'\fR form that includes collation, Perl |
| 926 |
looks to the \f(CW\*(C`LC_COLLATE\*(C'\fR |
| 927 |
environment variable to determine the application's notions on collation |
| 928 |
(ordering) of characters. For example, "b" likely follows "a" in Latin |
| 929 |
alphabets, but where do "á" and "å" belong? And while |
| 930 |
"color" follows "chocolate" in English, what about in traditional Spanish? |
| 931 |
.PP |
| 932 |
The following collations all make sense and you may meet any of them |
| 933 |
if you \f(CW"use locale"\fR. |
| 934 |
.PP |
| 935 |
.Vb 4 |
| 936 |
\& A B C D E a b c d e |
| 937 |
\& A a B b C c D d E e |
| 938 |
\& a A b B c C d D e E |
| 939 |
\& a b c d e A B C D E |
| 940 |
.Ve |
| 941 |
.PP |
| 942 |
Here is a code snippet to tell what "word" |
| 943 |
characters are in the current locale, in that locale's order: |
| 944 |
.PP |
| 945 |
.Vb 2 |
| 946 |
\& use locale; |
| 947 |
\& print +(sort grep /\ew/, map { chr } 0..255), "\en"; |
| 948 |
.Ve |
| 949 |
.PP |
| 950 |
Compare this with the characters that you see and their order if you |
| 951 |
state explicitly that the locale should be ignored: |
| 952 |
.PP |
| 953 |
.Vb 2 |
| 954 |
\& no locale; |
| 955 |
\& print +(sort grep /\ew/, map { chr } 0..255), "\en"; |
| 956 |
.Ve |
| 957 |
.PP |
| 958 |
This machine-native collation (which is what you get unless \f(CW\*(C`use\ locale\*(C'\fR has appeared earlier in the same block) must be used for |
| 959 |
sorting raw binary data, whereas the locale-dependent collation of the |
| 960 |
first example is useful for natural text. |
| 961 |
.PP |
| 962 |
As noted in "USING LOCALES", \f(CW\*(C`cmp\*(C'\fR compares according to the current |
| 963 |
collation locale when \f(CW\*(C`use locale\*(C'\fR is in effect, but falls back to a |
| 964 |
char-by-char comparison for strings that the locale says are equal. You |
| 965 |
can use \f(CWPOSIX::strcoll()\fR if you don't want this fall-back: |
| 966 |
.PP |
| 967 |
.Vb 3 |
| 968 |
\& use POSIX qw(strcoll); |
| 969 |
\& $equal_in_locale = |
| 970 |
\& !strcoll("space and case ignored", "SpaceAndCaseIgnored"); |
| 971 |
.Ve |
| 972 |
.PP |
| 973 |
\&\f(CW$equal_in_locale\fR will be true if the collation locale specifies a |
| 974 |
dictionary-like ordering that ignores space characters completely and |
| 975 |
which folds case. |
| 976 |
.PP |
| 977 |
Perl uses the platform's C library collation functions \f(CWstrcoll()\fR and |
| 978 |
\&\f(CWstrxfrm()\fR. That means you get whatever they give. On some |
| 979 |
platforms, these functions work well on UTF\-8 locales, giving |
| 980 |
a reasonable default collation for the code points that are important in |
| 981 |
that locale. (And if they aren't working well, the problem may only be |
| 982 |
that the locale definition is deficient, so can be fixed by using a |
| 983 |
better definition file. Unicode's definitions (see "Freely available |
| 984 |
locale definitions") provide reasonable UTF\-8 locale collation |
| 985 |
definitions.) Starting in Perl v5.26, Perl's use of these functions has |
| 986 |
been made more seamless. This may be sufficient for your needs. For |
| 987 |
more control, and to make sure strings containing any code point (not |
| 988 |
just the ones important in the locale) collate properly, the |
| 989 |
Unicode::Collate module is suggested. |
| 990 |
.PP |
| 991 |
In non\-UTF\-8 locales (hence single byte), code points above 0xFF are |
| 992 |
technically invalid. But if present, again starting in v5.26, they will |
| 993 |
collate to the same position as the highest valid code point does. This |
| 994 |
generally gives good results, but the collation order may be skewed if |
| 995 |
the valid code point gets special treatment when it forms particular |
| 996 |
sequences with other characters as defined by the locale. |
| 997 |
When two strings collate identically, the code point order is used as a |
| 998 |
tie breaker. |
| 999 |
.PP |
| 1000 |
If Perl detects that there are problems with the locale collation order, |
| 1001 |
it reverts to using non-locale collation rules for that locale. |
| 1002 |
.PP |
| 1003 |
If you have a single string that you want to check for "equality in |
| 1004 |
locale" against several others, you might think you could gain a little |
| 1005 |
efficiency by using \f(CWPOSIX::strxfrm()\fR in conjunction with \f(CW\*(C`eq\*(C'\fR: |
| 1006 |
.PP |
| 1007 |
.Vb 8 |
| 1008 |
\& use POSIX qw(strxfrm); |
| 1009 |
\& $xfrm_string = strxfrm("Mixed\-case string"); |
| 1010 |
\& print "locale collation ignores spaces\en" |
| 1011 |
\& if $xfrm_string eq strxfrm("Mixed\-casestring"); |
| 1012 |
\& print "locale collation ignores hyphens\en" |
| 1013 |
\& if $xfrm_string eq strxfrm("Mixedcase string"); |
| 1014 |
\& print "locale collation ignores case\en" |
| 1015 |
\& if $xfrm_string eq strxfrm("mixed\-case string"); |
| 1016 |
.Ve |
| 1017 |
.PP |
| 1018 |
\&\f(CWstrxfrm()\fR takes a string and maps it into a transformed string for use |
| 1019 |
in char-by-char comparisons against other transformed strings during |
| 1020 |
collation. "Under the hood", locale-affected Perl comparison operators |
| 1021 |
call \f(CWstrxfrm()\fR for both operands, then do a char-by-char |
| 1022 |
comparison of the transformed strings. By calling \f(CWstrxfrm()\fR explicitly |
| 1023 |
and using a non locale-affected comparison, the example attempts to save |
| 1024 |
a couple of transformations. But in fact, it doesn't save anything: Perl |
| 1025 |
magic (see "Magic Variables" in perlguts) creates the transformed version of a |
| 1026 |
string the first time it's needed in a comparison, then keeps this version around |
| 1027 |
in case it's needed again. An example rewritten the easy way with |
| 1028 |
\&\f(CW\*(C`cmp\*(C'\fR runs just about as fast. It also copes with null characters |
| 1029 |
embedded in strings; if you call \f(CWstrxfrm()\fR directly, it treats the first |
| 1030 |
null it finds as a terminator. Don't expect the transformed strings |
| 1031 |
it produces to be portable across systems\-\-or even from one revision |
| 1032 |
of your operating system to the next. In short, don't call \f(CWstrxfrm()\fR |
| 1033 |
directly: let Perl do it for you. |
| 1034 |
.PP |
| 1035 |
Note: \f(CW\*(C`use locale\*(C'\fR isn't shown in some of these examples because it isn't |
| 1036 |
needed: \f(CWstrcoll()\fR and \f(CWstrxfrm()\fR are POSIX:: functions |
| 1037 |
which use the standard system-supplied \f(CW\*(C`libc\*(C'\fR functions that |
| 1038 |
always obey the current \f(CW\*(C`LC_COLLATE\*(C'\fR locale. |
| 1039 |
.ie n .SS "Category ""LC_CTYPE"": Character Types" |
| 1040 |
.el .SS "Category \f(CWLC_CTYPE\fP: Character Types" |
| 1041 |
.IX Subsection "Category LC_CTYPE: Character Types" |
| 1042 |
In the scope of a \f(CW\*(C`use\ locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR, Perl |
| 1043 |
obeys the \f(CW\*(C`LC_CTYPE\*(C'\fR locale |
| 1044 |
setting. This controls the application's notion of which characters are |
| 1045 |
alphabetic, numeric, punctuation, \fIetc\fR. This affects Perl's \f(CW\*(C`\ew\*(C'\fR |
| 1046 |
regular expression metanotation, |
| 1047 |
which stands for alphanumeric characters\-\-that is, alphabetic, |
| 1048 |
numeric, and the platform's native underscore. |
| 1049 |
(Consult perlre for more information about |
| 1050 |
regular expressions.) Thanks to \f(CW\*(C`LC_CTYPE\*(C'\fR, depending on your locale |
| 1051 |
setting, characters like "æ", "ð", "ß", and |
| 1052 |
"ø" may be understood as \f(CW\*(C`\ew\*(C'\fR characters. |
| 1053 |
It also affects things like \f(CW\*(C`\es\*(C'\fR, \f(CW\*(C`\eD\*(C'\fR, and the POSIX character |
| 1054 |
classes, like \f(CW\*(C`[[:graph:]]\*(C'\fR. (See perlrecharclass for more |
| 1055 |
information on all these.) |
| 1056 |
.PP |
| 1057 |
The \f(CW\*(C`LC_CTYPE\*(C'\fR locale also provides the map used in transliterating |
| 1058 |
characters between lower and uppercase. This affects the case-mapping |
| 1059 |
functions\-\-\f(CWfc()\fR, \f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR, and \f(CWucfirst()\fR; |
| 1060 |
case-mapping |
| 1061 |
interpolation with \f(CW\*(C`\eF\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, or \f(CW\*(C`\eU\*(C'\fR in double-quoted |
| 1062 |
strings and \f(CW\*(C`s///\*(C'\fR substitutions; and case-insensitive regular expression |
| 1063 |
pattern matching using the \f(CW\*(C`i\*(C'\fR modifier. |
| 1064 |
.PP |
| 1065 |
Starting in v5.20, Perl supports UTF\-8 locales for \f(CW\*(C`LC_CTYPE\*(C'\fR, but |
| 1066 |
otherwise Perl only supports single-byte locales, such as the ISO 8859 |
| 1067 |
series. This means that wide character locales, for example for Asian |
| 1068 |
languages, are not well-supported. Use of these locales may cause core |
| 1069 |
dumps. If the platform has the capability for Perl to detect such a |
| 1070 |
locale, starting in Perl v5.22, Perl will warn, default |
| 1071 |
enabled, using the \f(CW\*(C`locale\*(C'\fR warning |
| 1072 |
category, whenever such a locale is switched into. The UTF\-8 locale |
| 1073 |
support is actually a |
| 1074 |
superset of POSIX locales, because it is really full Unicode behavior |
| 1075 |
as if no \f(CW\*(C`LC_CTYPE\*(C'\fR locale were in effect at all (except for tainting; |
| 1076 |
see "SECURITY"). POSIX locales, even UTF\-8 ones, |
| 1077 |
are lacking certain concepts in Unicode, such as the idea that changing |
| 1078 |
the case of a character could expand to be more than one character. |
| 1079 |
Perl in a UTF\-8 locale, will give you that expansion. Prior to v5.20, |
| 1080 |
Perl treated a UTF\-8 locale on some platforms like an ISO 8859\-1 one, |
| 1081 |
with some restrictions, and on other platforms more like the "C" locale. |
| 1082 |
For releases v5.16 and v5.18, \f(CW\*(C`use\ locale\ \*(Aqnot_characters\*(C'\fR could be |
| 1083 |
used as a workaround for this (see "Unicode and UTF\-8"). |
| 1084 |
.PP |
| 1085 |
Note that there are quite a few things that are unaffected by the |
| 1086 |
current locale. Any literal character is the native character for the |
| 1087 |
given platform. Hence 'A' means the character at code point 65 on ASCII |
| 1088 |
platforms, and 193 on EBCDIC. That may or may not be an 'A' in the |
| 1089 |
current locale, if that locale even has an 'A'. |
| 1090 |
Similarly, all the escape sequences for particular characters, |
| 1091 |
\&\f(CW\*(C`\en\*(C'\fR for example, always mean the platform's native one. This means, |
| 1092 |
for example, that \f(CW\*(C`\eN\*(C'\fR in regular expressions (every character |
| 1093 |
but new-line) works on the platform character set. |
| 1094 |
.PP |
| 1095 |
Starting in v5.22, Perl will by default warn when switching into a |
| 1096 |
locale that redefines any ASCII printable character (plus \f(CW\*(C`\et\*(C'\fR and |
| 1097 |
\&\f(CW\*(C`\en\*(C'\fR) into a different class than expected. This is likely to |
| 1098 |
happen on modern locales only on EBCDIC platforms, where, for example, |
| 1099 |
a CCSID 0037 locale on a CCSID 1047 machine moves \f(CW"["\fR, but it can |
| 1100 |
happen on ASCII platforms with the ISO 646 and other |
| 1101 |
7\-bit locales that are essentially obsolete. Things may still work, |
| 1102 |
depending on what features of Perl are used by the program. For |
| 1103 |
example, in the example from above where \f(CW"|"\fR becomes a \f(CW\*(C`\ew\*(C'\fR, and |
| 1104 |
there are no regular expressions where this matters, the program may |
| 1105 |
still work properly. The warning lists all the characters that |
| 1106 |
it can determine could be adversely affected. |
| 1107 |
.PP |
| 1108 |
\&\fBNote:\fR A broken or malicious \f(CW\*(C`LC_CTYPE\*(C'\fR locale definition may result |
| 1109 |
in clearly ineligible characters being considered to be alphanumeric by |
| 1110 |
your application. For strict matching of (mundane) ASCII letters and |
| 1111 |
digits\-\-for example, in command strings\-\-locale\-aware applications |
| 1112 |
should use \f(CW\*(C`\ew\*(C'\fR with the \f(CW\*(C`/a\*(C'\fR regular expression modifier. See "SECURITY". |
| 1113 |
.ie n .SS "Category ""LC_NUMERIC"": Numeric Formatting" |
| 1114 |
.el .SS "Category \f(CWLC_NUMERIC\fP: Numeric Formatting" |
| 1115 |
.IX Subsection "Category LC_NUMERIC: Numeric Formatting" |
| 1116 |
After a proper \f(CWPOSIX::setlocale()\fR call, and within the scope |
| 1117 |
of a \f(CW\*(C`use locale\*(C'\fR form that includes numerics, Perl obeys the |
| 1118 |
\&\f(CW\*(C`LC_NUMERIC\*(C'\fR locale information, which controls an application's idea |
| 1119 |
of how numbers should be formatted for human readability. |
| 1120 |
In most implementations the only effect is to |
| 1121 |
change the character used for the decimal point\-\-perhaps from "." to ",". |
| 1122 |
The functions aren't aware of such niceties as thousands separation and |
| 1123 |
so on. (See "The localeconv function" if you care about these things.) |
| 1124 |
.PP |
| 1125 |
.Vb 2 |
| 1126 |
\& use POSIX qw(strtod setlocale LC_NUMERIC); |
| 1127 |
\& use locale; |
| 1128 |
\& |
| 1129 |
\& setlocale LC_NUMERIC, ""; |
| 1130 |
\& |
| 1131 |
\& $n = 5/2; # Assign numeric 2.5 to $n |
| 1132 |
\& |
| 1133 |
\& $x = " $n"; # Locale\-dependent conversion to string |
| 1134 |
\& |
| 1135 |
\& print "half five is $n\en"; # Locale\-dependent output |
| 1136 |
\& |
| 1137 |
\& printf "half five is %g\en", $n; # Locale\-dependent output |
| 1138 |
\& |
| 1139 |
\& print "DECIMAL POINT IS COMMA\en" |
| 1140 |
\& if $n == (strtod("2,5"))[0]; # Locale\-dependent conversion |
| 1141 |
.Ve |
| 1142 |
.PP |
| 1143 |
See also I18N::Langinfo and \f(CW\*(C`RADIXCHAR\*(C'\fR. |
| 1144 |
.ie n .SS "Category ""LC_MONETARY"": Formatting of monetary amounts" |
| 1145 |
.el .SS "Category \f(CWLC_MONETARY\fP: Formatting of monetary amounts" |
| 1146 |
.IX Subsection "Category LC_MONETARY: Formatting of monetary amounts" |
| 1147 |
The C standard defines the \f(CW\*(C`LC_MONETARY\*(C'\fR category, but not a function |
| 1148 |
that is affected by its contents. (Those with experience of standards |
| 1149 |
committees will recognize that the working group decided to punt on the |
| 1150 |
issue. POSIX 2001 added the \f(CWstrfmon()\fR function to format currency |
| 1151 |
amounts, but there is no official function to parse strings representing |
| 1152 |
currency values.) |
| 1153 |
.PP |
| 1154 |
Perl essentially takes no notice of this category. On POSIX systems, you |
| 1155 |
can call \f(CWstrfmon()\fR from XS code to create formatted strings, and/or you |
| 1156 |
you can query the \f(CW\*(C`LC_MONETARY\*(C'\fR locale-specific values with |
| 1157 |
"The localeconv function" and use the information that it returns in your |
| 1158 |
application's own formatting of currency amounts. However, you may well |
| 1159 |
find that the information, voluminous and complex though it may be, still |
| 1160 |
does not quite meet your requirements: currency formatting is a hard nut |
| 1161 |
to crack. |
| 1162 |
.PP |
| 1163 |
See also \f(CW\*(C`CRNCYSTR\*(C'\fR in I18N::Langinfo. |
| 1164 |
.ie n .SS "Category ""LC_TIME"": Respresentation of time" |
| 1165 |
.el .SS "Category \f(CWLC_TIME\fP: Respresentation of time" |
| 1166 |
.IX Subsection "Category LC_TIME: Respresentation of time" |
| 1167 |
Output produced by \f(CWPOSIX::strftime()\fR, which builds a formatted |
| 1168 |
human-readable date/time string, is affected by the current \f(CW\*(C`LC_TIME\*(C'\fR |
| 1169 |
locale. Thus, in a French locale, the output produced by the \f(CW%B\fR |
| 1170 |
format element (full month name) for the first month of the year would |
| 1171 |
be "janvier". Here's how to get a list of long month names in the |
| 1172 |
current locale: |
| 1173 |
.PP |
| 1174 |
.Vb 5 |
| 1175 |
\& use POSIX qw(strftime); |
| 1176 |
\& for (0..11) { |
| 1177 |
\& $long_month_name[$_] = |
| 1178 |
\& strftime("%B", 0, 0, 0, 1, $_, 96); |
| 1179 |
\& } |
| 1180 |
.Ve |
| 1181 |
.PP |
| 1182 |
Note: \f(CW\*(C`use locale\*(C'\fR isn't needed in this example: \f(CWstrftime()\fR is a POSIX:: |
| 1183 |
function which uses the standard system-supplied \f(CW\*(C`libc\*(C'\fR function that |
| 1184 |
always obeys the current \f(CW\*(C`LC_TIME\*(C'\fR locale. |
| 1185 |
.PP |
| 1186 |
See also I18N::Langinfo and \f(CW\*(C`ABDAY_1\*(C'\fR..\f(CW\*(C`ABDAY_7\*(C'\fR, \f(CW\*(C`DAY_1\*(C'\fR..\f(CW\*(C`DAY_7\*(C'\fR, |
| 1187 |
\&\f(CW\*(C`ABMON_1\*(C'\fR..\f(CW\*(C`ABMON_12\*(C'\fR, and \f(CW\*(C`ABMON_1\*(C'\fR..\f(CW\*(C`ABMON_12\*(C'\fR. |
| 1188 |
.PP |
| 1189 |
There is also the libc \f(CWstrptime()\fR function defined starting in POSIX |
| 1190 |
2001 (it's not in Windows) that parses formatted time strings. There is |
| 1191 |
currently no pure perl access to this function, so you need to write XS |
| 1192 |
code to use it. |
| 1193 |
.ie n .SS "Category ""LC_MESSAGES"": System messages" |
| 1194 |
.el .SS "Category \f(CWLC_MESSAGES\fP: System messages" |
| 1195 |
.IX Subsection "Category LC_MESSAGES: System messages" |
| 1196 |
This category is used by perl to create a string describing a system |
| 1197 |
error number, such as what you would get by saying |
| 1198 |
\&\f(CW"$!"\fR or \f(CW"$^E"\fR. |
| 1199 |
On some systems and locales, the string will be in the language of the |
| 1200 |
locale given by \f(CW\*(C`LC_MESSAGES\*(C'\fR. But not many systems have bothered to |
| 1201 |
install such translations for all locales available on the system. If |
| 1202 |
no translation is available for a given locale, the string will be in |
| 1203 |
English. See Errno for information about portably using error codes. |
| 1204 |
.PP |
| 1205 |
The other categories mentioned so far are required to exist in any |
| 1206 |
platform on which Perl can run. But this category is a POSIX extension, |
| 1207 |
and Perl runs on platforms, Windows, for example, that don't have it. On |
| 1208 |
such platforms the underlying language for the system errors will be |
| 1209 |
whatever \f(CW\*(C`LC_CTYPE\*(C'\fR gives, or English. |
| 1210 |
.PP |
| 1211 |
This category in conjunction with I18N::Langinfo can be used to |
| 1212 |
output yes/no in its locale's language, and to parse strings that |
| 1213 |
contain "yes" or "no" in that language. |
| 1214 |
.SS "Other categories" |
| 1215 |
.IX Subsection "Other categories" |
| 1216 |
Some platforms have additional categories. These are not used by Perl |
| 1217 |
itself. I18N::Langinfo may be used to query them, yielding stub |
| 1218 |
values on platforms where they don't exist. But again note that things |
| 1219 |
Perl interacts with may use these, including extensions outside the |
| 1220 |
standard Perl distribution, and by the operating system and its |
| 1221 |
utilities. |
| 1222 |
.SH SECURITY |
| 1223 |
.IX Header "SECURITY" |
| 1224 |
Although the main discussion of Perl security issues can be found in |
| 1225 |
perlsec, a discussion of Perl's locale handling would be incomplete |
| 1226 |
if it did not draw your attention to locale-dependent security issues. |
| 1227 |
Locales\-\-particularly on systems that allow unprivileged users to |
| 1228 |
build their own locales\-\-are untrustworthy. A malicious (or just plain |
| 1229 |
broken) locale can make a locale-aware application give unexpected |
| 1230 |
results. Here are a few possibilities: |
| 1231 |
.IP \(bu 4 |
| 1232 |
Regular expression checks for safe file names or mail addresses using |
| 1233 |
\&\f(CW\*(C`\ew\*(C'\fR may be spoofed by an \f(CW\*(C`LC_CTYPE\*(C'\fR locale that claims that |
| 1234 |
characters such as \f(CW">"\fR and \f(CW"|"\fR are alphanumeric. |
| 1235 |
.IP \(bu 4 |
| 1236 |
String interpolation with case-mapping, as in, say, \f(CW$dest = |
| 1237 |
"C:\eU$name.$ext"\fR, may produce dangerous results if a bogus \f(CW\*(C`LC_CTYPE\*(C'\fR |
| 1238 |
case-mapping table is in effect. |
| 1239 |
.IP \(bu 4 |
| 1240 |
A sneaky \f(CW\*(C`LC_COLLATE\*(C'\fR locale could result in the names of students with |
| 1241 |
"D" grades appearing ahead of those with "A"s. |
| 1242 |
.IP \(bu 4 |
| 1243 |
An application that takes the trouble to use information in |
| 1244 |
\&\f(CW\*(C`LC_MONETARY\*(C'\fR may format debits as if they were credits and vice versa |
| 1245 |
if that locale has been subverted. Or it might make payments in US |
| 1246 |
dollars instead of Hong Kong dollars. |
| 1247 |
.IP \(bu 4 |
| 1248 |
The date and day names in dates formatted by \f(CWstrftime()\fR could be |
| 1249 |
manipulated to advantage by a malicious user able to subvert the |
| 1250 |
\&\f(CW\*(C`LC_TIME\*(C'\fR locale. ("Look\-\-it says I wasn't in the building on |
| 1251 |
Sunday.") |
| 1252 |
.PP |
| 1253 |
Such dangers are not peculiar to the locale system: any aspect of an |
| 1254 |
application's environment which may be modified maliciously presents |
| 1255 |
similar challenges. Similarly, they are not specific to Perl: any |
| 1256 |
programming language that allows you to write programs that take |
| 1257 |
account of their environment exposes you to these issues. |
| 1258 |
.PP |
| 1259 |
Perl cannot protect you from all possibilities shown in the |
| 1260 |
examples\-\-there is no substitute for your own vigilance\-\-but, when |
| 1261 |
\&\f(CW\*(C`use locale\*(C'\fR is in effect, Perl uses the tainting mechanism (see |
| 1262 |
perlsec) to mark string results that become locale-dependent, and |
| 1263 |
which may be untrustworthy in consequence. |
| 1264 |
.PP |
| 1265 |
Note that it is possible to compile Perl without taint support, |
| 1266 |
in which case all taint features silently do nothing. |
| 1267 |
.PP |
| 1268 |
Here is a summary of the tainting behavior of operators and functions |
| 1269 |
that may be affected by the locale: |
| 1270 |
.IP \(bu 4 |
| 1271 |
\&\fBComparison operators\fR (\f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`le\*(C'\fR, \f(CW\*(C`ge\*(C'\fR, \f(CW\*(C`gt\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR): |
| 1272 |
.Sp |
| 1273 |
Scalar true/false (or less/equal/greater) result is never tainted. |
| 1274 |
.IP \(bu 4 |
| 1275 |
\&\fBCase-mapping interpolation\fR (with \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, or \f(CW\*(C`\eF\*(C'\fR) |
| 1276 |
.Sp |
| 1277 |
The result string containing interpolated material is tainted if |
| 1278 |
a \f(CW\*(C`use locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect. |
| 1279 |
.IP \(bu 4 |
| 1280 |
\&\fBMatching operator\fR (\f(CW\*(C`m//\*(C'\fR): |
| 1281 |
.Sp |
| 1282 |
Scalar true/false result never tainted. |
| 1283 |
.Sp |
| 1284 |
All subpatterns, either delivered as a list-context result or as \f(CW$1\fR |
| 1285 |
\&\fIetc\fR., are tainted if a \f(CW\*(C`use locale\*(C'\fR form that includes |
| 1286 |
\&\f(CW\*(C`LC_CTYPE\*(C'\fR is in effect, and the subpattern |
| 1287 |
regular expression contains a locale-dependent construct. These |
| 1288 |
constructs include \f(CW\*(C`\ew\*(C'\fR (to match an alphanumeric character), \f(CW\*(C`\eW\*(C'\fR |
| 1289 |
(non-alphanumeric character), \f(CW\*(C`\eb\*(C'\fR and \f(CW\*(C`\eB\*(C'\fR (word-boundary and |
| 1290 |
non-boundardy, which depend on what \f(CW\*(C`\ew\*(C'\fR and \f(CW\*(C`\eW\*(C'\fR match), \f(CW\*(C`\es\*(C'\fR |
| 1291 |
(whitespace character), \f(CW\*(C`\eS\*(C'\fR (non whitespace character), \f(CW\*(C`\ed\*(C'\fR and |
| 1292 |
\&\f(CW\*(C`\eD\*(C'\fR (digits and non-digits), and the POSIX character classes, such as |
| 1293 |
\&\f(CW\*(C`[:alpha:]\*(C'\fR (see "POSIX Character Classes" in perlrecharclass). |
| 1294 |
.Sp |
| 1295 |
Tainting is also likely if the pattern is to be matched |
| 1296 |
case-insensitively (via \f(CW\*(C`/i\*(C'\fR). The exception is if all the code points |
| 1297 |
to be matched this way are above 255 and do not have folds under Unicode |
| 1298 |
rules to below 256. Tainting is not done for these because Perl |
| 1299 |
only uses Unicode rules for such code points, and those rules are the |
| 1300 |
same no matter what the current locale. |
| 1301 |
.Sp |
| 1302 |
The matched-pattern variables, \f(CW$&\fR, \f(CW\*(C`$\`\*(C'\fR (pre-match), \f(CW\*(C`$\*(Aq\*(C'\fR |
| 1303 |
(post-match), and \f(CW$+\fR (last match) also are tainted. |
| 1304 |
.IP \(bu 4 |
| 1305 |
\&\fBSubstitution operator\fR (\f(CW\*(C`s///\*(C'\fR): |
| 1306 |
.Sp |
| 1307 |
Has the same behavior as the match operator. Also, the left |
| 1308 |
operand of \f(CW\*(C`=~\*(C'\fR becomes tainted when a \f(CW\*(C`use locale\*(C'\fR |
| 1309 |
form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect, if modified as |
| 1310 |
a result of a substitution based on a regular |
| 1311 |
expression match involving any of the things mentioned in the previous |
| 1312 |
item, or of case-mapping, such as \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR,\f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, or \f(CW\*(C`\eF\*(C'\fR. |
| 1313 |
.IP \(bu 4 |
| 1314 |
\&\fBOutput formatting functions\fR (\f(CWprintf()\fR and \f(CWwrite()\fR): |
| 1315 |
.Sp |
| 1316 |
Results are never tainted because otherwise even output from print, |
| 1317 |
for example \f(CWprint(1/7)\fR, should be tainted if \f(CW\*(C`use locale\*(C'\fR is in |
| 1318 |
effect. |
| 1319 |
.IP \(bu 4 |
| 1320 |
\&\fBCase-mapping functions\fR (\f(CWlc()\fR, \f(CWlcfirst()\fR, \f(CWuc()\fR, \f(CWucfirst()\fR): |
| 1321 |
.Sp |
| 1322 |
Results are tainted if a \f(CW\*(C`use locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is |
| 1323 |
in effect. |
| 1324 |
.IP \(bu 4 |
| 1325 |
\&\fBPOSIX locale-dependent functions\fR (\f(CWlocaleconv()\fR, \f(CWstrcoll()\fR, |
| 1326 |
\&\f(CWstrftime()\fR, \f(CWstrxfrm()\fR): |
| 1327 |
.Sp |
| 1328 |
Results are never tainted. |
| 1329 |
.PP |
| 1330 |
Three examples illustrate locale-dependent tainting. |
| 1331 |
The first program, which ignores its locale, won't run: a value taken |
| 1332 |
directly from the command line may not be used to name an output file |
| 1333 |
when taint checks are enabled. |
| 1334 |
.PP |
| 1335 |
.Vb 2 |
| 1336 |
\& #/usr/local/bin/perl \-T |
| 1337 |
\& # Run with taint checking |
| 1338 |
\& |
| 1339 |
\& # Command line sanity check omitted... |
| 1340 |
\& $tainted_output_file = shift; |
| 1341 |
\& |
| 1342 |
\& open(F, ">$tainted_output_file") |
| 1343 |
\& or warn "Open of $tainted_output_file failed: $!\en"; |
| 1344 |
.Ve |
| 1345 |
.PP |
| 1346 |
The program can be made to run by "laundering" the tainted value through |
| 1347 |
a regular expression: the second example\-\-which still ignores locale |
| 1348 |
information\-\-runs, creating the file named on its command line |
| 1349 |
if it can. |
| 1350 |
.PP |
| 1351 |
.Vb 1 |
| 1352 |
\& #/usr/local/bin/perl \-T |
| 1353 |
\& |
| 1354 |
\& $tainted_output_file = shift; |
| 1355 |
\& $tainted_output_file =~ m%[\ew/]+%; |
| 1356 |
\& $untainted_output_file = $&; |
| 1357 |
\& |
| 1358 |
\& open(F, ">$untainted_output_file") |
| 1359 |
\& or warn "Open of $untainted_output_file failed: $!\en"; |
| 1360 |
.Ve |
| 1361 |
.PP |
| 1362 |
Compare this with a similar but locale-aware program: |
| 1363 |
.PP |
| 1364 |
.Vb 1 |
| 1365 |
\& #/usr/local/bin/perl \-T |
| 1366 |
\& |
| 1367 |
\& $tainted_output_file = shift; |
| 1368 |
\& use locale; |
| 1369 |
\& $tainted_output_file =~ m%[\ew/]+%; |
| 1370 |
\& $localized_output_file = $&; |
| 1371 |
\& |
| 1372 |
\& open(F, ">$localized_output_file") |
| 1373 |
\& or warn "Open of $localized_output_file failed: $!\en"; |
| 1374 |
.Ve |
| 1375 |
.PP |
| 1376 |
This third program fails to run because \f(CW$&\fR is tainted: it is the result |
| 1377 |
of a match involving \f(CW\*(C`\ew\*(C'\fR while \f(CW\*(C`use locale\*(C'\fR is in effect. |
| 1378 |
.SH ENVIRONMENT |
| 1379 |
.IX Header "ENVIRONMENT" |
| 1380 |
.IP PERL_SKIP_LOCALE_INIT 12 |
| 1381 |
.IX Item "PERL_SKIP_LOCALE_INIT" |
| 1382 |
This environment variable, available starting in Perl v5.20, if set |
| 1383 |
(to any value), tells Perl to not use the rest of the |
| 1384 |
environment variables to initialize with. Instead, Perl uses whatever |
| 1385 |
the current locale settings are. This is particularly useful in |
| 1386 |
embedded environments, see |
| 1387 |
"Using embedded Perl with POSIX locales" in perlembed. |
| 1388 |
.IP PERL_BADLANG 12 |
| 1389 |
.IX Item "PERL_BADLANG" |
| 1390 |
A string that can suppress Perl's warning about failed locale settings |
| 1391 |
at startup. Failure can occur if the locale support in the operating |
| 1392 |
system is lacking (broken) in some way\-\-or if you mistyped the name of |
| 1393 |
a locale when you set up your environment. If this environment |
| 1394 |
variable is absent, or has a value other than "0" or "", Perl will |
| 1395 |
complain about locale setting failures. |
| 1396 |
.Sp |
| 1397 |
\&\fBNOTE\fR: \f(CW\*(C`PERL_BADLANG\*(C'\fR only gives you a way to hide the warning message. |
| 1398 |
The message tells about some problem in your system's locale support, |
| 1399 |
and you should investigate what the problem is. |
| 1400 |
.IP DPKG_RUNNING_VERSION 12 |
| 1401 |
.IX Item "DPKG_RUNNING_VERSION" |
| 1402 |
On Debian systems, if the DPKG_RUNNING_VERSION environment variable is |
| 1403 |
set (to any value), the locale failure warnings will be suppressed just |
| 1404 |
like with a zero PERL_BADLANG setting. This is done to avoid floods |
| 1405 |
of spurious warnings during system upgrades. |
| 1406 |
See <http://bugs.debian.org/508764>. |
| 1407 |
.PP |
| 1408 |
The following environment variables are not specific to Perl: They are |
| 1409 |
part of the standardized (ISO C, XPG4, POSIX 1.c) \f(CWsetlocale()\fR method |
| 1410 |
for controlling an application's opinion on data. Windows is non-POSIX, |
| 1411 |
but Perl arranges for the following to work as described anyway. |
| 1412 |
If the locale given by an environment variable is not valid, Perl tries |
| 1413 |
the next lower one in priority. If none are valid, on Windows, the |
| 1414 |
system default locale is then tried. If all else fails, the \f(CW"C"\fR |
| 1415 |
locale is used. If even that doesn't work, something is badly broken, |
| 1416 |
but Perl tries to forge ahead with whatever the locale settings might |
| 1417 |
be. |
| 1418 |
.ie n .IP """LC_ALL""" 12 |
| 1419 |
.el .IP \f(CWLC_ALL\fR 12 |
| 1420 |
.IX Item "LC_ALL" |
| 1421 |
\&\f(CW\*(C`LC_ALL\*(C'\fR is the "override-all" locale environment variable. If |
| 1422 |
set, it overrides all the rest of the locale environment variables. |
| 1423 |
.ie n .IP """LANGUAGE""" 12 |
| 1424 |
.el .IP \f(CWLANGUAGE\fR 12 |
| 1425 |
.IX Item "LANGUAGE" |
| 1426 |
\&\fBNOTE\fR: \f(CW\*(C`LANGUAGE\*(C'\fR is a GNU extension, it affects you only if you |
| 1427 |
are using the GNU libc. This is the case if you are using e.g. Linux. |
| 1428 |
If you are using "commercial" Unixes you are most probably \fInot\fR |
| 1429 |
using GNU libc and you can ignore \f(CW\*(C`LANGUAGE\*(C'\fR. |
| 1430 |
.Sp |
| 1431 |
However, in the case you are using \f(CW\*(C`LANGUAGE\*(C'\fR: it affects the |
| 1432 |
language of informational, warning, and error messages output by |
| 1433 |
commands (in other words, it's like \f(CW\*(C`LC_MESSAGES\*(C'\fR) but it has higher |
| 1434 |
priority than \f(CW\*(C`LC_ALL\*(C'\fR. Moreover, it's not a single value but |
| 1435 |
instead a "path" (":"\-separated list) of \fIlanguages\fR (not locales). |
| 1436 |
See the GNU \f(CW\*(C`gettext\*(C'\fR library documentation for more information. |
| 1437 |
.ie n .IP """LC_CTYPE""" 12 |
| 1438 |
.el .IP \f(CWLC_CTYPE\fR 12 |
| 1439 |
.IX Item "LC_CTYPE" |
| 1440 |
In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_CTYPE\*(C'\fR chooses the character type |
| 1441 |
locale. In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_CTYPE\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR |
| 1442 |
chooses the character type locale. |
| 1443 |
.ie n .IP """LC_COLLATE""" 12 |
| 1444 |
.el .IP \f(CWLC_COLLATE\fR 12 |
| 1445 |
.IX Item "LC_COLLATE" |
| 1446 |
In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_COLLATE\*(C'\fR chooses the collation |
| 1447 |
(sorting) locale. In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_COLLATE\*(C'\fR, |
| 1448 |
\&\f(CW\*(C`LANG\*(C'\fR chooses the collation locale. |
| 1449 |
.ie n .IP """LC_MONETARY""" 12 |
| 1450 |
.el .IP \f(CWLC_MONETARY\fR 12 |
| 1451 |
.IX Item "LC_MONETARY" |
| 1452 |
In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_MONETARY\*(C'\fR chooses the monetary |
| 1453 |
formatting locale. In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_MONETARY\*(C'\fR, |
| 1454 |
\&\f(CW\*(C`LANG\*(C'\fR chooses the monetary formatting locale. |
| 1455 |
.ie n .IP """LC_NUMERIC""" 12 |
| 1456 |
.el .IP \f(CWLC_NUMERIC\fR 12 |
| 1457 |
.IX Item "LC_NUMERIC" |
| 1458 |
In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_NUMERIC\*(C'\fR chooses the numeric format |
| 1459 |
locale. In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_NUMERIC\*(C'\fR, \f(CW\*(C`LANG\*(C'\fR |
| 1460 |
chooses the numeric format. |
| 1461 |
.ie n .IP """LC_TIME""" 12 |
| 1462 |
.el .IP \f(CWLC_TIME\fR 12 |
| 1463 |
.IX Item "LC_TIME" |
| 1464 |
In the absence of \f(CW\*(C`LC_ALL\*(C'\fR, \f(CW\*(C`LC_TIME\*(C'\fR chooses the date and time |
| 1465 |
formatting locale. In the absence of both \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`LC_TIME\*(C'\fR, |
| 1466 |
\&\f(CW\*(C`LANG\*(C'\fR chooses the date and time formatting locale. |
| 1467 |
.ie n .IP """LANG""" 12 |
| 1468 |
.el .IP \f(CWLANG\fR 12 |
| 1469 |
.IX Item "LANG" |
| 1470 |
\&\f(CW\*(C`LANG\*(C'\fR is the "catch-all" locale environment variable. If it is set, it |
| 1471 |
is used as the last resort after the overall \f(CW\*(C`LC_ALL\*(C'\fR and the |
| 1472 |
category-specific \f(CW\*(C`LC_\fR\f(CIfoo\fR\f(CW\*(C'\fR. |
| 1473 |
.SS Examples |
| 1474 |
.IX Subsection "Examples" |
| 1475 |
The \f(CW\*(C`LC_NUMERIC\*(C'\fR controls the numeric output: |
| 1476 |
.PP |
| 1477 |
.Vb 4 |
| 1478 |
\& use locale; |
| 1479 |
\& use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants. |
| 1480 |
\& setlocale(LC_NUMERIC, "fr_FR") or die "Pardon"; |
| 1481 |
\& printf "%g\en", 1.23; # If the "fr_FR" succeeded, probably shows 1,23. |
| 1482 |
.Ve |
| 1483 |
.PP |
| 1484 |
and also how strings are parsed by \f(CWPOSIX::strtod()\fR as numbers: |
| 1485 |
.PP |
| 1486 |
.Vb 5 |
| 1487 |
\& use locale; |
| 1488 |
\& use POSIX qw(locale_h strtod); |
| 1489 |
\& setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung"; |
| 1490 |
\& my $x = strtod("2,34") + 5; |
| 1491 |
\& print $x, "\en"; # Probably shows 7,34. |
| 1492 |
.Ve |
| 1493 |
.SH NOTES |
| 1494 |
.IX Header "NOTES" |
| 1495 |
.ie n .SS "String ""eval"" and ""LC_NUMERIC""" |
| 1496 |
.el .SS "String \f(CWeval\fP and \f(CWLC_NUMERIC\fP" |
| 1497 |
.IX Subsection "String eval and LC_NUMERIC" |
| 1498 |
A string eval parses its expression as standard |
| 1499 |
Perl. It is therefore expecting the decimal point to be a dot. If |
| 1500 |
\&\f(CW\*(C`LC_NUMERIC\*(C'\fR is set to have this be a comma instead, the parsing will |
| 1501 |
be confused, perhaps silently. |
| 1502 |
.PP |
| 1503 |
.Vb 6 |
| 1504 |
\& use locale; |
| 1505 |
\& use POSIX qw(locale_h); |
| 1506 |
\& setlocale(LC_NUMERIC, "fr_FR") or die "Pardon"; |
| 1507 |
\& my $x = 1.2; |
| 1508 |
\& print eval "$x + 1.5"; |
| 1509 |
\& print "\en"; |
| 1510 |
.Ve |
| 1511 |
.PP |
| 1512 |
prints \f(CW\*(C`13,5\*(C'\fR. This is because in that locale, the comma is the |
| 1513 |
decimal point character. The \f(CW\*(C`eval\*(C'\fR thus expands to: |
| 1514 |
.PP |
| 1515 |
.Vb 1 |
| 1516 |
\& eval "1,2 + 1.5" |
| 1517 |
.Ve |
| 1518 |
.PP |
| 1519 |
and the result is not what you likely expected. No warnings are |
| 1520 |
generated. If you do string \f(CW\*(C`eval\*(C'\fR's within the scope of |
| 1521 |
\&\f(CW\*(C`use\ locale\*(C'\fR, you should instead change the \f(CW\*(C`eval\*(C'\fR line to do |
| 1522 |
something like: |
| 1523 |
.PP |
| 1524 |
.Vb 1 |
| 1525 |
\& print eval "no locale; $x + 1.5"; |
| 1526 |
.Ve |
| 1527 |
.PP |
| 1528 |
This prints \f(CW2.7\fR. |
| 1529 |
.PP |
| 1530 |
You could also exclude \f(CW\*(C`LC_NUMERIC\*(C'\fR, if you don't need it, by |
| 1531 |
.PP |
| 1532 |
.Vb 1 |
| 1533 |
\& use locale \*(Aq:!numeric\*(Aq; |
| 1534 |
.Ve |
| 1535 |
.SS "Backward compatibility" |
| 1536 |
.IX Subsection "Backward compatibility" |
| 1537 |
Versions of Perl prior to 5.004 \fBmostly\fR ignored locale information, |
| 1538 |
generally behaving as if something similar to the \f(CW"C"\fR locale were |
| 1539 |
always in force, even if the program environment suggested otherwise |
| 1540 |
(see "The setlocale function"). By default, Perl still behaves this |
| 1541 |
way for backward compatibility. If you want a Perl application to pay |
| 1542 |
attention to locale information, you \fBmust\fR use the \f(CW\*(C`use\ locale\*(C'\fR |
| 1543 |
pragma (see "The "use locale" pragma") or, in the unlikely event |
| 1544 |
that you want to do so for just pattern matching, the |
| 1545 |
\&\f(CW\*(C`/l\*(C'\fR regular expression modifier (see "Character set |
| 1546 |
modifiers" in perlre) to instruct it to do so. |
| 1547 |
.PP |
| 1548 |
Versions of Perl from 5.002 to 5.003 did use the \f(CW\*(C`LC_CTYPE\*(C'\fR |
| 1549 |
information if available; that is, \f(CW\*(C`\ew\*(C'\fR did understand what |
| 1550 |
were the letters according to the locale environment variables. |
| 1551 |
The problem was that the user had no control over the feature: |
| 1552 |
if the C library supported locales, Perl used them. |
| 1553 |
.SS "I18N:Collate obsolete" |
| 1554 |
.IX Subsection "I18N:Collate obsolete" |
| 1555 |
In versions of Perl prior to 5.004, per-locale collation was possible |
| 1556 |
using the \f(CW\*(C`I18N::Collate\*(C'\fR library module. This module is now mildly |
| 1557 |
obsolete and should be avoided in new applications. The \f(CW\*(C`LC_COLLATE\*(C'\fR |
| 1558 |
functionality is now integrated into the Perl core language: One can |
| 1559 |
use locale-specific scalar data completely normally with \f(CW\*(C`use locale\*(C'\fR, |
| 1560 |
so there is no longer any need to juggle with the scalar references of |
| 1561 |
\&\f(CW\*(C`I18N::Collate\*(C'\fR. |
| 1562 |
.SS "Sort speed and memory use impacts" |
| 1563 |
.IX Subsection "Sort speed and memory use impacts" |
| 1564 |
Comparing and sorting by locale is usually slower than the default |
| 1565 |
sorting; slow-downs of two to four times have been observed. It will |
| 1566 |
also consume more memory: once a Perl scalar variable has participated |
| 1567 |
in any string comparison or sorting operation obeying the locale |
| 1568 |
collation rules, it will take 3\-15 times more memory than before. (The |
| 1569 |
exact multiplier depends on the string's contents, the operating system |
| 1570 |
and the locale.) These downsides are dictated more by the operating |
| 1571 |
system's implementation of the locale system than by Perl. |
| 1572 |
.SS "Freely available locale definitions" |
| 1573 |
.IX Subsection "Freely available locale definitions" |
| 1574 |
The Unicode CLDR project extracts the POSIX portion of many of its |
| 1575 |
locales, available at |
| 1576 |
.PP |
| 1577 |
.Vb 1 |
| 1578 |
\& https://unicode.org/Public/cldr/2.0.1/ |
| 1579 |
.Ve |
| 1580 |
.PP |
| 1581 |
(Newer versions of CLDR require you to compute the POSIX data yourself. |
| 1582 |
See <https://unicode.org/Public/cldr/latest/>.) |
| 1583 |
.PP |
| 1584 |
There is a large collection of locale definitions at: |
| 1585 |
.PP |
| 1586 |
.Vb 1 |
| 1587 |
\& http://std.dkuug.dk/i18n/WG15\-collection/locales/ |
| 1588 |
.Ve |
| 1589 |
.PP |
| 1590 |
You should be aware that it is |
| 1591 |
unsupported, and is not claimed to be fit for any purpose. If your |
| 1592 |
system allows installation of arbitrary locales, you may find the |
| 1593 |
definitions useful as they are, or as a basis for the development of |
| 1594 |
your own locales. |
| 1595 |
.SS "I18n and l10n" |
| 1596 |
.IX Subsection "I18n and l10n" |
| 1597 |
"Internationalization" is often abbreviated as \fBi18n\fR because its first |
| 1598 |
and last letters are separated by eighteen others. (You may guess why |
| 1599 |
the internalin ... internaliti ... i18n tends to get abbreviated.) In |
| 1600 |
the same way, "localization" is often abbreviated to \fBl10n\fR. |
| 1601 |
.SS "An imperfect standard" |
| 1602 |
.IX Subsection "An imperfect standard" |
| 1603 |
Internationalization, as defined in the C and POSIX standards, can be |
| 1604 |
criticized as incomplete and ungainly. They also have a tendency, like |
| 1605 |
standards groups, to divide the world into nations, when we all know |
| 1606 |
that the world can equally well be divided into bankers, bikers, gamers, |
| 1607 |
and so on. |
| 1608 |
.SH "Unicode and UTF\-8" |
| 1609 |
.IX Header "Unicode and UTF-8" |
| 1610 |
The support of Unicode is new starting from Perl version v5.6, and more fully |
| 1611 |
implemented in versions v5.8 and later. See perluniintro. |
| 1612 |
.PP |
| 1613 |
Starting in Perl v5.20, UTF\-8 locales are supported in Perl, except |
| 1614 |
\&\f(CW\*(C`LC_COLLATE\*(C'\fR is only partially supported; collation support is improved |
| 1615 |
in Perl v5.26 to a level that may be sufficient for your needs |
| 1616 |
(see "Category \f(CW\*(C`LC_COLLATE\*(C'\fR: Collation: Text Comparisons and Sorting"). |
| 1617 |
.PP |
| 1618 |
If you have Perl v5.16 or v5.18 and can't upgrade, you can use |
| 1619 |
.PP |
| 1620 |
.Vb 1 |
| 1621 |
\& use locale \*(Aq:not_characters\*(Aq; |
| 1622 |
.Ve |
| 1623 |
.PP |
| 1624 |
When this form of the pragma is used, only the non-character portions of |
| 1625 |
locales are used by Perl, for example \f(CW\*(C`LC_NUMERIC\*(C'\fR. Perl assumes that |
| 1626 |
you have translated all the characters it is to operate on into Unicode |
| 1627 |
(actually the platform's native character set (ASCII or EBCDIC) plus |
| 1628 |
Unicode). For data in files, this can conveniently be done by also |
| 1629 |
specifying |
| 1630 |
.PP |
| 1631 |
.Vb 1 |
| 1632 |
\& use open \*(Aq:locale\*(Aq; |
| 1633 |
.Ve |
| 1634 |
.PP |
| 1635 |
This pragma arranges for all inputs from files to be translated into |
| 1636 |
Unicode from the current locale as specified in the environment (see |
| 1637 |
"ENVIRONMENT"), and all outputs to files to be translated back |
| 1638 |
into the locale. (See open). On a per-filehandle basis, you can |
| 1639 |
instead use the PerlIO::locale module, or the Encode::Locale |
| 1640 |
module, both available from CPAN. The latter module also has methods to |
| 1641 |
ease the handling of \f(CW\*(C`ARGV\*(C'\fR and environment variables, and can be used |
| 1642 |
on individual strings. If you know that all your locales will be |
| 1643 |
UTF\-8, as many are these days, you can use the |
| 1644 |
\&\fB\-C\fR command line switch. |
| 1645 |
.PP |
| 1646 |
This form of the pragma allows essentially seamless handling of locales |
| 1647 |
with Unicode. The collation order will be by Unicode code point order. |
| 1648 |
Unicode::Collate can be used to get Unicode rules collation. |
| 1649 |
.PP |
| 1650 |
All the modules and switches just described can be used in v5.20 with |
| 1651 |
just plain \f(CW\*(C`use locale\*(C'\fR, and, should the input locales not be UTF\-8, |
| 1652 |
you'll get the less than ideal behavior, described below, that you get |
| 1653 |
with pre\-v5.16 Perls, or when you use the locale pragma without the |
| 1654 |
\&\f(CW\*(C`:not_characters\*(C'\fR parameter in v5.16 and v5.18. If you are using |
| 1655 |
exclusively UTF\-8 locales in v5.20 and higher, the rest of this section |
| 1656 |
does not apply to you. |
| 1657 |
.PP |
| 1658 |
There are two cases, multi-byte and single-byte locales. First |
| 1659 |
multi-byte: |
| 1660 |
.PP |
| 1661 |
The only multi-byte (or wide character) locale that Perl is ever likely |
| 1662 |
to support is UTF\-8. This is due to the difficulty of implementation, |
| 1663 |
the fact that high quality UTF\-8 locales are now published for every |
| 1664 |
area of the world (<https://unicode.org/Public/cldr/2.0.1/> for |
| 1665 |
ones that are already set-up, but from an earlier version; |
| 1666 |
<https://unicode.org/Public/cldr/latest/> for the most up-to-date, but |
| 1667 |
you have to extract the POSIX information yourself), and |
| 1668 |
failing all that, you can use the Encode module to translate to/from |
| 1669 |
your locale. So, you'll have to do one of those things if you're using |
| 1670 |
one of these locales, such as Big5 or Shift JIS. For UTF\-8 locales, in |
| 1671 |
Perls (pre v5.20) that don't have full UTF\-8 locale support, they may |
| 1672 |
work reasonably well (depending on your C library implementation) |
| 1673 |
simply because both |
| 1674 |
they and Perl store characters that take up multiple bytes the same way. |
| 1675 |
However, some, if not most, C library implementations may not process |
| 1676 |
the characters in the upper half of the Latin\-1 range (128 \- 255) |
| 1677 |
properly under \f(CW\*(C`LC_CTYPE\*(C'\fR. To see if a character is a particular type |
| 1678 |
under a locale, Perl uses the functions like \f(CWisalnum()\fR. Your C |
| 1679 |
library may not work for UTF\-8 locales with those functions, instead |
| 1680 |
only working under the newer wide library functions like \f(CWiswalnum()\fR, |
| 1681 |
which Perl does not use. |
| 1682 |
These multi-byte locales are treated like single-byte locales, and will |
| 1683 |
have the restrictions described below. Starting in Perl v5.22 a warning |
| 1684 |
message is raised when Perl detects a multi-byte locale that it doesn't |
| 1685 |
fully support. |
| 1686 |
.PP |
| 1687 |
For single-byte locales, |
| 1688 |
Perl generally takes the tack to use locale rules on code points that can fit |
| 1689 |
in a single byte, and Unicode rules for those that can't (though this |
| 1690 |
isn't uniformly applied, see the note at the end of this section). This |
| 1691 |
prevents many problems in locales that aren't UTF\-8. Suppose the locale |
| 1692 |
is ISO8859\-7, Greek. The character at 0xD7 there is a capital Chi. But |
| 1693 |
in the ISO8859\-1 locale, Latin1, it is a multiplication sign. The POSIX |
| 1694 |
regular expression character class \f(CW\*(C`[[:alpha:]]\*(C'\fR will magically match |
| 1695 |
0xD7 in the Greek locale but not in the Latin one. |
| 1696 |
.PP |
| 1697 |
However, there are places where this breaks down. Certain Perl constructs are |
| 1698 |
for Unicode only, such as \f(CW\*(C`\ep{Alpha}\*(C'\fR. They assume that 0xD7 always has its |
| 1699 |
Unicode meaning (or the equivalent on EBCDIC platforms). Since Latin1 is a |
| 1700 |
subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and |
| 1701 |
Unicode, \f(CW\*(C`\ep{Alpha}\*(C'\fR will never match it, regardless of locale. A similar |
| 1702 |
issue occurs with \f(CW\*(C`\eN{...}\*(C'\fR. Prior to v5.20, it is therefore a bad |
| 1703 |
idea to use \f(CW\*(C`\ep{}\*(C'\fR or |
| 1704 |
\&\f(CW\*(C`\eN{}\*(C'\fR under plain \f(CW\*(C`use locale\*(C'\fR\-\-\fIunless\fR you can guarantee that the |
| 1705 |
locale will be ISO8859\-1. Use POSIX character classes instead. |
| 1706 |
.PP |
| 1707 |
Another problem with this approach is that operations that cross the |
| 1708 |
single byte/multiple byte boundary are not well-defined, and so are |
| 1709 |
disallowed. (This boundary is between the codepoints at 255/256.) |
| 1710 |
For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178) |
| 1711 |
should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF). But in the |
| 1712 |
Greek locale, for example, there is no character at 0xFF, and Perl |
| 1713 |
has no way of knowing what the character at 0xFF is really supposed to |
| 1714 |
represent. Thus it disallows the operation. In this mode, the |
| 1715 |
lowercase of U+0178 is itself. |
| 1716 |
.PP |
| 1717 |
The same problems ensue if you enable automatic UTF\-8\-ification of your |
| 1718 |
standard file handles, default \f(CWopen()\fR layer, and \f(CW@ARGV\fR on non\-ISO8859\-1, |
| 1719 |
non\-UTF\-8 locales (by using either the \fB\-C\fR command line switch or the |
| 1720 |
\&\f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable; see |
| 1721 |
perlrun). |
| 1722 |
Things are read in as UTF\-8, which would normally imply a Unicode |
| 1723 |
interpretation, but the presence of a locale causes them to be interpreted |
| 1724 |
in that locale instead. For example, a 0xD7 code point in the Unicode |
| 1725 |
input, which should mean the multiplication sign, won't be interpreted by |
| 1726 |
Perl that way under the Greek locale. This is not a problem |
| 1727 |
\&\fIprovided\fR you make certain that all locales will always and only be either |
| 1728 |
an ISO8859\-1, or, if you don't have a deficient C library, a UTF\-8 locale. |
| 1729 |
.PP |
| 1730 |
Still another problem is that this approach can lead to two code |
| 1731 |
points meaning the same character. Thus in a Greek locale, both U+03A7 |
| 1732 |
and U+00D7 are GREEK CAPITAL LETTER CHI. |
| 1733 |
.PP |
| 1734 |
Because of all these problems, starting in v5.22, Perl will raise a |
| 1735 |
warning if a multi-byte (hence Unicode) code point is used when a |
| 1736 |
single-byte locale is in effect. (Although it doesn't check for this if |
| 1737 |
doing so would unreasonably slow execution down.) |
| 1738 |
.PP |
| 1739 |
Vendor locales are notoriously buggy, and it is difficult for Perl to test |
| 1740 |
its locale-handling code because this interacts with code that Perl has no |
| 1741 |
control over; therefore the locale-handling code in Perl may be buggy as |
| 1742 |
well. (However, the Unicode-supplied locales should be better, and |
| 1743 |
there is a feed back mechanism to correct any problems. See |
| 1744 |
"Freely available locale definitions".) |
| 1745 |
.PP |
| 1746 |
If you have Perl v5.16, the problems mentioned above go away if you use |
| 1747 |
the \f(CW\*(C`:not_characters\*(C'\fR parameter to the locale pragma (except for vendor |
| 1748 |
bugs in the non-character portions). If you don't have v5.16, and you |
| 1749 |
\&\fIdo\fR have locales that work, using them may be worthwhile for certain |
| 1750 |
specific purposes, as long as you keep in mind the gotchas already |
| 1751 |
mentioned. For example, if the collation for your locales works, it |
| 1752 |
runs faster under locales than under Unicode::Collate; and you gain |
| 1753 |
access to such things as the local currency symbol and the names of the |
| 1754 |
months and days of the week. (But to hammer home the point, in v5.16, |
| 1755 |
you get this access without the downsides of locales by using the |
| 1756 |
\&\f(CW\*(C`:not_characters\*(C'\fR form of the pragma.) |
| 1757 |
.PP |
| 1758 |
Note: The policy of using locale rules for code points that can fit in a |
| 1759 |
byte, and Unicode rules for those that can't is not uniformly applied. |
| 1760 |
Pre\-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly |
| 1761 |
consistently to regular expression matching except for bracketed |
| 1762 |
character classes; in v5.14 it was extended to all regex matches; and in |
| 1763 |
v5.16 to the casing operations such as \f(CW\*(C`\eL\*(C'\fR and \f(CWuc()\fR. For |
| 1764 |
collation, in all releases so far, the system's \f(CWstrxfrm()\fR function is |
| 1765 |
called, and whatever it does is what you get. Starting in v5.26, various |
| 1766 |
bugs are fixed with the way perl uses this function. |
| 1767 |
.SH BUGS |
| 1768 |
.IX Header "BUGS" |
| 1769 |
.ie n .SS "Collation of strings containing embedded ""NUL"" characters" |
| 1770 |
.el .SS "Collation of strings containing embedded \f(CWNUL\fP characters" |
| 1771 |
.IX Subsection "Collation of strings containing embedded NUL characters" |
| 1772 |
\&\f(CW\*(C`NUL\*(C'\fR characters will sort the same as the lowest collating control |
| 1773 |
character does, or to \f(CW"\e001"\fR in the unlikely event that there are no |
| 1774 |
control characters at all in the locale. In cases where the strings |
| 1775 |
don't contain this non\-\f(CW\*(C`NUL\*(C'\fR control, the results will be correct, and |
| 1776 |
in many locales, this control, whatever it might be, will rarely be |
| 1777 |
encountered. But there are cases where a \f(CW\*(C`NUL\*(C'\fR should sort before this |
| 1778 |
control, but doesn't. If two strings do collate identically, the one |
| 1779 |
containing the \f(CW\*(C`NUL\*(C'\fR will sort to earlier. Prior to 5.26, there were |
| 1780 |
more bugs. |
| 1781 |
.ie n .SS """LANGUAGE""" |
| 1782 |
.el .SS \f(CWLANGUAGE\fP |
| 1783 |
.IX Subsection "LANGUAGE" |
| 1784 |
As stated above, Perl ignores this environment variable. |
| 1785 |
.SS "Embedded perls and multi-threaded" |
| 1786 |
.IX Subsection "Embedded perls and multi-threaded" |
| 1787 |
You should not change the locale after startup on a platform where |
| 1788 |
\&\f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is 0. It will always be 1 on an unthreaded |
| 1789 |
platform. |
| 1790 |
.PP |
| 1791 |
XS writers should refer to "Dealing with embedded perls and threads" in perlclib. |
| 1792 |
.SS "Broken systems" |
| 1793 |
.IX Subsection "Broken systems" |
| 1794 |
On a few remaining systems, the operating system's locale support |
| 1795 |
is broken and cannot be fixed or used by Perl. Such deficiencies can |
| 1796 |
and will result in mysterious hangs and/or Perl core dumps when |
| 1797 |
\&\f(CW\*(C`use locale\*(C'\fR is in effect. When confronted with such a system, |
| 1798 |
please report in excruciating detail to |
| 1799 |
<<https://github.com/Perl/perl5/issues>>, and |
| 1800 |
also contact your vendor: bug fixes may exist for these problems |
| 1801 |
in your operating system. Sometimes such bug fixes are called an |
| 1802 |
operating system upgrade. If you have the source for Perl, include in |
| 1803 |
the bug report the output of the test described above in "Testing |
| 1804 |
for broken locales". |
| 1805 |
.SH "SEE ALSO" |
| 1806 |
.IX Header "SEE ALSO" |
| 1807 |
I18N::Langinfo, perluniintro, perlunicode, open, |
| 1808 |
"localeconv" in POSIX, |
| 1809 |
"setlocale" in POSIX, "strcoll" in POSIX, "strftime" in POSIX, |
| 1810 |
"strtod" in POSIX, "strxfrm" in POSIX. |
| 1811 |
.PP |
| 1812 |
For special considerations when Perl is embedded in a C program, |
| 1813 |
see "Using embedded Perl with POSIX locales" in perlembed. |
| 1814 |
.SH HISTORY |
| 1815 |
.IX Header "HISTORY" |
| 1816 |
Jarkko Hietaniemi's original \fIperli18n.pod\fR heavily hacked by Dominic |
| 1817 |
Dunlop, assisted by the perl5\-porters. Prose worked over a bit by |
| 1818 |
Tom Christiansen, and now maintained by Perl 5 porters. |