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