=head1 DESCRIPTION
Perl supports language-specific notions of data such as "is this a
-letter", "what is the upper-case equivalent of this letter", and "which
+letter", "what is the uppercase equivalent of this letter", and "which
of these letters comes first". These are important issues, especially
for languages other than English - but also for English: it would be
very naE<iuml>ve to think that C<A-Za-z> defines all the "letters". Perl
B<NOTE>: This feature is new in Perl 5.004, and does not apply unless an
application specifically requests it - see L<Backward compatibility>.
+The one exception is that write() now B<always> uses the current locale
+- see L<"NOTES">.
=head1 PREPARING TO USE LOCALES
If you want a Perl application to process and present your data
according to a particular locale, the application code should include
-the S<C<use locale>> pragma (see L<The use locale Pragma>) where
+the S<C<use locale>> pragma (see L<The use locale pragma>) where
appropriate, and B<at least one> of the following must be true:
=over 4
category's locale is returned to the default specified by the
corresponding environment variables. Generally, this results in a
return to the default which was in force when Perl started up: changes
-to the environment made by the application after start-up may or may not
+to the environment made by the application after startup may or may not
be noticed, depending on the implementation of your system's C library.
If the second argument does not correspond to a valid locale, the locale
for the category is not changed, and the function returns I<undef>.
For further information about the categories, consult L<setlocale(3)>.
+
+=head2 Finding locales
+
For the locales available in your system, also consult L<setlocale(3)>
and see whether it leads you to the list of the available locales
(search for the I<SEE ALSO> section). If that fails, try the following
english.iso88591 german.iso88591 russian.iso88595
Sadly, even though the calling interface for setlocale() has been
-standardized, the names of the locales and the directories where
-the configuration is, have not. The basic form of the name is
-I<language_country/territory>B<.>I<codeset>, but the
-latter parts are not always present.
+standardized, the names of the locales and the directories where the
+configuration is, have not. The basic form of the name is
+I<language_country/territory>B<.>I<codeset>, but the latter parts
+after the I<language> are not always present. The I<language> and the
+I<country> are usually from the standards B<ISO 3166> and B<ISO 639>,
+respectively, the two-letter abbreviations for the countries and the
+languages of the world. The I<codeset> part often mentions some B<ISO
+8859> character set, the Latin codesets. For example the C<ISO
+8859-1> is the so-called "Western codeset" that can be used to encode
+most of the Western European languages. Again, sadly, as you can see,
+there are several ways to write even the name of that one standard.
Two special locales are worth particular mention: "C" and "POSIX".
Currently these are effectively the same locale: the difference is
POSIX-conformant), so use "C" when you need explicitly to specify this
default locale.
+=head2 LOCALE PROBLEMS
+
+You may meet the following warning message at Perl startup:
+
+ perl: warning: Setting locale failed.
+ perl: warning: Please check that your locale settings:
+ LC_ALL = "En_US",
+ LANG = (unset)
+ are supported and installed on your system.
+ perl: warning: Falling back to the standard locale ("C").
+
+This means that your locale settings were that LC_ALL equals "En_US"
+and LANG exists but has no value. Perl tried to believe you but it
+could not. Instead Perl gave up and fell back to the "C" locale, the
+default locale that is supposed to work no matter what. This usually
+means either or both of the two problems: either your locale settings
+were wrong, they talk of locales your system has never heard of, or
+that the locale installation in your system has problems, for example
+some system files are broken or missing. For the problems there are
+quick and temporary fixes and more thorough and lasting fixes.
+
+=head2 Temporarily fixing locale problems
+
+The two quickest fixes are either to make Perl be silent about any
+locale inconsistencies or to run Perl under the default locale "C".
+
+Perl's moaning about locale problems can be silenced by setting the
+environment variable PERL_BADLANG to a non-zero value, for example
+"1". This method really just sweeps the problem under the carpet: you
+tell Perl to shut up even when Perl sees that something is wrong. Do
+not be surprised if later something locale-dependent works funny.
+
+Perl can be run under the "C" locale by setting the environment
+variable LC_ALL to "C". This method is perhaps a bit more civilised
+than the PERL_BADLANG one but please note that setting the LC_ALL (or
+the other locale variables) may affect also other programs, not just
+Perl. Especially external programs run from within Perl will see
+these changes. If you make the new settings permanent (read on), all
+the programs you run will see the changes. See L<ENVIRONMENT> for for
+the full list of all the environment variables and L<USING LOCALES>
+for their effects in Perl. The effects in other programs are quite
+easily deducible: for example the variable LC_COLLATE may well affect
+your "sort" program (or whatever the program that arranges `records'
+alphabetically in your system is called).
+
+You can first try out changing these variables temporarily and if the
+new settings seem to help then put the settings into the startup files
+of your environment. Please consult your local documentation for the
+exact details but very shortly for UNIXish systems: in Bourneish
+shells (sh, ksh, bash, zsh) for example
+
+ LC_ALL=en_US.ISO8859-1
+ export LC_ALL
+
+We assume here that we saw with the above discussed commands the
+locale "en_US.ISO8859-1" and decided to try that instead of the above
+faulty locale "En_US" -- and in Cshish shells (csh, tcsh)
+
+ setenv LC_ALL en_US.ISO8859-1
+
+If you do not know what shell you have, please consult your local
+helpdesk or the equivalent.
+
+=head2 Permanently fixing locale problems
+
+Then the slower but better fixes: the misconfiguration of your own
+environment variables you may be able to fix yourself; the
+mis(sing)configuration of the whole system's locales usually requires
+the help of your friendly system administrator.
+
+First, see earlier in this document about L<Finding locales>. That
+tells how you can find which locales really are supported and more
+importantly, installed, in your system. In our example error message
+the environment variables affecting the locale are listed in the order
+of decreasing importance and unset variables do not matter, therefore
+in the above error message the LC_ALL being "En_US" must have been the
+bad choice. Always try fixing first the locale settings listed first.
+
+Second, if you see with the listed commands something B<exactly> (for
+example prefix matches do not count and case usually matters) like
+"En_US" (without the quotes), then you should be okay because you are
+using a locale name that should be installed and available in your
+system. In this case skip forward to L<Fixing the system locale
+configuration>.
+
+=head2 Permantently fixing your locale configuration
+
+This is the case when for example you see
+
+ perl: warning: Please check that your locale settings:
+ LC_ALL = "En_US",
+ LANG = (unset)
+ are supported and installed on your system.
+
+but then cannot see that "En_US" listed by the above-mentioned
+commands. You may see things like "en_US.ISO8859-1" but that is not
+the same thing. In this case you might try running under a locale
+that you could list and somehow matches with what you tried. The
+rules for matching locale names are a bit vague because
+standardisation is weak in this area. See again the L<Finding
+locales> about the general rules.
+
+=head2 Permanently fixing the system locale configuration
+
+Please contact your system administrator and tell her the exact error
+message you get and ask her to read this same documentation you are
+now reading. She should be able to check whether there is something
+wrong with the locale configuration of the system. The L<Finding
+locales> section is unfortunately a bit vague about the exact commands
+and places because these things are not that standardised.
+
=head2 The localeconv function
The POSIX::localeconv() function allows you to get particulars of the
$equal_in_locale will be true if the collation locale specifies a
dictionary-like ordering which ignores space characters completely, and
-which folds case. Alternatively, you can use this idiom:
-
- use locale;
- $s_a = "space and case ignored";
- $s_b = "SpaceAndCaseIgnored";
- $equal_in_locale = $s_a ge $s_b && $s_a le $s_b;
-
-which works because neither C<ne> nor C<ge> falls back to doing a
-byte-by-byte comparison when the operands are equal according to the
-locale. The idiom may be less efficient than using strcoll(), but,
-unlike that function, it is not confused by strings containing embedded
-nulls.
+which folds case.
If you have a single string which you want to check for "equality in
locale" against several others, you might think you could gain a little
comparison of the transformed strings. By calling strxfrm() explicitly,
and using a non locale-affected comparison, the example attempts to save
a couple of transformations. In fact, it doesn't save anything: Perl
-magic (see L<perlguts/Magic>) creates the transformed version of a
+magic (see L<perlguts/Magic Variables>) creates the transformed version of a
string the first time it's needed in a comparison, then keeps it around
in case it's needed again. An example rewritten the easy way with
-C<cmp> runs just about as fast. It also copes with null characters
+C<cmp> runs just about as fast. It also copes with null characters
embedded in strings; if you call strxfrm() directly, it treats the first
-null it finds as a terminator. In short, don't call strxfrm() directly:
-let Perl do it for you.
+null it finds as a terminator. And don't expect the transformed strings
+it produces to be portable across systems - or even from one revision
+of your operating system to the next. In short, don't call strxfrm()
+directly: let Perl do it for you.
Note: C<use locale> isn't shown in some of these examples, as it isn't
needed: strcoll() and strxfrm() exist only to generate locale-dependent
setting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and
'E<oslash>' may be understood as C<\w> characters.
-C<LC_CTYPE> also affects the POSIX character-class test functions -
+The C<LC_CTYPE> locale also provides the map used in transliterating
+characters between lower and uppercase. This affects the case-mapping
+functions - lc(), lcfirst, uc() and ucfirst(); case-mapping
+interpolation with C<\l>, C<\L>, C<\u> or C<\U> in double-quoted strings
+and in C<s///> substitutions; and case-independent regular expression
+pattern matching using the C<i> modifier.
+
+Finally, C<LC_CTYPE> affects the POSIX character-class test functions -
isalpha(), islower() and so on. For example, if you move from the "C"
locale to a 7-bit Scandinavian one, you may find - possibly to your
surprise - that "|" moves from the ispunct() class to isalpha().
=item *
+String interpolation with case-mapping, as in, say, C<$dest =
+"C:\U$name.$ext">, may produce dangerous results if a bogus LC_CTYPE
+case-mapping table is in effect.
+
+=item *
+
If the decimal point character in the C<LC_NUMERIC> locale is
surreptitiously changed from a dot to a comma, C<sprintf("%g",
0.123456e3)> produces a string result of "123,456". Many people would
Scalar true/false (or less/equal/greater) result is never tainted.
+=item B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
+
+Result string containing interpolated material is tainted if
+C<use locale> is in effect.
+
=item B<Matching operator> (C<m//>):
Scalar true/false result never tainted.
Subpatterns, either delivered as an array-context result, or as $1 etc.
are tainted if C<use locale> is in effect, and the subpattern regular
-expression contains C<\w> (to match an alphanumeric character). The
-matched pattern variable, $&, is also tainted if C<use locale> is in
-effect, and the regular expression contains C<\w>.
+expression contains C<\w> (to match an alphanumeric character), C<\W>
+(non-alphanumeric character), C<\s> (white-space character), or C<\S>
+(non white-space character). The matched pattern variable, $&, $`
+(pre-match), $' (post-match), and $+ (last match) are also tainted if
+C<use locale> is in effect and the regular expression contains C<\w>,
+C<\W>, C<\s>, or C<\S>.
=item B<Substitution operator> (C<s///>):
-Has the same behavior as the match operator. When C<use locale> is
-in effect, he left operand of C<=~> will become tainted if it is
-modified as a result of a substitution based on a regular expression
-match involving C<\w>.
+Has the same behavior as the match operator. Also, the left
+operand of C<=~> becomes tainted when C<use locale> in effect,
+if it is modified as a result of a substitution based on a regular
+expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
+case-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
=item B<In-memory formatting function> (sprintf()):
Three examples illustrate locale-dependent tainting.
The first program, which ignores its locale, won't run: a value taken
-directly from the command-line may not be used to name an output file
+directly from the command line may not be used to name an output file
when taint checks are enabled.
#/usr/local/bin/perl -T
# Run with taint checking
- # Command-line sanity check omitted...
+ # Command line sanity check omitted...
$tainted_output_file = shift;
open(F, ">$tainted_output_file")
The program can be made to run by "laundering" the tainted value through
a regular expression: the second example - which still ignores locale
-information - runs, creating the file named on its command-line
+information - runs, creating the file named on its command line
if it can.
#/usr/local/bin/perl -T
=item PERL_BADLANG
A string that can suppress Perl's warning about failed locale settings
-at start-up. Failure can occur if the locale support in the operating
-system is lacking (broken) is some way - or if you mistyped the name of
+at startup. Failure can occur if the locale support in the operating
+system is lacking (broken) in some way - or if you mistyped the name of
a locale when you set up your environment. If this environment variable
is absent, or has a value which does not evaluate to integer zero - that
is "0" or "" - Perl will complain about locale setting failures.
environment suggested otherwise. By default, Perl still behaves this
way so as to maintain backward compatibility. If you want a Perl
application to pay attention to locale information, you B<must> use
-the S<C<use locale>> pragma (see L<The S<C<use locale>> Pragma>) to
+the S<C<use locale>> pragma (see L<The use locale Pragma>) to
instruct it to do so.
Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE>
and the locale.) These downsides are dictated more by the operating
system's implementation of the locale system than by Perl.
+=head2 write() and LC_NUMERIC
+
+Formats are the only part of Perl which unconditionally use information
+from a program's locale; if a program's environment specifies an
+LC_NUMERIC locale, it is always used to specify the decimal point
+character in formatted output. Formatted output cannot be controlled by
+C<use locale> because the pragma is tied to the block structure of the
+program, and, for historical reasons, formats exist outside that block
+structure.
+
=head2 Freely available locale definitions
There is a large collection of locale definitions at
is broken and cannot be fixed or used by Perl. Such deficiencies can
and will result in mysterious hangs and/or Perl core dumps when the
C<use locale> is in effect. When confronted with such a system,
-please report in excruciating detail to C<perlbug@perl.com>, and
+please report in excruciating detail to <F<perlbug@perl.com>>, and
complain to your vendor: maybe some bug fixes exist for these problems
in your operating system. Sometimes such bug fixes are called an
operating system upgrade.
=head1 SEE ALSO
-L<POSIX (3)/isalnum>, L<POSIX (3)/isalpha>, L<POSIX (3)/isdigit>,
-L<POSIX (3)/isgraph>, L<POSIX (3)/islower>, L<POSIX (3)/isprint>,
-L<POSIX (3)/ispunct>, L<POSIX (3)/isspace>, L<POSIX (3)/isupper>,
-L<POSIX (3)/isxdigit>, L<POSIX (3)/localeconv>, L<POSIX (3)/setlocale>,
-L<POSIX (3)/strcoll>, L<POSIX (3)/strftime>, L<POSIX (3)/strtod>,
+L<POSIX (3)/isalnum>
+
+L<POSIX (3)/isalpha>
+
+L<POSIX (3)/isdigit>
+
+L<POSIX (3)/isgraph>
+
+L<POSIX (3)/islower>
+
+L<POSIX (3)/isprint>,
+
+L<POSIX (3)/ispunct>
+
+L<POSIX (3)/isspace>
+
+L<POSIX (3)/isupper>,
+
+L<POSIX (3)/isxdigit>
+
+L<POSIX (3)/localeconv>
+
+L<POSIX (3)/setlocale>,
+
+L<POSIX (3)/strcoll>
+
+L<POSIX (3)/strftime>
+
+L<POSIX (3)/strtod>,
+
L<POSIX (3)/strxfrm>
=head1 HISTORY
Jarkko Hietaniemi's original F<perli18n.pod> heavily hacked by Dominic
Dunlop, assisted by the perl5-porters.
-Last update: Tue Dec 24 16:43:11 EST 1996
+Last update: Mon Nov 17 22:48:48 EET 1997
projects / p5sagit/p5-mst-13.2.git / blobdiff