5 # Map layer name to package that defines it
14 if (exists $alias{$layer})
16 $layer = $alias{$layer}
20 $layer = "${class}::$layer";
22 eval "require $layer";
32 PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
36 open($fh,"<:crlf", "my.txt"); # portably open a text file for reading
38 open($fh,"<","his.jpg"); # portably open a binary file for reading
42 PERLIO=perlio perl ....
46 When an undefined layer 'foo' is encountered in an C<open> or
47 C<binmode> layer specification then C code performs the equivalent of:
51 The perl code in PerlIO.pm then attempts to locate a layer by doing
55 Otherwise the C<PerlIO> package is a place holder for additional
56 PerlIO related functions.
58 The following layers are currently defined:
64 Low level layer which calls C<read>, C<write> and C<lseek> etc.
68 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc. Note
69 that as this is "real" stdio it will ignore any layers beneath it and
70 got straight to the operating system via the C library as usual.
74 This is a re-implementation of "stdio-like" buffering written as a
75 PerlIO "layer". As such it will call whatever layer is below it for
80 A layer which does CRLF to "\n" translation distinguishing "text" and
81 "binary" files in the manner of MS-DOS and similar operating systems.
82 (It currently does I<not> mimic MS-DOS as far as treating of Control-Z
83 as being an end-of-file marker.)
87 Declares that the stream accepts perl's internal encoding of
88 characters. (Which really is UTF-8 on ASCII machines, but is
89 UTF-EBCDIC on EBCDIC machines.) This allows any character perl can
90 represent to be read from or written to the stream. The UTF-X encoding
91 is chosen to render simple text parts (i.e. non-accented letters,
92 digits and common punctuation) human readable in the encoded file.
94 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
95 and then read it back in.
97 open(F, ">:utf8", "data.utf");
101 open(F, "<:utf8", "data.utf");
107 This is the inverse of C<:utf8> layer. It turns off the flag
108 on the layer below so that data read from it is considered to
109 be "octets" i.e. characters in range 0..255 only. Likewise
110 on output perl will warn if a "wide" character is written
115 The C<:raw> layer is I<defined> as being identical to calling
116 C<binmode($fh)> - the stream is made suitable for passing binary
117 data i.e. each byte is passed as-is. The stream will still be
118 buffered. Unlike earlier versions of perl C<:raw> is I<not> just the
119 inverse of C<:crlf> - other layers which would affect the binary nature of
120 the stream are also removed or disabled.
122 The implementation of C<:raw> is as a pseudo-layer which when "pushed"
123 pops itself and then any layers which do not declare themselves as suitable
124 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
125 flags rather than poping layers but that is an implementation detail.)
127 As a consequence of the fact that C<:raw> normally pops layers
128 it usually only makes sense to have it as the only or first element in a
129 layer specification. When used as the first element it provides
130 a known base on which to build e.g.
132 open($fh,":raw:utf8",...)
134 will construct a "binary" stream, but then enable UTF-8 translation.
138 =head2 Alternatives to raw
140 To get a binary stream an alternate method is to use:
145 this has advantage of being backward compatible with how such things have
146 had to be coded on some platforms for years.
148 To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>)
151 open($fh,"<:unix",$path)
153 =head2 Defaults and how to override them
155 If the platform is MS-DOS like and normally does CRLF to "\n"
156 translation for text files then the default layers are :
160 (The low level "unix" layer may be replaced by a platform specific low
163 Otherwise if C<Configure> found out how to do "fast" IO using system's
164 stdio, then the default layers are :
168 Otherwise the default layers are
172 These defaults may change once perlio has been better tested and tuned.
174 The default can be overridden by setting the environment variable
175 PERLIO to a space separated list of layers (unix or platform low level
176 layer is always pushed first).
178 This can be used to see the effect of/bugs in the various layers e.g.
181 PERLIO=stdio ./perl harness
182 PERLIO=perlio ./perl harness
186 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
190 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>