Internals(3perl)

💖 Internals — the reserved special namespace for internals functions 💖

okay bestie, welcome to Internals(3perl) — it's the Internals page from the Perl Programmers Reference Guide, and it's giving "backstage pass to the perl core" energy. buckle up 🎀

---

✨ SYNOPSIS ✨

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

---

🌸 DESCRIPTION 🌸

so the Internals namespace? it's the lil hideout the core Perl development team uses to expose certain low level internals routines for testing and other purposes. it's not for us. it was never for us. 💅

in theory these routines were not and are not intended to be used outside of the perl core, and they are subject to change and removal at any time. like, anytime. no warning. gone. 🫠

in practice though? people have come to depend on these over the years, despite them being historically undocumented, so we will provide some level of forward compatibility for some time. nevertheless you can assume that any routine documented here is experimental or deprecated and you should find alternatives to their use. fr fr, go find the alternative. 🙈

---

🦋 FUNCTIONS 🦋

SvREFCNT(THING [, $value])

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

in theory Perl code should not have to care about this, and in a future version Perl might change to some other strategy — although in practice this is unlikely. so like, don't stress. 😌

this function lets you violate the abstraction of variables and get or set the refcount of a variable, and in general it's really only useful in code that is testing refcount behavior. it's a lab tool, not a lifestyle. 🧪

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 of doing so may result in segmentation faults or other undefined behavior. 💀 like bestie I am BEGGING you. 🙏

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. it's giving "it depends" and it means it. 🎀

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 which should be used instead. use those. they ate. 👑

see the core implementation for the exact meaning of the readonly flag for each internal variable type. that's the source of truth, not this page. 🫶

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 also available as Hash::Util::_clear_placeholders(%hash). so like, use the wrapper, she's right there. 🌸

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. flag bits, bestie, read them like flag bits. ⭐

---

👑 AUTHOR 👑

Perl core development team. absolute legends, no cap. 🌈

---

🔥 SEE ALSO 🔥

perlguts Hash::Util constant universal.c

---

okay that's the whole page, you made it, I'm so proud 🥹 this was perl v5.44.0, dated 2026-10-17, straight from the Internals(3perl) manual — mwah, go forth and please just use Hash::Util 💖✨🎀