lib/h2xs.t See if h2xs produces expected lists of files
lib/integer.pm For "use integer"
lib/integer.t For "use integer" testing
+lib/Internals.pod Document the Internals namespace (implemented by universal.c)
lib/Internals.t For Internals::* testing
lib/less.pm For "use less"
lib/less.t See if less support works
--- /dev/null
+=head1 NAME
+
+Internals - Reserved special namespace for internals related functions
+
+=head1 SYNOPSIS
+
+ $is_ro= Internals::SvREADONLY($x)
+ $refcnt= Internals::SvREFCNT($x)
+
+=head1 DESCRIPTION
+
+The Internals namespace is used by the core Perl development team to
+expose certain low level internals routines for testing and other purposes.
+
+In theory these routines were not and are not intended to be used outside
+of the perl core, and are subject to change and removal at any time.
+
+In practice people have come to depend on these over the years, despite
+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.
+
+=head2 FUNCTIONS
+
+=over 4
+
+=item SvREFCNT(THING [, $value])
+
+Historically Perl has been a refcounted language. This means that each
+variable tracks how many things reference it, and when the variable is no
+longer referenced it will automatically free itself. 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.
+
+This function allows one to violate the abstraction of variables and get
+or set the refcount of a variable, and in generally is really only useful
+in code that is testing refcount behavior.
+
+*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.
+
+=item SvREADONLY(THING, [, $value])
+
+Set or get whether a variable is readonly or not. Exactly what the
+readonly flag means depend on the type of the variable affected and the
+version of perl used.
+
+You are strongly discouraged from using this function directly. It is used
+by various core modules, like C<Hash::Util>, and the C<constant> pragma
+to implement higher-level behavior which should be used instead.
+
+See the core implementation for the exact meaning of the readonly flag for
+each internal variable type.
+
+=back
+
+=head1 AUTHOR
+
+Perl core development team.
+
+=head1 SEE ALSO
+
+L<perlguts>
+universal.c
+
+=cut
=head1 SV Manipulation Functions
=for apidoc Am|U32|SvREFCNT|SV* sv
-Returns the value of the object's reference count.
+Returns the value of the object's reference count. Exposed
+to perl code via Internals::SvREFCNT().
=for apidoc Am|SV*|SvREFCNT_inc|SV* sv
Increments the reference count of the given SV, returning the SV.
#define SvOBJECT_on(sv) (SvFLAGS(sv) |= SVs_OBJECT)
#define SvOBJECT_off(sv) (SvFLAGS(sv) &= ~SVs_OBJECT)
+/*
+=for apidoc Am|U32|SvREADONLY|SV* sv
+Returns true if the argument is readonly, otherwise returns false.
+Exposed to to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_on|SV* sv
+Mark an object as readonly. Exactly what this means depends on the object
+type. Exposed to perl code via Internals::SvREADONLY().
+
+=for apidoc Am|U32|SvREADONLY_off|SV* sv
+Mark an object as not-readonly. Exactly what this mean depends on the
+object type. Exposed to perl code via Internals::SvREADONLY().
+
+=cut
+*/
+
#define SvREADONLY(sv) (SvFLAGS(sv) & (SVf_READONLY|SVf_PROTECT))
#ifdef PERL_CORE
# define SvREADONLY_on(sv) (SvFLAGS(sv) |= (SVf_READONLY|SVf_PROTECT))