perlxs.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 "PERLXS 1"
.TH PERLXS 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"
perlxs \- XS language reference manual
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Sh "Introduction"
.IX Subsection "Introduction"
\&\s-1XS\s0 is an interface description file format used to create an extension
interface between Perl and C code (or a C library) which one wishes
to use with Perl.  The \s-1XS\s0 interface is combined with the library to
create a new library which can then be either dynamically loaded
or statically linked into perl.  The \s-1XS\s0 interface description is
written in the \s-1XS\s0 language and is the core component of the Perl
extension interface.
.PP
An \fB\s-1XSUB\s0\fR forms the basic unit of the \s-1XS\s0 interface.  After compilation
by the \fBxsubpp\fR compiler, each \s-1XSUB\s0 amounts to a C function definition
which will provide the glue between Perl calling conventions and C
calling conventions.
.PP
The glue code pulls the arguments from the Perl stack, converts these
Perl values to the formats expected by a C function, call this C function,
transfers the return values of the C function back to Perl.
Return values here may be a conventional C return value or any C
function arguments that may serve as output parameters.  These return
values may be passed back to Perl either by putting them on the
Perl stack, or by modifying the arguments supplied from the Perl side.
.PP
The above is a somewhat simplified view of what really happens.  Since
Perl allows more flexible calling conventions than C, XSUBs may do much
more in practice, such as checking input parameters for validity,
throwing exceptions (or returning undef/empty list) if the return value
from the C function indicates failure, calling different C functions
based on numbers and types of the arguments, providing an object-oriented
interface, etc.
.PP
Of course, one could write such glue code directly in C.  However, this
would be a tedious task, especially if one needs to write glue for
multiple C functions, and/or one is not familiar enough with the Perl
stack discipline and other such arcana.  \s-1XS\s0 comes to the rescue here:
instead of writing this glue C code in long-hand, one can write
a more concise short-hand \fIdescription\fR of what should be done by
the glue, and let the \s-1XS\s0 compiler \fBxsubpp\fR handle the rest.
.PP
The \s-1XS\s0 language allows one to describe the mapping between how the C
routine is used, and how the corresponding Perl routine is used.  It
also allows creation of Perl routines which are directly translated to
C code and which are not related to a pre-existing C function.  In cases
when the C interface coincides with the Perl interface, the \s-1XSUB\s0
declaration is almost identical to a declaration of a C function (in K&R
style).  In such circumstances, there is another tool called \f(CW\*(C`h2xs\*(C'\fR
that is able to translate an entire C header file into a corresponding
\&\s-1XS\s0 file that will provide glue to the functions/macros described in
the header file.
.PP
The \s-1XS\s0 compiler is called \fBxsubpp\fR.  This compiler creates
the constructs necessary to let an \s-1XSUB\s0 manipulate Perl values, and
creates the glue necessary to let Perl call the \s-1XSUB\s0.  The compiler
uses \fBtypemaps\fR to determine how to map C function parameters
and output values to Perl values and back.  The default typemap
(which comes with Perl) handles many common C types.  A supplementary
typemap may also be needed to handle any special structures and types
for the library being linked.
.PP
A file in \s-1XS\s0 format starts with a C language section which goes until the
first \f(CW\*(C`MODULE =\*(C'\fR directive.  Other \s-1XS\s0 directives and \s-1XSUB\s0 definitions
may follow this line.  The \*(L"language\*(R" used in this part of the file
is usually referred to as the \s-1XS\s0 language.  \fBxsubpp\fR recognizes and
skips \s-1POD\s0 (see perlpod) in both the C and \s-1XS\s0 language sections, which
allows the \s-1XS\s0 file to contain embedded documentation.
.PP
See perlxstut for a tutorial on the whole extension creation process.
.PP
Note: For some extensions, Dave Beazley's \s-1SWIG\s0 system may provide a
significantly more convenient mechanism for creating the extension
glue code.  See http://www.swig.org/ for more information.
.Sh "On The Road"
.IX Subsection "On The Road"
Many of the examples which follow will concentrate on creating an interface
between Perl and the \s-1ONC+\s0 \s-1RPC\s0 bind library functions.  The \fIrpcb_gettime()\fR
function is used to demonstrate many features of the \s-1XS\s0 language.  This
function has two parameters; the first is an input parameter and the second
is an output parameter.  The function also returns a status value.
.PP
.Vb 1
\&        bool_t rpcb_gettime(const char *host, time_t *timep);
.Ve
.PP
From C this function will be called with the following
statements.
.PP
.Vb 4
\&     #include <rpc/rpc.h>
\&     bool_t status;
\&     time_t timep;
\&     status = rpcb_gettime( "localhost", &timep );
.Ve
.PP
If an \s-1XSUB\s0 is created to offer a direct translation between this function
and Perl, then this \s-1XSUB\s0 will be used from Perl with the following code.
The \f(CW$status\fR and \f(CW$timep\fR variables will contain the output of the function.
.PP
.Vb 2
\&     use RPC;
\&     $status = rpcb_gettime( "localhost", $timep );
.Ve
.PP
The following \s-1XS\s0 file shows an \s-1XS\s0 subroutine, or \s-1XSUB\s0, which
demonstrates one possible interface to the \fIrpcb_gettime()\fR
function.  This \s-1XSUB\s0 represents a direct translation between
C and Perl and so preserves the interface even from Perl.
This \s-1XSUB\s0 will be invoked from Perl with the usage shown
above.  Note that the first three #include statements, for
\&\f(CW\*(C`EXTERN.h\*(C'\fR, \f(CW\*(C`perl.h\*(C'\fR, and \f(CW\*(C`XSUB.h\*(C'\fR, will always be present at the
beginning of an \s-1XS\s0 file.  This approach and others will be
expanded later in this document.
.PP
.Vb 4
\&     #include "EXTERN.h"
\&     #include "perl.h"
\&     #include "XSUB.h"
\&     #include <rpc/rpc.h>
\&
\&     MODULE = RPC  PACKAGE = RPC
\&
\&     bool_t
\&     rpcb_gettime(host,timep)
\&          char *host
\&          time_t &timep
\&        OUTPUT:
\&          timep
.Ve
.PP
Any extension to Perl, including those containing XSUBs,
should have a Perl module to serve as the bootstrap which
pulls the extension into Perl.  This module will export the
extension's functions and variables to the Perl program and
will cause the extension's XSUBs to be linked into Perl.
The following module will be used for most of the examples
in this document and should be used from Perl with the \f(CW\*(C`use\*(C'\fR
command as shown earlier.  Perl modules are explained in
more detail later in this document.
.PP
.Vb 1
\&     package RPC;
\&
\&     require Exporter;
\&     require DynaLoader;
\&     @ISA = qw(Exporter DynaLoader);
\&     @EXPORT = qw( rpcb_gettime );
\&
\&     bootstrap RPC;
\&     1;
.Ve
.PP
Throughout this document a variety of interfaces to the \fIrpcb_gettime()\fR
\&\s-1XSUB\s0 will be explored.  The XSUBs will take their parameters in different
orders or will take different numbers of parameters.  In each case the
\&\s-1XSUB\s0 is an abstraction between Perl and the real C \fIrpcb_gettime()\fR
function, and the \s-1XSUB\s0 must always ensure that the real \fIrpcb_gettime()\fR
function is called with the correct parameters.  This abstraction will
allow the programmer to create a more Perl-like interface to the C
function.
.Sh "The Anatomy of an \s-1XSUB\s0"
.IX Subsection "The Anatomy of an XSUB"
The simplest XSUBs consist of 3 parts: a description of the return
value, the name of the \s-1XSUB\s0 routine and the names of its arguments,
and a description of types or formats of the arguments.
.PP
The following \s-1XSUB\s0 allows a Perl program to access a C library function
called \fIsin()\fR.  The \s-1XSUB\s0 will imitate the C function which takes a single
argument and returns a single value.
.PP
.Vb 3
\&     double
\&     sin(x)
\&       double x
.Ve
.PP
Optionally, one can merge the description of types and the list of
argument names, rewriting this as
.PP
.Vb 2
\&     double
\&     sin(double x)
.Ve
.PP
This makes this \s-1XSUB\s0 look similar to an \s-1ANSI\s0 C declaration.  An optional
semicolon is allowed after the argument list, as in
.PP
.Vb 2
\&     double
\&     sin(double x);
.Ve
.PP
Parameters with C pointer types can have different semantic: C functions
with similar declarations
.PP
.Vb 2
\&     bool string_looks_as_a_number(char *s);
\&     bool make_char_uppercase(char *c);
.Ve
.PP
are used in absolutely incompatible manner.  Parameters to these functions
could be described \fBxsubpp\fR like this:
.PP
.Vb 2