SvOK(SV*)
The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.
-Its address can be used whenever an C<SV*> is needed.
-However, you have to be careful when using C<&PL_sv_undef> as a value in AVs
-or HVs (see L<AVs, HVs and undefined values>).
+
+Its address can be used whenever an C<SV*> is needed. Make sure that
+you don't try to compare a random sv with C<&PL_sv_undef>. For example
+when interfacing Perl code, it'll work correctly for:
+
+ foo(undef);
+
+But won't work when called as:
+
+ $x = undef;
+ foo($x);
+
+So to repeat always use SvOK() to check whether an sv is defined.
+
+Also you have to be careful when using C<&PL_sv_undef> as a value in
+AVs or HVs (see L<AVs, HVs and undefined values>).
There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their
The C<name> and C<namlen> arguments are used to associate a string with
the magic, typically the name of a variable. C<namlen> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlen> E<gt>= 0 a malloc'd
-copy of the name is stored in C<mg_ptr> field.
+C<mg_len> field and if C<name> is non-null then either a C<savepvn> copy of
+C<name> or C<name> itself is stored in the C<mg_ptr> field, depending on
+whether C<namlen> is greater than zero or equal to zero respectively. As a
+special case, if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
+to contain an C<SV*> and is stored as-is with its REFCNT incremented.
The sv_magic function uses C<how> to determine which, if any, predefined
"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
then C<obj> is merely stored, without the reference count being incremented.
+See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
+to an SV.
+
There is also a function to add magic to an C<HV>:
void hv_magic(HV *hv, GV *gv, int how);
Now that there is room on the stack, values can be pushed on it using C<PUSHs>
macro. The pushed values will often need to be "mortal" (See
-L</Reference Counts and Mortality>).
+L</Reference Counts and Mortality>):
PUSHs(sv_2mortal(newSViv(an_integer)))
+ PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
+ PUSHs(sv_2mortal(newSVnv(a_double)))
PUSHs(sv_2mortal(newSVpv("Some String",0)))
- PUSHs(sv_2mortal(newSVnv(3.141592)))
And now the Perl program calling C<tzname>, the two values will be assigned
as in:
do not need to call C<EXTEND> to extend the stack.
Despite their suggestions in earlier versions of this document the macros
-C<PUSHi>, C<PUSHn> and C<PUSHp> are I<not> suited to XSUBs which return
-multiple results, see L</Putting a C value on Perl stack>.
+C<(X)PUSH[iunp]> are I<not> suited to XSUBs which return multiple results.
+For that, either stick to the C<(X)PUSHs> macros shown above, or use the new
+C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.
For more information, consult L<perlxs> and L<perlxstut>.
The macro to put this target on stack is C<PUSHTARG>, and it is
directly used in some opcodes, as well as indirectly in zillions of
-others, which use it via C<(X)PUSH[pni]>.
+others, which use it via C<(X)PUSH[iunp]>.
Because the target is reused, you must be careful when pushing multiple
values on the stack. The following code will not do what you think:
the stack; set C<TARG> to 20, push a pointer to C<TARG> onto the stack".
At the end of the operation, the stack does not contain the values 10
and 20, but actually contains two pointers to C<TARG>, which we have set
-to 20. If you need to push multiple different values, use C<XPUSHs>,
-which bypasses C<TARG>.
+to 20.
+
+If you need to push multiple different values then you should either use
+the C<(X)PUSHs> macros, or else use the new C<m(X)PUSH[iunp]> macros,
+none of which make use of C<TARG>. The C<(X)PUSHs> macros simply push an
+SV* on the stack, which, as noted under L</XSUBs and the Argument Stack>,
+will often need to be "mortal". The new C<m(X)PUSH[iunp]> macros make
+this a little easier to achieve by creating a new mortal for you (via
+C<(X)PUSHmortal>), pushing that onto the stack (extending it if necessary
+in the case of the C<mXPUSH[iunp]> macros), and then setting its value.
+Thus, instead of writing this to "fix" the example above:
-On a related note, if you do use C<(X)PUSH[npi]>, then you're going to
+ XPUSHs(sv_2mortal(newSViv(10)))
+ XPUSHs(sv_2mortal(newSViv(20)))
+
+you can simply write:
+
+ mXPUSHi(10)
+ mXPUSHi(20)
+
+On a related note, if you do use C<(X)PUSH[iunp]>, then you're going to
need a C<dTARG> in your variable declarations so that the C<*PUSH*>
-macros can make use of the local variable C<TARG>.
+macros can make use of the local variable C<TARG>. See also C<dTARGET>
+and C<dXSTARG>.
=head2 Scratchpads
support for passing in a "hidden" first argument that represents all three
data structures.
+Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and
+PERL_GLOBAL_STRUCT_PRIVATE (the latter turns on the former, and the
+former turns on MULTIPLICITY.) The PERL_GLOBAL_STRUCT causes all the
+internal variables of Perl to be wrapped inside a single global struct,
+struct perl_vars, accessible as (globals) &PL_Vars or PL_VarsPtr or
+the function Perl_GetVars(). The PERL_GLOBAL_STRUCT_PRIVATE goes
+one step further, there is still a single struct (allocated in main()
+either from heap or from stack) but there are no global data symbols
+pointing to it. In either case the global struct should be initialised
+as the very first thing in main() using Perl_init_global_struct() and
+correspondingly tear it down after perl_free() using Perl_free_global_struct(),
+please see F<miniperlmain.c> for usage details. You may also need
+to use C<dVAR> in your coding to "declare the global variables"
+when you are using them. dTHX does this for you automatically.
+
+For backward compatibility reasons defining just PERL_GLOBAL_STRUCT
+doesn't actually hide all symbols inside a big global struct: some
+PerlIO_xxx vtables are left visible. The PERL_GLOBAL_STRUCT_PRIVATE
+then hides everything (see how the PERLIO_FUNCS_DECL is used).
+
All this obviously requires a way for the Perl internal functions to be
either subroutines taking some kind of structure as the first
argument, or subroutines taking nothing as the first argument. To
macro with the underscore for functions that take explicit arguments,
or the form without the argument for functions with no explicit arguments.
+If one is compiling Perl with the C<-DPERL_GLOBAL_STRUCT> the C<dVAR>
+definition is needed if the Perl global variables (see F<perlvars.h>
+or F<globvar.sym>) are accessed in the function and C<dTHX> is not
+used (the C<dTHX> includes the C<dVAR> if necessary). One notices
+the need for C<dVAR> only with the said compile-time define, because
+otherwise the Perl global variables are visible as-is.
+
=head2 Should I do anything special if I call perl from multiple threads?
If you create interpreters in one thread and then proceed to call them in
AV *av = ...;
UV uv = PTR2UV(av);
+=head2 Exception Handling
+
+There are a couple of macros to do very basic exception handling in XS
+modules. You have to define C<NO_XSLOCKS> before including F<XSUB.h> to
+be able to use these macros:
+
+ #define NO_XSLOCKS
+ #include "XSUB.h"
+
+You can use these macros if you call code that may croak, but you need
+to do some cleanup before giving control back to Perl. For example:
+
+ dXCPT; /* set up neccessary variables */
+
+ XCPT_TRY_START {
+ code_that_may_croak();
+ } XCPT_TRY_END
+
+ XCPT_CATCH
+ {
+ /* do cleanup here */
+ XCPT_RETHROW;
+ }
+
+Note that you always have to rethrow an exception that has been
+caught. Using these macros, it is not possible to just catch the
+exception and ignore it. If you have to ignore the exception, you
+have to use the C<call_*> function.
+
+The advantage of using the above macros is that you don't have
+to setup an extra function for C<call_*>, and that using these
+macros is faster than using C<call_*>.
+
=head2 Source Documentation
There's an effort going on to document the internal functions and
Please try and supply some documentation if you add functions to the
Perl core.
+=head2 Backwards compatibility
+
+The Perl API changes over time. New functions are added or the interfaces
+of existing functions are changed. The C<Devel::PPPort> module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+
+C<Devel::PPPort> generates a C header file F<ppport.h> that can also
+be run as a Perl script. To generate F<ppport.h>, run:
+
+ perl -MDevel::PPPort -eDevel::PPPort::WriteFile
+
+Besides checking existing XS code, the script can also be used to retrieve
+compatibility information for various API calls using the C<--api-info>
+command line switch. For example:
+
+ % perl ppport.h --api-info=sv_magicext
+
+For details, see C<perldoc ppport.h>.
+
=head1 Unicode Support
Perl 5.6.0 introduced Unicode support. It's important for porters and XS
projects / p5sagit/p5-mst-13.2.git / blobdiff