5 perllocale - Perl locale handling (internationalization and localization)
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.
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>).
25 Perl has been extended to support the locale system. This
26 is controlled per application by using one pragma, one function call,
27 and several environment variables.
29 Unfortunately, there are quite a few deficiencies with the design (and
30 often, the implementations) of locales, and their use for character sets
31 has mostly been supplanted by Unicode (see L<perlunitut> for an
32 introduction to that, and keep on reading here for how Unicode interacts
33 with locales in Perl).
35 Perl continues to support the old locale system, and starting in v5.16,
36 provides a hybrid way to use the Unicode character set, along with the
37 other portions of locales that may not be so problematic.
38 (Unicode is also creating C<CLDR>, the "Common Locale Data Repository",
39 L<http://cldr.unicode.org/> which includes more types of information than
40 are available in the POSIX locale system. At the time of this writing,
41 there was no CPAN module that provides access to this XML-encoded data.
42 However, many of its locales have the POSIX-only data extracted, and are
43 available at L<http://unicode.org/Public/cldr/latest/>.)
45 =head1 WHAT IS A LOCALE
47 A locale is a set of data that describes various aspects of how various
48 communities in the world categorize their world. These categories are
49 broken down into the following types (some of which include a brief
54 =item Category LC_NUMERIC: Numeric formatting
56 This indicates how numbers should be formatted for human readability,
57 for example the character used as the decimal point.
59 =item Category LC_MONETARY: Formatting of monetary amounts
62 The nbsp below makes this look better
66 =item Category LC_TIME: Date/Time formatting
69 The nbsp below makes this look better
73 =item Category LC_MESSAGES: Error and other messages
75 This is used by Perl itself only for accessing operating system error
76 messages via L<$!|perlvar/$ERRNO> and L<$^E|perlvar/$EXTENDED_OS_ERROR>.
78 =item Category LC_COLLATE: Collation
80 This indicates the ordering of letters for comparison and sorting.
81 In Latin alphabets, for example, "b", generally follows "a".
83 =item Category LC_CTYPE: Character Types
85 This indicates, for example if a character is an uppercase letter.
87 =item Other categories
89 Some platforms have other categories, dealing with such things as
90 measurement units and paper sizes. None of these are used directly by
91 Perl, but outside operations that Perl interacts with may use
92 these. See L</Not within the scope of any "use locale" variant> below.
96 More details on the categories used by Perl are given below in L</LOCALE
99 Together, these categories go a long way towards being able to customize
100 a single program to run in many different locations. But there are
101 deficiencies, so keep reading.
103 =head1 PREPARING TO USE LOCALES
105 Perl itself will not use locales unless specifically requested to (but
106 again note that Perl may interact with code that does use them). Even
107 if there is such a request, B<all> of the following must be true
108 for it to work properly:
114 B<Your operating system must support the locale system>. If it does,
115 you should find that the C<setlocale()> function is a documented part of
120 B<Definitions for locales that you use must be installed>. You, or
121 your system administrator, must make sure that this is the case. The
122 available locales, the location in which they are kept, and the manner
123 in which they are installed all vary from system to system. Some systems
124 provide only a few, hard-wired locales and do not allow more to be
125 added. Others allow you to add "canned" locales provided by the system
126 supplier. Still others allow you or the system administrator to define
127 and add arbitrary locales. (You may have to ask your supplier to
128 provide canned locales that are not delivered with your operating
129 system.) Read your system documentation for further illumination.
133 B<Perl must believe that the locale system is supported>. If it does,
134 C<perl -V:d_setlocale> will say that the value for C<d_setlocale> is
139 If you want a Perl application to process and present your data
140 according to a particular locale, the application code should include
141 the S<C<use locale>> pragma (see L<The use locale pragma>) where
142 appropriate, and B<at least one> of the following must be true:
148 B<The locale-determining environment variables (see L</"ENVIRONMENT">)
149 must be correctly set up> at the time the application is started, either
150 by yourself or by whomever set up your system account; or
154 B<The application must set its own locale> using the method described in
155 L<The setlocale function>.
161 =head2 The use locale pragma
163 By default, Perl itself ignores the current locale. The S<C<use locale>>
164 pragma tells Perl to use the current locale for some operations.
165 Starting in v5.16, there is an optional parameter to this pragma:
167 use locale ':not_characters';
169 This parameter allows better mixing of locales and Unicode, and is
170 described fully in L</Unicode and UTF-8>, but briefly, it tells Perl to
171 not use the character portions of the locale definition, that is
172 the C<LC_CTYPE> and C<LC_COLLATE> categories. Instead it will use the
173 native character set (extended by Unicode). When using this parameter,
174 you are responsible for getting the external character set translated
175 into the native/Unicode one (which it already will be if it is one of
176 the increasingly popular UTF-8 locales). There are convenient ways of
177 doing this, as described in L</Unicode and UTF-8>.
179 The current locale is set at execution time by
180 L<setlocale()|/The setlocale function> described below. If that function
181 hasn't yet been called in the course of the program's execution, the
182 current locale is that which was determined by the L</"ENVIRONMENT"> in
183 effect at the start of the program, except that
184 C<L<LC_NUMERIC|/Category LC_NUMERIC: Numeric Formatting>> is always
185 initialized to the C locale (mentioned under L<Finding locales>).
186 If there is no valid environment, the current locale is whatever the
187 system default has been set to. It is likely, but not necessarily, the
190 The operations that are affected by locale are:
194 =item B<Not within the scope of any C<"use locale"> variant>
196 Only operations originating outside Perl should be affected, as follows:
202 The variable L<$!|perlvar/$ERRNO> (and its synonyms C<$ERRNO> and
203 C<$OS_ERROR>) when used as strings always are in terms of the current
208 The current locale is also used when going outside of Perl with
209 operations like L<system()|perlfunc/system LIST> or
210 L<qxE<sol>E<sol>|perlop/qxE<sol>STRINGE<sol>>, if those operations are
215 Also Perl gives access to various C library functions through the
216 L<POSIX> module. Some of those functions are always affected by the
217 current locale. For example, C<POSIX::strftime()> uses C<LC_TIME>;
218 C<POSIX::strtod()> uses C<LC_NUMERIC>; C<POSIX::strcoll()> and
219 C<POSIX::strxfrm()> use C<LC_COLLATE>; and character classification
220 functions like C<POSIX::isalnum()> use C<LC_CTYPE>. All such functions
221 will behave according to the current underlying locale, even if that
222 locale isn't exposed to Perl space.
226 Perl also provides lite wrappers for XS modules to use some C library
227 C<printf> functions. These wrappers don't do anything with the locale,
228 and the underlying C library function is affected by the locale in
229 effect at the time of the wrapper call.
230 The affected functions are
231 L<perlapi/my_sprintf>,
232 L<perlapi/my_snprintf>,
234 L<perlapi/my_vsnprintf>.
238 =item Lingering effects of C<S<use locale>>
240 Certain Perl operations that are set-up within the scope of a
241 C<use locale> variant retain that effect even outside the scope.
248 The output format of a L<write()|perlfunc/write> is determined by an
249 earlier format declaration (L<perlfunc/format>), so whether or not the
250 output is affected by locale is determined by if the C<format()> is
251 within the scope of a C<use locale> variant, not whether the C<write()>
256 Regular expression patterns can be compiled using
257 L<qrE<sol>E<sol>|perlop/qrE<sol>STRINGE<sol>msixpodual> with actual
258 matching deferred to later. Again, it is whether or not the compilation
259 was done within the scope of C<use locale> that determines the match
260 behavior, not if the matches are done within such a scope or not.
264 =item B<Under C<"use locale ':not_characters';">>
270 All the non-Perl operations.
274 B<Format declarations> (L<perlfunc/format>) and hence any subsequent
275 C<write()>s use C<LC_NUMERIC>.
279 B<stringification and output> use C<LC_NUMERIC>.
280 These include the results of
290 The nbsp below makes this look better
294 =item B<Under just plain C<"use locale";>>
300 All the above operations
304 B<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>) use
305 C<LC_COLLATE>. C<sort()> is also affected if used without an
306 explicit comparison function, because it uses C<cmp> by default.
308 B<Note:> C<eq> and C<ne> are unaffected by locale: they always
309 perform a char-by-char comparison of their scalar operands. What's
310 more, if C<cmp> finds that its operands are equal according to the
311 collation sequence specified by the current locale, it goes on to
312 perform a char-by-char comparison, and only returns I<0> (equal) if the
313 operands are char-for-char identical. If you really want to know whether
314 two strings--which C<eq> and C<cmp> may consider different--are equal
315 as far as collation in the locale is concerned, see the discussion in
316 L<Category LC_COLLATE: Collation>.
320 B<Regular expressions and case-modification functions> (C<uc()>, C<lc()>,
321 C<ucfirst()>, and C<lcfirst()>) use C<LC_CTYPE>
327 The default behavior is restored with the S<C<no locale>> pragma, or
328 upon reaching the end of the block enclosing C<use locale>.
329 Note that C<use locale> and C<use locale ':not_characters'> may be
330 nested, and that what is in effect within an inner scope will revert to
331 the outer scope's rules at the end of the inner scope.
333 The string result of any operation that uses locale
334 information is tainted, as it is possible for a locale to be
335 untrustworthy. See L<"SECURITY">.
337 =head2 The setlocale function
339 You can switch locales as often as you wish at run time with the
340 C<POSIX::setlocale()> function:
342 # Import locale-handling tool set from POSIX module.
343 # This example uses: setlocale -- the function call
344 # LC_CTYPE -- explained below
345 # (Showing the testing for success/failure of operations is
346 # omitted in these examples to avoid distracting from the main
349 use POSIX qw(locale_h);
353 # query and save the old locale
354 $old_locale = setlocale(LC_CTYPE);
356 setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
357 # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
359 setlocale(LC_CTYPE, "");
360 # LC_CTYPE now reset to default defined by LC_ALL/LC_CTYPE/LANG
361 # environment variables. See below for documentation.
363 # restore the old locale
364 setlocale(LC_CTYPE, $old_locale);
366 The first argument of C<setlocale()> gives the B<category>, the second the
367 B<locale>. The category tells in what aspect of data processing you
368 want to apply locale-specific rules. Category names are discussed in
369 L</LOCALE CATEGORIES> and L</"ENVIRONMENT">. The locale is the name of a
370 collection of customization information corresponding to a particular
371 combination of language, country or territory, and codeset. Read on for
372 hints on the naming of locales: not all systems name locales as in the
375 If no second argument is provided and the category is something other
376 than LC_ALL, the function returns a string naming the current locale
377 for the category. You can use this value as the second argument in a
378 subsequent call to C<setlocale()>, B<but> on some platforms the string
379 is opaque, not something that most people would be able to decipher as
380 to what locale it means.
382 If no second argument is provided and the category is LC_ALL, the
383 result is implementation-dependent. It may be a string of
384 concatenated locale names (separator also implementation-dependent)
385 or a single locale name. Please consult your L<setlocale(3)> man page for
388 If a second argument is given and it corresponds to a valid locale,
389 the locale for the category is set to that value, and the function
390 returns the now-current locale value. You can then use this in yet
391 another call to C<setlocale()>. (In some implementations, the return
392 value may sometimes differ from the value you gave as the second
393 argument--think of it as an alias for the value you gave.)
395 As the example shows, if the second argument is an empty string, the
396 category's locale is returned to the default specified by the
397 corresponding environment variables. Generally, this results in a
398 return to the default that was in force when Perl started up: changes
399 to the environment made by the application after startup may or may not
400 be noticed, depending on your system's C library.
402 Note that Perl ignores the current C<LC_CTYPE> and C<LC_COLLATE> locales
403 within the scope of a C<use locale ':not_characters'>.
405 If C<set_locale()> fails for some reason (for example, an attempt to set
406 to a locale unknown to the system), the locale for the category is not
407 changed, and the function returns C<undef>.
410 For further information about the categories, consult L<setlocale(3)>.
412 =head2 Finding locales
414 For locales available in your system, consult also L<setlocale(3)> to
415 see whether it leads to the list of available locales (search for the
416 I<SEE ALSO> section). If that fails, try the following command lines:
430 and see whether they list something resembling these
432 en_US.ISO8859-1 de_DE.ISO8859-1 ru_RU.ISO8859-5
433 en_US.iso88591 de_DE.iso88591 ru_RU.iso88595
436 english german russian
437 english.iso88591 german.iso88591 russian.iso88595
438 english.roman8 russian.koi8r
440 Sadly, even though the calling interface for C<setlocale()> has been
441 standardized, names of locales and the directories where the
442 configuration resides have not been. The basic form of the name is
443 I<language_territory>B<.>I<codeset>, but the latter parts after
444 I<language> are not always present. The I<language> and I<country>
445 are usually from the standards B<ISO 3166> and B<ISO 639>, the
446 two-letter abbreviations for the countries and the languages of the
447 world, respectively. The I<codeset> part often mentions some B<ISO
448 8859> character set, the Latin codesets. For example, C<ISO 8859-1>
449 is the so-called "Western European codeset" that can be used to encode
450 most Western European languages adequately. Again, there are several
451 ways to write even the name of that one standard. Lamentably.
453 Two special locales are worth particular mention: "C" and "POSIX".
454 Currently these are effectively the same locale: the difference is
455 mainly that the first one is defined by the C standard, the second by
456 the POSIX standard. They define the B<default locale> in which
457 every program starts in the absence of locale information in its
458 environment. (The I<default> default locale, if you will.) Its language
459 is (American) English and its character codeset ASCII or, rarely, a
460 superset thereof (such as the "DEC Multinational Character Set
461 (DEC-MCS)"). B<Warning>. The C locale delivered by some vendors
462 may not actually exactly match what the C standard calls for. So
465 B<NOTE>: Not all systems have the "POSIX" locale (not all systems are
466 POSIX-conformant), so use "C" when you need explicitly to specify this
469 =head2 LOCALE PROBLEMS
471 You may encounter the following warning message at Perl startup:
473 perl: warning: Setting locale failed.
474 perl: warning: Please check that your locale settings:
477 are supported and installed on your system.
478 perl: warning: Falling back to the standard locale ("C").
480 This means that your locale settings had LC_ALL set to "En_US" and
481 LANG exists but has no value. Perl tried to believe you but could not.
482 Instead, Perl gave up and fell back to the "C" locale, the default locale
483 that is supposed to work no matter what. This usually means your locale
484 settings were wrong, they mention locales your system has never heard
485 of, or the locale installation in your system has problems (for example,
486 some system files are broken or missing). There are quick and temporary
487 fixes to these problems, as well as more thorough and lasting fixes.
489 =head2 Testing for broken locales
491 If you are building Perl from source, the Perl test suite file
492 F<lib/locale.t> can be used to test the locales on your system.
493 Setting the environment variable C<PERL_DEBUG_FULL_TEST> to 1
494 will cause it to output detailed results. For example, on Linux, you
497 PERL_DEBUG_FULL_TEST=1 ./perl -T -Ilib lib/locale.t > locale.log 2>&1
499 Besides many other tests, it will test every locale it finds on your
500 system to see if they conform to the POSIX standard. If any have
501 errors, it will include a summary near the end of the output of which
502 locales passed all its tests, and which failed, and why.
504 =head2 Temporarily fixing locale problems
506 The two quickest fixes are either to render Perl silent about any
507 locale inconsistencies or to run Perl under the default locale "C".
509 Perl's moaning about locale problems can be silenced by setting the
510 environment variable PERL_BADLANG to a zero value, for example "0".
511 This method really just sweeps the problem under the carpet: you tell
512 Perl to shut up even when Perl sees that something is wrong. Do not
513 be surprised if later something locale-dependent misbehaves.
515 Perl can be run under the "C" locale by setting the environment
516 variable LC_ALL to "C". This method is perhaps a bit more civilized
517 than the PERL_BADLANG approach, but setting LC_ALL (or
518 other locale variables) may affect other programs as well, not just
519 Perl. In particular, external programs run from within Perl will see
520 these changes. If you make the new settings permanent (read on), all
521 programs you run see the changes. See L<"ENVIRONMENT"> for
522 the full list of relevant environment variables and L<USING LOCALES>
523 for their effects in Perl. Effects in other programs are
524 easily deducible. For example, the variable LC_COLLATE may well affect
525 your B<sort> program (or whatever the program that arranges "records"
526 alphabetically in your system is called).
528 You can test out changing these variables temporarily, and if the
529 new settings seem to help, put those settings into your shell startup
530 files. Consult your local documentation for the exact details. For in
531 Bourne-like shells (B<sh>, B<ksh>, B<bash>, B<zsh>):
533 LC_ALL=en_US.ISO8859-1
536 This assumes that we saw the locale "en_US.ISO8859-1" using the commands
537 discussed above. We decided to try that instead of the above faulty
538 locale "En_US"--and in Cshish shells (B<csh>, B<tcsh>)
540 setenv LC_ALL en_US.ISO8859-1
542 or if you have the "env" application you can do in any shell
544 env LC_ALL=en_US.ISO8859-1 perl ...
546 If you do not know what shell you have, consult your local
547 helpdesk or the equivalent.
549 =head2 Permanently fixing locale problems
551 The slower but superior fixes are when you may be able to yourself
552 fix the misconfiguration of your own environment variables. The
553 mis(sing)configuration of the whole system's locales usually requires
554 the help of your friendly system administrator.
556 First, see earlier in this document about L<Finding locales>. That tells
557 how to find which locales are really supported--and more importantly,
558 installed--on your system. In our example error message, environment
559 variables affecting the locale are listed in the order of decreasing
560 importance (and unset variables do not matter). Therefore, having
561 LC_ALL set to "En_US" must have been the bad choice, as shown by the
562 error message. First try fixing locale settings listed first.
564 Second, if using the listed commands you see something B<exactly>
565 (prefix matches do not count and case usually counts) like "En_US"
566 without the quotes, then you should be okay because you are using a
567 locale name that should be installed and available in your system.
568 In this case, see L<Permanently fixing your system's locale configuration>.
570 =head2 Permanently fixing your system's locale configuration
572 This is when you see something like:
574 perl: warning: Please check that your locale settings:
577 are supported and installed on your system.
579 but then cannot see that "En_US" listed by the above-mentioned
580 commands. You may see things like "en_US.ISO8859-1", but that isn't
581 the same. In this case, try running under a locale
582 that you can list and which somehow matches what you tried. The
583 rules for matching locale names are a bit vague because
584 standardization is weak in this area. See again the
585 L<Finding locales> about general rules.
587 =head2 Fixing system locale configuration
589 Contact a system administrator (preferably your own) and report the exact
590 error message you get, and ask them to read this same documentation you
591 are now reading. They should be able to check whether there is something
592 wrong with the locale configuration of the system. The L<Finding locales>
593 section is unfortunately a bit vague about the exact commands and places
594 because these things are not that standardized.
596 =head2 The localeconv function
598 The C<POSIX::localeconv()> function allows you to get particulars of the
599 locale-dependent numeric formatting information specified by the current
600 C<LC_NUMERIC> and C<LC_MONETARY> locales. (If you just want the name of
601 the current locale for a particular category, use C<POSIX::setlocale()>
602 with a single parameter--see L<The setlocale function>.)
604 use POSIX qw(locale_h);
606 # Get a reference to a hash of locale-dependent info
607 $locale_values = localeconv();
609 # Output sorted list of the values
610 for (sort keys %$locale_values) {
611 printf "%-20s = %s\n", $_, $locale_values->{$_}
614 C<localeconv()> takes no arguments, and returns B<a reference to> a hash.
615 The keys of this hash are variable names for formatting, such as
616 C<decimal_point> and C<thousands_sep>. The values are the
617 corresponding, er, values. See L<POSIX/localeconv> for a longer
618 example listing the categories an implementation might be expected to
619 provide; some provide more and others fewer. You don't need an
620 explicit C<use locale>, because C<localeconv()> always observes the
623 Here's a simple-minded example program that rewrites its command-line
624 parameters as integers correctly formatted in the current locale:
626 use POSIX qw(locale_h);
628 # Get some of locale's numeric formatting parameters
629 my ($thousands_sep, $grouping) =
630 @{localeconv()}{'thousands_sep', 'grouping'};
632 # Apply defaults if values are missing
633 $thousands_sep = ',' unless $thousands_sep;
635 # grouping and mon_grouping are packed lists
636 # of small integers (characters) telling the
637 # grouping (thousand_seps and mon_thousand_seps
638 # being the group dividers) of numbers and
639 # monetary quantities. The integers' meanings:
640 # 255 means no more grouping, 0 means repeat
641 # the previous grouping, 1-254 means use that
642 # as the current grouping. Grouping goes from
643 # right to left (low to high digits). In the
644 # below we cheat slightly by never using anything
645 # else than the first grouping (whatever that is).
647 @grouping = unpack("C*", $grouping);
652 # Format command line params for current locale
654 $_ = int; # Chop non-integer part
656 s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
661 =head2 I18N::Langinfo
663 Another interface for querying locale-dependent information is the
664 C<I18N::Langinfo::langinfo()> function, available at least in Unix-like
667 The following example will import the C<langinfo()> function itself and
668 three constants to be used as arguments to C<langinfo()>: a constant for
669 the abbreviated first day of the week (the numbering starts from
670 Sunday = 1) and two more constants for the affirmative and negative
671 answers for a yes/no question in the current locale.
673 use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
675 my ($abday_1, $yesstr, $nostr)
676 = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
678 print "$abday_1? [$yesstr/$nostr] ";
680 In other words, in the "C" (or English) locale the above will probably
681 print something like:
685 See L<I18N::Langinfo> for more information.
687 =head1 LOCALE CATEGORIES
689 The following subsections describe basic locale categories. Beyond these,
690 some combination categories allow manipulation of more than one
691 basic category at a time. See L<"ENVIRONMENT"> for a discussion of these.
693 =head2 Category LC_COLLATE: Collation
695 In the scope of S<C<use locale>> (but not a
696 C<use locale ':not_characters'>), Perl looks to the C<LC_COLLATE>
697 environment variable to determine the application's notions on collation
698 (ordering) of characters. For example, "b" follows "a" in Latin
699 alphabets, but where do "E<aacute>" and "E<aring>" belong? And while
700 "color" follows "chocolate" in English, what about in traditional Spanish?
702 The following collations all make sense and you may meet any of them
710 Here is a code snippet to tell what "word"
711 characters are in the current locale, in that locale's order:
714 print +(sort grep /\w/, map { chr } 0..255), "\n";
716 Compare this with the characters that you see and their order if you
717 state explicitly that the locale should be ignored:
720 print +(sort grep /\w/, map { chr } 0..255), "\n";
722 This machine-native collation (which is what you get unless S<C<use
723 locale>> has appeared earlier in the same block) must be used for
724 sorting raw binary data, whereas the locale-dependent collation of the
725 first example is useful for natural text.
727 As noted in L<USING LOCALES>, C<cmp> compares according to the current
728 collation locale when C<use locale> is in effect, but falls back to a
729 char-by-char comparison for strings that the locale says are equal. You
730 can use C<POSIX::strcoll()> if you don't want this fall-back:
732 use POSIX qw(strcoll);
734 !strcoll("space and case ignored", "SpaceAndCaseIgnored");
736 C<$equal_in_locale> will be true if the collation locale specifies a
737 dictionary-like ordering that ignores space characters completely and
740 If you have a single string that you want to check for "equality in
741 locale" against several others, you might think you could gain a little
742 efficiency by using C<POSIX::strxfrm()> in conjunction with C<eq>:
744 use POSIX qw(strxfrm);
745 $xfrm_string = strxfrm("Mixed-case string");
746 print "locale collation ignores spaces\n"
747 if $xfrm_string eq strxfrm("Mixed-casestring");
748 print "locale collation ignores hyphens\n"
749 if $xfrm_string eq strxfrm("Mixedcase string");
750 print "locale collation ignores case\n"
751 if $xfrm_string eq strxfrm("mixed-case string");
753 C<strxfrm()> takes a string and maps it into a transformed string for use
754 in char-by-char comparisons against other transformed strings during
755 collation. "Under the hood", locale-affected Perl comparison operators
756 call C<strxfrm()> for both operands, then do a char-by-char
757 comparison of the transformed strings. By calling C<strxfrm()> explicitly
758 and using a non locale-affected comparison, the example attempts to save
759 a couple of transformations. But in fact, it doesn't save anything: Perl
760 magic (see L<perlguts/Magic Variables>) creates the transformed version of a
761 string the first time it's needed in a comparison, then keeps this version around
762 in case it's needed again. An example rewritten the easy way with
763 C<cmp> runs just about as fast. It also copes with null characters
764 embedded in strings; if you call C<strxfrm()> directly, it treats the first
765 null it finds as a terminator. don't expect the transformed strings
766 it produces to be portable across systems--or even from one revision
767 of your operating system to the next. In short, don't call C<strxfrm()>
768 directly: let Perl do it for you.
770 Note: C<use locale> isn't shown in some of these examples because it isn't
771 needed: C<strcoll()> and C<strxfrm()> are POSIX functions
772 which use the standard system-supplied C<libc> functions that
773 always obey the current C<LC_COLLATE> locale.
775 =head2 Category LC_CTYPE: Character Types
777 In the scope of S<C<use locale>> (but not a
778 C<use locale ':not_characters'>), Perl obeys the C<LC_CTYPE> locale
779 setting. This controls the application's notion of which characters are
780 alphabetic. This affects Perl's C<\w> regular expression metanotation,
781 which stands for alphanumeric characters--that is, alphabetic,
782 numeric, and including other special characters such as the underscore or
783 hyphen. (Consult L<perlre> for more information about
784 regular expressions.) Thanks to C<LC_CTYPE>, depending on your locale
785 setting, characters like "E<aelig>", "E<eth>", "E<szlig>", and
786 "E<oslash>" may be understood as C<\w> characters.
788 The C<LC_CTYPE> locale also provides the map used in transliterating
789 characters between lower and uppercase. This affects the case-mapping
790 functions--C<fc()>, C<lc()>, C<lcfirst()>, C<uc()>, and C<ucfirst()>; case-mapping
791 interpolation with C<\F>, C<\l>, C<\L>, C<\u>, or C<\U> in double-quoted
792 strings and C<s///> substitutions; and case-independent regular expression
793 pattern matching using the C<i> modifier.
795 Finally, C<LC_CTYPE> affects the POSIX character-class test
796 functions--C<POSIX::isalpha()>, C<POSIX::islower()>, and so on. For
797 example, if you move from the "C" locale to a 7-bit Scandinavian one,
798 you may find--possibly to your surprise--that "|" moves from the
799 C<POSIX::ispunct()> class to C<POSIX::isalpha()>.
800 Unfortunately, this creates big problems for regular expressions. "|" still
801 means alternation even though it matches C<\w>.
803 Note that there are quite a few things that are unaffected by the
804 current locale. All the escape sequences for particular characters,
805 C<\n> for example, always mean the platform's native one. This means,
806 for example, that C<\N> in regular expressions (every character
807 but new-line) works on the platform character set.
809 B<Note:> A broken or malicious C<LC_CTYPE> locale definition may result
810 in clearly ineligible characters being considered to be alphanumeric by
811 your application. For strict matching of (mundane) ASCII letters and
812 digits--for example, in command strings--locale-aware applications
813 should use C<\w> with the C</a> regular expression modifier. See L<"SECURITY">.
815 =head2 Category LC_NUMERIC: Numeric Formatting
817 After a proper C<POSIX::setlocale()> call, and within the scope of one
818 of the C<use locale> variants, Perl obeys the C<LC_NUMERIC>
819 locale information, which controls an application's idea of how numbers
820 should be formatted for human readability.
821 In most implementations the only effect is to
822 change the character used for the decimal point--perhaps from "." to ",".
823 The functions aren't aware of such niceties as thousands separation and
824 so on. (See L<The localeconv function> if you care about these things.)
826 use POSIX qw(strtod setlocale LC_NUMERIC);
829 setlocale LC_NUMERIC, "";
831 $n = 5/2; # Assign numeric 2.5 to $n
833 $a = " $n"; # Locale-dependent conversion to string
835 print "half five is $n\n"; # Locale-dependent output
837 printf "half five is %g\n", $n; # Locale-dependent output
839 print "DECIMAL POINT IS COMMA\n"
840 if $n == (strtod("2,5"))[0]; # Locale-dependent conversion
842 See also L<I18N::Langinfo> and C<RADIXCHAR>.
844 =head2 Category LC_MONETARY: Formatting of monetary amounts
846 The C standard defines the C<LC_MONETARY> category, but not a function
847 that is affected by its contents. (Those with experience of standards
848 committees will recognize that the working group decided to punt on the
849 issue.) Consequently, Perl essentially takes no notice of it. If you
850 really want to use C<LC_MONETARY>, you can query its contents--see
851 L<The localeconv function>--and use the information that it returns in your
852 application's own formatting of currency amounts. However, you may well
853 find that the information, voluminous and complex though it may be, still
854 does not quite meet your requirements: currency formatting is a hard nut
857 See also L<I18N::Langinfo> and C<CRNCYSTR>.
861 Output produced by C<POSIX::strftime()>, which builds a formatted
862 human-readable date/time string, is affected by the current C<LC_TIME>
863 locale. Thus, in a French locale, the output produced by the C<%B>
864 format element (full month name) for the first month of the year would
865 be "janvier". Here's how to get a list of long month names in the
868 use POSIX qw(strftime);
870 $long_month_name[$_] =
871 strftime("%B", 0, 0, 0, 1, $_, 96);
874 Note: C<use locale> isn't needed in this example: C<strftime()> is a POSIX
875 function which uses the standard system-supplied C<libc> function that
876 always obeys the current C<LC_TIME> locale.
878 See also L<I18N::Langinfo> and C<ABDAY_1>..C<ABDAY_7>, C<DAY_1>..C<DAY_7>,
879 C<ABMON_1>..C<ABMON_12>, and C<ABMON_1>..C<ABMON_12>.
881 =head2 Other categories
883 The remaining locale categories are not currently used by Perl itself.
884 But again note that things Perl interacts with may use these, including
885 extensions outside the standard Perl distribution, and by the
886 operating system and its utilities. Note especially that the string
887 value of C<$!> and the error messages given by external utilities may
888 be changed by C<LC_MESSAGES>. If you want to have portable error
889 codes, use C<%!>. See L<Errno>.
893 Although the main discussion of Perl security issues can be found in
894 L<perlsec>, a discussion of Perl's locale handling would be incomplete
895 if it did not draw your attention to locale-dependent security issues.
896 Locales--particularly on systems that allow unprivileged users to
897 build their own locales--are untrustworthy. A malicious (or just plain
898 broken) locale can make a locale-aware application give unexpected
899 results. Here are a few possibilities:
905 Regular expression checks for safe file names or mail addresses using
906 C<\w> may be spoofed by an C<LC_CTYPE> locale that claims that
907 characters such as "E<gt>" and "|" are alphanumeric.
911 String interpolation with case-mapping, as in, say, C<$dest =
912 "C:\U$name.$ext">, may produce dangerous results if a bogus LC_CTYPE
913 case-mapping table is in effect.
917 A sneaky C<LC_COLLATE> locale could result in the names of students with
918 "D" grades appearing ahead of those with "A"s.
922 An application that takes the trouble to use information in
923 C<LC_MONETARY> may format debits as if they were credits and vice versa
924 if that locale has been subverted. Or it might make payments in US
925 dollars instead of Hong Kong dollars.
929 The date and day names in dates formatted by C<strftime()> could be
930 manipulated to advantage by a malicious user able to subvert the
931 C<LC_DATE> locale. ("Look--it says I wasn't in the building on
936 Such dangers are not peculiar to the locale system: any aspect of an
937 application's environment which may be modified maliciously presents
938 similar challenges. Similarly, they are not specific to Perl: any
939 programming language that allows you to write programs that take
940 account of their environment exposes you to these issues.
942 Perl cannot protect you from all possibilities shown in the
943 examples--there is no substitute for your own vigilance--but, when
944 C<use locale> is in effect, Perl uses the tainting mechanism (see
945 L<perlsec>) to mark string results that become locale-dependent, and
946 which may be untrustworthy in consequence. Here is a summary of the
947 tainting behavior of operators and functions that may be affected by
954 B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
956 Scalar true/false (or less/equal/greater) result is never tainted.
960 B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u>, C<\U>, or C<\F>)
962 Result string containing interpolated material is tainted if
963 C<use locale> (but not S<C<use locale ':not_characters'>>) is in effect.
967 B<Matching operator> (C<m//>):
969 Scalar true/false result never tainted.
971 All subpatterns, either delivered as a list-context result or as C<$1>
972 I<etc>., are tainted if C<use locale> (but not
973 S<C<use locale ':not_characters'>>) is in effect, and the subpattern
974 regular expression is matched case-insensitively (C</i>) or contains a
975 locale-dependent construct. These constructs include C<\w>
976 (to match an alphanumeric character), C<\W> (non-alphanumeric
977 character), C<\s> (whitespace character), C<\S> (non whitespace
978 character), and the POSIX character classes, such as C<[:alpha:]> (see
979 L<perlrecharclass/POSIX Character Classes>).
980 The matched-pattern variables, C<$&>, C<$`> (pre-match), C<$'>
981 (post-match), and C<$+> (last match) also are tainted.
982 (Note that currently there are some bugs where not everything that
983 should be tainted gets tainted in all circumstances.)
987 B<Substitution operator> (C<s///>):
989 Has the same behavior as the match operator. Also, the left
990 operand of C<=~> becomes tainted when C<use locale>
991 (but not S<C<use locale ':not_characters'>>) is in effect if modified as
992 a result of a substitution based on a regular
993 expression match involving any of the things mentioned in the previous
994 item, or of case-mapping, such as C<\l>, C<\L>,C<\u>, C<\U>, or C<\F>.
998 B<Output formatting functions> (C<printf()> and C<write()>):
1000 Results are never tainted because otherwise even output from print,
1001 for example C<print(1/7)>, should be tainted if C<use locale> is in
1006 B<Case-mapping functions> (C<lc()>, C<lcfirst()>, C<uc()>, C<ucfirst()>):
1008 Results are tainted if C<use locale> (but not
1009 S<C<use locale ':not_characters'>>) is in effect.
1013 B<POSIX locale-dependent functions> (C<localeconv()>, C<strcoll()>,
1014 C<strftime()>, C<strxfrm()>):
1016 Results are never tainted.
1020 B<POSIX character class tests> (C<POSIX::isalnum()>,
1021 C<POSIX::isalpha()>, C<POSIX::isdigit()>, C<POSIX::isgraph()>,
1022 C<POSIX::islower()>, C<POSIX::isprint()>, C<POSIX::ispunct()>,
1023 C<POSIX::isspace()>, C<POSIX::isupper()>, C<POSIX::isxdigit()>):
1025 True/false results are never tainted.
1029 Three examples illustrate locale-dependent tainting.
1030 The first program, which ignores its locale, won't run: a value taken
1031 directly from the command line may not be used to name an output file
1032 when taint checks are enabled.
1034 #/usr/local/bin/perl -T
1035 # Run with taint checking
1037 # Command line sanity check omitted...
1038 $tainted_output_file = shift;
1040 open(F, ">$tainted_output_file")
1041 or warn "Open of $tainted_output_file failed: $!\n";
1043 The program can be made to run by "laundering" the tainted value through
1044 a regular expression: the second example--which still ignores locale
1045 information--runs, creating the file named on its command line
1048 #/usr/local/bin/perl -T
1050 $tainted_output_file = shift;
1051 $tainted_output_file =~ m%[\w/]+%;
1052 $untainted_output_file = $&;
1054 open(F, ">$untainted_output_file")
1055 or warn "Open of $untainted_output_file failed: $!\n";
1057 Compare this with a similar but locale-aware program:
1059 #/usr/local/bin/perl -T
1061 $tainted_output_file = shift;
1063 $tainted_output_file =~ m%[\w/]+%;
1064 $localized_output_file = $&;
1066 open(F, ">$localized_output_file")
1067 or warn "Open of $localized_output_file failed: $!\n";
1069 This third program fails to run because C<$&> is tainted: it is the result
1070 of a match involving C<\w> while C<use locale> is in effect.
1078 A string that can suppress Perl's warning about failed locale settings
1079 at startup. Failure can occur if the locale support in the operating
1080 system is lacking (broken) in some way--or if you mistyped the name of
1081 a locale when you set up your environment. If this environment
1082 variable is absent, or has a value that does not evaluate to integer
1083 zero--that is, "0" or ""-- Perl will complain about locale setting
1086 B<NOTE>: PERL_BADLANG only gives you a way to hide the warning message.
1087 The message tells about some problem in your system's locale support,
1088 and you should investigate what the problem is.
1092 The following environment variables are not specific to Perl: They are
1093 part of the standardized (ISO C, XPG4, POSIX 1.c) C<setlocale()> method
1094 for controlling an application's opinion on data.
1100 C<LC_ALL> is the "override-all" locale environment variable. If
1101 set, it overrides all the rest of the locale environment variables.
1105 B<NOTE>: C<LANGUAGE> is a GNU extension, it affects you only if you
1106 are using the GNU libc. This is the case if you are using e.g. Linux.
1107 If you are using "commercial" Unixes you are most probably I<not>
1108 using GNU libc and you can ignore C<LANGUAGE>.
1110 However, in the case you are using C<LANGUAGE>: it affects the
1111 language of informational, warning, and error messages output by
1112 commands (in other words, it's like C<LC_MESSAGES>) but it has higher
1113 priority than C<LC_ALL>. Moreover, it's not a single value but
1114 instead a "path" (":"-separated list) of I<languages> (not locales).
1115 See the GNU C<gettext> library documentation for more information.
1119 In the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type
1120 locale. In the absence of both C<LC_ALL> and C<LC_CTYPE>, C<LANG>
1121 chooses the character type locale.
1125 In the absence of C<LC_ALL>, C<LC_COLLATE> chooses the collation
1126 (sorting) locale. In the absence of both C<LC_ALL> and C<LC_COLLATE>,
1127 C<LANG> chooses the collation locale.
1131 In the absence of C<LC_ALL>, C<LC_MONETARY> chooses the monetary
1132 formatting locale. In the absence of both C<LC_ALL> and C<LC_MONETARY>,
1133 C<LANG> chooses the monetary formatting locale.
1137 In the absence of C<LC_ALL>, C<LC_NUMERIC> chooses the numeric format
1138 locale. In the absence of both C<LC_ALL> and C<LC_NUMERIC>, C<LANG>
1139 chooses the numeric format.
1143 In the absence of C<LC_ALL>, C<LC_TIME> chooses the date and time
1144 formatting locale. In the absence of both C<LC_ALL> and C<LC_TIME>,
1145 C<LANG> chooses the date and time formatting locale.
1149 C<LANG> is the "catch-all" locale environment variable. If it is set, it
1150 is used as the last resort after the overall C<LC_ALL> and the
1151 category-specific C<LC_...>.
1157 The LC_NUMERIC controls the numeric output:
1160 use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
1161 setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
1162 printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
1164 and also how strings are parsed by C<POSIX::strtod()> as numbers:
1167 use POSIX qw(locale_h strtod);
1168 setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
1169 my $x = strtod("2,34") + 5;
1170 print $x, "\n"; # Probably shows 7,34.
1174 =head2 String C<eval> and C<LC_NUMERIC>
1176 A string L<eval|perlfunc/eval EXPR> parses its expression as standard
1177 Perl. It is therefore expecting the decimal point to be a dot. If
1178 C<LC_NUMERIC> is set to have this be a comma instead, the parsing will
1179 be confused, perhaps silently.
1182 use POSIX qw(locale_h);
1183 setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
1185 print eval "$a + 1.5";
1188 prints C<13,5>. This is because in that locale, the comma is the
1189 decimal point character. The C<eval> thus expands to:
1193 and the result is not what you likely expected. No warnings are
1194 generated. If you do string C<eval>'s within the scope of
1195 S<C<use locale>>, you should instead change the C<eval> line to do
1198 print eval "no locale; $a + 1.5";
1202 =head2 Backward compatibility
1204 Versions of Perl prior to 5.004 B<mostly> ignored locale information,
1205 generally behaving as if something similar to the C<"C"> locale were
1206 always in force, even if the program environment suggested otherwise
1207 (see L<The setlocale function>). By default, Perl still behaves this
1208 way for backward compatibility. If you want a Perl application to pay
1209 attention to locale information, you B<must> use the S<C<use locale>>
1210 pragma (see L<The use locale pragma>) or, in the unlikely event
1211 that you want to do so for just pattern matching, the
1212 C</l> regular expression modifier (see L<perlre/Character set
1213 modifiers>) to instruct it to do so.
1215 Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE>
1216 information if available; that is, C<\w> did understand what
1217 were the letters according to the locale environment variables.
1218 The problem was that the user had no control over the feature:
1219 if the C library supported locales, Perl used them.
1221 =head2 I18N:Collate obsolete
1223 In versions of Perl prior to 5.004, per-locale collation was possible
1224 using the C<I18N::Collate> library module. This module is now mildly
1225 obsolete and should be avoided in new applications. The C<LC_COLLATE>
1226 functionality is now integrated into the Perl core language: One can
1227 use locale-specific scalar data completely normally with C<use locale>,
1228 so there is no longer any need to juggle with the scalar references of
1231 =head2 Sort speed and memory use impacts
1233 Comparing and sorting by locale is usually slower than the default
1234 sorting; slow-downs of two to four times have been observed. It will
1235 also consume more memory: once a Perl scalar variable has participated
1236 in any string comparison or sorting operation obeying the locale
1237 collation rules, it will take 3-15 times more memory than before. (The
1238 exact multiplier depends on the string's contents, the operating system
1239 and the locale.) These downsides are dictated more by the operating
1240 system's implementation of the locale system than by Perl.
1242 =head2 Freely available locale definitions
1244 The Unicode CLDR project extracts the POSIX portion of many of its
1245 locales, available at
1247 http://unicode.org/Public/cldr/latest/
1249 There is a large collection of locale definitions at:
1251 http://std.dkuug.dk/i18n/WG15-collection/locales/
1253 You should be aware that it is
1254 unsupported, and is not claimed to be fit for any purpose. If your
1255 system allows installation of arbitrary locales, you may find the
1256 definitions useful as they are, or as a basis for the development of
1259 =head2 I18n and l10n
1261 "Internationalization" is often abbreviated as B<i18n> because its first
1262 and last letters are separated by eighteen others. (You may guess why
1263 the internalin ... internaliti ... i18n tends to get abbreviated.) In
1264 the same way, "localization" is often abbreviated to B<l10n>.
1266 =head2 An imperfect standard
1268 Internationalization, as defined in the C and POSIX standards, can be
1269 criticized as incomplete, ungainly, and having too large a granularity.
1270 (Locales apply to a whole process, when it would arguably be more useful
1271 to have them apply to a single thread, window group, or whatever.) They
1272 also have a tendency, like standards groups, to divide the world into
1273 nations, when we all know that the world can equally well be divided
1274 into bankers, bikers, gamers, and so on.
1276 =head1 Unicode and UTF-8
1278 The support of Unicode is new starting from Perl version v5.6, and more fully
1279 implemented in versions v5.8 and later. See L<perluniintro>. It is
1280 strongly recommended that when combining Unicode and locale (starting in
1283 use locale ':not_characters';
1285 When this form of the pragma is used, only the non-character portions of
1286 locales are used by Perl, for example C<LC_NUMERIC>. Perl assumes that
1287 you have translated all the characters it is to operate on into Unicode
1288 (actually the platform's native character set (ASCII or EBCDIC) plus
1289 Unicode). For data in files, this can conveniently be done by also
1294 This pragma arranges for all inputs from files to be translated into
1295 Unicode from the current locale as specified in the environment (see
1296 L</ENVIRONMENT>), and all outputs to files to be translated back
1297 into the locale. (See L<open>). On a per-filehandle basis, you can
1298 instead use the L<PerlIO::locale> module, or the L<Encode::Locale>
1299 module, both available from CPAN. The latter module also has methods to
1300 ease the handling of C<ARGV> and environment variables, and can be used
1301 on individual strings. Also, if you know that all your locales will be
1302 UTF-8, as many are these days, you can use the L<B<-C>|perlrun/-C>
1303 command line switch.
1305 This form of the pragma allows essentially seamless handling of locales
1306 with Unicode. The collation order will be Unicode's. It is strongly
1307 recommended that when you need to order and sort strings that you use
1308 the standard module L<Unicode::Collate> which gives much better results
1309 in many instances than you can get with the old-style locale handling.
1311 For pre-v5.16 Perls, or if you use the locale pragma without the
1312 C<:not_characters> parameter, Perl tries to work with both Unicode and
1313 locales--but there are problems.
1315 Perl does not handle multi-byte locales in this case, such as have been
1317 Asian languages, such as Big5 or Shift JIS. However, the increasingly
1318 common multi-byte UTF-8 locales, if properly implemented, may work
1319 reasonably well (depending on your C library implementation) in this
1320 form of the locale pragma, simply because both
1321 they and Perl store characters that take up multiple bytes the same way.
1322 However, some, if not most, C library implementations may not process
1323 the characters in the upper half of the Latin-1 range (128 - 255)
1324 properly under LC_CTYPE. To see if a character is a particular type
1325 under a locale, Perl uses the functions like C<isalnum()>. Your C
1326 library may not work for UTF-8 locales with those functions, instead
1327 only working under the newer wide library functions like C<iswalnum()>.
1329 Perl generally takes the tack to use locale rules on code points that can fit
1330 in a single byte, and Unicode rules for those that can't (though this
1331 isn't uniformly applied, see the note at the end of this section). This
1332 prevents many problems in locales that aren't UTF-8. Suppose the locale
1333 is ISO8859-7, Greek. The character at 0xD7 there is a capital Chi. But
1334 in the ISO8859-1 locale, Latin1, it is a multiplication sign. The POSIX
1335 regular expression character class C<[[:alpha:]]> will magically match
1336 0xD7 in the Greek locale but not in the Latin one.
1338 However, there are places where this breaks down. Certain Perl constructs are
1339 for Unicode only, such as C<\p{Alpha}>. They assume that 0xD7 always has its
1340 Unicode meaning (or the equivalent on EBCDIC platforms). Since Latin1 is a
1341 subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and
1342 Unicode, C<\p{Alpha}> will never match it, regardless of locale. A similar
1343 issue occurs with C<\N{...}>. It is therefore a bad idea to use C<\p{}> or
1344 C<\N{}> under plain C<use locale>--I<unless> you can guarantee that the
1345 locale will be a ISO8859-1. Use POSIX character classes instead.
1347 Another problem with this approach is that operations that cross the
1348 single byte/multiple byte boundary are not well-defined, and so are
1349 disallowed. (This boundary is between the codepoints at 255/256.).
1350 For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
1351 should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF). But in the
1352 Greek locale, for example, there is no character at 0xFF, and Perl
1353 has no way of knowing what the character at 0xFF is really supposed to
1354 represent. Thus it disallows the operation. In this mode, the
1355 lowercase of U+0178 is itself.
1357 The same problems ensue if you enable automatic UTF-8-ification of your
1358 standard file handles, default C<open()> layer, and C<@ARGV> on non-ISO8859-1,
1359 non-UTF-8 locales (by using either the B<-C> command line switch or the
1360 C<PERL_UNICODE> environment variable; see L<perlrun>).
1361 Things are read in as UTF-8, which would normally imply a Unicode
1362 interpretation, but the presence of a locale causes them to be interpreted
1363 in that locale instead. For example, a 0xD7 code point in the Unicode
1364 input, which should mean the multiplication sign, won't be interpreted by
1365 Perl that way under the Greek locale. This is not a problem
1366 I<provided> you make certain that all locales will always and only be either
1367 an ISO8859-1, or, if you don't have a deficient C library, a UTF-8 locale.
1369 Still another problem is that this approach can lead to two code
1370 points meaning the same character. Thus in a Greek locale, both U+03A7
1371 and U+00D7 are GREEK CAPITAL LETTER CHI.
1373 Vendor locales are notoriously buggy, and it is difficult for Perl to test
1374 its locale-handling code because this interacts with code that Perl has no
1375 control over; therefore the locale-handling code in Perl may be buggy as
1376 well. (However, the Unicode-supplied locales should be better, and
1377 there is a feed back mechanism to correct any problems. See
1378 L</Freely available locale definitions>.)
1380 If you have Perl v5.16, the problems mentioned above go away if you use
1381 the C<:not_characters> parameter to the locale pragma (except for vendor
1382 bugs in the non-character portions). If you don't have v5.16, and you
1383 I<do> have locales that work, using them may be worthwhile for certain
1384 specific purposes, as long as you keep in mind the gotchas already
1385 mentioned. For example, if the collation for your locales works, it
1386 runs faster under locales than under L<Unicode::Collate>; and you gain
1387 access to such things as the local currency symbol and the names of the
1388 months and days of the week. (But to hammer home the point, in v5.16,
1389 you get this access without the downsides of locales by using the
1390 C<:not_characters> form of the pragma.)
1392 Note: The policy of using locale rules for code points that can fit in a
1393 byte, and Unicode rules for those that can't is not uniformly applied.
1394 Pre-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
1395 consistently to regular expression matching except for bracketed
1396 character classes; in v5.14 it was extended to all regex matches; and in
1397 v5.16 to the casing operations such as C<"\L"> and C<uc()>. For
1398 collation, in all releases, the system's C<strxfrm()> function is called,
1399 and whatever it does is what you get.
1403 =head2 Broken systems
1405 In certain systems, the operating system's locale support
1406 is broken and cannot be fixed or used by Perl. Such deficiencies can
1407 and will result in mysterious hangs and/or Perl core dumps when
1408 C<use locale> is in effect. When confronted with such a system,
1409 please report in excruciating detail to <F<perlbug@perl.org>>, and
1410 also contact your vendor: bug fixes may exist for these problems
1411 in your operating system. Sometimes such bug fixes are called an
1412 operating system upgrade. If you have the source for Perl, include in
1413 the perlbug email the output of the test described above in L</Testing
1414 for broken locales>.
1418 L<I18N::Langinfo>, L<perluniintro>, L<perlunicode>, L<open>,
1419 L<POSIX/isalnum>, L<POSIX/isalpha>,
1420 L<POSIX/isdigit>, L<POSIX/isgraph>, L<POSIX/islower>,
1421 L<POSIX/isprint>, L<POSIX/ispunct>, L<POSIX/isspace>,
1422 L<POSIX/isupper>, L<POSIX/isxdigit>, L<POSIX/localeconv>,
1423 L<POSIX/setlocale>, L<POSIX/strcoll>, L<POSIX/strftime>,
1424 L<POSIX/strtod>, L<POSIX/strxfrm>.
1426 For special considerations when Perl is embedded in a C program,
1427 see L<perlembed/Using embedded Perl with POSIX locales>.
1431 Jarkko Hietaniemi's original F<perli18n.pod> heavily hacked by Dominic
1432 Dunlop, assisted by the perl5-porters. Prose worked over a bit by
1433 Tom Christiansen, and updated by Perl 5 porters.