perlapi.1

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

responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before
the call, and decrementing it if the function returned \s-1NULL\s0.  Effectively
a successful hv_store takes ownership of one reference to \f(CW\*(C`val\*(C'\fR.  This is
usually what you want; a newly created \s-1SV\s0 has a reference count of one, so
if all your code does is create SVs then store them in a hash, hv_store
will own the only reference to the new \s-1SV\s0, and your code doesn't need to do
anything further to tidy up.  hv_store is not implemented as a call to
hv_store_ent, and does not create a temporary \s-1SV\s0 for the key, so if your
key data is not already in \s-1SV\s0 form then use hv_store in preference to
hv_store_ent.
.Sp
See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more
information on how to use this function on tied hashes.
.Sp
.Vb 1
\&        SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
.Ve
.IP "hv_stores" 8
.IX Xref "hv_stores"
.IX Item "hv_stores"
Like \f(CW\*(C`hv_store\*(C'\fR, but takes a literal string instead of a string/length pair
and omits the hash parameter.
.Sp
.Vb 1
\&        SV**    hv_stores(HV* tb, const char* key, NULLOK SV* val)
.Ve
.IP "hv_store_ent" 8
.IX Xref "hv_store_ent"
.IX Item "hv_store_ent"
Stores \f(CW\*(C`val\*(C'\fR in a hash.  The hash key is specified as \f(CW\*(C`key\*(C'\fR.  The \f(CW\*(C`hash\*(C'\fR
parameter is the precomputed hash value; if it is zero then Perl will
compute it.  The return value is the new hash entry so created.  It will be
\&\s-1NULL\s0 if the operation failed or if the value did not need to be actually
stored within the hash (as in the case of tied hashes).  Otherwise the
contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros
described here.  Note that the caller is responsible for suitably
incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and
decrementing it if the function returned \s-1NULL\s0.  Effectively a successful
hv_store_ent takes ownership of one reference to \f(CW\*(C`val\*(C'\fR.  This is
usually what you want; a newly created \s-1SV\s0 has a reference count of one, so
if all your code does is create SVs then store them in a hash, hv_store
will own the only reference to the new \s-1SV\s0, and your code doesn't need to do
anything further to tidy up.  Note that hv_store_ent only reads the \f(CW\*(C`key\*(C'\fR;
unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct
reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller's responsibility.  hv_store
is not implemented as a call to hv_store_ent, and does not create a temporary
\&\s-1SV\s0 for the key, so if your key data is not already in \s-1SV\s0 form then use
hv_store in preference to hv_store_ent.
.Sp
See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more
information on how to use this function on tied hashes.
.Sp
.Vb 1
\&        HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
.Ve
.IP "hv_undef" 8
.IX Xref "hv_undef"
.IX Item "hv_undef"
Undefines the hash.
.Sp
.Vb 1
\&        void    hv_undef(HV* tb)
.Ve
.IP "newHV" 8
.IX Xref "newHV"
.IX Item "newHV"
Creates a new \s-1HV\s0.  The reference count is set to 1.
.Sp
.Vb 1
\&        HV*     newHV()
.Ve
.SH "Magical Functions"
.IX Header "Magical Functions"
.IP "mg_clear" 8
.IX Xref "mg_clear"
.IX Item "mg_clear"
Clear something magical that the \s-1SV\s0 represents.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        int     mg_clear(SV* sv)
.Ve
.IP "mg_copy" 8
.IX Xref "mg_copy"
.IX Item "mg_copy"
Copies the magic from one \s-1SV\s0 to another.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
.Ve
.IP "mg_find" 8
.IX Xref "mg_find"
.IX Item "mg_find"
Finds the magic pointer for type matching the \s-1SV\s0.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        MAGIC*  mg_find(const SV* sv, int type)
.Ve
.IP "mg_free" 8
.IX Xref "mg_free"
.IX Item "mg_free"
Free any magic storage used by the \s-1SV\s0.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        int     mg_free(SV* sv)
.Ve
.IP "mg_get" 8
.IX Xref "mg_get"
.IX Item "mg_get"
Do magic after a value is retrieved from the \s-1SV\s0.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        int     mg_get(SV* sv)
.Ve
.IP "mg_length" 8
.IX Xref "mg_length"
.IX Item "mg_length"
Report on the \s-1SV\s0's length.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        U32     mg_length(SV* sv)
.Ve
.IP "mg_magical" 8
.IX Xref "mg_magical"
.IX Item "mg_magical"
Turns on the magical status of an \s-1SV\s0.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        void    mg_magical(SV* sv)
.Ve
.IP "mg_set" 8
.IX Xref "mg_set"
.IX Item "mg_set"
Do magic after a value is assigned to the \s-1SV\s0.  See \f(CW\*(C`sv_magic\*(C'\fR.
.Sp
.Vb 1
\&        int     mg_set(SV* sv)
.Ve
.IP "SvGETMAGIC" 8
.IX Xref "SvGETMAGIC"
.IX Item "SvGETMAGIC"
Invokes \f(CW\*(C`mg_get\*(C'\fR on an \s-1SV\s0 if it has 'get' magic.  This macro evaluates its
argument more than once.
.Sp
.Vb 1
\&        void    SvGETMAGIC(SV* sv)
.Ve
.IP "SvLOCK" 8
.IX Xref "SvLOCK"
.IX Item "SvLOCK"
Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
has been loaded.
.Sp
.Vb 1
\&        void    SvLOCK(SV* sv)
.Ve
.IP "SvSETMAGIC" 8
.IX Xref "SvSETMAGIC"
.IX Item "SvSETMAGIC"
Invokes \f(CW\*(C`mg_set\*(C'\fR on an \s-1SV\s0 if it has 'set' magic.  This macro evaluates its
argument more than once.
.Sp
.Vb 1
\&        void    SvSETMAGIC(SV* sv)
.Ve
.IP "SvSetMagicSV" 8
.IX Xref "SvSetMagicSV"
.IX Item "SvSetMagicSV"
Like \f(CW\*(C`SvSetSV\*(C'\fR, but does any set magic required afterwards.
.Sp
.Vb 1
\&        void    SvSetMagicSV(SV* dsb, SV* ssv)
.Ve
.IP "SvSetMagicSV_nosteal" 8
.IX Xref "SvSetMagicSV_nosteal"
.IX Item "SvSetMagicSV_nosteal"
Like \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, but does any set magic required afterwards.
.Sp
.Vb 1
\&        void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
.Ve
.IP "SvSetSV" 8
.IX Xref "SvSetSV"
.IX Item "SvSetSV"
Calls \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as ssv.  May evaluate arguments
more than once.
.Sp
.Vb 1
\&        void    SvSetSV(SV* dsb, SV* ssv)
.Ve
.IP "SvSetSV_nosteal" 8
.IX Xref "SvSetSV_nosteal"
.IX Item "SvSetSV_nosteal"
Calls a non-destructive version of \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as
ssv. May evaluate arguments more than once.
.Sp
.Vb 1
\&        void    SvSetSV_nosteal(SV* dsv, SV* ssv)
.Ve
.IP "SvSHARE" 8
.IX Xref "SvSHARE"
.IX Item "SvSHARE"
Arranges for sv to be shared between threads if a suitable module
has been loaded.
.Sp
.Vb 1
\&        void    SvSHARE(SV* sv)
.Ve
.IP "SvUNLOCK" 8
.IX Xref "SvUNLOCK"
.IX Item "SvUNLOCK"
Releases a mutual exclusion lock on sv if a suitable module
has been loaded.
.Sp
.Vb 1
\&        void    SvUNLOCK(SV* sv)
.Ve
.SH "Memory Management"
.IX Header "Memory Management"
.IP "Copy" 8
.IX Xref "Copy"
.IX Item "Copy"
The XSUB-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function.  The \f(CW\*(C`src\*(C'\fR is the
source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is
the type.  May fail on overlapping copies.  See also \f(CW\*(C`Move\*(C'\fR.
.Sp
.Vb 1
\&        void    Copy(void* src, void* dest, int nitems, type)
.Ve
.IP "CopyD" 8
.IX Xref "CopyD"
.IX Item "CopyD"
Like \f(CW\*(C`Copy\*(C'\fR but returns dest. Useful for encouraging compilers to tail-call
optimise.
.Sp
.Vb 1
\&        void *  CopyD(void* src, void* dest, int nitems, type)
.Ve
.IP "Move" 8
.IX Xref "Move"
.IX Item "Move"
The XSUB-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function.  The \f(CW\*(C`src\*(C'\fR is the
source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is
the type.  Can do overlapping moves.  See also \f(CW\*(C`Copy\*(C'\fR.
.Sp
.Vb 1
\&        void    Move(void* src, void* dest, int nitems, type)
.Ve
.IP "MoveD" 8
.IX Xref "MoveD"
.IX Item "MoveD"
Like \f(CW\*(C`Move\*(C'\fR but returns dest. Useful for encouraging compilers to tail-call
optimise.
.Sp
.Vb 1
\&        void *  MoveD(void* src, void* dest, int nitems, type)
.Ve
.IP "Newx" 8
.IX Xref "Newx"
.IX Item "Newx"
The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function.
.Sp
In 5.9.3, \fINewx()\fR and friends replace the older \fINew()\fR \s-1API\s0, and drops
the first parameter, \fIx\fR, a debug aid which allowed callers to identify
themselves.  This aid has been superseded by a new build option,
\&\s-1PERL_MEM_LOG\s0 (see \*(L"\s-1PERL_MEM_LOG\s0\*(R" in perlhack).  The older \s-1API\s0 is still
there for use in \s-1XS\s0 modules supporting older perls.
.Sp
.Vb 1
\&        void    Newx(void* ptr, int nitems, type)
.Ve
.IP "Newxc" 8
.IX Xref "Newxc"
.IX Item "Newxc"
The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with
cast.  See also \f(CW\*(C`Newx\*(C'\fR.
.Sp
.Vb 1
\&        void    Newxc(void* ptr, int nitems, type, cast)
.Ve
.IP "Newxz" 8
.IX Xref "Newxz"
.IX Item "Newxz"
The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function.  The allocated
memory is zeroed with \f(CW\*(C`memzero\*(C'\fR.  See also \f(CW\*(C`Newx\*(C'\fR.
.Sp
.Vb 1
\&        void    Newxz(void* ptr, int nitems, type)
.Ve
.IP "Poison" 8
.IX Xref "Poison"
.IX Item "Poison"
PoisonWith(0xEF) for catching access to freed memory.
.Sp
.Vb 1
\&        void    Poison(void* dest, int nitems, type)
.Ve
.IP "PoisonFree" 8
.IX Xref "PoisonFree"
.IX Item "PoisonFree"
PoisonWith(0xEF) for catching access to freed memory.
.Sp
.Vb 1
\&        void    PoisonFree(void* dest, int nitems, type)
.Ve
.IP "PoisonNew" 8
.IX Xref "PoisonNew"
.IX Item "PoisonNew"
PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
.Sp
.Vb 1
\&        void    PoisonNew(void* dest, int nitems, type)
.Ve
.IP "PoisonWith" 8
.IX Xref "PoisonWith"
.IX Item "PoisonWith"
Fill up memory with a byte pattern (a byte repeated over and over
again) that hopefully catches attempts to access uninitialized memory.
.Sp
.Vb 1
\&        void    PoisonWith(void* dest, int nitems, type, U8 byte)
.Ve
.IP "Renew" 8
.IX Xref "Renew"
.IX Item "Renew"
The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function.
.Sp
.Vb 1
\&        void    Renew(void* ptr, int nitems, type)
.Ve
.IP "Renewc" 8
.IX Xref "Renewc"
.IX Item "Renewc"
The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with
cast.
.Sp
.Vb 1
\&        void    Renewc(void* ptr, int nitems, type, cast)
.Ve
.IP "Safefree" 8
.IX Xref "Safefree"
.IX Item "Safefree"
The XSUB-writer's interface to the C \f(CW\*(C`free\*(C'\fR function.
.Sp
.Vb 1
\&        void    Safefree(void* ptr)
.Ve
.IP "savepv" 8
.IX Xref "savepv"
.IX Item "savepv"
Perl's version of \f(CW\*(C`strdup()\*(C'\fR. Returns a pointer to a newly allocated
string which is a duplicate of \f(CW\*(C`pv\*(C'\fR. The size of the string is
determined by \f(CW\*(C`strlen()\*(C'\fR. The memory allocated for the new string can
be freed with the \f(CW\*(C`Safefree()\*(C'\fR function.
.Sp
.Vb 1
\&        char*   savepv(const char* pv)
.Ve
.IP "savepvn" 8
.IX Xref "savepvn"
.IX Item "savepvn"
Perl's version of what \f(CW\*(C`strndup()\*(C'\fR would be if it existed. Returns a
pointer to a newly allocated string which is a duplicate of the first
\&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR, plus a trailing \s-1NUL\s0 byte. The memory allocated for
the new string can be freed with the \f(CW\*(C`Safefree()\*(C'\fR function.
.Sp
.Vb 1
\&        char*   savepvn(const char* pv, I32 len)
.Ve
.IP "savepvs" 8
.IX Xref "savepvs"
.IX Item "savepvs"
Like \f(CW\*(C`savepvn\*(C'\fR, but takes a literal string instead of a string/length pair.
.Sp
.Vb 1
\&        char*   savepvs(const char* s)
.Ve
.IP "savesharedpv" 8
.IX Xref "savesharedpv"
.IX Item "savesharedpv"
A version of \f(CW\*(C`savepv()\*(C'\fR which allocates the duplicate string in memory
which is shared between threads.
.Sp
.Vb 1
\&        char*   savesharedpv(const char* pv)
.Ve
.IP "savesharedpvn" 8
.IX Xref "savesharedpvn"
.IX Item "savesharedpvn"
A version of \f(CW\*(C`savepvn()\*(C'\fR which allocates the duplicate string in memory
which is shared between threads. (With the specific difference that a \s-1NULL\s0
pointer is not acceptable)
.Sp
.Vb 1
\&        char*   savesharedpvn(const char *const pv, const STRLEN len)
.Ve
.IP "savesvpv" 8
.IX Xref "savesvpv"
.IX Item "savesvpv