1=head1 NAME 2 3perlclib - Interacting with standard C library functions 4 5=head1 DESCRIPTION 6 7The perl interpreter is written in C; XS code also expands to C. 8Inevitably, this code will call some functions from the C library, 9C<libc>. This document gives some guidance on interfacing with that 10library. 11 12One thing Perl porters should note is that F<perl> doesn't tend to use that 13much of the C standard library internally; you'll see very little use of, 14for example, the F<ctype.h> functions in there. This is because Perl 15tends to reimplement or abstract standard library functions, so that we 16know exactly how they're going to operate. 17 18=head1 libc functions to avoid 19 20There are many many libc functions. Most of them are fair game to use, 21but some are not. Some of the possible reasons are: 22 23=over 24 25=item * 26 27They likely will interfere with the perl interpreter's functioning, 28such as its bookkeeping, or signal handling, or memory allocation, 29or any number of harmful things. 30 31=item * 32 33They aren't implemented on all platforms, but there is an alternative 34that is. 35 36Or they may be buggy or deprecated on some or all platforms. 37 38=item * 39 40They aren't suitable for multi-threaded operation, but there is an 41alternative that is, and is just as easily usable. 42 43You may not expect your code to ever be used under threads, but code has 44a way of being adapted beyond our initial expectations. If it is just 45as easy to use something that can be used under threads, it's better to 46use that now, just in case. 47 48=item * 49 50In functions that deal with strings, complications may arise because the 51string may be encoded in different ways, for example in UTF-8. For 52these, it is likely better to place the string in a SV and use the Perl 53SV string handling functions that contain extensive logic to deal with 54this. 55 56=item * 57 58In functions that deal with numbers, complications may arise because the 59numbers get too big or small, and what those limits are depends on the 60current platform. Again, the Perl SV numeric data types have extensive 61logic to take care of these kinds of issues. 62 63=item * 64 65They are locale-aware, and your caller may not want this. 66 67=back 68 69The following commentary and tables give some functions in the first 70column that shouldn't be used in C or XS code, with the preferred 71alternative (if any) in the second column. 72 73=head2 Conventions 74 75In the following tables: 76 77=over 3 78 79=item C<~> 80 81marks the function as deprecated; it should not be used regardless. 82 83=item C<t> 84 85is a type. 86 87=item C<p> 88 89is a pointer. 90 91=item C<n> 92 93is a number. 94 95=item C<s> 96 97is a string. 98 99=back 100 101C<sv>, C<av>, C<hv>, etc. represent variables of their respective types. 102 103=head2 File Operations 104 105Instead of the F<stdio.h> functions, you should use the Perl abstraction 106layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*> 107types. Don't forget that with the new PerlIO layered I/O abstraction 108C<FILE*> types may not even be available. See also the C<perlapio> 109documentation for more information about the following functions: 110 111 Instead Of: Use: 112 113 stdin PerlIO_stdin() 114 stdout PerlIO_stdout() 115 stderr PerlIO_stderr() 116 117 fopen(fn, mode) PerlIO_open(fn, mode) 118 freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Dep- 119 recated) 120 fflush(stream) PerlIO_flush(perlio) 121 fclose(stream) PerlIO_close(perlio) 122 123=head2 File Input and Output 124 125 Instead Of: Use: 126 127 fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...) 128 129 [f]getc(stream) PerlIO_getc(perlio) 130 [f]putc(stream, n) PerlIO_putc(perlio, n) 131 ungetc(n, stream) PerlIO_ungetc(perlio, n) 132 133Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly 134different from their C library counterparts: 135 136 fread(p, size, n, stream) PerlIO_read(perlio, buf, numbytes) 137 fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes) 138 139 fputs(s, stream) PerlIO_puts(perlio, s) 140 141There is no equivalent to C<fgets>; one should use C<sv_gets> instead: 142 143 fgets(s, n, stream) sv_gets(sv, perlio, append) 144 145=head2 File Positioning 146 147 Instead Of: Use: 148 149 feof(stream) PerlIO_eof(perlio) 150 fseek(stream, n, whence) PerlIO_seek(perlio, n, whence) 151 rewind(stream) PerlIO_rewind(perlio) 152 153 fgetpos(stream, p) PerlIO_getpos(perlio, sv) 154 fsetpos(stream, p) PerlIO_setpos(perlio, sv) 155 156 ferror(stream) PerlIO_error(perlio) 157 clearerr(stream) PerlIO_clearerr(perlio) 158 159=head2 Memory Management and String Handling 160 161 Instead Of: Use: 162 163 t* p = malloc(n) Newx(p, n, t) 164 t* p = calloc(n, s) Newxz(p, n, t) 165 p = realloc(p, n) Renew(p, n, t) 166 memcpy(dst, src, n) Copy(src, dst, n, t) 167 memmove(dst, src, n) Move(src, dst, n, t) 168 memcpy(dst, src, sizeof(t)) StructCopy(src, dst, t) 169 memset(dst, 0, n * sizeof(t)) Zero(dst, n, t) 170 memzero(dst, 0) Zero(dst, n, char) 171 free(p) Safefree(p) 172 173 strdup(p) savepv(p) 174 strndup(p, n) savepvn(p, n) (Hey, strndup doesn't 175 exist!) 176 177 strstr(big, little) instr(big, little) 178 memmem(big, blen, little, len) ninstr(big, bigend, little, little_end) 179 strcmp(s1, s2) strLE(s1, s2) / strEQ(s1, s2) 180 / strGT(s1,s2) 181 strncmp(s1, s2, n) strnNE(s1, s2, n) / strnEQ(s1, s2, n) 182 183 memcmp(p1, p2, n) memNE(p1, p2, n) 184 !memcmp(p1, p2, n) memEQ(p1, p2, n) 185 186Notice the different order of arguments to C<Copy> and C<Move> than used 187in C<memcpy> and C<memmove>. 188 189Most of the time, though, you'll want to be dealing with SVs internally 190instead of raw C<char *> strings: 191 192 strlen(s) sv_len(sv) 193 strcpy(dt, src) sv_setpv(sv, s) 194 strncpy(dt, src, n) sv_setpvn(sv, s, n) 195 strcat(dt, src) sv_catpv(sv, s) 196 strncat(dt, src) sv_catpvn(sv, s) 197 sprintf(s, fmt, ...) sv_setpvf(sv, fmt, ...) 198 199If you do need raw strings, some platforms have safer interfaces, and 200Perl makes sure a version of these are available on all platforms: 201 202 strlcat(dt, src, sizeof(dt)) my_strlcat(dt, src, sizeof(dt)) 203 strlcpy(dt, src, sizeof(dt)) my_strlcpy(dt, src, sizeof(dt)) 204 strnlen(s) my_strnlen(s, maxlen) 205 206Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining 207concatenation with formatting. 208 209Sometimes instead of zeroing the allocated heap by using Newxz() you 210should consider "poisoning" the data. This means writing a bit 211pattern into it that should be illegal as pointers (and floating point 212numbers), and also hopefully surprising enough as integers, so that 213any code attempting to use the data without forethought will break 214sooner rather than later. Poisoning can be done using the Poison() 215macros, which have similar arguments to Zero(): 216 217 PoisonWith(dst, n, t, b) scribble memory with byte b 218 PoisonNew(dst, n, t) equal to PoisonWith(dst, n, t, 0xAB) 219 PoisonFree(dst, n, t) equal to PoisonWith(dst, n, t, 0xEF) 220 Poison(dst, n, t) equal to PoisonFree(dst, n, t) 221 222=head2 Character Class Tests 223 224There are several types of character class tests that Perl implements. 225All are more fully described in L<perlapi/Character classification> and 226L<perlapi/Character case changing>. 227 228The C library routines listed in the table below return values based on 229the current locale. Use the entries in the final column for that 230functionality. The other two columns always assume a POSIX (or C) 231locale. The entries in the ASCII column are only meaningful for ASCII 232inputs, returning FALSE for anything else. Use these only when you 233B<know> that is what you want. The entries in the Latin1 column assume 234that the non-ASCII 8-bit characters are as Unicode defines them, the 235same as ISO-8859-1, often called Latin 1. 236 237 Instead Of: Use for ASCII: Use for Latin1: Use for locale: 238 239 isalnum(c) isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c) 240 isalpha(c) isALPHA(c) isALPHA_L1(c) isALPHA_LC(u ) 241 isascii(c) isASCII(c) isASCII_LC(c) 242 isblank(c) isBLANK(c) isBLANK_L1(c) isBLANK_LC(c) 243 iscntrl(c) isCNTRL(c) isCNTRL_L1(c) isCNTRL_LC(c) 244 isdigit(c) isDIGIT(c) isDIGIT_L1(c) isDIGIT_LC(c) 245 isgraph(c) isGRAPH(c) isGRAPH_L1(c) isGRAPH_LC(c) 246 islower(c) isLOWER(c) isLOWER_L1(c) isLOWER_LC(c) 247 isprint(c) isPRINT(c) isPRINT_L1(c) isPRINT_LC(c) 248 ispunct(c) isPUNCT(c) isPUNCT_L1(c) isPUNCT_LC(c) 249 isspace(c) isSPACE(c) isSPACE_L1(c) isSPACE_LC(c) 250 isupper(c) isUPPER(c) isUPPER_L1(c) isUPPER_LC(c) 251 isxdigit(c) isXDIGIT(c) isXDIGIT_L1(c) isXDIGIT_LC(c) 252 253 tolower(c) toLOWER(c) toLOWER_L1(c) 254 toupper(c) toUPPER(c) 255 256For the corresponding functions like C<iswupper()>, I<etc.>, use 257C<isUPPER_uvchr()> for non-locale; or C<isUPPER_LC_uvchr()> for locale. 258And use C<toLOWER_uvchr()> instead of C<towlower()>, I<etc.>. There are 259no direct equivalents for locale; best to put the string into an SV. 260 261Don't use any of the functions like C<isalnum_l()>. Those are 262non-portable, and interfere with Perl's internal handling. 263 264To emphasize that you are operating only on ASCII characters, you can 265append C<_A> to each of the macros in the ASCII column: C<isALPHA_A>, 266C<isDIGIT_A>, and so on. 267 268(There is no entry in the Latin1 column for C<isascii> even though there 269is an C<isASCII_L1>, which is identical to C<isASCII>; the 270latter name is clearer. There is no entry in the Latin1 column for 271C<toupper> because the result can be non-Latin1. You have to use 272C<toUPPER_uvchr>, as described in L<perlapi/Character case changing>.) 273 274Note that the libc caseless comparisons are crippled; Unicode 275provides a richer set, using the concept of folding. If you need 276more than equality/non-equality, it's probably best to store your 277strings in an SV and use SV functions to do the comparision. Similarly 278for collation. 279 280=head2 F<stdlib.h> functions 281 282 Instead Of: Use: 283 284 atof(s) my_atof(s) or Atof(s) 285 atoi(s) grok_atoUV(s, &uv, &e) 286 atol(s) grok_atoUV(s, &uv, &e) 287 strtod(s, &p) Strtod(s, &p) 288 strtol(s, &p, n) Strtol(s, &p, b) 289 strtoul(s, &p, n) Strtoul(s, &p, b) 290 291But note that these are subject to locale; see L</Dealing with locales>. 292 293Typical use is to do range checks on C<uv> before casting: 294 295 int i; UV uv; 296 char* end_ptr = input_end; 297 if (grok_atoUV(input, &uv, &end_ptr) 298 && uv <= INT_MAX) 299 i = (int)uv; 300 ... /* continue parsing from end_ptr */ 301 } else { 302 ... /* parse error: not a decimal integer in range 0 .. MAX_IV */ 303 } 304 305Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in 306F<numeric.c> for converting strings representing numbers in the respective 307bases into C<NV>s. Note that grok_atoUV() doesn't handle negative inputs, 308or leading whitespace (being purposefully strict). 309 310=head2 Miscellaneous functions 311 312You should not even B<want> to use F<setjmp.h> functions, but if you 313think you do, use the C<JMPENV> stack in F<scope.h> instead. 314 315 ~asctime() Perl_sv_strftime_tm() 316 ~asctime_r() Perl_sv_strftime_tm() 317 chsize() my_chsize() 318 ~ctime() Perl_sv_strftime_tm() 319 ~ctime_r() Perl_sv_strftime_tm() 320 ~cuserid() DO NOT USE; see its man page 321 dirfd() my_dirfd() 322 duplocale() Perl_setlocale() 323 ~ecvt() my_snprintf() 324 ~endgrent_r() endgrent() 325 ~endhostent_r() endhostent() 326 ~endnetent_r() endnetent() 327 ~endprotoent_r() endprotoent() 328 ~endpwent_r() endpwent() 329 ~endservent_r() endservent() 330 ~endutent() endutxent() 331 exit(n) my_exit(n) 332 ~fcvt() my_snprintf() 333 freelocale() Perl_setlocale() 334 ~ftw() nftw() 335 getenv(s) PerlEnv_getenv(s) 336 ~gethostbyaddr() getaddrinfo() 337 ~gethostbyname() getnameinfo() 338 ~getpass() DO NOT USE; see its man page 339 ~getpw() getpwuid() 340 ~getutent() getutxent() 341 ~getutid() getutxid() 342 ~getutline() getutxline() 343 ~gsignal() DO NOT USE; see its man page 344 localeconv() Perl_localeconv() 345 mblen() mbrlen() 346 mbtowc() mbrtowc() 347 newlocale() Perl_setlocale() 348 pclose() my_pclose() 349 popen() my_popen() 350 ~pututline() pututxline() 351 ~qecvt() my_snprintf() 352 ~qfcvt() my_snprintf() 353 querylocale() Perl_setlocale() 354 int rand() double Drand01() 355 srand(n) { seedDrand01((Rand_seed_t)n); 356 PL_srand_called = TRUE; } 357 ~readdir_r() readdir() 358 realloc() saferealloc(), Renew() or Renewc() 359 ~re_comp() regcomp() 360 ~re_exec() regexec() 361 ~rexec() rcmd() 362 ~rexec_af() rcmd() 363 setenv(s, val) my_setenv(s, val) 364 ~setgrent_r() setgrent() 365 ~sethostent_r() sethostent() 366 setlocale() Perl_setlocale() 367 setlocale_r() Perl_setlocale() 368 ~setnetent_r() setnetent() 369 ~setprotoent_r() setprotoent() 370 ~setpwent_r() setpwent() 371 ~setservent_r() setservent() 372 ~setutent() setutxent() 373 sigaction() rsignal(signo, handler) 374 ~siginterrupt() rsignal() with the SA_RESTART flag instead 375 signal(signo, handler) rsignal(signo, handler) 376 ~ssignal() DO NOT USE; see its man page 377 strcasecmp() a Perl foldEQ-family function 378 strerror() sv_string_from_errnum() 379 strerror_l() sv_string_from_errnum() 380 strerror_r() sv_string_from_errnum() 381 strftime() Perl_sv_strftime_tm() 382 strtod() my_strtod() or Strtod() 383 system(s) Don't. Look at pp_system or use my_popen. 384 ~tempnam() mkstemp() or tmpfile() 385 ~tmpnam() mkstemp() or tmpfile() 386 tmpnam_r() mkstemp() or tmpfile() 387 uselocale() Perl_setlocale() 388 vsnprintf() my_vsnprintf() 389 wctob() wcrtomb() 390 wctomb() wcrtomb() 391 wsetlocale() Perl_setlocale() 392 393The Perl-furnished alternatives are documented in L<perlapi>, which you 394should peruse anyway to see what all is available to you. 395 396The lists are incomplete. Think when using an unlisted function if it 397seems likely to interfere with Perl. 398 399=head1 Dealing with locales 400 401Like it or not, your code will be executed in the context of a locale, 402as are all C language programs. See L<perllocale>. Most libc calls are 403not affected by the locale, but a surprising number are: 404 405 addmntent() getspent_r() sethostent() 406 alphasort() getspnam() sethostent_r() 407 asctime() getspnam_r() setnetent() 408 asctime_r() getwc() setnetent_r() 409 asprintf() getwchar() setnetgrent() 410 atof() glob() setprotoent() 411 atoi() gmtime() setprotoent_r() 412 atol() gmtime_r() setpwent() 413 atoll() grantpt() setpwent_r() 414 btowc() iconv_open() setrpcent() 415 catopen() inet_addr() setservent() 416 ctime() inet_aton() setservent_r() 417 ctime_r() inet_network() setspent() 418 cuserid() inet_ntoa() sgetspent_r() 419 daylight inet_ntop() shm_open() 420 dirname() inet_pton() shm_unlink() 421 dprintf() initgroups() snprintf() 422 endaliasent() innetgr() sprintf() 423 endgrent() iruserok() sscanf() 424 endgrent_r() iruserok_af() strcasecmp() 425 endhostent() isalnum() strcasestr() 426 endhostent_r() isalnum_l() strcoll() 427 endnetent() isalpha() strerror() 428 endnetent_r() isalpha_l() strerror_l() 429 endprotoent() isascii() strerror_r() 430 endprotoent_r() isascii_l() strfmon() 431 endpwent() isblank() strfmon_l() 432 endpwent_r() isblank_l() strfromd() 433 endrpcent() iscntrl() strfromf() 434 endservent() iscntrl_l() strfroml() 435 endservent_r() isdigit() strftime() 436 endspent() isdigit_l() strftime_l() 437 err() isgraph() strncasecmp() 438 error() isgraph_l() strptime() 439 error_at_line() islower() strsignal() 440 errx() islower_l() strtod() 441 fgetwc() isprint() strtof() 442 fgetwc_unlocked() isprint_l() strtoimax() 443 fgetws() ispunct() strtol() 444 fgetws_unlocked() ispunct_l() strtold() 445 fnmatch() isspace() strtoll() 446 forkpty() isspace_l() strtoq() 447 fprintf() isupper() strtoul() 448 fputwc() isupper_l() strtoull() 449 fputwc_unlocked() iswalnum() strtoumax() 450 fputws() iswalnum_l() strtouq() 451 fputws_unlocked() iswalpha() strverscmp() 452 fscanf() iswalpha_l() strxfrm() 453 fwprintf() iswblank() swprintf() 454 fwscanf() iswblank_l() swscanf() 455 getaddrinfo() iswcntrl() syslog() 456 getaliasbyname_r() iswcntrl_l() timegm() 457 getaliasent_r() iswdigit() timelocal() 458 getdate() iswdigit_l() timezone 459 getdate_r() iswgraph() tolower() 460 getfsent() iswgraph_l() tolower_l() 461 getfsfile() iswlower() toupper() 462 getfsspec() iswlower_l() toupper_l() 463 getgrent() iswprint() towctrans() 464 getgrent_r() iswprint_l() towlower() 465 getgrgid() iswpunct() towlower_l() 466 getgrgid_r() iswpunct_l() towupper() 467 getgrnam() iswspace() towupper_l() 468 getgrnam_r() iswspace_l() tzname 469 getgrouplist() iswupper() tzset() 470 gethostbyaddr() iswupper_l() ungetwc() 471 gethostbyaddr_r() iswxdigit() vasprintf() 472 gethostbyname() iswxdigit_l() vdprintf() 473 gethostbyname2() isxdigit() verr() 474 gethostbyname2_r() isxdigit_l() verrx() 475 gethostbyname_r() localeconv() versionsort() 476 gethostent() localtime() vfprintf() 477 gethostent_r() localtime_r() vfscanf() 478 gethostid() MB_CUR_MAX vfwprintf() 479 getlogin() mblen() vprintf() 480 getlogin_r() mbrlen() vscanf() 481 getmntent() mbrtowc() vsnprintf() 482 getmntent_r() mbsinit() vsprintf() 483 getnameinfo() mbsnrtowcs() vsscanf() 484 getnetbyaddr() mbsrtowcs() vswprintf() 485 getnetbyaddr_r() mbstowcs() vsyslog() 486 getnetbyname() mbtowc() vwarn() 487 getnetbyname_r() mktime() vwarnx() 488 getnetent() nan() vwprintf() 489 getnetent_r() nanf() warn() 490 getnetgrent() nanl() warnx() 491 getnetgrent_r() nl_langinfo() wcrtomb() 492 getprotobyname() openpty() wcscasecmp() 493 getprotobyname_r() printf() wcschr() 494 getprotobynumber() psiginfo() wcscoll() 495 getprotobynumber_r() psignal() wcsftime() 496 getprotoent() putpwent() wcsncasecmp() 497 getprotoent_r() putspent() wcsnrtombs() 498 getpw() putwc() wcsrchr() 499 getpwent() putwchar() wcsrtombs() 500 getpwent_r() regcomp() wcstod() 501 getpwnam() regexec() wcstof() 502 getpwnam_r() res_nclose() wcstoimax() 503 getpwuid() res_ninit() wcstold() 504 getpwuid_r() res_nquery() wcstombs() 505 getrpcbyname_r() res_nquerydomain() wcstoumax() 506 getrpcbynumber_r() res_nsearch() wcswidth() 507 getrpcent_r() res_nsend() wcsxfrm() 508 getrpcport() rpmatch() wctob() 509 getservbyname() ruserok() wctomb() 510 getservbyname_r() ruserok_af() wctrans() 511 getservbyport() scandir() wctype() 512 getservbyport_r() scanf() wcwidth() 513 getservent() setaliasent() wordexp() 514 getservent_r() setgrent() wprintf() 515 getspent() setgrent_r() wscanf() 516 517(The list doesn't include functions that manipulate the locale, such as 518C<setlocale()>.) 519 520If any of these functions are called directly or indirectly from your 521code, you are affected by the current locale. 522 523The first thing to know about this list is that there are better 524alternatives to many of the functions, which it's highly likely that you 525should be using instead. See L</libc functions to avoid> above. 526This includes using Perl IO L<perlapio>. 527 528The second thing to know is that Perl is documented to not pay attention 529to the current locale except for code executed within the scope of a 530S<C<use locale>> statement. If you violate that, you may be creating 531bugs, depending on the application. 532 533The next thing to know is that many of these functions depend only on 534the locale in regards to numeric values. Your code is likely to have 535been written expecting that the decimal point (radix) character is a dot 536(U+002E: FULL STOP), and that strings of integer numbers are not 537separated into groups (1,000,000 in an American locale means a million; 538your code is likely not expecting the commas.) The good news is that 539normally (as of Perl v5.22), your code will get called with the locale 540set so those expectations are met. Explicit action has to be taken to 541change this (described a little ways below). This is accomplished by 542Perl not actually switching into a locale that doesn't conform to these 543expectations, except when explicitly told to do so. The Perl 544input/output and formatting routines do this switching for you 545automatically, if appropriate, and then switch back. If, for some 546reason, you need to do it yourself, the easiest way from C and XS code 547is to use the macro L<perlapi/C<WITH_LC_NUMERIC_SET_TO_NEEDED>>. You 548can wrap this macro around an entire block of code that you want to be 549executed in the correct environment. The bottom line is that your code 550is likely to work as expected in this regard without you having to take 551any action. 552 553This leaves the remaining functions. Your code will get called with all 554but the numeric locale portions set to the underlying locale. Often, 555the locale is of not much import to your code, and you also won't have 556to take any action; things will just work out. But you should examine 557the man pages of the ones you use to verify this. Often, Perl has 558better ways of doing the same functionality. Consider using SVs and 559their access routines rather than calling the low level functions that, 560for example, find how many bytes are in a UTF-8 encoded character. 561 562You can determine if you have been called from within the scope of a 563S<C<use locale>> by using the boolen macro L<perlapi/C<IN_LOCALE>>. 564 565If you need to not be in the underlying locale, you can call 566L<perlapi/C<Perl_setlocale>> to change it temporarily to the one you 567need (likely the "C" locale), and then change it back before returning. 568This can be B<very> problematic on threaded perls on some platforms. See 569L</Dealing with embedded perls and threads>. 570 571A problem with changing the locale of a single category is that mojibake 572can arise on some platforms if the C<LC_CTYPE> category and the changed one 573are not the same. On the platforms that that isn't an issue, the 574preprocessor directive C<LIBC_HANDLES_MISMATCHED_CTYPE> will be defined. 575Otherwise, you may have to change more than one category to correctly 576accomplish your task. And, there will be many locale combinations where 577the mojibake likely won't happen, so you won't be confronted with this 578until the code gets executed in the field by someone who doesn't speak 579your language very well. 580 581Earlier we mentioned that explicit action is required to have your code 582get called with the numeric portions of the locale not meeting the 583the typical expectations of having a dot for the radix character and no 584punctuation separating groups of digits. That action is to call the 585function L<perlapi/C<switch_to_global_locale>>. 586 587C<switch_to_global_locale()> was written initially to cope with the 588C<Tk> library, but is general enough for other similar situations. C<Tk> 589changes the global locale to match its expectations (later versions of 590it allow this to be turned off). This presents a conflict with Perl 591thinking it also controls the locale. Calling this function tells Perl to 592yield control. Calling L<perlapi/C<sync_locale>> tells Perl to take 593control again, accepting whatever the locale has been changed to in the 594interim. If your code is called during that interim, all portions of 595the locale will be the raw underlying values. Should you need to 596manipulate numbers, you are on your own with regard to the radix 597character and grouping. If you find yourself in this situation, it is 598generally best to make the interval between the calls to these two 599functions as short as possible, and avoid calculations until after perl 600has control again. 601 602It is important for perl to know about all the possible locale 603categories on the platform, even if they aren't apparently used in your 604program. Perl knows all of the Linux ones. If your platform has 605others, you can submit an issue at 606L<https://github.com/Perl/perl5/issues> for inclusion of it in the next 607release. In the meantime, it is possible to edit the Perl source to 608teach it about the category, and then recompile. Search for instances 609of, say, C<LC_PAPER> in the source, and use that as a template to add 610the omitted one. 611 612There are further complications under multi-threaded operation. Keep on 613reading. 614 615=head1 Dealing with embedded perls and threads 616 617It is possible to embed a Perl interpreter within a larger program. See 618L<perlembed>. 619 620MULTIPLICITY is the way this is accomplished internally; it is described in 621L<perlguts/How multiple interpreters and concurrency are supported>. 622Multiple Perl interpreters may be embedded. 623 624It is also possible to compile perl to support threading. See 625L<perlthrtut>. Perl's implementation of threading requires 626MULTIPLICITY, but not the other way around. 627 628MULTIPLICITY without threading means that only one thing runs at a time, 629so there are no concurrency issues, but each component or instance can 630affect the global state, potentially interfering with the execution of 631other instance. This can happen if one instance: 632 633=over 634 635=item * 636 637changes the current working directory 638 639=item * 640 641changes the process's environment 642 643=item * 644 645changes the global locale the process is operating under 646 647=item * 648 649writes to shared memory or to a shared file 650 651=item * 652 653uses a shared file descriptor (including a database iterator) 654 655=item * 656 657raises a signal that functions in other instances are sensitive to 658 659=back 660 661If your code doesn't do any of these things, nor depends on any of their 662values, then Congratulations!!, you don't have to worry about MULTIPLICITY 663or threading. But wait, a surprising number of libc functions do 664depend on data global to the process in some way that may not be 665immediately obvious. For example, calling C<L<strtok(3)>> changes the 666global state of a process, and thus needs special attention. 667 668The section 3 libc uses that we know about that have MULTIPLICITY and/or 669multi-thread issues are: 670 671 addmntent() getrpcent_r() re_exec() 672 alphasort() getrpcport() regcomp() 673 asctime() getservbyname() regerror() 674 asctime_r() getservbyname_r() regexec() 675 asprintf() getservbyport() res_nclose() 676 atof() getservbyport_r() res_ninit() 677 atoi() getservent() res_nquery() 678 atol() getservent_r() res_nquerydomain() 679 atoll() getspent() res_nsearch() 680 basename() getspent_r() res_nsend() 681 btowc() getspnam() rexec() 682 catgets() getspnam_r() rexec_af() 683 catopen() getttyent() rpmatch() 684 clearenv() getttynam() ruserok() 685 clearerr_unlocked() getusershell() ruserok_af() 686 crypt() getutent() scandir() 687 crypt_gensalt() getutid() scanf() 688 crypt_r() getutline() secure_getenv() 689 ctermid() getutxent() seed48() 690 ctermid_r() getutxid() seed48_r() 691 ctime() getutxline() setaliasent() 692 ctime_r() getwc() setcontext() 693 cuserid() getwchar() setenv() 694 daylight getwchar_unlocked() setfsent() 695 dbm_clearerr() getwc_unlocked() setgrent() 696 dbm_close() glob() setgrent_r() 697 dbm_delete() gmtime() sethostent() 698 dbm_error() gmtime_r() sethostent_r() 699 dbm_fetch() grantpt() sethostid() 700 dbm_firstkey() hcreate() setkey() 701 dbm_nextkey() hcreate_r() setlocale() 702 dbm_open() hdestroy() setlocale_r() 703 dbm_store() hdestroy_r() setlogmask() 704 dirname() hsearch() setnetent() 705 dlerror() hsearch_r() setnetent_r() 706 dprintf() iconv() setnetgrent() 707 drand48() iconv_open() setprotoent() 708 drand48_r() inet_addr() setprotoent_r() 709 ecvt() inet_aton() setpwent() 710 encrypt() inet_network() setpwent_r() 711 endaliasent() inet_ntoa() setrpcent() 712 endfsent() inet_ntop() setservent() 713 endgrent() inet_pton() setservent_r() 714 endgrent_r() initgroups() setspent() 715 endhostent() initstate_r() setstate_r() 716 endhostent_r() innetgr() setttyent() 717 endnetent() iruserok() setusershell() 718 endnetent_r() iruserok_af() setutent() 719 endnetgrent() isalnum() setutxent() 720 endprotoent() isalnum_l() sgetspent() 721 endprotoent_r() isalpha() sgetspent_r() 722 endpwent() isalpha_l() shm_open() 723 endpwent_r() isascii() shm_unlink() 724 endrpcent() isascii_l() siginterrupt() 725 endservent() isblank() sleep() 726 endservent_r() isblank_l() snprintf() 727 endspent() iscntrl() sprintf() 728 endttyent() iscntrl_l() srand48() 729 endusershell() isdigit() srand48_r() 730 endutent() isdigit_l() srandom_r() 731 endutxent() isgraph() sscanf() 732 erand48() isgraph_l() ssignal() 733 erand48_r() islower() strcasecmp() 734 err() islower_l() strcasestr() 735 error() isprint() strcoll() 736 error_at_line() isprint_l() strerror() 737 errx() ispunct() strerror_l() 738 ether_aton() ispunct_l() strerror_r() 739 ether_ntoa() isspace() strfmon() 740 execlp() isspace_l() strfmon_l() 741 execvp() isupper() strfromd() 742 execvpe() isupper_l() strfromf() 743 exit() iswalnum() strfroml() 744 __fbufsize() iswalnum_l() strftime() 745 fcloseall() iswalpha() strftime_l() 746 fcvt() iswalpha_l() strncasecmp() 747 fflush_unlocked() iswblank() strptime() 748 fgetc_unlocked() iswblank_l() strsignal() 749 fgetgrent() iswcntrl() strtod() 750 fgetpwent() iswcntrl_l() strtof() 751 fgetspent() iswdigit() strtoimax() 752 fgets_unlocked() iswdigit_l() strtok() 753 fgetwc() iswgraph() strtol() 754 fgetwc_unlocked() iswgraph_l() strtold() 755 fgetws() iswlower() strtoll() 756 fgetws_unlocked() iswlower_l() strtoq() 757 fnmatch() iswprint() strtoul() 758 forkpty() iswprint_l() strtoull() 759 __fpending() iswpunct() strtoumax() 760 fprintf() iswpunct_l() strtouq() 761 __fpurge() iswspace() strverscmp() 762 fputc_unlocked() iswspace_l() strxfrm() 763 fputs_unlocked() iswupper() swapcontext() 764 fputwc() iswupper_l() swprintf() 765 fputwc_unlocked() iswxdigit() swscanf() 766 fputws() iswxdigit_l() sysconf() 767 fputws_unlocked() isxdigit() syslog() 768 fread_unlocked() isxdigit_l() system() 769 fscanf() jrand48() tdelete() 770 __fsetlocking() jrand48_r() tempnam() 771 fts_children() l64a() tfind() 772 fts_read() lcong48() timegm() 773 ftw() lcong48_r() timelocal() 774 fwprintf() lgamma() timezone 775 fwrite_unlocked() lgammaf() tmpnam() 776 fwscanf() lgammal() tmpnam_r() 777 gamma() localeconv() tolower() 778 gammaf() localtime() tolower_l() 779 gammal() localtime_r() toupper() 780 getaddrinfo() login() toupper_l() 781 getaliasbyname() login_tty() towctrans() 782 getaliasbyname_r() logout() towlower() 783 getaliasent() logwtmp() towlower_l() 784 getaliasent_r() lrand48() towupper() 785 getchar_unlocked() lrand48_r() towupper_l() 786 getcontext() makecontext() tsearch() 787 getc_unlocked() mallinfo() ttyname() 788 get_current_dir_name() MB_CUR_MAX ttyname_r() 789 getdate() mblen() ttyslot() 790 getdate_r() mbrlen() twalk() 791 getenv() mbrtowc() twalk_r() 792 getfsent() mbsinit() tzname 793 getfsfile() mbsnrtowcs() tzset() 794 getfsspec() mbsrtowcs() ungetwc() 795 getgrent() mbstowcs() unsetenv() 796 getgrent_r() mbtowc() updwtmp() 797 getgrgid() mcheck() utmpname() 798 getgrgid_r() mcheck_check_all() va_arg() 799 getgrnam() mcheck_pedantic() valloc() 800 getgrnam_r() mktime() vasprintf() 801 getgrouplist() mprobe() vdprintf() 802 gethostbyaddr() mrand48() verr() 803 gethostbyaddr_r() mrand48_r() verrx() 804 gethostbyname() mtrace() versionsort() 805 gethostbyname2() muntrace() vfprintf() 806 gethostbyname2_r() nan() vfscanf() 807 gethostbyname_r() nanf() vfwprintf() 808 gethostent() nanl() vprintf() 809 gethostent_r() newlocale() vscanf() 810 gethostid() nftw() vsnprintf() 811 getlogin() nl_langinfo() vsprintf() 812 getlogin_r() nrand48() vsscanf() 813 getmntent() nrand48_r() vswprintf() 814 getmntent_r() openpty() vsyslog() 815 getnameinfo() perror() vwarn() 816 getnetbyaddr() posix_fallocate() vwarnx() 817 getnetbyaddr_r() printf() vwprintf() 818 getnetbyname() profil() warn() 819 getnetbyname_r() psiginfo() warnx() 820 getnetent() psignal() wcrtomb() 821 getnetent_r() ptsname() wcscasecmp() 822 getnetgrent() putchar_unlocked() wcschr() 823 getnetgrent_r() putc_unlocked() wcscoll() 824 getopt() putenv() wcsftime() 825 getopt_long() putpwent() wcsncasecmp() 826 getopt_long_only() putspent() wcsnrtombs() 827 getpass() pututline() wcsrchr() 828 getprotobyname() pututxline() wcsrtombs() 829 getprotobyname_r() putwc() wcstod() 830 getprotobynumber() putwchar() wcstof() 831 getprotobynumber_r() putwchar_unlocked() wcstoimax() 832 getprotoent() putwc_unlocked() wcstold() 833 getprotoent_r() pvalloc() wcstombs() 834 getpw() qecvt() wcstoumax() 835 getpwent() qfcvt() wcswidth() 836 getpwent_r() querylocale() wcsxfrm() 837 getpwnam() rand() wctob() 838 getpwnam_r() random_r() wctomb() 839 getpwuid() rcmd() wctrans() 840 getpwuid_r() rcmd_af() wctype() 841 getrpcbyname() readdir() wcwidth() 842 getrpcbyname_r() readdir64() wordexp() 843 getrpcbynumber() readdir64_r() wprintf() 844 getrpcbynumber_r() readdir_r() wscanf() 845 getrpcent() re_comp() wsetlocale() 846 847(If you know of additional functions that are unsafe on some platform or 848another, notify us via filing a bug report at 849L<https://github.com/Perl/perl5/issues>.) 850 851Some of these are safe under MULTIPLICITY, problematic only under threading. 852If a use doesn't appear in the above list, we think it is MULTIPLICITY 853and thread-safe on all platforms. 854 855All the uses listed above are function calls, except for these: 856 857 daylight MB_CUR_MAX timezone tzname 858 859There are three main approaches to coping with issues involving these 860constructs, each suitable for different circumstances: 861 862=over 863 864=item * 865 866Don't use them. Some of them have preferred alternatives. Use the list 867above in L</libc functions to avoid> to replace your uses with ones 868that are thread-friendly. For example I/O, should be done via 869L<perlapio>. 870 871If you must use them, many, but not all, of them will be ok as long as 872their use is confined to a single thread that has no interaction with 873conflicting uses in other threads. You will need to closely examine 874their man pages for this, and be aware that vendor documentation is 875often imprecise. 876 877=item * 878 879Do all your business before any other code can change things. If you 880make changes, change back before returning. 881 882=item * 883 884Save the result of a query of global information to a per-instance area 885before allowing another instance to execute. Then you can work on it at 886your leisure. This might be an automatic C variable for non-pointers, 887or something as described above in 888C<L<perlxs/Safely Storing Static Data in XS>>. 889 890=back 891 892Without threading, you don't have to worry about being interrupted by 893the system giving control to another thread. With threading, you will 894have to uses mutexes, and be concerned with the possibility of deadlock. 895 896=head2 Functions always unsuitable for use under multi-threads 897 898A few functions are considered totally unsuited for use in a multi-thread 899environment. These must be called only during single-thread operation. 900 901 endusershell() @getaliasent() muntrace() rexec() 902 ether_aton() @getrpcbyname() profil() rexec_af() 903 ether_ntoa() @getrpcbynumber() rcmd() setusershell() 904 fts_children() @getrpcent() rcmd_af() ttyslot() 905 fts_read() getusershell() re_comp() 906 @getaliasbyname() mtrace() re_exec() 907 908C<@> above marks the functions for which there are preferred alternatives 909available on some platforms, and those alternatives may be suitable for 910multi-thread use. 911 912=head2 Functions which must be called at least once before starting threads 913 914Some functions perform initialization on their first call that must be done 915while still in a single-thread environment, but subsequent calls are 916thread-safe when executed in a critical section. 917Therefore, they must be called at least once before switching to 918multi-threads: 919 920 getutent() getutline() getutxid() mallinfo() valloc() 921 getutid() getutxent() getutxline() pvalloc() 922 923=head2 Functions that are thread-safe when called with appropriate arguments 924 925Some of the functions are thread-safe if called with arguments that 926comply with certain (easily met) restrictions. These are: 927 928 ctermid() mbrlen() mbsrtowcs() wcrtomb() 929 cuserid() mbrtowc() tmpnam() wcsnrtombs() 930 error_at_line() mbsnrtowcs() va_arg() wcsrtombs() 931 932See the man pages of each for details. (For completeness, the list 933includes functions that you shouldn't be using anyway because of other 934reasons.) 935 936=head2 Functions vulnerable to signals 937 938Some functions are vulnerable to asynchronous signals. These are: 939 940 getlogin() getutid() getutxid() login() pututline() updwtmp() 941 getlogin_r() getutline() getutxline() logout() pututxline() wordexp() 942 getutent() getutxent() glob() logwtmp() sleep() 943 944Some libc's implement 'system()' thread-safely. But in others, it also 945has signal issues. 946 947=head2 General issues with thread-safety 948 949Some libc functions use and/or modify a global state, such as a database. 950The libc functions presume that there is only one instance at a time 951operating on that database. Unpredictable results occur if more than one 952does, even if the database is not changed. For example, typically there is 953a global iterator for such a data base and that iterator is maintained by 954libc, so that each new read from any instance advances it, meaning that no 955instance will see all the entries. The only way to make these thread-safe 956is to have an exclusive lock on a mutex from the open call through the 957close. You are advised to not use such databases from more than one 958instance at a time. 959 960Other examples of functions that use a global state include pseudo-random 961number generators. Some libc implementations of 'rand()', for example, may 962share the data across threads; and others may have per-thread data. The 963shared ones will have unreproducible results, as the threads will vary in 964their timings and interactions. This may be what you want; or it may not 965be. (This particular function is a candidate to be removed from the POSIX 966Standard because of these issues.) 967 968Functions that output to a stream also are considered thread-unsafe when 969locking is not done. But the typical consequences are just that the data 970is output in an unpredictable order; that outcome may be totally 971acceptable to you. 972 973Since the current working directory is global to a process, all 974instances depend on it. One instance doing a chdir(2) affects all the 975other instances. In a multi-threaded environment, any libc call that 976expects the directory to not change for the duration of its execution 977will have undefined results if another thread interrupts it at just the 978wrong time and changes the directory. The man pages only list one such 979call, nftw(). But there may be other issues lurking. 980 981=head2 Reentrant equivalent functions 982 983Some functions that are problematic with regard to MULTIPLICITY have 984reentrant versions (on some or all platforms) that are better suited, 985with fewer (perhaps no) races when run under threads. 986 987Some of these reentrant functions that are available on all platforms 988should always be used anyway; they are in the lists directly under 989L<libc functions to avoid>. 990 991Others may not be available on some platforms, or have issues that makes 992them undesirable to use even when they are available. Or it may just be 993more complicated and tedious to use the reentrant version. For these, 994perl has a mechanism for automatically substituting that reentrant 995version when available and desirable, while hiding the complications 996from your code. This feature is enabled by default for code in the Perl 997core and its extensions. To enable it in other XS modules, 998 999 #define PERL_REENTRANT 1000 1001It is simpler for you to use the unpreferred version in your code, and 1002rely on this feature to do the better thing, in part because no 1003substitution is done if the alternative is not available or desirable on 1004the platform, nor if threads aren't enabled. You just write as if there 1005weren't threads, and you get the better behavior without having to think 1006about it. 1007 1008On some platforms the safer library functions may fail if the result 1009buffer is too small (for example the user group databases may be rather 1010large, and the reentrant functions may have to carry around a full 1011snapshot of those databases). Perl will start with a small buffer, but 1012keep retrying and growing the result buffer until the result fits. If 1013this limitless growing sounds bad for security or memory consumption 1014reasons you can recompile Perl with C<PERL_REENTRANT_MAXSIZE> #defined 1015to the maximum number of bytes you will allow. 1016 1017Below is a list of the non-reentrant functions and their reentrant 1018alternatives. This substitution is done even on functions that you 1019shouldn't be using in the first place. These are marked by a C<*>. You 1020should instead use the alternate given in the lists directly under 1021L<libc functions to avoid>. 1022 1023Even so, some of the preferred alternatives are considered obsolete or 1024otherwise unwise to use on some platforms. These are marked with a '?'. 1025Also, some alternatives aren't Perl-defined functions and aren't in in 1026the POSIX Standard, so won't be widely available. These are marked with 1027'~'. (Remember that the automatic substitution only happens when they 1028are available and desirable, so you can just use the unpreferred 1029alternative.) 1030 1031 *asctime() ?asctime_r() 1032 crypt() ~crypt_r() 1033 ctermid() ~ctermid_r() 1034 *ctime() ?ctime_r() 1035 endgrent() ?~endgrent_r() 1036 endhostent() ?~endhostent_r() 1037 endnetent() ?~endnetent_r() 1038 endprotoent() ?~endprotoent_r() 1039 endpwent() ?~endpwent_r() 1040 endservent() ?~endservent_r() 1041 getgrent() ~getgrent_r() 1042 getgrgid() getgrgid_r() 1043 getgrnam() getgrnam_r() 1044 gethostbyaddr() ~gethostbyaddr_r() 1045 gethostbyname() ~gethostbyname_r() 1046 gethostent() ~gethostent_r() 1047 getlogin() getlogin_r() 1048 getnetbyaddr() ~getnetbyaddr_r() 1049 getnetbyname() ~getnetbyname_r() 1050 getnetent() ~getnetent_r() 1051 getprotobyname() ~getprotobyname_r() 1052 getprotobynumber() ~getprotobynumber_r() 1053 getprotoent() ~getprotoent_r() 1054 getpwent() ~getpwent_r() 1055 getpwnam() getpwnam_r() 1056 getpwuid() getpwuid_r() 1057 getservbyname() ~getservbyname_r() 1058 getservbyport() ~getservbyport_r() 1059 getservent() ~getservent_r() 1060 getspnam() ~getspnam_r() 1061 gmtime() gmtime_r() 1062 localtime() localtime_r() 1063 readdir() ?readdir_r() 1064 readdir64() ~readdir64_r() 1065 setgrent() ?~setgrent_r() 1066 sethostent() ?~sethostent_r() 1067 *setlocale() ?~setlocale_r() 1068 setnetent() ?~setnetent_r() 1069 setprotoent() ?~setprotoent_r() 1070 setpwent() ?~setpwent_r() 1071 setservent() ?~setservent_r() 1072 *strerror() strerror_r() 1073 *tmpnam() ~tmpnam_r() 1074 ttyname() ttyname_r() 1075 1076The Perl-furnished items are documented in perlapi. 1077 1078The bottom line is: 1079 1080=over 1081 1082=item For items marked C<*> 1083 1084Replace all uses of these with the preferred alternative given in the 1085lists directly under L<libc functions to avoid>. 1086 1087=item For the remaining items 1088 1089If you really need to use these functions, you have two choices: 1090 1091=over 1092 1093=item If you #define PERL_REENTRANT 1094 1095Use the function in the first column as-is, and let perl do the work of 1096substituting the function in the right column if available on the 1097platform, and it is deemed suitable for use. 1098 1099You should look at the man pages for both versions to find any other 1100gotchas. 1101 1102=item If you don't enable automatic substitution 1103 1104You should examine the application's code to determine if the column 1 1105function presents a real problem under threads given the circumstances 1106it is used in. You can go directly to the column 2 replacement, but 1107beware of the ones that are marked. Some of those may be nonexistent or 1108flaky on some platforms. 1109 1110=back 1111 1112=back 1113 1114=head2 Functions that need the environment to be constant 1115 1116Since the environment is global to a process, all instances depend on 1117it. One instance changing the environment affects all the other 1118instances. Under threads, any libc call that expects the environment to 1119not change for the duration of its execution will have undefined results 1120if another thread interrupts it at just the wrong time and changes it. 1121These are the functions that the man pages list as being sensitive to 1122that. 1123 1124 catopen() gethostbyname2() newlocale() 1125 ctime() gethostbyname2_r() regerror() 1126 ctime_r() gethostbyname_r() secure_getenv() 1127 endhostent() gethostent() sethostent() 1128 endhostent_r() gethostent_r() sethostent_r() 1129 endnetent() gethostid() setlocale() 1130 endnetent_r() getnameinfo() setlocale_r() 1131 execlp() getnetbyname() setnetent() 1132 execvp() getnetent() setnetent_r() 1133 execvpe() getopt() strftime() 1134 fnmatch() getopt_long() strptime() 1135 getaddrinfo() getopt_long_only() sysconf() 1136 get_current_dir_name() getrpcport() syslog() 1137 getdate() glob() tempnam() 1138 getdate_r() gmtime() timegm() 1139 getenv() gmtime_r() timelocal() 1140 gethostbyaddr() localtime() tzset() 1141 gethostbyaddr_r() localtime_r() vsyslog() 1142 gethostbyname() mktime() 1143 1144Many of these functions are problematic under threads for other reasons 1145as well. See the man pages for any you use. 1146 1147Perl defines mutexes C<ENV_READ_LOCK> and C<ENV_READ_UNLOCK> with which 1148to wrap calls to these functions. You need to consider the possibility 1149of deadlock. It is expected that a different mechanism will be in place 1150and preferred for Perl v5.42. 1151 1152=head2 Locale-specific issues 1153 1154C language programs originally had a single locale global to the entire 1155process. This was later found to be inadequate for many purposes, so later 1156extensions changed that, first with Windows, and then POSIX 2008. In 1157Windows, you can change any thread at any time to operate either with a 1158per-thread locale, or with the global one, using a special new libc 1159function. In POSIX, the original API operates only on the global 1160locale, but there is an entirely new API to manipulate either per-thread 1161locales or the global one. As with Windows (but using the new API), a 1162thread can be switched at any time to operate on the global locale, or a 1163per-thread one. 1164 1165When one instance changes the global locale, all other instances using 1166the global locale are affected. Almost all the locale-related functions 1167in the list directly under L</Dealing with embedded perls and threads> 1168have undefined behavior if another thread interrupts their execution and 1169changes the locale. Under threads, another thread could do exactly that. 1170 1171But, on systems that have per-thread locales, starting with Perl v5.28, 1172perl uses them after initialization; the global locale is not used 1173except if XS code has called C<switch_to_global_locale()>. Doing so 1174affects only the thread that called it. If a maximum of one instance is 1175using the global locale, no other instances are affected, the locale of 1176concurrently executing functions in other threads is not changed, and 1177this becomes a non-issue. The C preprocessor symbol 1178C<USE_THREAD_SAFE_LOCALE> will be defined if per-thread locales are 1179available and perl has been compiled to use them. The implementation of 1180per-thread locales on some platforms, like most *BSD-based ones, is so 1181buggy that the perl hints files for them deliberately turn off the 1182possibility of using them. 1183 1184The converse is that on systems with only a global locale, having 1185different threads using different locales is not likely to work well; 1186and changing the locale is dangerous, often leading to crashes. 1187 1188Perl has extensive code to work as well as possible on both types of 1189systems. You should always use C<Perl_setlocale()> to change and query 1190the locale, as it portably works across the range of possibilities. 1191 1192=head1 SEE ALSO 1193 1194L<perlapi>, L<perlapio>, L<perlguts>, L<perlxs> 1195 1196