Debian Codegraph @

upstream/fedora-44/man1/perllocale.1

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