Host not found: =head1 NAME
Host not found: PerlIO - On demand loader for PerlIO layers and root o
+f PerlIO::* name space
Host not found: =head1 SYNOPSIS
Host not found: open($fh,"<:crlf", "my.txt"); # support platform-nativ
+e and CRLF text files
Host not found: open($fh,"<","his.jpg");      # portably open a binary
+ file for reading
Host not found: binmode($fh);
Host not found: Shell:
Host not found: PERLIO=perlio perl ....
Host not found: =head1 DESCRIPTION
Host not found: When an undefined layer 'foo' is encountered in an C o
+r
Host not found: C layer specification then C code performs the equival
+ent of:
Host not found: use PerlIO 'foo';
Host not found: The perl code in PerlIO.pm then attempts to locate a l
+ayer by doing
Host not found: require PerlIO::foo;
Host not found: Otherwise the C package is a place holder for addition
+al
Host not found: PerlIO related functions.
Host not found: The following layers are currently defined:
Host not found: =over 4
Host not found: =item :unix
Host not found: Lowest level layer which provides basic PerlIO operati
+ons in terms of
Host not found: UNIX/POSIX numeric file descriptor calls
Host not found: (open(), read(), write(), lseek(), close()).
Host not found: =item :stdio
Host not found: Layer which calls C, C and C/C etc.  Note
Host not found: that as this is "real" stdio it will ignore any layers
+ beneath it and
Host not found: got straight to the operating system via the C library
+ as usual.
Host not found: =item :perlio
Host not found: A from scratch implementation of buffering for PerlIO.
+ Provides fast
Host not found: access to the buffer for C which implements perl's rea
+dline/EE
Host not found: and in general attempts to minimize data copying.
Host not found: C<:perlio> will insert a C<:unix> layer below itself t
+o do low level IO.
Host not found: =item :crlf
Host not found: A layer that implements DOS/Windows like CRLF line end
+ings.  On read
Host not found: converts pairs of CR,LF to a single "\n" newline chara
+cter.  On write
Host not found: converts each "\n" to a CR,LF pair.  Note that this la
+yer likes to be
Host not found: one of its kind: it silently ignores attempts to be pu
+shed into the
Host not found: layer stack more than once.
Host not found: It currently does I mimic MS-DOS as far as treating of
+ Control-Z
Host not found: as being an end-of-file marker.
Host not found: (Gory details follow) To be more exact what happens is
+ this: after
Host not found: pushing itself to the stack, the C<:crlf> layer checks
+ all the layers
Host not found: below itself to find the first layer that is capable o
+f being a CRLF
Host not found: layer but is not yet enabled to be a CRLF layer.  If i
+t finds such a
Host not found: layer, it enables the CRLFness of that other deeper la
+yer, and then
Host not found: pops itself off the stack.  If not, fine, use the one 
+we just pushed.
Host not found: The end result is that a C<:crlf> means "please enable
+ the first CRLF
Host not found: layer you can find, and if you can't find one, here wo
+uld be a good
Host not found: spot to place a new one."
Host not found: Based on the C<:perlio> layer.
Host not found: =item :mmap
Host not found: A layer which implements "reading" of files by using C
+ to
Host not found: make (whole) file appear in the process's address spac
+e, and then
Host not found: using that as PerlIO's "buffer". This I be faster in c
+ertain
Host not found: circumstances for large files, and may result in less 
+physical memory
Host not found: use when multiple processes are reading the same file.
Host not found: Files which are not C-able revert to behaving like the
+ C<:perlio>
Host not found: layer. Writes also behave like C<:perlio> layer as C f
+or write
Host not found: needs extra house-keeping (to extend the file) which n
+egates any advantage.
Host not found: The C<:mmap> layer will not exist if platform does not
+ support C.
Host not found: =item :utf8
Host not found: Declares that the stream accepts perl's I encoding of
Host not found: characters.  (Which really is UTF-8 on ASCII machines,
+ but is
Host not found: UTF-EBCDIC on EBCDIC machines.)  This allows any chara
+cter perl can
Host not found: represent to be read from or written to the stream. Th
+e UTF-X encoding
Host not found: is chosen to render simple text parts (i.e.  non-accen
+ted letters,
Host not found: digits and common punctuation) human readable in the e
+ncoded file.
Host not found: Here is how to write your native data out using UTF-8 
+(or UTF-EBCDIC)
Host not found: and then read it back in.
Host not found: open(F, ">:utf8", "data.utf");
Host not found: print F $out;
Host not found: close(F);
Host not found: open(F, "<:utf8", "data.utf");
Host not found: $in = ;
Host not found: close(F);
Host not found: Note that this layer does not validate byte sequences.
+ For reading
Host not found: input, using C<:encoding(utf8)> instead of bare C<:utf
+8>, is strongly
Host not found: recommended.
Host not found: =item :bytes
Host not found: This is the inverse of C<:utf8> layer. It turns off th
+e flag
Host not found: on the layer below so that data read from it is consid
+ered to
Host not found: be "octets" i.e. characters in range 0..255 only. Like
+wise
Host not found: on output perl will warn if a "wide" character is writ
+ten
Host not found: to a such a stream.
Host not found: =item :raw
Host not found: The C<:raw> layer is I as being identical to calling
Host not found: C - the stream is made suitable for passing binary dat
+a
Host not found: i.e. each byte is passed as-is. The stream will still 
+be
Host not found: buffered.
Host not found: In Perl 5.6 and some books the C<:raw> layer (previous
+ly sometimes also
Host not found: referred to as a "discipline") is documented as the in
+verse of the
Host not found: C<:crlf> layer. That is no longer the case - other lay
+ers which would
Host not found: alter binary nature of the stream are also disabled.  
+If you want UNIX
Host not found: line endings on a platform that normally does CRLF tra
+nslation, but still
Host not found: want UTF-8 or encoding defaults the appropriate thing 
+to do is to add
Host not found: C<:perlio> to PERLIO environment variable.
Host not found: The implementation of C<:raw> is as a pseudo-layer whi
+ch when "pushed"
Host not found: pops itself and then any layers which do not declare t
+hemselves as suitable
Host not found: for binary data. (Undoing :utf8 and :crlf are implemen
+ted by clearing
Host not found: flags rather than popping layers but that is an implem
+entation detail.)
Host not found: As a consequence of the fact that C<:raw> normally pop
+s layers
Host not found: it usually only makes sense to have it as the only or 
+first element in
Host not found: a layer specification.  When used as the first element
+ it provides
Host not found: a known base on which to build e.g.
Host not found: open($fh,":raw:utf8",...)
Host not found: will construct a "binary" stream, but then enable UTF-
+8 translation.
Host not found: =item :pop
Host not found: A pseudo layer that removes the top-most layer. Gives 
+perl code
Host not found: a way to manipulate the layer stack. Should be conside
+red
Host not found: as experimental. Note that C<:pop> only works on real 
+layers
Host not found: and will not undo the effects of pseudo layers like C<
+:utf8>.
Host not found: An example of a possible use might be:
Host not found: open($fh,...)
Host not found: ...
Host not found: binmode($fh,":encoding(...)");  # next chunk is encode
+d
Host not found: ...
Host not found: binmode($fh,":pop");            # back to un-encoded
Host not found: A more elegant (and safer) interface is needed.
Host not found: =item :win32
Host not found: On Win32 platforms this I layer uses native "handle" I
+O
Host not found: rather than unix-like numeric file descriptor layer. K
+nown to be
Host not found: buggy as of perl 5.8.2.
Host not found: =back
Host not found: =head2 Custom Layers
Host not found: It is possible to write custom layers in addition to t
+he above builtin
Host not found: ones, both in C/XS and Perl.  Two such layers (and one
+ example written
Host not found: in Perl using the latter) come with the Perl distribut
+ion.
Host not found: =over 4
Host not found: =item :encoding
Host not found: Use C<:encoding(ENCODING)> either in open() or binmode
+() to install
Host not found: a layer that does transparently character set and enco
+ding transformations,
Host not found: for example from Shift-JIS to Unicode.  Note that unde
+r C
Host not found: an C<:encoding> also enables C<:utf8>.  See L
Host not found: for more information.
Host not found: =item :via
Host not found: Use C<:via(MODULE)> either in open() or binmode() to i
+nstall a layer
Host not found: that does whatever transformation (for example compres
+sion /
Host not found: decompression, encryption / decryption) to the filehan
+dle.
Host not found: See L for more information.
Host not found: =back
Host not found: =head2 Alternatives to raw
Host not found: To get a binary stream an alternate method is to use:
Host not found: open($fh,"whatever")
Host not found: binmode($fh);
Host not found: this has advantage of being backward compatible with h
+ow such things have
Host not found: had to be coded on some platforms for years.
Host not found: To get an un-buffered stream specify an unbuffered lay
+er (e.g. C<:unix>)
Host not found: in the open call:
Host not found: open($fh,"<:unix",$path)
Host not found: =head2 Defaults and how to override them
Host not found: If the platform is MS-DOS like and normally does CRLF 
+to "\n"
Host not found: translation for text files then the default layers are
+ :
Host not found: unix crlf
Host not found: (The low level "unix" layer may be replaced by a platf
+orm specific low
Host not found: level layer.)
Host not found: Otherwise if C found out how to do "fast" IO using sys
+tem's
Host not found: stdio, then the default layers are:
Host not found: unix stdio
Host not found: Otherwise the default layers are
Host not found: unix perlio
Host not found: These defaults may change once perlio has been better 
+tested and tuned.
Host not found: The default can be overridden by setting the environme
+nt variable
Host not found: PERLIO to a space separated list of layers (C or platf
+orm low
Host not found: level layer is always pushed first).
Host not found: This can be used to see the effect of/bugs in the vari
+ous layers e.g.
Host not found: cd .../perl/t
Host not found: PERLIO=stdio  ./perl harness
Host not found: PERLIO=perlio ./perl harness
Host not found: For the various value of PERLIO see L.
Host not found: =head2 Querying the layers of filehandles
Host not found: The following returns the B of the PerlIO layers on a 
+filehandle.
Host not found: my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "F
+H".
Host not found: The layers are returned in the order an open() or binm
+ode() call would
Host not found: use them.  Note that the "default stack" depends on th
+e operating
Host not found: system and on the Perl version, and both the compile-t
+ime and
Host not found: runtime configurations of Perl.
Host not found: The following table summarizes the default layers on U
+NIX-like and
Host not found: DOS-like platforms and depending on the setting of the
+ C<$ENV{PERLIO}>:
Host not found: PERLIO     UNIX-like                   DOS-like
Host not found: ------     ---------                   --------
Host not found: unset / "" unix perlio / stdio [1]     unix crlf
Host not found: stdio      unix perlio / stdio [1]     stdio
Host not found: perlio     unix perlio                 unix perlio
Host not found: mmap       unix mmap                   unix mmap
Host not found: # [1] "stdio" if Configure found out how to do "fast s
+tdio" (depends
Host not found: # on the stdio implementation) and in Perl 5.8, otherw
+ise "unix perlio"
Host not found: By default the layers from the input side of the fileh
+andle is
Host not found: returned, to get the output side use the optional C ar
+gument:
Host not found: my @layers = PerlIO::get_layers($fh, output => 1);
Host not found: (Usually the layers are identical on either side of a 
+filehandle but
Host not found: for example with sockets there may be differences, or 
+if you have
Host not found: been using the C pragma.)
Host not found: There is no set_layers(), nor does get_layers() return
+ a tied array
Host not found: mirroring the stack, or anything fancy like that.  Thi
+s is not
Host not found: accidental or unintentional.  The PerlIO layer stack i
+s a bit more
Host not found: complicated than just a stack (see for example the beh
+aviour of C<:raw>).
Host not found: You are supposed to use open() and binmode() to manipu
+late the stack.
Host not found: B
Host not found: The arguments to layers are by default returned in par
+enthesis after
Host not found: the name of the layer, and certain layers (like C) are
+ not real
Host not found: layers but instead flags on real layers: to get all of
+ these returned
Host not found: separately use the optional C argument:
Host not found: my @layer_and_args_and_flags = PerlIO::get_layers($fh,
+ details => 1);
Host not found: The result will be up to be three times the number of 
+layers:
Host not found: the first element will be a name, the second element t
+he arguments
Host not found: (unspecified arguments will be C), the third element t
+he flags,
Host not found: the fourth element a name again, and so forth.
Host not found: B
Host not found: =head1 AUTHOR
Host not found: Nick Ing-Simmons Enick@ing-simmons.netE
Host not found: =head1 SEE ALSO
Host not found: L, L, L, L,
Host not found: L
Host not found: =cut
[download]