This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
f45116f990f066c3bef0933ee7a5e19bfa3e7aed
[perl5.git] / lib / PerlIO.pm
1 package PerlIO;
2
3 our $VERSION = '1.07';
4
5 # Map layer name to package that defines it
6 our %alias;
7
8 sub import
9 {
10  my $class = shift;
11  while (@_)
12   {
13    my $layer = shift;
14    if (exists $alias{$layer})
15     {
16      $layer = $alias{$layer}
17     }
18    else
19     {
20      $layer = "${class}::$layer";
21     }
22    eval "require $layer";
23    warn $@ if $@;
24   }
25 }
26
27 sub F_UTF8 () { 0x8000 }
28
29 1;
30 __END__
31
32 =head1 NAME
33
34 PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space
35
36 =head1 SYNOPSIS
37
38   open($fh, "<:crlf", "my.txt"); # support platform-native and 
39                                  # CRLF text files
40
41   open($fh, "<", "his.jpg"); # portably open a binary file for reading
42   binmode($fh);
43
44   Shell:
45     PERLIO=perlio perl ....
46
47 =head1 DESCRIPTION
48
49 When an undefined layer 'foo' is encountered in an C<open> or
50 C<binmode> layer specification then C code performs the equivalent of:
51
52   use PerlIO 'foo';
53
54 The perl code in PerlIO.pm then attempts to locate a layer by doing
55
56   require PerlIO::foo;
57
58 Otherwise the C<PerlIO> package is a place holder for additional
59 PerlIO related functions.
60
61 The following layers are currently defined:
62
63 =over 4
64
65 =item :unix
66
67 Lowest level layer which provides basic PerlIO operations in terms of
68 UNIX/POSIX numeric file descriptor calls
69 (open(), read(), write(), lseek(), close()).
70
71 =item :stdio
72
73 Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc.  Note
74 that as this is "real" stdio it will ignore any layers beneath it and
75 go straight to the operating system via the C library as usual.
76
77 =item :perlio
78
79 A from scratch implementation of buffering for PerlIO. Provides fast
80 access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
81 and in general attempts to minimize data copying.
82
83 C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
84
85 =item :crlf
86
87 A layer that implements DOS/Windows like CRLF line endings.  On read
88 converts pairs of CR,LF to a single "\n" newline character.  On write
89 converts each "\n" to a CR,LF pair.  Note that this layer will silently
90 refuse to be pushed on top of itself.
91
92 It currently does I<not> mimic MS-DOS as far as treating of Control-Z
93 as being an end-of-file marker.
94
95 Based on the C<:perlio> layer.
96
97 =item :utf8
98
99 Declares that the stream accepts perl's I<internal> encoding of
100 characters.  (Which really is UTF-8 on ASCII machines, but is
101 UTF-EBCDIC on EBCDIC machines.)  This allows any character perl can
102 represent to be read from or written to the stream. The UTF-X encoding
103 is chosen to render simple text parts (i.e.  non-accented letters,
104 digits and common punctuation) human readable in the encoded file.
105
106 Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
107 and then read it back in.
108
109         open(F, ">:utf8", "data.utf");
110         print F $out;
111         close(F);
112
113         open(F, "<:utf8", "data.utf");
114         $in = <F>;
115         close(F);
116
117 Note that this layer does not validate byte sequences. For reading
118 input, using C<:encoding(utf8)> instead of bare C<:utf8> is strongly
119 recommended.
120
121 =item :bytes
122
123 This is the inverse of the C<:utf8> layer. It turns off the flag
124 on the layer below so that data read from it is considered to
125 be "octets" i.e. characters in the range 0..255 only. Likewise
126 on output perl will warn if a "wide" character is written
127 to a such a stream.
128
129 =item :raw
130
131 The C<:raw> layer is I<defined> as being identical to calling
132 C<binmode($fh)> - the stream is made suitable for passing binary data,
133 i.e. each byte is passed as-is. The stream will still be
134 buffered.
135
136 In Perl 5.6 and some books the C<:raw> layer (previously sometimes also
137 referred to as a "discipline") is documented as the inverse of the
138 C<:crlf> layer. That is no longer the case - other layers which would
139 alter the binary nature of the stream are also disabled.  If you want UNIX
140 line endings on a platform that normally does CRLF translation, but still
141 want UTF-8 or encoding defaults, the appropriate thing to do is to add
142 C<:perlio> to the PERLIO environment variable.
143
144 The implementation of C<:raw> is as a pseudo-layer which when "pushed"
145 pops itself and then any layers which do not declare themselves as suitable
146 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
147 flags rather than popping layers but that is an implementation detail.)
148
149 As a consequence of the fact that C<:raw> normally pops layers,
150 it usually only makes sense to have it as the only or first element in
151 a layer specification.  When used as the first element it provides
152 a known base on which to build e.g.
153
154     open($fh,":raw:utf8",...)
155
156 will construct a "binary" stream, but then enable UTF-8 translation.
157
158 =item :pop
159
160 A pseudo layer that removes the top-most layer. Gives perl code
161 a way to manipulate the layer stack. Should be considered
162 as experimental. Note that C<:pop> only works on real layers
163 and will not undo the effects of pseudo layers like C<:utf8>.
164 An example of a possible use might be:
165
166     open($fh,...)
167     ...
168     binmode($fh,":encoding(...)");  # next chunk is encoded
169     ...
170     binmode($fh,":pop");            # back to un-encoded
171
172 A more elegant (and safer) interface is needed.
173
174 =item :win32
175
176 On Win32 platforms this I<experimental> layer uses the native "handle" IO
177 rather than the unix-like numeric file descriptor layer. Known to be
178 buggy as of perl 5.8.2.
179
180 =back
181
182 =head2 Custom Layers
183
184 It is possible to write custom layers in addition to the above builtin
185 ones, both in C/XS and Perl.  Two such layers (and one example written
186 in Perl using the latter) come with the Perl distribution.
187
188 =over 4
189
190 =item :encoding
191
192 Use C<:encoding(ENCODING)> either in open() or binmode() to install
193 a layer that transparently does character set and encoding transformations,
194 for example from Shift-JIS to Unicode.  Note that under C<stdio>
195 an C<:encoding> also enables C<:utf8>.  See L<PerlIO::encoding>
196 for more information.
197
198 =item :mmap
199
200 A layer which implements "reading" of files by using C<mmap()> to
201 make a (whole) file appear in the process's address space, and then
202 using that as PerlIO's "buffer". This I<may> be faster in certain
203 circumstances for large files, and may result in less physical memory
204 use when multiple processes are reading the same file.
205
206 Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
207 layer. Writes also behave like the C<:perlio> layer, as C<mmap()> for write
208 needs extra house-keeping (to extend the file) which negates any advantage.
209
210 The C<:mmap> layer will not exist if the platform does not support C<mmap()>.
211
212 =item :via
213
214 Use C<:via(MODULE)> either in open() or binmode() to install a layer
215 that does whatever transformation (for example compression /
216 decompression, encryption / decryption) to the filehandle.
217 See L<PerlIO::via> for more information.
218
219 =back
220
221 =head2 Alternatives to raw
222
223 To get a binary stream an alternate method is to use:
224
225     open($fh,"whatever")
226     binmode($fh);
227
228 this has the advantage of being backward compatible with how such things have
229 had to be coded on some platforms for years.
230
231 To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>)
232 in the open call:
233
234     open($fh,"<:unix",$path)
235
236 =head2 Defaults and how to override them
237
238 If the platform is MS-DOS like and normally does CRLF to "\n"
239 translation for text files then the default layers are :
240
241   unix crlf
242
243 (The low level "unix" layer may be replaced by a platform specific low
244 level layer.)
245
246 Otherwise if C<Configure> found out how to do "fast" IO using the system's
247 stdio, then the default layers are:
248
249   unix stdio
250
251 Otherwise the default layers are
252
253   unix perlio
254
255 These defaults may change once perlio has been better tested and tuned.
256
257 The default can be overridden by setting the environment variable
258 PERLIO to a space separated list of layers (C<unix> or platform low
259 level layer is always pushed first).
260
261 This can be used to see the effect of/bugs in the various layers e.g.
262
263   cd .../perl/t
264   PERLIO=stdio  ./perl harness
265   PERLIO=perlio ./perl harness
266
267 For the various values of PERLIO see L<perlrun/PERLIO>.
268
269 =head2 Querying the layers of filehandles
270
271 The following returns the B<names> of the PerlIO layers on a filehandle.
272
273    my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
274
275 The layers are returned in the order an open() or binmode() call would
276 use them.  Note that the "default stack" depends on the operating
277 system and on the Perl version, and both the compile-time and
278 runtime configurations of Perl.
279
280 The following table summarizes the default layers on UNIX-like and
281 DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>:
282
283  PERLIO     UNIX-like                   DOS-like
284  ------     ---------                   --------
285  unset / "" unix perlio / stdio [1]     unix crlf
286  stdio      unix perlio / stdio [1]     stdio
287  perlio     unix perlio                 unix perlio
288
289  # [1] "stdio" if Configure found out how to do "fast stdio" (depends
290  # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
291
292 By default the layers from the input side of the filehandle are
293 returned; to get the output side, use the optional C<output> argument:
294
295    my @layers = PerlIO::get_layers($fh, output => 1);
296
297 (Usually the layers are identical on either side of a filehandle but
298 for example with sockets there may be differences, or if you have
299 been using the C<open> pragma.)
300
301 There is no set_layers(), nor does get_layers() return a tied array
302 mirroring the stack, or anything fancy like that.  This is not
303 accidental or unintentional.  The PerlIO layer stack is a bit more
304 complicated than just a stack (see for example the behaviour of C<:raw>).
305 You are supposed to use open() and binmode() to manipulate the stack.
306
307 B<Implementation details follow, please close your eyes.>
308
309 The arguments to layers are by default returned in parentheses after
310 the name of the layer, and certain layers (like C<utf8>) are not real
311 layers but instead flags on real layers; to get all of these returned
312 separately, use the optional C<details> argument:
313
314    my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
315
316 The result will be up to be three times the number of layers:
317 the first element will be a name, the second element the arguments
318 (unspecified arguments will be C<undef>), the third element the flags,
319 the fourth element a name again, and so forth.
320
321 B<You may open your eyes now.>
322
323 =head1 AUTHOR
324
325 Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
326
327 =head1 SEE ALSO
328
329 L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>,
330 L<Encode>
331
332 =cut