PERLCLIB(1perl)
💖 perlclib 💖
okay so bestie, this is perlclib, and it lives in the Perl Programmers Reference Guide. it's the page all about how perl talks to the standard C library, and ngl it's a whole journey. part 1 of 7, so buckle up, we are NOT done yet 💅
🌸 NAME 🌸
perlclib — Interacting with standard C library functions
✨ DESCRIPTION ✨
okay so here's the vibe: the perl interpreter? written in C. your XS code? also expands to C. and inevitably, all that C is gonna call stuff from the C library, aka libc. this doc is the group chat where we give you the guidance on interfacing with that library. 🫶
one thing perl porters should clock: perl doesn't really use that much of the C standard library internally. like, you'll see very little use of the ctype.h functions in there, fr fr. why? because perl tends to reimplement or abstract standard library functions, so that we know exactly how they're going to operate. no mystery, no surprises, just vibes we control. 👑
🚫 libc functions to avoid 🚫
so there are many many libc functions out there. most of them are fair game, lowkey totally fine to use. but some are not. here's the tea on why some of them gotta go:
- they'll probably interfere with the perl interpreter's functioning — like its bookkeeping, or signal handling, or memory allocation, or honestly any number of harmful things. it's giving chaos 😭
- 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's an alternative that is, and it's 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. so if it's just as easy to use something that can be used under threads, it's better to use that now, just in case. main character foresight, honestly. ✨
- with 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's likely better to place the string in an SV and use the Perl SV string handling functions, which contain extensive logic to deal with this. sv brain > raw char star brain 🧚
- with functions that deal with numbers, complications may arise because the numbers get too big or too 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. i'm turning the tables into bullet lists because tables in a terminal are, respectfully, not iconic. 💅
📖 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. and bestie, don't forget — 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:
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)(Deprecated)fflush(stream)→PerlIO_flush(perlio)fclose(stream)→PerlIO_close(perlio)
🔁 File Input and Output 🔁
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)
heads up though: the PerlIO equivalents of fread and fwrite are slightly different from their C library counterparts:
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)
and there is no equivalent to fgets (or the deprecated gets 😭). you should use sv_gets instead:
fgets(s, n, stream)→sv_gets(sv, perlio, append)
📍 File Positioning 📍
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 🧠
t* p = malloc(n)→Newx(p, n, t)t* p = calloc(n, s)→Newxz(p, n, t)(But see [1] below)p = realloc(p, n)→Renew(p, n, t)
⚠️ it is not portable to try to allocate 0 bytes; allocating 1 or more is portable. and never pass pointers betweenNewx,Renew,Safefreeand libc equivalentsmalloc,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. this is the scary part bestie. respect it. 💀
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. yeah. they flipped it. keep your eyes open. 👀
memset(dst, 0, n * sizeof(t))→Zero(dst, n, t)(But see [1] below)memzero(dst, 0)→Zero(dst, n, char)(But see [1] below)free(p)→Safefree(p)strdup(p)→savepv(p)strndup(p, n)→savepvn(p, n)(Hey,strndupdoesn't exist!)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)
but 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 alert:printf(),sprintf(), etc. are buggy before glibc version 2.17. they won't allow a%.sformat 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%sand its operand are simply skipped without any notice. 😭 silent skipping is the worst kind of skipping.<https://sourceware.org/bugzilla/show_bug.cgi?id=6530>
[1] sometimes instead of zeroing the allocated memory, you should consider "poisoning" the data to catch uninitialized uses of it. see "Catching hidden flaws" in perlhacktips. 🧪
🔤 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 below return values based on the current locale. use the entries in the final column for that functionality. the other two columns always 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. 💫
isalnum(c)→ ASCII:isALPHANUMERIC(c)· Latin1:isALPHANUMERIC_L1(c)· locale:isALPHANUMERIC_LC(c)isalpha(c)→ ASCII:isALPHA(c)· Latin1:isALPHA_L1(c)· locale:isALPHA_LC(u )isascii(c)→ ASCII:isASCII(c)· locale:isASCII_LC(c)isblank(c)→ ASCII:isBLANK(c)· Latin1:isBLANK_L1(c)· locale:isBLANK_LC(c)iscntrl(c)→ ASCII:isCNTRL(c)· Latin1:isCNTRL_L1(c)· locale:isCNTRL_LC(c)isdigit(c)→ ASCII:isDIGIT(c)· Latin1:isDIGIT_L1(c)· locale:isDIGIT_LC(c)isgraph(c)→ ASCII:isGRAPH(c)· Latin1:isGRAPH_L1(c)· locale:isGRAPH_LC(c)islower(c)→ ASCII:isLOWER(c)· Latin1:isLOWER_L1(c)· locale:isLOWER_LC(c)isprint(c)→ ASCII:isPRINT(c)· Latin1:isPRINT_L1(c)· locale:isPRINT_LC(c)ispunct(c)→ ASCII:isPUNCT(c)· Latin1:isPUNCT_L1(c)· locale:isPUNCT_LC(c)isspace(c)→ ASCII:isSPACE(c)· Latin1:isSPACE_L1(c)· locale:isSPACE_LC(c)isupper(c)→ ASCII:isUPPER(c)· Latin1:isUPPER_L1(c)· locale:isUPPER_LC(c)isxdigit(c)→ ASCII:isXDIGIT(c)· Latin1:isXDIGIT_L1(c)· locale:isXDIGIT_LC(c)tolower(c)→ ASCII:toLOWER(c)· Latin1:toLOWER_L1(c)toupper(c)→ ASCII: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 they interfere with Perl's internal handling. hard pass.
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. 💅
(there is no entry in the Latin1 column for isascii even though there is an isASCII_L1, which is identical to isASCII; the latter name is clearer. there is 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.) 🌈
okay that's the whole first chunk bestie, and there's still so much more coming — stay tuned, we're not even close to done. 💖
Like, the libc caseless comparisons are genuinely crippled 😭 no cap. Unicode hands you a way richer set, because it works off this whole concept of folding. So if you need more than plain equality/non-equality, the move is: store your strings in an SV and let the SV functions do the comparing. Same energy for collation. 💅
--
✨ stdlib.h functions ✨
Okay so here's the swap list, one glow-up per line. The Instead Of on the left, the Use on the right, no cap:
atof(s)— 🚫 not this. Usemy_atof(s)orAtof(s)atoi(s)— usegrok_atoUV(s, &uv, &e)atol(s)— usegrok_atoUV(s, &uv, &e)strtod(s, &p)— useStrtod(s, &p)strtol(s, &p, n)— useStrtol(s, &p, b)strtoul(s, &p, n)— useStrtoul(s, &p, b)
but fr fr, heads up: even the alternative functions are still subject to locale 😭 — see "Dealing with locales" further down, it's required reading bestie.
The typical use is that you do your range checks on uv before you cast it, like this:
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 */
}(yes that's verbatim from the page, brace situation and all — I am ✨not✨ editing it, that's literally what it says 🙈)
Also!! grok_bin, grok_hex, and grok_oct are chilling in numeric.c, and they convert strings that represent numbers in their respective bases into NVs. Note that grok_atoUV() doesn't handle negative inputs, and it doesn't handle leading whitespace either — it's being purposefully strict, and honestly? iconic of it. 👑
🌈 Miscellaneous functions 🌈
You should not even want to use setjmp.h functions, bestie. But if you truly think you do… use the JMPENV stack in scope.h instead. periodt.
(also: some of these names come with a little ~ glued to the front — that's exactly how the list writes them, so keep the ~, don't vibe-check it away 💅)
~asctime()— usePerl_sv_strftime_tm()~asctime_r()— usePerl_sv_strftime_tm()chsize()— usemy_chsize()~ctime()— usePerl_sv_strftime_tm()~ctime_r()— usePerl_sv_strftime_tm()~cuserid()— 🚫 DO NOT USE; see its man pagedirfd()— usemy_dirfd()duplocale()— usePerl_setlocale()~ecvt()— usemy_snprintf()~endgrent_r()— useendgrent()~endhostent_r()— useendhostent()~endnetent_r()— useendnetent()~endprotoent_r()— useendprotoent()~endpwent_r()— useendpwent()~endservent_r()— useendservent()~endutent()— useendutxent()exit(n)— usemy_exit(n)🫶~fcvt()— usemy_snprintf()freelocale()— usePerl_setlocale()~ftw()— usenftw()getenv(s)— usePerlEnv_getenv(s)~gethostbyaddr()— usegetaddrinfo()~gethostbyname()— usegetnameinfo()~getpass()— 🚫 DO NOT USE; see its man page~getpw()— usegetpwuid()~getutent()— usegetutxent()~getutid()— usegetutxid()~getutline()— usegetutxline()~gsignal()— 🚫 DO NOT USE; see its man pagelocaleconv()— usePerl_localeconv()mblen()— usembrlen()mbtowc()— usembrtowc()newlocale()— usePerl_setlocale()pclose()— usemy_pclose()popen()— usemy_popen()~pututline()— usepututxline()~qecvt()— usemy_snprintf()~qfcvt()— usemy_snprintf()querylocale()— usePerl_setlocale()int rand()— usedouble Drand01()srand(n)— instead do this:
{ seedDrand01((Rand_seed_t)n);
PL_srand_called = TRUE; }~readdir_r()— usereaddir()realloc()— usesaferealloc(),Renew()orRenewc()~re_comp()— useregcomp()~re_exec()— useregexec()~rexec()— usercmd()~rexec_af()— usercmd()setenv(s, val)— usemy_setenv(s, val)~setgrent_r()— usesetgrent()~sethostent_r()— usesethostent()setlocale()— usePerl_setlocale()setlocale_r()— usePerl_setlocale()~setnetent_r()— usesetnetent()~setprotoent_r()— usesetprotoent()~setpwent_r()— usesetpwent()~setservent_r()— usesetservent()~setutent()— usesetutxent()sigaction()— usersignal(signo, handler)~siginterrupt()— usersignal()with theSA_RESTARTflag insteadsignal(signo, handler)— usersignal(signo, handler)~ssignal()— 🚫 DO NOT USE; see its man pagestrcasecmp()— use a PerlfoldEQ-family functionstrerror()— usesv_string_from_errnum()strerror_l()— usesv_string_from_errnum()strerror_r()— usesv_string_from_errnum()strftime()— usePerl_sv_strftime_tm()strtod()— usemy_strtod()orStrtod()system(s)— Don't. 👀 Look atpp_systemor usemy_popen.~tempnam()— usemkstemp()~tmpnam()— usemkstemp()tmpnam_r()— usemkstemp()uselocale()— usePerl_setlocale()vsnprintf()— usemy_vsnprintf()wctob()— usewcrtomb()wctomb()— usewcrtomb()wsetlocale()— usePerl_setlocale()
The Perl-furnished alternatives are documented in perlapi, which you should be perusing anyway to see what all is available to you 💖 (it's giving infinite scroll, in a good way).
And the lists are incomplete bestie. So when you reach for a function that isn't listed, use your brain: does it seem likely to interfere with Perl? Then don't. 😭
💖 Dealing with locales 💖
Like it or not — and I fear it's not — your code will be executed in the context of a locale, same as 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()Ok bestie, that's the roster 💅 and just so we're clear: this list does not include the functions that actually manipulate the locale, like setlocale(). Those are a whole different vibe. 🙈
So if any of these functions get called — directly or indirectly — from your code, then babe, you are affected by the current locale. No cap. 🫠
The first thing to know about this list is that there are better alternatives to many of these functions, and it's highly likely you should be using those instead. See "libc functions to avoid" up above ⬆️ — and yes, that includes using Perl IO perlapio. 👑
The second thing to know is that Perl is documented to not pay attention to the current locale at all, EXCEPT for code that runs inside the scope of a use locale statement. So if you break that rule?? You may literally be creating bugs, depending on the application. 💀 Not cute. Not the move.
The next thing to know is that 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 (that's the radix character) is a dot (U+002E: FULL STOP), and that strings of integer numbers don't get chopped into groups. Like, 1,000,000 in an American locale means a million — and your code is probably not expecting those commas. 😭
The good news? Normally — as of Perl v5.22 — your code gets called with the locale set so those expectations ARE met. ✨ You'd have to take explicit action to change that (and we'll spill that tea a little ways below). Perl pulls this off by simply not switching 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, when appropriate, and then switch right back. 🎀
But say you, for some reason, need to do it yourself — from C and XS code the easiest way is the macro "WITH_LC_NUMERIC_SET_TO_NEEDED" in perlapii. You can wrap that macro around an entire block of code you want executed in the correct environment. The bottom line? Your code will lowkey just work as expected here, and you won't have to do a single thing. 🫶
That leaves the remaining functions. 🙃 Your code gets called with all but the numeric locale portions set to the underlying locale. Often the locale is of not much import to your code and you won't have to do anything either — things will just work out. 🌈 But you should go read the man pages of whichever ones you use, to verify that. A lot of the time Perl has better ways of doing the exact same functionality. Consider using SVs and their access routines instead of calling the low-level functions that, for example, figure out how many bytes are in a UTF-8 encoded character. 💅
You can figure out whether you've been called from inside the scope of a use locale by using the boolean macro "IN_LOCALE" in perlapi. 🔍
And if you need to not be in the underlying locale, you can call "Perl_setlocale" in perlapi to temporarily swap it to the one you need (likely the "C" locale), then change it right back before returning. 🌀
⚠️ Heads up though: this can be very problematic on threaded perls on some platforms. See "Dealing with embedded perls and threads". 😭
Now, a problem with changing the locale of just one category is that mojibake can pop up on some platforms if the LC_CTYPE category and the changed one aren't the same. 👹 On the platforms where that's not an issue, the preprocessor directive LIBC_HANDLES_MISMATCHED_CTYPE will be defined. Otherwise you might have to change more than one category to correctly accomplish your task. And honestly? There are a TON of locale combinations where the mojibake probably just won't happen — so you won't even get confronted with this until your code is out there running in the field, being used by someone who doesn't speak your language very well. 💀 Scary hours fr fr.
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, no punctuation separating groups of digits" thing. That action? Calling the function "switch_to_global_locale" in perlapi. 🎯 And that's the whole vibe, bestie. 🦋
So like… switch_to_global_locale() got born specifically to deal with the "Tk" library 🎀 — though honestly it's general enough to handle other messy situations like that too. The thing is, "Tk" goes and changes the global locale to match whatever it expects (newer versions let you turn that off, bless 🙏). Which immediately beefs with Perl, who also thinks it's the one running the locale 😭. Calling this function is basically you telling Perl "bestie, stand down, yield control." Then calling "sync_locale" in perlapi tells Perl to grab the wheel again — accepting literally whatever the locale got changed to while it wasn't looking. 👑
But heads up fr fr: if your code runs during that in-between era, every single part of the locale is the raw underlying values. Numbers? Radix character? Grouping? You are on your own, bestie 💀.
If you ever find yourself stuck in that situation: keep the gap between those two function calls as short as humanly possible and don't do any calculations until perl has control back. Periodt.
Also, super important: perl needs to know about every possible locale category on the platform, even the ones that look like they're not being used in your program 👀. Perl already knows all the Linux ones. If your platform's got extras, you can submit an issue at https://github.com/Perl/perl5/issues so it gets added in the next release ✨. In the meantime? You can literally edit the Perl source to teach it about the category, then recompile — search for instances of, like, LC_PAPER in the source and use that as a template to add the one that's missing. DIY queen 🛠️💅
And yep — there are further complications once you go multi-threaded. Keep reading 👇
🧵 Dealing with embedded perls and threads 🧵
Okay so plot twist: you can totally embed a Perl interpreter inside a bigger program 🫶. See perlembed.
MULTIPLICITY is how that's pulled off internally — it's described in "How multiple interpreters and concurrency are supported" in perlguts. And yes, multiple Perl interpreters can be embedded at once, no cap.
You can also compile perl to support threading. See perlthrtut. Perl's threading implementation requires MULTIPLICITY, but not the other way around (MULTIPLICITY does not require threading) 🌸.
Now, MULTIPLICITY without threading means only one thing runs at a time — so no concurrency issues there 🙌. BUT each component or instance can still mess with the global state and lowkey interfere with how other instances execute 😬. 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 and doesn't depend on any of their values — then Congratulations!! 🎉 you don't have to worry about MULTIPLICITY or threading at all, iconic, live your life 🦋.
But wait… 😳 a surprising number of libc functions secretly depend on data that's global to the process in some way that is genuinely not immediately obvious. Like, calling strtok(3) changes the global state of a process — so it needs special attention 👀.
The section 3 libc uses that we know about that have MULTIPLICITY and/or multi-thread issues are:
…and here's the rest of the roster, bestie, no skips, no shortcuts, the whole entire list:
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()Li'l heads-up, bestie: if you clock a function that's sketchy on some platform or another that we didn't list, tell us — file a bug report at <https://github.com/Perl/perl5/issues>. That's the whole move. 🫶
Also, tiny detail that matters so much: some of these are actually chill under MULTIPLICITY, and only become a problem under threading. So if a use doesn't show up in the list above, our official take is that it's MULTIPLICITY and thread-safe on every platform. cute. ✨
And one more thing — almost everything on that big beautiful list is a plain old function call. Except these four, which are not:
daylight MB_CUR_MAX timezone tzname
There are three main approaches to coping with issues involving these constructs, each suitable for different circumstances:
- Don't use them. Some of them have preferred alternatives, and the list up in "libc functions to avoid" exists exactly so you can swap your uses out for thread-friendly ones. I/O, for example? That's
perlapio's whole job. 💅 - Okay but if you must use them 🥺 — a bunch of them (not all, bestie, definitely not all) will be totally fine as long as their use stays confined to a single thread that has zero interaction with conflicting uses in other threads. You're gonna have to read their man pages super closely to figure that out, and be warned: vendor documentation is often imprecise. 😭
- Do all your business before any other code can change things. And if you make changes, change back before returning. ✨
- Save the result of a query of global information to a per-instance area before you let another instance execute. Then you get to work on it at your leisure 🫶. This might be an automatic C variable for non-pointers, or something as described above in "Safely Storing Static Data in XS" in perlxs.
No threading? Then you literally never have to worry about getting interrupted by the system handing control over to another thread. With threading? You're gonna have to use mutexes, and now you get to be 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, no notes. These must be called only during single-thread operation:
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()That @ mark up there means these are the functions for which there are 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 very first call that has to happen while you're still in a single-thread environment, but after that, subsequent calls are thread-safe when executed in a critical section. So bestie, they've 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 the restrictions are easily met, so this is genuinely good news:
ctermid() mbrlen() mbsrtowcs() wcrtomb()
cuserid() mbrtowc() tmpnam() wcsnrtombs()
error_at_line() mbsnrtowcs() va_arg() wcsrtombs()Peep the man pages of each one for the details. (And for completeness 🫠 — the list includes functions you shouldn't be using anyway, for other reasons entirely.)
📡 Functions vulnerable to signals 📡
Some functions are vulnerable to asynchronous signals. It's giving risky:
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 also has signal issues. 🙈
💀 General issues with thread-safety 💀
Some libc functions use and/or modify a global state, like a database. The libc functions presume there's only one instance at a time operating on that database. If more than one does, you get unpredictable results — even if the database isn't changed. Example: there's typically a global iterator for such a database and that iterator is maintained by libc, 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 have 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. Periodt.
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 will have unreproducible results, since the threads will vary in their timings and interactions. This may be what you want; or it may not be. (That 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 the typical consequences are just that the data gets output in an unpredictable order — and honestly that outcome may be totally acceptable to you. 🎀
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 — maybe even 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 all 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_REENTRANTIt's simpler for you to use the unpreferred version in your code and rely on this feature to do the better thing 💖 — in part because no substitution is done if the alternative isn't available or desirable on the platform, nor 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, honestly.
On some platforms the safer library functions may fail if the result buffer is too small (for example the user group databases may be rather 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 for security or memory consumption reasons, you can recompile Perl with PERL_REENTRANT_MAXSIZE #defined to the maximum number of bytes you will allow. 📏
Below is a list of the non-reentrant functions and their reentrant alternatives. This substitution is done even on functions that 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 that the automatic substitution only happens when they are available and desirable, so you can just use the unpreferred alternative.) 🫶
*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". - 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 it is 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. 😭
- If you
✨ Functions that need the environment to be constant ✨
Okay so bestie, the environment is global to the whole process, like one giant group chat everybody's in. Every instance is reading from it, so every instance depends on it. And the second one instance changes the environment, it changes for all of them. No opt-out, no private mode. 💀
Under threads this gets spicy: any libc call that expects the environment to stay frozen for the entire duration of its execution will have undefined results if another thread interrupts it at literally the worst possible moment and rewrites the env. And these are the functions whose man pages straight up flag them as sensitive to that. 👇
catopen() gethostbyname2() newlocale()
ctime() gethostbyname2_r() regerror()
ctime_r() gethostbyname_r() secure_getenv()
endhostent() gethostent() sethostent()
endhostent_r() gethostent_r() sethostent_r()
endnetent() gethostid() setlocale()
endnetent_r() getnameinfo() setlocale_r()
execlp() getnetbyname() setnetent()
execvp() getnetent() setnetent_r()
execvpe() getopt() strftime()
fnmatch() getopt_long() strptime()
getaddrinfo() getopt_long_only() sysconf()
get_current_dir_name() getrpcport() syslog()
getdate() glob() tempnam()
getdate_r() gmtime() timegm()
getenv() gmtime_r() timelocal()
gethostbyaddr() localtime() tzset()
gethostbyaddr_r() localtime_r() vsyslog()
gethostbyname() mktime()And ngl, a lot of these are problematic under threads for other reasons too — that's not me being dramatic, that's just true. Go read the man page for whichever ones you actually use. 🫶
Perl's answer to this whole mess: it defines mutexes ENV_READ_LOCK and ENV_READ_UNLOCK, and you're supposed to wrap your calls to these functions in them. Cute! Except you have to think about the possibility of deadlock, which is not cute at all. 🙈
Heads up: it's expected that a different mechanism will be in place and preferred for Perl v5.42. So this specific arrangement has a shelf life, iykyk.
🦋 Locale-specific issues 🦋
History lesson time, stay with me. C programs originally had one single locale for the entire process. One. Global. Just for everybody. Then people realised that was lowkey inadequate for a bunch of purposes, so later extensions changed the game — first with Windows, and then with POSIX 2008. ✨
Here's the split:
- On Windows, you can flip any thread, at any time, to run either with a per-thread locale or with the global one, using a special new libc function.
- On POSIX, the original API only ever touches the global locale. But there's a whole entirely new API that can manipulate either per-thread locales or the global one. And just like on Windows (except using the new API), a thread can be switched at any moment to operate on the global locale, or on a per-thread one.
So when one instance changes the global locale, every other instance using the global locale gets affected. Almost all the locale-related functions sitting right up there in the list directly under "Dealing with embedded perls and threads" have undefined behavior if another thread interrupts their execution and swaps the locale out from under them. And under threads? Another thread can absolutely do exactly that. 😭
But here's the slay part: on systems that have per-thread locales, starting with Perl v5.28, perl uses them right after initialization. The global locale just isn't used — unless XS code has gone and called switch_to_global_locale(). And that only affects the thread that called it, bestie. So if a maximum of one instance is using the global locale, no other instances get touched, the locale of concurrently executing functions in other threads stays put, and this whole problem 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 actually use them.
Real talk though: 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 a vibe. 🚫
And the converse, because there's always a converse:
- On systems with only a global locale, having different threads using different locales is... not likely to work well. 🫠
- And changing the locale there is dangerous, often leading to crashes. Genuinely risky, don't do it casually.
Perl has extensive code to work as well as it possibly can on both flavours of system. And the takeaway for you, my love: always use Perl_setlocale() to change and query the locale, because it portably works across the entire range of possibilities. That's the one. 👑
🌈 SEE ALSO 🌈
perlapiperlapioperlgutsperlxs
and that's a wrap on PERLCLIB, bestie!! 🎀 thanks for reading the whole thing, you ate fr fr 💖 this was perl v5.44.0, dated 2026-10-17, from the PERLCLIB(1perl) era — iconic, no cap, go forth and write thread-safe locale code 🦋✨
📦 where this page comes from
- arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms