perlguts.1

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

\&  Had to create <varname> unexpectedly
.Ve
.Sp
if the variable did not exist before the function was called.
.PP
If you do not specify a package name, the variable is created in the current
package.
.Sh "Reference Counts and Mortality"
.IX Subsection "Reference Counts and Mortality"
Perl uses a reference count-driven garbage collection mechanism. SVs,
AVs, or HVs (xV for short in the following) start their life with a
reference count of 1.  If the reference count of an xV ever drops to 0,
then it will be destroyed and its memory made available for reuse.
.PP
This normally doesn't happen at the Perl level unless a variable is
undef'ed or the last variable holding a reference to it is changed or
overwritten.  At the internal level, however, reference counts can be
manipulated with the following macros:
.PP
.Vb 3
\&    int SvREFCNT(SV* sv);
\&    SV* SvREFCNT_inc(SV* sv);
\&    void SvREFCNT_dec(SV* sv);
.Ve
.PP
However, there is one other function which manipulates the reference
count of its argument.  The \f(CW\*(C`newRV_inc\*(C'\fR function, you will recall,
creates a reference to the specified argument.  As a side effect,
it increments the argument's reference count.  If this is not what
you want, use \f(CW\*(C`newRV_noinc\*(C'\fR instead.
.PP
For example, imagine you want to return a reference from an \s-1XSUB\s0 function.
Inside the \s-1XSUB\s0 routine, you create an \s-1SV\s0 which initially has a reference
count of one.  Then you call \f(CW\*(C`newRV_inc\*(C'\fR, passing it the just-created \s-1SV\s0.
This returns the reference as a new \s-1SV\s0, but the reference count of the
\&\s-1SV\s0 you passed to \f(CW\*(C`newRV_inc\*(C'\fR has been incremented to two.  Now you
return the reference from the \s-1XSUB\s0 routine and forget about the \s-1SV\s0.
But Perl hasn't!  Whenever the returned reference is destroyed, the
reference count of the original \s-1SV\s0 is decreased to one and nothing happens.
The \s-1SV\s0 will hang around without any way to access it until Perl itself
terminates.  This is a memory leak.
.PP
The correct procedure, then, is to use \f(CW\*(C`newRV_noinc\*(C'\fR instead of
\&\f(CW\*(C`newRV_inc\*(C'\fR.  Then, if and when the last reference is destroyed,
the reference count of the \s-1SV\s0 will go to zero and it will be destroyed,
stopping any memory leak.
.PP
There are some convenience functions available that can help with the
destruction of xVs.  These functions introduce the concept of \*(L"mortality\*(R".
An xV that is mortal has had its reference count marked to be decremented,
but not actually decremented, until \*(L"a short time later\*(R".  Generally the
term \*(L"short time later\*(R" means a single Perl statement, such as a call to
an \s-1XSUB\s0 function.  The actual determinant for when mortal xVs have their
reference count decremented depends on two macros, \s-1SAVETMPS\s0 and \s-1FREETMPS\s0.
See perlcall and perlxs for more details on these macros.
.PP
\&\*(L"Mortalization\*(R" then is at its simplest a deferred \f(CW\*(C`SvREFCNT_dec\*(C'\fR.
However, if you mortalize a variable twice, the reference count will
later be decremented twice.
.PP
\&\*(L"Mortal\*(R" SVs are mainly used for SVs that are placed on perl's stack.
For example an \s-1SV\s0 which is created just to pass a number to a called sub
is made mortal to have it cleaned up automatically when it's popped off
the stack. Similarly, results returned by XSUBs (which are pushed on the
stack) are often made mortal.
.PP
To create a mortal variable, use the functions:
.PP
.Vb 3
\&    SV*  sv_newmortal()
\&    SV*  sv_2mortal(SV*)
\&    SV*  sv_mortalcopy(SV*)
.Ve
.PP
The first call creates a mortal \s-1SV\s0 (with no value), the second converts an existing
\&\s-1SV\s0 to a mortal \s-1SV\s0 (and thus defers a call to \f(CW\*(C`SvREFCNT_dec\*(C'\fR), and the
third creates a mortal copy of an existing \s-1SV\s0.
Because \f(CW\*(C`sv_newmortal\*(C'\fR gives the new \s-1SV\s0 no value,it must normally be given one
via \f(CW\*(C`sv_setpv\*(C'\fR, \f(CW\*(C`sv_setiv\*(C'\fR, etc. :
.PP
.Vb 2
\&    SV *tmp = sv_newmortal();
\&    sv_setiv(tmp, an_integer);
.Ve
.PP
As that is multiple C statements it is quite common so see this idiom instead:
.PP
.Vb 1
\&    SV *tmp = sv_2mortal(newSViv(an_integer));
.Ve
.PP
You should be careful about creating mortal variables.  Strange things
can happen if you make the same value mortal within multiple contexts,
or if you make a variable mortal multiple times. Thinking of \*(L"Mortalization\*(R"
as deferred \f(CW\*(C`SvREFCNT_dec\*(C'\fR should help to minimize such problems.
For example if you are passing an \s-1SV\s0 which you \fIknow\fR has high enough \s-1REFCNT\s0
to survive its use on the stack you need not do any mortalization.
If you are not sure then doing an \f(CW\*(C`SvREFCNT_inc\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR, or
making a \f(CW\*(C`sv_mortalcopy\*(C'\fR is safer.
.PP
The mortal routines are not just for SVs \*(-- AVs and HVs can be
made mortal by passing their address (type-casted to \f(CW\*(C`SV*\*(C'\fR) to the
\&\f(CW\*(C`sv_2mortal\*(C'\fR or \f(CW\*(C`sv_mortalcopy\*(C'\fR routines.
.Sh "Stashes and Globs"
.IX Subsection "Stashes and Globs"
A \fBstash\fR is a hash that contains all variables that are defined
within a package.  Each key of the stash is a symbol
name (shared by all the different types of objects that have the same
name), and each value in the hash table is a \s-1GV\s0 (Glob Value).  This \s-1GV\s0
in turn contains references to the various objects of that name,
including (but not limited to) the following:
.PP
.Vb 6
\&    Scalar Value
\&    Array Value
\&    Hash Value
\&    I/O Handle
\&    Format
\&    Subroutine
.Ve
.PP
There is a single stash called \f(CW\*(C`PL_defstash\*(C'\fR that holds the items that exist
in the \f(CW\*(C`main\*(C'\fR package.  To get at the items in other packages, append the
string \*(L"::\*(R" to the package name.  The items in the \f(CW\*(C`Foo\*(C'\fR package are in
the stash \f(CW\*(C`Foo::\*(C'\fR in PL_defstash.  The items in the \f(CW\*(C`Bar::Baz\*(C'\fR package are
in the stash \f(CW\*(C`Baz::\*(C'\fR in \f(CW\*(C`Bar::\*(C'\fR's stash.
.PP
To get the stash pointer for a particular package, use the function:
.PP
.Vb 2
\&    HV*  gv_stashpv(const char* name, I32 flags)
\&    HV*  gv_stashsv(SV*, I32 flags)
.Ve
.PP
The first function takes a literal string, the second uses the string stored
in the \s-1SV\s0.  Remember that a stash is just a hash table, so you get back an
\&\f(CW\*(C`HV*\*(C'\fR.  The \f(CW\*(C`flags\*(C'\fR flag will create a new package if it is set to \s-1GV_ADD\s0.
.PP
The name that \f(CW\*(C`gv_stash*v\*(C'\fR wants is the name of the package whose symbol table
you want.  The default package is called \f(CW\*(C`main\*(C'\fR.  If you have multiply nested
packages, pass their names to \f(CW\*(C`gv_stash*v\*(C'\fR, separated by \f(CW\*(C`::\*(C'\fR as in the Perl
language itself.
.PP
Alternately, if you have an \s-1SV\s0 that is a blessed reference, you can find
out the stash pointer by using:
.PP
.Vb 1
\&    HV*  SvSTASH(SvRV(SV*));
.Ve
.PP
then use the following to get the package name itself:
.PP
.Vb 1
\&    char*  HvNAME(HV* stash);
.Ve
.PP
If you need to bless or re-bless an object you can use the following
function:
.PP
.Vb 1
\&    SV*  sv_bless(SV*, HV* stash)
.Ve
.PP
where the first argument, an \f(CW\*(C`SV*\*(C'\fR, must be a reference, and the second
argument is a stash.  The returned \f(CW\*(C`SV*\*(C'\fR can now be used in the same way
as any other \s-1SV\s0.
.PP
For more information on references and blessings, consult perlref.
.Sh "Double-Typed SVs"
.IX Subsection "Double-Typed SVs"
Scalar variables normally contain only one type of value, an integer,
double, pointer, or reference.  Perl will automatically convert the
actual scalar data from the stored type into the requested type.
.PP
Some scalar variables contain more than one type of scalar data.  For
example, the variable \f(CW$!\fR contains either the numeric value of \f(CW\*(C`errno\*(C'\fR
or its string equivalent from either \f(CW\*(C`strerror\*(C'\fR or \f(CW\*(C`sys_errlist[]\*(C'\fR.
.PP
To force multiple data values into an \s-1SV\s0, you must do two things: use the
\&\f(CW\*(C`sv_set*v\*(C'\fR routines to add the additional scalar type, then set a flag
so that Perl will believe it contains more than one type of data.  The
four macros to set the flags are:
.PP
.Vb 4
\&        SvIOK_on
\&        SvNOK_on
\&        SvPOK_on
\&        SvROK_on
.Ve
.PP
The particular macro you must use depends on which \f(CW\*(C`sv_set*v\*(C'\fR routine
you called first.  This is because every \f(CW\*(C`sv_set*v\*(C'\fR routine turns on
only the bit for the particular type of data being set, and turns off
all the rest.
.PP
For example, to create a new Perl variable called \*(L"dberror\*(R" that contains
both the numeric and descriptive string error values, you could use the
following code:
.PP
.Vb 2
\&    extern int  dberror;
\&    extern char *dberror_list;
\&
\&    SV* sv = get_sv("dberror", TRUE);
\&    sv_setiv(sv, (IV) dberror);
\&    sv_setpv(sv, dberror_list[dberror]);
\&    SvIOK_on(sv);
.Ve
.PP
If the order of \f(CW\*(C`sv_setiv\*(C'\fR and \f(CW\*(C`sv_setpv\*(C'\fR had been reversed, then the
macro \f(CW\*(C`SvPOK_on\*(C'\fR would need to be called instead of \f(CW\*(C`SvIOK_on\*(C'\fR.
.Sh "Magic Variables"
.IX Subsection "Magic Variables"
[This section still under construction.  Ignore everything here.  Post no
bills.  Everything not permitted is forbidden.]
.PP
Any \s-1SV\s0 may be magical, that is, it has special features that a normal
\&\s-1SV\s0 does not have.  These features are stored in the \s-1SV\s0 structure in a
linked list of \f(CW\*(C`struct magic\*(C'\fR's, typedef'ed to \f(CW\*(C`MAGIC\*(C'\fR.
.PP
.Vb 10
\&    struct magic {
\&        MAGIC*      mg_moremagic;
\&        MGVTBL*     mg_virtual;
\&        U16         mg_private;
\&        char        mg_type;
\&        U8          mg_flags;
\&        I32         mg_len;
\&        SV*         mg_obj;
\&        char*       mg_ptr;
\&    };
.Ve
.PP
Note this is current as of patchlevel 0, and could change at any time.
.Sh "Assigning Magic"
.IX Subsection "Assigning Magic"
Perl adds magic to an \s-1SV\s0 using the sv_magic function:
.PP
.Vb 1
\&    void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
.Ve
.PP
The \f(CW\*(C`sv\*(C'\fR argument is a pointer to the \s-1SV\s0 that is to acquire a new magical
feature.
.PP
If \f(CW\*(C`sv\*(C'\fR is not already magical, Perl uses the \f(CW\*(C`SvUPGRADE\*(C'\fR macro to
convert \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR. Perl then continues by adding new magic
to the beginning of the linked list of magical features.  Any prior entry
of the same type of magic is deleted.  Note that this can be overridden,
and multiple instances of the same type of magic can be associated with an
\&\s-1SV\s0.
.PP
The \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments are used to associate a string with
the magic, typically the name of a variable. \f(CW\*(C`namlen\*(C'\fR is stored in the
\&\f(CW\*(C`mg_len\*(C'\fR field and if \f(CW\*(C`name\*(C'\fR is non-null then either a \f(CW\*(C`savepvn\*(C'\fR copy of
\&\f(CW\*(C`name\*(C'\fR or \f(CW\*(C`name\*(C'\fR itself is stored in the \f(CW\*(C`mg_ptr\*(C'\fR field, depending on
whether \f(CW\*(C`namlen\*(C'\fR is greater than zero or equal to zero respectively.  As a
special case, if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed
to contain an \f(CW\*(C`SV*\*(C'\fR and is stored as-is with its \s-1REFCNT\s0 incremented.
.PP
The sv_magic function uses \f(CW\*(C`how\*(C'\fR to determine which, if any, predefined
\&\*(L"Magic Virtual Table\*(R" should be assigned to the \f(CW\*(C`mg_virtual\*(C'\fR field.
See the \*(L"Magic Virtual Tables\*(R" section below.  The \f(CW\*(C`how\*(C'\fR argument is also
stored in the \f(CW\*(C`mg_type\*(C'\fR field. The value of \f(CW\*(C`how\*(C'\fR should be chosen
from the set of macros \f(CW\*(C`PERL_MAGIC_foo\*(C'\fR found in \fIperl.h\fR. Note that before
these macros were added, Perl internals used to directly use character
literals, so you may occasionally come across old code or documentation
referring to 'U' magic rather than \f(CW\*(C`PERL_MAGIC_uvar\*(C'\fR for example.
.PP
The \f(CW\*(C`obj\*(C'\fR argument is stored in the \f(CW\*(C`mg_obj\*(C'\fR field of the \f(CW\*(C`MAGIC\*(C'\fR
structure.  If it is not the same as the \f(CW\*(C`sv\*(C'\fR argument, the reference
count of the \f(CW\*(C`obj\*(C'\fR object is incremented.  If it is the same, or if
the \f(CW\*(C`how\*(C'\fR argument is \f(CW\*(C`PERL_MAGIC_arylen\*(C'\fR, or if it is a \s-1NULL\s0 pointer,
then \f(CW\*(C`obj\*(C'\fR is merely stored, without the reference count being incremented.
.PP
See also \f(CW\*(C`sv_magicext\*(C'\fR in perlapi for a more flexible way to add magic
to an \s-1SV\s0.
.PP
There is also a function to add magic to an \f(CW\*(C`HV\*(C'\fR:
.PP
.Vb 1
\&    void hv_magic(HV *hv, GV *gv, int how);
.Ve
.PP
This simply calls \f(CW\*(C`sv_magic\*(C'\fR and coerces the \f(CW\*(C`gv\*(C'\fR argument into an \f(CW\*(C`SV\*(C'\fR.
.PP
To remove the magic from an \s-1SV\s0, call the function sv_unmagic:
.PP
.Vb 1
\&    void sv_unmagic(SV *sv, int type);
.Ve
.PP
The \f(CW\*(C`type\*(C'\fR argument should be equal to the \f(CW\*(C`how\*(C'\fR value when the \f(CW\*(C`SV\*(C'\fR
was initially made magical.
.Sh "Magic Virtual Tables"
.IX Subsection "Magic Virtual Tables"
The \f(CW\*(C`mg_virtual\*(C'\fR field in the \f(CW\*(C`MAGIC\*(C'\fR structure is a pointer to an
\&\f(CW\*(C`MGVTBL\*(C'\fR, which is a structure of function pointers and stands for
\&\*(L"Magic Virtual Table\*(R" to handle the various operations that might be
applied to that variable.
.PP
The \f(CW\*(C`MGVTBL\*(C'\fR has five (or sometimes eight) pointers to the following
routine types:
.PP
.Vb 5
\&    int  (*svt_get)(SV* sv, MAGIC* mg);
\&    int  (*svt_set)(SV* sv, MAGIC* mg);
\&    U32  (*svt_len)(SV* sv, MAGIC* mg);
\&    int  (*svt_clear)(SV* sv, MAGIC* mg);
\&    int  (*svt_free)(SV* sv, MAGIC* mg);