perlcall.1

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

from the stack.
.PP
See \fIUsing G_EVAL\fR for details on using G_EVAL.
.Sh "G_KEEPERR"
.IX Subsection "G_KEEPERR"
You may have noticed that using the G_EVAL flag described above will
\&\fBalways\fR clear the \f(CW$@\fR variable and set it to a string describing
the error iff there was an error in the called code.  This unqualified
resetting of \f(CW$@\fR can be problematic in the reliable identification of
errors using the \f(CW\*(C`eval {}\*(C'\fR mechanism, because the possibility exists
that perl will call other code (end of block processing code, for
example) between the time the error causes \f(CW$@\fR to be set within
\&\f(CW\*(C`eval {}\*(C'\fR, and the subsequent statement which checks for the value of
\&\f(CW$@\fR gets executed in the user's script.
.PP
This scenario will mostly be applicable to code that is meant to be
called from within destructors, asynchronous callbacks, signal
handlers, \f(CW\*(C`_\|_DIE_\|_\*(C'\fR or \f(CW\*(C`_\|_WARN_\|_\*(C'\fR hooks, and \f(CW\*(C`tie\*(C'\fR functions.  In
such situations, you will not want to clear \f(CW$@\fR at all, but simply to
append any new errors to any existing value of \f(CW$@\fR.
.PP
The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
\&\fIcall_*\fR functions that are used to implement such code.  This flag
has no effect when G_EVAL is not used.
.PP
When G_KEEPERR is used, any errors in the called code will be prefixed
with the string \*(L"\et(in cleanup)\*(R", and appended to the current value
of \f(CW$@\fR.  an error will not be appended if that same error string is
already at the end of \f(CW$@\fR.
.PP
In addition, a warning is generated using the appended string. This can be
disabled using \f(CW\*(C`no warnings \*(Aqmisc\*(Aq\*(C'\fR.
.PP
The G_KEEPERR flag was introduced in Perl version 5.002.
.PP
See \fIUsing G_KEEPERR\fR for an example of a situation that warrants the
use of this flag.
.Sh "Determining the Context"
.IX Subsection "Determining the Context"
As mentioned above, you can determine the context of the currently
executing subroutine in Perl with \fIwantarray\fR.  The equivalent test
can be made in C by using the \f(CW\*(C`GIMME_V\*(C'\fR macro, which returns
\&\f(CW\*(C`G_ARRAY\*(C'\fR if you have been called in a list context, \f(CW\*(C`G_SCALAR\*(C'\fR if
in a scalar context, or \f(CW\*(C`G_VOID\*(C'\fR if in a void context (i.e. the
return value will not be used).  An older version of this macro is
called \f(CW\*(C`GIMME\*(C'\fR; in a void context it returns \f(CW\*(C`G_SCALAR\*(C'\fR instead of
\&\f(CW\*(C`G_VOID\*(C'\fR.  An example of using the \f(CW\*(C`GIMME_V\*(C'\fR macro is shown in
section \fIUsing \s-1GIMME_V\s0\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Enough of the definition talk, let's have a few examples.
.PP
Perl provides many macros to assist in accessing the Perl stack.
Wherever possible, these macros should always be used when interfacing
to Perl internals.  We hope this should make the code less vulnerable
to any changes made to Perl in the future.
.PP
Another point worth noting is that in the first series of examples I
have made use of only the \fIcall_pv\fR function.  This has been done
to keep the code simpler and ease you into the topic.  Wherever
possible, if the choice is between using \fIcall_pv\fR and
\&\fIcall_sv\fR, you should always try to use \fIcall_sv\fR.  See
\&\fIUsing call_sv\fR for details.
.Sh "No Parameters, Nothing returned"
.IX Subsection "No Parameters, Nothing returned"
This first trivial example will call a Perl subroutine, \fIPrintUID\fR, to
print out the \s-1UID\s0 of the process.
.PP
.Vb 4
\&    sub PrintUID
\&    {
\&        print "UID is $<\en";
\&    }
.Ve
.PP
and here is a C function to call it
.PP
.Vb 4
\&    static void
\&    call_PrintUID()
\&    {
\&        dSP;
\&
\&        PUSHMARK(SP);
\&        call_pv("PrintUID", G_DISCARD|G_NOARGS);
\&    }
.Ve
.PP
Simple, eh.
.PP
A few points to note about this example.
.IP "1." 5
Ignore \f(CW\*(C`dSP\*(C'\fR and \f(CW\*(C`PUSHMARK(SP)\*(C'\fR for now. They will be discussed in
the next example.
.IP "2." 5
We aren't passing any parameters to \fIPrintUID\fR so G_NOARGS can be
specified.
.IP "3." 5
We aren't interested in anything returned from \fIPrintUID\fR, so
G_DISCARD is specified. Even if \fIPrintUID\fR was changed to
return some value(s), having specified G_DISCARD will mean that they
will be wiped by the time control returns from \fIcall_pv\fR.
.IP "4." 5
As \fIcall_pv\fR is being used, the Perl subroutine is specified as a
C string. In this case the subroutine name has been 'hard\-wired' into the
code.
.IP "5." 5
Because we specified G_DISCARD, it is not necessary to check the value
returned from \fIcall_pv\fR. It will always be 0.
.Sh "Passing Parameters"
.IX Subsection "Passing Parameters"
Now let's make a slightly more complex example. This time we want to
call a Perl subroutine, \f(CW\*(C`LeftString\*(C'\fR, which will take 2 parameters\*(--a
string ($s) and an integer ($n).  The subroutine will simply
print the first \f(CW$n\fR characters of the string.
.PP
So the Perl subroutine would look like this
.PP
.Vb 5
\&    sub LeftString
\&    {
\&        my($s, $n) = @_;
\&        print substr($s, 0, $n), "\en";
\&    }
.Ve
.PP
The C function required to call \fILeftString\fR would look like this.
.PP
.Vb 6
\&    static void
\&    call_LeftString(a, b)
\&    char * a;
\&    int b;
\&    {
\&        dSP;
\&
\&        ENTER;
\&        SAVETMPS;
\&
\&        PUSHMARK(SP);
\&        XPUSHs(sv_2mortal(newSVpv(a, 0)));
\&        XPUSHs(sv_2mortal(newSViv(b)));
\&        PUTBACK;
\&
\&        call_pv("LeftString", G_DISCARD);
\&
\&        FREETMPS;
\&        LEAVE;
\&    }
.Ve
.PP
Here are a few notes on the C function \fIcall_LeftString\fR.
.IP "1." 5
Parameters are passed to the Perl subroutine using the Perl stack.
This is the purpose of the code beginning with the line \f(CW\*(C`dSP\*(C'\fR and
ending with the line \f(CW\*(C`PUTBACK\*(C'\fR.  The \f(CW\*(C`dSP\*(C'\fR declares a local copy
of the stack pointer.  This local copy should \fBalways\fR be accessed
as \f(CW\*(C`SP\*(C'\fR.
.IP "2." 5
If you are going to put something onto the Perl stack, you need to know
where to put it. This is the purpose of the macro \f(CW\*(C`dSP\*(C'\fR\-\-it declares
and initializes a \fIlocal\fR copy of the Perl stack pointer.
.Sp
All the other macros which will be used in this example require you to
have used this macro.
.Sp
The exception to this rule is if you are calling a Perl subroutine
directly from an \s-1XSUB\s0 function. In this case it is not necessary to
use the \f(CW\*(C`dSP\*(C'\fR macro explicitly\*(--it will be declared for you
automatically.
.IP "3." 5
Any parameters to be pushed onto the stack should be bracketed by the
\&\f(CW\*(C`PUSHMARK\*(C'\fR and \f(CW\*(C`PUTBACK\*(C'\fR macros.  The purpose of these two macros, in
this context, is to count the number of parameters you are
pushing automatically.  Then whenever Perl is creating the \f(CW@_\fR array for the
subroutine, it knows how big to make it.
.Sp
The \f(CW\*(C`PUSHMARK\*(C'\fR macro tells Perl to make a mental note of the current
stack pointer. Even if you aren't passing any parameters (like the
example shown in the section \fINo Parameters, Nothing returned\fR) you
must still call the \f(CW\*(C`PUSHMARK\*(C'\fR macro before you can call any of the
\&\fIcall_*\fR functions\*(--Perl still needs to know that there are no
parameters.
.Sp
The \f(CW\*(C`PUTBACK\*(C'\fR macro sets the global copy of the stack pointer to be
the same as our local copy. If we didn't do this \fIcall_pv\fR
wouldn't know where the two parameters we pushed were\*(--remember that
up to now all the stack pointer manipulation we have done is with our
local copy, \fInot\fR the global copy.
.IP "4." 5
Next, we come to XPUSHs. This is where the parameters actually get
pushed onto the stack. In this case we are pushing a string and an
integer.
.Sp
See \*(L"XSUBs and the Argument Stack\*(R" in perlguts for details
on how the \s-1XPUSH\s0 macros work.
.IP "5." 5
Because we created temporary values (by means of \fIsv_2mortal()\fR calls)
we will have to tidy up the Perl stack and dispose of mortal SVs.
.Sp
This is the purpose of
.Sp
.Vb 2
\&    ENTER;
\&    SAVETMPS;
.Ve
.Sp
at the start of the function, and
.Sp
.Vb 2
\&    FREETMPS;
\&    LEAVE;
.Ve
.Sp
at the end. The \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR pair creates a boundary for any
temporaries we create.  This means that the temporaries we get rid of
will be limited to those which were created after these calls.
.Sp
The \f(CW\*(C`FREETMPS\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair will get rid of any values returned by
the Perl subroutine (see next example), plus it will also dump the
mortal SVs we have created.  Having \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR at the
beginning of the code makes sure that no other mortals are destroyed.
.Sp
Think of these macros as working a bit like using \f(CW\*(C`{\*(C'\fR and \f(CW\*(C`}\*(C'\fR in Perl
to limit the scope of local variables.
.Sp
See the section \fIUsing Perl to dispose of temporaries\fR for details of
an alternative to using these macros.
.IP "6." 5
Finally, \fILeftString\fR can now be called via the \fIcall_pv\fR function.
The only flag specified this time is G_DISCARD. Because we are passing
2 parameters to the Perl subroutine this time, we have not specified
G_NOARGS.
.Sh "Returning a Scalar"
.IX Subsection "Returning a Scalar"
Now for an example of dealing with the items returned from a Perl
subroutine.
.PP
Here is a Perl subroutine, \fIAdder\fR, that takes 2 integer parameters
and simply returns their sum.
.PP
.Vb 5
\&    sub Adder
\&    {
\&        my($a, $b) = @_;
\&        $a + $b;
\&    }
.Ve
.PP
Because we are now concerned with the return value from \fIAdder\fR, the C
function required to call it is now a bit more complex.
.PP
.Vb 7
\&    static void
\&    call_Adder(a, b)
\&    int a;
\&    int b;
\&    {
\&        dSP;
\&        int count;
\&
\&        ENTER;
\&        SAVETMPS;
\&
\&        PUSHMARK(SP);
\&        XPUSHs(sv_2mortal(newSViv(a)));
\&        XPUSHs(sv_2mortal(newSViv(b)));
\&        PUTBACK;
\&
\&        count = call_pv("Adder", G_SCALAR);
\&
\&        SPAGAIN;
\&
\&        if (count != 1)
\&            croak("Big trouble\en");
\&
\&        printf ("The sum of %d and %d is %d\en", a, b, POPi);
\&
\&        PUTBACK;
\&        FREETMPS;
\&        LEAVE;
\&    }
.Ve
.PP
Points to note this time are
.IP "1." 5
The only flag specified this time was G_SCALAR. That means the \f(CW@_\fR
array will be created and that the value returned by \fIAdder\fR will
still exist after the call to \fIcall_pv\fR.
.IP "2." 5
The purpose of the macro \f(CW\*(C`SPAGAIN\*(C'\fR is to refresh the local copy of the
stack pointer. This is necessary because it is possible that the memory
allocated to the Perl stack has been reallocated whilst in the
\&\fIcall_pv\fR call.
.Sp
If you are making use of the Perl stack pointer in your code you must
always refresh the local copy using \s-1SPAGAIN\s0 whenever you make use
of the \fIcall_*\fR functions or any other Perl internal function.
.IP "3." 5
Although only a single value was expected to be returned from \fIAdder\fR,
it is still good practice to check the return code from \fIcall_pv\fR
anyway.
.Sp
Expecting a single value is not quite the same as knowing that there
will be one. If someone modified \fIAdder\fR to return a list and we
didn't check for that possibility and take appropriate action the Perl
stack would end up in an inconsistent state. That is something you
\&\fIreally\fR don't want to happen ever.
.IP "4." 5
The \f(CW\*(C`POPi\*(C'\fR macro is used here to pop the return value from the stack.
In this case we wanted an integer, so \f(CW\*(C`POPi\*(C'\fR was used.
.Sp
Here is the complete list of \s-1POP\s0 macros available, along with the types
they return.
.Sp
.Vb 5
\&    POPs        SV
\&    POPp        pointer
\&    POPn        double
\&    POPi        integer
\&    POPl        long
.Ve
.IP "5." 5
The final \f(CW\*(C`PUTBACK\*(C'\fR is used to leave the Perl stack in a consistent
state before exiting the function.  This is necessary because when we
popped the return value from the stack with \f(CW\*(C`POPi\*(C'\fR it updated only our
local copy of the stack pointer.  Remember, \f(CW\*(C`PUTBACK\*(C'\fR sets the global
stack pointer to be the same as our local copy.
.Sh "Returning a list of values"
.IX Subsection "Returning a list of values"
Now, let's extend the previous example to return both the sum of the
parameters and the difference.
.PP
Here is the Perl subroutine
.PP
.Vb 5
\&    sub AddSubtract
\&    {
\&       my($a, $b) = @_;
\&       ($a+$b, $a\-$b);
\&    }
.Ve
.PP
and this is the C function
.PP
.Vb 7
\&    static void
\&    call_AddSubtract(a, b)
\&    int a;
\&    int b;
\&    {
\&        dSP;
\&        int count;
\&
\&        ENTER;
\&        SAVETMPS;
\&
\&        PUSHMARK(SP);
\&        XPUSHs(sv_2mortal(newSViv(a)));
\&        XPUSHs(sv_2mortal(newSViv(b)));
\&        PUTBACK;
\&
\&        count = call_pv("AddSubtract", G_ARRAY);
\&
\&        SPAGAIN;
\&
\&        if (count != 2)
\&            croak("Big trouble\en");
\&
\&        printf ("%d \- %d = %d\en", a, b, POPi);
\&        printf ("%d + %d = %d\en", a, b, POPi);
\&
\&        PUTBACK;
\&        FREETMPS;
\&        LEAVE;
\&    }
.Ve
.PP
If \fIcall_AddSubtract\fR is called like this
.PP
.Vb 1
\&    call_AddSubtract(7, 4);
.Ve
.PP
then here is the output
.PP
.Vb 2
\&    7 \- 4 = 3
\&    7 + 4 = 11
.Ve
.PP
Notes
.IP "1." 5
We wanted list context, so G_ARRAY was used.
.IP "2." 5
Not surprisingly \f(CW\*(C`POPi\*(C'\fR is used twice this time because we were
retrieving 2 values from the stack. The important thing to note is that
when using the \f(CW\*(C`POP*\*(C'\fR macros they come off the stack in \fIreverse\fR
order.