Question

When using keys %:: to get a list of the currently loaded root namespaces, the Internals:: package is loaded by default (along with UNIVERSAL:: and a few others). However, I haven’t found any documentation for the functions in Internals::

keys %{Internals::} returns SvREFCNT hv_clear_placeholders hash_seed SvREADONLY HvREHASH rehash_seed

All of these can probably be looked up in Perl’s C API docs, but is there any Perl level documentation for them? Is the package stable? It’s used by several core modules (Hash::Util for one), so I imagine it is, but the lack of documentation is a bit troubling.

I didn’t see Internals.pm in the Perl distribution (different name maybe?), and it is not the Internals module up on CPAN.

Note: I fully understand that the functions in Internals:: are potentially dangerous, and I do not have any particular use in mind. I was reading through Hash::Util‘s source and came across it.

Answer 1

IIRC the code is not Internals.pm but libinternals.c. It looks like they used to be in universal.c in Perl 5.8 but got migrated out.

As per 03/2009 and Perl 5.10 they were not documented as per this perlmonks thread.

Also, in the same thread, ysth states:

Undocumented things in universal.c
should not be depended on; they should
only be used by core modules. They
aren’t documented on purpose, to allow
them to be changed whenever and
however necessary. For those purposes,
the code is good enough documentation.