Internals(3pm)

🌸 Internals(3pm) — aka the perl internals club 💅

ok so you're looking at Internals(3pm), straight out of the Perl Programmers Reference Guide, and bestie… this is the backstage pass page. it's not for the general public, it's for the perl core devs. read on, but read the warnings, fr fr 🫶

---

✨ SYNOPSIS ✨

$is_ro= Internals::SvREADONLY($x)
$refcnt= Internals::SvREFCNT($x)
hv_clear_placeholders(%hash);
if (Internals::stack_refcounted & 1) { .... }

that's the whole vibe. no cap, that's it up there 👑

---

🦋 DESCRIPTION 🦋

so the Internals namespace? it's the thing the core Perl development team uses to expose certain low level internals routines — for testing and other purposes. like, behind-the-curtain stuff. 🎀

in theory, these routines were never intended to be used outside of the perl core, and they're subject to change and removal at any time. literally any time. 😭

in practice though? people have come to depend on these over the years, even though they were historically undocumented, so perl provides some level of forward compatibility for some time. but bestie, hear me: you can assume that any routine documented here is experimental or deprecated, and you should find alternatives to their use. periodt. 💀

---

🔥 FUNCTIONS 🔥

SvREFCNT(THING [, $value])

historically Perl has been a refcounted language. that means each variable tracks how many things reference it, and when the variable is no longer referenced it will automatically free itself. ✨ self-care, honestly.

in theory Perl code shouldn't have to care about this at all, and in a future version Perl might switch to some other strategy — although in practice that's unlikely.

this function lets you straight-up violate the abstraction of variables and get or set the refcount of a variable. it's really only useful in code that's testing refcount behavior. that's the whole niche. 🧚

NOTE — you are strongly discouraged from using this function in non-test code, and especially discouraged from using the set form of this function. the results may include segmentation faults or other undefined behavior. like, actual crashes. don't play with this in prod, i'm begging 🙈

SvREADONLY(THING, [, $value])

set or get whether a variable is readonly or not. exactly what the readonly flag means depends on the type of the variable affected and the version of perl used — so it's giving "it depends", lowkey. 🦋

you are strongly discouraged from using this function directly. it's used by various core modules, like Hash::Util and the constant pragma, to implement higher-level behavior — and that higher-level stuff is what you should be using instead. 💅

see the core implementation for the exact meaning of the readonly flag for each internal variable type.

hv_clear_placeholders(%hash)

clear any placeholders from a locked hash. 🔒 should not be used directly — you should use the wrapper functions provided by Hash::Util instead. as of 5.25 it's also available as Hash::Util::_clear_placeholders(%hash). slay for having an alias ✨

stack_refcounted

returns an integer indicating whether the perl binary has been configured and built with an argument stack which reference-counts any items pushed onto it. the value should be treated as flag bits 🎀 — currently only bit 0 is used, indicating that PERL_RC_STACK was enabled during the build. iykyk.

---

👑 AUTHOR 👑

Perl core development team. main character energy, collectively. 💜

---

🌈 SEE ALSO 🌈

• perlguts
• Hash::Util
• constant
• universal.c

---

ok bye bestie, go read perlguts next, and remember: this page is perl v5.42.3, dated 2026-11-03. mwah 💖🎀🦋