1N/Aperllocale - Perl locale handling (internationalization and localization)
1N/APerl supports language-specific notions of data such as "is this
1N/Aa letter", "what is the uppercase equivalent of this letter", and
1N/A"which of these letters comes first". These are important issues,
1N/Aespecially for languages other than English--but also for English: it
1N/Awould be naE<iuml>ve to imagine that C<A-Za-z> defines all the "letters"
1N/Aneeded to write in English. Perl is also aware that some character other
1N/Athan '.' may be preferred as a decimal point, and that output date
1N/Arepresentations may be language-specific. The process of making an
1N/Aapplication take account of its users' preferences in such matters is
1N/Acalled B<internationalization> (often abbreviated as B<i18n>); telling
1N/Asuch an application about a particular set of preferences is known as
1N/AB<localization> (B<l10n>).
1N/APerl can understand language-specific data via the standardized (ISO C,
1N/AXPG4, POSIX
1.c) method called "the locale system". The locale system is
1N/Acontrolled per application using one pragma, one function call, and
1N/Aseveral environment variables.
1N/AB<NOTE>: This feature is new in Perl 5.004, and does not apply unless an
1N/Aapplication specifically requests it--see L<Backward compatibility>.
1N/AThe one exception is that write() now B<always> uses the current locale
1N/A=head1 PREPARING TO USE LOCALES
1N/AIf Perl applications are to understand and present your data
1N/Acorrectly according a locale of your choice, B<all> of the following
1N/AB<Your operating system must support the locale system>. If it does,
1N/Ayou should find that the setlocale() function is a documented part of
1N/AB<Definitions for locales that you use must be installed>. You, or
1N/Ayour system administrator, must make sure that this is the case. The
1N/Aavailable locales, the location in which they are kept, and the manner
1N/Ain which they are installed all vary from system to system. Some systems
1N/Aprovide only a few, hard-wired locales and do not allow more to be
1N/Aadded. Others allow you to add "canned" locales provided by the system
1N/Asupplier. Still others allow you or the system administrator to define
1N/Aand add arbitrary locales. (You may have to ask your supplier to
1N/Aprovide canned locales that are not delivered with your operating
1N/Asystem.) Read your system documentation for further illumination.
1N/AB<Perl must believe that the locale system is supported>. If it does,
1N/AC<perl -V:d_setlocale> will say that the value for C<d_setlocale> is
1N/AIf you want a Perl application to process and present your data
1N/Aaccording to a particular locale, the application code should include
1N/Athe S<C<use locale>> pragma (see L<The use locale pragma>) where
1N/Aappropriate, and B<at least one> of the following must be true:
1N/AB<The locale-determining environment variables (see L<"ENVIRONMENT">)
1N/Amust be correctly set up> at the time the application is started, either
1N/Aby yourself or by whoever set up your system account.
1N/AB<The application must set its own locale> using the method described in
1N/AL<The setlocale function>.
1N/A=head2 The use locale pragma
1N/ABy default, Perl ignores the current locale. The S<C<use locale>>
1N/Apragma tells Perl to use the current locale for some operations:
1N/AB<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>) and
1N/Athe POSIX string collation functions strcoll() and strxfrm() use
1N/AC<LC_COLLATE>. sort() is also affected if used without an
1N/Aexplicit comparison function, because it uses C<cmp> by default.
1N/AB<Note:> C<eq> and C<ne> are unaffected by locale: they always
1N/Aperform a char-by-char comparison of their scalar operands. What's
1N/Amore, if C<cmp> finds that its operands are equal according to the
1N/Acollation sequence specified by the current locale, it goes on to
1N/Aperform a char-by-char comparison, and only returns I<0> (equal) if the
1N/Aoperands are char-for-char identical. If you really want to know whether
1N/Atwo strings--which C<eq> and C<cmp> may consider different--are equal
1N/Aas far as collation in the locale is concerned, see the discussion in
1N/AL<Category LC_COLLATE: Collation>.
1N/AB<Regular expressions and case-modification functions> (uc(), lc(),
1N/Aucfirst(), and lcfirst()) use C<LC_CTYPE>
1N/AB<The formatting functions> (printf(), sprintf() and write()) use
1N/AB<The POSIX date formatting function> (strftime()) uses C<LC_TIME>.
1N/AC<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in
1N/AL<LOCALE CATEGORIES>.
1N/AThe default behavior is restored with the S<C<no locale>> pragma, or
1N/Aupon reaching the end of block enclosing C<use locale>.
1N/AThe string result of any operation that uses locale
1N/Ainformation is tainted, as it is possible for a locale to be
1N/Auntrustworthy. See L<"SECURITY">.
1N/A=head2 The setlocale function
1N/AYou can switch locales as often as you wish at run time with the
1N/APOSIX::setlocale() function:
1N/A # This functionality not usable prior to Perl 5.004
1N/A # Import locale-handling tool set from POSIX module.
1N/A # This example uses: setlocale -- the function call
1N/A # LC_CTYPE -- explained below
1N/A use POSIX qw(locale_h);
1N/A # query and save the old locale
1N/A $old_locale = setlocale(LC_CTYPE);
1N/A # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
1N/A setlocale(LC_CTYPE, "");
1N/A # environment variables. See below for documentation.
1N/A # restore the old locale
1N/A setlocale(LC_CTYPE, $old_locale);
1N/AThe first argument of setlocale() gives the B<category>, the second the
1N/AB<locale>. The category tells in what aspect of data processing you
1N/Awant to apply locale-specific rules. Category names are discussed in
1N/AL<LOCALE CATEGORIES> and L<"ENVIRONMENT">. The locale is the name of a
1N/Acollection of customization information corresponding to a particular
1N/Acombination of language, country or territory, and codeset. Read on for
1N/Ahints on the naming of locales: not all systems name locales as in the
1N/AIf no second argument is provided and the category is something else
1N/Athan LC_ALL, the function returns a string naming the current locale
1N/Afor the category. You can use this value as the second argument in a
1N/Asubsequent call to setlocale().
1N/AIf no second argument is provided and the category is LC_ALL, the
1N/Aresult is implementation-dependent. It may be a string of
1N/Aconcatenated locales names (separator also implementation-dependent)
1N/Aor a single locale name. Please consult your L<setlocale(3)> for
1N/AIf a second argument is given and it corresponds to a valid locale,
1N/Athe locale for the category is set to that value, and the function
1N/Areturns the now-current locale value. You can then use this in yet
1N/Aanother call to setlocale(). (In some implementations, the return
1N/Avalue may sometimes differ from the value you gave as the second
1N/Aargument--think of it as an alias for the value you gave.)
1N/AAs the example shows, if the second argument is an empty string, the
1N/Acategory's locale is returned to the default specified by the
1N/Acorresponding environment variables. Generally, this results in a
1N/Areturn to the default that was in force when Perl started up: changes
1N/Ato the environment made by the application after startup may or may not
1N/Abe noticed, depending on your system's C library.
1N/AIf the second argument does not correspond to a valid locale, the locale
1N/Afor the category is not changed, and the function returns I<undef>.
1N/AFor further information about the categories, consult L<setlocale(3)>.
1N/A=head2 Finding locales
1N/AFor locales available in your system, consult also L<setlocale(3)> to
1N/Asee whether it leads to the list of available locales (search for the
1N/AI<SEE ALSO> section). If that fails, try the following command lines:
1N/Aand see whether they list something resembling these
1N/A english german russian
1N/ASadly, even though the calling interface for setlocale() has been
1N/Astandardized, names of locales and the directories where the
1N/Aconfiguration resides have not been. The basic form of the name is
1N/AI<language_territory>B<.>I<codeset>, but the latter parts after
1N/AI<language> are not always present. The I<language> and I<country>
1N/Aare usually from the standards B<ISO 3166> and B<ISO 639>, the
1N/Atwo-letter abbreviations for the countries and the languages of the
1N/Aworld, respectively. The I<codeset> part often mentions some B<ISO
1N/A8859> character set, the Latin codesets. For example, C<ISO 8859-1>
1N/Ais the so-called "Western European codeset" that can be used to encode
1N/Amost Western European languages adequately. Again, there are several
1N/Aways to write even the name of that one standard. Lamentably.
1N/ATwo special locales are worth particular mention: "C" and "POSIX".
1N/ACurrently these are effectively the same locale: the difference is
1N/Amainly that the first one is defined by the C standard, the second by
1N/Athe POSIX standard. They define the B<default locale> in which
1N/Aevery program starts in the absence of locale information in its
1N/Aenvironment. (The I<default> default locale, if you will.) Its language
1N/Ais (American) English and its character codeset ASCII.
1N/AB<NOTE>: Not all systems have the "POSIX" locale (not all systems are
1N/APOSIX-conformant), so use "C" when you need explicitly to specify this
1N/A=head2 LOCALE PROBLEMS
1N/AYou may encounter the following warning message at Perl startup:
1N/A perl: warning: Setting locale failed.
1N/A perl: warning: Please check that your locale settings:
1N/A are supported and installed on your system.
1N/A perl: warning: Falling back to the standard locale ("C").
1N/AThis means that your locale settings had LC_ALL set to "En_US" and
1N/ALANG exists but has no value. Perl tried to believe you but could not.
1N/AInstead, Perl gave up and fell back to the "C" locale, the default locale
1N/Athat is supposed to work no matter what. This usually means your locale
1N/Asettings were wrong, they mention locales your system has never heard
1N/Aof, or the locale installation in your system has problems (for example,
1N/Asome system files are broken or missing). There are quick and temporary
1N/Afixes to these problems, as well as more thorough and lasting fixes.
1N/A=head2 Temporarily fixing locale problems
1N/AThe two quickest fixes are either to render Perl silent about any
1N/Alocale inconsistencies or to run Perl under the default locale "C".
1N/APerl's moaning about locale problems can be silenced by setting the
1N/Aenvironment variable PERL_BADLANG to a zero value, for example "0".
1N/AThis method really just sweeps the problem under the carpet: you tell
1N/APerl to shut up even when Perl sees that something is wrong. Do not
1N/Abe surprised if later something locale-dependent misbehaves.
1N/APerl can be run under the "C" locale by setting the environment
1N/Avariable LC_ALL to "C". This method is perhaps a bit more civilized
1N/Athan the PERL_BADLANG approach, but setting LC_ALL (or
1N/Aother locale variables) may affect other programs as well, not just
1N/APerl. In particular, external programs run from within Perl will see
1N/Athese changes. If you make the new settings permanent (read on), all
1N/Aprograms you run see the changes. See L<ENVIRONMENT> for
1N/Athe full list of relevant environment variables and L<USING LOCALES>
1N/Afor their effects in Perl. Effects in other programs are
1N/Aeasily deducible. For example, the variable LC_COLLATE may well affect
1N/Ayour B<sort> program (or whatever the program that arranges `records'
1N/Aalphabetically in your system is called).
1N/AYou can test out changing these variables temporarily, and if the
1N/Anew settings seem to help, put those settings into your shell startup
1N/Afiles. Consult your local documentation for the exact details. For in
1N/ABourne-like shells (B<sh>, B<ksh>, B<bash>, B<zsh>):
1N/Adiscussed above. We decided to try that instead of the above faulty
1N/Alocale "En_US"--and in Cshish shells (B<csh>, B<tcsh>)
1N/Aor if you have the "env" application you can do in any shell
1N/AIf you do not know what shell you have, consult your local
1N/Ahelpdesk or the equivalent.
1N/A=head2 Permanently fixing locale problems
1N/AThe slower but superior fixes are when you may be able to yourself
1N/Afix the misconfiguration of your own environment variables. The
1N/Amis(sing)configuration of the whole system's locales usually requires
1N/Athe help of your friendly system administrator.
1N/AFirst, see earlier in this document about L<Finding locales>. That tells
1N/Ahow to find which locales are really supported--and more importantly,
1N/Ainstalled--on your system. In our example error message, environment
1N/Avariables affecting the locale are listed in the order of decreasing
1N/Aimportance (and unset variables do not matter). Therefore, having
1N/ALC_ALL set to "En_US" must have been the bad choice, as shown by the
1N/Aerror message. First try fixing locale settings listed first.
1N/ASecond, if using the listed commands you see something B<exactly>
1N/A(prefix matches do not count and case usually counts) like "En_US"
1N/Awithout the quotes, then you should be okay because you are using a
1N/Alocale name that should be installed and available in your system.
1N/AIn this case, see L<Permanently fixing your system's locale configuration>.
1N/A=head2 Permanently fixing your system's locale configuration
1N/AThis is when you see something like:
1N/A perl: warning: Please check that your locale settings:
1N/A are supported and installed on your system.
1N/Abut then cannot see that "En_US" listed by the above-mentioned
1N/Athe same. In this case, try running under a locale
1N/Athat you can list and which somehow matches what you tried. The
1N/Arules for matching locale names are a bit vague because
1N/Astandardization is weak in this area. See again the
1N/AL<Finding locales> about general rules.
1N/A=head2 Fixing system locale configuration
1N/AContact a system administrator (preferably your own) and report the exact
1N/Aerror message you get, and ask them to read this same documentation you
1N/Aare now reading. They should be able to check whether there is something
1N/Awrong with the locale configuration of the system. The L<Finding locales>
1N/Asection is unfortunately a bit vague about the exact commands and places
1N/Abecause these things are not that standardized.
1N/A=head2 The localeconv function
1N/AThe POSIX::localeconv() function allows you to get particulars of the
1N/Alocale-dependent numeric formatting information specified by the current
1N/AC<LC_NUMERIC> and C<LC_MONETARY> locales. (If you just want the name of
1N/Athe current locale for a particular category, use POSIX::setlocale()
1N/Awith a single parameter--see L<The setlocale function>.)
1N/A use POSIX qw(locale_h);
1N/A # Get a reference to a hash of locale-dependent info
1N/A $locale_values = localeconv();
1N/A # Output sorted list of the values
1N/A for (sort keys %$locale_values) {
1N/A printf "%-20s = %s\n", $_, $locale_values->{$_}
1N/Alocaleconv() takes no arguments, and returns B<a reference to> a hash.
1N/AThe keys of this hash are variable names for formatting, such as
1N/AC<decimal_point> and C<thousands_sep>. The values are the
1N/Aexample listing the categories an implementation might be expected to
1N/Aprovide; some provide more and others fewer. You don't need an
1N/Aexplicit C<use locale>, because localeconv() always observes the
1N/AHere's a simple-minded example program that rewrites its command-line
1N/Aparameters as integers correctly formatted in the current locale:
1N/A # See comments in previous example
1N/A use POSIX qw(locale_h);
1N/A # Get some of locale's numeric formatting parameters
1N/A my ($thousands_sep, $grouping) =
1N/A @{localeconv()}{'thousands_sep', 'grouping'};
1N/A # Apply defaults if values are missing
1N/A $thousands_sep = ',' unless $thousands_sep;
1N/A # grouping and mon_grouping are packed lists
1N/A # of small integers (characters) telling the
1N/A # grouping (thousand_seps and mon_thousand_seps
1N/A # being the group dividers) of numbers and
1N/A # monetary quantities. The integers' meanings:
1N/A # 255 means no more grouping, 0 means repeat
1N/A # the previous grouping, 1-254 means use that
1N/A # as the current grouping. Grouping goes from
1N/A # right to left (low to high digits). In the
1N/A # below we cheat slightly by never using anything
1N/A # else than the first grouping (whatever that is).
1N/A @grouping = unpack("C*", $grouping);
1N/A # Format command line params for current locale
1N/A $_ = int; # Chop non-integer part
1N/A s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
1N/A=head2 I18N::Langinfo
1N/AAnother interface for querying locale-dependent information is the
1N/AI18N::Langinfo::langinfo() function, available at least in UNIX-like
1N/AThe following example will import the langinfo() function itself and
1N/Athree constants to be used as arguments to langinfo(): a constant for
1N/Athe abbreviated first day of the week (the numbering starts from
1N/ASunday = 1) and two more constants for the affirmative and negative
1N/Aanswers for a
yes/no question in the current locale.
1N/A use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
1N/A my ($abday_1, $yesstr, $nostr) = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
1N/A print "$abday_1? [$yesstr/$nostr] ";
1N/AIn other words, in the "C" (or English) locale the above will probably
1N/Aprint something like:
1N/ASee L<I18N::Langinfo> for more information.
1N/A=head1 LOCALE CATEGORIES
1N/AThe following subsections describe basic locale categories. Beyond these,
1N/Asome combination categories allow manipulation of more than one
1N/Abasic category at a time. See L<"ENVIRONMENT"> for a discussion of these.
1N/A=head2 Category LC_COLLATE: Collation
1N/AIn the scope of S<C<use locale>>, Perl looks to the C<LC_COLLATE>
1N/Aenvironment variable to determine the application's notions on collation
1N/A(ordering) of characters. For example, 'b' follows 'a' in Latin
1N/Aalphabets, but where do 'E<aacute>' and 'E<aring>' belong? And while
1N/A'color' follows 'chocolate' in English, what about in Spanish?
1N/AThe following collations all make sense and you may meet any of them
1N/AHere is a code snippet to tell what "word"
1N/Acharacters are in the current locale, in that locale's order:
1N/A print +(sort grep /\w/, map { chr } 0..255), "\n";
1N/ACompare this with the characters that you see and their order if you
1N/Astate explicitly that the locale should be ignored:
1N/A print +(sort grep /\w/, map { chr } 0..255), "\n";
1N/AThis machine-native collation (which is what you get unless S<C<use
1N/Alocale>> has appeared earlier in the same block) must be used for
1N/Asorting raw binary data, whereas the locale-dependent collation of the
1N/Afirst example is useful for natural text.
1N/AAs noted in L<USING LOCALES>, C<cmp> compares according to the current
1N/Acollation locale when C<use locale> is in effect, but falls back to a
1N/Achar-by-char comparison for strings that the locale says are equal. You
1N/Acan use POSIX::strcoll() if you don't want this fall-back:
1N/A use POSIX qw(strcoll);
1N/A !strcoll("space and case ignored", "SpaceAndCaseIgnored");
1N/A$equal_in_locale will be true if the collation locale specifies a
1N/Adictionary-like ordering that ignores space characters completely and
1N/AIf you have a single string that you want to check for "equality in
1N/Alocale" against several others, you might think you could gain a little
1N/Aefficiency by using POSIX::strxfrm() in conjunction with C<eq>:
1N/A use POSIX qw(strxfrm);
1N/A $xfrm_string = strxfrm("Mixed-case string");
1N/A print "locale collation ignores spaces\n"
1N/A if $xfrm_string eq strxfrm("Mixed-casestring");
1N/A print "locale collation ignores hyphens\n"
1N/A if $xfrm_string eq strxfrm("Mixedcase string");
1N/A print "locale collation ignores case\n"
1N/A if $xfrm_string eq strxfrm("mixed-case string");
1N/Astrxfrm() takes a string and maps it into a transformed string for use
1N/Ain char-by-char comparisons against other transformed strings during
1N/Acollation. "Under the hood", locale-affected Perl comparison operators
1N/Acall strxfrm() for both operands, then do a char-by-char
1N/Acomparison of the transformed strings. By calling strxfrm() explicitly
1N/Aand using a non locale-affected comparison, the example attempts to save
1N/Aa couple of transformations. But in fact, it doesn't save anything: Perl
1N/Astring the first time it's needed in a comparison, then keeps this version around
1N/Ain case it's needed again. An example rewritten the easy way with
1N/AC<cmp> runs just about as fast. It also copes with null characters
1N/Aembedded in strings; if you call strxfrm() directly, it treats the first
1N/Anull it finds as a terminator. don't expect the transformed strings
1N/Ait produces to be portable across systems--or even from one revision
1N/Aof your operating system to the next. In short, don't call strxfrm()
1N/Adirectly: let Perl do it for you.
1N/ANote: C<use locale> isn't shown in some of these examples because it isn't
1N/Aneeded: strcoll() and strxfrm() exist only to generate locale-dependent
1N/Aresults, and so always obey the current C<LC_COLLATE> locale.
1N/A=head2 Category LC_CTYPE: Character Types
1N/AIn the scope of S<C<use locale>>, Perl obeys the C<LC_CTYPE> locale
1N/Asetting. This controls the application's notion of which characters are
1N/Aalphabetic. This affects Perl's C<\w> regular expression metanotation,
1N/Awhich stands for alphanumeric characters--that is, alphabetic,
1N/Anumeric, and including other special characters such as the underscore or
1N/Ahyphen. (Consult L<perlre> for more information about
1N/Aregular expressions.) Thanks to C<LC_CTYPE>, depending on your locale
1N/Asetting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and
1N/A'E<oslash>' may be understood as C<\w> characters.
1N/AThe C<LC_CTYPE> locale also provides the map used in transliterating
1N/Acharacters between lower and uppercase. This affects the case-mapping
1N/Afunctions--lc(), lcfirst, uc(), and ucfirst(); case-mapping
1N/Ainterpolation with C<\l>, C<\L>, C<\u>, or C<\U> in double-quoted strings
1N/Aand C<s///> substitutions; and case-independent regular expression
1N/Apattern matching using the C<i> modifier.
1N/AFinally, C<LC_CTYPE> affects the POSIX character-class test
1N/Afunctions--isalpha(), islower(), and so on. For example, if you move
1N/Afrom the "C" locale to a 7-bit Scandinavian one, you may find--possibly
1N/Ato your surprise--that "|" moves from the ispunct() class to isalpha().
1N/AB<Note:> A broken or malicious C<LC_CTYPE> locale definition may result
1N/Ain clearly ineligible characters being considered to be alphanumeric by
1N/Ayour application. For strict matching of (mundane) letters and
1N/Adigits--for example, in command strings--locale-aware applications
1N/Ashould use C<\w> inside a C<no locale> block. See L<"SECURITY">.
1N/A=head2 Category LC_NUMERIC: Numeric Formatting
1N/AIn the scope of S<C<use locale>>, Perl obeys the C<LC_NUMERIC> locale
1N/Ainformation, which controls an application's idea of how numbers should
1N/Abe formatted for human readability by the printf(), sprintf(), and
1N/Awrite() functions. String-to-numeric conversion by the POSIX::strtod()
1N/Afunction is also affected. In most implementations the only effect is to
1N/Achange the character used for the decimal point--perhaps from '.' to ','.
1N/AThese functions aren't aware of such niceties as thousands separation and
1N/Aso on. (See L<The localeconv function> if you care about these things.)
1N/AOutput produced by print() is also affected by the current locale: it
1N/Adepends on whether C<use locale> or C<no locale> is in effect, and
1N/Acorresponds to what you'd get from printf() in the "C" locale. The
1N/Asame is true for Perl's internal conversions between numeric and
1N/A use POSIX qw(strtod);
1N/A $n = 5/2; # Assign numeric 2.5 to $n
1N/A $a = " $n"; # Locale-dependent conversion to string
1N/A print "half five is $n\n"; # Locale-dependent output
1N/A printf "half five is %g\n", $n; # Locale-dependent output
1N/A print "DECIMAL POINT IS COMMA\n"
1N/A if $n == (strtod("2,5"))[0]; # Locale-dependent conversion
1N/ASee also L<I18N::Langinfo> and C<RADIXCHAR>.
1N/A=head2 Category LC_MONETARY: Formatting of monetary amounts
1N/AThe C standard defines the C<LC_MONETARY> category, but no function
1N/Athat is affected by its contents. (Those with experience of standards
1N/Acommittees will recognize that the working group decided to punt on the
1N/Aissue.) Consequently, Perl takes no notice of it. If you really want
1N/Ato use C<LC_MONETARY>, you can query its contents--see
1N/AL<The localeconv function>--and use the information that it returns in your
1N/Aapplication's own formatting of currency amounts. However, you may well
1N/Afind that the information, voluminous and complex though it may be, still
1N/Adoes not quite meet your requirements: currency formatting is a hard nut
1N/ASee also L<I18N::Langinfo> and C<CRNCYSTR>.
1N/AOutput produced by POSIX::strftime(), which builds a formatted
1N/Ahuman-readable
date/time string, is affected by the current C<LC_TIME>
1N/Alocale. Thus, in a French locale, the output produced by the C<%B>
1N/Aformat element (full month name) for the first month of the year would
1N/Abe "janvier". Here's how to get a list of long month names in the
1N/A use POSIX qw(strftime);
1N/A $long_month_name[$_] =
1N/A strftime("%B", 0, 0, 0, 1, $_, 96);
1N/ANote: C<use locale> isn't needed in this example: as a function that
1N/Aexists only to generate locale-dependent results, strftime() always
1N/Aobeys the current C<LC_TIME> locale.
1N/ASee also L<I18N::Langinfo> and C<ABDAY_1>
..C<ABDAY_7>, C<DAY_1>
..C<DAY_7>,
1N/AC<ABMON_1>
..C<ABMON_12>, and C<ABMON_1>
..C<ABMON_12>.
1N/A=head2 Other categories
1N/AThe remaining locale category, C<LC_MESSAGES> (possibly supplemented
1N/Aby others in particular implementations) is not currently used by
1N/APerl--except possibly to affect the behavior of library functions
1N/Acalled by extensions outside the standard Perl distribution and by the
1N/Aoperating system and its utilities. Note especially that the string
1N/Avalue of C<$!> and the error messages given by external utilities may
1N/Abe changed by C<LC_MESSAGES>. If you want to have portable error
1N/Acodes, use C<%!>. See L<Errno>.
1N/AAlthough the main discussion of Perl security issues can be found in
1N/AL<perlsec>, a discussion of Perl's locale handling would be incomplete
1N/Aif it did not draw your attention to locale-dependent security issues.
1N/ALocales--particularly on systems that allow unprivileged users to
1N/Abuild their own locales--are untrustworthy. A malicious (or just plain
1N/Abroken) locale can make a locale-aware application give unexpected
1N/Aresults. Here are a few possibilities:
1N/ARegular expression checks for safe file names or mail addresses using
1N/AC<\w> may be spoofed by an C<LC_CTYPE> locale that claims that
1N/Acharacters such as "E<gt>" and "|" are alphanumeric.
1N/AString interpolation with case-mapping, as in, say, C<$dest =
1N/A"C:\U$name.$ext">, may produce dangerous results if a bogus LC_CTYPE
1N/Acase-mapping table is in effect.
1N/AA sneaky C<LC_COLLATE> locale could result in the names of students with
1N/A"D" grades appearing ahead of those with "A"s.
1N/AAn application that takes the trouble to use information in
1N/AC<LC_MONETARY> may format debits as if they were credits and vice versa
1N/Aif that locale has been subverted. Or it might make payments in US
1N/Adollars instead of Hong Kong dollars.
1N/AThe date and day names in dates formatted by strftime() could be
1N/Amanipulated to advantage by a malicious user able to subvert the
1N/AC<LC_DATE> locale. ("Look--it says I wasn't in the building on
1N/ASuch dangers are not peculiar to the locale system: any aspect of an
1N/Aapplication's environment which may be modified maliciously presents
1N/Asimilar challenges. Similarly, they are not specific to Perl: any
1N/Aprogramming language that allows you to write programs that take
1N/Aaccount of their environment exposes you to these issues.
1N/APerl cannot protect you from all possibilities shown in the
1N/Aexamples--there is no substitute for your own vigilance--but, when
1N/AC<use locale> is in effect, Perl uses the tainting mechanism (see
1N/AL<perlsec>) to mark string results that become locale-dependent, and
1N/Awhich may be untrustworthy in consequence. Here is a summary of the
1N/Atainting behavior of operators and functions that may be affected by
1N/AB<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):
1N/AB<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
1N/AResult string containing interpolated material is tainted if
1N/AC<use locale> is in effect.
1N/AB<Matching operator> (C<m//>):
1N/ASubpatterns, either delivered as a list-context result or as $1 etc.
1N/Aare tainted if C<use locale> is in effect, and the subpattern regular
1N/Aexpression contains C<\w> (to match an alphanumeric character), C<\W>
1N/A(non-alphanumeric character), C<\s> (white-space character), or C<\S>
1N/A(non white-space character). The matched-pattern variable, $&, $`
1N/A(pre-match), $' (post-match), and $+ (last match) are also tainted if
1N/AC<use locale> is in effect and the regular expression contains C<\w>,
1N/AC<\W>, C<\s>, or C<\S>.
1N/AB<Substitution operator> (C<s///>):
1N/AHas the same behavior as the match operator. Also, the left
1N/Aoperand of C<=~> becomes tainted when C<use locale> in effect
1N/Aif modified as a result of a substitution based on a regular
1N/Aexpression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
1N/Acase-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
1N/AB<Output formatting functions> (printf() and write()):
1N/AResults are never tainted because otherwise even output from print,
1N/Afor example C<print(1/7)>, should be tainted if C<use locale> is in
1N/AB<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()):
1N/AResults are tainted if C<use locale> is in effect.
1N/AB<POSIX locale-dependent functions> (localeconv(), strcoll(),
1N/Astrftime(), strxfrm()):
1N/AResults are never tainted.
1N/AB<POSIX character class tests> (isalnum(), isalpha(), isdigit(),
1N/Aisgraph(), islower(), isprint(), ispunct(), isspace(), isupper(),
1N/AThree examples illustrate locale-dependent tainting.
1N/AThe first program, which ignores its locale, won't run: a value taken
1N/Adirectly from the command line may not be used to name an output file
1N/Awhen taint checks are enabled.
1N/A # Run with taint checking
1N/A # Command line sanity check omitted...
1N/A $tainted_output_file = shift;
1N/A open(F, ">$tainted_output_file")
1N/A or warn "Open of $untainted_output_file failed: $!\n";
1N/AThe program can be made to run by "laundering" the tainted value through
1N/Aa regular expression: the second example--which still ignores locale
1N/Ainformation--runs, creating the file named on its command line
1N/A $tainted_output_file = shift;
1N/A $tainted_output_file =~ m%[\w/]+%;
1N/A $untainted_output_file = $&;
1N/A open(F, ">$untainted_output_file")
1N/A or warn "Open of $untainted_output_file failed: $!\n";
1N/ACompare this with a similar but locale-aware program:
1N/A $tainted_output_file = shift;
1N/A $tainted_output_file =~ m%[\w/]+%;
1N/A $localized_output_file = $&;
1N/A open(F, ">$localized_output_file")
1N/A or warn "Open of $localized_output_file failed: $!\n";
1N/AThis third program fails to run because $& is tainted: it is the result
1N/Aof a match involving C<\w> while C<use locale> is in effect.
1N/AA string that can suppress Perl's warning about failed locale settings
1N/Aat startup. Failure can occur if the locale support in the operating
1N/Asystem is lacking (broken) in some way--or if you mistyped the name of
1N/Aa locale when you set up your environment. If this environment
1N/Avariable is absent, or has a value that does not evaluate to integer
1N/Azero--that is, "0" or ""-- Perl will complain about locale setting
1N/AB<NOTE>: PERL_BADLANG only gives you a way to hide the warning message.
1N/AThe message tells about some problem in your system's locale support,
1N/Aand you should investigate what the problem is.
1N/AThe following environment variables are not specific to Perl: They are
1N/Apart of the standardized (ISO C, XPG4, POSIX
1.c) setlocale() method
1N/Afor controlling an application's opinion on data.
1N/AC<LC_ALL> is the "override-all" locale environment variable. If
1N/Aset, it overrides all the rest of the locale environment variables.
1N/AB<NOTE>: C<LANGUAGE> is a GNU extension, it affects you only if you
1N/Aare using the GNU libc. This is the case if you are using
e.g. Linux.
1N/AIf you are using "commercial" UNIXes you are most probably I<not>
1N/Ausing GNU libc and you can ignore C<LANGUAGE>.
1N/AHowever, in the case you are using C<LANGUAGE>: it affects the
1N/Alanguage of informational, warning, and error messages output by
1N/Acommands (in other words, it's like C<LC_MESSAGES>) but it has higher
1N/Apriority than L<LC_ALL>. Moreover, it's not a single value but
1N/Ainstead a "path" (":"-separated list) of I<languages> (not locales).
1N/ASee the GNU C<gettext> library documentation for more information.
1N/AIn the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type
1N/Alocale. In the absence of both C<LC_ALL> and C<LC_CTYPE>, C<LANG>
1N/Achooses the character type locale.
1N/AIn the absence of C<LC_ALL>, C<LC_COLLATE> chooses the collation
1N/A(sorting) locale. In the absence of both C<LC_ALL> and C<LC_COLLATE>,
1N/AC<LANG> chooses the collation locale.
1N/AIn the absence of C<LC_ALL>, C<LC_MONETARY> chooses the monetary
1N/Aformatting locale. In the absence of both C<LC_ALL> and C<LC_MONETARY>,
1N/AC<LANG> chooses the monetary formatting locale.
1N/AIn the absence of C<LC_ALL>, C<LC_NUMERIC> chooses the numeric format
1N/Alocale. In the absence of both C<LC_ALL> and C<LC_NUMERIC>, C<LANG>
1N/Achooses the numeric format.
1N/AIn the absence of C<LC_ALL>, C<LC_TIME> chooses the date and time
1N/Aformatting locale. In the absence of both C<LC_ALL> and C<LC_TIME>,
1N/AC<LANG> chooses the date and time formatting locale.
1N/AC<LANG> is the "catch-all" locale environment variable. If it is set, it
1N/Ais used as the last resort after the overall C<LC_ALL> and the
1N/Acategory-specific C<LC_...>.
1N/A=head2 Backward compatibility
1N/AVersions of Perl prior to 5.004 B<mostly> ignored locale information,
1N/Agenerally behaving as if something similar to the C<"C"> locale were
1N/Aalways in force, even if the program environment suggested otherwise
1N/A(see L<The setlocale function>). By default, Perl still behaves this
1N/Away for backward compatibility. If you want a Perl application to pay
1N/Aattention to locale information, you B<must> use the S<C<use locale>>
1N/Apragma (see L<The use locale pragma>) to instruct it to do so.
1N/AVersions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE>
1N/Ainformation if available; that is, C<\w> did understand what
1N/Awere the letters according to the locale environment variables.
1N/AThe problem was that the user had no control over the feature:
1N/Aif the C library supported locales, Perl used them.
1N/A=head2 I18N:Collate obsolete
1N/AIn versions of Perl prior to 5.004, per-locale collation was possible
1N/Ausing the C<I18N::Collate> library module. This module is now mildly
1N/Aobsolete and should be avoided in new applications. The C<LC_COLLATE>
1N/Afunctionality is now integrated into the Perl core language: One can
1N/Ause locale-specific scalar data completely normally with C<use locale>,
1N/Aso there is no longer any need to juggle with the scalar references of
1N/A=head2 Sort speed and memory use impacts
1N/AComparing and sorting by locale is usually slower than the default
1N/Asorting; slow-downs of two to four times have been observed. It will
1N/Aalso consume more memory: once a Perl scalar variable has participated
1N/Ain any string comparison or sorting operation obeying the locale
1N/Acollation rules, it will take 3-15 times more memory than before. (The
1N/Aexact multiplier depends on the string's contents, the operating system
1N/Aand the locale.) These downsides are dictated more by the operating
1N/Asystem's implementation of the locale system than by Perl.
1N/A=head2 write() and LC_NUMERIC
1N/AFormats are the only part of Perl that unconditionally use information
1N/Afrom a program's locale; if a program's environment specifies an
1N/ALC_NUMERIC locale, it is always used to specify the decimal point
1N/Acharacter in formatted output. Formatted output cannot be controlled by
1N/AC<use locale> because the pragma is tied to the block structure of the
1N/Aprogram, and, for historical reasons, formats exist outside that block
1N/A=head2 Freely available locale definitions
1N/AThere is a large collection of locale definitions at
1N/Aunsupported, and is not claimed to be fit for any purpose. If your
1N/Asystem allows installation of arbitrary locales, you may find the
1N/Adefinitions useful as they are, or as a basis for the development of
1N/A"Internationalization" is often abbreviated as B<i18n> because its first
1N/Aand last letters are separated by eighteen others. (You may guess why
1N/Athe internalin ... internaliti ... i18n tends to get abbreviated.) In
1N/Athe same way, "localization" is often abbreviated to B<l10n>.
1N/A=head2 An imperfect standard
1N/AInternationalization, as defined in the C and POSIX standards, can be
1N/Acriticized as incomplete, ungainly, and having too large a granularity.
1N/A(Locales apply to a whole process, when it would arguably be more useful
1N/Ato have them apply to a single thread, window group, or whatever.) They
1N/Aalso have a tendency, like standards groups, to divide the world into
1N/Anations, when we all know that the world can equally well be divided
1N/Ainto bankers, bikers, gamers, and so on. But, for now, it's the only
1N/Astandard we've got. This may be construed as a bug.
1N/A=head1 Unicode and UTF-8
1N/AThe support of Unicode is new starting from Perl version 5.6, and
1N/Amore fully implemented in the version 5.8. See L<perluniintro> and
1N/AL<perlunicode> for more details.
1N/AUsually locale settings and Unicode do not affect each other, but
1N/A=head2 Broken systems
1N/AIn certain systems, the operating system's locale support
1N/Ais broken and cannot be fixed or used by Perl. Such deficiencies can
1N/Aand will result in mysterious hangs
and/or Perl core dumps when the
1N/AC<use locale> is in effect. When confronted with such a system,
1N/Aplease report in excruciating detail to <F<perlbug@perl.org>>, and
1N/Acomplain to your vendor: bug fixes may exist for these problems
1N/Ain your operating system. Sometimes such bug fixes are called an
1N/Aoperating system upgrade.
1N/AL<I18N::Langinfo>, L<perluniintro>, L<perlunicode>, L<open>,
1N/ADunlop, assisted by the perl5-porters. Prose worked over a bit by
1N/ALast update: Thu Jun 11 08:44:13 MDT 1998