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 writing
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.
85 Declares that the stream accepts perl's internal encoding of
86 characters. (Which really is UTF-8 on ASCII machines, but is
87 UTF-EBCDIC on EBCDIC machines.) This allows any character perl can
88 represent to be read from or written to the stream. The UTF-X encoding
89 is chosen to render simple text parts (i.e. non-accented letters,
90 digits and common punctuation) human readable in the encoded file.
92 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
93 and then read it back in.
95 open(F, ">:utf8", "data.utf");
99 open(F, "<:utf8", "data.utf");
105 This is the inverse of C<:utf8> layer. It turns off the flag
106 on the layer below so that data read from it is considered to
107 be "octets" i.e. characters in range 0..255 only. Likewise
108 on output perl will warn if a "wide" character is written
113 B<Note that the explicit use of the C<raw> layer is deprecated.>
115 A pseudo-layer which performs two functions (which is messy, but
116 necessary to maintain compatibility with non-PerlIO builds of Perl
117 and their way things have been documented elsewhere).
119 Firstly it forces the file handle to be considered binary at that
120 point in the layer stack, i.e. it turns off any CRLF translation.
122 Secondly in prevents the IO system seaching back before it in the
123 layer specification. Thus:
125 open($fh,":raw:perlio",...)
127 Forces the use of C<perlio> layer even if the platform default, or
128 C<use open> default is something else (such as ":encoding(iso-8859-7)")
129 (the C<:encoding> requires C<use Encode>) which would interfere with
130 binary nature of the stream.
134 =head2 Defaults and how to override them
136 If the platform is MS-DOS like and normally does CRLF to "\n"
137 translation for text files then the default layers are :
141 (The low level "unix" layer may be replaced by a platform specific low
144 Otherwise if C<Configure> found out how to do "fast" IO using system's
145 stdio, then the default layers are :
149 Otherwise the default layers are
153 These defaults may change once perlio has been better tested and tuned.
155 The default can be overridden by setting the environment variable
156 PERLIO to a space separated list of layers (unix or platform low level
157 layer is always pushed first).
159 This can be used to see the effect of/bugs in the various layers e.g.
162 PERLIO=stdio ./perl harness
163 PERLIO=perlio ./perl harness
167 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
171 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<Encode>