perlguts.1

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

the following macros:
.PP
.Vb 2
\&    SvCUR(SV*)
\&    SvCUR_set(SV*, I32 val)
.Ve
.PP
You can also get a pointer to the end of the string stored in the \s-1SV\s0
with the macro:
.PP
.Vb 1
\&    SvEND(SV*)
.Ve
.PP
But note that these last three macros are valid only if \f(CW\*(C`SvPOK()\*(C'\fR is true.
.PP
If you want to append something to the end of string stored in an \f(CW\*(C`SV*\*(C'\fR,
you can use the following functions:
.PP
.Vb 5
\&    void  sv_catpv(SV*, const char*);
\&    void  sv_catpvn(SV*, const char*, STRLEN);
\&    void  sv_catpvf(SV*, const char*, ...);
\&    void  sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
\&    void  sv_catsv(SV*, SV*);
.Ve
.PP
The first function calculates the length of the string to be appended by
using \f(CW\*(C`strlen\*(C'\fR.  In the second, you specify the length of the string
yourself.  The third function processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and
appends the formatted output.  The fourth function works like \f(CW\*(C`vsprintf\*(C'\fR.
You can specify the address and length of an array of SVs instead of the
va_list argument. The fifth function extends the string stored in the first
\&\s-1SV\s0 with the string stored in the second \s-1SV\s0.  It also forces the second \s-1SV\s0
to be interpreted as a string.
.PP
The \f(CW\*(C`sv_cat*()\*(C'\fR functions are not generic enough to operate on values that
have \*(L"magic\*(R".  See \*(L"Magic Virtual Tables\*(R" later in this document.
.PP
If you know the name of a scalar variable, you can get a pointer to its \s-1SV\s0
by using the following:
.PP
.Vb 1
\&    SV*  get_sv("package::varname", FALSE);
.Ve
.PP
This returns \s-1NULL\s0 if the variable does not exist.
.PP
If you want to know if this variable (or any other \s-1SV\s0) is actually \f(CW\*(C`defined\*(C'\fR,
you can call:
.PP
.Vb 1
\&    SvOK(SV*)
.Ve
.PP
The scalar \f(CW\*(C`undef\*(C'\fR value is stored in an \s-1SV\s0 instance called \f(CW\*(C`PL_sv_undef\*(C'\fR.
.PP
Its address can be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed. Make sure that
you don't try to compare a random sv with \f(CW&PL_sv_undef\fR. For example
when interfacing Perl code, it'll work correctly for:
.PP
.Vb 1
\&  foo(undef);
.Ve
.PP
But won't work when called as:
.PP
.Vb 2
\&  $x = undef;
\&  foo($x);
.Ve
.PP
So to repeat always use \fISvOK()\fR to check whether an sv is defined.
.PP
Also you have to be careful when using \f(CW&PL_sv_undef\fR as a value in
AVs or HVs (see \*(L"AVs, HVs and undefined values\*(R").
.PP
There are also the two values \f(CW\*(C`PL_sv_yes\*(C'\fR and \f(CW\*(C`PL_sv_no\*(C'\fR, which contain
boolean \s-1TRUE\s0 and \s-1FALSE\s0 values, respectively.  Like \f(CW\*(C`PL_sv_undef\*(C'\fR, their
addresses can be used whenever an \f(CW\*(C`SV*\*(C'\fR is needed.
.PP
Do not be fooled into thinking that \f(CW\*(C`(SV *) 0\*(C'\fR is the same as \f(CW&PL_sv_undef\fR.
Take this code:
.PP
.Vb 5
\&    SV* sv = (SV*) 0;
\&    if (I\-am\-to\-return\-a\-real\-value) {
\&            sv = sv_2mortal(newSViv(42));
\&    }
\&    sv_setsv(ST(0), sv);
.Ve
.PP
This code tries to return a new \s-1SV\s0 (which contains the value 42) if it should
return a real value, or undef otherwise.  Instead it has returned a \s-1NULL\s0
pointer which, somewhere down the line, will cause a segmentation violation,
bus error, or just weird results.  Change the zero to \f(CW&PL_sv_undef\fR in the
first line and all will be well.
.PP
To free an \s-1SV\s0 that you've created, call \f(CW\*(C`SvREFCNT_dec(SV*)\*(C'\fR.  Normally this
call is not necessary (see \*(L"Reference Counts and Mortality\*(R").
.Sh "Offsets"
.IX Subsection "Offsets"
Perl provides the function \f(CW\*(C`sv_chop\*(C'\fR to efficiently remove characters
from the beginning of a string; you give it an \s-1SV\s0 and a pointer to
somewhere inside the \s-1PV\s0, and it discards everything before the
pointer. The efficiency comes by means of a little hack: instead of
actually removing the characters, \f(CW\*(C`sv_chop\*(C'\fR sets the flag \f(CW\*(C`OOK\*(C'\fR
(offset \s-1OK\s0) to signal to other functions that the offset hack is in
effect, and it puts the number of bytes chopped off into the \s-1IV\s0 field
of the \s-1SV\s0. It then moves the \s-1PV\s0 pointer (called \f(CW\*(C`SvPVX\*(C'\fR) forward that
many bytes, and adjusts \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR.
.PP
Hence, at this point, the start of the buffer that we allocated lives
at \f(CW\*(C`SvPVX(sv) \- SvIV(sv)\*(C'\fR in memory and the \s-1PV\s0 pointer is pointing
into the middle of this allocated storage.
.PP
This is best demonstrated by example:
.PP
.Vb 8
\&  % ./perl \-Ilib \-MDevel::Peek \-le \*(Aq$a="12345"; $a=~s/.//; Dump($a)\*(Aq
\&  SV = PVIV(0x8128450) at 0x81340f0
\&    REFCNT = 1
\&    FLAGS = (POK,OOK,pPOK)
\&    IV = 1  (OFFSET)
\&    PV = 0x8135781 ( "1" . ) "2345"\e0
\&    CUR = 4
\&    LEN = 5
.Ve
.PP
Here the number of bytes chopped off (1) is put into \s-1IV\s0, and
\&\f(CW\*(C`Devel::Peek::Dump\*(C'\fR helpfully reminds us that this is an offset. The
portion of the string between the \*(L"real\*(R" and the \*(L"fake\*(R" beginnings is
shown in parentheses, and the values of \f(CW\*(C`SvCUR\*(C'\fR and \f(CW\*(C`SvLEN\*(C'\fR reflect
the fake beginning, not the real one.
.PP
Something similar to the offset hack is performed on AVs to enable
efficient shifting and splicing off the beginning of the array; while
\&\f(CW\*(C`AvARRAY\*(C'\fR points to the first element in the array that is visible from
Perl, \f(CW\*(C`AvALLOC\*(C'\fR points to the real start of the C array. These are
usually the same, but a \f(CW\*(C`shift\*(C'\fR operation can be carried out by
increasing \f(CW\*(C`AvARRAY\*(C'\fR by one and decreasing \f(CW\*(C`AvFILL\*(C'\fR and \f(CW\*(C`AvLEN\*(C'\fR.
Again, the location of the real start of the C array only comes into
play when freeing the array. See \f(CW\*(C`av_shift\*(C'\fR in \fIav.c\fR.
.Sh "What's Really Stored in an \s-1SV\s0?"
.IX Subsection "What's Really Stored in an SV?"
Recall that the usual method of determining the type of scalar you have is
to use \f(CW\*(C`Sv*OK\*(C'\fR macros.  Because a scalar can be both a number and a string,
usually these macros will always return \s-1TRUE\s0 and calling the \f(CW\*(C`Sv*V\*(C'\fR
macros will do the appropriate conversion of string to integer/double or
integer/double to string.
.PP
If you \fIreally\fR need to know if you have an integer, double, or string
pointer in an \s-1SV\s0, you can use the following three macros instead:
.PP
.Vb 3
\&    SvIOKp(SV*)
\&    SvNOKp(SV*)
\&    SvPOKp(SV*)
.Ve
.PP
These will tell you if you truly have an integer, double, or string pointer
stored in your \s-1SV\s0.  The \*(L"p\*(R" stands for private.
.PP
The are various ways in which the private and public flags may differ.
For example, a tied \s-1SV\s0 may have a valid underlying value in the \s-1IV\s0 slot
(so SvIOKp is true), but the data should be accessed via the \s-1FETCH\s0
routine rather than directly, so SvIOK is false. Another is when
numeric conversion has occurred and precision has been lost: only the
private flag is set on 'lossy' values. So when an \s-1NV\s0 is converted to an
\&\s-1IV\s0 with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.
.PP
In general, though, it's best to use the \f(CW\*(C`Sv*V\*(C'\fR macros.
.Sh "Working with AVs"
.IX Subsection "Working with AVs"
There are two ways to create and load an \s-1AV\s0.  The first method creates an
empty \s-1AV:\s0
.PP
.Vb 1
\&    AV*  newAV();
.Ve
.PP
The second method both creates the \s-1AV\s0 and initially populates it with SVs:
.PP
.Vb 1
\&    AV*  av_make(I32 num, SV **ptr);
.Ve
.PP
The second argument points to an array containing \f(CW\*(C`num\*(C'\fR \f(CW\*(C`SV*\*(C'\fR's.  Once the
\&\s-1AV\s0 has been created, the SVs can be destroyed, if so desired.
.PP
Once the \s-1AV\s0 has been created, the following operations are possible on AVs:
.PP
.Vb 4
\&    void  av_push(AV*, SV*);
\&    SV*   av_pop(AV*);
\&    SV*   av_shift(AV*);
\&    void  av_unshift(AV*, I32 num);
.Ve
.PP
These should be familiar operations, with the exception of \f(CW\*(C`av_unshift\*(C'\fR.
This routine adds \f(CW\*(C`num\*(C'\fR elements at the front of the array with the \f(CW\*(C`undef\*(C'\fR
value.  You must then use \f(CW\*(C`av_store\*(C'\fR (described below) to assign values
to these new elements.
.PP
Here are some other functions:
.PP
.Vb 3
\&    I32   av_len(AV*);
\&    SV**  av_fetch(AV*, I32 key, I32 lval);
\&    SV**  av_store(AV*, I32 key, SV* val);
.Ve
.PP
The \f(CW\*(C`av_len\*(C'\fR function returns the highest index value in array (just
like $#array in Perl).  If the array is empty, \-1 is returned.  The
\&\f(CW\*(C`av_fetch\*(C'\fR function returns the value at index \f(CW\*(C`key\*(C'\fR, but if \f(CW\*(C`lval\*(C'\fR
is non-zero, then \f(CW\*(C`av_fetch\*(C'\fR will store an undef value at that index.
The \f(CW\*(C`av_store\*(C'\fR function stores the value \f(CW\*(C`val\*(C'\fR at index \f(CW\*(C`key\*(C'\fR, and does
not increment the reference count of \f(CW\*(C`val\*(C'\fR.  Thus the caller is responsible
for taking care of that, and if \f(CW\*(C`av_store\*(C'\fR returns \s-1NULL\s0, the caller will
have to decrement the reference count to avoid a memory leak.  Note that
\&\f(CW\*(C`av_fetch\*(C'\fR and \f(CW\*(C`av_store\*(C'\fR both return \f(CW\*(C`SV**\*(C'\fR's, not \f(CW\*(C`SV*\*(C'\fR's as their
return value.
.PP
.Vb 3
\&    void  av_clear(AV*);
\&    void  av_undef(AV*);
\&    void  av_extend(AV*, I32 key);
.Ve
.PP
The \f(CW\*(C`av_clear\*(C'\fR function deletes all the elements in the AV* array, but
does not actually delete the array itself.  The \f(CW\*(C`av_undef\*(C'\fR function will
delete all the elements in the array plus the array itself.  The
\&\f(CW\*(C`av_extend\*(C'\fR function extends the array so that it contains at least \f(CW\*(C`key+1\*(C'\fR
elements.  If \f(CW\*(C`key+1\*(C'\fR is less than the currently allocated length of the array,
then nothing is done.
.PP
If you know the name of an array variable, you can get a pointer to its \s-1AV\s0
by using the following:
.PP
.Vb 1
\&    AV*  get_av("package::varname", FALSE);
.Ve
.PP
This returns \s-1NULL\s0 if the variable does not exist.
.PP
See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" for more
information on how to use the array access functions on tied arrays.
.Sh "Working with HVs"
.IX Subsection "Working with HVs"
To create an \s-1HV\s0, you use the following routine:
.PP
.Vb 1
\&    HV*  newHV();
.Ve
.PP
Once the \s-1HV\s0 has been created, the following operations are possible on HVs:
.PP
.Vb 2
\&    SV**  hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
\&    SV**  hv_fetch(HV*, const char* key, U32 klen, I32 lval);
.Ve
.PP
The \f(CW\*(C`klen\*(C'\fR parameter is the length of the key being passed in (Note that
you cannot pass 0 in as a value of \f(CW\*(C`klen\*(C'\fR to tell Perl to measure the
length of the key).  The \f(CW\*(C`val\*(C'\fR argument contains the \s-1SV\s0 pointer to the
scalar being stored, and \f(CW\*(C`hash\*(C'\fR is the precomputed hash value (zero if
you want \f(CW\*(C`hv_store\*(C'\fR to calculate it for you).  The \f(CW\*(C`lval\*(C'\fR parameter
indicates whether this fetch is actually a part of a store operation, in
which case a new undefined value will be added to the \s-1HV\s0 with the supplied
key and \f(CW\*(C`hv_fetch\*(C'\fR will return as if the value had already existed.
.PP
Remember that \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_fetch\*(C'\fR return \f(CW\*(C`SV**\*(C'\fR's and not just
\&\f(CW\*(C`SV*\*(C'\fR.  To access the scalar value, you must first dereference the return
value.  However, you should check to make sure that the return value is
not \s-1NULL\s0 before dereferencing it.
.PP
These two functions check if a hash table entry exists, and deletes it.
.PP
.Vb 2
\&    bool  hv_exists(HV*, const char* key, U32 klen);
\&    SV*   hv_delete(HV*, const char* key, U32 klen, I32 flags);
.Ve
.PP
If \f(CW\*(C`flags\*(C'\fR does not include the \f(CW\*(C`G_DISCARD\*(C'\fR flag then \f(CW\*(C`hv_delete\*(C'\fR will
create and return a mortal copy of the deleted value.
.PP
And more miscellaneous functions:
.PP
.Vb 2
\&    void   hv_clear(HV*);
\&    void   hv_undef(HV*);
.Ve
.PP
Like their \s-1AV\s0 counterparts, \f(CW\*(C`hv_clear\*(C'\fR deletes all the entries in the hash
table but does not actually delete the hash table.  The \f(CW\*(C`hv_undef\*(C'\fR deletes
both the entries and the hash table itself.
.PP
Perl keeps the actual data in linked list of structures with a typedef of \s-1HE\s0.
These contain the actual key and value pointers (plus extra administrative
overhead).  The key is a string pointer; the value is an \f(CW\*(C`SV*\*(C'\fR.  However,
once you have an \f(CW\*(C`HE*\*(C'\fR, to get the actual key and value, use the routines
specified below.
.PP
.Vb 10
\&    I32    hv_iterinit(HV*);
\&            /* Prepares starting point to traverse hash table */
\&    HE*    hv_iternext(HV*);
\&            /* Get the next entry, and return a pointer to a
\&               structure that has both the key and value */
\&    char*  hv_iterkey(HE* entry, I32* retlen);