Debian Codegraph @

upstream/debian-unstable/man1/perllocale.1

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