Host not found: =head1 NAME
Host not found: PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
Host not found: =head1 SYNOPSIS
Host not found: open($fh,"<:crlf", "my.txt"); # support platform-native 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 or
Host not found: C layer specification then C code performs the equivalent of:
Host not found: use PerlIO 'foo';
Host not found: The perl code in PerlIO.pm then attempts to locate a layer by doing
Host not found: require PerlIO::foo;
Host not found: Otherwise the C package is a place holder for additional
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 operations 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 readline/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 to do low level IO.
Host not found: =item :crlf
Host not found: A layer that implements DOS/Windows like CRLF line endings.  On read
Host not found: converts pairs of CR,LF to a single "\n" newline character.  On write
Host not found: converts each "\n" to a CR,LF pair.  Note that this layer likes to be
Host not found: one of its kind: it silently ignores attempts to be pushed 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 of being a CRLF
Host not found: layer but is not yet enabled to be a CRLF layer.  If it finds such a
Host not found: layer, it enables the CRLFness of that other deeper layer, 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 would 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 space, and then
Host not found: using that as PerlIO's "buffer". This I be faster in certain
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 for write
Host not found: needs extra house-keeping (to extend the file) which negates 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 character perl can
Host not found: represent to be read from or written to the stream. The UTF-X encoding
Host not found: is chosen to render simple text parts (i.e.  non-accented letters,
Host not found: digits and common punctuation) human readable in the encoded 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<:utf8>, 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 the flag
Host not found: on the layer below so that data read from it is considered to
Host not found: be "octets" i.e. characters in range 0..255 only. Likewise
Host not found: on output perl will warn if a "wide" character is written
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 data
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 (previously sometimes also
Host not found: referred to as a "discipline") is documented as the inverse of the
Host not found: C<:crlf> layer. That is no longer the case - other layers 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 translation, 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 which when "pushed"
Host not found: pops itself and then any layers which do not declare themselves as suitable
Host not found: for binary data. (Undoing :utf8 and :crlf are implemented by clearing
Host not found: flags rather than popping layers but that is an implementation detail.)
Host not found: As a consequence of the fact that C<:raw> normally pops 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 considered
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 encoded
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" IO
Host not found: rather than unix-like numeric file descriptor layer. Known 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 the 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 distribution.
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 encoding transformations,
Host not found: for example from Shift-JIS to Unicode.  Note that under 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 install a layer
Host not found: that does whatever transformation (for example compression /
Host not found: decompression, encryption / decryption) to the filehandle.
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 how 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 layer (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 platform specific low
Host not found: level layer.)
Host not found: Otherwise if C found out how to do "fast" IO using system'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 environment variable
Host not found: PERLIO to a space separated list of layers (C or platform 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 various 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, "FH".
Host not found: The layers are returned in the order an open() or binmode() call would
Host not found: use them.  Note that the "default stack" depends on the operating
Host not found: system and on the Perl version, and both the compile-time and
Host not found: runtime configurations of Perl.
Host not found: The following table summarizes the default layers on UNIX-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 stdio" (depends
Host not found: # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
Host not found: By default the layers from the input side of the filehandle is
Host not found: returned, to get the output side use the optional C argument:
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.  This is not
Host not found: accidental or unintentional.  The PerlIO layer stack is a bit more
Host not found: complicated than just a stack (see for example the behaviour of C<:raw>).
Host not found: You are supposed to use open() and binmode() to manipulate the stack.
Host not found: B
Host not found: The arguments to layers are by default returned in parenthesis 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 the arguments
Host not found: (unspecified arguments will be C), the third element the 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