perliol.1

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

adjusted for data read from below but not actually consumed.
(Should perhaps \f(CW\*(C`Unread()\*(C'\fR such data to the lower layer.)
.Sp
Returns 0 on success, \-1 on failure.
.IP "Fill" 4
.IX Item "Fill"
.Vb 1
\&        IV      (*Fill)(pTHX_ PerlIO *f);
.Ve
.Sp
The buffer for this layer should be filled (for read) from layer
below.  When you \*(L"subclass\*(R" PerlIOBuf layer, you want to use its
\&\fI_read\fR method and to supply your own fill method, which fills the
PerlIOBuf's buffer.
.Sp
Returns 0 on success, \-1 on failure.
.IP "Eof" 4
.IX Item "Eof"
.Vb 1
\&        IV      (*Eof)(pTHX_ PerlIO *f);
.Ve
.Sp
Return end-of-file indicator. \f(CW\*(C`PerlIOBase_eof()\*(C'\fR is normally sufficient.
.Sp
Returns 0 on end-of-file, 1 if not end-of-file, \-1 on error.
.IP "Error" 4
.IX Item "Error"
.Vb 1
\&        IV      (*Error)(pTHX_ PerlIO *f);
.Ve
.Sp
Return error indicator. \f(CW\*(C`PerlIOBase_error()\*(C'\fR is normally sufficient.
.Sp
Returns 1 if there is an error (usually when \f(CW\*(C`PERLIO_F_ERROR\*(C'\fR is set,
0 otherwise.
.IP "Clearerr" 4
.IX Item "Clearerr"
.Vb 1
\&        void    (*Clearerr)(pTHX_ PerlIO *f);
.Ve
.Sp
Clear end-of-file and error indicators. Should call \f(CW\*(C`PerlIOBase_clearerr()\*(C'\fR
to set the \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags, which may suffice.
.IP "Setlinebuf" 4
.IX Item "Setlinebuf"
.Vb 1
\&        void    (*Setlinebuf)(pTHX_ PerlIO *f);
.Ve
.Sp
Mark the stream as line buffered. \f(CW\*(C`PerlIOBase_setlinebuf()\*(C'\fR sets the
\&\s-1PERLIO_F_LINEBUF\s0 flag and is normally sufficient.
.IP "Get_base" 4
.IX Item "Get_base"
.Vb 1
\&        STDCHAR *       (*Get_base)(pTHX_ PerlIO *f);
.Ve
.Sp
Allocate (if not already done so) the read buffer for this layer and
return pointer to it. Return \s-1NULL\s0 on failure.
.IP "Get_bufsiz" 4
.IX Item "Get_bufsiz"
.Vb 1
\&        Size_t  (*Get_bufsiz)(pTHX_ PerlIO *f);
.Ve
.Sp
Return the number of bytes that last \f(CW\*(C`Fill()\*(C'\fR put in the buffer.
.IP "Get_ptr" 4
.IX Item "Get_ptr"
.Vb 1
\&        STDCHAR *       (*Get_ptr)(pTHX_ PerlIO *f);
.Ve
.Sp
Return the current read pointer relative to this layer's buffer.
.IP "Get_cnt" 4
.IX Item "Get_cnt"
.Vb 1
\&        SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
.Ve
.Sp
Return the number of bytes left to be read in the current buffer.
.IP "Set_ptrcnt" 4
.IX Item "Set_ptrcnt"
.Vb 2
\&        void    (*Set_ptrcnt)(pTHX_ PerlIO *f,
\&                              STDCHAR *ptr, SSize_t cnt);
.Ve
.Sp
Adjust the read pointer and count of bytes to match \f(CW\*(C`ptr\*(C'\fR and/or \f(CW\*(C`cnt\*(C'\fR.
The application (or layer above) must ensure they are consistent.
(Checking is allowed by the paranoid.)
.Sh "Utilities"
.IX Subsection "Utilities"
To ask for the next layer down use PerlIONext(PerlIO *f).
.PP
To check that a PerlIO* is valid use PerlIOValid(PerlIO *f).  (All
this does is really just to check that the pointer is non-NULL and
that the pointer behind that is non-NULL.)
.PP
PerlIOBase(PerlIO *f) returns the \*(L"Base\*(R" pointer, or in other words,
the \f(CW\*(C`PerlIOl*\*(C'\fR pointer.
.PP
PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
.PP
Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
calls the \fIcallback\fR from the functions of the layer \fIf\fR (just by
the name of the \s-1IO\s0 function, like \*(L"Read\*(R") with the \fIargs\fR, or if
there is no such callback, calls the \fIbase\fR version of the callback
with the same args, or if the f is invalid, set errno to \s-1EBADF\s0 and
return \fIfailure\fR.
.PP
Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR,
or if there is no such callback, set errno to \s-1EINVAL\s0.  Or if the f is
invalid, set errno to \s-1EBADF\s0 and return \fIfailure\fR.
.PP
Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR,
or if there is no such callback, calls the \fIbase\fR version of the
callback with the same args, or if the f is invalid, set errno to
\&\s-1EBADF\s0.
.PP
Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
\&\fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, or if
there is no such callback, set errno to \s-1EINVAL\s0.  Or if the f is
invalid, set errno to \s-1EBADF\s0.
.Sh "Implementing PerlIO Layers"
.IX Subsection "Implementing PerlIO Layers"
If you find the implementation document unclear or not sufficient,
look at the existing PerlIO layer implementations, which include:
.IP "\(bu" 4
C implementations
.Sp
The \fIperlio.c\fR and \fIperliol.h\fR in the Perl core implement the
\&\*(L"unix\*(R", \*(L"perlio\*(R", \*(L"stdio\*(R", \*(L"crlf\*(R", \*(L"utf8\*(R", \*(L"byte\*(R", \*(L"raw\*(R", \*(L"pending\*(R"
layers, and also the \*(L"mmap\*(R" and \*(L"win32\*(R" layers if applicable.
(The \*(L"win32\*(R" is currently unfinished and unused, to see what is used
instead in Win32, see \*(L"Querying the layers of filehandles\*(R" in PerlIO .)
.Sp
PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
.Sp
PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on \s-1CPAN\s0.
.IP "\(bu" 4
Perl implementations
.Sp
PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on \s-1CPAN\s0.
.PP
If you are creating a PerlIO layer, you may want to be lazy, in other
words, implement only the methods that interest you.  The other methods
you can either replace with the \*(L"blank\*(R" methods
.PP
.Vb 2
\&    PerlIOBase_noop_ok
\&    PerlIOBase_noop_fail
.Ve
.PP
(which do nothing, and return zero and \-1, respectively) or for
certain methods you may assume a default behaviour by using a \s-1NULL\s0
method.  The Open method looks for help in the 'parent' layer.
The following table summarizes the behaviour:
.PP
.Vb 1
\&    method      behaviour with NULL
\&
\&    Clearerr    PerlIOBase_clearerr
\&    Close       PerlIOBase_close
\&    Dup         PerlIOBase_dup
\&    Eof         PerlIOBase_eof
\&    Error       PerlIOBase_error
\&    Fileno      PerlIOBase_fileno
\&    Fill        FAILURE
\&    Flush       SUCCESS
\&    Getarg      SUCCESS
\&    Get_base    FAILURE
\&    Get_bufsiz  FAILURE
\&    Get_cnt     FAILURE
\&    Get_ptr     FAILURE
\&    Open        INHERITED
\&    Popped      SUCCESS
\&    Pushed      SUCCESS
\&    Read        PerlIOBase_read
\&    Seek        FAILURE
\&    Set_cnt     FAILURE
\&    Set_ptrcnt  FAILURE
\&    Setlinebuf  PerlIOBase_setlinebuf
\&    Tell        FAILURE
\&    Unread      PerlIOBase_unread
\&    Write       FAILURE
\&
\& FAILURE        Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and
\&                return \-1 (for numeric return values) or NULL (for pointers)
\& INHERITED      Inherited from the layer below
\& SUCCESS        Return 0 (for numeric return values) or a pointer
.Ve
.Sh "Core Layers"
.IX Subsection "Core Layers"
The file \f(CW\*(C`perlio.c\*(C'\fR provides the following layers:
.ie n .IP """unix""" 4
.el .IP "``unix''" 4
.IX Item "unix"
A basic non-buffered layer which calls Unix/POSIX \f(CW\*(C`read()\*(C'\fR, \f(CW\*(C`write()\*(C'\fR,
\&\f(CW\*(C`lseek()\*(C'\fR, \f(CW\*(C`close()\*(C'\fR. No buffering. Even on platforms that distinguish
between O_TEXT and O_BINARY this layer is always O_BINARY.
.ie n .IP """perlio""" 4
.el .IP "``perlio''" 4
.IX Item "perlio"
A very complete generic buffering layer which provides the whole of
PerlIO \s-1API\s0. It is also intended to be used as a \*(L"base class\*(R" for other
layers. (For example its \f(CW\*(C`Read()\*(C'\fR method is implemented in terms of
the \f(CW\*(C`Get_cnt()\*(C'\fR/\f(CW\*(C`Get_ptr()\*(C'\fR/\f(CW\*(C`Set_ptrcnt()\*(C'\fR methods).
.Sp
\&\*(L"perlio\*(R" over \*(L"unix\*(R" provides a complete replacement for stdio as seen
via PerlIO \s-1API\s0. This is the default for \s-1USE_PERLIO\s0 when system's stdio
does not permit perl's \*(L"fast gets\*(R" access, and which do not
distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR.
.ie n .IP """stdio""" 4
.el .IP "``stdio''" 4
.IX Item "stdio"
A layer which provides the PerlIO \s-1API\s0 via the layer scheme, but
implements it by calling system's stdio. This is (currently) the default
if system's stdio provides sufficient access to allow perl's \*(L"fast gets\*(R"
access and which do not distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR.
.ie n .IP """crlf""" 4
.el .IP "``crlf''" 4
.IX Item "crlf"
A layer derived using \*(L"perlio\*(R" as a base class. It provides Win32\-like
\&\*(L"\en\*(R" to \s-1CR\s0,LF translation. Can either be applied above \*(L"perlio\*(R" or serve
as the buffer layer itself. \*(L"crlf\*(R" over \*(L"unix\*(R" is the default if system
distinguishes between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR opens. (At some point
\&\*(L"unix\*(R" will be replaced by a \*(L"native\*(R" Win32 \s-1IO\s0 layer on that platform,
as Win32's read/write layer has various drawbacks.) The \*(L"crlf\*(R" layer is
a reasonable model for a layer which transforms data in some way.
.ie n .IP """mmap""" 4
.el .IP "``mmap''" 4
.IX Item "mmap"
If Configure detects \f(CW\*(C`mmap()\*(C'\fR functions this layer is provided (with
\&\*(L"perlio\*(R" as a \*(L"base\*(R") which does \*(L"read\*(R" operations by \fImmap()\fRing the
file. Performance improvement is marginal on modern systems, so it is
mainly there as a proof of concept. It is likely to be unbundled from
the core at some point. The \*(L"mmap\*(R" layer is a reasonable model for a
minimalist \*(L"derived\*(R" layer.
.ie n .IP """pending""" 4
.el .IP "``pending''" 4
.IX Item "pending"
An \*(L"internal\*(R" derivative of \*(L"perlio\*(R" which can be used to provide
\&\fIUnread()\fR function for layers which have no buffer or cannot be
bothered.  (Basically this layer's \f(CW\*(C`Fill()\*(C'\fR pops itself off the stack
and so resumes reading from layer below.)
.ie n .IP """raw""" 4
.el .IP "``raw''" 4
.IX Item "raw"
A dummy layer which never exists on the layer stack. Instead when
\&\*(L"pushed\*(R" it actually pops the stack removing itself, it then calls
Binmode function table entry on all the layers in the stack \- normally
this (via PerlIOBase_binmode) removes any layers which do not have
\&\f(CW\*(C`PERLIO_K_RAW\*(C'\fR bit set. Layers can modify that behaviour by defining
their own Binmode entry.
.ie n .IP """utf8""" 4
.el .IP "``utf8''" 4
.IX Item "utf8"
Another dummy layer. When pushed it pops itself and sets the
\&\f(CW\*(C`PERLIO_F_UTF8\*(C'\fR flag on the layer which was (and now is once more)
the top of the stack.
.PP
In addition \fIperlio.c\fR also provides a number of \f(CW\*(C`PerlIOBase_xxxx()\*(C'\fR
functions which are intended to be used in the table slots of classes
which do not need to do anything special for a particular method.
.Sh "Extension Layers"
.IX Subsection "Extension Layers"
Layers can made available by extension modules. When an unknown layer
is encountered the PerlIO code will perform the equivalent of :
.PP
.Vb 1
\&   use PerlIO \*(Aqlayer\*(Aq;
.Ve
.PP
Where \fIlayer\fR is the unknown layer. \fIPerlIO.pm\fR will then attempt to:
.PP
.Vb 1
\&   require PerlIO::layer;
.Ve
.PP
If after that process the layer is still not defined then the \f(CW\*(C`open\*(C'\fR
will fail.
.PP
The following extension layers are bundled with perl:
.ie n .IP """:encoding""" 4
.el .IP "``:encoding''" 4
.IX Item ":encoding"
.Vb 1
\&   use Encoding;
.Ve
.Sp
makes this layer available, although \fIPerlIO.pm\fR \*(L"knows\*(R" where to
find it.  It is an example of a layer which takes an argument as it is
called thus:
.Sp
.Vb 1
\&   open( $fh, "<:encoding(iso\-8859\-7)", $pathname );
.Ve
.ie n .IP """:scalar""" 4
.el .IP "``:scalar''" 4
.IX Item ":scalar"
Provides support for reading data from and writing data to a scalar.
.Sp
.Vb 1
\&   open( $fh, "+<:scalar", \e$scalar );
.Ve
.Sp
When a handle is so opened, then reads get bytes from the string value
of \fI\f(CI$scalar\fI\fR, and writes change the value. In both cases the position
in \fI\f(CI$scalar\fI\fR starts as zero but can be altered via \f(CW\*(C`seek\*(C'\fR, and
determined via \f(CW\*(C`tell\*(C'\fR.
.Sp
Please note that this layer is implied when calling \fIopen()\fR thus:
.Sp
.Vb 1
\&   open( $fh, "+<", \e$scalar );
.Ve
.ie n .IP """:via""" 4
.el .IP "``:via''" 4
.IX Item ":via"
Provided to allow layers to be implemented as Perl code.  For instance:
.Sp
.Vb 2
\&   use PerlIO::via::StripHTML;
\&   open( my $fh, "<:via(StripHTML)", "index.html" );
.Ve
.Sp
See PerlIO::via for details.
.SH "TODO"
.IX Header "TODO"
Things that need to be done to improve this document.
.IP "\(bu" 4
Explain how to make a valid fh without going through \fIopen()\fR(i.e. apply
a layer). For example if the file is not opened through perl, but we
want to get back a fh, like it was opened by Perl.
.Sp
How PerlIO_apply_layera fits in, where its docs, was it made public?
.Sp
Currently the example could be something like this:
.Sp
.Vb 8
\&  PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
\&  {
\&      char *mode; /* "w", "r", etc */
\&      const char *layers = ":APR"; /* the layer name */
\&      PerlIO *f = PerlIO_allocate(aTHX);
\&      if (!f) {
\&          return NULL;
\&      }
\&
\&      PerlIO_apply_layers(aTHX_ f, mode, layers);
\&
\&      if (f) {
\&          PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
\&          /* fill in the st struct, as in _open() */
\&          st\->file = file;
\&          PerlIOBase(f)\->flags |= PERLIO_F_OPEN;
\&
\&          return f;
\&      }
\&      return NULL;
\&  }
.Ve
.IP "\(bu" 4
fix/add the documentation in places marked as \s-1XXX\s0.
.IP "\(bu" 4
The handling of errors by the layer is not specified. e.g. when $!
should be set explicitly, when the error handling should be just
delegated to the top layer.
.Sp
Probably give some hints on using \s-1\fISETERRNO\s0()\fR or pointers to where they
can be found.
.IP "\(bu" 4
I think it would help to give some concrete examples to make it easier
to understand the \s-1API\s0. Of course I agree that the \s-1API\s0 has to be
concise, but since there is no second document that is more of a
guide, I think that it'd make it easier to start with the doc which is
an \s-1API\s0, but has examples in it in places where things are unclear, to
a person who is not a PerlIO guru (yet).