This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
17796cacb01e272578f3884ddfe720e4f5c853c3
[perl5.git] / pod / perllocale.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 perllocale - Perl locale handling (internationalization and localization)
6
7 =head1 DESCRIPTION
8
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
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.
28
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).
34
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/>.)
44
45 =head1 WHAT IS A LOCALE
46
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
50 note here):
51
52 =over
53
54 =item Category LC_NUMERIC: Numeric formatting
55
56 This indicates how numbers should be formatted for human readability,
57 for example the character used as the decimal point.
58
59 =item Category LC_MONETARY: Formatting of monetary amounts
60
61 =for comment
62 The nbsp below makes this look better
63
64 E<160>
65
66 =item Category LC_TIME: Date/Time formatting
67
68 =for comment
69 The nbsp below makes this look better
70
71 E<160>
72
73 =item Category LC_MESSAGES: Error and other messages
74
75 This is used by Perl itself only for accessing operating system error
76 messages via L<$!|perlvar/$ERRNO>.
77
78 =item Category LC_COLLATE: Collation
79
80 This indicates the ordering of letters for comparison and sorting.
81 In Latin alphabets, for example, "b", generally follows "a".
82
83 =item Category LC_CTYPE: Character Types
84
85 This indicates, for example if a character is an uppercase letter.
86
87 =item Other categories
88
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.
93
94 =back
95
96 More details on the categories used by Perl are given below in L</LOCALE
97 CATEGORIES>.
98
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.
102
103 =head1 PREPARING TO USE LOCALES
104
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:
109
110 =over 4
111
112 =item *
113
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
116 its C library.
117
118 =item *
119
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.
130
131 =item *
132
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
135 C<define>.
136
137 =back
138
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:
143
144 =over 4
145
146 =item 1
147
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
151
152 =item 2
153
154 B<The application must set its own locale> using the method described in
155 L<The setlocale function>.
156
157 =back
158
159 =head1 USING LOCALES
160
161 =head2 The use locale pragma
162
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:
166
167     use locale ':not_characters';
168
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>.
178
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 undefined.  It
187 is likely, but not necessarily, the "C" locale.
188
189 The operations that are affected by locale are:
190
191 =over 4
192
193 =item B<Not within the scope of any C<use locale> variant>
194
195 Only operations originating outside Perl should be affected.
196
197 The variable L<$!|perlvar/$ERRNO> (and its synonyms C<$ERRNO> and
198 C<$OS_ERROR>) when used as strings always are in terms of the current
199 locale.
200
201 The current locale is also used when going outside of Perl with
202 operations like L<system()|perlfunc/system LIST> or
203 L<qxE<sol>E<sol>|perlop/qxE<sol>STRINGE<sol>>, if those operations are
204 locale-sensitive.
205
206 Also Perl gives access to various C library functions through the
207 L<POSIX> module.  Some of those functions are always affected by the
208 current locale.  For example, C<POSIX::strftime()> uses C<LC_TIME>;
209 C<POSIX::strtod()> uses C<LC_NUMERIC>; C<POSIX::strcoll()> and
210 C<POSIX::strxfrm()> use C<LC_COLLATE>; and character classification
211 functions like C<POSIX::isalnum()> use C<LC_CTYPE>.  All such functions
212 will behave according to the current underlying locale, even if that
213 isn't exposed to Perl space.
214
215 And, certain Perl operations that are set-up within the scope of a
216 C<use locale> variant retain that effect even outside the scope.
217 These include:
218
219 =over 4
220
221 =item *
222
223 The output format of a L<write()|perlfunc/write> is determined by an
224 earlier format declaration (L<perlfunc/format>), so whether or not the
225 output is affected by locale is determined by if the C<format()> is
226 within the scope of a C<use locale> variant, not whether the C<write()>
227 is.
228
229 =item *
230
231 Regular expression patterns can be compiled using
232 L<qrE<sol>E<sol>|perlop/qrE<sol>STRINGE<sol>msixpodual> with actual
233 matching deferred to later.  Again, it is whether or not the compilation
234 was done within the scope of C<use locale> that determines the match
235 behavior, not if the matches are done within such a scope or not.
236
237 =back
238
239 =item B<Under C<use locale ':not_characters';>>
240
241 =over 4
242
243 =item *
244
245 All the non-Perl operations.
246
247 =item *
248
249 B<Format declarations> (L<perlfunc/format>) and hence any subsequent
250 C<write()>s use C<LC_NUMERIC>.
251
252 =item *
253
254 B<stringification and output> use C<LC_NUMERIC>.
255 These include the results of
256 C<print()>,
257 C<printf()>,
258 C<say()>,
259 and
260 C<sprintf()>.
261
262 =back
263
264 =for comment
265 The nbsp below makes this look better
266
267 E<160>
268
269 =item B<Under just plain C<use locale;>>
270
271 =over 4
272
273 =item *
274
275 All the above operations
276
277 =item *
278
279 B<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>) use
280 C<LC_COLLATE>.  C<sort()> is also affected if used without an
281 explicit comparison function, because it uses C<cmp> by default.
282
283 B<Note:> C<eq> and C<ne> are unaffected by locale: they always
284 perform a char-by-char comparison of their scalar operands.  What's
285 more, if C<cmp> finds that its operands are equal according to the
286 collation sequence specified by the current locale, it goes on to
287 perform a char-by-char comparison, and only returns I<0> (equal) if the
288 operands are char-for-char identical.  If you really want to know whether
289 two strings--which C<eq> and C<cmp> may consider different--are equal
290 as far as collation in the locale is concerned, see the discussion in
291 L<Category LC_COLLATE: Collation>.
292
293 =item *
294
295 B<Regular expressions and case-modification functions> (C<uc()>, C<lc()>,
296 C<ucfirst()>, and C<lcfirst()>) use C<LC_CTYPE>
297
298 =back
299
300 =back
301
302 The default behavior is restored with the S<C<no locale>> pragma, or
303 upon reaching the end of the block enclosing C<use locale>.
304 Note that C<use locale> and C<use locale ':not_characters'> may be
305 nested, and that what is in effect within an inner scope will revert to
306 the outer scope's rules at the end of the inner scope.
307
308 The string result of any operation that uses locale
309 information is tainted, as it is possible for a locale to be
310 untrustworthy.  See L<"SECURITY">.
311
312 =head2 The setlocale function
313
314 You can switch locales as often as you wish at run time with the
315 C<POSIX::setlocale()> function:
316
317         # Import locale-handling tool set from POSIX module.
318         # This example uses: setlocale -- the function call
319         #                    LC_CTYPE -- explained below
320         # (Showing the testing for success/failure of operations is
321         # omitted in these examples to avoid distracting from the main
322         # point)
323         use POSIX qw(locale_h);
324
325         # query and save the old locale
326         $old_locale = setlocale(LC_CTYPE);
327
328         setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
329         # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
330
331         setlocale(LC_CTYPE, "");
332         # LC_CTYPE now reset to default defined by LC_ALL/LC_CTYPE/LANG
333         # environment variables.  See below for documentation.
334
335         # restore the old locale
336         setlocale(LC_CTYPE, $old_locale);
337
338 The first argument of C<setlocale()> gives the B<category>, the second the
339 B<locale>.  The category tells in what aspect of data processing you
340 want to apply locale-specific rules.  Category names are discussed in
341 L</LOCALE CATEGORIES> and L</"ENVIRONMENT">.  The locale is the name of a
342 collection of customization information corresponding to a particular
343 combination of language, country or territory, and codeset.  Read on for
344 hints on the naming of locales: not all systems name locales as in the
345 example.
346
347 If no second argument is provided and the category is something other
348 than LC_ALL, the function returns a string naming the current locale
349 for the category.  You can use this value as the second argument in a
350 subsequent call to C<setlocale()>.
351
352 If no second argument is provided and the category is LC_ALL, the
353 result is implementation-dependent.  It may be a string of
354 concatenated locale names (separator also implementation-dependent)
355 or a single locale name.  Please consult your L<setlocale(3)> man page for
356 details.
357
358 If a second argument is given and it corresponds to a valid locale,
359 the locale for the category is set to that value, and the function
360 returns the now-current locale value.  You can then use this in yet
361 another call to C<setlocale()>.  (In some implementations, the return
362 value may sometimes differ from the value you gave as the second
363 argument--think of it as an alias for the value you gave.)
364
365 As the example shows, if the second argument is an empty string, the
366 category's locale is returned to the default specified by the
367 corresponding environment variables.  Generally, this results in a
368 return to the default that was in force when Perl started up: changes
369 to the environment made by the application after startup may or may not
370 be noticed, depending on your system's C library.
371
372 If the second argument does not correspond to a valid locale, the locale
373 for the category is not changed, and the function returns C<undef>.
374
375 Note that Perl ignores the current C<LC_CTYPE> and C<LC_COLLATE> locales
376 within the scope of a C<use locale ':not_characters'>.
377
378 If C<set_locale()> fails for some reason (for example an attempt to set
379 to a locale unknown to the system), C<undef> is returned.
380
381 For further information about the categories, consult L<setlocale(3)>.
382
383 =head2 Finding locales
384
385 For locales available in your system, consult also L<setlocale(3)> to
386 see whether it leads to the list of available locales (search for the
387 I<SEE ALSO> section).  If that fails, try the following command lines:
388
389         locale -a
390
391         nlsinfo
392
393         ls /usr/lib/nls/loc
394
395         ls /usr/lib/locale
396
397         ls /usr/lib/nls
398
399         ls /usr/share/locale
400
401 and see whether they list something resembling these
402
403         en_US.ISO8859-1     de_DE.ISO8859-1     ru_RU.ISO8859-5
404         en_US.iso88591      de_DE.iso88591      ru_RU.iso88595
405         en_US               de_DE               ru_RU
406         en                  de                  ru
407         english             german              russian
408         english.iso88591    german.iso88591     russian.iso88595
409         english.roman8                          russian.koi8r
410
411 Sadly, even though the calling interface for C<setlocale()> has been
412 standardized, names of locales and the directories where the
413 configuration resides have not been.  The basic form of the name is
414 I<language_territory>B<.>I<codeset>, but the latter parts after
415 I<language> are not always present.  The I<language> and I<country>
416 are usually from the standards B<ISO 3166> and B<ISO 639>, the
417 two-letter abbreviations for the countries and the languages of the
418 world, respectively.  The I<codeset> part often mentions some B<ISO
419 8859> character set, the Latin codesets.  For example, C<ISO 8859-1>
420 is the so-called "Western European codeset" that can be used to encode
421 most Western European languages adequately.  Again, there are several
422 ways to write even the name of that one standard.  Lamentably.
423
424 Two special locales are worth particular mention: "C" and "POSIX".
425 Currently these are effectively the same locale: the difference is
426 mainly that the first one is defined by the C standard, the second by
427 the POSIX standard.  They define the B<default locale> in which
428 every program starts in the absence of locale information in its
429 environment.  (The I<default> default locale, if you will.)  Its language
430 is (American) English and its character codeset ASCII or, rarely, a
431 superset thereof (such as the "DEC Multinational Character Set
432 (DEC-MCS)").  B<Warning>. The C locale delivered by some vendors
433 may not actually exactly match what the C standard calls for.  So
434 beware.
435
436 B<NOTE>: Not all systems have the "POSIX" locale (not all systems are
437 POSIX-conformant), so use "C" when you need explicitly to specify this
438 default locale.
439
440 =head2 LOCALE PROBLEMS
441
442 You may encounter the following warning message at Perl startup:
443
444         perl: warning: Setting locale failed.
445         perl: warning: Please check that your locale settings:
446                 LC_ALL = "En_US",
447                 LANG = (unset)
448             are supported and installed on your system.
449         perl: warning: Falling back to the standard locale ("C").
450
451 This means that your locale settings had LC_ALL set to "En_US" and
452 LANG exists but has no value.  Perl tried to believe you but could not.
453 Instead, Perl gave up and fell back to the "C" locale, the default locale
454 that is supposed to work no matter what.  This usually means your locale
455 settings were wrong, they mention locales your system has never heard
456 of, or the locale installation in your system has problems (for example,
457 some system files are broken or missing).  There are quick and temporary
458 fixes to these problems, as well as more thorough and lasting fixes.
459
460 =head2 Temporarily fixing locale problems
461
462 The two quickest fixes are either to render Perl silent about any
463 locale inconsistencies or to run Perl under the default locale "C".
464
465 Perl's moaning about locale problems can be silenced by setting the
466 environment variable PERL_BADLANG to a zero value, for example "0".
467 This method really just sweeps the problem under the carpet: you tell
468 Perl to shut up even when Perl sees that something is wrong.  Do not
469 be surprised if later something locale-dependent misbehaves.
470
471 Perl can be run under the "C" locale by setting the environment
472 variable LC_ALL to "C".  This method is perhaps a bit more civilized
473 than the PERL_BADLANG approach, but setting LC_ALL (or
474 other locale variables) may affect other programs as well, not just
475 Perl.  In particular, external programs run from within Perl will see
476 these changes.  If you make the new settings permanent (read on), all
477 programs you run see the changes.  See L<"ENVIRONMENT"> for
478 the full list of relevant environment variables and L<USING LOCALES>
479 for their effects in Perl.  Effects in other programs are
480 easily deducible.  For example, the variable LC_COLLATE may well affect
481 your B<sort> program (or whatever the program that arranges "records"
482 alphabetically in your system is called).
483
484 You can test out changing these variables temporarily, and if the
485 new settings seem to help, put those settings into your shell startup
486 files.  Consult your local documentation for the exact details.  For in
487 Bourne-like shells (B<sh>, B<ksh>, B<bash>, B<zsh>):
488
489         LC_ALL=en_US.ISO8859-1
490         export LC_ALL
491
492 This assumes that we saw the locale "en_US.ISO8859-1" using the commands
493 discussed above.  We decided to try that instead of the above faulty
494 locale "En_US"--and in Cshish shells (B<csh>, B<tcsh>)
495
496         setenv LC_ALL en_US.ISO8859-1
497
498 or if you have the "env" application you can do in any shell
499
500         env LC_ALL=en_US.ISO8859-1 perl ...
501
502 If you do not know what shell you have, consult your local
503 helpdesk or the equivalent.
504
505 =head2 Permanently fixing locale problems
506
507 The slower but superior fixes are when you may be able to yourself
508 fix the misconfiguration of your own environment variables.  The
509 mis(sing)configuration of the whole system's locales usually requires
510 the help of your friendly system administrator.
511
512 First, see earlier in this document about L<Finding locales>.  That tells
513 how to find which locales are really supported--and more importantly,
514 installed--on your system.  In our example error message, environment
515 variables affecting the locale are listed in the order of decreasing
516 importance (and unset variables do not matter).  Therefore, having
517 LC_ALL set to "En_US" must have been the bad choice, as shown by the
518 error message.  First try fixing locale settings listed first.
519
520 Second, if using the listed commands you see something B<exactly>
521 (prefix matches do not count and case usually counts) like "En_US"
522 without the quotes, then you should be okay because you are using a
523 locale name that should be installed and available in your system.
524 In this case, see L<Permanently fixing your system's locale configuration>.
525
526 =head2 Permanently fixing your system's locale configuration
527
528 This is when you see something like:
529
530         perl: warning: Please check that your locale settings:
531                 LC_ALL = "En_US",
532                 LANG = (unset)
533             are supported and installed on your system.
534
535 but then cannot see that "En_US" listed by the above-mentioned
536 commands.  You may see things like "en_US.ISO8859-1", but that isn't
537 the same.  In this case, try running under a locale
538 that you can list and which somehow matches what you tried.  The
539 rules for matching locale names are a bit vague because
540 standardization is weak in this area.  See again the
541 L<Finding locales> about general rules.
542
543 =head2 Fixing system locale configuration
544
545 Contact a system administrator (preferably your own) and report the exact
546 error message you get, and ask them to read this same documentation you
547 are now reading.  They should be able to check whether there is something
548 wrong with the locale configuration of the system.  The L<Finding locales>
549 section is unfortunately a bit vague about the exact commands and places
550 because these things are not that standardized.
551
552 =head2 The localeconv function
553
554 The C<POSIX::localeconv()> function allows you to get particulars of the
555 locale-dependent numeric formatting information specified by the current
556 C<LC_NUMERIC> and C<LC_MONETARY> locales.  (If you just want the name of
557 the current locale for a particular category, use C<POSIX::setlocale()>
558 with a single parameter--see L<The setlocale function>.)
559
560         use POSIX qw(locale_h);
561
562         # Get a reference to a hash of locale-dependent info
563         $locale_values = localeconv();
564
565         # Output sorted list of the values
566         for (sort keys %$locale_values) {
567             printf "%-20s = %s\n", $_, $locale_values->{$_}
568         }
569
570 C<localeconv()> takes no arguments, and returns B<a reference to> a hash.
571 The keys of this hash are variable names for formatting, such as
572 C<decimal_point> and C<thousands_sep>.  The values are the
573 corresponding, er, values.  See L<POSIX/localeconv> for a longer
574 example listing the categories an implementation might be expected to
575 provide; some provide more and others fewer.  You don't need an
576 explicit C<use locale>, because C<localeconv()> always observes the
577 current locale.
578
579 Here's a simple-minded example program that rewrites its command-line
580 parameters as integers correctly formatted in the current locale:
581
582     use POSIX qw(locale_h);
583
584     # Get some of locale's numeric formatting parameters
585     my ($thousands_sep, $grouping) =
586             @{localeconv()}{'thousands_sep', 'grouping'};
587
588     # Apply defaults if values are missing
589     $thousands_sep = ',' unless $thousands_sep;
590
591     # grouping and mon_grouping are packed lists
592     # of small integers (characters) telling the
593     # grouping (thousand_seps and mon_thousand_seps
594     # being the group dividers) of numbers and
595     # monetary quantities.  The integers' meanings:
596     # 255 means no more grouping, 0 means repeat
597     # the previous grouping, 1-254 means use that
598     # as the current grouping.  Grouping goes from
599     # right to left (low to high digits).  In the
600     # below we cheat slightly by never using anything
601     # else than the first grouping (whatever that is).
602     if ($grouping) {
603         @grouping = unpack("C*", $grouping);
604     } else {
605         @grouping = (3);
606     }
607
608     # Format command line params for current locale
609     for (@ARGV) {
610         $_ = int;    # Chop non-integer part
611         1 while
612         s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
613         print "$_";
614     }
615     print "\n";
616
617 =head2 I18N::Langinfo
618
619 Another interface for querying locale-dependent information is the
620 C<I18N::Langinfo::langinfo()> function, available at least in Unix-like
621 systems and VMS.
622
623 The following example will import the C<langinfo()> function itself and
624 three constants to be used as arguments to C<langinfo()>: a constant for
625 the abbreviated first day of the week (the numbering starts from
626 Sunday = 1) and two more constants for the affirmative and negative
627 answers for a yes/no question in the current locale.
628
629     use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
630
631     my ($abday_1, $yesstr, $nostr)
632                 = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
633
634     print "$abday_1? [$yesstr/$nostr] ";
635
636 In other words, in the "C" (or English) locale the above will probably
637 print something like:
638
639     Sun? [yes/no]
640
641 See L<I18N::Langinfo> for more information.
642
643 =head1 LOCALE CATEGORIES
644
645 The following subsections describe basic locale categories.  Beyond these,
646 some combination categories allow manipulation of more than one
647 basic category at a time.  See L<"ENVIRONMENT"> for a discussion of these.
648
649 =head2 Category LC_COLLATE: Collation
650
651 In the scope of S<C<use locale>> (but not a
652 C<use locale ':not_characters'>), Perl looks to the C<LC_COLLATE>
653 environment variable to determine the application's notions on collation
654 (ordering) of characters.  For example, "b" follows "a" in Latin
655 alphabets, but where do "E<aacute>" and "E<aring>" belong?  And while
656 "color" follows "chocolate" in English, what about in traditional Spanish?
657
658 The following collations all make sense and you may meet any of them
659 if you "use locale".
660
661         A B C D E a b c d e
662         A a B b C c D d E e
663         a A b B c C d D e E
664         a b c d e A B C D E
665
666 Here is a code snippet to tell what "word"
667 characters are in the current locale, in that locale's order:
668
669         use locale;
670         print +(sort grep /\w/, map { chr } 0..255), "\n";
671
672 Compare this with the characters that you see and their order if you
673 state explicitly that the locale should be ignored:
674
675         no locale;
676         print +(sort grep /\w/, map { chr } 0..255), "\n";
677
678 This machine-native collation (which is what you get unless S<C<use
679 locale>> has appeared earlier in the same block) must be used for
680 sorting raw binary data, whereas the locale-dependent collation of the
681 first example is useful for natural text.
682
683 As noted in L<USING LOCALES>, C<cmp> compares according to the current
684 collation locale when C<use locale> is in effect, but falls back to a
685 char-by-char comparison for strings that the locale says are equal. You
686 can use C<POSIX::strcoll()> if you don't want this fall-back:
687
688         use POSIX qw(strcoll);
689         $equal_in_locale =
690             !strcoll("space and case ignored", "SpaceAndCaseIgnored");
691
692 C<$equal_in_locale> will be true if the collation locale specifies a
693 dictionary-like ordering that ignores space characters completely and
694 which folds case.
695
696 If you have a single string that you want to check for "equality in
697 locale" against several others, you might think you could gain a little
698 efficiency by using C<POSIX::strxfrm()> in conjunction with C<eq>:
699
700         use POSIX qw(strxfrm);
701         $xfrm_string = strxfrm("Mixed-case string");
702         print "locale collation ignores spaces\n"
703             if $xfrm_string eq strxfrm("Mixed-casestring");
704         print "locale collation ignores hyphens\n"
705             if $xfrm_string eq strxfrm("Mixedcase string");
706         print "locale collation ignores case\n"
707             if $xfrm_string eq strxfrm("mixed-case string");
708
709 C<strxfrm()> takes a string and maps it into a transformed string for use
710 in char-by-char comparisons against other transformed strings during
711 collation.  "Under the hood", locale-affected Perl comparison operators
712 call C<strxfrm()> for both operands, then do a char-by-char
713 comparison of the transformed strings.  By calling C<strxfrm()> explicitly
714 and using a non locale-affected comparison, the example attempts to save
715 a couple of transformations.  But in fact, it doesn't save anything: Perl
716 magic (see L<perlguts/Magic Variables>) creates the transformed version of a
717 string the first time it's needed in a comparison, then keeps this version around
718 in case it's needed again.  An example rewritten the easy way with
719 C<cmp> runs just about as fast.  It also copes with null characters
720 embedded in strings; if you call C<strxfrm()> directly, it treats the first
721 null it finds as a terminator.  don't expect the transformed strings
722 it produces to be portable across systems--or even from one revision
723 of your operating system to the next.  In short, don't call C<strxfrm()>
724 directly: let Perl do it for you.
725
726 Note: C<use locale> isn't shown in some of these examples because it isn't
727 needed: C<strcoll()> and C<strxfrm()> exist only to generate locale-dependent
728 results, and so always obey the current C<LC_COLLATE> locale.
729
730 =head2 Category LC_CTYPE: Character Types
731
732 In the scope of S<C<use locale>> (but not a
733 C<use locale ':not_characters'>), Perl obeys the C<LC_CTYPE> locale
734 setting.  This controls the application's notion of which characters are
735 alphabetic.  This affects Perl's C<\w> regular expression metanotation,
736 which stands for alphanumeric characters--that is, alphabetic,
737 numeric, and including other special characters such as the underscore or
738 hyphen.  (Consult L<perlre> for more information about
739 regular expressions.)  Thanks to C<LC_CTYPE>, depending on your locale
740 setting, characters like "E<aelig>", "E<eth>", "E<szlig>", and
741 "E<oslash>" may be understood as C<\w> characters.
742
743 The C<LC_CTYPE> locale also provides the map used in transliterating
744 characters between lower and uppercase.  This affects the case-mapping
745 functions--C<fc()>, C<lc()>, C<lcfirst()>, C<uc()>, and C<ucfirst()>; case-mapping
746 interpolation with C<\F>, C<\l>, C<\L>, C<\u>, or C<\U> in double-quoted
747 strings and C<s///> substitutions; and case-independent regular expression
748 pattern matching using the C<i> modifier.
749
750 Finally, C<LC_CTYPE> affects the POSIX character-class test
751 functions--C<isalpha()>, C<islower()>, and so on.  For example, if you move
752 from the "C" locale to a 7-bit Scandinavian one, you may find--possibly
753 to your surprise--that "|" moves from the C<ispunct()> class to C<isalpha()>.
754 Unfortunately, this creates big problems for regular expressions. "|" still
755 means alternation even though it matches C<\w>.
756
757 Note that there are quite a few things that are unaffected by the
758 current locale.  All the escape sequences for particular characters,
759 C<\n> for example, always mean the platform's native one.  This means,
760 for example, that C<\N> in regular expressions (every character
761 but new-line) work on the platform character set.
762
763 B<Note:> A broken or malicious C<LC_CTYPE> locale definition may result
764 in clearly ineligible characters being considered to be alphanumeric by
765 your application.  For strict matching of (mundane) ASCII letters and
766 digits--for example, in command strings--locale-aware applications
767 should use C<\w> with the C</a> regular expression modifier.  See L<"SECURITY">.
768
769 =head2 Category LC_NUMERIC: Numeric Formatting
770
771 After a proper C<POSIX::setlocale()> call, and within the scope of one
772 of the C<use locale> variants, Perl obeys the C<LC_NUMERIC>
773 locale information, which controls an application's idea of how numbers
774 should be formatted for human readability.
775 In most implementations the only effect is to
776 change the character used for the decimal point--perhaps from "."  to ",".
777 The functions aren't aware of such niceties as thousands separation and
778 so on. (See L<The localeconv function> if you care about these things.)
779
780  use POSIX qw(strtod setlocale LC_NUMERIC);
781  use locale;
782
783  setlocale LC_NUMERIC, "";
784
785  $n = 5/2;   # Assign numeric 2.5 to $n
786
787  $a = " $n"; # Locale-dependent conversion to string
788
789  print "half five is $n\n";       # Locale-dependent output
790
791  printf "half five is %g\n", $n;  # Locale-dependent output
792
793  print "DECIMAL POINT IS COMMA\n"
794           if $n == (strtod("2,5"))[0]; # Locale-dependent conversion
795
796 See also L<I18N::Langinfo> and C<RADIXCHAR>.
797
798 =head2 Category LC_MONETARY: Formatting of monetary amounts
799
800 The C standard defines the C<LC_MONETARY> category, but not a function
801 that is affected by its contents.  (Those with experience of standards
802 committees will recognize that the working group decided to punt on the
803 issue.)  Consequently, Perl essentially takes no notice of it.  If you
804 really want to use C<LC_MONETARY>, you can query its contents--see
805 L<The localeconv function>--and use the information that it returns in your
806 application's own formatting of currency amounts.  However, you may well
807 find that the information, voluminous and complex though it may be, still
808 does not quite meet your requirements: currency formatting is a hard nut
809 to crack.
810
811 See also L<I18N::Langinfo> and C<CRNCYSTR>.
812
813 =head2 LC_TIME
814
815 Output produced by C<POSIX::strftime()>, which builds a formatted
816 human-readable date/time string, is affected by the current C<LC_TIME>
817 locale.  Thus, in a French locale, the output produced by the C<%B>
818 format element (full month name) for the first month of the year would
819 be "janvier".  Here's how to get a list of long month names in the
820 current locale:
821
822         use POSIX qw(strftime);
823         for (0..11) {
824             $long_month_name[$_] =
825                 strftime("%B", 0, 0, 0, 1, $_, 96);
826         }
827
828 Note: C<use locale> isn't needed in this example: C<strftime()> is a POSIX
829 function which uses the standard system-supplied C<libc> function that
830 always obeys the current C<LC_TIME> locale.
831
832 See also L<I18N::Langinfo> and C<ABDAY_1>..C<ABDAY_7>, C<DAY_1>..C<DAY_7>,
833 C<ABMON_1>..C<ABMON_12>, and C<ABMON_1>..C<ABMON_12>.
834
835 =head2 Other categories
836
837 The remaining locale categories are not currently used by Perl itself.
838 But again note that things Perl interacts with may use these, including
839 extensions outside the standard Perl distribution, and by the
840 operating system and its utilities.  Note especially that the string
841 value of C<$!> and the error messages given by external utilities may
842 be changed by C<LC_MESSAGES>.  If you want to have portable error
843 codes, use C<%!>.  See L<Errno>.
844
845 =head1 SECURITY
846
847 Although the main discussion of Perl security issues can be found in
848 L<perlsec>, a discussion of Perl's locale handling would be incomplete
849 if it did not draw your attention to locale-dependent security issues.
850 Locales--particularly on systems that allow unprivileged users to
851 build their own locales--are untrustworthy.  A malicious (or just plain
852 broken) locale can make a locale-aware application give unexpected
853 results.  Here are a few possibilities:
854
855 =over 4
856
857 =item *
858
859 Regular expression checks for safe file names or mail addresses using
860 C<\w> may be spoofed by an C<LC_CTYPE> locale that claims that
861 characters such as "E<gt>" and "|" are alphanumeric.
862
863 =item *
864
865 String interpolation with case-mapping, as in, say, C<$dest =
866 "C:\U$name.$ext">, may produce dangerous results if a bogus LC_CTYPE
867 case-mapping table is in effect.
868
869 =item *
870
871 A sneaky C<LC_COLLATE> locale could result in the names of students with
872 "D" grades appearing ahead of those with "A"s.
873
874 =item *
875
876 An application that takes the trouble to use information in
877 C<LC_MONETARY> may format debits as if they were credits and vice versa
878 if that locale has been subverted.  Or it might make payments in US
879 dollars instead of Hong Kong dollars.
880
881 =item *
882
883 The date and day names in dates formatted by C<strftime()> could be
884 manipulated to advantage by a malicious user able to subvert the
885 C<LC_DATE> locale.  ("Look--it says I wasn't in the building on
886 Sunday.")
887
888 =back
889
890 Such dangers are not peculiar to the locale system: any aspect of an
891 application's environment which may be modified maliciously presents
892 similar challenges.  Similarly, they are not specific to Perl: any
893 programming language that allows you to write programs that take
894 account of their environment exposes you to these issues.
895
896 Perl cannot protect you from all possibilities shown in the
897 examples--there is no substitute for your own vigilance--but, when
898 C<use locale> is in effect, Perl uses the tainting mechanism (see
899 L<perlsec>) to mark string results that become locale-dependent, and
900 which may be untrustworthy in consequence.  Here is a summary of the
901 tainting behavior of operators and functions that may be affected by
902 the locale:
903
904 =over 4
905
906 =item  *
907
908 B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
909
910 Scalar true/false (or less/equal/greater) result is never tainted.
911
912 =item  *
913
914 B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
915
916 Result string containing interpolated material is tainted if
917 C<use locale> (but not S<C<use locale ':not_characters'>>) is in effect.
918
919 =item  *
920
921 B<Matching operator> (C<m//>):
922
923 Scalar true/false result never tainted.
924
925 Subpatterns, either delivered as a list-context result or as $1 etc.
926 are tainted if C<use locale> (but not S<C<use locale ':not_characters'>>)
927 is in effect, and the subpattern regular
928 expression contains C<\w> (to match an alphanumeric character), C<\W>
929 (non-alphanumeric character), C<\s> (whitespace character), or C<\S>
930 (non whitespace character).  The matched-pattern variable, $&, $`
931 (pre-match), $' (post-match), and $+ (last match) are also tainted if
932 C<use locale> is in effect and the regular expression contains C<\w>,
933 C<\W>, C<\s>, or C<\S>.
934
935 =item  *
936
937 B<Substitution operator> (C<s///>):
938
939 Has the same behavior as the match operator.  Also, the left
940 operand of C<=~> becomes tainted when C<use locale>
941 (but not S<C<use locale ':not_characters'>>) is in effect if modified as
942 a result of a substitution based on a regular
943 expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
944 case-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
945
946 =item *
947
948 B<Output formatting functions> (C<printf()> and C<write()>):
949
950 Results are never tainted because otherwise even output from print,
951 for example C<print(1/7)>, should be tainted if C<use locale> is in
952 effect.
953
954 =item *
955
956 B<Case-mapping functions> (C<lc()>, C<lcfirst()>, C<uc()>, C<ucfirst()>):
957
958 Results are tainted if C<use locale> (but not
959 S<C<use locale ':not_characters'>>) is in effect.
960
961 =item *
962
963 B<POSIX locale-dependent functions> (C<localeconv()>, C<strcoll()>,
964 C<strftime()>, C<strxfrm()>):
965
966 Results are never tainted.
967
968 =item *
969
970 B<POSIX character class tests> (C<isalnum()>, C<isalpha()>, C<isdigit()>,
971 C<isgraph()>, C<islower()>, C<isprint()>, C<ispunct()>, C<isspace()>, C<isupper()>,
972 C<isxdigit()>):
973
974 True/false results are never tainted.
975
976 =back
977
978 Three examples illustrate locale-dependent tainting.
979 The first program, which ignores its locale, won't run: a value taken
980 directly from the command line may not be used to name an output file
981 when taint checks are enabled.
982
983         #/usr/local/bin/perl -T
984         # Run with taint checking
985
986         # Command line sanity check omitted...
987         $tainted_output_file = shift;
988
989         open(F, ">$tainted_output_file")
990             or warn "Open of $tainted_output_file failed: $!\n";
991
992 The program can be made to run by "laundering" the tainted value through
993 a regular expression: the second example--which still ignores locale
994 information--runs, creating the file named on its command line
995 if it can.
996
997         #/usr/local/bin/perl -T
998
999         $tainted_output_file = shift;
1000         $tainted_output_file =~ m%[\w/]+%;
1001         $untainted_output_file = $&;
1002
1003         open(F, ">$untainted_output_file")
1004             or warn "Open of $untainted_output_file failed: $!\n";
1005
1006 Compare this with a similar but locale-aware program:
1007
1008         #/usr/local/bin/perl -T
1009
1010         $tainted_output_file = shift;
1011         use locale;
1012         $tainted_output_file =~ m%[\w/]+%;
1013         $localized_output_file = $&;
1014
1015         open(F, ">$localized_output_file")
1016             or warn "Open of $localized_output_file failed: $!\n";
1017
1018 This third program fails to run because $& is tainted: it is the result
1019 of a match involving C<\w> while C<use locale> is in effect.
1020
1021 =head1 ENVIRONMENT
1022
1023 =over 12
1024
1025 =item PERL_BADLANG
1026
1027 A string that can suppress Perl's warning about failed locale settings
1028 at startup.  Failure can occur if the locale support in the operating
1029 system is lacking (broken) in some way--or if you mistyped the name of
1030 a locale when you set up your environment.  If this environment
1031 variable is absent, or has a value that does not evaluate to integer
1032 zero--that is, "0" or ""-- Perl will complain about locale setting
1033 failures.
1034
1035 B<NOTE>: PERL_BADLANG only gives you a way to hide the warning message.
1036 The message tells about some problem in your system's locale support,
1037 and you should investigate what the problem is.
1038
1039 =back
1040
1041 The following environment variables are not specific to Perl: They are
1042 part of the standardized (ISO C, XPG4, POSIX 1.c) C<setlocale()> method
1043 for controlling an application's opinion on data.
1044
1045 =over 12
1046
1047 =item LC_ALL
1048
1049 C<LC_ALL> is the "override-all" locale environment variable. If
1050 set, it overrides all the rest of the locale environment variables.
1051
1052 =item LANGUAGE
1053
1054 B<NOTE>: C<LANGUAGE> is a GNU extension, it affects you only if you
1055 are using the GNU libc.  This is the case if you are using e.g. Linux.
1056 If you are using "commercial" Unixes you are most probably I<not>
1057 using GNU libc and you can ignore C<LANGUAGE>.
1058
1059 However, in the case you are using C<LANGUAGE>: it affects the
1060 language of informational, warning, and error messages output by
1061 commands (in other words, it's like C<LC_MESSAGES>) but it has higher
1062 priority than C<LC_ALL>.  Moreover, it's not a single value but
1063 instead a "path" (":"-separated list) of I<languages> (not locales).
1064 See the GNU C<gettext> library documentation for more information.
1065
1066 =item LC_CTYPE
1067
1068 In the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type
1069 locale.  In the absence of both C<LC_ALL> and C<LC_CTYPE>, C<LANG>
1070 chooses the character type locale.
1071
1072 =item LC_COLLATE
1073
1074 In the absence of C<LC_ALL>, C<LC_COLLATE> chooses the collation
1075 (sorting) locale.  In the absence of both C<LC_ALL> and C<LC_COLLATE>,
1076 C<LANG> chooses the collation locale.
1077
1078 =item LC_MONETARY
1079
1080 In the absence of C<LC_ALL>, C<LC_MONETARY> chooses the monetary
1081 formatting locale.  In the absence of both C<LC_ALL> and C<LC_MONETARY>,
1082 C<LANG> chooses the monetary formatting locale.
1083
1084 =item LC_NUMERIC
1085
1086 In the absence of C<LC_ALL>, C<LC_NUMERIC> chooses the numeric format
1087 locale.  In the absence of both C<LC_ALL> and C<LC_NUMERIC>, C<LANG>
1088 chooses the numeric format.
1089
1090 =item LC_TIME
1091
1092 In the absence of C<LC_ALL>, C<LC_TIME> chooses the date and time
1093 formatting locale.  In the absence of both C<LC_ALL> and C<LC_TIME>,
1094 C<LANG> chooses the date and time formatting locale.
1095
1096 =item LANG
1097
1098 C<LANG> is the "catch-all" locale environment variable. If it is set, it
1099 is used as the last resort after the overall C<LC_ALL> and the
1100 category-specific C<LC_...>.
1101
1102 =back
1103
1104 =head2 Examples
1105
1106 The LC_NUMERIC controls the numeric output:
1107
1108    use locale;
1109    use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
1110    setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
1111    printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
1112
1113 and also how strings are parsed by C<POSIX::strtod()> as numbers:
1114
1115    use locale;
1116    use POSIX qw(locale_h strtod);
1117    setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
1118    my $x = strtod("2,34") + 5;
1119    print $x, "\n"; # Probably shows 7,34.
1120
1121 =head1 NOTES
1122
1123 =head2 String C<eval> and C<LC_NUMERIC>
1124
1125 A string L<eval|perlfunc/eval EXPR> parses its expression as standard
1126 Perl.  It is therefore expecting the decimal point to be a dot.  If
1127 C<LC_NUMERIC> is set to have this be a comma instead, the parsing will
1128 be confused, perhaps silently.
1129
1130  use locale;
1131  use POSIX qw(locale_h);
1132  setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
1133  my $a = 1.2;
1134  print eval "$a + 1.5";
1135  print "\n";
1136
1137 prints C<13,5>.  This is because in that locale, the comma is the
1138 decimal point character.  The C<eval> thus expands to:
1139
1140  eval "1,2 + 1.5"
1141
1142 and the result is not what you likely expected.  No warnings are
1143 generated.  If you do string C<eval>'s within the scope of
1144 S<C<use locale>>, you should instead change the C<eval> line to do
1145 something like:
1146
1147  print eval "no locale; $a + 1.5";
1148
1149 This prints C<2.7>.
1150
1151 =head2 Backward compatibility
1152
1153 Versions of Perl prior to 5.004 B<mostly> ignored locale information,
1154 generally behaving as if something similar to the C<"C"> locale were
1155 always in force, even if the program environment suggested otherwise
1156 (see L<The setlocale function>).  By default, Perl still behaves this
1157 way for backward compatibility.  If you want a Perl application to pay
1158 attention to locale information, you B<must> use the S<C<use locale>>
1159 pragma (see L<The use locale pragma>) or, in the unlikely event
1160 that you want to do so for just pattern matching, the
1161 C</l> regular expression modifier (see L<perlre/Character set
1162 modifiers>) to instruct it to do so.
1163
1164 Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE>
1165 information if available; that is, C<\w> did understand what
1166 were the letters according to the locale environment variables.
1167 The problem was that the user had no control over the feature:
1168 if the C library supported locales, Perl used them.
1169
1170 =head2 I18N:Collate obsolete
1171
1172 In versions of Perl prior to 5.004, per-locale collation was possible
1173 using the C<I18N::Collate> library module.  This module is now mildly
1174 obsolete and should be avoided in new applications.  The C<LC_COLLATE>
1175 functionality is now integrated into the Perl core language: One can
1176 use locale-specific scalar data completely normally with C<use locale>,
1177 so there is no longer any need to juggle with the scalar references of
1178 C<I18N::Collate>.
1179
1180 =head2 Sort speed and memory use impacts
1181
1182 Comparing and sorting by locale is usually slower than the default
1183 sorting; slow-downs of two to four times have been observed.  It will
1184 also consume more memory: once a Perl scalar variable has participated
1185 in any string comparison or sorting operation obeying the locale
1186 collation rules, it will take 3-15 times more memory than before.  (The
1187 exact multiplier depends on the string's contents, the operating system
1188 and the locale.) These downsides are dictated more by the operating
1189 system's implementation of the locale system than by Perl.
1190
1191 =head2 Freely available locale definitions
1192
1193 The Unicode CLDR project extracts the POSIX portion of many of its
1194 locales, available at
1195
1196   http://unicode.org/Public/cldr/latest/
1197
1198 There is a large collection of locale definitions at:
1199
1200   http://std.dkuug.dk/i18n/WG15-collection/locales/
1201
1202 You should be aware that it is
1203 unsupported, and is not claimed to be fit for any purpose.  If your
1204 system allows installation of arbitrary locales, you may find the
1205 definitions useful as they are, or as a basis for the development of
1206 your own locales.
1207
1208 =head2 I18n and l10n
1209
1210 "Internationalization" is often abbreviated as B<i18n> because its first
1211 and last letters are separated by eighteen others.  (You may guess why
1212 the internalin ... internaliti ... i18n tends to get abbreviated.)  In
1213 the same way, "localization" is often abbreviated to B<l10n>.
1214
1215 =head2 An imperfect standard
1216
1217 Internationalization, as defined in the C and POSIX standards, can be
1218 criticized as incomplete, ungainly, and having too large a granularity.
1219 (Locales apply to a whole process, when it would arguably be more useful
1220 to have them apply to a single thread, window group, or whatever.)  They
1221 also have a tendency, like standards groups, to divide the world into
1222 nations, when we all know that the world can equally well be divided
1223 into bankers, bikers, gamers, and so on.
1224
1225 =head1 Unicode and UTF-8
1226
1227 The support of Unicode is new starting from Perl version v5.6, and more fully
1228 implemented in version v5.8 and later.  See L<perluniintro>.  It is
1229 strongly recommended that when combining Unicode and locale (starting in
1230 v5.16), you use
1231
1232     use locale ':not_characters';
1233
1234 When this form of the pragma is used, only the non-character portions of
1235 locales are used by Perl, for example C<LC_NUMERIC>.  Perl assumes that
1236 you have translated all the characters it is to operate on into Unicode
1237 (actually the platform's native character set (ASCII or EBCDIC) plus
1238 Unicode).  For data in files, this can conveniently be done by also
1239 specifying
1240
1241     use open ':locale';
1242
1243 This pragma arranges for all inputs from files to be translated into
1244 Unicode from the current locale as specified in the environment (see
1245 L</ENVIRONMENT>), and all outputs to files to be translated back
1246 into the locale.  (See L<open>).  On a per-filehandle basis, you can
1247 instead use the L<PerlIO::locale> module, or the L<Encode::Locale>
1248 module, both available from CPAN.  The latter module also has methods to
1249 ease the handling of C<ARGV> and environment variables, and can be used
1250 on individual strings.  Also, if you know that all your locales will be
1251 UTF-8, as many are these days, you can use the L<B<-C>|perlrun/-C>
1252 command line switch.
1253
1254 This form of the pragma allows essentially seamless handling of locales
1255 with Unicode.  The collation order will be Unicode's.  It is strongly
1256 recommended that when you need to order and sort strings that you use
1257 the standard module L<Unicode::Collate> which gives much better results
1258 in many instances than you can get with the old-style locale handling.
1259
1260 For pre-v5.16 Perls, or if you use the locale pragma without the
1261 C<:not_characters> parameter, Perl tries to work with both Unicode and
1262 locales--but there are problems.
1263
1264 Perl does not handle multi-byte locales in this case, such as have been
1265 used for various
1266 Asian languages, such as Big5 or Shift JIS.  However, the increasingly
1267 common multi-byte UTF-8 locales, if properly implemented, may work
1268 reasonably well (depending on your C library implementation) in this
1269 form of the locale pragma, simply because both
1270 they and Perl store characters that take up multiple bytes the same way.
1271 However, some, if not most, C library implementations may not process
1272 the characters in the upper half of the Latin-1 range (128 - 255)
1273 properly under LC_CTYPE.  To see if a character is a particular type
1274 under a locale, Perl uses the functions like C<isalnum()>.  Your C
1275 library may not work for UTF-8 locales with those functions, instead
1276 only working under the newer wide library functions like C<iswalnum()>.
1277
1278 Perl generally takes the tack to use locale rules on code points that can fit
1279 in a single byte, and Unicode rules for those that can't (though this
1280 isn't uniformly applied, see the note at the end of this section).  This
1281 prevents many problems in locales that aren't UTF-8.  Suppose the locale
1282 is ISO8859-7, Greek.  The character at 0xD7 there is a capital Chi. But
1283 in the ISO8859-1 locale, Latin1, it is a multiplication sign.  The POSIX
1284 regular expression character class C<[[:alpha:]]> will magically match
1285 0xD7 in the Greek locale but not in the Latin one.
1286
1287 However, there are places where this breaks down.  Certain constructs are
1288 for Unicode only, such as C<\p{Alpha}>.  They assume that 0xD7 always has its
1289 Unicode meaning (or the equivalent on EBCDIC platforms).  Since Latin1 is a
1290 subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and
1291 Unicode, C<\p{Alpha}> will never match it, regardless of locale.  A similar
1292 issue occurs with C<\N{...}>.  It is therefore a bad idea to use C<\p{}> or
1293 C<\N{}> under plain C<use locale>--I<unless> you can guarantee that the
1294 locale will be a ISO8859-1.  Use POSIX character classes instead.
1295
1296 Another problem with this approach is that operations that cross the
1297 single byte/multiple byte boundary are not well-defined, and so are
1298 disallowed.  (This boundary is between the codepoints at 255/256.).
1299 For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
1300 should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF).  But in the
1301 Greek locale, for example, there is no character at 0xFF, and Perl
1302 has no way of knowing what the character at 0xFF is really supposed to
1303 represent.  Thus it disallows the operation.  In this mode, the
1304 lowercase of U+0178 is itself.
1305
1306 The same problems ensue if you enable automatic UTF-8-ification of your
1307 standard file handles, default C<open()> layer, and C<@ARGV> on non-ISO8859-1,
1308 non-UTF-8 locales (by using either the B<-C> command line switch or the
1309 C<PERL_UNICODE> environment variable; see L<perlrun>).
1310 Things are read in as UTF-8, which would normally imply a Unicode
1311 interpretation, but the presence of a locale causes them to be interpreted
1312 in that locale instead.  For example, a 0xD7 code point in the Unicode
1313 input, which should mean the multiplication sign, won't be interpreted by
1314 Perl that way under the Greek locale.  This is not a problem
1315 I<provided> you make certain that all locales will always and only be either
1316 an ISO8859-1, or, if you don't have a deficient C library, a UTF-8 locale.
1317
1318 Vendor locales are notoriously buggy, and it is difficult for Perl to test
1319 its locale-handling code because this interacts with code that Perl has no
1320 control over; therefore the locale-handling code in Perl may be buggy as
1321 well.  (However, the Unicode-supplied locales should be better, and
1322 there is a feed back mechanism to correct any problems.  See
1323 L</Freely available locale definitions>.)
1324
1325 If you have Perl v5.16, the problems mentioned above go away if you use
1326 the C<:not_characters> parameter to the locale pragma (except for vendor
1327 bugs in the non-character portions).  If you don't have v5.16, and you
1328 I<do> have locales that work, using them may be worthwhile for certain
1329 specific purposes, as long as you keep in mind the gotchas already
1330 mentioned.  For example, if the collation for your locales works, it
1331 runs faster under locales than under L<Unicode::Collate>; and you gain
1332 access to such things as the local currency symbol and the names of the
1333 months and days of the week.  (But to hammer home the point, in v5.16,
1334 you get this access without the downsides of locales by using the
1335 C<:not_characters> form of the pragma.)
1336
1337 Note: The policy of using locale rules for code points that can fit in a
1338 byte, and Unicode rules for those that can't is not uniformly applied.
1339 Pre-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
1340 consistently to regular expression matching except for bracketed
1341 character classes; in v5.14 it was extended to all regex matches; and in
1342 v5.16 to the casing operations such as C<"\L"> and C<uc()>.  For
1343 collation, in all releases, the system's C<strxfrm()> function is called,
1344 and whatever it does is what you get.
1345
1346 =head1 BUGS
1347
1348 =head2 Broken systems
1349
1350 In certain systems, the operating system's locale support
1351 is broken and cannot be fixed or used by Perl.  Such deficiencies can
1352 and will result in mysterious hangs and/or Perl core dumps when
1353 C<use locale> is in effect.  When confronted with such a system,
1354 please report in excruciating detail to <F<perlbug@perl.org>>, and
1355 also contact your vendor: bug fixes may exist for these problems
1356 in your operating system.  Sometimes such bug fixes are called an
1357 operating system upgrade.
1358
1359 =head1 SEE ALSO
1360
1361 L<I18N::Langinfo>, L<perluniintro>, L<perlunicode>, L<open>,
1362 L<POSIX/isalnum>, L<POSIX/isalpha>,
1363 L<POSIX/isdigit>, L<POSIX/isgraph>, L<POSIX/islower>,
1364 L<POSIX/isprint>, L<POSIX/ispunct>, L<POSIX/isspace>,
1365 L<POSIX/isupper>, L<POSIX/isxdigit>, L<POSIX/localeconv>,
1366 L<POSIX/setlocale>, L<POSIX/strcoll>, L<POSIX/strftime>,
1367 L<POSIX/strtod>, L<POSIX/strxfrm>.
1368
1369 =head1 HISTORY
1370
1371 Jarkko Hietaniemi's original F<perli18n.pod> heavily hacked by Dominic
1372 Dunlop, assisted by the perl5-porters.  Prose worked over a bit by
1373 Tom Christiansen, and updated by Perl 5 porters.