PERLCLIB(1)

💖 NAME 💖

perlclib — Interacting with standard C library functions

---

🌸 DESCRIPTION 🌸

okay so bestie, listen up: the perl interpreter is literally written in C, and XS code also expands to C. Which means — no matter what — this code is gonna call some functions from the C library, aka libc. This doc is the vibe check on how to interface with that library. 🫶

One thing Perl porters should note: perl lowkey doesn't use that much of the C standard library internally. You'll see <em>very</em> little use of, for example, the ctype.h functions in there. Why? Because Perl tends to reimplement or abstract standard library functions, so that we know exactly how they're going to operate. Control freak behavior, but make it ✨robust✨.

---

🚫 libc functions to avoid 🚫

There are so many libc functions. Most of them are fair game to use, but some are absolutely not. Some of the possible reasons are:

• They likely will interfere with the perl interpreter's functioning, such as its bookkeeping, or signal handling, or memory allocation, or any number of harmful things. 💀
• They aren't implemented on all platforms, but there is an alternative that is. Or they may be buggy or deprecated on some or all platforms.
• They aren't suitable for multi-threaded operation, but there is an alternative that is, and is just as easily usable. You may not expect your code to ever be used under threads, but code has a way of being adapted beyond our initial expectations. If it is just as easy to use something that can be used under threads, it's better to use that now, just in case.
• In functions that deal with strings, complications may arise because the string may be encoded in different ways, for example in UTF-8. For these, it is likely better to place the string in a SV and use the Perl SV string handling functions that contain extensive logic to deal with this.
• In functions that deal with numbers, complications may arise because the numbers get too big or small, and what those limits are depends on the current platform. Again, the Perl SV numeric data types have extensive logic to take care of these kinds of issues.
• They are locale-aware, and your caller may not want this.

The following commentary and tables give some functions in the first column that shouldn't be used in C or XS code, with the preferred alternative (if any) in the second column. 👑

---

🎀 Conventions 🎀

In the following tables:

• "~" — marks the function as deprecated; it should not be used regardless.
• "t" — is a type.
• "p" — is a pointer.
• "n" — is a number.
• "s" — is a string.
• "sv", "av", "hv", etc. represent variables of their respective types.

---

📁 File Operations 📁

Instead of the stdio.h functions, you should use the Perl abstraction layer. Instead of "FILE*" types, you need to be handling "PerlIO*" types. Don't forget that with the new PerlIO layered I/O abstraction, "FILE*" types may not even be available. See also the "perlapio" documentation for more info about the following functions:

Instead Of:                 Use:

stdin                       PerlIO_stdin()
stdout                      PerlIO_stdout()
stderr                      PerlIO_stderr()

fopen(fn, mode)             PerlIO_open(fn, mode)
freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Dep-
                              recated)
fflush(stream)              PerlIO_flush(perlio)
fclose(stream)              PerlIO_close(perlio)

---

🔤 File Input and Output 🔤

Instead Of:                 Use:

fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)

[f]getc(stream)             PerlIO_getc(perlio)
[f]putc(stream, n)          PerlIO_putc(perlio, n)
ungetc(n, stream)           PerlIO_ungetc(perlio, n)

Note that the PerlIO equivalents of fread and fwrite are slightly different from their C library counterparts, bestie — the args do not line up the same way:

fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)

fputs(s, stream)            PerlIO_puts(perlio, s)

There is no equivalent to fgets (or the deprecated gets); one should use sv_gets instead:

fgets(s, n, stream)         sv_gets(sv, perlio, append)

---

🧭 File Positioning 🧭

Instead Of:                 Use:

feof(stream)                PerlIO_eof(perlio)
fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
rewind(stream)              PerlIO_rewind(perlio)

fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
fsetpos(stream, p)          PerlIO_setpos(perlio, sv)

ferror(stream)              PerlIO_error(perlio)
clearerr(stream)            PerlIO_clearerr(perlio)

---

🧠 Memory Management and String Handling 🧠

Instead Of:                    Use:

t* p = malloc(n)               Newx(p, n, t)
t* p = calloc(n, s)            Newxz(p, n, t)
p = realloc(p, n)              Renew(p, n, t)

It is not portable to try to allocate 0 bytes; allocating 1 or more is portable. 📏

NEVER pass pointers between Newx, Renew, Safefree and libc equivalents malloc, realloc, free. They are not from the same memory pool or allocator. Either an instant or delayed SEGV will occur, or subtle memory leaks or subtle heap corruption. Like, fr fr, do not do this. 💀

memcpy(dst, src, n)            Copy(src, dst, n, t)
memmove(dst, src, n)           Move(src, dst, n, t)
memcpy(dst, src, sizeof(t))    StructCopy(src, dst, t)

Notice the different order of arguments to Copy and Move than used in memcpy and memmove. Yes, it's giving "gotcha", sorry bestie. 🙈

memset(dst, 0, n * sizeof(t))  Zero(dst, n, t)
memzero(dst, 0)                Zero(dst, n, char)
free(p)                        Safefree(p)

strdup(p)                      savepv(p)
strndup(p, n)                  savepvn(p, n) (Hey, strndup doesn't
                                              exist!)

Sometimes, instead of zeroing the allocated heap by using Newxz() you should consider "poisoning" the data. This means writing a bit pattern into it that should be illegal as pointers (and floating point numbers), and also hopefully surprising enough as integers, so that any code attempting to use the data without forethought will break <em>sooner</em> rather than later. Poisoning can be done using the Poison() macros, which have similar arguments to Zero():

PoisonWith(dst, n, t, b)    scribble memory with byte b
PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
Poison(dst, n, t)           equal to PoisonFree(dst, n, t)

strstr(big, little)            instr(big, little)
memmem(big, blen, little, len) ninstr(big, bigend, little, little_end)
strcmp(s1, s2)                 strLE(s1, s2) / strEQ(s1, s2)
                                             / strGT(s1,s2)
strncmp(s1, s2, n)             strnNE(s1, s2, n) / strnEQ(s1, s2, n)

memcmp(p1, p2, n)              memNE(p1, p2, n)
!memcmp(p1, p2, n)             memEQ(p1, p2, n)

Most of the time, though, you'll want to be dealing with SVs internally instead of raw char * strings:

strlen(s)                   sv_len(sv)
strcpy(dt, src)             sv_setpv(sv, s)
strncpy(dt, src, n)         sv_setpvn(sv, s, n)
strcat(dt, src)             sv_catpv(sv, s)
strncat(dt, src)            sv_catpvn(sv, s, n)

If you do need raw strings, use these instead:

my_strnlen(s, maxlen)
my_strlcpy(dt, src, sizeof(dt))
my_strlcat(dt, src, sizeof(dt))

Similarly, you can use SVs for creating strings from formats:

sprintf(s, fmt, ...)         sv_setpvf(sv, fmt, ...)
vsprintf(str, fmt, va_list)  sv_vsetpvf(sv, fmt, va_list)

Or for raw strings:

my_snprintf(dt, len, fmt, ...)
my_vsnprintf(dt, len, fmt, va_list)
vsprintf(str, fmt, va_list)  sv_vsnprintf(sv, fmt, va_list)

Note also the existence of sv_catpvf and sv_vcatpvfn, combining concatenation with formatting; and Perl_form() for another form of formatted populating. ✨

🚨 glibc printf(), sprintf(), etc. are buggy before glibc version 2.17. They won't allow a "%.s" format with a precision to create a string that isn't valid UTF-8 if the current underlying locale of the program is UTF-8. What happens is that the %s and its operand are simply <em>skipped</em> without any notice. <https://sourceware.org/bugzilla/show_bug.cgi?id=6530>. Not me finding out about this the hard way 😭

---

🔡 Character Class Tests 🔡

There are several types of character class tests that Perl implements. All are more fully described in "Character classification" in perlapi and "Character case changing" in perlapi.

The C library routines listed in the table below return values based on the current locale. Use the entries in the final column for that functionality. The other two columns <em>always</em> assume a POSIX (or C) locale. The entries in the ASCII column are only meaningful for ASCII inputs, returning FALSE for anything else — use these only when you know that is what you want. The entries in the Latin1 column assume that the non-ASCII 8-bit characters are as Unicode defines them, the same as ISO-8859-1, often called Latin 1.

Instead Of:  Use for ASCII:   Use for Latin1:      Use for locale:

isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
isascii(c)  isASCII(c)                             isASCII_LC(c)
isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)

tolower(c)  toLOWER(c)        toLOWER_L1(c)
toupper(c)  toUPPER(c)

For the corresponding functions like iswupper(), etc., use isUPPER_uvchr() for non-locale; or isUPPER_LC_uvchr() for locale. And use toLOWER_uvchr() instead of towlower(), etc. There are no direct equivalents for locale; best to put the string into an SV.

🛑 Don't use any of the functions like isalnum_l(). Those are non-portable, and interfere with Perl's internal handling.

To emphasize that you are operating only on ASCII characters, you can append "_A" to each of the macros in the ASCII column: "isALPHA_A", "isDIGIT_A", and so on. 💅

(Okay so quick Latin1 column tea, bestie 👀) There's literally no entry in the Latin1 column for isascii even though there's an isASCII_L1, which is identical to isASCII; the latter name is clearer. And there's no entry in the Latin1 column for toupper because the result can be non-Latin1. You have to use toUPPER_uvchr, as described in "Character case changing" in perlapi.

Also not me using libc caseless comparisons because they're crippled 💀. Unicode provides a richer set, using the concept of folding. If you need more than equality/non-equality, it's probably best to store your strings in an SV and use SV functions to do the comparison. Same energy for collation.

✨ stdlib.h functions ✨

Okay so here's the stdlib.h glow-up list, no cap:

• atof(s) — use my_atof(s) or Atof(s)
• atoi(s) — use grok_atoUV(s, &uv, &e)
• atol(s) — use grok_atoUV(s, &uv, &e)
• strtod(s, &p) — use Strtod(s, &p)
• strtol(s, &p, n) — use Strtol(s, &p, b)
• strtoul(s, &p, n) — use Strtoul(s, &p, b)

But heads up: even the alternative functions are subject to locale; see "Dealing with locales".

Typical use is to do range checks on uv before casting:

int i; UV uv;
char* end_ptr = input_end;
if (grok_atoUV(input, &uv, &end_ptr)
    && uv <= INT_MAX)
  i = (int)uv;
  ... /* continue parsing from end_ptr */
} else {
  ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
}

Also peep grok_bin, grok_hex, and grok_oct in numeric.c for converting strings representing numbers in the respective bases into NVs. And note that grok_atoUV() doesn't handle negative inputs, or leading whitespace — it's being purposefully strict, fr fr.

🦋 Miscellaneous functions 🦋

You should not even want to use setjmp.h functions, but if you think you do, use the JMPENV stack in scope.h instead. Trust. 💅

• ~asctime() — use Perl_sv_strftime_tm()
• ~asctime_r() — use Perl_sv_strftime_tm()
• chsize() — use my_chsize()
• ~ctime() — use Perl_sv_strftime_tm()
• ~ctime_r() — use Perl_sv_strftime_tm()
• ~cuserid() — DO NOT USE; see its man page
• dirfd() — use my_dirfd()
• duplocale() — use Perl_setlocale()
• ~ecvt() — use my_snprintf()
• ~endgrent_r() — use endgrent()
• ~endhostent_r() — use endhostent()
• ~endnetent_r() — use endnetent()
• ~endprotoent_r() — use endprotoent()
• ~endpwent_r() — use endpwent()
• ~endservent_r() — use endservent()
• ~endutent() — use endutxent()
• exit(n) — use my_exit(n)
• ~fcvt() — use my_snprintf()
• freelocale() — use Perl_setlocale()
• ~ftw() — use nftw()
• getenv(s) — use PerlEnv_getenv(s)
• ~gethostbyaddr() — use getaddrinfo()
• ~gethostbyname() — use getnameinfo()
• ~getpass() — DO NOT USE; see its man page
• ~getpw() — use getpwuid()
• ~getutent() — use getutxent()
• ~getutid() — use getutxid()
• ~getutline() — use getutxline()
• ~gsignal() — DO NOT USE; see its man page
• localeconv() — use Perl_localeconv()
• mblen() — use mbrlen()
• mbtowc() — use mbrtowc()
• newlocale() — use Perl_setlocale()
• pclose() — use my_pclose()
• popen() — use my_popen()
• ~pututline() — use pututxline()
• ~qecvt() — use my_snprintf()
• ~qfcvt() — use my_snprintf()
• querylocale() — use Perl_setlocale()
• int rand() — use double Drand01()
• srand(n) — use:

{ seedDrand01((Rand_seed_t)n);
  PL_srand_called = TRUE; }

• ~readdir_r() — use readdir()
• realloc() — use saferealloc(), Renew() or Renewc()
• ~re_comp() — use regcomp()
• ~re_exec() — use regexec()
• ~rexec() — use rcmd()
• ~rexec_af() — use rcmd()
• setenv(s, val) — use my_setenv(s, val)
• ~setgrent_r() — use setgrent()
• ~sethostent_r() — use sethostent()
• setlocale() — use Perl_setlocale()
• setlocale_r() — use Perl_setlocale()
• ~setnetent_r() — use setnetent()
• ~setprotoent_r() — use setprotoent()
• ~setpwent_r() — use setpwent()
• ~setservent_r() — use setservent()
• ~setutent() — use setutxent()
• sigaction() — use rsignal(signo, handler)
• ~siginterrupt() — use rsignal() with the SA_RESTART flag instead
• signal(signo, handler) — use rsignal(signo, handler)
• ~ssignal() — DO NOT USE; see its man page
• strcasecmp() — use a Perl foldEQ-family function
• strerror() — use sv_string_from_errnum()
• strerror_l() — use sv_string_from_errnum()
• strerror_r() — use sv_string_from_errnum()
• strftime() — use Perl_sv_strftime_tm()
• strtod() — use my_strtod() or Strtod()
• system(s) — Don't. Look at pp_system or use my_popen.
• ~tempnam() — use mkstemp()
• ~tmpnam() — use mkstemp()
• tmpnam_r() — use mkstemp()
• uselocale() — use Perl_setlocale()
• vsnprintf() — use my_vsnprintf()
• wctob() — use wcrtomb()
• wctomb() — use wcrtomb()
• wsetlocale() — use Perl_setlocale()

The Perl-furnished alternatives are documented in perlapi, which you should totally peruse anyway to see what all is available to you. 💖

The lists are incomplete. So think when using an unlisted function if it seems likely to interfere with Perl. Vibe check it. ✨

🌍 Dealing with locales 🌍

Like it or not, your code will be executed in the context of a locale, as are all C language programs. See perllocale. Most libc calls are not affected by the locale, but a surprising number are:

        addmntent()           getspent_r()        sethostent()
        alphasort()           getspnam()          sethostent_r()
        asctime()             getspnam_r()        setnetent()
        asctime_r()           getwc()             setnetent_r()
        asprintf()            getwchar()          setnetgrent()
        atof()                glob()              setprotoent()
        atoi()                gmtime()            setprotoent_r()
        atol()                gmtime_r()          setpwent()
        atoll()               grantpt()           setpwent_r()
        btowc()               iconv_open()        setrpcent()
        catopen()             inet_addr()         setservent()
        ctime()               inet_aton()         setservent_r()
        ctime_r()             inet_network()      setspent()
        cuserid()             inet_ntoa()         sgetspent_r()
        daylight              inet_ntop()         shm_open()
        dirname()             inet_pton()         shm_unlink()
        dprintf()             initgroups()        snprintf()
        endaliasent()         innetgr()           sprintf()
        endgrent()            iruserok()          sscanf()
        endgrent_r()          iruserok_af()       strcasecmp()
        endhostent()          isalnum()           strcasestr()
        endhostent_r()        isalnum_l()         strcoll()
        endnetent()           isalpha()           strerror()
        endnetent_r()         isalpha_l()         strerror_l()
        endprotoent()         isascii()           strerror_r()
        endprotoent_r()       isascii_l()         strfmon()
        endpwent()            isblank()           strfmon_l()
        endpwent_r()          isblank_l()         strfromd()
        endrpcent()           iscntrl()           strfromf()
        endservent()          iscntrl_l()         strfroml()
        endservent_r()        isdigit()           strftime()
        endspent()            isdigit_l()         strftime_l()
        err()                 isgraph()           strncasecmp()
        error()               isgraph_l()         strptime()
        error_at_line()       islower()           strsignal()
        errx()                islower_l()         strtod()
        fgetwc()              isprint()           strtof()
        fgetwc_unlocked()     isprint_l()         strtoimax()
        fgetws()              ispunct()           strtol()
        fgetws_unlocked()     ispunct_l()         strtold()
        fnmatch()             isspace()           strtoll()
        forkpty()             isspace_l()         strtoq()
        fprintf()             isupper()           strtoul()
        fputwc()              isupper_l()         strtoull()
        fputwc_unlocked()     iswalnum()          strtoumax()
        fputws()              iswalnum_l()        strtouq()
        fputws_unlocked()     iswalpha()          strverscmp()
        fscanf()              iswalpha_l()        strxfrm()
        fwprintf()            iswblank()          swprintf()
        fwscanf()             iswblank_l()        swscanf()
        getaddrinfo()         iswcntrl()          syslog()
        getaliasbyname_r()    iswcntrl_l()        timegm()
        getaliasent_r()       iswdigit()          timelocal()
        getdate()             iswdigit_l()        timezone
        getdate_r()           iswgraph()          tolower()
        getfsent()            iswgraph_l()        tolower_l()
        getfsfile()           iswlower()          toupper()
        getfsspec()           iswlower_l()        toupper_l()
        getgrent()            iswprint()          towctrans()
        getgrent_r()          iswprint_l()        towlower()
        getgrgid()            iswpunct()          towlower_l()
        getgrgid_r()          iswpunct_l()        towupper()
        getgrnam()            iswspace()          towupper_l()
        getgrnam_r()          iswspace_l()        tzname
        getgrouplist()        iswupper()          tzset()
        gethostbyaddr()       iswupper_l()        ungetwc()
        gethostbyaddr_r()     iswxdigit()         vasprintf()
        gethostbyname()       iswxdigit_l()       vdprintf()
        gethostbyname2()      isxdigit()          verr()
        gethostbyname2_r()    isxdigit_l()        verrx()
        gethostbyname_r()     localeconv()        versionsort()
        gethostent()          localtime()         vfprintf()
        gethostent_r()        localtime_r()       vfscanf()
        gethostid()           MB_CUR_MAX          vfwprintf()
        getlogin()            mblen()             vprintf()
        getlogin_r()          mbrlen()            vscanf()
        getmntent()           mbrtowc()           vsnprintf()
        getmntent_r()         mbsinit()           vsprintf()
        getnameinfo()         mbsnrtowcs()        vsscanf()
        getnetbyaddr()        mbsrtowcs()         vswprintf()
        getnetbyaddr_r()      mbstowcs()          vsyslog()
        getnetbyname()        mbtowc()            vwarn()
        getnetbyname_r()      mktime()            vwarnx()
        getnetent()           nan()               vwprintf()
        getnetent_r()         nanf()              warn()
        getnetgrent()         nanl()              warnx()
        getnetgrent_r()       nl_langinfo()       wcrtomb()
        getprotobyname()      openpty()           wcscasecmp()
        getprotobyname_r()    printf()            wcschr()
        getprotobynumber()    psiginfo()          wcscoll()
        getprotobynumber_r()  psignal()           wcsftime()
        getprotoent()         putpwent()          wcsncasecmp()
        getprotoent_r()       putspent()          wcsnrtombs()
        getpw()               putwc()             wcsrchr()
        getpwent()            putwchar()          wcsrtombs()
        getpwent_r()          regcomp()           wcstod()
        getpwnam()            regexec()           wcstof()
        getpwnam_r()          res_nclose()        wcstoimax()
        getpwuid()            res_ninit()         wcstold()
        getpwuid_r()          res_nquery()        wcstombs()
        getrpcbyname_r()      res_nquerydomain()  wcstoumax()
        getrpcbynumber_r()    res_nsearch()       wcswidth()
        getrpcent_r()         res_nsend()         wcsxfrm()
        getrpcport()          rpmatch()           wctob()
        getservbyname()       ruserok()           wctomb()
        getservbyname_r()     ruserok_af()        wctrans()
        getservbyport()       scandir()           wctype()
        getservbyport_r()     scanf()             wcwidth()
        getservent()          setaliasent()       wordexp()
        getservent_r()        setgrent()          wprintf()
        getspent()            setgrent_r()        wscanf()

(The list doesn't include functions that manipulate the locale, such as setlocale().)

---

okay so if ANY of these get called — directly or indirectly, from your code — you are affected by the current locale. that's it, that's the whole vibe check. 💅

First thing you need to know, bestie: there are better alternatives to a whole bunch of these, and it's highly likely you should be using those instead. go read "libc functions to avoid" above, it's literally right there. that list includes using Perl IO — aka perlapio. slay.

Second thing: Perl is documented to not pay attention to the current locale — except for code that runs inside the scope of a "use locale" statement. if you violate that? you may be creating bugs, depending on the application. not the cute kind of bug. the 3am kind. 😭

Next thing: a lot of these functions only care about the locale when it comes to numeric values. your code was probably written assuming the decimal point (radix) character is a dot — that's U+002E: FULL STOP — and that strings of integer numbers are not split into groups (1,000,000 in an American locale means a million; your code is likely not expecting the commas, fr fr). 🍓

the good news? normally — and by "normally" I mean as of Perl v5.22 — your code gets called with the locale set so those expectations are met. ✨ you have to take explicit action to change that (more on that a lil ways below 👇). how does Perl pull this off? it just… doesn't actually switch into a locale that doesn't conform to those expectations, unless it's explicitly told to. the Perl input/output and formatting routines do that switching for you automatically, if appropriate, and then switch back. 🫶

and if for some reason you do need to do it yourself, the easiest way from C and XS code is to use the macro "WITH_LC_NUMERIC_SET_TO_NEEDED" in perlapi. you can wrap that macro around an entire block of code you want executed in the correct environment. bottom line: your code is likely to just work as expected here, no action required. periodt. 👑

---

that leaves the remaining functions. your code will get called with all but the numeric locale portions set to the underlying locale. often the locale doesn't matter much to your code at all, and you also won't have to do anything — things just work out. 🌈

but you should examine the man pages of the ones you use to verify this. and often, Perl has better ways of doing the same functionality. consider using SVs and their access routines instead of calling the low level functions that, for example, find how many bytes are in a UTF-8 encoded character. iykyk. 💜

you can determine if you've been called from within the scope of a "use locale" by using the boolean macro "IN_LOCALE" in perlapi. 👀

if you need to not be in the underlying locale, you can call "Perl_setlocale" in perlapi to change it temporarily to the one you need (likely the "C" locale), and then change it back before returning. > but heads up: this can be very problematic on threaded perls on some platforms. go see "Dealing with embedded perls and threads". 🙈

---

and now the messy part. 🫠 a problem with changing the locale of a single category is that mojibake can arise on some platforms if the "LC_CTYPE" category and the changed one are not the same. on the platforms where that isn't an issue, the preprocessor directive "LIBC_HANDLES_MISMATCHED_CTYPE" will be defined. otherwise? you may have to change more than one category to correctly accomplish your task. 😮‍💨

and listen — there will be many locale combinations where the mojibake likely won't happen, so you won't be confronted with this until the code gets executed in the field by someone who doesn't speak your language very well. 💀

earlier we mentioned that explicit action is required to have your code get called with the numeric portions of the locale not meeting the typical expectations — y'know, the whole "dot for the radix character and no punctuation separating groups of digits" thing. that action is to call the function "switch_to_global_locale" in perlapi. that's the one. go get it. 🎀

okay so switch_to_global_locale() was originally written to deal with the "Tk" library, but bestie it's general enough for other similar situations too 💅. What "Tk" does is change the global locale to match its own expectations (later versions let you turn that off, thank god). And that lowkey creates a whole conflict with Perl, which also thinks it controls the locale 😭. So calling this function tells Perl to yield control. Then calling "sync_locale" in perlapi tells Perl to take control back, accepting whatever the locale got changed to in the interim. If your code gets called during that interim?? all portions of the locale will be the raw underlying values, no cap. Should you need to manipulate numbers, you are on your own with regard to the radix character and grouping 🙈. If you find yourself in this situation, it is generally best to make the interval between the calls to these two functions as short as possible, and avoid calculations until after perl has control again. periodt.

It's important for perl to know about all the possible locale categories on the platform, even if they aren't apparently used in your program. Perl knows all of the Linux ones ✨. If your platform has others, you can submit an issue at <https://github.com/Perl/perl5/issues> for inclusion of it in the next release. In the meantime, it is possible to edit the Perl source to teach it about the category, and then recompile. Search for instances of, say, "LC_PAPER" in the source, and use that as a template to add the omitted one 🫶.

There are further complications under multi-threaded operation. Keep on reading 👀.

---

🧵 Dealing with embedded perls and threads 🧵

It is possible to embed a Perl interpreter within a larger program. See perlembed 💖.

MULTIPLICITY is the way this is accomplished internally; it is described in "How multiple interpreters and concurrency are supported" in perlguts. Multiple Perl interpreters may be embedded 👑.

It is also possible to compile perl to support threading. See perlthrtut. Perl's implementation of threading requires MULTIPLICITY, but not the other way around 🌀.

MULTIPLICITY without threading means that only one thing runs at a time, so there are no concurrency issues, but each component or instance can affect the global state, potentially interfering with the execution of other instances 😬. This can happen if one instance:

• changes the current working directory
• changes the process's environment
• changes the global locale the process is operating under
• writes to shared memory or to a shared file
• uses a shared file descriptor (including a database iterator)
• raises a signal that functions in other instances are sensitive to

If your code doesn't do any of these things, nor depends on any of their values, then Congratulations!! 🎉🎀, you don't have to worry about MULTIPLICITY or threading. But wait 😳, a surprising number of libc functions do depend on data global to the process in some way that may not be immediately obvious. For example, calling "strtok(3)" changes the global state of a process, and thus needs special attention 💀.

The section 3 libc uses that we know about that have MULTIPLICITY and/or multi-thread issues are:

okay bestie, buckle in, because this next bit is a mega list and it is not playtime. 💀

These are all the libc functions, variables and macros that Perl considers not safe to use — like, at all, on some platform or another. Read 'em and weep:

        addmntent()             getrpcent_r()        re_exec()
        alphasort()             getrpcport()         regcomp()
        asctime()               getservbyname()      regerror()
        asctime_r()             getservbyname_r()    regexec()
        asprintf()              getservbyport()      res_nclose()
        atof()                  getservbyport_r()    res_ninit()
        atoi()                  getservent()         res_nquery()
        atol()                  getservent_r()       res_nquerydomain()
        atoll()                 getspent()           res_nsearch()
        basename()              getspent_r()         res_nsend()
        btowc()                 getspnam()           rexec()
        catgets()               getspnam_r()         rexec_af()
        catopen()               getttyent()          rpmatch()
        clearenv()              getttynam()          ruserok()
        clearerr_unlocked()     getusershell()       ruserok_af()
        crypt()                 getutent()           scandir()
        crypt_gensalt()         getutid()            scanf()
        crypt_r()               getutline()          secure_getenv()
        ctermid()               getutxent()          seed48()
        ctermid_r()             getutxid()           seed48_r()
        ctime()                 getutxline()         setaliasent()
        ctime_r()               getwc()              setcontext()
        cuserid()               getwchar()           setenv()
        daylight                getwchar_unlocked()  setfsent()
        dbm_clearerr()          getwc_unlocked()     setgrent()
        dbm_close()             glob()               setgrent_r()
        dbm_delete()            gmtime()             sethostent()
        dbm_error()             gmtime_r()           sethostent_r()
        dbm_fetch()             grantpt()            sethostid()
        dbm_firstkey()          hcreate()            setkey()
        dbm_nextkey()           hcreate_r()          setlocale()
        dbm_open()              hdestroy()           setlocale_r()
        dbm_store()             hdestroy_r()         setlogmask()
        dirname()               hsearch()            setnetent()
        dlerror()               hsearch_r()          setnetent_r()
        dprintf()               iconv()              setnetgrent()
        drand48()               iconv_open()         setprotoent()
        drand48_r()             inet_addr()          setprotoent_r()
        ecvt()                  inet_aton()          setpwent()
        encrypt()               inet_network()       setpwent_r()
        endaliasent()           inet_ntoa()          setrpcent()
        endfsent()              inet_ntop()          setservent()
        endgrent()              inet_pton()          setservent_r()
        endgrent_r()            initgroups()         setspent()
        endhostent()            initstate_r()        setstate_r()
        endhostent_r()          innetgr()            setttyent()
        endnetent()             iruserok()           setusershell()
        endnetent_r()           iruserok_af()        setutent()
        endnetgrent()           isalnum()            setutxent()
        endprotoent()           isalnum_l()          sgetspent()
        endprotoent_r()         isalpha()            sgetspent_r()
        endpwent()              isalpha_l()          shm_open()
        endpwent_r()            isascii()            shm_unlink()
        endrpcent()             isascii_l()          siginterrupt()
        endservent()            isblank()            sleep()
        endservent_r()          isblank_l()          snprintf()
        endspent()              iscntrl()            sprintf()
        endttyent()             iscntrl_l()          srand48()
        endusershell()          isdigit()            srand48_r()
        endutent()              isdigit_l()          srandom_r()
        endutxent()             isgraph()            sscanf()
        erand48()               isgraph_l()          ssignal()
        erand48_r()             islower()            strcasecmp()
        err()                   islower_l()          strcasestr()
        error()                 isprint()            strcoll()
        error_at_line()         isprint_l()          strerror()
        errx()                  ispunct()            strerror_l()
        ether_aton()            ispunct_l()          strerror_r()
        ether_ntoa()            isspace()            strfmon()
        execlp()                isspace_l()          strfmon_l()
        execvp()                isupper()            strfromd()
        execvpe()               isupper_l()          strfromf()
        exit()                  iswalnum()           strfroml()
        __fbufsize()            iswalnum_l()         strftime()
        fcloseall()             iswalpha()           strftime_l()
        fcvt()                  iswalpha_l()         strncasecmp()
        fflush_unlocked()       iswblank()           strptime()
        fgetc_unlocked()        iswblank_l()         strsignal()
        fgetgrent()             iswcntrl()           strtod()
        fgetpwent()             iswcntrl_l()         strtof()
        fgetspent()             iswdigit()           strtoimax()
        fgets_unlocked()        iswdigit_l()         strtok()
        fgetwc()                iswgraph()           strtol()
        fgetwc_unlocked()       iswgraph_l()         strtold()
        fgetws()                iswlower()           strtoll()
        fgetws_unlocked()       iswlower_l()         strtoq()
        fnmatch()               iswprint()           strtoul()
        forkpty()               iswprint_l()         strtoull()
        __fpending()            iswpunct()           strtoumax()
        fprintf()               iswpunct_l()         strtouq()
        __fpurge()              iswspace()           strverscmp()
        fputc_unlocked()        iswspace_l()         strxfrm()
        fputs_unlocked()        iswupper()           swapcontext()
        fputwc()                iswupper_l()         swprintf()
        fputwc_unlocked()       iswxdigit()          swscanf()
        fputws()                iswxdigit_l()        sysconf()
        fputws_unlocked()       isxdigit()           syslog()
        fread_unlocked()        isxdigit_l()         system()
        fscanf()                jrand48()            tdelete()
        __fsetlocking()         jrand48_r()          tempnam()
        fts_children()          l64a()               tfind()
        fts_read()              lcong48()            timegm()
        ftw()                   lcong48_r()          timelocal()
        fwprintf()              lgamma()             timezone
        fwrite_unlocked()       lgammaf()            tmpnam()
        fwscanf()               lgammal()            tmpnam_r()
        gamma()                 localeconv()         tolower()
        gammaf()                localtime()          tolower_l()
        gammal()                localtime_r()        toupper()
        getaddrinfo()           login()              toupper_l()
        getaliasbyname()        login_tty()          towctrans()
        getaliasbyname_r()      logout()             towlower()
        getaliasent()           logwtmp()            towlower_l()
        getaliasent_r()         lrand48()            towupper()
        getchar_unlocked()      lrand48_r()          towupper_l()
        getcontext()            makecontext()        tsearch()
        getc_unlocked()         mallinfo()           ttyname()
        get_current_dir_name()  MB_CUR_MAX           ttyname_r()
        getdate()               mblen()              ttyslot()
        getdate_r()             mbrlen()             twalk()
        getenv()                mbrtowc()            twalk_r()
        getfsent()              mbsinit()            tzname
        getfsfile()             mbsnrtowcs()         tzset()
        getfsspec()             mbsrtowcs()          ungetwc()
        getgrent()              mbstowcs()           unsetenv()
        getgrent_r()            mbtowc()             updwtmp()
        getgrgid()              mcheck()             utmpname()
        getgrgid_r()            mcheck_check_all()   va_arg()
        getgrnam()              mcheck_pedantic()    valloc()
        getgrnam_r()            mktime()             vasprintf()
        getgrouplist()          mprobe()             vdprintf()
        gethostbyaddr()         mrand48()            verr()
        gethostbyaddr_r()       mrand48_r()          verrx()
        gethostbyname()         mtrace()             versionsort()
        gethostbyname2()        muntrace()           vfprintf()
        gethostbyname2_r()      nan()                vfscanf()
        gethostbyname_r()       nanf()               vfwprintf()
        gethostent()            nanl()               vprintf()
        gethostent_r()          newlocale()          vscanf()
        gethostid()             nftw()               vsnprintf()
        getlogin()              nl_langinfo()        vsprintf()
        getlogin_r()            nrand48()            vsscanf()
        getmntent()             nrand48_r()          vswprintf()
        getmntent_r()           openpty()            vsyslog()
        getnameinfo()           perror()             vwarn()
        getnetbyaddr()          posix_fallocate()    vwarnx()
        getnetbyaddr_r()        printf()             vwprintf()
        getnetbyname()          profil()             warn()
        getnetbyname_r()        psiginfo()           warnx()
        getnetent()             psignal()            wcrtomb()
        getnetent_r()           ptsname()            wcscasecmp()
        getnetgrent()           putchar_unlocked()   wcschr()
        getnetgrent_r()         putc_unlocked()      wcscoll()
        getopt()                putenv()             wcsftime()
        getopt_long()           putpwent()           wcsncasecmp()
        getopt_long_only()      putspent()           wcsnrtombs()
        getpass()               pututline()          wcsrchr()
        getprotobyname()        pututxline()         wcsrtombs()
        getprotobyname_r()      putwc()              wcstod()
        getprotobynumber()      putwchar()           wcstof()
        getprotobynumber_r()    putwchar_unlocked()  wcstoimax()
        getprotoent()           putwc_unlocked()     wcstold()
        getprotoent_r()         pvalloc()            wcstombs()
        getpw()                 qecvt()              wcstoumax()
        getpwent()              qfcvt()              wcswidth()
        getpwent_r()            querylocale()        wcsxfrm()
        getpwnam()              rand()               wctob()
        getpwnam_r()            random_r()           wctomb()
        getpwuid()              rcmd()               wctrans()
        getpwuid_r()            rcmd_af()            wctype()
        getrpcbyname()          readdir()            wcwidth()
        getrpcbyname_r()        readdir64()          wordexp()
        getrpcbynumber()        readdir64_r()        wprintf()
        getrpcbynumber_r()      readdir_r()          wscanf()
        getrpcent()             re_comp()            wsetlocale()

iconic list, terrifying list, same thing 💅

---

If you clock some other function that's unsafe on some platform or another and it's not up there? Bestie, tell us — file a bug report at <https://github.com/Perl/perl5/issues>. We wanna know. 🫶

---

Real talk though: some of these are only a problem under certain conditions. Under MULTIPLICITY a bunch of them are totally fine — they only get sketchy when threading is in the mix. So the vibe check is:

• If something you're using doesn't show up in that list above? We're pretty confident it's MULTIPLICITY-safe and thread-safe on all platforms. No notes. ✨

---

And one lil' asterisk, because of course there's an asterisk 🙈

Everything in that big list up there is a function call — except these four, which are not functions at all:

daylight  MB_CUR_MAX  timezone  tzname

Those are the little gremlins that don't play by function rules. 👑

---

So now that we know what is dangerous, there are three main approaches to coping with issues involving these constructs, and each one is built for different circumstances:

• Just... don't use them. 💀 A bunch of them have glow-up alternatives, and the list up in "libc functions to avoid" is your cheat sheet — swap your usages for the thread-friendly ones. Like, I/O? Do it through perlapio. Periodt.
• If you must use them, okay, many (but not all, bestie, not all) are fine as long as their use stays locked inside a single thread that isn't beefing with conflicting uses in other threads. You're gonna have to read their man pages super closely for this, and heads up: vendor docs are often mad imprecise. 🙈
• Do all your business before any other code can change stuff. If you make changes, change them back before you return. Respect the timeline. ✨
• Save the result of a global-info query into a per-instance area before you let another instance execute. Then you can vibe with it at your leisure. Could be an automatic C variable for non-pointers, or something like what's described up in "Safely Storing Static Data in XS" in perlxs.

Without threading, you never have to stress about the system interrupting you to hand control to another thread. With threading? You're gonna need mutexes, and you're gonna need to be very concerned about the possibility of deadlock. 😭

---

🚫 Functions always unsuitable for use under multi-threads

A few functions are just considered totally unsuited for a multi-thread environment. These must be called only during single-thread operation. No exceptions, no cap.

 endusershell()    @getaliasent()      muntrace()   rexec()
 ether_aton()      @getrpcbyname()     profil()     rexec_af()
 ether_ntoa()      @getrpcbynumber()   rcmd()       setusershell()
 fts_children()    @getrpcent()        rcmd_af()    ttyslot()
 fts_read()         getusershell()     re_comp()
@getaliasbyname()   mtrace()           re_exec()

The @ up there marks the functions that have preferred alternatives available on some platforms — and those alternatives may be suitable for multi-thread use. 👑

---

🌅 Functions which must be called at least once before starting threads

Some functions do initialization on their first call that has to happen while you're still in a single-thread environment. But subsequent calls are thread-safe when executed in a critical section. So yeah — they gotta be called at least once before you switch to multi-threads:

 getutent()  getutline()  getutxid()    mallinfo()  valloc()
 getutid()   getutxent()  getutxline()  pvalloc()

---

✅ Functions that are thread-safe when called with appropriate arguments

Some of these are thread-safe if you call them with arguments that comply with certain restrictions — and luckily the restrictions are easy to meet. They are:

 ctermid()        mbrlen()      mbsrtowcs()  wcrtomb()
 cuserid()        mbrtowc()     tmpnam()     wcsnrtombs()
 error_at_line()  mbsnrtowcs()  va_arg()     wcsrtombs()

Peep the man pages of each for the deets. (And for completeness — this list includes functions you shouldn't be using anyway, for other reasons. 🙃)

---

⚡ Functions vulnerable to signals

Some functions are vulnerable to asynchronous signals. These are:

 getlogin()    getutid()    getutxid()    login()   pututline()  updwtmp()
 getlogin_r()  getutline()  getutxline()  logout()  pututxline() wordexp()
 getutent()    getutxent()  glob()        logwtmp() sleep()

Some libc's implement system() thread-safely. But in others, it's also got signal issues. iykyk 🌈

---

🌍 General issues with thread-safety

Some libc functions use and/or modify a global state — like, a database. The libc functions just presume there's only one instance at a time operating on that database. If more than one does? Unpredictable results, babe, even if nobody changes the database. Like, typically there's a global iterator for such a database and libc is the one maintaining it — so every new read from any instance advances it, which means no instance will ever see all the entries. 😭 The only way to make these thread-safe is to hold an exclusive lock on a mutex from the open call all the way through the close. You are advised to not use such databases from more than one instance at a time.

Other examples of functions that use a global state include pseudo-random number generators. Some libc implementations of rand(), for example, may share the data across threads; others may have per-thread data. The shared ones are gonna give you unreproducible results, because the threads will vary in their timings and interactions. Maybe that's what you want. Maybe it's not. (This particular function is a candidate to be removed from the POSIX Standard because of these issues. 💀)

Functions that output to a stream also count as thread-unsafe when locking isn't done. But honestly the typical consequences are just that the data comes out in an unpredictable order — and that outcome may be totally acceptable to you. vibe check passed ✨

Since the current working directory is global to a process, all instances depend on it. One instance doing a chdir(2) affects all the other instances. In a multi-threaded environment, any libc call that expects the directory to not change for the duration of its execution will have undefined results if another thread interrupts it at just the wrong time and changes the directory. The man pages only list one such call, nftw(). But there may be other issues lurking. 👀

---

🔁 Reentrant equivalent functions

Some functions that are problematic with regard to MULTIPLICITY have reentrant versions (on some or all platforms) that are better suited, with fewer (perhaps no) races when run under threads. 🎀

Some of these reentrant functions are available on all platforms and should always be used anyway — they're in the lists directly under "libc functions to avoid".

Others may not be available on some platforms, or have issues that make them undesirable to use even when they are available. Or it may just be more complicated and tedious to use the reentrant version. For those, perl has a mechanism for automatically substituting the reentrant version when it's available and desirable, while hiding the complications from your code. This feature is enabled by default for code in the Perl core and its extensions. To enable it in other XS modules:

#define PERL_REENTRANT

It's simpler for you to use the unpreferred version in your code and rely on this feature to do the better thing — partly because no substitution is done if the alternative isn't available or desirable on the platform, and also not if threads aren't enabled. You just write as if there weren't threads, and you get the better behavior without having to think about it. main character energy tbh 💅

On some platforms the safer library functions may fail if the result buffer is too small (like, the user group databases can be pretty large, and the reentrant functions may have to carry around a full snapshot of those databases). Perl will start with a small buffer, but keep retrying and growing the result buffer until the result fits. If this limitless growing sounds bad to you for security or memory consumption reasons, you can recompile Perl with PERL_REENTRANT_MAXSIZE #defined to the maximum number of bytes you'll allow. 🫶

Below is a list of the non-reentrant functions and their reentrant alternatives. This substitution is done even on functions you shouldn't be using in the first place — those are marked by a *. You should instead use the alternate given in the lists directly under "libc functions to avoid".

Even so, some of the preferred alternatives are considered obsolete or otherwise unwise to use on some platforms. Those are marked with a ?. Also, some alternatives aren't Perl-defined functions and aren't in the POSIX Standard, so they won't be widely available — those are marked with a ~. (Remember: the automatic substitution only happens when they're available and desirable, so you can just use the unpreferred alternative. no stress. 🌸)

 *asctime()             ?asctime_r()
  crypt()               ~crypt_r()
  ctermid()             ~ctermid_r()
 *ctime()               ?ctime_r()
  endgrent()           ?~endgrent_r()
  endhostent()         ?~endhostent_r()
  endnetent()          ?~endnetent_r()
  endprotoent()        ?~endprotoent_r()
  endpwent()           ?~endpwent_r()
  endservent()         ?~endservent_r()
  getgrent()            ~getgrent_r()
  getgrgid()             getgrgid_r()
  getgrnam()             getgrnam_r()
  gethostbyaddr()       ~gethostbyaddr_r()
  gethostbyname()       ~gethostbyname_r()
  gethostent()          ~gethostent_r()
  getlogin()             getlogin_r()
  getnetbyaddr()        ~getnetbyaddr_r()
  getnetbyname()        ~getnetbyname_r()
  getnetent()           ~getnetent_r()
  getprotobyname()      ~getprotobyname_r()
  getprotobynumber()    ~getprotobynumber_r()
  getprotoent()         ~getprotoent_r()
  getpwent()            ~getpwent_r()
  getpwnam()             getpwnam_r()
  getpwuid()             getpwuid_r()
  getservbyname()       ~getservbyname_r()
  getservbyport()       ~getservbyport_r()
  getservent()          ~getservent_r()
  getspnam()            ~getspnam_r()
  gmtime()               gmtime_r()
  localtime()            localtime_r()
  readdir()             ?readdir_r()
  readdir64()           ~readdir64_r()
  setgrent()           ?~setgrent_r()
  sethostent()         ?~sethostent_r()
 *setlocale()          ?~setlocale_r()
  setnetent()          ?~setnetent_r()
  setprotoent()        ?~setprotoent_r()
  setpwent()           ?~setpwent_r()
  setservent()         ?~setservent_r()
 *strerror()             strerror_r()
 *tmpnam()              ~tmpnam_r()
  ttyname()              ttyname_r()

The Perl-furnished items are documented in perlapi. 📚

---

💖 The bottom line is:

For items marked *

• Replace all uses of these with the preferred alternative given in the lists directly under "libc functions to avoid". No negotiating. 🎯

For the remaining items

• If you really need to use these functions, you have two choices:
  • If you #define PERL_REENTRANT — use the function in the first column as-is, and let perl do the work of substituting the function in the right column if it's available on the platform and if it's deemed suitable for use. You should look at the man pages for both versions to find any other gotchas. 👀
  • If you don't enable automatic substitution — you should examine the application's code to determine if the column 1 function presents a real problem under threads, given the circumstances it's used in. You can go directly to the column 2 replacement, but beware of the ones that are marked. Some of those may be nonexistent or flaky on some platforms. fr fr, tread carefully. 💀

✨ Functions that need the environment to be constant ✨

okay so bestie, the environment is global to a process — meaning every single instance is riding the same one. One instance changes it, everybody else feels it. No exceptions, no takebacks. 💀

Under threads it gets spicier: any libc call that assumes the environment is gonna sit still for the whole duration of its execution gets undefined results if another thread interrupts it at exactly the wrong moment and changes things. Rude of them, honestly. These are the functions whose man pages flag them as sensitive to that:

• catopen()
• ctime()
• ctime_r()
• endhostent()
• endhostent_r()
• endnetent()
• endnetent_r()
• execlp()
• execvp()
• execvpe()
• fnmatch()
• getaddrinfo()
• get_current_dir_name()
• getdate()
• getdate_r()
• getenv()
• gethostbyaddr()
• gethostbyaddr_r()
• gethostbyname()
• gethostbyname2()
• gethostbyname2_r()
• gethostbyname_r()
• gethostent()
• gethostent_r()
• gethostid()
• getnameinfo()
• getnetbyname()
• getnetent()
• getopt()
• getopt_long()
• getopt_long_only()
• getrpcport()
• glob()
• gmtime()
• gmtime_r()
• localtime()
• localtime_r()
• mktime()
• newlocale()
• regerror()
• secure_getenv()
• sethostent()
• sethostent_r()
• setlocale()
• setlocale_r()
• setnetent()
• setnetent_r()
• strftime()
• strptime()
• sysconf()
• syslog()
• tempnam()
• timegm()
• timelocal()
• tzset()
• vsyslog()

And ngl, a lot of these are problematic under threads for other reasons too. So fr fr, go read the man page for any of them you're actually using. 🔍

Perl's got your back though: it defines the mutexes ENV_READ_LOCK and ENV_READ_UNLOCK, and you wrap your calls to these functions in them. 🫶

⚠️ but bestie, please think about deadlock. Like, genuinely think about it. It's expected that a different mechanism will be in place and preferred for Perl v5.42. So this is giving ✨ transitional era ✨.

---

🌍 Locale-specific issues 🌍

history time, sit down. 🍓

C language programs originally had a single locale, global to the entire process. Turns out that was not it for a lot of purposes, so later extensions changed things up — first Windows, then POSIX 2008. iconic evolution honestly.

• On Windows: you can switch any thread, at any time, to run with either a per-thread locale or the global one, using a special new libc function.
• On POSIX: the original API only touches the global locale, but there's a whole brand-new API for manipulating either per-thread locales or the global one. Just like Windows (but through the new API), a thread can be flipped at any moment to work on the global locale, or a per-thread one. 🦋

Here's the tea: when one instance changes the global locale, every other instance using the global locale is affected. And almost all the locale-related functions in the list directly under "Dealing with embedded perls and threads" have undefined behavior if another thread interrupts their execution and changes the locale mid-flight. Under threads, another thread could do exactly that. not a vibe. 😭

BUT — on systems that have per-thread locales, starting with Perl v5.28, perl uses them after initialization. The global locale is not used except if XS code has called switch_to_global_locale(). And calling that affects only the thread that called it. 👑

So if a maximum of one instance is using the global locale, no other instances are affected, the locale of concurrently executing functions in other threads doesn't change, and this whole thing becomes a non-issue. periodt. 💅

The C preprocessor symbol USE_THREAD_SAFE_LOCALE will be defined if per-thread locales are available and perl has been compiled to use them.

🙈 fair warning: the implementation of per-thread locales on some platforms — like most *BSD-based ones — is so buggy that the perl hints files for them deliberately turn off the possibility of using them. not me being shady, that's just what the page says.

The converse situation, bestie: on systems with only a global locale, having different threads use different locales is not likely to work well; and changing the locale is dangerous, often leading to crashes. 💀

Perl has extensive code to work as well as possible on both types of systems. And your move? Always use Perl_setlocale() to change and query the locale, because it portably works across the whole range of possibilities. that's the one. 🎀

---

👀 SEE ALSO 👀

• perlapi
• perlapio
• perlguts
• perlxs

---

okay and that's a wrap on the whole page, bestie!! 🌈✨ this was perl v5.42.3, dated 2026-08-03, and it's the PERLCLIB(1) page — go forth and be thread-safe, you absolute icon. 💖🦋👑