Profile of PerlIO.pm

Filename	/usr/share/perl/5.20/PerlIO.pm
Statements	Executed 0 statements in 0s

Line	State ments	Time on line	Calls	Time in subs	Code
1					package PerlIO;
2
3					our $VERSION = '1.09';
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 =~ s{::}{/}gr . '.pm' };
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					(B<CAUTION>: This layer does not validate byte sequences. For reading input,
107					you should instead use C<:encoding(utf8)> instead of bare C<:utf8>.)
108
109					Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
110					and then read it back in.
111
112					open(F, ">:utf8", "data.utf");
113					print F $out;
114					close(F);
115
116					open(F, "<:utf8", "data.utf");
117					$in = <F>;
118					close(F);
119
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 a
161					way to manipulate the layer stack. Note that C<:pop> only works on
162					real layers and will not undo the effects of pseudo layers like
163					C<:utf8>. An example of a possible use might be:
164
165					open($fh,...)
166					...
167					binmode($fh,":encoding(...)"); # next chunk is encoded
168					...
169					binmode($fh,":pop"); # back to un-encoded
170
171					A more elegant (and safer) interface is needed.
172
173					=item :win32
174
175					On Win32 platforms this I<experimental> layer uses the native "handle" IO
176					rather than the unix-like numeric file descriptor layer. Known to be
177					buggy as of perl 5.8.2.
178
179					=back
180
181					=head2 Custom Layers
182
183					It is possible to write custom layers in addition to the above builtin
184					ones, both in C/XS and Perl. Two such layers (and one example written
185					in Perl using the latter) come with the Perl distribution.
186
187					=over 4
188
189					=item :encoding
190
191					Use C<:encoding(ENCODING)> either in open() or binmode() to install
192					a layer that transparently does character set and encoding transformations,
193					for example from Shift-JIS to Unicode. Note that under C<stdio>
194					an C<:encoding> also enables C<:utf8>. See L<PerlIO::encoding>
195					for more information.
196
197					=item :mmap
198
199					A layer which implements "reading" of files by using C<mmap()> to
200					make a (whole) file appear in the process's address space, and then
201					using that as PerlIO's "buffer". This I<may> be faster in certain
202					circumstances for large files, and may result in less physical memory
203					use when multiple processes are reading the same file.
204
205					Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
206					layer. Writes also behave like the C<:perlio> layer, as C<mmap()> for write
207					needs extra house-keeping (to extend the file) which negates any advantage.
208
209					The C<:mmap> layer will not exist if the platform does not support C<mmap()>.
210
211					=item :via
212
213					Use C<:via(MODULE)> either in open() or binmode() to install a layer
214					that does whatever transformation (for example compression /
215					decompression, encryption / decryption) to the filehandle.
216					See L<PerlIO::via> for more information.
217
218					=back
219
220					=head2 Alternatives to raw
221
222					To get a binary stream an alternate method is to use:
223
224					open($fh,"whatever")
225					binmode($fh);
226
227					this has the advantage of being backward compatible with how such things have
228					had to be coded on some platforms for years.
229
230					To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>)
231					in the open call:
232
233					open($fh,"<:unix",$path)
234
235					=head2 Defaults and how to override them
236
237					If the platform is MS-DOS like and normally does CRLF to "\n"
238					translation for text files then the default layers are :
239
240					unix crlf
241
242					(The low level "unix" layer may be replaced by a platform specific low
243					level layer.)
244
245					Otherwise if C<Configure> found out how to do "fast" IO using the system's
246					stdio, then the default layers are:
247
248					unix stdio
249
250					Otherwise the default layers are
251
252					unix perlio
253
254					These defaults may change once perlio has been better tested and tuned.
255
256					The default can be overridden by setting the environment variable
257					PERLIO to a space separated list of layers (C<unix> or platform low
258					level layer is always pushed first).
259
260					This can be used to see the effect of/bugs in the various layers e.g.
261
262					cd .../perl/t
263					PERLIO=stdio ./perl harness
264					PERLIO=perlio ./perl harness
265
266					For the various values of PERLIO see L<perlrun/PERLIO>.
267
268					=head2 Querying the layers of filehandles
269
270					The following returns the B<names> of the PerlIO layers on a filehandle.
271
272					my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
273
274					The layers are returned in the order an open() or binmode() call would
275					use them. Note that the "default stack" depends on the operating
276					system and on the Perl version, and both the compile-time and
277					runtime configurations of Perl.
278
279					The following table summarizes the default layers on UNIX-like and
280					DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>:
281
282					PERLIO UNIX-like DOS-like
283					------ --------- --------
284					unset / "" unix perlio / stdio [1] unix crlf
285					stdio unix perlio / stdio [1] stdio
286					perlio unix perlio unix perlio
287
288					# [1] "stdio" if Configure found out how to do "fast stdio" (depends
289					# on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"
290
291					By default the layers from the input side of the filehandle are
292					returned; to get the output side, use the optional C<output> argument:
293
294					my @layers = PerlIO::get_layers($fh, output => 1);
295
296					(Usually the layers are identical on either side of a filehandle but
297					for example with sockets there may be differences, or if you have
298					been using the C<open> pragma.)
299
300					There is no set_layers(), nor does get_layers() return a tied array
301					mirroring the stack, or anything fancy like that. This is not
302					accidental or unintentional. The PerlIO layer stack is a bit more
303					complicated than just a stack (see for example the behaviour of C<:raw>).
304					You are supposed to use open() and binmode() to manipulate the stack.
305
306					B<Implementation details follow, please close your eyes.>
307
308					The arguments to layers are by default returned in parentheses after
309					the name of the layer, and certain layers (like C<utf8>) are not real
310					layers but instead flags on real layers; to get all of these returned
311					separately, use the optional C<details> argument:
312
313					my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
314
315					The result will be up to be three times the number of layers:
316					the first element will be a name, the second element the arguments
317					(unspecified arguments will be C<undef>), the third element the flags,
318					the fourth element a name again, and so forth.
319
320					B<You may open your eyes now.>
321
322					=head1 AUTHOR
323
324					Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
325
326					=head1 SEE ALSO
327
328					L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>,
329					L<Encode>
330
331					=cut