perlcall.1

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

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PERLCALL 1"
.TH PERLCALL 1 "2007-12-18" "perl v5.10.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
perlcall \- Perl calling conventions from C
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write \fIcallbacks\fR.
.PP
Apart from discussing the C interface provided by Perl for writing
callbacks the document uses a series of examples to show how the
interface actually works in practice.  In addition some techniques for
coding callbacks are covered.
.PP
Examples where callbacks are necessary include
.IP "\(bu" 5
An Error Handler
.Sp
You have created an \s-1XSUB\s0 interface to an application's C \s-1API\s0.
.Sp
A fairly common feature in applications is to allow you to define a C
function that will be called whenever something nasty occurs. What we
would like is to be able to specify a Perl subroutine that will be
called instead.
.IP "\(bu" 5
An Event Driven Program
.Sp
The classic example of where callbacks are used is when writing an
event driven program like for an X windows application.  In this case
you register functions to be called whenever specific events occur,
e.g., a mouse button is pressed, the cursor moves into a window or a
menu item is selected.
.PP
Although the techniques described here are applicable when embedding
Perl in a C program, this is not the primary goal of this document.
There are other details that must be considered and are specific to
embedding Perl. For details on embedding Perl in C refer to
perlembed.
.PP
Before you launch yourself head first into the rest of this document,
it would be a good idea to have read the following two documents \-
perlxs and perlguts.
.SH "THE CALL_ FUNCTIONS"
.IX Header "THE CALL_ FUNCTIONS"
Although this stuff is easier to explain using examples, you first need
be aware of a few important definitions.
.PP
Perl has a number of C functions that allow you to call Perl
subroutines.  They are
.PP
.Vb 4
\&    I32 call_sv(SV* sv, I32 flags);
\&    I32 call_pv(char *subname, I32 flags);
\&    I32 call_method(char *methname, I32 flags);
\&    I32 call_argv(char *subname, I32 flags, register char **argv);
.Ve
.PP
The key function is \fIcall_sv\fR.  All the other functions are
fairly simple wrappers which make it easier to call Perl subroutines in
special cases. At the end of the day they will all call \fIcall_sv\fR
to invoke the Perl subroutine.
.PP
All the \fIcall_*\fR functions have a \f(CW\*(C`flags\*(C'\fR parameter which is
used to pass a bit mask of options to Perl.  This bit mask operates
identically for each of the functions.  The settings available in the
bit mask are discussed in \*(L"\s-1FLAG\s0 \s-1VALUES\s0\*(R".
.PP
Each of the functions will now be discussed in turn.
.IP "call_sv" 5
.IX Item "call_sv"
\&\fIcall_sv\fR takes two parameters, the first, \f(CW\*(C`sv\*(C'\fR, is an SV*.
This allows you to specify the Perl subroutine to be called either as a
C string (which has first been converted to an \s-1SV\s0) or a reference to a
subroutine. The section, \fIUsing call_sv\fR, shows how you can make
use of \fIcall_sv\fR.
.IP "call_pv" 5
.IX Item "call_pv"
The function, \fIcall_pv\fR, is similar to \fIcall_sv\fR except it
expects its first parameter to be a C char* which identifies the Perl
subroutine you want to call, e.g., \f(CW\*(C`call_pv("fred", 0)\*(C'\fR.  If the
subroutine you want to call is in another package, just include the
package name in the string, e.g., \f(CW"pkg::fred"\fR.
.IP "call_method" 5
.IX Item "call_method"
The function \fIcall_method\fR is used to call a method from a Perl
class.  The parameter \f(CW\*(C`methname\*(C'\fR corresponds to the name of the method
to be called.  Note that the class that the method belongs to is passed
on the Perl stack rather than in the parameter list. This class can be
either the name of the class (for a static method) or a reference to an
object (for a virtual method).  See perlobj for more information on
static and virtual methods and \*(L"Using call_method\*(R" for an example
of using \fIcall_method\fR.
.IP "call_argv" 5
.IX Item "call_argv"
\&\fIcall_argv\fR calls the Perl subroutine specified by the C string
stored in the \f(CW\*(C`subname\*(C'\fR parameter. It also takes the usual \f(CW\*(C`flags\*(C'\fR
parameter.  The final parameter, \f(CW\*(C`argv\*(C'\fR, consists of a \s-1NULL\s0 terminated
list of C strings to be passed as parameters to the Perl subroutine.
See \fIUsing call_argv\fR.
.PP
All the functions return an integer. This is a count of the number of
items returned by the Perl subroutine. The actual items returned by the
subroutine are stored on the Perl stack.
.PP
As a general rule you should \fIalways\fR check the return value from
these functions.  Even if you are expecting only a particular number of
values to be returned from the Perl subroutine, there is nothing to
stop someone from doing something unexpected\*(--don't say you haven't
been warned.
.SH "FLAG VALUES"
.IX Header "FLAG VALUES"
The \f(CW\*(C`flags\*(C'\fR parameter in all the \fIcall_*\fR functions is a bit mask
which can consist of any combination of the symbols defined below,
\&\s-1OR\s0'ed together.
.Sh "G_VOID"
.IX Subsection "G_VOID"
Calls the Perl subroutine in a void context.
.PP
This flag has 2 effects:
.IP "1." 5
It indicates to the subroutine being called that it is executing in
a void context (if it executes \fIwantarray\fR the result will be the
undefined value).
.IP "2." 5
It ensures that nothing is actually returned from the subroutine.
.PP
The value returned by the \fIcall_*\fR function indicates how many
items have been returned by the Perl subroutine \- in this case it will
be 0.
.Sh "G_SCALAR"
.IX Subsection "G_SCALAR"
Calls the Perl subroutine in a scalar context.  This is the default
context flag setting for all the \fIcall_*\fR functions.
.PP
This flag has 2 effects:
.IP "1." 5
It indicates to the subroutine being called that it is executing in a
scalar context (if it executes \fIwantarray\fR the result will be false).
.IP "2." 5
It ensures that only a scalar is actually returned from the subroutine.
The subroutine can, of course,  ignore the \fIwantarray\fR and return a
list anyway. If so, then only the last element of the list will be
returned.
.PP
The value returned by the \fIcall_*\fR function indicates how many
items have been returned by the Perl subroutine \- in this case it will
be either 0 or 1.
.PP
If 0, then you have specified the G_DISCARD flag.
.PP
If 1, then the item actually returned by the Perl subroutine will be
stored on the Perl stack \- the section \fIReturning a Scalar\fR shows how
to access this value on the stack.  Remember that regardless of how
many items the Perl subroutine returns, only the last one will be
accessible from the stack \- think of the case where only one value is
returned as being a list with only one element.  Any other items that
were returned will not exist by the time control returns from the
\&\fIcall_*\fR function.  The section \fIReturning a list in a scalar
context\fR shows an example of this behavior.
.Sh "G_ARRAY"
.IX Subsection "G_ARRAY"
Calls the Perl subroutine in a list context.
.PP
As with G_SCALAR, this flag has 2 effects:
.IP "1." 5
It indicates to the subroutine being called that it is executing in a
list context (if it executes \fIwantarray\fR the result will be true).
.IP "2." 5
It ensures that all items returned from the subroutine will be
accessible when control returns from the \fIcall_*\fR function.
.PP
The value returned by the \fIcall_*\fR function indicates how many
items have been returned by the Perl subroutine.
.PP
If 0, then you have specified the G_DISCARD flag.
.PP
If not 0, then it will be a count of the number of items returned by
the subroutine. These items will be stored on the Perl stack.  The
section \fIReturning a list of values\fR gives an example of using the
G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.
.Sh "G_DISCARD"
.IX Subsection "G_DISCARD"
By default, the \fIcall_*\fR functions place the items returned from
by the Perl subroutine on the stack.  If you are not interested in
these items, then setting this flag will make Perl get rid of them
automatically for you.  Note that it is still possible to indicate a
context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
.PP
If you do not set this flag then it is \fIvery\fR important that you make
sure that any temporaries (i.e., parameters passed to the Perl
subroutine and values returned from the subroutine) are disposed of
yourself.  The section \fIReturning a Scalar\fR gives details of how to
dispose of these temporaries explicitly and the section \fIUsing Perl to
dispose of temporaries\fR discusses the specific circumstances where you
can ignore the problem and let Perl deal with it for you.
.Sh "G_NOARGS"
.IX Subsection "G_NOARGS"
Whenever a Perl subroutine is called using one of the \fIcall_*\fR
functions, it is assumed by default that parameters are to be passed to
the subroutine.  If you are not passing any parameters to the Perl
subroutine, you can save a bit of time by setting this flag.  It has
the effect of not creating the \f(CW@_\fR array for the Perl subroutine.
.PP
Although the functionality provided by this flag may seem
straightforward, it should be used only if there is a good reason to do
so.  The reason for being cautious is that even if you have specified
the G_NOARGS flag, it is still possible for the Perl subroutine that
has been called to think that you have passed it parameters.
.PP
In fact, what can happen is that the Perl subroutine you have called
can access the \f(CW@_\fR array from a previous Perl subroutine.  This will
occur when the code that is executing the \fIcall_*\fR function has
itself been called from another Perl subroutine. The code below
illustrates this
.PP
.Vb 2
\&    sub fred
\&      { print "@_\en"  }
\&
\&    sub joe
\&      { &fred }
\&
\&    &joe(1,2,3);
.Ve
.PP
This will print
.PP
.Vb 1
\&    1 2 3
.Ve
.PP
What has happened is that \f(CW\*(C`fred\*(C'\fR accesses the \f(CW@_\fR array which
belongs to \f(CW\*(C`joe\*(C'\fR.
.Sh "G_EVAL"
.IX Subsection "G_EVAL"
It is possible for the Perl subroutine you are calling to terminate
abnormally, e.g., by calling \fIdie\fR explicitly or by not actually
existing.  By default, when either of these events occurs, the
process will terminate immediately.  If you want to trap this
type of event, specify the G_EVAL flag.  It will put an \fIeval { }\fR
around the subroutine call.
.PP
Whenever control returns from the \fIcall_*\fR function you need to
check the \f(CW$@\fR variable as you would in a normal Perl script.
.PP
The value returned from the \fIcall_*\fR function is dependent on
what other flags have been specified and whether an error has
occurred.  Here are all the different cases that can occur:
.IP "\(bu" 5
If the \fIcall_*\fR function returns normally, then the value
returned is as specified in the previous sections.
.IP "\(bu" 5
If G_DISCARD is specified, the return value will always be 0.
.IP "\(bu" 5
If G_ARRAY is specified \fIand\fR an error has occurred, the return value
will always be 0.
.IP "\(bu" 5
If G_SCALAR is specified \fIand\fR an error has occurred, the return value
will be 1 and the value on the top of the stack will be \fIundef\fR. This
means that if you have already detected the error by checking \f(CW$@\fR and
you want the program to continue, you must remember to pop the \fIundef\fR