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<env> program, if you have it.
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<perldebguts>.
+the format of the output is explained in L<perldebguts>.
As an alternative, specify a number instead of list of letters (e.g.,
B<-D14> is equivalent to B<-Dtls>):
All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see L<Devel::Peek>, L<re> which may change this).
-See the F<INSTALL> file in the Perl source distribution
+See the F<INSTALL> file in the Perl source distribution
for how to do this. This flag is automatically set if you include B<-g>
option when C<Configure> 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<sh -x> 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
This is faster than using the B<-exec> switch of B<find> 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<BEGIN> and C<END> blocks may be used to capture control before or after
the implicit program loop, just as in B<awk>.
B<All> 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 *
=item B<-V:>I<name>
Prints to STDOUT the value of the named configuration variable.
-For example,
+For example,
$ perl -V:man.dir
=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<all> 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<PerlIO>.
=over 8
=item :bytes
-XXX
+Turns I<off> 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<mmap()> to
+make (whole) file appear in the process's address space, and then
+using that as PerlIO's "buffer". This I<may> 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<mmap()>-able revert to behaving like the C<:perlio>
+layer. Writes also behave like C<:perlio> layer as C<mmap()> 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<mmap()>.
-=item perlio
+=item :perlio
-XXX
+A from scratch implementation of buffering for PerlIO. Provides fast
+access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
+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<read> behave like C<sysread>.)
-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<not> 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<open(), read(), write(), lseek(), close()>
=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<experimental> 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<crlf> layer as
+the buffer avoids those issues and makes things more uniform.
+The C<crlf> layer provides CRLF to/from "\n" conversion as well as
+buffering.
+
+This release uses C<unix> as the bottom layer on Win32 and so still uses C
+compiler's numeric file descriptor routines. There is an experimental native
+C<win32> layer which is expected to be enhanced and should eventually replace
+the C<unix> 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
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<perlvms> and in F<README.vms> in the Perl source distribution.
=item SYS$LOGIN (specific to the VMS port)
projects / p5sagit/p5-mst-13.2.git / commitdiff