X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/39f7a87036eb8d13c207511143dc7f2e620b3891..69ed27fe764cd794db1ef8cad79cb972940cca21:/lib/PerlIO.pm diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index c3c5c97..7658ce4 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -1,6 +1,6 @@ package PerlIO; -our $VERSION = '1.01'; +our $VERSION = '1.10'; # Map layer name to package that defines it our %alias; @@ -19,7 +19,7 @@ sub import { $layer = "${class}::$layer"; } - eval "require $layer"; + eval { require $layer =~ s{::}{/}gr . '.pm' }; warn $@ if $@; } } @@ -35,9 +35,10 @@ PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space =head1 SYNOPSIS - open($fh,"<:crlf", "my.txt"); # portably open a text file for reading + open($fh, "<:crlf", "my.txt"); # support platform-native and + # CRLF text files - open($fh,"<","his.jpg"); # portably open a binary file for reading + open($fh, "<", "his.jpg"); # portably open a binary file for reading binmode($fh); Shell: @@ -61,38 +62,50 @@ The following layers are currently defined: =over 4 -=item unix +=item :unix -Low level layer which calls C, C and C etc. +Lowest level layer which provides basic PerlIO operations in terms of +UNIX/POSIX numeric file descriptor calls +(open(), read(), write(), lseek(), close()). -=item stdio +=item :stdio Layer which calls C, C and C/C etc. Note that as this is "real" stdio it will ignore any layers beneath it and -got straight to the operating system via the C library as usual. +go straight to the operating system via the C library as usual. -=item perlio +=item :perlio -This is a re-implementation of "stdio-like" buffering written as a -PerlIO "layer". As such it will call whatever layer is below it for -its operations. +A from scratch implementation of buffering for PerlIO. Provides fast +access to the buffer for C which implements perl's readline/EE +and in general attempts to minimize data copying. -=item crlf +C<:perlio> will insert a C<:unix> layer below itself to do low level IO. -A layer which does CRLF to "\n" translation distinguishing "text" and -"binary" files in the manner of MS-DOS and similar operating systems. -(It currently does I mimic MS-DOS as far as treating of Control-Z -as being an end-of-file marker.) +=item :crlf -=item utf8 +A layer that implements DOS/Windows like CRLF line endings. On read +converts pairs of CR,LF to a single "\n" newline character. On write +converts each "\n" to a CR,LF pair. Note that this layer will silently +refuse to be pushed on top of itself. -Declares that the stream accepts perl's internal encoding of +It currently does I mimic MS-DOS as far as treating of Control-Z +as being an end-of-file marker. + +Based on the C<:perlio> layer. + +=item :utf8 + +Declares that the stream accepts perl's I encoding of characters. (Which really is UTF-8 on ASCII machines, but is UTF-EBCDIC on EBCDIC machines.) This allows any character perl can represent to be read from or written to the stream. The UTF-X encoding is chosen to render simple text parts (i.e. non-accented letters, digits and common punctuation) human readable in the encoded file. +(B: This layer does not validate byte sequences. For reading input, +you should instead use C<:encoding(UTF-8)> instead of bare C<:utf8>.) + Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) and then read it back in. @@ -104,29 +117,36 @@ and then read it back in. $in = ; close(F); -=item bytes -This is the inverse of C<:utf8> layer. It turns off the flag +=item :bytes + +This is the inverse of the C<:utf8> layer. It turns off the flag on the layer below so that data read from it is considered to -be "octets" i.e. characters in range 0..255 only. Likewise +be "octets" i.e. characters in the range 0..255 only. Likewise on output perl will warn if a "wide" character is written to a such a stream. -=item raw +=item :raw The C<:raw> layer is I as being identical to calling -C - the stream is made suitable for passing binary -data i.e. each byte is passed as-is. The stream will still be -buffered. Unlike earlier versions of perl C<:raw> is I just the -inverse of C<:crlf> - other layers which would affect the binary nature of -the stream are also removed or disabled. +C - the stream is made suitable for passing binary data, +i.e. each byte is passed as-is. The stream will still be +buffered. + +In Perl 5.6 and some books the C<:raw> layer (previously sometimes also +referred to as a "discipline") is documented as the inverse of the +C<:crlf> layer. That is no longer the case - other layers which would +alter the binary nature of the stream are also disabled. If you want UNIX +line endings on a platform that normally does CRLF translation, but still +want UTF-8 or encoding defaults, the appropriate thing to do is to add +C<:perlio> to the PERLIO environment variable. The implementation of C<:raw> is as a pseudo-layer which when "pushed" pops itself and then any layers which do not declare themselves as suitable for binary data. (Undoing :utf8 and :crlf are implemented by clearing flags rather than popping layers but that is an implementation detail.) -As a consequence of the fact that C<:raw> normally pops layers +As a consequence of the fact that C<:raw> normally pops layers, it usually only makes sense to have it as the only or first element in a layer specification. When used as the first element it provides a known base on which to build e.g. @@ -135,22 +155,27 @@ a known base on which to build e.g. will construct a "binary" stream, but then enable UTF-8 translation. -=item pop +=item :pop -A pseudo layer that removes the top-most layer. Gives perl code -a way to manipulate the layer stack. Should be considered -as experimental. Note that C<:pop> only works on real layers -and will not undo the effects of pseudo layers like C<:utf8>. -An example of a possible use might be: +A pseudo layer that removes the top-most layer. Gives perl code a +way to manipulate the layer stack. Note that C<:pop> only works on +real layers and will not undo the effects of pseudo layers like +C<:utf8>. An example of a possible use might be: open($fh,...) ... binmode($fh,":encoding(...)"); # next chunk is encoded ... - binmode($fh,":pop"); # back to un-encocded + binmode($fh,":pop"); # back to un-encoded A more elegant (and safer) interface is needed. +=item :win32 + +On Win32 platforms this I layer uses the native "handle" IO +rather than the unix-like numeric file descriptor layer. Known to be +buggy as of perl 5.8.2. + =back =head2 Custom Layers @@ -164,9 +189,24 @@ in Perl using the latter) come with the Perl distribution. =item :encoding Use C<:encoding(ENCODING)> either in open() or binmode() to install -a layer that does transparently character set and encoding transformations, -for example from Shift-JIS to Unicode. Note that an C<:encoding> also -enables C<:utf8>. See L for more information. +a layer that transparently does character set and encoding transformations, +for example from Shift-JIS to Unicode. Note that under C +an C<:encoding> also enables C<:utf8>. See L +for more information. + +=item :mmap + +A layer which implements "reading" of files by using C to +make a (whole) file appear in the process's address space, and then +using that as PerlIO's "buffer". This I be faster in certain +circumstances for large files, and may result in less physical memory +use when multiple processes are reading the same file. + +Files which are not C-able revert to behaving like the C<:perlio> +layer. Writes also behave like the C<:perlio> layer, as C for write +needs extra house-keeping (to extend the file) which negates any advantage. + +The C<:mmap> layer will not exist if the platform does not support C. =item :via @@ -184,10 +224,10 @@ To get a binary stream an alternate method is to use: open($fh,"whatever") binmode($fh); -this has advantage of being backward compatible with how such things have +this has the advantage of being backward compatible with how such things have had to be coded on some platforms for years. -To get an un-buffered stream specify an unbuffered layer (e.g. C<:unix>) +To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>) in the open call: open($fh,"<:unix",$path) @@ -202,8 +242,8 @@ translation for text files then the default layers are : (The low level "unix" layer may be replaced by a platform specific low level layer.) -Otherwise if C found out how to do "fast" IO using system's -stdio, then the default layers are : +Otherwise if C found out how to do "fast" IO using the system's +stdio, then the default layers are: unix stdio @@ -223,32 +263,54 @@ This can be used to see the effect of/bugs in the various layers e.g. PERLIO=stdio ./perl harness PERLIO=perlio ./perl harness -=head2 Querying the layers of filehandle +For the various values of PERLIO see L. + +=head2 Querying the layers of filehandles The following returns the B of the PerlIO layers on a filehandle. - my @layers = PerlIO::get_layers(FH); + my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH". The layers are returned in the order an open() or binmode() call would -use them. Note that the stack begings (normally) from C, the -platform specific low-level I/O (like C) is not part of the stack. +use them. Note that the "default stack" depends on the operating +system and on the Perl version, and both the compile-time and +runtime configurations of Perl. + +The following table summarizes the default layers on UNIX-like and +DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>: -By default the layers from the input side of the filehandle is -returned, to get the output side use the optional C argument: + PERLIO UNIX-like DOS-like + ------ --------- -------- + unset / "" unix perlio / stdio [1] unix crlf + stdio unix perlio / stdio [1] stdio + perlio unix perlio unix perlio - my @layers = PerlIO::get_layers(FH, output => 1); + # [1] "stdio" if Configure found out how to do "fast stdio" (depends + # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio" + +By default the layers from the input side of the filehandle are +returned; to get the output side, use the optional C argument: + + my @layers = PerlIO::get_layers($fh, output => 1); (Usually the layers are identical on either side of a filehandle but -for example with sockets there may be differences.) +for example with sockets there may be differences, or if you have +been using the C pragma.) + +There is no set_layers(), nor does get_layers() return a tied array +mirroring the stack, or anything fancy like that. This is not +accidental or unintentional. The PerlIO layer stack is a bit more +complicated than just a stack (see for example the behaviour of C<:raw>). +You are supposed to use open() and binmode() to manipulate the stack. B -The arguments to layers are by default returned in parenthesis after +The arguments to layers are by default returned in parentheses after the name of the layer, and certain layers (like C) are not real -layers but instead flags on real layers: to get all of these returned -separately use the optional C argument: +layers but instead flags on real layers; to get all of these returned +separately, use the optional C
argument: - my @layer_and_args_and_flags = PerlIO::get_layers(FH, details => 1); + my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1); The result will be up to be three times the number of layers: the first element will be a name, the second element the arguments @@ -267,4 +329,3 @@ L, L, L, L, L =cut -