From: Nick Ing-Simmons Date: Sat, 20 Apr 2002 13:38:24 +0000 (+0000) Subject: Fill in the PERLIO sections. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=44a4342c9f1bf4dd16241a6721340a5828ede477;p=p5sagit%2Fp5-mst-13.2.git Fill in the PERLIO sections. p4raw-id: //depot/perlio@16018 --- diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 082a38e..564d111 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -81,7 +81,7 @@ if you were so inclined, say eval 'exec perl -wS $0 ${1+"$@"}' if $running_under_some_shell; -to let Perl see the B<-p> switch. +to let Perl see the B<-p> switch. A similar trick involves the B program, if you have it. @@ -302,7 +302,7 @@ sets debugging flags. To watch how it executes your program, use B<-Dtls>. (This works only if debugging is compiled into your Perl.) Another nice value is B<-Dx>, which lists your compiled syntax tree. And B<-Dr> displays compiled regular expressions; -the format of the output is explained in L. +the format of the output is explained in L. As an alternative, specify a number instead of list of letters (e.g., B<-D14> is equivalent to B<-Dtls>): @@ -330,13 +330,13 @@ B<-D14> is equivalent to B<-Dtls>): All these flags require B<-DDEBUGGING> when you compile the Perl executable (but see L, L which may change this). -See the F file in the Perl source distribution +See the F file in the Perl source distribution for how to do this. This flag is automatically set if you include B<-g> option when C asks you about optimizer/debugger flags. If you're just trying to get a print out of each line of Perl code as it executes, the way that C provides for shell scripts, -you can't use Perl's B<-D> switch. Instead do this +you can't use Perl's B<-D> switch. Instead do this # If you have "env" utility env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program @@ -547,7 +547,7 @@ Here is an efficient way to delete all files older than a week: This is faster than using the B<-exec> switch of B because you don't have to start a process on every filename found. It does suffer from the bug of mishandling newlines in pathnames, which you can fix if -you follow the example under B<-0>. +you follow the example under B<-0>. C and C blocks may be used to capture control before or after the implicit program loop, just as in B. @@ -603,7 +603,7 @@ A C<-P> on a C<#!> line doesn't work. B lines that begin with (whitespace and) a C<#> but do not look like cpp commands, are stripped, including anything -inside Perl strings, regular expressions, and here-docs . +inside Perl strings, regular expressions, and here-docs . =item * @@ -764,7 +764,7 @@ values of @INC. =item B<-V:>I Prints to STDOUT the value of the named configuration variable. -For example, +For example, $ perl -V:man.dir @@ -855,45 +855,137 @@ enabled, and any subsequent options ignored. =item PERLIO -A space-separated list of PerlIO layers. +A space (or colon) separated list of PerlIO layers. If perl is built +to use PerlIO system for IO (the default) these layers effect perl's IO. + +It is conventional to start layer names with a colon e.g. C<:perlio> to +emphasise their similarity to variable "attributes". But the code that parses +layer specification strings (which is also used to decode the PERLIO +environment variable) treats the colon as a separator. + +The list becomes the default for I perl's IO. Consequently only built-in +layers can appear in this list, as external layers (such as :encoding()) need +IO in order to load them!. See L<"open pragma"|open> for how to add external +encodings as defaults. + +The layers that it makes sense to include in the PERLIO environment +variable are summarised below. For more details see L. =over 8 =item :bytes -XXX +Turns I the C<:utf8> flag for the layer below. +Unlikey to be useful in global PERLIO environment variable. =item :crlf -XXX +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. +Based on the C<:perlio> layer. + +=item :mmap + +A layer which implements "reading" of files by using C to +make (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. -=item mmap +Files which are not C-able revert to behaving like the C<:perlio> +layer. Writes also behave like C<:perlio> layer as C for write +needs extra house-keeping (to extend the file) which negates any advantage. -XXX +The C<:mmap> layer will not exist if platform does not support C. -=item perlio +=item :perlio -XXX +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 raw +C<:perlio> will insert a C<:unix> layer below itself to do low level IO. -XXX +=item :raw -=item stdio +Arranges for all accesses go straight to the lowest level layer provided +by the configration. That is it strips off any layers above that layer. +(The intent - unless layers are then pushed on top again - +is to make perl's C behave like C.) -XXX +Not really useful in PERLIO environment variable, instead just use C<:unix> +layer explicitly. -=item unix +In perl5.6 and some books the C<:raw> layer (also called a discipline) is +documented as the inverse of the C<:crlf> layer. That is not really the case. +If you want UNIX line endings on a platform that normaly does CRLF translation +the appropriate thing to do is to add C<:perlio> to PERLIO environment +variable. -XXX +=item :stdio + +This layer provides PerlIO interface by wrapping system's ANSI C "stdio" +library calls. The layer provides both buffering and IO. +Note that C<:stdio> layer does I do CRLF translation even if that +is platforms normal behaviour. You will need a C<:crlf> layer above it +to do that. + +=item :unix + +Lowest level layer which provides basic PerlIO operations in terms of +UNIX/POSIX numeric file descriptor calls +C =item :utf8 -XXX +Turns on a flag on the layer below to tell perl that data sent to the +stream should be converted to perl internal "utf8" form and that data from the +stream should be considered as so encoded. On ASCII based platforms the +encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC. +May be useful in PERLIO environment variable to make UTF-8 the +default. (To turn off that behaviour use C<:bytes> layer.) + +=item :win32 + +On Win32 platfroms this I layer uses native "handle" IO +rather than unix-like numeric file descriptor layer. Known to be +buggy in this release. =back -For example, XXX ... for Unicode XXXX ... for Win32 XXX +On all platforms the default set of layers should give acceptable results. + +For UNIX platfroms that will equivalent of "unix perlio" or "stdio". +Configure is setup to prefer "stdio" implementation if system's library +provides for fast access to the buffer, otherwise it uses the "unix perlio" +implementation. + +On Win32 the default in this release is "unix crlf". Win32's "stdio" +has a number of bugs/mis-features for perl IO which are somewhat +C compiler verndor/version dependant. Using our own C layer as +the buffer avoids those issues and makes things more uniform. +The C layer provides CRLF to/from "\n" conversion as well as +buffering. + +This release uses C as the bottom layer on Win32 and so still uses C +compiler's numeric file descriptor routines. There is an experimental native +C layer which is expected to be enhanced and should eventually replace +the C layer. + +=item PERLIO_DEBUG + +If set to the name of a file or device then certain operations of PerlIO +sub-system will be logged to that file (opened as append). Typical uses +are UNIX: + + PERLIO_DEBUG=/dev/tty perl script ... + +and Win32 approximate equivalent: + + set PERLIO_DEBUG=CON + perl script ... + =item PERLLIB @@ -945,8 +1037,8 @@ PERL_ENCODING environment variable is consulted for an encoding name. A translation concealed rooted logical name that contains perl and the logical device for the @INC path on VMS only. Other logical names that -affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and -SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in +affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and +SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in L and in F in the Perl source distribution. =item SYS$LOGIN (specific to the VMS port)