If you know the name of a scalar variable, you can get a pointer to its SV
by using the following:
- SV* get_sv("package::varname", FALSE);
+ SV* get_sv("package::varname", 0);
This returns NULL if the variable does not exist.
C<AvARRAY> points to the first element in the array that is visible from
Perl, C<AvALLOC> points to the real start of the C array. These are
usually the same, but a C<shift> operation can be carried out by
-increasing C<AvARRAY> by one and decreasing C<AvFILL> and C<AvLEN>.
+increasing C<AvARRAY> by one and decreasing C<AvFILL> and C<AvMAX>.
Again, the location of the real start of the C array only comes into
play when freeing the array. See C<av_shift> in F<av.c>.
If you know the name of an array variable, you can get a pointer to its AV
by using the following:
- AV* get_av("package::varname", FALSE);
+ AV* get_av("package::varname", 0);
This returns NULL if the variable does not exist.
If you know the name of a hash variable, you can get a pointer to its HV
by using the following:
- HV* get_hv("package::varname", FALSE);
+ HV* get_hv("package::varname", 0);
This returns NULL if the variable does not exist.
SVt_PVGV Glob (possible a file handle)
SVt_PVMG Blessed or Magical Scalar
- See the sv.h header file for more details.
+See the F<sv.h> header file for more details.
=head2 Blessed References and Class Objects
To create a new Perl variable with an undef value which can be accessed from
your Perl script, use the following routines, depending on the variable type.
- SV* get_sv("package::varname", TRUE);
- AV* get_av("package::varname", TRUE);
- HV* get_hv("package::varname", TRUE);
+ SV* get_sv("package::varname", GV_ADD);
+ AV* get_av("package::varname", GV_ADD);
+ HV* get_hv("package::varname", GV_ADD);
Notice the use of TRUE as the second parameter. The new variable can now
be set, using the routines appropriate to the data type.
If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or
making a C<sv_mortalcopy> is safer.
-The mortal routines are not just for SVs -- AVs and HVs can be
+The mortal routines are not just for SVs; AVs and HVs can be
made mortal by passing their address (type-casted to C<SV*>) to the
C<sv_2mortal> or C<sv_mortalcopy> routines.
extern int dberror;
extern char *dberror_list;
- SV* sv = get_sv("dberror", TRUE);
+ SV* sv = get_sv("dberror", GV_ADD);
sv_setiv(sv, (IV) dberror);
sv_setpv(sv, dberror_list[dberror]);
SvIOK_on(sv);
int (*svt_clear)(SV* sv, MAGIC* mg);
int (*svt_free)(SV* sv, MAGIC* mg);
- int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, int namlen);
+ int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, I32 namlen);
int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
int (*svt_local)(SV *nsv, MAGIC *mg);
This MGVTBL structure is set at compile-time in F<perl.h> and there are
-currently 19 types (or 21 with overloading turned on). These different
-structures contain pointers to various routines that perform additional
-actions depending on which function is being called.
+currently 32 types. These different structures contain pointers to various
+routines that perform additional actions depending on which function is
+being called.
Function pointer Action taken
---------------- ------------
The current kinds of Magic Virtual Tables are:
mg_type
- (old-style char and macro) MGVTBL Type of magic
- -------------------------- ------ ----------------------------
+ (old-style char and macro) MGVTBL Type of magic
+ -------------------------- ------ -------------
\0 PERL_MAGIC_sv vtbl_sv Special scalar variable
A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash
a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element
e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
f PERL_MAGIC_fm vtbl_fm Formline ('compiled' format)
g PERL_MAGIC_regex_global vtbl_mglob m//g target / study()ed string
- H PERL_MAGIC_hints vtbl_sig %^H hash
+ H PERL_MAGIC_hints vtbl_hints %^H hash
h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element
I PERL_MAGIC_isa vtbl_isa @ISA array
i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
=head2 Scratchpads
The question remains on when the SVs which are I<target>s for opcodes
-are created. The answer is that they are created when the current unit --
-a subroutine or a file (for opcodes for statements outside of
-subroutines) -- is compiled. During this time a special anonymous Perl
-array is created, which is called a scratchpad for the current
-unit.
+are created. The answer is that they are created when the current
+unit--a subroutine or a file (for opcodes for statements outside of
+subroutines)--is compiled. During this time a special anonymous Perl
+array is created, which is called a scratchpad for the current unit.
A scratchpad keeps SVs which are lexicals for the current unit and are
targets for opcodes. One can deduce that an SV lives on a scratchpad
state. With multiplicity-enabled perls, PERL_IMPLICIT_CONTEXT is also
normally defined, and enables the support for passing in a "hidden" first
argument that represents all three data structures. MULTIPLICITY makes
-mutli-threaded perls possible (with the ithreads threading model, related
+multi-threaded perls possible (with the ithreads threading model, related
to the macro USE_ITHREADS.)
Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and
void
Perl_sv_setiv(pTHX_ SV* dsv, IV num)
-C<pTHX_> is one of a number of macros (in perl.h) that hide the
+C<pTHX_> is one of a number of macros (in F<perl.h>) that hide the
details of the interpreter's context. THX stands for "thread", "this",
or "thingy", as the case may be. (And no, George Lucas is not involved. :-)
The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
There are three ways to do this. First, the easy but inefficient way,
which is also the default, in order to maintain source compatibility
-with extensions: whenever XSUB.h is #included, it redefines the aTHX
+with extensions: whenever F<XSUB.h> is #included, it redefines the aTHX
and aTHX_ macros to call a function that will return the context.
Thus, something like:
environment) for all the system calls. This makes it possible for
all the system stuff to maintain their own state, broken down into
seven C structures. These are thin wrappers around the usual system
-calls (see win32/perllib.c) for the default perl executable, but for a
+calls (see F<win32/perllib.c>) for the default perl executable, but for a
more ambitious host (like the one that would do fork() emulation) all
the extra work needed to pretend that different interpreters are
actually different "processes", would be done here.
Similarly, all global variables begin with C<PL_>. (By convention,
static functions start with C<S_>.)
-Inside the Perl core, you can get at the functions either with or
-without the C<Perl_> prefix, thanks to a bunch of defines that live in
-F<embed.h>. This header file is generated automatically from
+Inside the Perl core (C<PERL_CORE> defined), you can get at the functions
+either with or without the C<Perl_> prefix, thanks to a bunch of defines
+that live in F<embed.h>. Note that extension code should I<not> set
+C<PERL_CORE>; this exposes the full perl internals, and is likely to cause
+breakage of the XS in each new perl release.
+
+The file F<embed.h> is generated automatically from
F<embed.pl> and F<embed.fnc>. F<embed.pl> also creates the prototyping
header files for the internal functions, generates the documentation
and a lot of other bits and pieces. It's important that when you add
slightly differently. A flag in the SV, C<SVf_UTF8>, indicates that the
string is internally encoded as UTF-8. Without it, the byte value is the
codepoint number and vice versa (in other words, the string is encoded
-as iso-8859-1). You can check and manipulate this flag with the
+as iso-8859-1, but C<use feature 'unicode_strings'> is needed to get iso-8859-1
+semantics). You can check and manipulate this flag with the
following macros:
SvUTF8(sv)
=item *
Mixing UTF-8 and non-UTF-8 strings is tricky. Use C<bytes_to_utf8> to get
-a new string which is UTF-8 encoded. There are tricks you can use to
-delay deciding whether you need to use a UTF-8 string until you get to a
-high character - C<HALF_UPGRADE> is one of those.
+a new string which is UTF-8 encoded, and then combine them.
=back
need to enter a name and description for your op at the appropriate
place in the C<PL_custom_op_names> and C<PL_custom_op_descs> hashes.
-Forthcoming versions of C<B::Generate> (version 1.0 and above) should
-directly support the creation of custom ops by name.
+C<B::Generate> directly supports the creation of custom ops by name.
=head1 AUTHORS
=head1 SEE ALSO
-perlapi(1), perlintern(1), perlxs(1), perlembed(1)
+L<perlapi>, L<perlintern>, L<perlxs>, L<perlembed>