diff options
Diffstat (limited to 'pod')
59 files changed, 10336 insertions, 3805 deletions
diff --git a/pod/Makefile b/pod/Makefile index 50fb270865..bd2e148c42 100644 --- a/pod/Makefile +++ b/pod/Makefile @@ -47,6 +47,7 @@ POD = \ perlipc.pod \ perlthrtut.pod \ perldbmfilter.pod \ + perldebguts.pod \ perldebug.pod \ perlnumber.pod \ perldiag.pod \ @@ -113,6 +114,7 @@ MAN = \ perlipc.man \ perlthrtut.man \ perldbmfilter.man \ + perldebguts.man \ perldebug.man \ perlnumber.man \ perldiag.man \ @@ -179,6 +181,7 @@ HTML = \ perlipc.html \ perlthrtut.html \ perldbmfilter.html \ + perldebguts.html \ perldebug.html \ perlnumber.html \ perldiag.html \ @@ -245,6 +248,7 @@ TEX = \ perlipc.tex \ perlthrtut.tex \ perldbmfilter.tex \ + perldebguts.tex \ perldebug.tex \ perlnumber.tex \ perldiag.tex \ diff --git a/pod/Win32.pod b/pod/Win32.pod index 37c5cbd43d..bd1d06581e 100644 --- a/pod/Win32.pod +++ b/pod/Win32.pod @@ -92,8 +92,8 @@ between two backslashes) on this file system. =item Win32::FreeLibrary(HANDLE) [EXT] Unloads a previously loaded dynamic-link library. The HANDLE is -no longer valid after this call. See L<LoadLibrary> for information on -dynamically loading a library. +no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)> +for information on dynamically loading a library. =item Win32::GetArchName() @@ -132,7 +132,7 @@ same value. =item Win32::GetLongPathName(PATHNAME) -[CORE] Returns a representaion of PATHNAME composed of longname +[CORE] Returns a representation of PATHNAME composed of longname components (if any). The result may not necessarily be longer than PATHNAME. No attempt is made to convert PATHNAME to the absolute path. Compare with Win32::GetShortPathName and diff --git a/pod/buildtoc b/pod/buildtoc index d947ddccee..58bfc54fd7 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -11,7 +11,7 @@ sub output ($); perlmod perlmodlib perlmodinstall perlfork perlform perllocale perlref perlreftut perldsc perllol perlboot perltoot perltootc perlobj perltie perlbot perlipc - perldbmfilter perldebug perlnumber + perldbmfilter perldebug perlnumber perldebguts perldiag perlsec perltrap perlport perlstyle perlpod perlbook perlembed perlapio perlxs perlxstut perlguts perlcall perlcompile perlapi perlintern perlhist @@ -177,10 +177,11 @@ sub podset { $inhead2 = 1; output $_; nl(); next; } - if (s/^=item ([^=].*)\n/$1/) { + if (s/^=item ([^=].*)/$1/) { next if $pod eq 'perldiag'; s/^\s*\*\s*$// && next; s/^\s*\*\s*//; + s/\n/ /g; s/\s+$//; next if /^[\d.]+$/; next if $pod eq 'perlmodlib' && /^ftp:/; diff --git a/pod/perl.pod b/pod/perl.pod index 120dc44f09..59ca0e0368 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -69,6 +69,7 @@ sections: perlembed Perl ways to embed perl in your C or C++ application perlapio Perl internal IO abstraction interface + perldebguts Perl debugging guts and tips perlxs Perl XS application programming interface perlxstut Perl XS tutorial perlguts Perl internal functions for those doing extensions @@ -84,6 +85,7 @@ sections: perlcygwin Perl notes for Cygwin perldos Perl notes for DOS perlhpux Perl notes for HP-UX + perlmachten Perl notes for Power MachTen perlos2 Perl notes for OS/2 perlos390 Perl notes for OS/390 perlvms Perl notes for VMS @@ -222,147 +224,8 @@ Okay, that's I<definitely> enough hype. =head1 AVAILABILITY Perl is available for most operating systems, including virtually -all Unix-like platforms. - -As of early March 2000 (the Perl release 5.6.0), the following -platforms are able to build Perl from the standard source code -distribution available at http://www.perl.com/CPAN/src/index.html - - AIX - DOS DJGPP 1) - FreeBSD - HP-UX - IRIX - Linux - MachTen - MPE/iX - NetBSD - OpenBSD - OS/2 - Rhapsody/Darwin 2) - Solaris - Tru64 UNIX 3) - UNICOS - UNICOS/mk - VMS - VOS - Windows 3.1 1) - Windows 95 1) 4) - Windows 98 1) 4) - Windows NT 1) 4) - - 1) in DOS mode either the DOS or OS/2 ports can be used - 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X - 3) formerly known as Digital UNIX and before that DEC OSF/1 - 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++ - -The following platforms worked for the previous major release -(5.005_03 being the latest maintenance release of that, as of early -March 2000), but be did not manage to test these in time for the 5.6.0 -release of Perl. There is a very good chance that these will work -just fine with 5.6.0. - - A/UX - BeOS - BSD/OS - DG/UX - DYNIX/ptx - DomainOS - Hurd - NextSTEP - OpenSTEP - PowerMAX - QNX - SCO ODT/OSR - SunOS - SVR4 - Ultrix - -The following platform worked for the previous major release (5.005_03 -being the latest maintenance release of that, as of early March 2000). -However, standardization on UTF-8 as the internal string representation -in 5.6.0 has introduced incompatibilities in this EBCDIC platform. -Support for this platform may be enabled in a future release: - - OS390 1) - - 1) Previously known as MVS, or OpenEdition MVS. - -Strongly related to the OS390 platform by also being EBCDIC-based -mainframe platforms are the following platforms: - - BS2000 - VM/ESA - -These are also not expected to work under 5.6.0 for the same reasons -as OS390. Contact the mailing list perl-mvs@perl.org for more details. - -MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source -does work with 5.6.0, but additional MacOS specific source code is needed -for a complete port. Contact the mailing list macperl-porters@macperl.org -for more more information. - -The following platforms have been known to build Perl from source in -the past, but we haven't been able to verify their status for the -current release, either because the hardware/software platforms are -rare or because we don't have an active champion on these -platforms--or both: - - 3b1 - AmigaOS - ConvexOS - CX/UX - DC/OSx - DDE SMES - DOS EMX - Dynix - EP/IX - ESIX - FPS - GENIX - Greenhills - ISC - MachTen 68k - MiNT - MPC - NEWS-OS - Opus - Plan 9 - PowerUX - RISC/os - Stellar - SVR2 - TI1500 - TitanOS - Unisys Dynix - Unixware - -Support for the following platform is planned for a future Perl release: - - Netware - -The following platforms have their own source code distributions and -binaries available via http://www.perl.com/CPAN/ports/index.html: - - Perl release - - AS/400 5.003 - Netware 5.003_07 - Tandem Guardian 5.004 - -The following platforms have only binaries available via -http://www.perl.com/CPAN/ports/index.html: - - Perl release - - Acorn RISCOS 5.005_02 - AOS 5.002 - LynxOS 5.004_02 - -Although we do suggest that you always build your own Perl from -the source code, both for maximal configurability and for security, -in case you are in a hurry you can check -http://www.perl.com/CPAN/ports/index.html for binary distributions. +all Unix-like platforms. See L<perlport/"Supported Platforms"> +for a listing. =head1 ENVIRONMENT @@ -391,7 +254,8 @@ Perl developers, please write to perl-thanks@perl.org . =head1 DIAGNOSTICS -The B<-w> switch produces some lovely diagnostics. +The C<use warnings> pragma (and the B<-w> switch) produces some +lovely diagnostics. See L<perldiag> for explanations of all Perl's diagnostics. The C<use diagnostics> pragma automatically turns Perl's normally terse warnings @@ -430,7 +294,7 @@ affected by wraparound). You may mail your bug reports (be sure to include full configuration information as output by the myconfig program in the perl source tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded -in compiling perl, the perlbug script in the utils/ subdirectory +in compiling perl, the B<perlbug> script in the F<utils/> subdirectory can be used to help mail in a bug report. Perl actually stands for Pathologically Eclectic Rubbish Lister, but diff --git a/pod/perl56delta.pod b/pod/perl56delta.pod new file mode 100644 index 0000000000..27cdc224ff --- /dev/null +++ b/pod/perl56delta.pod @@ -0,0 +1,2954 @@ +=head1 NAME + +perldelta - what's new for perl v5.6.0 + +=head1 DESCRIPTION + +This document describes differences between the 5.005 release and this one. + +=head1 Core Enhancements + +=head2 Interpreter cloning, threads, and concurrency + +Perl 5.005_63 introduces the beginnings of support for running multiple +interpreters concurrently in different threads. In conjunction with +the perl_clone() API call, which can be used to selectively duplicate +the state of any given interpreter, it is possible to compile a +piece of code once in an interpreter, clone that interpreter +one or more times, and run all the resulting interpreters in distinct +threads. + +On the Windows platform, this feature is used to emulate fork() at the +interpreter level. See L<perlfork> for details about that. + +This feature is still in evolution. It is eventually meant to be used +to selectively clone a subroutine and data reachable from that +subroutine in a separate interpreter and run the cloned subroutine +in a separate thread. Since there is no shared data between the +interpreters, little or no locking will be needed (unless parts of +the symbol table are explicitly shared). This is obviously intended +to be an easy-to-use replacement for the existing threads support. + +Support for cloning interpreters and interpreter concurrency can be +enabled using the -Dusethreads Configure option (see win32/Makefile for +how to enable it on Windows.) The resulting perl executable will be +functionally identical to one that was built with -Dmultiplicity, but +the perl_clone() API call will only be available in the former. + +-Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn +enables Perl source code changes that provide a clear separation between +the op tree and the data it operates with. The former is immutable, and +can therefore be shared between an interpreter and all of its clones, +while the latter is considered local to each interpreter, and is therefore +copied for each clone. + +Note that building Perl with the -Dusemultiplicity Configure option +is adequate if you wish to run multiple B<independent> interpreters +concurrently in different threads. -Dusethreads only provides the +additional functionality of the perl_clone() API call and other +support for running B<cloned> interpreters concurrently. + + NOTE: This is an experimental feature. Implementation details are + subject to change. + +=head2 Lexically scoped warning categories + +You can now control the granularity of warnings emitted by perl at a finer +level using the C<use warnings> pragma. L<warnings> and L<perllexwarn> +have copious documentation on this feature. + +=head2 Unicode and UTF-8 support + +Perl now uses UTF-8 as its internal representation for character +strings. The C<utf8> and C<bytes> pragmas are used to control this support +in the current lexical scope. See L<perlunicode>, L<utf8> and L<bytes> for +more information. + +This feature is expected to evolve quickly to support some form of I/O +disciplines that can be used to specify the kind of input and output data +(bytes or characters). Until that happens, additional modules from CPAN +will be needed to complete the toolkit for dealing with Unicode. + + NOTE: This should be considered an experimental feature. Implementation + details are subject to change. + +=head2 Support for interpolating named characters + +The new C<\N> escape interpolates named characters within strings. +For example, C<"Hi! \N{WHITE SMILING FACE}"> evaluates to a string +with a unicode smiley face at the end. + +=head2 "our" declarations + +An "our" declaration introduces a value that can be best understood +as a lexically scoped symbolic alias to a global variable in the +package that was current where the variable was declared. This is +mostly useful as an alternative to the C<vars> pragma, but also provides +the opportunity to introduce typing and other attributes for such +variables. See L<perlfunc/our>. + +=head2 Support for strings represented as a vector of ordinals + +Literals of the form C<v1.2.3.4> are now parsed as a string composed +of characters with the specified ordinals. This is an alternative, more +readable way to construct (possibly unicode) strings instead of +interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">. The leading +C<v> may be omitted if there are more than two ordinals, so C<1.2.3> is +parsed the same as C<v1.2.3>. + +Strings written in this form are also useful to represent version "numbers". +It is easy to compare such version "numbers" (which are really just plain +strings) using any of the usual string comparison operators C<eq>, C<ne>, +C<lt>, C<gt>, etc., or perform bitwise string operations on them using C<|>, +C<&>, etc. + +In conjunction with the new C<$^V> magic variable (which contains +the perl version as a string), such literals can be used as a readable way +to check if you're running a particular version of Perl: + + # this will parse in older versions of Perl also + if ($^V and $^V gt v5.6.0) { + # new features supported + } + +C<require> and C<use> also have some special magic to support such literals. +They will be interpreted as a version rather than as a module name: + + require v5.6.0; # croak if $^V lt v5.6.0 + use v5.6.0; # same, but croaks at compile-time + +Alternatively, the C<v> may be omitted if there is more than one dot: + + require 5.6.0; + use 5.6.0; + +Also, C<sprintf> and C<printf> support the Perl-specific format flag C<%v> +to print ordinals of characters in arbitrary strings: + + printf "v%vd", $^V; # prints current version, such as "v5.5.650" + printf "%*vX", ":", $addr; # formats IPv6 address + printf "%*vb", " ", $bits; # displays bitstring + +See L<perldata/"Scalar value constructors"> for additional information. + +=head2 Improved Perl version numbering system + +Beginning with Perl version 5.6.0, the version number convention has been +changed to a "dotted integer" scheme that is more commonly found in open +source projects. + +Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc. +The next development series following v5.6.0 will be numbered v5.7.x, +beginning with v5.7.0, and the next major production release following +v5.6.0 will be v5.8.0. + +The English module now sets $PERL_VERSION to $^V (a string value) rather +than C<$]> (a numeric value). (This is a potential incompatibility. +Send us a report via perlbug if you are affected by this.) + +The v1.2.3 syntax is also now legal in Perl. +See L<Support for strings represented as a vector of ordinals> for more on that. + +To cope with the new versioning system's use of at least three significant +digits for each version component, the method used for incrementing the +subversion number has also changed slightly. We assume that versions older +than v5.6.0 have been incrementing the subversion component in multiples of +10. Versions after v5.6.0 will increment them by 1. Thus, using the new +notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance +version following v5.6.0 will be v5.6.1 (which should be read as being +equivalent to a floating point value of 5.006_001 in the older format, +stored in C<$]>). + +=head2 New syntax for declaring subroutine attributes + +Formerly, if you wanted to mark a subroutine as being a method call or +as requiring an automatic lock() when it is entered, you had to declare +that with a C<use attrs> pragma in the body of the subroutine. +That can now be accomplished with declaration syntax, like this: + + sub mymethod : locked method ; + ... + sub mymethod : locked method { + ... + } + + sub othermethod :locked :method ; + ... + sub othermethod :locked :method { + ... + } + + +(Note how only the first C<:> is mandatory, and whitespace surrounding +the C<:> is optional.) + +F<AutoSplit.pm> and F<SelfLoader.pm> have been updated to keep the attributes +with the stubs they provide. See L<attributes>. + +=head2 File and directory handles can be autovivified + +Similar to how constructs such as C<< $x->[0] >> autovivify a reference, +handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(), +socket(), and accept()) now autovivify a file or directory handle +if the handle passed to them is an uninitialized scalar variable. This +allows the constructs such as C<open(my $fh, ...)> and C<open(local $fh,...)> +to be used to create filehandles that will conveniently be closed +automatically when the scope ends, provided there are no other references +to them. This largely eliminates the need for typeglobs when opening +filehandles that must be passed around, as in the following example: + + sub myopen { + open my $fh, "@_" + or die "Can't open '@_': $!"; + return $fh; + } + + { + my $f = myopen("</etc/motd"); + print <$f>; + # $f implicitly closed here + } + +=head2 open() with more than two arguments + +If open() is passed three arguments instead of two, the second argument +is used as the mode and the third argument is taken to be the file name. +This is primarily useful for protecting against unintended magic behavior +of the traditional two-argument form. See L<perlfunc/open>. + +=head2 64-bit support + +Any platform that has 64-bit integers either + + (1) natively as longs or ints + (2) via special compiler flags + (3) using long long or int64_t + +is able to use "quads" (64-bit integers) as follows: + +=over 4 + +=item * + +constants (decimal, hexadecimal, octal, binary) in the code + +=item * + +arguments to oct() and hex() + +=item * + +arguments to print(), printf() and sprintf() (flag prefixes ll, L, q) + +=item * + +printed as such + +=item * + +pack() and unpack() "q" and "Q" formats + +=item * + +in basic arithmetics: + - * / % (NOTE: operating close to the limits +of the integer values may produce surprising results) + +=item * + +in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced +to be 32 bits wide but now operate on the full native width.) + +=item * + +vec() + +=back + +Note that unless you have the case (a) you will have to configure +and compile Perl using the -Duse64bitint Configure flag. + + NOTE: The Configure flags -Duselonglong and -Duse64bits have been + deprecated. Use -Duse64bitint instead. + +There are actually two modes of 64-bitness: the first one is achieved +using Configure -Duse64bitint and the second one using Configure +-Duse64bitall. The difference is that the first one is minimal and +the second one maximal. The first works in more places than the second. + +The C<use64bitint> does only as much as is required to get 64-bit +integers into Perl (this may mean, for example, using "long longs") +while your memory may still be limited to 2 gigabytes (because your +pointers could still be 32-bit). Note that the name C<64bitint> does +not imply that your C compiler will be using 64-bit C<int>s (it might, +but it doesn't have to): the C<use64bitint> means that you will be +able to have 64 bits wide scalar values. + +The C<use64bitall> goes all the way by attempting to switch also +integers (if it can), longs (and pointers) to being 64-bit. This may +create an even more binary incompatible Perl than -Duse64bitint: the +resulting executable may not run at all in a 32-bit box, or you may +have to reboot/reconfigure/rebuild your operating system to be 64-bit +aware. + +Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint +nor -Duse64bitall. + +Last but not least: note that due to Perl's habit of always using +floating point numbers, the quads are still not true integers. +When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned, +-9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they +are silently promoted to floating point numbers, after which they will +start losing precision (in their lower digits). + + NOTE: 64-bit support is still experimental on most platforms. + Existing support only covers the LP64 data model. In particular, the + LLP64 data model is not yet supported. 64-bit libraries and system + APIs on many platforms have not stabilized--your mileage may vary. + +=head2 Large file support + +If you have filesystems that support "large files" (files larger than +2 gigabytes), you may now also be able to create and access them from +Perl. + + NOTE: The default action is to enable large file support, if + available on the platform. + +If the large file support is on, and you have a Fcntl constant +O_LARGEFILE, the O_LARGEFILE is automatically added to the flags +of sysopen(). + +Beware that unless your filesystem also supports "sparse files" seeking +to umpteen petabytes may be inadvisable. + +Note that in addition to requiring a proper file system to do large +files you may also need to adjust your per-process (or your +per-system, or per-process-group, or per-user-group) maximum filesize +limits before running Perl scripts that try to handle large files, +especially if you intend to write such files. + +Finally, in addition to your process/process group maximum filesize +limits, you may have quota limits on your filesystems that stop you +(your user id or your user group id) from using large files. + +Adjusting your process/user/group/file system/operating system limits +is outside the scope of Perl core language. For process limits, you +may try increasing the limits using your shell's limits/limit/ulimit +command before running Perl. The BSD::Resource extension (not +included with the standard Perl distribution) may also be of use, it +offers the getrlimit/setrlimit interface that can be used to adjust +process resource usage limits, including the maximum filesize limit. + +=head2 Long doubles + +In some systems you may be able to use long doubles to enhance the +range and precision of your double precision floating point numbers +(that is, Perl's numbers). Use Configure -Duselongdouble to enable +this support (if it is available). + +=head2 "more bits" + +You can "Configure -Dusemorebits" to turn on both the 64-bit support +and the long double support. + +=head2 Enhanced support for sort() subroutines + +Perl subroutines with a prototype of C<($$)>, and XSUBs in general, can +now be used as sort subroutines. In either case, the two elements to +be compared are passed as normal parameters in @_. See L<perlfunc/sort>. + +For unprototyped sort subroutines, the historical behavior of passing +the elements to be compared as the global variables $a and $b remains +unchanged. + +=head2 C<sort $coderef @foo> allowed + +sort() did not accept a subroutine reference as the comparison +function in earlier versions. This is now permitted. + +=head2 File globbing implemented internally + +Perl now uses the File::Glob implementation of the glob() operator +automatically. This avoids using an external csh process and the +problems associated with it. + + NOTE: This is currently an experimental feature. Interfaces and + implementation are subject to change. + +=item Support for CHECK blocks + +In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>, +subroutines named C<CHECK> are now special. These are queued up during +compilation and behave similar to END blocks, except they are called at +the end of compilation rather than at the end of execution. They cannot +be called directly. + +=head2 POSIX character class syntax [: :] supported + +For example to match alphabetic characters use /[[:alpha:]]/. +See L<perlre> for details. + +=item Better pseudo-random number generator + +In 5.005_0x and earlier, perl's rand() function used the C library +rand(3) function. As of 5.005_52, Configure tests for drand48(), +random(), and rand() (in that order) and picks the first one it finds. + +These changes should result in better random numbers from rand(). + +=head2 Improved C<qw//> operator + +The C<qw//> operator is now evaluated at compile time into a true list +instead of being replaced with a run time call to C<split()>. This +removes the confusing misbehaviour of C<qw//> in scalar context, which +had inherited that behaviour from split(). + +Thus: + + $foo = ($bar) = qw(a b c); print "$foo|$bar\n"; + +now correctly prints "3|a", instead of "2|a". + +=item Better worst-case behavior of hashes + +Small changes in the hashing algorithm have been implemented in +order to improve the distribution of lower order bits in the +hashed value. This is expected to yield better performance on +keys that are repeated sequences. + +=head2 pack() format 'Z' supported + +The new format type 'Z' is useful for packing and unpacking null-terminated +strings. See L<perlfunc/"pack">. + +=head2 pack() format modifier '!' supported + +The new format type modifier '!' is useful for packing and unpacking +native shorts, ints, and longs. See L<perlfunc/"pack">. + +=head2 pack() and unpack() support counted strings + +The template character '/' can be used to specify a counted string +type to be packed or unpacked. See L<perlfunc/"pack">. + +=head2 Comments in pack() templates + +The '#' character in a template introduces a comment up to +end of the line. This facilitates documentation of pack() +templates. + +=head2 Weak references + +In previous versions of Perl, you couldn't cache objects so as +to allow them to be deleted if the last reference from outside +the cache is deleted. The reference in the cache would hold a +reference count on the object and the objects would never be +destroyed. + +Another familiar problem is with circular references. When an +object references itself, its reference count would never go +down to zero, and it would not get destroyed until the program +is about to exit. + +Weak references solve this by allowing you to "weaken" any +reference, that is, make it not count towards the reference count. +When the last non-weak reference to an object is deleted, the object +is destroyed and all the weak references to the object are +automatically undef-ed. + +To use this feature, you need the WeakRef package from CPAN, which +contains additional documentation. + + NOTE: This is an experimental feature. Details are subject to change. + +=head2 Binary numbers supported + +Binary numbers are now supported as literals, in s?printf formats, and +C<oct()>: + + $answer = 0b101010; + printf "The answer is: %b\n", oct("0b101010"); + +=head2 Lvalue subroutines + +Subroutines can now return modifiable lvalues. +See L<perlsub/"Lvalue subroutines">. + + NOTE: This is an experimental feature. Details are subject to change. + +=head2 Some arrows may be omitted in calls through references + +Perl now allows the arrow to be omitted in many constructs +involving subroutine calls through references. For example, +C<< $foo[10]->('foo') >> may now be written C<$foo[10]('foo')>. +This is rather similar to how the arrow may be omitted from +C<< $foo[10]->{'foo'} >>. Note however, that the arrow is still +required for C<< foo(10)->('bar') >>. + +=head2 Boolean assignment operators are legal lvalues + +Constructs such as C<($a ||= 2) += 1> are now allowed. + +=head2 exists() is supported on subroutine names + +The exists() builtin now works on subroutine names. A subroutine +is considered to exist if it has been declared (even if implicitly). +See L<perlfunc/exists> for examples. + +=head2 exists() and delete() are supported on array elements + +The exists() and delete() builtins now work on simple arrays as well. +The behavior is similar to that on hash elements. + +exists() can be used to check whether an array element has been +initialized. This avoids autovivifying array elements that don't exist. +If the array is tied, the EXISTS() method in the corresponding tied +package will be invoked. + +delete() may be used to remove an element from the array and return +it. The array element at that position returns to its uninitialized +state, so that testing for the same element with exists() will return +false. If the element happens to be the one at the end, the size of +the array also shrinks up to the highest element that tests true for +exists(), or 0 if none such is found. If the array is tied, the DELETE() +method in the corresponding tied package will be invoked. + +See L<perlfunc/exists> and L<perlfunc/delete> for examples. + +=head2 Pseudo-hashes work better + +Dereferencing some types of reference values in a pseudo-hash, +such as C<< $ph->{foo}[1] >>, was accidentally disallowed. This has +been corrected. + +When applied to a pseudo-hash element, exists() now reports whether +the specified value exists, not merely if the key is valid. + +delete() now works on pseudo-hashes. When given a pseudo-hash element +or slice it deletes the values corresponding to the keys (but not the keys +themselves). See L<perlref/"Pseudo-hashes: Using an array as a hash">. + +Pseudo-hash slices with constant keys are now optimized to array lookups +at compile-time. + +List assignments to pseudo-hash slices are now supported. + +The C<fields> pragma now provides ways to create pseudo-hashes, via +fields::new() and fields::phash(). See L<fields>. + + NOTE: The pseudo-hash data type continues to be experimental. + Limiting oneself to the interface elements provided by the + fields pragma will provide protection from any future changes. + +=head2 Automatic flushing of output buffers + +fork(), exec(), system(), qx//, and pipe open()s now flush buffers +of all files opened for output when the operation was attempted. This +mostly eliminates confusing buffering mishaps suffered by users unaware +of how Perl internally handles I/O. + +This is not supported on some platforms like Solaris where a suitably +correct implementation of fflush(NULL) isn't available. + +=head2 Better diagnostics on meaningless filehandle operations + +Constructs such as C<< open(<FH>) >> and C<< close(<FH>) >> +are compile time errors. Attempting to read from filehandles that +were opened only for writing will now produce warnings (just as +writing to read-only filehandles does). + +=head2 Where possible, buffered data discarded from duped input filehandle + +C<< open(NEW, "<&OLD") >> now attempts to discard any data that +was previously read and buffered in C<OLD> before duping the handle. +On platforms where doing this is allowed, the next read operation +on C<NEW> will return the same data as the corresponding operation +on C<OLD>. Formerly, it would have returned the data from the start +of the following disk block instead. + +=head2 eof() has the same old magic as <> + +C<eof()> would return true if no attempt to read from C<< <> >> had +yet been made. C<eof()> has been changed to have a little magic of its +own, it now opens the C<< <> >> files. + +=head2 binmode() can be used to set :crlf and :raw modes + +binmode() now accepts a second argument that specifies a discipline +for the handle in question. The two pseudo-disciplines ":raw" and +":crlf" are currently supported on DOS-derivative platforms. +See L<perlfunc/"binmode"> and L<open>. + +=head2 C<-T> filetest recognizes UTF-8 encoded files as "text" + +The algorithm used for the C<-T> filetest has been enhanced to +correctly identify UTF-8 content as "text". + +=head2 system(), backticks and pipe open now reflect exec() failure + +On Unix and similar platforms, system(), qx() and open(FOO, "cmd |") +etc., are implemented via fork() and exec(). When the underlying +exec() fails, earlier versions did not report the error properly, +since the exec() happened to be in a different process. + +The child process now communicates with the parent about the +error in launching the external command, which allows these +constructs to return with their usual error value and set $!. + +=head2 Improved diagnostics + +Line numbers are no longer suppressed (under most likely circumstances) +during the global destruction phase. + +Diagnostics emitted from code running in threads other than the main +thread are now accompanied by the thread ID. + +Embedded null characters in diagnostics now actually show up. They +used to truncate the message in prior versions. + +$foo::a and $foo::b are now exempt from "possible typo" warnings only +if sort() is encountered in package C<foo>. + +Unrecognized alphabetic escapes encountered when parsing quote +constructs now generate a warning, since they may take on new +semantics in later versions of Perl. + +Many diagnostics now report the internal operation in which the warning +was provoked, like so: + + Use of uninitialized value in concatenation (.) at (eval 1) line 1. + Use of uninitialized value in print at (eval 1) line 1. + +Diagnostics that occur within eval may also report the file and line +number where the eval is located, in addition to the eval sequence +number and the line number within the evaluated text itself. For +example: + + Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF + +=head2 Diagnostics follow STDERR + +Diagnostic output now goes to whichever file the C<STDERR> handle +is pointing at, instead of always going to the underlying C runtime +library's C<stderr>. + +=item More consistent close-on-exec behavior + +On systems that support a close-on-exec flag on filehandles, the +flag is now set for any handles created by pipe(), socketpair(), +socket(), and accept(), if that is warranted by the value of $^F +that may be in effect. Earlier versions neglected to set the flag +for handles created with these operators. See L<perlfunc/pipe>, +L<perlfunc/socketpair>, L<perlfunc/socket>, L<perlfunc/accept>, +and L<perlvar/$^F>. + +=head2 syswrite() ease-of-use + +The length argument of C<syswrite()> has become optional. + +=head2 Better syntax checks on parenthesized unary operators + +Expressions such as: + + print defined(&foo,&bar,&baz); + print uc("foo","bar","baz"); + undef($foo,&bar); + +used to be accidentally allowed in earlier versions, and produced +unpredictable behaviour. Some produced ancillary warnings +when used in this way; others silently did the wrong thing. + +The parenthesized forms of most unary operators that expect a single +argument now ensure that they are not called with more than one +argument, making the cases shown above syntax errors. The usual +behaviour of: + + print defined &foo, &bar, &baz; + print uc "foo", "bar", "baz"; + undef $foo, &bar; + +remains unchanged. See L<perlop>. + +=head2 Bit operators support full native integer width + +The bit operators (& | ^ ~ << >>) now operate on the full native +integral width (the exact size of which is available in $Config{ivsize}). +For example, if your platform is either natively 64-bit or if Perl +has been configured to use 64-bit integers, these operations apply +to 8 bytes (as opposed to 4 bytes on 32-bit platforms). +For portability, be sure to mask off the excess bits in the result of +unary C<~>, e.g., C<~$x & 0xffffffff>. + +=head2 Improved security features + +More potentially unsafe operations taint their results for improved +security. + +The C<passwd> and C<shell> fields returned by the getpwent(), getpwnam(), +and getpwuid() are now tainted, because the user can affect their own +encrypted password and login shell. + +The variable modified by shmread(), and messages returned by msgrcv() +(and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted, +because other untrusted processes can modify messages and shared memory +segments for their own nefarious purposes. + +=item More functional bareword prototype (*) + +Bareword prototypes have been rationalized to enable them to be used +to override builtins that accept barewords and interpret them in +a special way, such as C<require> or C<do>. + +Arguments prototyped as C<*> will now be visible within the subroutine +as either a simple scalar or as a reference to a typeglob. +See L<perlsub/Prototypes>. + +=head2 C<require> and C<do> may be overridden + +C<require> and C<do 'file'> operations may be overridden locally +by importing subroutines of the same name into the current package +(or globally by importing them into the CORE::GLOBAL:: namespace). +Overriding C<require> will also affect C<use>, provided the override +is visible at compile-time. +See L<perlsub/"Overriding Built-in Functions">. + +=head2 $^X variables may now have names longer than one character + +Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax +error. Now variable names that begin with a control character may be +arbitrarily long. However, for compatibility reasons, these variables +I<must> be written with explicit braces, as C<${^XY}> for example. +C<${^XYZ}> is synonymous with ${"\cXYZ"}. Variable names with more +than one control character, such as C<${^XY^Z}>, are illegal. + +The old syntax has not changed. As before, `^X' may be either a +literal control-X character or the two-character sequence `caret' plus +`X'. When braces are omitted, the variable name stops after the +control character. Thus C<"$^XYZ"> continues to be synonymous with +C<$^X . "YZ"> as before. + +As before, lexical variables may not have names beginning with control +characters. As before, variables whose names begin with a control +character are always forced to be in package `main'. All such variables +are reserved for future extensions, except those that begin with +C<^_>, which may be used by user programs and are guaranteed not to +acquire special meaning in any future version of Perl. + +=head2 New variable $^C reflects C<-c> switch + +C<$^C> has a boolean value that reflects whether perl is being run +in compile-only mode (i.e. via the C<-c> switch). Since +BEGIN blocks are executed under such conditions, this variable +enables perl code to determine whether actions that make sense +only during normal running are warranted. See L<perlvar>. + +=head2 New variable $^V contains Perl version as a string + +C<$^V> contains the Perl version number as a string composed of +characters whose ordinals match the version numbers, i.e. v5.6.0. +This may be used in string comparisons. + +See C<Support for strings represented as a vector of ordinals> for an +example. + +=head2 Optional Y2K warnings + +If Perl is built with the cpp macro C<PERL_Y2KWARN> defined, +it emits optional warnings when concatenating the number 19 +with another number. + +This behavior must be specifically enabled when running Configure. +See F<INSTALL> and F<README.Y2K>. + +=head1 Modules and Pragmata + +=head2 Modules + +=over 4 + +=item attributes + +While used internally by Perl as a pragma, this module also +provides a way to fetch subroutine and variable attributes. +See L<attributes>. + +=item B + +The Perl Compiler suite has been extensively reworked for this +release. More of the standard Perl testsuite passes when run +under the Compiler, but there is still a significant way to +go to achieve production quality compiled executables. + + NOTE: The Compiler suite remains highly experimental. The + generated code may not be correct, even when it manages to execute + without errors. + +=item Benchmark + +Overall, Benchmark results exhibit lower average error and better timing +accuracy. + +You can now run tests for I<n> seconds instead of guessing the right +number of tests to run: e.g., timethese(-5, ...) will run each +code for at least 5 CPU seconds. Zero as the "number of repetitions" +means "for at least 3 CPU seconds". The output format has also +changed. For example: + + use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}}) + +will now output something like this: + + Benchmark: running a, b, each for at least 5 CPU seconds... + a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516) + b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686) + +New features: "each for at least N CPU seconds...", "wallclock secs", +and the "@ operations/CPU second (n=operations)". + +timethese() now returns a reference to a hash of Benchmark objects containing +the test results, keyed on the names of the tests. + +timethis() now returns the iterations field in the Benchmark result object +instead of 0. + +timethese(), timethis(), and the new cmpthese() (see below) can also take +a format specifier of 'none' to suppress output. + +A new function countit() is just like timeit() except that it takes a +TIME instead of a COUNT. + +A new function cmpthese() prints a chart comparing the results of each test +returned from a timethese() call. For each possible pair of tests, the +percentage speed difference (iters/sec or seconds/iter) is shown. + +For other details, see L<Benchmark>. + +=item ByteLoader + +The ByteLoader is a dedicated extension to generate and run +Perl bytecode. See L<ByteLoader>. + +=item constant + +References can now be used. + +The new version also allows a leading underscore in constant names, but +disallows a double leading underscore (as in "__LINE__"). Some other names +are disallowed or warned against, including BEGIN, END, etc. Some names +which were forced into main:: used to fail silently in some cases; now they're +fatal (outside of main::) and an optional warning (inside of main::). +The ability to detect whether a constant had been set with a given name has +been added. + +See L<constant>. + +=item charnames + +This pragma implements the C<\N> string escape. See L<charnames>. + +=item Data::Dumper + +A C<Maxdepth> setting can be specified to avoid venturing +too deeply into deep data structures. See L<Data::Dumper>. + +The XSUB implementation of Dump() is now automatically called if the +C<Useqq> setting is not in use. + +Dumping C<qr//> objects works correctly. + +=item DB + +C<DB> is an experimental module that exposes a clean abstraction +to Perl's debugging API. + +=item DB_File + +DB_File can now be built with Berkeley DB versions 1, 2 or 3. +See C<ext/DB_File/Changes>. + +=item Devel::DProf + +Devel::DProf, a Perl source code profiler has been added. See +L<Devel::DProf> and L<dprofpp>. + +=item Devel::Peek + +The Devel::Peek module provides access to the internal representation +of Perl variables and data. It is a data debugging tool for the XS programmer. + +=item Dumpvalue + +The Dumpvalue module provides screen dumps of Perl data. + +=item DynaLoader + +DynaLoader now supports a dl_unload_file() function on platforms that +support unloading shared objects using dlclose(). + +Perl can also optionally arrange to unload all extension shared objects +loaded by Perl. To enable this, build Perl with the Configure option +C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>. (This maybe useful if you are +using Apache with mod_perl.) + +=item English + +$PERL_VERSION now stands for C<$^V> (a string value) rather than for C<$]> +(a numeric value). + +=item Env + +Env now supports accessing environment variables like PATH as array +variables. + +=item Fcntl + +More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for +large file (more than 4GB) access (NOTE: the O_LARGEFILE is +automatically added to sysopen() flags if large file support has been +configured, as is the default), Free/Net/OpenBSD locking behaviour +flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined +mask of O_RDONLY, O_WRONLY, and O_RDWR. The seek()/sysseek() +constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the +C<:seek> tag. The chmod()/stat() S_IF* constants and S_IS* functions +are available via the C<:mode> tag. + +=item File::Compare + +A compare_text() function has been added, which allows custom +comparison functions. See L<File::Compare>. + +=item File::Find + +File::Find now works correctly when the wanted() function is either +autoloaded or is a symbolic reference. + +A bug that caused File::Find to lose track of the working directory +when pruning top-level directories has been fixed. + +File::Find now also supports several other options to control its +behavior. It can follow symbolic links if the C<follow> option is +specified. Enabling the C<no_chdir> option will make File::Find skip +changing the current directory when walking directories. The C<untaint> +flag can be useful when running with taint checks enabled. + +See L<File::Find>. + +=item File::Glob + +This extension implements BSD-style file globbing. By default, +it will also be used for the internal implementation of the glob() +operator. See L<File::Glob>. + +=item File::Spec + +New methods have been added to the File::Spec module: devnull() returns +the name of the null device (/dev/null on Unix) and tmpdir() the name of +the temp directory (normally /tmp on Unix). There are now also methods +to convert between absolute and relative filenames: abs2rel() and +rel2abs(). For compatibility with operating systems that specify volume +names in file paths, the splitpath(), splitdir(), and catdir() methods +have been added. + +=item File::Spec::Functions + +The new File::Spec::Functions modules provides a function interface +to the File::Spec module. Allows shorthand + + $fullname = catfile($dir1, $dir2, $file); + +instead of + + $fullname = File::Spec->catfile($dir1, $dir2, $file); + +=item Getopt::Long + +Getopt::Long licensing has changed to allow the Perl Artistic License +as well as the GPL. It used to be GPL only, which got in the way of +non-GPL applications that wanted to use Getopt::Long. + +Getopt::Long encourages the use of Pod::Usage to produce help +messages. For example: + + use Getopt::Long; + use Pod::Usage; + my $man = 0; + my $help = 0; + GetOptions('help|?' => \$help, man => \$man) or pod2usage(2); + pod2usage(1) if $help; + pod2usage(-exitstatus => 0, -verbose => 2) if $man; + + __END__ + + =head1 NAME + + sample - Using GetOpt::Long and Pod::Usage + + =head1 SYNOPSIS + + sample [options] [file ...] + + Options: + -help brief help message + -man full documentation + + =head1 OPTIONS + + =over 8 + + =item B<-help> + + Print a brief help message and exits. + + =item B<-man> + + Prints the manual page and exits. + + =back + + =head1 DESCRIPTION + + B<This program> will read the given input file(s) and do something + useful with the contents thereof. + + =cut + +See L<Pod::Usage> for details. + +A bug that prevented the non-option call-back <> from being +specified as the first argument has been fixed. + +To specify the characters < and > as option starters, use ><. Note, +however, that changing option starters is strongly deprecated. + +=item IO + +write() and syswrite() will now accept a single-argument +form of the call, for consistency with Perl's syswrite(). + +You can now create a TCP-based IO::Socket::INET without forcing +a connect attempt. This allows you to configure its options +(like making it non-blocking) and then call connect() manually. + +A bug that prevented the IO::Socket::protocol() accessor +from ever returning the correct value has been corrected. + +IO::Socket::connect now uses non-blocking IO instead of alarm() +to do connect timeouts. + +IO::Socket::accept now uses select() instead of alarm() for doing +timeouts. + +IO::Socket::INET->new now sets $! correctly on failure. $@ is +still set for backwards compatibility. + +=item JPL + +Java Perl Lingo is now distributed with Perl. See jpl/README +for more information. + +=item lib + +C<use lib> now weeds out any trailing duplicate entries. +C<no lib> removes all named entries. + +=item Math::BigInt + +The bitwise operations C<<< << >>>, C<<< >> >>>, C<&>, C<|>, +and C<~> are now supported on bigints. + +=item Math::Complex + +The accessor methods Re, Im, arg, abs, rho, and theta can now also +act as mutators (accessor $z->Re(), mutator $z->Re(3)). + +The class method C<display_format> and the corresponding object method +C<display_format>, in addition to accepting just one argument, now can +also accept a parameter hash. Recognized keys of a parameter hash are +C<"style">, which corresponds to the old one parameter case, and two +new parameters: C<"format">, which is a printf()-style format string +(defaults usually to C<"%.15g">, you can revert to the default by +setting the format string to C<undef>) used for both parts of a +complex number, and C<"polar_pretty_print"> (defaults to true), +which controls whether an attempt is made to try to recognize small +multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a +polar complex number. + +The potentially disruptive change is that in list context both methods +now I<return the parameter hash>, instead of only the value of the +C<"style"> parameter. + +=item Math::Trig + +A little bit of radial trigonometry (cylindrical and spherical), +radial coordinate conversions, and the great circle distance were added. + +=item Pod::Parser, Pod::InputObjects + +Pod::Parser is a base class for parsing and selecting sections of +pod documentation from an input stream. This module takes care of +identifying pod paragraphs and commands in the input and hands off the +parsed paragraphs and commands to user-defined methods which are free +to interpret or translate them as they see fit. + +Pod::InputObjects defines some input objects needed by Pod::Parser, and +for advanced users of Pod::Parser that need more about a command besides +its name and text. + +As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned +"base parser code" recommended for use by all pod2xxx translators. +Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted +to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already +underway. For any questions or comments about pod parsing and translating +issues and utilities, please use the pod-people@perl.org mailing list. + +For further information, please see L<Pod::Parser> and L<Pod::InputObjects>. + +=item Pod::Checker, podchecker + +This utility checks pod files for correct syntax, according to +L<perlpod>. Obvious errors are flagged as such, while warnings are +printed for mistakes that can be handled gracefully. The checklist is +not complete yet. See L<Pod::Checker>. + +=item Pod::ParseUtils, Pod::Find + +These modules provide a set of gizmos that are useful mainly for pod +translators. L<Pod::Find|Pod::Find> traverses directory structures and +returns found pod files, along with their canonical names (like +C<File::Spec::Unix>). L<Pod::ParseUtils|Pod::ParseUtils> contains +B<Pod::List> (useful for storing pod list information), B<Pod::Hyperlink> +(for parsing the contents of C<LE<lt>E<gt>> sequences) and B<Pod::Cache> +(for caching information about pod files, e.g., link nodes). + +=item Pod::Select, podselect + +Pod::Select is a subclass of Pod::Parser which provides a function +named "podselect()" to filter out user-specified sections of raw pod +documentation from an input stream. podselect is a script that provides +access to Pod::Select from other scripts to be used as a filter. +See L<Pod::Select>. + +=item Pod::Usage, pod2usage + +Pod::Usage provides the function "pod2usage()" to print usage messages for +a Perl script based on its embedded pod documentation. The pod2usage() +function is generally useful to all script authors since it lets them +write and maintain a single source (the pods) for documentation, thus +removing the need to create and maintain redundant usage message text +consisting of information already in the pods. + +There is also a pod2usage script which can be used from other kinds of +scripts to print usage messages from pods (even for non-Perl scripts +with pods embedded in comments). + +For details and examples, please see L<Pod::Usage>. + +=item Pod::Text and Pod::Man + +Pod::Text has been rewritten to use Pod::Parser. While pod2text() is +still available for backwards compatibility, the module now has a new +preferred interface. See L<Pod::Text> for the details. The new Pod::Text +module is easily subclassed for tweaks to the output, and two such +subclasses (Pod::Text::Termcap for man-page-style bold and underlining +using termcap information, and Pod::Text::Color for markup with ANSI color +sequences) are now standard. + +pod2man has been turned into a module, Pod::Man, which also uses +Pod::Parser. In the process, several outstanding bugs related to quotes +in section headers, quoting of code escapes, and nested lists have been +fixed. pod2man is now a wrapper script around this module. + +=item SDBM_File + +An EXISTS method has been added to this module (and sdbm_exists() has +been added to the underlying sdbm library), so one can now call exists +on an SDBM_File tied hash and get the correct result, rather than a +runtime error. + +A bug that may have caused data loss when more than one disk block +happens to be read from the database in a single FETCH() has been +fixed. + +=item Sys::Syslog + +Sys::Syslog now uses XSUBs to access facilities from syslog.h so it +no longer requires syslog.ph to exist. + +=item Sys::Hostname + +Sys::Hostname now uses XSUBs to call the C library's gethostname() or +uname() if they exist. + +=item Term::ANSIColor + +Term::ANSIColor is a very simple module to provide easy and readable +access to the ANSI color and highlighting escape sequences, supported by +most ANSI terminal emulators. It is now included standard. + +=item Time::Local + +The timelocal() and timegm() functions used to silently return bogus +results when the date fell outside the machine's integer range. They +now consistently croak() if the date falls in an unsupported range. + +=item Win32 + +The error return value in list context has been changed for all functions +that return a list of values. Previously these functions returned a list +with a single element C<undef> if an error occurred. Now these functions +return the empty list in these situations. This applies to the following +functions: + + Win32::FsType + Win32::GetOSVersion + +The remaining functions are unchanged and continue to return C<undef> on +error even in list context. + +The Win32::SetLastError(ERROR) function has been added as a complement +to the Win32::GetLastError() function. + +The new Win32::GetFullPathName(FILENAME) returns the full absolute +pathname for FILENAME in scalar context. In list context it returns +a two-element list containing the fully qualified directory name and +the filename. See L<Win32>. + +=item XSLoader + +The XSLoader extension is a simpler alternative to DynaLoader. +See L<XSLoader>. + +=item DBM Filters + +A new feature called "DBM Filters" has been added to all the +DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File. +DBM Filters add four new methods to each DBM module: + + filter_store_key + filter_store_value + filter_fetch_key + filter_fetch_value + +These can be used to filter key-value pairs before the pairs are +written to the database or just after they are read from the database. +See L<perldbmfilter> for further information. + +=back + +=head2 Pragmata + +C<use attrs> is now obsolete, and is only provided for +backward-compatibility. It's been replaced by the C<sub : attributes> +syntax. See L<perlsub/"Subroutine Attributes"> and L<attributes>. + +Lexical warnings pragma, C<use warnings;>, to control optional warnings. +See L<perllexwarn>. + +C<use filetest> to control the behaviour of filetests (C<-r> C<-w> +...). Currently only one subpragma implemented, "use filetest +'access';", that uses access(2) or equivalent to check permissions +instead of using stat(2) as usual. This matters in filesystems +where there are ACLs (access control lists): the stat(2) might lie, +but access(2) knows better. + +The C<open> pragma can be used to specify default disciplines for +handle constructors (e.g. open()) and for qx//. The two +pseudo-disciplines C<:raw> and C<:crlf> are currently supported on +DOS-derivative platforms (i.e. where binmode is not a no-op). +See also L</"binmode() can be used to set :crlf and :raw modes">. + +=head1 Utility Changes + +=head2 dprofpp + +C<dprofpp> is used to display profile data generated using C<Devel::DProf>. +See L<dprofpp>. + +=head2 find2perl + +The C<find2perl> utility now uses the enhanced features of the File::Find +module. The -depth and -follow options are supported. Pod documentation +is also included in the script. + +=head2 h2xs + +The C<h2xs> tool can now work in conjunction with C<C::Scan> (available +from CPAN) to automatically parse real-life header files. The C<-M>, +C<-a>, C<-k>, and C<-o> options are new. + +=head2 perlcc + +C<perlcc> now supports the C and Bytecode backends. By default, +it generates output from the simple C backend rather than the +optimized C backend. + +Support for non-Unix platforms has been improved. + +=head2 perldoc + +C<perldoc> has been reworked to avoid possible security holes. +It will not by default let itself be run as the superuser, but you +may still use the B<-U> switch to try to make it drop privileges +first. + +=head2 The Perl Debugger + +Many bug fixes and enhancements were added to F<perl5db.pl>, the +Perl debugger. The help documentation was rearranged. New commands +include C<< < ? >>, C<< > ? >>, and C<< { ? >> to list out current +actions, C<man I<docpage>> to run your doc viewer on some perl +docset, and support for quoted options. The help information was +rearranged, and should be viewable once again if you're using B<less> +as your pager. A serious security hole was plugged--you should +immediately remove all older versions of the Perl debugger as +installed in previous releases, all the way back to perl3, from +your system to avoid being bitten by this. + +=head1 Improved Documentation + +Many of the platform-specific README files are now part of the perl +installation. See L<perl> for the complete list. + +=over 4 + +=item perlapi.pod + +The official list of public Perl API functions. + +=item perlboot.pod + +A tutorial for beginners on object-oriented Perl. + +=item perlcompile.pod + +An introduction to using the Perl Compiler suite. + +=item perldbmfilter.pod + +A howto document on using the DBM filter facility. + +=item perldebug.pod + +All material unrelated to running the Perl debugger, plus all +low-level guts-like details that risked crushing the casual user +of the debugger, have been relocated from the old manpage to the +next entry below. + +=item perldebguts.pod + +This new manpage contains excessively low-level material not related +to the Perl debugger, but slightly related to debugging Perl itself. +It also contains some arcane internal details of how the debugging +process works that may only be of interest to developers of Perl +debuggers. + +=item perlfork.pod + +Notes on the fork() emulation currently available for the Windows platform. + +=item perlfilter.pod + +An introduction to writing Perl source filters. + +=item perlhack.pod + +Some guidelines for hacking the Perl source code. + +=item perlintern.pod + +A list of internal functions in the Perl source code. +(List is currently empty.) + +=item perllexwarn.pod + +Introduction and reference information about lexically scoped +warning categories. + +=item perlnumber.pod + +Detailed information about numbers as they are represented in Perl. + +=item perlopentut.pod + +A tutorial on using open() effectively. + +=item perlreftut.pod + +A tutorial that introduces the essentials of references. + +=item perltootc.pod + +A tutorial on managing class data for object modules. + +=item perltodo.pod + +Discussion of the most often wanted features that may someday be +supported in Perl. + +=item perlunicode.pod + +An introduction to Unicode support features in Perl. + +=back + +=head1 Performance enhancements + +=head2 Simple sort() using { $a <=> $b } and the like are optimized + +Many common sort() operations using a simple inlined block are now +optimized for faster performance. + +=head2 Optimized assignments to lexical variables + +Certain operations in the RHS of assignment statements have been +optimized to directly set the lexical variable on the LHS, +eliminating redundant copying overheads. + +=head2 Faster subroutine calls + +Minor changes in how subroutine calls are handled internally +provide marginal improvements in performance. + +=item delete(), each(), values() and hash iteration are faster + +The hash values returned by delete(), each(), values() and hashes in a +list context are the actual values in the hash, instead of copies. +This results in significantly better performance, because it eliminates +needless copying in most situations. + +=head1 Installation and Configuration Improvements + +=head2 -Dusethreads means something different + +The -Dusethreads flag now enables the experimental interpreter-based thread +support by default. To get the flavor of experimental threads that was in +5.005 instead, you need to run Configure with "-Dusethreads -Duse5005threads". + +As of v5.6.0, interpreter-threads support is still lacking a way to +create new threads from Perl (i.e., C<use Thread;> will not work with +interpreter threads). C<use Thread;> continues to be available when you +specify the -Duse5005threads option to Configure, bugs and all. + + NOTE: Support for threads continues to be an experimental feature. + Interfaces and implementation are subject to sudden and drastic changes. + +=head2 New Configure flags + +The following new flags may be enabled on the Configure command line +by running Configure with C<-Dflag>. + + usemultiplicity + usethreads useithreads (new interpreter threads: no Perl API yet) + usethreads use5005threads (threads as they were in 5.005) + + use64bitint (equal to now deprecated 'use64bits') + use64bitall + + uselongdouble + usemorebits + uselargefiles + usesocks (only SOCKS v5 supported) + +=head2 Threadedness and 64-bitness now more daring + +The Configure options enabling the use of threads and the use of +64-bitness are now more daring in the sense that they no more have an +explicit list of operating systems of known threads/64-bit +capabilities. In other words: if your operating system has the +necessary APIs and datatypes, you should be able just to go ahead and +use them, for threads by Configure -Dusethreads, and for 64 bits +either explicitly by Configure -Duse64bitint or implicitly if your +system has 64-bit wide datatypes. See also L<"64-bit support">. + +=head2 Long Doubles + +Some platforms have "long doubles", floating point numbers of even +larger range than ordinary "doubles". To enable using long doubles for +Perl's scalars, use -Duselongdouble. + +=head2 -Dusemorebits + +You can enable both -Duse64bitint and -Duselongdouble with -Dusemorebits. +See also L<"64-bit support">. + +=head2 -Duselargefiles + +Some platforms support system APIs that are capable of handling large files +(typically, files larger than two gigabytes). Perl will try to use these +APIs if you ask for -Duselargefiles. + +See L<"Large file support"> for more information. + +=head2 installusrbinperl + +You can use "Configure -Uinstallusrbinperl" which causes installperl +to skip installing perl also as /usr/bin/perl. This is useful if you +prefer not to modify /usr/bin for some reason or another but harmful +because many scripts assume to find Perl in /usr/bin/perl. + +=head2 SOCKS support + +You can use "Configure -Dusesocks" which causes Perl to probe +for the SOCKS proxy protocol library (v5, not v4). For more information +on SOCKS, see: + + http://www.socks.nec.com/ + +=head2 C<-A> flag + +You can "post-edit" the Configure variables using the Configure C<-A> +switch. The editing happens immediately after the platform specific +hints files have been processed but before the actual configuration +process starts. Run C<Configure -h> to find out the full C<-A> syntax. + +=head2 Enhanced Installation Directories + +The installation structure has been enriched to improve the support +for maintaining multiple versions of perl, to provide locations for +vendor-supplied modules, scripts, and manpages, and to ease maintenance +of locally-added modules, scripts, and manpages. See the section on +Installation Directories in the INSTALL file for complete details. +For most users building and installing from source, the defaults should +be fine. + +If you previously used C<Configure -Dsitelib> or C<-Dsitearch> to set +special values for library directories, you might wish to consider using +the new C<-Dsiteprefix> setting instead. Also, if you wish to re-use a +config.sh file from an earlier version of perl, you should be sure to +check that Configure makes sensible choices for the new directories. +See INSTALL for complete details. + +=head1 Platform specific changes + +=head2 Supported platforms + +=over 4 + +=item * + +The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread +extension. + +=item * + +GNU/Hurd is now supported. + +=item * + +Rhapsody/Darwin is now supported. + +=item * + +EPOC is now supported (on Psion 5). + +=item * + +The cygwin port (formerly cygwin32) has been greatly improved. + +=back + +=head2 DOS + +=over 4 + +=item * + +Perl now works with djgpp 2.02 (and 2.03 alpha). + +=item * + +Environment variable names are not converted to uppercase any more. + +=item * + +Incorrect exit codes from backticks have been fixed. + +=item * + +This port continues to use its own builtin globbing (not File::Glob). + +=back + +=head2 OS390 (OpenEdition MVS) + +Support for this EBCDIC platform has not been renewed in this release. +There are difficulties in reconciling Perl's standardization on UTF-8 +as its internal representation for characters with the EBCDIC character +set, because the two are incompatible. + +It is unclear whether future versions will renew support for this +platform, but the possibility exists. + +=head2 VMS + +Numerous revisions and extensions to configuration, build, testing, and +installation process to accommodate core changes and VMS-specific options. + +Expand %ENV-handling code to allow runtime mapping to logical names, +CLI symbols, and CRTL environ array. + +Extension of subprocess invocation code to accept filespecs as command +"verbs". + +Add to Perl command line processing the ability to use default file types and +to recognize Unix-style C<2E<gt>&1>. + +Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS. + +Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly. + +Barewords at start of Unix-syntax paths may be treated as text rather than +only as logical names. + +Optional secure translation of several logical names used internally by Perl. + +Miscellaneous bugfixing and porting of new core code to VMS. + +Thanks are gladly extended to the many people who have contributed VMS +patches, testing, and ideas. + +=head2 Win32 + +Perl can now emulate fork() internally, using multiple interpreters running +in different concurrent threads. This support must be enabled at build +time. See L<perlfork> for detailed information. + +When given a pathname that consists only of a drivename, such as C<A:>, +opendir() and stat() now use the current working directory for the drive +rather than the drive root. + +The builtin XSUB functions in the Win32:: namespace are documented. See +L<Win32>. + +$^X now contains the full path name of the running executable. + +A Win32::GetLongPathName() function is provided to complement +Win32::GetFullPathName() and Win32::GetShortPathName(). See L<Win32>. + +POSIX::uname() is supported. + +system(1,...) now returns true process IDs rather than process +handles. kill() accepts any real process id, rather than strictly +return values from system(1,...). + +For better compatibility with Unix, C<kill(0, $pid)> can now be used to +test whether a process exists. + +The C<Shell> module is supported. + +Better support for building Perl under command.com in Windows 95 +has been added. + +Scripts are read in binary mode by default to allow ByteLoader (and +the filter mechanism in general) to work properly. For compatibility, +the DATA filehandle will be set to text mode if a carriage return is +detected at the end of the line containing the __END__ or __DATA__ +token; if not, the DATA filehandle will be left open in binary mode. +Earlier versions always opened the DATA filehandle in text mode. + +The glob() operator is implemented via the C<File::Glob> extension, +which supports glob syntax of the C shell. This increases the flexibility +of the glob() operator, but there may be compatibility issues for +programs that relied on the older globbing syntax. If you want to +preserve compatibility with the older syntax, you might want to run +perl with C<-MFile::DosGlob>. For details and compatibility information, +see L<File::Glob>. + +=head1 Significant bug fixes + +=head2 <HANDLE> on empty files + +With C<$/> set to C<undef>, "slurping" an empty file returns a string of +zero length (instead of C<undef>, as it used to) the first time the +HANDLE is read after C<$/> is set to C<undef>. Further reads yield +C<undef>. + +This means that the following will append "foo" to an empty file (it used +to do nothing): + + perl -0777 -pi -e 's/^/foo/' empty_file + +The behaviour of: + + perl -pi -e 's/^/foo/' empty_file + +is unchanged (it continues to leave the file empty). + +=head2 C<eval '...'> improvements + +Line numbers (as reflected by caller() and most diagnostics) within +C<eval '...'> were often incorrect where here documents were involved. +This has been corrected. + +Lexical lookups for variables appearing in C<eval '...'> within +functions that were themselves called within an C<eval '...'> were +searching the wrong place for lexicals. The lexical search now +correctly ends at the subroutine's block boundary. + +The use of C<return> within C<eval {...}> caused $@ not to be reset +correctly when no exception occurred within the eval. This has +been fixed. + +Parsing of here documents used to be flawed when they appeared as +the replacement expression in C<eval 's/.../.../e'>. This has +been fixed. + +=head2 All compilation errors are true errors + +Some "errors" encountered at compile time were by necessity +generated as warnings followed by eventual termination of the +program. This enabled more such errors to be reported in a +single run, rather than causing a hard stop at the first error +that was encountered. + +The mechanism for reporting such errors has been reimplemented +to queue compile-time errors and report them at the end of the +compilation as true errors rather than as warnings. This fixes +cases where error messages leaked through in the form of warnings +when code was compiled at run time using C<eval STRING>, and +also allows such errors to be reliably trapped using C<eval "...">. + +=head2 Implicitly closed filehandles are safer + +Sometimes implicitly closed filehandles (as when they are localized, +and Perl automatically closes them on exiting the scope) could +inadvertently set $? or $!. This has been corrected. + + +=head2 Behavior of list slices is more consistent + +When taking a slice of a literal list (as opposed to a slice of +an array or hash), Perl used to return an empty list if the +result happened to be composed of all undef values. + +The new behavior is to produce an empty list if (and only if) +the original list was empty. Consider the following example: + + @a = (1,undef,undef,2)[2,1,2]; + +The old behavior would have resulted in @a having no elements. +The new behavior ensures it has three undefined elements. + +Note in particular that the behavior of slices of the following +cases remains unchanged: + + @a = ()[1,2]; + @a = (getpwent)[7,0]; + @a = (anything_returning_empty_list())[2,1,2]; + @a = @b[2,1,2]; + @a = @c{'a','b','c'}; + +See L<perldata>. + +=head2 C<(\$)> prototype and C<$foo{a}> + +A scalar reference prototype now correctly allows a hash or +array element in that slot. + +=head2 C<goto &sub> and AUTOLOAD + +The C<goto &sub> construct works correctly when C<&sub> happens +to be autoloaded. + +=head2 C<-bareword> allowed under C<use integer> + +The autoquoting of barewords preceded by C<-> did not work +in prior versions when the C<integer> pragma was enabled. +This has been fixed. + +=head2 Failures in DESTROY() + +When code in a destructor threw an exception, it went unnoticed +in earlier versions of Perl, unless someone happened to be +looking in $@ just after the point the destructor happened to +run. Such failures are now visible as warnings when warnings are +enabled. + +=head2 Locale bugs fixed + +printf() and sprintf() previously reset the numeric locale +back to the default "C" locale. This has been fixed. + +Numbers formatted according to the local numeric locale +(such as using a decimal comma instead of a decimal dot) caused +"isn't numeric" warnings, even while the operations accessing +those numbers produced correct results. These warnings have been +discontinued. + +=head2 Memory leaks + +The C<eval 'return sub {...}'> construct could sometimes leak +memory. This has been fixed. + +Operations that aren't filehandle constructors used to leak memory +when used on invalid filehandles. This has been fixed. + +Constructs that modified C<@_> could fail to deallocate values +in C<@_> and thus leak memory. This has been corrected. + +=head2 Spurious subroutine stubs after failed subroutine calls + +Perl could sometimes create empty subroutine stubs when a +subroutine was not found in the package. Such cases stopped +later method lookups from progressing into base packages. +This has been corrected. + +=head2 Taint failures under C<-U> + +When running in unsafe mode, taint violations could sometimes +cause silent failures. This has been fixed. + +=head2 END blocks and the C<-c> switch + +Prior versions used to run BEGIN B<and> END blocks when Perl was +run in compile-only mode. Since this is typically not the expected +behavior, END blocks are not executed anymore when the C<-c> switch +is used, or if compilation fails. + +See L<CHECK blocks> for how to run things when the compile phase ends. + +=head2 Potential to leak DATA filehandles + +Using the C<__DATA__> token creates an implicit filehandle to +the file that contains the token. It is the program's +responsibility to close it when it is done reading from it. + +This caveat is now better explained in the documentation. +See L<perldata>. + +=head1 New or Changed Diagnostics + +=over 4 + +=item "%s" variable %s masks earlier declaration in same %s + +(W misc) A "my" or "our" variable has been redeclared in the current scope or statement, +effectively eliminating all access to the previous instance. This is almost +always a typographical error. Note that the earlier variable will still exist +until the end of the scope or until all closure referents to it are +destroyed. + +=item "my sub" not yet implemented + +(F) Lexically scoped subroutines are not yet implemented. Don't try that +yet. + +=item "our" variable %s redeclared + +(W misc) You seem to have already declared the same global once before in the +current lexical scope. + +=item '!' allowed only after types %s + +(F) The '!' is allowed in pack() and unpack() only after certain types. +See L<perlfunc/pack>. + +=item / cannot take a count + +(F) You had an unpack template indicating a counted-length string, +but you have also specified an explicit size for the string. +See L<perlfunc/pack>. + +=item / must be followed by a, A or Z + +(F) You had an unpack template indicating a counted-length string, +which must be followed by one of the letters a, A or Z +to indicate what sort of string is to be unpacked. +See L<perlfunc/pack>. + +=item / must be followed by a*, A* or Z* + +(F) You had a pack template indicating a counted-length string, +Currently the only things that can have their length counted are a*, A* or Z*. +See L<perlfunc/pack>. + +=item / must follow a numeric type + +(F) You had an unpack template that contained a '#', +but this did not follow some numeric unpack specification. +See L<perlfunc/pack>. + +=item /%s/: Unrecognized escape \\%c passed through + +(W regexp) You used a backslash-character combination which is not recognized +by Perl. This combination appears in an interpolated variable or a +C<'>-delimited regular expression. The character was understood literally. + +=item /%s/: Unrecognized escape \\%c in character class passed through + +(W regexp) You used a backslash-character combination which is not recognized +by Perl inside character classes. The character was understood literally. + +=item /%s/ should probably be written as "%s" + +(W syntax) You have used a pattern where Perl expected to find a string, +as in the first argument to C<join>. Perl will treat the true +or false result of matching the pattern against $_ as the string, +which is probably not what you had in mind. + +=item %s() called too early to check prototype + +(W prototype) You've called a function that has a prototype before the parser saw a +definition or declaration for it, and Perl could not check that the call +conforms to the prototype. You need to either add an early prototype +declaration for the subroutine in question, or move the subroutine +definition ahead of the call to get proper prototype checking. Alternatively, +if you are certain that you're calling the function correctly, you may put +an ampersand before the name to avoid the warning. See L<perlsub>. + +=item %s argument is not a HASH or ARRAY element + +(F) The argument to exists() must be a hash or array element, such as: + + $foo{$bar} + $ref->{"susie"}[12] + +=item %s argument is not a HASH or ARRAY element or slice + +(F) The argument to delete() must be either a hash or array element, such as: + + $foo{$bar} + $ref->{"susie"}[12] + +or a hash or array slice, such as: + + @foo[$bar, $baz, $xyzzy] + @{$ref->[12]}{"susie", "queue"} + +=item %s argument is not a subroutine name + +(F) The argument to exists() for C<exists &sub> must be a subroutine +name, and not a subroutine call. C<exists &sub()> will generate this error. + +=item %s package attribute may clash with future reserved word: %s + +(W reserved) A lowercase attribute name was used that had a package-specific handler. +That name might have a meaning to Perl itself some day, even though it +doesn't yet. Perhaps you should use a mixed-case attribute name, instead. +See L<attributes>. + +=item (in cleanup) %s + +(W misc) This prefix usually indicates that a DESTROY() method raised +the indicated exception. Since destructors are usually called by +the system at arbitrary points during execution, and often a vast +number of times, the warning is issued only once for any number +of failures that would otherwise result in the same message being +repeated. + +Failure of user callbacks dispatched using the C<G_KEEPERR> flag +could also result in this warning. See L<perlcall/G_KEEPERR>. + +=item <> should be quotes + +(F) You wrote C<< require <file> >> when you should have written +C<require 'file'>. + +=item Attempt to join self + +(F) You tried to join a thread from within itself, which is an +impossible task. You may be joining the wrong thread, or you may +need to move the join() to some other thread. + +=item Bad evalled substitution pattern + +(F) You've used the /e switch to evaluate the replacement for a +substitution, but perl found a syntax error in the code to evaluate, +most likely an unexpected right brace '}'. + +=item Bad realloc() ignored + +(S) An internal routine called realloc() on something that had never been +malloc()ed in the first place. Mandatory, but can be disabled by +setting environment variable C<PERL_BADFREE> to 1. + +=item Bareword found in conditional + +(W bareword) The compiler found a bareword where it expected a conditional, +which often indicates that an || or && was parsed as part of the +last argument of the previous construct, for example: + + open FOO || die; + +It may also indicate a misspelled constant that has been interpreted +as a bareword: + + use constant TYPO => 1; + if (TYOP) { print "foo" } + +The C<strict> pragma is useful in avoiding such errors. + +=item Binary number > 0b11111111111111111111111111111111 non-portable + +(W portable) The binary number you specified is larger than 2**32-1 +(4294967295) and therefore non-portable between systems. See +L<perlport> for more on portability concerns. + +=item Bit vector size > 32 non-portable + +(W portable) Using bit vector sizes larger than 32 is non-portable. + +=item Buffer overflow in prime_env_iter: %s + +(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over +%ENV, it encountered a logical name or symbol definition which was too long, +so it was truncated to the string shown. + +=item Can't check filesystem of script "%s" + +(P) For some reason you can't check the filesystem of the script for nosuid. + +=item Can't declare class for non-scalar %s in "%s" + +(S) Currently, only scalar variables can declared with a specific class +qualifier in a "my" or "our" declaration. The semantics may be extended +for other types of variables in future. + +=item Can't declare %s in "%s" + +(F) Only scalar, array, and hash variables may be declared as "my" or +"our" variables. They must have ordinary identifiers as names. + +=item Can't ignore signal CHLD, forcing to default + +(W signal) Perl has detected that it is being run with the SIGCHLD signal +(sometimes known as SIGCLD) disabled. Since disabling this signal +will interfere with proper determination of exit status of child +processes, Perl has reset the signal to its default value. +This situation typically indicates that the parent program under +which Perl may be running (e.g., cron) is being very careless. + +=item Can't modify non-lvalue subroutine call + +(F) Subroutines meant to be used in lvalue context should be declared as +such, see L<perlsub/"Lvalue subroutines">. + +=item Can't read CRTL environ + +(S) A warning peculiar to VMS. Perl tried to read an element of %ENV +from the CRTL's internal environment array and discovered the array was +missing. You need to figure out where your CRTL misplaced its environ +or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched. + +=item Can't remove %s: %s, skipping file + +(S) You requested an inplace edit without creating a backup file. Perl +was unable to remove the original file to replace it with the modified +file. The file was left unmodified. + +=item Can't return %s from lvalue subroutine + +(F) Perl detected an attempt to return illegal lvalues (such +as temporary or readonly values) from a subroutine used as an lvalue. +This is not allowed. + +=item Can't weaken a nonreference + +(F) You attempted to weaken something that was not a reference. Only +references can be weakened. + +=item Character class [:%s:] unknown + +(F) The class in the character class [: :] syntax is unknown. +See L<perlre>. + +=item Character class syntax [%s] belongs inside character classes + +(W unsafe) The character class constructs [: :], [= =], and [. .] go +I<inside> character classes, the [] are part of the construct, +for example: /[012[:alpha:]345]/. Note that [= =] and [. .] +are not currently implemented; they are simply placeholders for +future extensions. + +=item Constant is not %s reference + +(F) A constant value (perhaps declared using the C<use constant> pragma) +is being dereferenced, but it amounts to the wrong type of reference. The +message indicates the type of reference that was expected. This usually +indicates a syntax error in dereferencing the constant value. +See L<perlsub/"Constant Functions"> and L<constant>. + +=item constant(%s): %s + +(F) The parser found inconsistencies either while attempting to define an +overloaded constant, or when trying to find the character name specified +in the C<\N{...}> escape. Perhaps you forgot to load the corresponding +C<overload> or C<charnames> pragma? See L<charnames> and L<overload>. + +=item CORE::%s is not a keyword + +(F) The CORE:: namespace is reserved for Perl keywords. + +=item defined(@array) is deprecated + +(D) defined() is not usually useful on arrays because it checks for an +undefined I<scalar> value. If you want to see if the array is empty, +just use C<if (@array) { # not empty }> for example. + +=item defined(%hash) is deprecated + +(D) defined() is not usually useful on hashes because it checks for an +undefined I<scalar> value. If you want to see if the hash is empty, +just use C<if (%hash) { # not empty }> for example. + +=item Did not produce a valid header + +See Server error. + +=item (Did you mean "local" instead of "our"?) + +(W misc) Remember that "our" does not localize the declared global variable. +You have declared it again in the same lexical scope, which seems superfluous. + +=item Document contains no data + +See Server error. + +=item entering effective %s failed + +(F) While under the C<use filetest> pragma, switching the real and +effective uids or gids failed. + +=item false [] range "%s" in regexp + +(W regexp) A character class range must start and end at a literal character, not +another character class like C<\d> or C<[:alpha:]>. The "-" in your false +range is interpreted as a literal "-". Consider quoting the "-", "\-". +See L<perlre>. + +=item Filehandle %s opened only for output + +(W io) You tried to read from a filehandle opened only for writing. If you +intended it to be a read/write filehandle, you needed to open it with +"+<" or "+>" or "+>>" instead of with "<" or nothing. If +you intended only to read from the file, use "<". See +L<perlfunc/open>. + +=item flock() on closed filehandle %s + +(W closed) The filehandle you're attempting to flock() got itself closed some +time before now. Check your logic flow. flock() operates on filehandles. +Are you attempting to call flock() on a dirhandle by the same name? + +=item Global symbol "%s" requires explicit package name + +(F) You've said "use strict vars", which indicates that all variables +must either be lexically scoped (using "my"), declared beforehand using +"our", or explicitly qualified to say which package the global variable +is in (using "::"). + +=item Hexadecimal number > 0xffffffff non-portable + +(W portable) The hexadecimal number you specified is larger than 2**32-1 +(4294967295) and therefore non-portable between systems. See +L<perlport> for more on portability concerns. + +=item Ill-formed CRTL environ value "%s" + +(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal +environ array, and encountered an element without the C<=> delimiter +used to separate keys from values. The element is ignored. + +=item Ill-formed message in prime_env_iter: |%s| + +(W internal) A warning peculiar to VMS. Perl tried to read a logical name +or CLI symbol definition when preparing to iterate over %ENV, and +didn't see the expected delimiter between key and value, so the +line was ignored. + +=item Illegal binary digit %s + +(F) You used a digit other than 0 or 1 in a binary number. + +=item Illegal binary digit %s ignored + +(W digit) You may have tried to use a digit other than 0 or 1 in a binary number. +Interpretation of the binary number stopped before the offending digit. + +=item Illegal number of bits in vec + +(F) The number of bits in vec() (the third argument) must be a power of +two from 1 to 32 (or 64, if your platform supports that). + +=item Integer overflow in %s number + +(W overflow) The hexadecimal, octal or binary number you have specified either +as a literal or as an argument to hex() or oct() is too big for your +architecture, and has been converted to a floating point number. On a +32-bit architecture the largest hexadecimal, octal or binary number +representable without overflow is 0xFFFFFFFF, 037777777777, or +0b11111111111111111111111111111111 respectively. Note that Perl +transparently promotes all numbers to a floating point representation +internally--subject to loss of precision errors in subsequent +operations. + +=item Invalid %s attribute: %s + +The indicated attribute for a subroutine or variable was not recognized +by Perl or by a user-supplied handler. See L<attributes>. + +=item Invalid %s attributes: %s + +The indicated attributes for a subroutine or variable were not recognized +by Perl or by a user-supplied handler. See L<attributes>. + +=item invalid [] range "%s" in regexp + +The offending range is now explicitly displayed. + +=item Invalid separator character %s in attribute list + +(F) Something other than a colon or whitespace was seen between the +elements of an attribute list. If the previous attribute +had a parenthesised parameter list, perhaps that list was terminated +too soon. See L<attributes>. + +=item Invalid separator character %s in subroutine attribute list + +(F) Something other than a colon or whitespace was seen between the +elements of a subroutine attribute list. If the previous attribute +had a parenthesised parameter list, perhaps that list was terminated +too soon. + +=item leaving effective %s failed + +(F) While under the C<use filetest> pragma, switching the real and +effective uids or gids failed. + +=item Lvalue subs returning %s not implemented yet + +(F) Due to limitations in the current implementation, array and hash +values cannot be returned in subroutines used in lvalue context. +See L<perlsub/"Lvalue subroutines">. + +=item Method %s not permitted + +See Server error. + +=item Missing %sbrace%s on \N{} + +(F) Wrong syntax of character name literal C<\N{charname}> within +double-quotish context. + +=item Missing command in piped open + +(W pipe) You used the C<open(FH, "| command")> or C<open(FH, "command |")> +construction, but the command was missing or blank. + +=item Missing name in "my sub" + +(F) The reserved syntax for lexically scoped subroutines requires that they +have a name with which they can be found. + +=item No %s specified for -%c + +(F) The indicated command line switch needs a mandatory argument, but +you haven't specified one. + +=item No package name allowed for variable %s in "our" + +(F) Fully qualified variable names are not allowed in "our" declarations, +because that doesn't make much sense under existing semantics. Such +syntax is reserved for future extensions. + +=item No space allowed after -%c + +(F) The argument to the indicated command line switch must follow immediately +after the switch, without intervening spaces. + +=item no UTC offset information; assuming local time is UTC + +(S) A warning peculiar to VMS. Perl was unable to find the local +timezone offset, so it's assuming that local system time is equivalent +to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL> +to translate to the number of seconds which need to be added to UTC to +get local time. + +=item Octal number > 037777777777 non-portable + +(W portable) The octal number you specified is larger than 2**32-1 (4294967295) +and therefore non-portable between systems. See L<perlport> for more +on portability concerns. + +See also L<perlport> for writing portable code. + +=item panic: del_backref + +(P) Failed an internal consistency check while trying to reset a weak +reference. + +=item panic: kid popen errno read + +(F) forked child returned an incomprehensible message about its errno. + +=item panic: magic_killbackrefs + +(P) Failed an internal consistency check while trying to reset all weak +references to an object. + +=item Parentheses missing around "%s" list + +(W parenthesis) You said something like + + my $foo, $bar = @_; + +when you meant + + my ($foo, $bar) = @_; + +Remember that "my", "our", and "local" bind tighter than comma. + +=item Possible Y2K bug: %s + +(W y2k) You are concatenating the number 19 with another number, which +could be a potential Year 2000 problem. + +=item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead + +(W deprecated) You have written something like this: + + sub doit + { + use attrs qw(locked); + } + +You should use the new declaration syntax instead. + + sub doit : locked + { + ... + +The C<use attrs> pragma is now obsolete, and is only provided for +backward-compatibility. See L<perlsub/"Subroutine Attributes">. + + +=item Premature end of script headers + +See Server error. + +=item Repeat count in pack overflows + +(F) You can't specify a repeat count so large that it overflows +your signed integers. See L<perlfunc/pack>. + +=item Repeat count in unpack overflows + +(F) You can't specify a repeat count so large that it overflows +your signed integers. See L<perlfunc/unpack>. + +=item realloc() of freed memory ignored + +(S) An internal routine called realloc() on something that had already +been freed. + +=item Reference is already weak + +(W misc) You have attempted to weaken a reference that is already weak. +Doing so has no effect. + +=item setpgrp can't take arguments + +(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments, +unlike POSIX setpgid(), which takes a process ID and process group ID. + +=item Strange *+?{} on zero-length expression + +(W regexp) You applied a regular expression quantifier in a place where it +makes no sense, such as on a zero-width assertion. +Try putting the quantifier inside the assertion instead. For example, +the way to match "abc" provided that it is followed by three +repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. + +=item switching effective %s is not implemented + +(F) While under the C<use filetest> pragma, we cannot switch the +real and effective uids or gids. + +=item This Perl can't reset CRTL environ elements (%s) + +=item This Perl can't set CRTL environ elements (%s=%s) + +(W internal) Warnings peculiar to VMS. You tried to change or delete an element +of the CRTL's internal environ array, but your copy of Perl wasn't +built with a CRTL that contained the setenv() function. You'll need to +rebuild Perl with a CRTL that does, or redefine F<PERL_ENV_TABLES> (see +L<perlvms>) so that the environ array isn't the target of the change to +%ENV which produced the warning. + +=item Too late to run %s block + +(W void) A CHECK or INIT block is being defined during run time proper, +when the opportunity to run them has already passed. Perhaps you are +loading a file with C<require> or C<do> when you should be using +C<use> instead. Or perhaps you should put the C<require> or C<do> +inside a BEGIN block. + +=item Unknown open() mode '%s' + +(F) The second argument of 3-argument open() is not among the list +of valid modes: C<< < >>, C<< > >>, C<<< >> >>>, C<< +< >>, +C<< +> >>, C<<< +>> >>>, C<-|>, C<|->. + +=item Unknown process %x sent message to prime_env_iter: %s + +(P) An error peculiar to VMS. Perl was reading values for %ENV before +iterating over it, and someone else stuck a message in the stream of +data Perl expected. Someone's very confused, or perhaps trying to +subvert Perl's population of %ENV for nefarious purposes. + +=item Unrecognized escape \\%c passed through + +(W misc) You used a backslash-character combination which is not recognized +by Perl. The character was understood literally. + +=item Unterminated attribute parameter in attribute list + +(F) The lexer saw an opening (left) parenthesis character while parsing an +attribute list, but the matching closing (right) parenthesis +character was not found. You may need to add (or remove) a backslash +character to get your parentheses to balance. See L<attributes>. + +=item Unterminated attribute list + +(F) The lexer found something other than a simple identifier at the start +of an attribute, and it wasn't a semicolon or the start of a +block. Perhaps you terminated the parameter list of the previous attribute +too soon. See L<attributes>. + +=item Unterminated attribute parameter in subroutine attribute list + +(F) The lexer saw an opening (left) parenthesis character while parsing a +subroutine attribute list, but the matching closing (right) parenthesis +character was not found. You may need to add (or remove) a backslash +character to get your parentheses to balance. + +=item Unterminated subroutine attribute list + +(F) The lexer found something other than a simple identifier at the start +of a subroutine attribute, and it wasn't a semicolon or the start of a +block. Perhaps you terminated the parameter list of the previous attribute +too soon. + +=item Value of CLI symbol "%s" too long + +(W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV +element from a CLI symbol table, and found a resultant string longer +than 1024 characters. The return value has been truncated to 1024 +characters. + +=item Version number must be a constant number + +(P) The attempt to translate a C<use Module n.n LIST> statement into +its equivalent C<BEGIN> block found an internal inconsistency with +the version number. + +=back + +=head1 New tests + +=over 4 + +=item lib/attrs + +Compatibility tests for C<sub : attrs> vs the older C<use attrs>. + +=item lib/env + +Tests for new environment scalar capability (e.g., C<use Env qw($BAR);>). + +=item lib/env-array + +Tests for new environment array capability (e.g., C<use Env qw(@PATH);>). + +=item lib/io_const + +IO constants (SEEK_*, _IO*). + +=item lib/io_dir + +Directory-related IO methods (new, read, close, rewind, tied delete). + +=item lib/io_multihomed + +INET sockets with multi-homed hosts. + +=item lib/io_poll + +IO poll(). + +=item lib/io_unix + +UNIX sockets. + +=item op/attrs + +Regression tests for C<my ($x,@y,%z) : attrs> and <sub : attrs>. + +=item op/filetest + +File test operators. + +=item op/lex_assign + +Verify operations that access pad objects (lexicals and temporaries). + +=item op/exists_sub + +Verify C<exists &sub> operations. + +=back + +=head1 Incompatible Changes + +=head2 Perl Source Incompatibilities + +Beware that any new warnings that have been added or old ones +that have been enhanced are B<not> considered incompatible changes. + +Since all new warnings must be explicitly requested via the C<-w> +switch or the C<warnings> pragma, it is ultimately the programmer's +responsibility to ensure that warnings are enabled judiciously. + +=over 4 + +=item CHECK is a new keyword + +All subroutine definitions named CHECK are now special. See +C</"Support for CHECK blocks"> for more information. + +=item Treatment of list slices of undef has changed + +There is a potential incompatibility in the behavior of list slices +that are comprised entirely of undefined values. +See L</"Behavior of list slices is more consistent">. + +=head2 Format of $English::PERL_VERSION is different + +The English module now sets $PERL_VERSION to $^V (a string value) rather +than C<$]> (a numeric value). This is a potential incompatibility. +Send us a report via perlbug if you are affected by this. + +See L</"Improved Perl version numbering system"> for the reasons for +this change. + +=item Literals of the form C<1.2.3> parse differently + +Previously, numeric literals with more than one dot in them were +interpreted as a floating point number concatenated with one or more +numbers. Such "numbers" are now parsed as strings composed of the +specified ordinals. + +For example, C<print 97.98.99> used to output C<97.9899> in earlier +versions, but now prints C<abc>. + +See L</"Support for strings represented as a vector of ordinals">. + +=item Possibly changed pseudo-random number generator + +Perl programs that depend on reproducing a specific set of pseudo-random +numbers may now produce different output due to improvements made to the +rand() builtin. You can use C<sh Configure -Drandfunc=rand> to obtain +the old behavior. + +See L</"Better pseudo-random number generator">. + +=item Hashing function for hash keys has changed + +Even though Perl hashes are not order preserving, the apparently +random order encountered when iterating on the contents of a hash +is actually determined by the hashing algorithm used. Improvements +in the algorithm may yield a random order that is B<different> from +that of previous versions, especially when iterating on hashes. + +See L</"Better worst-case behavior of hashes"> for additional +information. + +=item C<undef> fails on read only values + +Using the C<undef> operator on a readonly value (such as $1) has +the same effect as assigning C<undef> to the readonly value--it +throws an exception. + +=item Close-on-exec bit may be set on pipe and socket handles + +Pipe and socket handles are also now subject to the close-on-exec +behavior determined by the special variable $^F. + +See L</"More consistent close-on-exec behavior">. + +=item Writing C<"$$1"> to mean C<"${$}1"> is unsupported + +Perl 5.004 deprecated the interpretation of C<$$1> and +similar within interpolated strings to mean C<$$ . "1">, +but still allowed it. + +In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">. + +=item delete(), values() and C<\(%h)> operate on aliases to values, not copies + +delete(), each(), values() and hashes in a list context return the actual +values in the hash, instead of copies (as they used to in earlier +versions). Typical idioms for using these constructs copy the +returned values, but this can make a significant difference when +creating references to the returned values. Keys in the hash are still +returned as copies when iterating on a hash. + +See also L</"delete(), each(), values() and hash iteration are faster">. + +=item vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS + +vec() generates a run-time error if the BITS argument is not +a valid power-of-two integer. + +=item Text of some diagnostic output has changed + +Most references to internal Perl operations in diagnostics +have been changed to be more descriptive. This may be an +issue for programs that may incorrectly rely on the exact +text of diagnostics for proper functioning. + +=item C<%@> has been removed + +The undocumented special variable C<%@> that used to accumulate +"background" errors (such as those that happen in DESTROY()) +has been removed, because it could potentially result in memory +leaks. + +=item Parenthesized not() behaves like a list operator + +The C<not> operator now falls under the "if it looks like a function, +it behaves like a function" rule. + +As a result, the parenthesized form can be used with C<grep> and C<map>. +The following construct used to be a syntax error before, but it works +as expected now: + + grep not($_), @things; + +On the other hand, using C<not> with a literal list slice may not +work. The following previously allowed construct: + + print not (1,2,3)[0]; + +needs to be written with additional parentheses now: + + print not((1,2,3)[0]); + +The behavior remains unaffected when C<not> is not followed by parentheses. + +=item Semantics of bareword prototype C<(*)> have changed + +The semantics of the bareword prototype C<*> have changed. Perl 5.005 +always coerced simple scalar arguments to a typeglob, which wasn't useful +in situations where the subroutine must distinguish between a simple +scalar and a typeglob. The new behavior is to not coerce bareword +arguments to a typeglob. The value will always be visible as either +a simple scalar or as a reference to a typeglob. + +See L</"More functional bareword prototype (*)">. + +=head2 Semantics of bit operators may have changed on 64-bit platforms + +If your platform is either natively 64-bit or if Perl has been +configured to used 64-bit integers, i.e., $Config{ivsize} is 8, +there may be a potential incompatibility in the behavior of bitwise +numeric operators (& | ^ ~ << >>). These operators used to strictly +operate on the lower 32 bits of integers in previous versions, but now +operate over the entire native integral width. In particular, note +that unary C<~> will produce different results on platforms that have +different $Config{ivsize}. For portability, be sure to mask off +the excess bits in the result of unary C<~>, e.g., C<~$x & 0xffffffff>. + +See L</"Bit operators support full native integer width">. + +=head2 More builtins taint their results + +As described in L</"Improved security features">, there may be more +sources of taint in a Perl program. + +To avoid these new tainting behaviors, you can build Perl with the +Configure option C<-Accflags=-DINCOMPLETE_TAINTS>. Beware that the +ensuing perl binary may be insecure. + +=back + +=head2 C Source Incompatibilities + +=over 4 + +=item C<PERL_POLLUTE> + +Release 5.005 grandfathered old global symbol names by providing preprocessor +macros for extension source compatibility. As of release 5.6.0, these +preprocessor definitions are not available by default. You need to explicitly +compile perl with C<-DPERL_POLLUTE> to get these definitions. For +extensions still using the old symbols, this option can be +specified via MakeMaker: + + perl Makefile.PL POLLUTE=1 + +=item C<PERL_IMPLICIT_CONTEXT> + +This new build option provides a set of macros for all API functions +such that an implicit interpreter/thread context argument is passed to +every API function. As a result of this, something like C<sv_setsv(foo,bar)> +amounts to a macro invocation that actually translates to something like +C<Perl_sv_setsv(my_perl,foo,bar)>. While this is generally expected +to not have any significant source compatibility issues, the difference +between a macro and a real function call will need to be considered. + +This means that there B<is> a source compatibility issue as a result of +this if your extensions attempt to use pointers to any of the Perl API +functions. + +Note that the above issue is not relevant to the default build of +Perl, whose interfaces continue to match those of prior versions +(but subject to the other options described here). + +See L<perlguts/"The Perl API"> for detailed information on the +ramifications of building Perl with this option. + + NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built + with one of -Dusethreads, -Dusemultiplicity, or both. It is not + intended to be enabled by users at this time. + +=item C<PERL_POLLUTE_MALLOC> + +Enabling Perl's malloc in release 5.005 and earlier caused the namespace of +the system's malloc family of functions to be usurped by the Perl versions, +since by default they used the same names. Besides causing problems on +platforms that do not allow these functions to be cleanly replaced, this +also meant that the system versions could not be called in programs that +used Perl's malloc. Previous versions of Perl have allowed this behaviour +to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor +definitions. + +As of release 5.6.0, Perl's malloc family of functions have default names +distinct from the system versions. You need to explicitly compile perl with +C<-DPERL_POLLUTE_MALLOC> to get the older behaviour. HIDEMYMALLOC +and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now +the default. + +Note that these functions do B<not> constitute Perl's memory allocation API. +See L<perlguts/"Memory Allocation"> for further information about that. + +=back + +=head2 Compatible C Source API Changes + +=over + +=item C<PATCHLEVEL> is now C<PERL_VERSION> + +The cpp macros C<PERL_REVISION>, C<PERL_VERSION>, and C<PERL_SUBVERSION> +are now available by default from perl.h, and reflect the base revision, +patchlevel, and subversion respectively. C<PERL_REVISION> had no +prior equivalent, while C<PERL_VERSION> and C<PERL_SUBVERSION> were +previously available as C<PATCHLEVEL> and C<SUBVERSION>. + +The new names cause less pollution of the B<cpp> namespace and reflect what +the numbers have come to stand for in common practice. For compatibility, +the old names are still supported when F<patchlevel.h> is explicitly +included (as required before), so there is no source incompatibility +from the change. + +=back + +=head2 Binary Incompatibilities + +In general, the default build of this release is expected to be binary +compatible for extensions built with the 5.005 release or its maintenance +versions. However, specific platforms may have broken binary compatibility +due to changes in the defaults used in hints files. Therefore, please be +sure to always check the platform-specific README files for any notes to +the contrary. + +The usethreads or usemultiplicity builds are B<not> binary compatible +with the corresponding builds in 5.005. + +On platforms that require an explicit list of exports (AIX, OS/2 and Windows, +among others), purely internal symbols such as parser functions and the +run time opcodes are not exported by default. Perl 5.005 used to export +all functions irrespective of whether they were considered part of the +public API or not. + +For the full list of public API functions, see L<perlapi>. + +=head1 Known Problems + +=head2 Thread test failures + +The subtests 19 and 20 of lib/thr5005.t test are known to fail due to +fundamental problems in the 5.005 threading implementation. These are +not new failures--Perl 5.005_0x has the same bugs, but didn't have these +tests. + +=head2 EBCDIC platforms not supported + +In earlier releases of Perl, EBCDIC environments like OS390 (also +known as Open Edition MVS) and VM-ESA were supported. Due to changes +required by the UTF-8 (Unicode) support, the EBCDIC platforms are not +supported in Perl 5.6.0. + +=head2 In 64-bit HP-UX the lib/io_multihomed test may hang + +The lib/io_multihomed test may hang in HP-UX if Perl has been +configured to be 64-bit. Because other 64-bit platforms do not +hang in this test, HP-UX is suspect. All other tests pass +in 64-bit HP-UX. The test attempts to create and connect to +"multihomed" sockets (sockets which have multiple IP addresses). + +=head2 NEXTSTEP 3.3 POSIX test failure + +In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the +operating system libraries is buggy: the %j format numbers the days of +a month starting from zero, which, while being logical to programmers, +will cause the subtests 19 to 27 of the lib/posix test may fail. + +=head2 Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc + +If compiled with gcc 2.95 the lib/sdbm test will fail (dump core). +The cure is to use the vendor cc, it comes with the operating system +and produces good code. + +=head2 UNICOS/mk CC failures during Configure run + +In UNICOS/mk the following errors may appear during the Configure run: + + Guessing which symbols your C compiler and preprocessor define... + CC-20 cc: ERROR File = try.c, Line = 3 + ... + bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K + ... + 4 errors detected in the compilation of "try.c". + +The culprit is the broken awk of UNICOS/mk. The effect is fortunately +rather mild: Perl itself is not adversely affected by the error, only +the h2ph utility coming with Perl, and that is rather rarely needed +these days. + +=head2 Arrow operator and arrays + +When the left argument to the arrow operator C<< -> >> is an array, or +the C<scalar> operator operating on an array, the result of the +operation must be considered erroneous. For example: + + @x->[2] + scalar(@x)->[2] + +These expressions will get run-time errors in some future release of +Perl. + +=head2 Experimental features + +As discussed above, many features are still experimental. Interfaces and +implementation of these features are subject to change, and in extreme cases, +even subject to removal in some future release of Perl. These features +include the following: + +=over 4 + +=item Threads + +=item Unicode + +=item 64-bit support + +=item Lvalue subroutines + +=item Weak references + +=item The pseudo-hash data type + +=item The Compiler suite + +=item Internal implementation of file globbing + +=item The DB module + +=item The regular expression constructs C<(?{ code })> and C<(??{ code })> + +=back + +=head1 Obsolete Diagnostics + +=over 4 + +=item Character class syntax [: :] is reserved for future extensions + +(W) Within regular expression character classes ([]) the syntax beginning +with "[:" and ending with ":]" is reserved for future extensions. +If you need to represent those character sequences inside a regular +expression character class, just quote the square brackets with the +backslash: "\[:" and ":\]". + +=item Ill-formed logical name |%s| in prime_env_iter + +(W) A warning peculiar to VMS. A logical name was encountered when preparing +to iterate over %ENV which violates the syntactic rules governing logical +names. Because it cannot be translated normally, it is skipped, and will not +appear in %ENV. This may be a benign occurrence, as some software packages +might directly modify logical name tables and introduce nonstandard names, +or it may indicate that a logical name table has been corrupted. + +=item Probable precedence problem on %s + +(W) The compiler found a bareword where it expected a conditional, +which often indicates that an || or && was parsed as part of the +last argument of the previous construct, for example: + + open FOO || die; + +=item regexp too big + +(F) The current implementation of regular expressions uses shorts as +address offsets within a string. Unfortunately this means that if +the regular expression compiles to longer than 32767, it'll blow up. +Usually when you want a regular expression this big, there is a better +way to do it with multiple statements. See L<perlre>. + +=item Use of "$$<digit>" to mean "${$}<digit>" is deprecated + +(D) Perl versions before 5.004 misinterpreted any type marker followed +by "$" and a digit. For example, "$$0" was incorrectly taken to mean +"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004. + +However, the developers of Perl 5.004 could not fix this bug completely, +because at least two widely-used modules depend on the old meaning of +"$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the +old (broken) way inside strings; but it generates this message as a +warning. And in Perl 5.005, this special treatment will cease. + +=back + +=head1 Reporting Bugs + +If you find what you think is a bug, you might check the +articles recently posted to the comp.lang.perl.misc newsgroup. +There may also be information at http://www.perl.com/perl/, the Perl +Home Page. + +If you believe you have an unreported bug, please run the B<perlbug> +program included with your release. Be sure to trim your bug down +to a tiny but sufficient test case. Your bug report, along with the +output of C<perl -V>, will be sent off to perlbug@perl.com to be +analysed by the Perl porting team. + +=head1 SEE ALSO + +The F<Changes> file for exhaustive details on what changed. + +The F<INSTALL> file for how to build Perl. + +The F<README> file for general stuff. + +The F<Artistic> and F<Copying> files for copyright information. + +=head1 HISTORY + +Written by Gurusamy Sarathy <F<gsar@activestate.com>>, with many +contributions from The Perl Porters. + +Send omissions or corrections to <F<perlbug@perl.com>>. + +=cut diff --git a/pod/perlapi.pod b/pod/perlapi.pod index e4dedbe21b..58e29515c4 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -237,7 +237,7 @@ NOTE: the perl_ form of this function is deprecated. =item EXTEND Used to extend the argument stack for an XSUB's return values. Once -used, guarrantees that there is room for at least C<nitems> to be pushed +used, guarantees that there is room for at least C<nitems> to be pushed onto the stack. void EXTEND(SP, int nitems) @@ -381,17 +381,17 @@ C<call_sv> apply equally to these functions. =item gv_stashpv -Returns a pointer to the stash for a specified package. If C<create> is -set then the package will be created if it does not already exist. If -C<create> is not set and the package does not exist then NULL is -returned. +Returns a pointer to the stash for a specified package. C<name> should +be a valid UTF-8 string. If C<create> is set then the package will be +created if it does not already exist. If C<create> is not set and the +package does not exist then NULL is returned. HV* gv_stashpv(const char* name, I32 create) =item gv_stashsv -Returns a pointer to the stash for a specified package. See -C<gv_stashpv>. +Returns a pointer to the stash for a specified package, which must be a +valid UTF-8 string. See C<gv_stashpv>. HV* gv_stashsv(SV* sv, I32 create) @@ -662,21 +662,21 @@ Undefines the hash. =item isALNUM -Returns a boolean indicating whether the C C<char> is an ascii alphanumeric +Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric character or digit. bool isALNUM(char ch) =item isALPHA -Returns a boolean indicating whether the C C<char> is an ascii alphabetic +Returns a boolean indicating whether the C C<char> is an ASCII alphabetic character. bool isALPHA(char ch) =item isDIGIT -Returns a boolean indicating whether the C C<char> is an ascii +Returns a boolean indicating whether the C C<char> is an ASCII digit. bool isDIGIT(char ch) @@ -897,6 +897,13 @@ Creates a new SV which is an exact duplicate of the original SV. SV* newSVsv(SV* old) +=item newSVuv + +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. + + SV* newSVuv(UV u) + =item newXS Used by C<xsubpp> to hook up XSUBs as Perl subs. @@ -1256,7 +1263,7 @@ wrapper for C<strncmp>). =item StructCopy -This is an architecture-independant macro to copy one structure to another. +This is an architecture-independent macro to copy one structure to another. void StructCopy(type src, type dest, type) @@ -1590,17 +1597,17 @@ false, defined or undefined. Does not handle 'get' magic. bool SvTRUE(SV* sv) +=item svtype + +An enum of flags for Perl types. These are found in the file B<sv.h> +in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. + =item SvTYPE Returns the type of the SV. See C<svtype>. svtype SvTYPE(SV* sv) -=item svtype - -An enum of flags for Perl types. These are found in the file B<sv.h> -in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. - =item SVt_IV Integer type flag for scalars. See C<svtype>. diff --git a/pod/perlbook.pod b/pod/perlbook.pod index 3a693ddd8e..1b322fb576 100644 --- a/pod/perlbook.pod +++ b/pod/perlbook.pod @@ -9,7 +9,7 @@ by Larry Wall et al, is the definitive reference work covering nearly all of Perl. You can order it and other Perl books from O'Reilly & Associates, 1-800-998-9938. Local/overseas is +1 707 829 0515. If you can locate an O'Reilly order form, you can also fax to +1 707 829 0104. -If you're web-connected, you can even mosey on over to http://www.ora.com/ +If you're web-connected, you can even mosey on over to http://www.oreilly.com/ for an online order form. Other Perl books from various publishers and authors diff --git a/pod/perlboot.pod b/pod/perlboot.pod index bab365609e..b549f45e49 100644 --- a/pod/perlboot.pod +++ b/pod/perlboot.pod @@ -7,7 +7,7 @@ perlboot - Beginner's Object-Oriented Tutorial If you're not familiar with objects from other languages, some of the other Perl object documentation may be a little daunting, such as L<perlobj>, a basic reference in using objects, and L<perltoot>, which -introduces readers to the pecularities of Perl's object system in a +introduces readers to the peculiarities of Perl's object system in a tutorial way. So, let's take a different approach, presuming no prior object @@ -139,8 +139,8 @@ attempts to invoke subroutine C<Class::method> as: (If the subroutine can't be found, "inheritance" kicks in, but we'll get to that later.) This means that we get the class name as the -first parameter. So we can rewrite the C<Sheep> speaking subroutine -as: +first parameter (the only parameter, if no arguments are given). So +we can rewrite the C<Sheep> speaking subroutine as: sub Sheep::speak { my $class = shift; @@ -245,14 +245,15 @@ inheritance. When we turn on C<use strict>, we'll get complaints on C<@ISA>, since it's not a variable containing an explicit package name, nor is it a -lexical ("my") variable. We can't make it a lexical variable though, +lexical ("my") variable. We can't make it a lexical variable though +(it has to belong to the package to be found by the inheritance mechanism), so there's a couple of straightforward ways to handle that. The easiest is to just spell the package name out: @Cow::ISA = qw(Animal); -Or allow it as an implictly named package variable: +Or allow it as an implicitly named package variable: package Cow; use vars qw(@ISA); @@ -490,7 +491,7 @@ If Horse::sound had not been found, we'd be wandering up the C<@Horse::ISA> list to try to find the method in one of the superclasses, just as for a class method. The only difference between a class method and an instance method is whether the first parameter -is a instance (a blessed reference) or a class name (a string). +is an instance (a blessed reference) or a class name (a string). =head2 Accessing the instance data @@ -552,6 +553,17 @@ C<Horse::named> are C<Horse> and C<Mr. Ed>. The C<bless> operator not only blesses C<$name>, it also returns the reference to C<$name>, so that's fine as a return value. And that's how to build a horse. +We've called the constructor C<named> here, so that it quickly denotes +the constructor's argument as the name for this particular C<Horse>. +You can use different constructors with different names for different +ways of "giving birth" to the object (like maybe recording its +pedigree or date of birth). However, you'll find that most people +coming to Perl from more limited languages use a single constructor +named C<new>, with various ways of interpreting the arguments to +C<new>. Either style is fine, as long as you document your particular +way of giving birth to an object. (And you I<were> going to do that, +right?) + =head2 Inheriting the constructor But was there anything specific to C<Horse> in that method? No. Therefore, diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 34f442a424..148b24b51b 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -1939,7 +1939,7 @@ done inside our C code: C<eval_pv> is used to compile the anonymous subroutine, which will be the return value as well (read more about C<eval_pv> in -L<perlguts/eval_pv>). Once this code reference is in hand, it +L<perlapi/eval_pv>). Once this code reference is in hand, it can be mixed in with all the previous examples we've shown. =head1 SEE ALSO diff --git a/pod/perlcompile.pod b/pod/perlcompile.pod index 04dc019b36..e5544ec444 100644 --- a/pod/perlcompile.pod +++ b/pod/perlcompile.pod @@ -103,9 +103,9 @@ This is why all the back ends print: before producing any other output. -=head2 The Cross Referencing Back End (B::Xref) +=head2 The Cross Referencing Back End -The cross referencing back end produces a report on your program, +The cross referencing back end (B::Xref) produces a report on your program, breaking down declarations and uses of subroutines and variables (and formats) by file and subroutine. For instance, here's part of the report from the I<pod2man> program that comes with Perl: @@ -203,11 +203,11 @@ The B<-p> option adds parentheses where normally they are omitted: See L<B::Deparse> for more information on the formatting options. -=head2 The Lint Back End (B::Lint) +=head2 The Lint Back End -The lint back end inspects programs for poor style. One programmer's -bad style is another programmer's useful tool, so options let you -select what is complained about. +The lint back end (B::Lint) inspects programs for poor style. One +programmer's bad style is another programmer's useful tool, so options +let you select what is complained about. To run the style checker across your source code: @@ -306,8 +306,9 @@ I<assemble> program that produces bytecode. =item B::Bblock -This module is used by the B::CC back end. It walks "basic blocks", -whatever they may be. +This module is used by the B::CC back end. It walks "basic blocks". +A basic block is a series of operations which is known to execute from +start to finish, with no possibility of branching or halting. =item B::Bytecode @@ -368,12 +369,12 @@ can identify. See L</"The Lint Back End"> for details about usage. =item B::Showlex This module prints out the my() variables used in a function or a -file. To gt a list of the my() variables used in the subroutine +file. To get a list of the my() variables used in the subroutine mysub() defined in the file myperlprogram: $ perl -MO=Showlex,mysub myperlprogram -To gt a list of the my() variables used in the file myperlprogram: +To get a list of the my() variables used in the file myperlprogram: $ perl -MO=Showlex myperlprogram @@ -418,7 +419,7 @@ names. The optimized C backend outputs code for more modules than it should (e.g., DirHandle). It also has little hope of properly handling -C<goto LABEL> outside the running subroutine (C<goto &sub> is ok). +C<goto LABEL> outside the running subroutine (C<goto &sub> is okay). C<goto LABEL> currently does not work at all in this backend. It also creates a huge initialization function that gives C compilers headaches. Splitting the initialization function gives diff --git a/pod/perldata.pod b/pod/perldata.pod index e3361e4dad..ac444fa17c 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -129,7 +129,8 @@ assignment to an array or hash evaluates the righthand side in list context. Assignment to a list (or slice, which is just a list anyway) also evaluates the righthand side in list context. -When you use Perl's B<-w> command-line option, you may see warnings +When you use the C<use warnings> pragma or Perl's B<-w> command-line +option, you may see warnings about useless uses of constants or functions in "void context". Void context just means the value has been discarded, such as a statement containing only C<"fred";> or C<getpwuid(0);>. It still @@ -274,7 +275,6 @@ integer formats: 0xff # hex 0377 # octal 0b011011 # binary - v102.111.111 # string (made of characters "f", "o", "o") String literals are usually delimited by either single or double quotes. They work much like quotes in the standard Unix shells: @@ -282,7 +282,7 @@ double-quoted string literals are subject to backslash and variable substitution; single-quoted strings are not (except for C<\'> and C<\\>). The usual C-style backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic -forms. See L<perlop/"Quote and Quotelike Operators"> for a list. +forms. See L<perlop/"Quote and Quote-like Operators"> for a list. Hexadecimal, octal, or binary, representations in string literals (e.g. '0xff') are not automatically converted to their integer @@ -331,7 +331,13 @@ readable interpolation form C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for representing Unicode strings, and for comparing version "numbers" using the string comparison operators, C<cmp>, C<gt>, C<lt> etc. If there are two or more dots in the literal, the leading C<v> may be -omitted. Such literals are accepted by both C<require> and C<use> for +omitted. + + print v9786; # prints UTF-8 encoded SMILEY, "\x{263a}" + print v102.111.111; # prints "foo" + print 102.111.111; # same + +Such literals are accepted by both C<require> and C<use> for doing a version check. The C<$^V> special variable also contains the running Perl interpreter's version in this form. See L<perlvar/$^V>. @@ -366,7 +372,8 @@ A word that has no other interpretation in the grammar will be treated as if it were a quoted string. These are known as "barewords". As with filehandles and labels, a bareword that consists entirely of lowercase letters risks conflict with future reserved -words, and if you use the B<-w> switch, Perl will warn you about any +words, and if you use the C<use warnings> pragma or the B<-w> switch, +Perl will warn you about any such words. Some people may wish to outlaw barewords entirely. If you say @@ -743,6 +750,28 @@ C<*HANDLE{IO}> only works if HANDLE has already been used as a handle. In other words, C<*FH> must be used to create new symbol table entries; C<*foo{THING}> cannot. When in doubt, use C<*FH>. +All functions that are capable of creating filehandles (open(), +opendir(), pipe(), socketpair(), sysopen(), socket(), and accept()) +automatically create an anonymous filehandle if the handle passed to +them is an uninitialized scalar variable. This allows the constructs +such as C<open(my $fh, ...)> and C<open(local $fh,...)> to be used to +create filehandles that will conveniently be closed automatically when +the scope ends, provided there are no other references to them. This +largely eliminates the need for typeglobs when opening filehandles +that must be passed around, as in the following example: + + sub myopen { + open my $fh, "@_" + or die "Can't open '@_': $!"; + return $fh; + } + + { + my $f = myopen("</etc/motd"); + print <$f>; + # $f implicitly closed here + } + Another way to create anonymous filehandles is with the Symbol module or with the IO::Handle module and its ilk. These modules have the advantage of not hiding different types of the same name diff --git a/pod/perldbmfilter.pod b/pod/perldbmfilter.pod index faed2d25d2..3350596aab 100644 --- a/pod/perldbmfilter.pod +++ b/pod/perldbmfilter.pod @@ -86,6 +86,7 @@ sure you have already guessed, this is a problem that DBM Filters can fix very easily. use strict ; + use warnings ; use SDBM_File ; use Fcntl ; @@ -99,7 +100,8 @@ fix very easily. # Install DBM Filters $db->filter_fetch_key ( sub { s/\0$// } ) ; $db->filter_store_key ( sub { $_ .= "\0" } ) ; - $db->filter_fetch_value( sub { s/\0$// } ) ; + $db->filter_fetch_value( + sub { no warnings 'uninitialized' ;s/\0$// } ) ; $db->filter_store_value( sub { $_ .= "\0" } ) ; $hash{"abc"} = "def" ; @@ -132,6 +134,7 @@ when reading. Here is a DBM Filter that does it: use strict ; + use warnings ; use DB_File ; my %hash ; my $filename = "/tmp/filt" ; diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod new file mode 100644 index 0000000000..45c33c7ec4 --- /dev/null +++ b/pod/perldebguts.pod @@ -0,0 +1,923 @@ +=head1 NAME + +perldebguts - Guts of Perl debugging + +=head1 DESCRIPTION + +This is not the perldebug(1) manpage, which tells you how to use +the debugger. This manpage describes low-level details ranging +between difficult and impossible for anyone who isn't incredibly +intimate with Perl's guts to understand. Caveat lector. + +=head1 Debugger Internals + +Perl has special debugging hooks at compile-time and run-time used +to create debugging environments. These hooks are not to be confused +with the I<perl -Dxxx> command described in L<perlrun>, which is +usable only if a special Perl is built per the instructions in the +F<INSTALL> podpage in the Perl source tree. + +For example, whenever you call Perl's built-in C<caller> function +from the package DB, the arguments that the corresponding stack +frame was called with are copied to the @DB::args array. The +general mechanisms is enabled by calling Perl with the B<-d> switch, the +following additional features are enabled (cf. L<perlvar/$^P>): + +=over + +=item * + +Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require +'perl5db.pl'}> if not present) before the first line of your program. + +=item * + +The array C<@{"_<$filename"}> holds the lines of $filename for all +files compiled by Perl. The same for C<eval>ed strings that contain +subroutines, or which are currently being executed. The $filename +for C<eval>ed strings looks like C<(eval 34)>. Code assertions +in regexes look like C<(re_eval 19)>. + +=item * + +The hash C<%{"_<$filename"}> contains breakpoints and actions keyed +by line number. Individual entries (as opposed to the whole hash) +are settable. Perl only cares about Boolean true here, although +the values used by F<perl5db.pl> have the form +C<"$break_condition\0$action">. Values in this hash are magical +in numeric context: they are zeros if the line is not breakable. + +The same holds for evaluated strings that contain subroutines, or +which are currently being executed. The $filename for C<eval>ed strings +looks like C<(eval 34)> or C<(re_eval 19)>. + +=item * + +The scalar C<${"_<$filename"}> contains C<"_<$filename">. This is +also the case for evaluated strings that contain subroutines, or +which are currently being executed. The $filename for C<eval>ed +strings looks like C<(eval 34)> or C<(re_eval 19)>. + +=item * + +After each C<require>d file is compiled, but before it is executed, +C<DB::postponed(*{"_<$filename"})> is called if the subroutine +C<DB::postponed> exists. Here, the $filename is the expanded name of +the C<require>d file, as found in the values of %INC. + +=item * + +After each subroutine C<subname> is compiled, the existence of +C<$DB::postponed{subname}> is checked. If this key exists, +C<DB::postponed(subname)> is called if the C<DB::postponed> subroutine +also exists. + +=item * + +A hash C<%DB::sub> is maintained, whose keys are subroutine names +and whose values have the form C<filename:startline-endline>. +C<filename> has the form C<(eval 34)> for subroutines defined inside +C<eval>s, or C<(re_eval 19)> for those within regex code assertions. + +=item * + +When the execution of your program reaches a point that can hold a +breakpoint, the C<DB::DB()> subroutine is called any of the variables +$DB::trace, $DB::single, or $DB::signal is true. These variables +are not C<local>izable. This feature is disabled when executing +inside C<DB::DB()>, including functions called from it +unless C<< $^D & (1<<30) >> is true. + +=item * + +When execution of the program reaches a subroutine call, a call to +C<&DB::sub>(I<args>) is made instead, with C<$DB::sub> holding the +name of the called subroutine. This doesn't happen if the subroutine +was compiled in the C<DB> package.) + +=back + +Note that if C<&DB::sub> needs external data for it to work, no +subroutine call is possible until this is done. For the standard +debugger, the C<$DB::deep> variable (how many levels of recursion +deep into the debugger you can go before a mandatory break) gives +an example of such a dependency. + +=head2 Writing Your Own Debugger + +The minimal working debugger consists of one line + + sub DB::DB {} + +which is quite handy as contents of C<PERL5DB> environment +variable: + + $ PERL5DB="sub DB::DB {}" perl -d your-script + +Another brief debugger, slightly more useful, could be created +with only the line: + + sub DB::DB {print ++$i; scalar <STDIN>} + +This debugger would print the sequential number of encountered +statement, and would wait for you to hit a newline before continuing. + +The following debugger is quite functional: + + { + package DB; + sub DB {} + sub sub {print ++$i, " $sub\n"; &$sub} + } + +It prints the sequential number of subroutine call and the name of the +called subroutine. Note that C<&DB::sub> should be compiled into the +package C<DB>. + +At the start, the debugger reads your rc file (F<./.perldb> or +F<~/.perldb> under Unix), which can set important options. This file may +define a subroutine C<&afterinit> to be executed after the debugger is +initialized. + +After the rc file is read, the debugger reads the PERLDB_OPTS +environment variable and parses this as the remainder of a C<O ...> +line as one might enter at the debugger prompt. + +The debugger also maintains magical internal variables, such as +C<@DB::dbline>, C<%DB::dbline>, which are aliases for +C<@{"::_<current_file"}> C<%{"::_<current_file"}>. Here C<current_file> +is the currently selected file, either explicitly chosen with the +debugger's C<f> command, or implicitly by flow of execution. + +Some functions are provided to simplify customization. See +L<perldebug/"Options"> for description of options parsed by +C<DB::parse_options(string)>. The function C<DB::dump_trace(skip[, +count])> skips the specified number of frames and returns a list +containing information about the calling frames (all of them, if +C<count> is missing). Each entry is reference to a hash with +keys C<context> (either C<.>, C<$>, or C<@>), C<sub> (subroutine +name, or info about C<eval>), C<args> (C<undef> or a reference to +an array), C<file>, and C<line>. + +The function C<DB::print_trace(FH, skip[, count[, short]])> prints +formatted info about caller frames. The last two functions may be +convenient as arguments to C<< < >>, C<< << >> commands. + +Note that any variables and functions that are not documented in +this manpages (or in L<perldebug>) are considered for internal +use only, and as such are subject to change without notice. + +=head1 Frame Listing Output Examples + +The C<frame> option can be used to control the output of frame +information. For example, contrast this expression trace: + + $ perl -de 42 + Stack dump during die enabled outside of evals. + + Loading DB routines from perl5db.pl patch level 0.94 + Emacs support available. + + Enter h or `h h' for help. + + main::(-e:1): 0 + DB<1> sub foo { 14 } + + DB<2> sub bar { 3 } + + DB<3> t print foo() * bar() + main::((eval 172):3): print foo() + bar(); + main::foo((eval 168):2): + main::bar((eval 170):2): + 42 + +with this one, once the C<O>ption C<frame=2> has been set: + + DB<4> O f=2 + frame = '2' + DB<5> t print foo() * bar() + 3: foo() * bar() + entering main::foo + 2: sub foo { 14 }; + exited main::foo + entering main::bar + 2: sub bar { 3 }; + exited main::bar + 42 + +By way of demonstration, we present below a laborious listing +resulting from setting your C<PERLDB_OPTS> environment variable to +the value C<f=n N>, and running I<perl -d -V> from the command line. +Examples use various values of C<n> are shown to give you a feel +for the difference between settings. Long those it may be, this +is not a complete listing, but only excerpts. + +=over 4 + +=item 1 + + entering main::BEGIN + entering Config::BEGIN + Package lib/Exporter.pm. + Package lib/Carp.pm. + Package lib/Config.pm. + entering Config::TIEHASH + entering Exporter::import + entering Exporter::export + entering Config::myconfig + entering Config::FETCH + entering Config::FETCH + entering Config::FETCH + entering Config::FETCH + +=item 2 + + entering main::BEGIN + entering Config::BEGIN + Package lib/Exporter.pm. + Package lib/Carp.pm. + exited Config::BEGIN + Package lib/Config.pm. + entering Config::TIEHASH + exited Config::TIEHASH + entering Exporter::import + entering Exporter::export + exited Exporter::export + exited Exporter::import + exited main::BEGIN + entering Config::myconfig + entering Config::FETCH + exited Config::FETCH + entering Config::FETCH + exited Config::FETCH + entering Config::FETCH + +=item 4 + + in $=main::BEGIN() from /dev/null:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li + in @=Config::myconfig() from /dev/null:0 + in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 + +=item 6 + + in $=main::BEGIN() from /dev/null:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + out $=Config::BEGIN() from lib/Config.pm:0 + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + out $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ + out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ + out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + out $=main::BEGIN() from /dev/null:0 + in @=Config::myconfig() from /dev/null:0 + in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 + out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 + in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 + +=item 14 + + in $=main::BEGIN() from /dev/null:0 + in $=Config::BEGIN() from lib/Config.pm:2 + Package lib/Exporter.pm. + Package lib/Carp.pm. + out $=Config::BEGIN() from lib/Config.pm:0 + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:644 + out $=Config::TIEHASH('Config') from lib/Config.pm:644 + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E + out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E + out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + out $=main::BEGIN() from /dev/null:0 + in @=Config::myconfig() from /dev/null:0 + in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 + out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 + in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 + out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 + +=item 30 + + in $=CODE(0x15eca4)() from /dev/null:0 + in $=CODE(0x182528)() from lib/Config.pm:2 + Package lib/Exporter.pm. + out $=CODE(0x182528)() from lib/Config.pm:0 + scalar context return from CODE(0x182528): undef + Package lib/Config.pm. + in $=Config::TIEHASH('Config') from lib/Config.pm:628 + out $=Config::TIEHASH('Config') from lib/Config.pm:628 + scalar context return from Config::TIEHASH: empty hash + in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 + out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 + scalar context return from Exporter::export: '' + out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 + scalar context return from Exporter::import: '' + +=back + +In all cases shown above, the line indentation shows the call tree. +If bit 2 of C<frame> is set, a line is printed on exit from a +subroutine as well. If bit 4 is set, the arguments are printed +along with the caller info. If bit 8 is set, the arguments are +printed even if they are tied or references. If bit 16 is set, the +return value is printed, too. + +When a package is compiled, a line like this + + Package lib/Carp.pm. + +is printed with proper indentation. + +=head1 Debugging regular expressions + +There are two ways to enable debugging output for regular expressions. + +If your perl is compiled with C<-DDEBUGGING>, you may use the +B<-Dr> flag on the command line. + +Otherwise, one can C<use re 'debug'>, which has effects at +compile time and run time. It is not lexically scoped. + +=head2 Compile-time output + +The debugging output at compile time looks like this: + + compiling RE `[bc]d(ef*g)+h[ij]k$' + size 43 first at 1 + 1: ANYOF(11) + 11: EXACT <d>(13) + 13: CURLYX {1,32767}(27) + 15: OPEN1(17) + 17: EXACT <e>(19) + 19: STAR(22) + 20: EXACT <f>(0) + 22: EXACT <g>(24) + 24: CLOSE1(26) + 26: WHILEM(0) + 27: NOTHING(28) + 28: EXACT <h>(30) + 30: ANYOF(40) + 40: EXACT <k>(42) + 42: EOL(43) + 43: END(0) + anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating) + stclass `ANYOF' minlen 7 + +The first line shows the pre-compiled form of the regex. The second +shows the size of the compiled form (in arbitrary units, usually +4-byte words) and the label I<id> of the first node that does a +match. + +The last line (split into two lines above) contains optimizer +information. In the example shown, the optimizer found that the match +should contain a substring C<de> at offset 1, plus substring C<gh> +at some offset between 3 and infinity. Moreover, when checking for +these substrings (to abandon impossible matches quickly), Perl will check +for the substring C<gh> before checking for the substring C<de>. The +optimizer may also use the knowledge that the match starts (at the +C<first> I<id>) with a character class, and the match cannot be +shorter than 7 chars. + +The fields of interest which may appear in the last line are + +=over + +=item C<anchored> I<STRING> C<at> I<POS> + +=item C<floating> I<STRING> C<at> I<POS1..POS2> + +See above. + +=item C<matching floating/anchored> + +Which substring to check first. + +=item C<minlen> + +The minimal length of the match. + +=item C<stclass> I<TYPE> + +Type of first matching node. + +=item C<noscan> + +Don't scan for the found substrings. + +=item C<isall> + +Means that the optimizer info is all that the regular +expression contains, and thus one does not need to enter the regex engine at +all. + +=item C<GPOS> + +Set if the pattern contains C<\G>. + +=item C<plus> + +Set if the pattern starts with a repeated char (as in C<x+y>). + +=item C<implicit> + +Set if the pattern starts with C<.*>. + +=item C<with eval> + +Set if the pattern contain eval-groups, such as C<(?{ code })> and +C<(??{ code })>. + +=item C<anchored(TYPE)> + +If the pattern may match only at a handful of places, (with C<TYPE> +being C<BOL>, C<MBOL>, or C<GPOS>. See the table below. + +=back + +If a substring is known to match at end-of-line only, it may be +followed by C<$>, as in C<floating `k'$>. + +The optimizer-specific info is used to avoid entering (a slow) regex +engine on strings that will not definitely match. If C<isall> flag +is set, a call to the regex engine may be avoided even when the optimizer +found an appropriate place for the match. + +The rest of the output contains the list of I<nodes> of the compiled +form of the regex. Each line has format + +C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>) + +=head2 Types of nodes + +Here are the possible types, with short descriptions: + + # TYPE arg-description [num-args] [longjump-len] DESCRIPTION + + # Exit points + END no End of program. + SUCCEED no Return from a subroutine, basically. + + # Anchors: + BOL no Match "" at beginning of line. + MBOL no Same, assuming multiline. + SBOL no Same, assuming singleline. + EOS no Match "" at end of string. + EOL no Match "" at end of line. + MEOL no Same, assuming multiline. + SEOL no Same, assuming singleline. + BOUND no Match "" at any word boundary + BOUNDL no Match "" at any word boundary + NBOUND no Match "" at any word non-boundary + NBOUNDL no Match "" at any word non-boundary + GPOS no Matches where last m//g left off. + + # [Special] alternatives + ANY no Match any one character (except newline). + SANY no Match any one character. + ANYOF sv Match character in (or not in) this class. + ALNUM no Match any alphanumeric character + ALNUML no Match any alphanumeric char in locale + NALNUM no Match any non-alphanumeric character + NALNUML no Match any non-alphanumeric char in locale + SPACE no Match any whitespace character + SPACEL no Match any whitespace char in locale + NSPACE no Match any non-whitespace character + NSPACEL no Match any non-whitespace char in locale + DIGIT no Match any numeric character + NDIGIT no Match any non-numeric character + + # BRANCH The set of branches constituting a single choice are hooked + # together with their "next" pointers, since precedence prevents + # anything being concatenated to any individual branch. The + # "next" pointer of the last BRANCH in a choice points to the + # thing following the whole choice. This is also where the + # final "next" pointer of each individual branch points; each + # branch starts with the operand node of a BRANCH node. + # + BRANCH node Match this alternative, or the next... + + # BACK Normal "next" pointers all implicitly point forward; BACK + # exists to make loop structures possible. + # not used + BACK no Match "", "next" ptr points backward. + + # Literals + EXACT sv Match this string (preceded by length). + EXACTF sv Match this string, folded (prec. by length). + EXACTFL sv Match this string, folded in locale (w/len). + + # Do nothing + NOTHING no Match empty string. + # A variant of above which delimits a group, thus stops optimizations + TAIL no Match empty string. Can jump here from outside. + + # STAR,PLUS '?', and complex '*' and '+', are implemented as circular + # BRANCH structures using BACK. Simple cases (one character + # per match) are implemented with STAR and PLUS for speed + # and to minimize recursive plunges. + # + STAR node Match this (simple) thing 0 or more times. + PLUS node Match this (simple) thing 1 or more times. + + CURLY sv 2 Match this simple thing {n,m} times. + CURLYN no 2 Match next-after-this simple thing + # {n,m} times, set parens. + CURLYM no 2 Match this medium-complex thing {n,m} times. + CURLYX sv 2 Match this complex thing {n,m} times. + + # This terminator creates a loop structure for CURLYX + WHILEM no Do curly processing and see if rest matches. + + # OPEN,CLOSE,GROUPP ...are numbered at compile time. + OPEN num 1 Mark this point in input as start of #n. + CLOSE num 1 Analogous to OPEN. + + REF num 1 Match some already matched string + REFF num 1 Match already matched string, folded + REFFL num 1 Match already matched string, folded in loc. + + # grouping assertions + IFMATCH off 1 2 Succeeds if the following matches. + UNLESSM off 1 2 Fails if the following matches. + SUSPEND off 1 1 "Independent" sub-regex. + IFTHEN off 1 1 Switch, should be preceded by switcher . + GROUPP num 1 Whether the group matched. + + # Support for long regex + LONGJMP off 1 1 Jump far away. + BRANCHJ off 1 1 BRANCH with long offset. + + # The heavy worker + EVAL evl 1 Execute some Perl code. + + # Modifiers + MINMOD no Next operator is not greedy. + LOGICAL no Next opcode should set the flag only. + + # This is not used yet + RENUM off 1 1 Group with independently numbered parens. + + # This is not really a node, but an optimized away piece of a "long" node. + # To simplify debugging output, we mark it as if it were a node + OPTIMIZED off Placeholder for dump. + +=head2 Run-time output + +First of all, when doing a match, one may get no run-time output even +if debugging is enabled. This means that the regex engine was never +entered and that all of the job was therefore done by the optimizer. + +If the regex engine was entered, the output may look like this: + + Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__' + Setting an EVAL scope, savestack=3 + 2 <ab> <cdefg__gh_> | 1: ANYOF + 3 <abc> <defg__gh_> | 11: EXACT <d> + 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767} + 4 <abcd> <efg__gh_> | 26: WHILEM + 0 out of 1..32767 cc=effff31c + 4 <abcd> <efg__gh_> | 15: OPEN1 + 4 <abcd> <efg__gh_> | 17: EXACT <e> + 5 <abcde> <fg__gh_> | 19: STAR + EXACT <f> can match 1 times out of 32767... + Setting an EVAL scope, savestack=3 + 6 <bcdef> <g__gh__> | 22: EXACT <g> + 7 <bcdefg> <__gh__> | 24: CLOSE1 + 7 <bcdefg> <__gh__> | 26: WHILEM + 1 out of 1..32767 cc=effff31c + Setting an EVAL scope, savestack=12 + 7 <bcdefg> <__gh__> | 15: OPEN1 + 7 <bcdefg> <__gh__> | 17: EXACT <e> + restoring \1 to 4(4)..7 + failed, try continuation... + 7 <bcdefg> <__gh__> | 27: NOTHING + 7 <bcdefg> <__gh__> | 28: EXACT <h> + failed... + failed... + +The most significant information in the output is about the particular I<node> +of the compiled regex that is currently being tested against the target string. +The format of these lines is + +C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE> + +The I<TYPE> info is indented with respect to the backtracking level. +Other incidental information appears interspersed within. + +=head1 Debugging Perl memory usage + +Perl is a profligate wastrel when it comes to memory use. There +is a saying that to estimate memory usage of Perl, assume a reasonable +algorithm for memory allocation, multiply that estimate by 10, and +while you still may miss the mark, at least you won't be quite so +astonished. This is not absolutely true, but may provide a good +grasp of what happens. + +Assume that an integer cannot take less than 20 bytes of memory, a +float cannot take less than 24 bytes, a string cannot take less +than 32 bytes (all these examples assume 32-bit architectures, the +result are quite a bit worse on 64-bit architectures). If a variable +is accessed in two of three different ways (which require an integer, +a float, or a string), the memory footprint may increase yet another +20 bytes. A sloppy malloc(3) implementation can make inflate these +numbers dramatically. + +On the opposite end of the scale, a declaration like + + sub foo; + +may take up to 500 bytes of memory, depending on which release of Perl +you're running. + +Anecdotal estimates of source-to-compiled code bloat suggest an +eightfold increase. This means that the compiled form of reasonable +(normally commented, properly indented etc.) code will take +about eight times more space in memory than the code took +on disk. + +There are two Perl-specific ways to analyze memory usage: +$ENV{PERL_DEBUG_MSTATS} and B<-DL> command-line switch. The first +is available only if Perl is compiled with Perl's malloc(); the +second only if Perl was built with C<-DDEBUGGING>. See the +instructions for how to do this in the F<INSTALL> podpage at +the top level of the Perl source tree. + +=head2 Using C<$ENV{PERL_DEBUG_MSTATS}> + +If your perl is using Perl's malloc() and was compiled with the +necessary switches (this is the default), then it will print memory +usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS} +> 1 >>, and before termination of the program when C<< +$ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to +the following example: + + $ PERL_DEBUG_MSTATS=2 perl -e "require Carp" + Memory allocation statistics after compilation: (buckets 4(4)..8188(8192) + 14216 free: 130 117 28 7 9 0 2 2 1 0 0 + 437 61 36 0 5 + 60924 used: 125 137 161 55 7 8 6 16 2 0 1 + 74 109 304 84 20 + Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048. + Memory allocation statistics after execution: (buckets 4(4)..8188(8192) + 30888 free: 245 78 85 13 6 2 1 3 2 0 1 + 315 162 39 42 11 + 175816 used: 265 176 1112 111 26 22 11 27 2 1 1 + 196 178 1066 798 39 + Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. + +It is possible to ask for such a statistic at arbitrary points in +your execution using the mstats() function out of the standard +Devel::Peek module. + +Here is some explanation of that format: + +=over + +=item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)> + +Perl's malloc() uses bucketed allocations. Every request is rounded +up to the closest bucket size available, and a bucket is taken from +the pool of buckets of that size. + +The line above describes the limits of buckets currently in use. +Each bucket has two sizes: memory footprint and the maximal size +of user data that can fit into this bucket. Suppose in the above +example that the smallest bucket were size 4. The biggest bucket +would have usable size 8188, and the memory footprint would be 8192. + +In a Perl built for debugging, some buckets may have negative usable +size. This means that these buckets cannot (and will not) be used. +For larger buckets, the memory footprint may be one page greater +than a power of 2. If so, case the corresponding power of two is +printed in the C<APPROX> field above. + +=item Free/Used + +The 1 or 2 rows of numbers following that correspond to the number +of buckets of each size between C<SMALLEST> and C<GREATEST>. In +the first row, the sizes (memory footprints) of buckets are powers +of two--or possibly one page greater. In the second row, if present, +the memory footprints of the buckets are between the memory footprints +of two buckets "above". + +For example, suppose under the previous example, the memory footprints +were + + free: 8 16 32 64 128 256 512 1024 2048 4096 8192 + 4 12 24 48 80 + +With non-C<DEBUGGING> perl, the buckets starting from C<128> have +a 4-byte overhead, and thus a 8192-long bucket may take up to +8188-byte allocations. + +=item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS> + +The first two fields give the total amount of memory perl sbrk(2)ed +(ess-broken? :-) and number of sbrk(2)s used. The third number is +what perl thinks about continuity of returned chunks. So long as +this number is positive, malloc() will assume that it is probable +that sbrk(2) will provide continuous memory. + +Memory allocated by external libraries is not counted. + +=item C<pad: 0> + +The amount of sbrk(2)ed memory needed to keep buckets aligned. + +=item C<heads: 2192> + +Although memory overhead of bigger buckets is kept inside the bucket, for +smaller buckets, it is kept in separate areas. This field gives the +total size of these areas. + +=item C<chain: 0> + +malloc() may want to subdivide a bigger bucket into smaller buckets. +If only a part of the deceased bucket is left unsubdivided, the rest +is kept as an element of a linked list. This field gives the total +size of these chunks. + +=item C<tail: 6144> + +To minimize the number of sbrk(2)s, malloc() asks for more memory. This +field gives the size of the yet unused part, which is sbrk(2)ed, but +never touched. + +=back + +=head2 Example of using B<-DL> switch + +Below we show how to analyse memory usage by + + do 'lib/auto/POSIX/autosplit.ix'; + +The file in question contains a header and 146 lines similar to + + sub getcwd; + +B<WARNING>: The discussion below supposes 32-bit architecture. In +newer releases of Perl, memory usage of the constructs discussed +here is greatly improved, but the story discussed below is a real-life +story. This story is mercilessly terse, and assumes rather more than cursory +knowledge of Perl internals. Type space to continue, `q' to quit. +(Actually, you just want to skip to the next section.) + +Here is the itemized list of Perl allocations performed during parsing +of this file: + + !!! "after" at test.pl line 3. + Id subtot 4 8 12 16 20 24 28 32 36 40 48 56 64 72 80 80+ + 0 02 13752 . . . . 294 . . . . . . . . . . 4 + 0 54 5545 . . 8 124 16 . . . 1 1 . . . . . 3 + 5 05 32 . . . . . . . 1 . . . . . . . . + 6 02 7152 . . . . . . . . . . 149 . . . . . + 7 02 3600 . . . . . 150 . . . . . . . . . . + 7 03 64 . -1 . 1 . . 2 . . . . . . . . . + 7 04 7056 . . . . . . . . . . . . . . . 7 + 7 17 38404 . . . . . . . 1 . . 442 149 . . 147 . + 9 03 2078 17 249 32 . . . . 2 . . . . . . . . + + +To see this list, insert two C<warn('!...')> statements around the call: + + warn('!'); + do 'lib/auto/POSIX/autosplit.ix'; + warn('!!! "after"'); + +and run it with Perl's B<-DL> option. The first warn() will print +memory allocation info before parsing the file and will memorize +the statistics at this point (we ignore what it prints). The second +warn() prints increments with respect to these memorized data. This +is the printout shown above. + +Different I<Id>s on the left correspond to different subsystems of +the perl interpreter. They are just the first argument given to +the perl memory allocation API named New(). To find what C<9 03> +means, just B<grep> the perl source for C<903>. You'll find it in +F<util.c>, function savepvn(). (I know, you wonder why we told you +to B<grep> and then gave away the answer. That's because grepping +the source is good for the soul.) This function is used to store +a copy of an existing chunk of memory. Using a C debugger, one can +see that the function was called either directly from gv_init() or +via sv_magic(), and that gv_init() is called from gv_fetchpv()--which +was itself called from newSUB(). Please stop to catch your breath now. + +B<NOTE>: To reach this point in the debugger and skip the calls to +savepvn() during the compilation of the main program, you should +set a C breakpoint +in Perl_warn(), continue until this point is reached, and I<then> set +a C breakpoint in Perl_savepvn(). Note that you may need to skip a +handful of Perl_savepvn() calls that do not correspond to mass production +of CVs (there are more C<903> allocations than 146 similar lines of +F<lib/auto/POSIX/autosplit.ix>). Note also that C<Perl_> prefixes are +added by macroization code in perl header files to avoid conflicts +with external libraries. + +Anyway, we see that C<903> ids correspond to creation of globs, twice +per glob - for glob name, and glob stringification magic. + +Here are explanations for other I<Id>s above: + +=over + +=item C<717> + +Creates bigger C<XPV*> structures. In the case above, it +creates 3 C<AV>s per subroutine, one for a list of lexical variable +names, one for a scratchpad (which contains lexical variables and +C<targets>), and one for the array of scratchpads needed for +recursion. + +It also creates a C<GV> and a C<CV> per subroutine, all called from +start_subparse(). + +=item C<002> + +Creates a C array corresponding to the C<AV> of scratchpads and the +scratchpad itself. The first fake entry of this scratchpad is +created though the subroutine itself is not defined yet. + +It also creates C arrays to keep data for the stash. This is one HV, +but it grows; thus, there are 4 big allocations: the big chunks are not +freed, but are kept as additional arenas for C<SV> allocations. + +=item C<054> + +Creates a C<HEK> for the name of the glob for the subroutine. This +name is a key in a I<stash>. + +Big allocations with this I<Id> correspond to allocations of new +arenas to keep C<HE>. + +=item C<602> + +Creates a C<GP> for the glob for the subroutine. + +=item C<702> + +Creates the C<MAGIC> for the glob for the subroutine. + +=item C<704> + +Creates I<arenas> which keep SVs. + +=back + +=head2 B<-DL> details + +If Perl is run with B<-DL> option, then warn()s that start with `!' +behave specially. They print a list of I<categories> of memory +allocations, and statistics of allocations of different sizes for +these categories. + +If warn() string starts with + +=over + +=item C<!!!> + +print changed categories only, print the differences in counts of allocations. + +=item C<!!> + +print grown categories only; print the absolute values of counts, and totals. + +=item C<!> + +print nonempty categories, print the absolute values of counts and totals. + +=back + +=head2 Limitations of B<-DL> statistics + +If an extension or external library does not use the Perl API to +allocate memory, such allocations are not counted. + +=head1 SEE ALSO + +L<perldebug>, +L<perlguts>, +L<perlrun> +L<re>, +and +L<Devel::Dprof>. diff --git a/pod/perldebug.pod b/pod/perldebug.pod index fe2418457e..c8ef60fa45 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -8,15 +8,6 @@ First of all, have you tried using the B<-w> switch? =head1 The Perl Debugger -"As soon as we started programming, we found to our -surprise that it wasn't as easy to get programs right -as we had thought. Debugging had to be discovered. -I can remember the exact instant when I realized that -a large part of my life from then on was going to be -spent in finding mistakes in my own programs." - -I< --Maurice Wilkes, 1949> - If you invoke Perl with the B<-d> switch, your script runs under the Perl source debugger. This works like an interactive Perl environment, prompting for debugger commands that let you examine @@ -25,14 +16,14 @@ variables, etc. This is so convenient that you often fire up the debugger all by itself just to test out Perl constructs interactively to see what they do. For example: - perl -d -e 42 + $ perl -d -e 42 -In Perl, the debugger is not a separate program as it usually is in the +In Perl, the debugger is not a separate program the way it usually is in the typical compiled environment. Instead, the B<-d> flag tells the compiler to insert source information into the parse trees it's about to hand off to the interpreter. That means your code must first compile correctly for the debugger to work on it. Then when the interpreter starts up, it -preloads a Perl library file containing the debugger itself. +preloads a special Perl library file containing the debugger. The program will halt I<right before> the first run-time executable statement (but see below regarding compile-time statements) and ask you @@ -41,12 +32,15 @@ the debugger halts and shows you a line of code, it always displays the line it's I<about> to execute, rather than the one it has just executed. Any command not recognized by the debugger is directly executed -(C<eval>'d) as Perl code in the current package. (The debugger uses the -DB package for its own state information.) +(C<eval>'d) as Perl code in the current package. (The debugger +uses the DB package for keeping its own state information.) -Leading white space before a command would cause the debugger to think -it's I<NOT> a debugger command but for Perl, so be careful not to do -that. +For any text entered at the debugger prompt, leading and trailing whitespace +is first stripped before further processing. If a debugger command +coincides with some function in your own program, merely precede the +function with something that doesn't look like a debugger command, such +as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses +or braces. =head2 Debugger Commands @@ -64,8 +58,8 @@ argument of C<h h> produces a more compact help listing, designed to fit together on one screen. If the output of the C<h> command (or any command, for that matter) scrolls -past your screen, either precede the command with a leading pipe symbol so -it's run through your pager, as in +past your screen, precede the command with a leading pipe symbol so +that it's run through your pager, as in DB> |h @@ -74,7 +68,7 @@ You may change the pager which is used via C<O pager=...> command. =item p expr Same as C<print {$DB::OUT} expr> in the current package. In particular, -because this is just Perl's own B<print> function, this means that nested +because this is just Perl's own C<print> function, this means that nested data structures and objects are not dumped, unlike with the C<x> command. The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of @@ -84,26 +78,25 @@ where STDOUT may be redirected to. Evaluates its expression in list context and dumps out the result in a pretty-printed fashion. Nested data structures are printed out -recursively, unlike the C<print> function. +recursively, unlike the real C<print> function in Perl. +See L<Dumpvalue> if you'd like to do this yourself. -The details of printout are governed by multiple C<O>ptions. +The output format is governed by multiple options described under +L<"Options">. =item V [pkg [vars]] -Display all (or some) variables in package (defaulting to the C<main> -package) using a data pretty-printer (hashes show their keys and values so -you see what's what, control characters are made printable, etc.). Make -sure you don't put the type specifier (like C<$>) there, just the symbol -names, like this: +Display all (or some) variables in package (defaulting to C<main>) +using a data pretty-printer (hashes show their keys and values so +you see what's what, control characters are made printable, etc.). +Make sure you don't put the type specifier (like C<$>) there, just +the symbol names, like this: V DB filename line -Use C<~pattern> and C<!pattern> for positive and negative regexps. - -Nested data structures are printed out in a legible fashion, unlike -the C<print> function. +Use C<~pattern> and C<!pattern> for positive and negative regexes. -The details of printout are governed by multiple C<O>ptions. +This is similar to calling the C<x> command on each applicable var. =item X [vars] @@ -115,21 +108,21 @@ Produce a stack backtrace. See below for details on its output. =item s [expr] -Single step. Executes until it reaches the beginning of another +Single step. Executes until the beginning of another statement, descending into subroutine calls. If an expression is supplied that includes function calls, it too will be single-stepped. =item n [expr] -Next. Executes over subroutine calls, until it reaches the beginning +Next. Executes over subroutine calls, until the beginning of the next statement. If an expression is supplied that includes function calls, those functions will be executed with stops before each statement. =item r -Continue until return from the current subroutine. Dump the return -value, if the PrintRet option is set (default). +Continue until the return from the current subroutine. +Dump the return value if the C<PrintRet> option is set (default). =item <CR> @@ -159,7 +152,7 @@ List a single line. =item l subname List first window of lines from subroutine. I<subname> may -be a variable which contains a code reference. +be a variable that contains a code reference. =item - @@ -171,24 +164,24 @@ List window (a few lines) around the current line. =item . -Return debugger pointer to the last-executed line and -print it out. +Return the internal debugger pointer to the line last +executed, and print out that line. =item f filename -Switch to viewing a different file or eval statement. If C<filename> -is not a full filename as found in values of %INC, it is considered as -a regexp. +Switch to viewing a different file or C<eval> statement. If I<filename> +is not a full pathname found in the values of %INC, it is considered +a regex. C<eval>ed strings (when accessible) are considered to be filenames: C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string -(in the order of execution). The bodies of currently executed C<eval> -and of C<eval>ed strings which define subroutines are saved, thus are -accessible by this mechanism. +(in the order of execution). The bodies of the currently executed C<eval> +and of C<eval>ed strings that define subroutines are saved and thus +accessible. =item /pattern/ -Search forwards for pattern; final / is optional. +Search forwards for pattern (a Perl regex); final / is optional. =item ?pattern? @@ -198,58 +191,27 @@ Search backwards for pattern; final ? is optional. List all breakpoints and actions. -=item S [[!]pattern] +=item S [[!]regex] -List subroutine names [not] matching pattern. +List subroutine names [not] matching the regex. =item t -Toggle trace mode (see also C<AutoTrace> C<O>ption). +Toggle trace mode (see also the C<AutoTrace> option). =item t expr -Trace through execution of expr. For example: - - $ perl -de 42 - Stack dump during die enabled outside of evals. - - Loading DB routines from perl5db.pl patch level 0.94 - Emacs support available. - - Enter h or `h h' for help. - - main::(-e:1): 0 - DB<1> sub foo { 14 } - - DB<2> sub bar { 3 } - - DB<3> t print foo() * bar() - main::((eval 172):3): print foo() + bar(); - main::foo((eval 168):2): - main::bar((eval 170):2): - 42 - -or, with the C<O>ption C<frame=2> set, - - DB<4> O f=2 - frame = '2' - DB<5> t print foo() * bar() - 3: foo() * bar() - entering main::foo - 2: sub foo { 14 }; - exited main::foo - entering main::bar - 2: sub bar { 3 }; - exited main::bar - 42 +Trace through execution of C<expr>. +See L<perldebguts/"Frame Listing Output Examples"> for examples. =item b [line] [condition] -Set a breakpoint. If line is omitted, sets a breakpoint on the line -that is about to be executed. If a condition is specified, it's -evaluated each time the statement is reached and a breakpoint is taken -only if the condition is true. Breakpoints may be set on only lines -that begin an executable statement. Conditions don't use B<if>: +Set a breakpoint before the given line. If I<line> is omitted, set a +breakpoint on the line about to be executed. If a condition +is specified, it's evaluated each time the statement is reached: a +breakpoint is taken only if the condition is true. Breakpoints may +only be set on lines that begin an executable statement. Conditions +don't use C<if>: b 237 $x > 30 b 237 ++$count237 < 11 @@ -257,28 +219,28 @@ that begin an executable statement. Conditions don't use B<if>: =item b subname [condition] -Set a breakpoint at the first line of the named subroutine. I<subname> may -be a variable which contains a code reference (in this case I<condition> +Set a breakpoint before the first line of the named subroutine. I<subname> may +be a variable containing a code reference (in this case I<condition> is not supported). =item b postpone subname [condition] -Set breakpoint at first line of subroutine after it is compiled. +Set a breakpoint at first line of subroutine after it is compiled. =item b load filename -Set breakpoint at the first executed line of the file. Filename should -be a full name as found in values of %INC. +Set a breakpoint before the first executed line of the I<filename>, +which should be a full pathname found amongst the %INC values. =item b compile subname -Sets breakpoint at the first statement executed after the subroutine -is compiled. +Sets a breakpoint before the first statement executed after the specified +subroutine is compiled. =item d [line] -Delete a breakpoint at the specified line. If line is omitted, deletes -the breakpoint on the line that is about to be executed. +Delete a breakpoint from the specified I<line>. If I<line> is omitted, deletes +the breakpoint from the line about to be executed. =item D @@ -286,8 +248,8 @@ Delete all installed breakpoints. =item a [line] command -Set an action to be done before the line is executed. If line is -omitted, sets an action on the line that is about to be executed. +Set an action to be done before the line is executed. If I<line> is +omitted, set an action on the line about to be executed. The sequence of steps taken by the debugger is 1. check for a breakpoint at this line @@ -303,38 +265,222 @@ For example, this will print out $foo every time line =item a [line] -Delete an action at the specified line. If line is omitted, deletes +Delete an action from the specified line. If I<line> is omitted, delete the action on the line that is about to be executed. =item A Delete all installed actions. -=item W [expr] +=item W expr -Add a global watch-expression. +Add a global watch-expression. We hope you know what one of these +is, because they're supposed to be obvious. B<WARNING>: It is far +too easy to destroy your watch expressions by accidentally omitting +the I<expr>. =item W Delete all watch-expressions. -=item O [opt[=val]] [opt"val"] [opt?]... +=item O booloption ... + +Set each listed Boolean option to the value C<1>. + +=item O anyoption? ... + +Print out the value of one or more options. + +=item O option=value ... + +Set the value of one or more options. If the value has internal +whitespace, it should be quoted. For example, you could set C<O +pager="less -MQeicsNfr"> to call B<less> with those specific options. +You may use either single or double quotes, but if you do, you must +escape any embedded instances of same sort of quote you began with, +as well as any escaping any escapes that immediately precede that +quote but which are not meant to escape the quote itself. In other +words, you follow single-quoting rules irrespective of the quote; +eg: C<O option='this isn\'t bad'> or C<O option="She said, \"Isn't +it?\"">. + +For historical reasons, the C<=value> is optional, but defaults to +1 only where it is safe to do so--that is, mostly for Boolean +options. It is always better to assign a specific value using C<=>. +The C<option> can be abbreviated, but for clarity probably should +not be. Several options can be set together. See L<"Options"> for +a list of these. + +=item < ? + +List out all pre-prompt Perl command actions. + +=item < [ command ] + +Set an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backslashing the newlines. +B<WARNING> If C<command> is missing, all actions are wiped out! + +=item << command + +Add an action (Perl command) to happen before every debugger prompt. +A multi-line command may be entered by backwhacking the newlines. + +=item > ? + +List out post-prompt Perl command actions. + +=item > command + +Set an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by backslashing the newlines (we bet you +couldn't've guessed this by now). B<WARNING> If C<command> is +missing, all actions are wiped out! + +=item >> command + +Adds an action (Perl command) to happen after the prompt when you've +just given a command to return to executing the script. A multi-line +command may be entered by slackbashing the newlines. + +=item { ? + +List out pre-prompt debugger commands. + +=item { [ command ] + +Set an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered in the customary fashion. +B<WARNING> If C<command> is missing, all actions are wiped out! + +Because this command is in some senses new, a warning is issued if +you appear to have accidentally entered a block instead. If that's +what you mean to do, write it as with C<;{ ... }> or even +C<do { ... }>. + +=item {{ command + +Add an action (debugger command) to happen before every debugger prompt. +A multi-line command may be entered, if you can guess how: see above. + +=item ! number + +Redo a previous command (defaults to the previous command). + +=item ! -number + +Redo number'th previous command. + +=item ! pattern + +Redo last command that started with pattern. +See C<O recallCommand>, too. + +=item !! cmd + +Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See +C<O shellBang>, also. Note that the user's current shell (well, +their C<$ENV{SHELL}> variable) will be used, which can interfere +with proper interpretation of exit status or signal and coredump +information. + +=item H -number + +Display last n commands. Only commands longer than one character are +listed. If I<number> is omitted, list them all. + +=item q or ^D + +Quit. ("quit" doesn't work for this, unless you've made an alias) +This is the only supported way to exit the debugger, though typing +C<exit> twice might work. + +Set the C<inhibit_exit> option to 0 if you want to be able to step +off the end the script. You may also need to set $finished to 0 +if you want to step through global destruction. + +=item R + +Restart the debugger by C<exec()>ing a new session. We try to maintain +your history across this, but internal settings and command-line options +may be lost. + +The following setting are currently preserved: history, breakpoints, +actions, debugger options, and the Perl command-line +options B<-w>, B<-I>, and B<-e>. + +=item |dbcmd + +Run the debugger command, piping DB::OUT into your current pager. + +=item ||dbcmd + +Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well. + +=item = [alias value] + +Define a command alias, like + + = quit q + +or list current aliases. + +=item command + +Execute command as a Perl statement. A trailing semicolon will be +supplied. If the Perl statement would otherwise be confused for a +Perl debugger, use a leading semicolon, too. + +=item m expr + +List which methods may be called on the result of the evaluated +expression. The expression may evaluated to a reference to a +blessed object, or to a package name. + +=item man [manpage] + +Despite its name, this calls your system's default documentation +viewer on the given page, or on the viewer itself if I<manpage> is +omitted. If that viewer is B<man>, the current C<Config> information +is used to invoke B<man> using the proper MANPATH or S<B<-M> +I<manpath>> option. Failed lookups of the form C<XXX> that match +known manpages of the form I<perlXXX> will be retried. This lets +you type C<man debug> or C<man op> from the debugger. -Set or query values of options. val defaults to 1. opt can -be abbreviated. Several options can be listed. +On systems traditionally bereft of a usable B<man> command, the +debugger invokes B<perldoc>. Occasionally this determination is +incorrect due to recalcitrant vendors or rather more felicitously, +to enterprising users. If you fall into either category, just +manually set the $DB::doccmd variable to whatever viewer to view +the Perl documentation on your system. This may be set in an rc +file, or through direct assignment. We're still waiting for a +working example of something along the lines of: + + $DB::doccmd = 'netscape -remote http://something.here/'; + +=back + +=head2 Configurable Options + +The debugger has numerous options settable using the C<O> command, +either interactively or from the environment or an rc file. =over 12 =item C<recallCommand>, C<ShellBang> The characters used to recall command or spawn shell. By -default, these are both set to C<!>. +default, both are set to C<!>, which is unfortunate. =item C<pager> -Program to use for output of pager-piped commands (those -beginning with a C<|> character.) By default, -C<$ENV{PAGER}> will be used. +Program to use for output of pager-piped commands (those beginning +with a C<|> character.) By default, C<$ENV{PAGER}> will be used. +Because the debugger uses your current terminal characteristics +for bold and underlining, if the chosen pager does not pass escape +sequences through unchanged, the output of some debugger commands +will not be readable when sent through the pager. =item C<tkRunning> @@ -342,14 +488,23 @@ Run Tk while prompting (with ReadLine). =item C<signalLevel>, C<warnLevel>, C<dieLevel> -Level of verbosity. By default the debugger is in a sane verbose mode, -thus it will print backtraces on all the warnings and die-messages -which are going to be printed out, and will print a message when -interesting uncaught signals arrive. - -To disable this behaviour, set these values to 0. If C<dieLevel> is 2, -then the messages which will be caught by surrounding C<eval> are also -printed. +Level of verbosity. By default, the debugger leaves your exceptions +and warnings alone, because altering them can break correctly running +programs. It will attempt to print a message when uncaught INT, BUS, or +SEGV signals arrive. (But see the mention of signals in L<BUGS> below.) + +To disable this default safe mode, set these values to something higher +than 0. At a level of 1, you get backtraces upon receiving any kind +of warning (this is often annoying) or exception (this is +often valuable). Unfortunately, the debugger cannot discern fatal +exceptions from non-fatal ones. If C<dieLevel> is even 1, then your +non-fatal exceptions are also traced and unceremoniously altered if they +came from C<eval'd> strings or from any kind of C<eval> within modules +you're attempting to load. If C<dieLevel> is 2, the debugger doesn't +care where they came from: It usurps your exception handler and prints +out a trace, then modifies all exceptions with its own embellishments. +This may perhaps be useful for some tracing purposes, but tends to hopelessly +destroy any program that takes its exception handling seriously. =item C<AutoTrace> @@ -359,7 +514,10 @@ C<PERLDB_OPTS>). =item C<LineInfo> File or pipe to print line number info to. If it is a pipe (say, -C<|visual_perl_db>), then a short, "emacs like" message is used. +C<|visual_perl_db>), then a short message is used. This is the +mechanism used to interact with a slave editor or visual debugger, +such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical +debugger. =item C<inhibit_exit> @@ -371,25 +529,28 @@ Print return value after C<r> command if set (default). =item C<ornaments> -affects screen appearance of the command line (see L<Term::ReadLine>). +Affects screen appearance of the command line (see L<Term::ReadLine>). +There is currently no way to disable these, which can render +some output illegible on some displays, or with some pagers. +This is considered a bug. =item C<frame> -affects printing messages on entry and exit from subroutines. If +Affects the printing of messages upon entry and exit from subroutines. If C<frame & 2> is false, messages are printed on entry only. (Printing -on exit may be useful if inter(di)spersed with other messages.) +on exit might be useful if interspersed with other messages.) -If C<frame & 4>, arguments to functions are printed as well as the -context and caller info. If C<frame & 8>, overloaded C<stringify> and -C<tie>d C<FETCH> are enabled on the printed arguments. If C<frame & -16>, the return value from the subroutine is printed as well. +If C<frame & 4>, arguments to functions are printed, plus context +and caller info. If C<frame & 8>, overloaded C<stringify> and +C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame +& 16>, the return value from the subroutine is printed. The length at which the argument list is truncated is governed by the next option: =item C<maxTraceLen> -length at which the argument list is truncated when C<frame> option's +Length to truncate the argument list when the C<frame> option's bit 4 is set. =back @@ -405,7 +566,7 @@ Print only first N elements ('' for all). =item C<compactDump>, C<veryCompact> -Change style of array and hash dump. If C<compactDump>, short array +Change the style of array and hash output. If C<compactDump>, short array may be printed on one line. =item C<globPrint> @@ -426,29 +587,30 @@ Dump contents of "reused" addresses. =item C<quote>, C<HighBit>, C<undefPrint> -Change style of string dump. Default value of C<quote> is C<auto>, one -can enable either double-quotish dump, or single-quotish by setting it -to C<"> or C<'>. By default, characters with high bit set are printed -I<as is>. +Change the style of string dump. The default value for C<quote> +is C<auto>; one can enable double-quotish or single-quotish format +by setting it to C<"> or C<'>, respectively. By default, characters +with their high bit set are printed verbatim. =item C<UsageOnly> -I<very> rudimentally per-package memory usage dump. Calculates total -size of strings in variables in the package. +Rudimentary per-package memory usage dump. Calculates total +size of strings found in variables in the package. This does not +include lexicals in a module's file scope, or lost in closures. =back -During startup options are initialized from C<$ENV{PERLDB_OPTS}>. -You can put additional initialization options C<TTY>, C<noTTY>, +During startup, options are initialized from C<$ENV{PERLDB_OPTS}>. +You may place the initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop> there. -Example rc file: +If your rc file contains: - &parse_options("NonStop=1 LineInfo=db.out AutoTrace"); + parse_options("NonStop=1 LineInfo=db.out AutoTrace"); -The script will run without human intervention, putting trace information -into the file I<db.out>. (If you interrupt it, you would better reset -C<LineInfo> to something "interactive"!) +then your script will run without human intervention, putting trace +information into the file I<db.out>. (If you interrupt it, you'd +better reset C<LineInfo> to F</dev/tty> if you expect to see anything.) =over 12 @@ -458,173 +620,65 @@ The TTY to use for debugging I/O. =item C<noTTY> -If set, goes in C<NonStop> mode, and would not connect to a TTY. If -interrupt (or if control goes to debugger via explicit setting of -$DB::signal or $DB::single from the Perl script), connects to a TTY -specified by the C<TTY> option at startup, or to a TTY found at -runtime using C<Term::Rendezvous> module of your choice. +If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If +interrupted (or if control goes to the debugger via explicit setting of +$DB::signal or $DB::single from the Perl script), it connects to a TTY +specified in the C<TTY> option at startup, or to a tty found at +runtime using the C<Term::Rendezvous> module of your choice. -This module should implement a method C<new> which returns an object -with two methods: C<IN> and C<OUT>, returning two filehandles to use -for debugging input and output correspondingly. Method C<new> may -inspect an argument which is a value of C<$ENV{PERLDB_NOTTY}> at -startup, or is C<"/tmp/perldbtty$$"> otherwise. +This module should implement a method named C<new> that returns an object +with two methods: C<IN> and C<OUT>. These should return filehandles to use +for debugging input and output correspondingly. The C<new> method should +inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at +startup, or C<"/tmp/perldbtty$$"> otherwise. This file is not +inspected for proper ownership, so security hazards are theoretically +possible. =item C<ReadLine> -If false, readline support in debugger is disabled, so you can debug -ReadLine applications. +If false, readline support in the debugger is disabled in order +to debug applications that themselves use ReadLine. =item C<NonStop> -If set, debugger goes into noninteractive mode until interrupted, or +If set, the debugger goes into non-interactive mode until interrupted, or programmatically by setting $DB::signal or $DB::single. =back Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: - $ PERLDB_OPTS="N f=2" perl -d myprogram + $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram -will run the script C<myprogram> without human intervention, printing -out the call tree with entry and exit points. Note that C<N f=2> is -equivalent to C<NonStop=1 frame=2>. Note also that at the moment when -this documentation was written all the options to the debugger could -be uniquely abbreviated by the first letter (with exception of -C<Dump*> options). +That will run the script B<myprogram> without human intervention, +printing out the call tree with entry and exit points. Note that +C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally, +options could be uniquely abbreviated by the first letter (modulo +the C<Dump*> options). It is nevertheless recommended that you +always spell them out in full for legibility and future compatibility. -Other examples may include +Other examples include - $ PERLDB_OPTS="N f A L=listing" perl -d myprogram + $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram -- runs script noninteractively, printing info on each entry into a -subroutine and each executed line into the file F<listing>. (If you -interrupt it, you would better reset C<LineInfo> to something +which runs script non-interactively, printing info on each entry +into a subroutine and each executed line into the file named F<listing>. +(If you interrupt it, you would better reset C<LineInfo> to something "interactive"!) +Other examples include (using standard shell syntax to show environment +variable settings): - $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram + $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" + perl -d myprogram ) -may be useful for debugging a program which uses C<Term::ReadLine> -itself. Do not forget detach shell from the TTY in the window which -corresponds to F</dev/ttyc>, say, by issuing a command like +which may be useful for debugging a program that uses C<Term::ReadLine> +itself. Do not forget to detach your shell from the TTY in the window that +corresponds to F</dev/ttyXX>, say, by issuing a command like $ sleep 1000000 -See L<"Debugger Internals"> below for more details. - -=item < [ command ] - -Set an action (Perl command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. If -C<command> is missing, resets the list of actions. - -=item << command - -Add an action (Perl command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. - -=item > command - -Set an action (Perl command) to happen after the prompt when you've -just given a command to return to executing the script. A multi-line -command may be entered by backslashing the newlines. If C<command> is -missing, resets the list of actions. - -=item >> command - -Adds an action (Perl command) to happen after the prompt when you've -just given a command to return to executing the script. A multi-line -command may be entered by backslashing the newlines. - -=item { [ command ] - -Set an action (debugger command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. If -C<command> is missing, resets the list of actions. - -=item {{ command - -Add an action (debugger command) to happen before every debugger prompt. -A multi-line command may be entered by backslashing the newlines. - -=item ! number - -Redo a previous command (default previous command). - -=item ! -number - -Redo number'th-to-last command. - -=item ! pattern - -Redo last command that started with pattern. -See C<O recallCommand>, too. - -=item !! cmd - -Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) -See C<O shellBang> too. - -=item H -number - -Display last n commands. Only commands longer than one character are -listed. If number is omitted, lists them all. - -=item q or ^D - -Quit. ("quit" doesn't work for this.) This is the only supported way -to exit the debugger, though typing C<exit> twice may do it too. - -Set an C<O>ption C<inhibit_exit> to 0 if you want to be able to I<step -off> the end the script. You may also need to set $finished to 0 at -some moment if you want to step through global destruction. - -=item R - -Restart the debugger by B<exec>ing a new session. It tries to maintain -your history across this, but internal settings and command line options -may be lost. - -Currently the following setting are preserved: history, breakpoints, -actions, debugger C<O>ptions, and the following command line -options: B<-w>, B<-I>, and B<-e>. - -=item |dbcmd - -Run debugger command, piping DB::OUT to current pager. - -=item ||dbcmd - -Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well. -Often used with commands that would otherwise produce long -output, such as - - |V main - -=item = [alias value] - -Define a command alias, like - - = quit q - -or list current aliases. - -=item command - -Execute command as a Perl statement. A missing semicolon will be -supplied. - -=item m expr - -The expression is evaluated, and the methods which may be applied to -the result are listed. - -=item m package - -The methods which may be applied to objects in the C<package> are listed. - -=back +See L<perldebguts/"Debugger Internals"> for details. =head2 Debugger input/output @@ -640,19 +694,20 @@ or even DB<<17>> -where that number is the command number, which you'd use to access with -the builtin B<csh>-like history mechanism, e.g., C<!17> would repeat -command number 17. The number of angle brackets indicates the depth of -the debugger. You could get more than one set of brackets, for example, if -you'd already at a breakpoint and then printed out the result of a -function call that itself also has a breakpoint, or you step into an -expression via C<s/n/t expression> command. +where that number is the command number, and which you'd use to +access with the built-in B<csh>-like history mechanism. For example, +C<!17> would repeat command number 17. The depth of the angle +brackets indicates the nesting depth of the debugger. You could +get more than one set of brackets, for example, if you'd already +at a breakpoint and then printed the result of a function call that +itself has a breakpoint, or you step into an expression via C<s/n/t +expression> command. =item Multiline commands If you want to enter a multi-line command, such as a subroutine -definition with several statements, or a format, you may escape the -newline that would normally end the debugger command with a backslash. +definition with several statements or a format, escape the newline +that would normally end the debugger command with a backslash. Here's an example: DB<1> for (1..4) { \ @@ -675,24 +730,26 @@ look like: @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7 $ = main::pests('bactrian', 4) called from file `camel_flea' line 4 -The left-hand character up there tells whether the function was called -in a scalar or list context (we bet you can tell which is which). What -that says is that you were in the function C<main::infested> when you ran -the stack dump, and that it was called in a scalar context from line 10 -of the file I<Ambulation.pm>, but without any arguments at all, meaning -it was called as C<&infested>. The next stack frame shows that the -function C<Ambulation::legs> was called in a list context from the -I<camel_flea> file with four arguments. The last stack frame shows that -C<main::pests> was called in a scalar context, also from I<camel_flea>, -but from line 4. +The left-hand character up there indicates the context in which the +function was called, with C<$> and C<@> meaning scalar or list +contexts respectively, and C<.> meaning void context (which is +actually a sort of scalar context). The display above says +that you were in the function C<main::infested> when you ran the +stack dump, and that it was called in scalar context from line +10 of the file I<Ambulation.pm>, but without any arguments at all, +meaning it was called as C<&infested>. The next stack frame shows +that the function C<Ambulation::legs> was called in list context +from the I<camel_flea> file with four arguments. The last stack +frame shows that C<main::pests> was called in scalar context, +also from I<camel_flea>, but from line 4. -Note that if you execute C<T> command from inside an active C<use> -statement, the backtrace will contain both C<require> -frame and an C<eval>) frame. +If you execute the C<T> command from inside an active C<use> +statement, the backtrace will contain both a C<require> frame and +an C<eval>) frame. -=item Listing +=item Line Listing Format -Listing given via different flavors of C<l> command looks like this: +This shows the sorts of output the C<l> command can produce: DB<<13>> l 101: @i{@i} = (); @@ -706,976 +763,185 @@ Listing given via different flavors of C<l> command looks like this: 109:a if ($extra-- > 0) { 110: %isa = ($pack,1); -Note that the breakable lines are marked with C<:>, lines with -breakpoints are marked by C<b>, with actions by C<a>, and the -next executed line is marked by C<< ==> >>. +Breakable lines are marked with C<:>. Lines with breakpoints are +marked by C<b> and those with actions by C<a>. The line that's +about to be executed is marked by C<< ==> >>. =item Frame listing -When C<frame> option is set, debugger would print entered (and -optionally exited) subroutines in different styles. - -What follows is the start of the listing of - - env "PERLDB_OPTS=f=n N" perl -d -V - -for different values of C<n>: - -=over 4 - -=item 1 - - entering main::BEGIN - entering Config::BEGIN - Package lib/Exporter.pm. - Package lib/Carp.pm. - Package lib/Config.pm. - entering Config::TIEHASH - entering Exporter::import - entering Exporter::export - entering Config::myconfig - entering Config::FETCH - entering Config::FETCH - entering Config::FETCH - entering Config::FETCH - -=item 2 - - entering main::BEGIN - entering Config::BEGIN - Package lib/Exporter.pm. - Package lib/Carp.pm. - exited Config::BEGIN - Package lib/Config.pm. - entering Config::TIEHASH - exited Config::TIEHASH - entering Exporter::import - entering Exporter::export - exited Exporter::export - exited Exporter::import - exited main::BEGIN - entering Config::myconfig - entering Config::FETCH - exited Config::FETCH - entering Config::FETCH - exited Config::FETCH - entering Config::FETCH - -=item 4 - - in $=main::BEGIN() from /dev/nul:0 - in $=Config::BEGIN() from lib/Config.pm:2 - Package lib/Exporter.pm. - Package lib/Carp.pm. - Package lib/Config.pm. - in $=Config::TIEHASH('Config') from lib/Config.pm:644 - in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 - in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li - in @=Config::myconfig() from /dev/nul:0 - in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574 - -=item 6 - - in $=main::BEGIN() from /dev/nul:0 - in $=Config::BEGIN() from lib/Config.pm:2 - Package lib/Exporter.pm. - Package lib/Carp.pm. - out $=Config::BEGIN() from lib/Config.pm:0 - Package lib/Config.pm. - in $=Config::TIEHASH('Config') from lib/Config.pm:644 - out $=Config::TIEHASH('Config') from lib/Config.pm:644 - in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 - in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ - out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/ - out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 - out $=main::BEGIN() from /dev/nul:0 - in @=Config::myconfig() from /dev/nul:0 - in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 - out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 - out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 - out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574 - in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574 - -=item 14 - - in $=main::BEGIN() from /dev/nul:0 - in $=Config::BEGIN() from lib/Config.pm:2 - Package lib/Exporter.pm. - Package lib/Carp.pm. - out $=Config::BEGIN() from lib/Config.pm:0 - Package lib/Config.pm. - in $=Config::TIEHASH('Config') from lib/Config.pm:644 - out $=Config::TIEHASH('Config') from lib/Config.pm:644 - in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 - in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E - out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E - out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0 - out $=main::BEGIN() from /dev/nul:0 - in @=Config::myconfig() from /dev/nul:0 - in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 - out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574 - in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 - out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574 - -=item 30 - - in $=CODE(0x15eca4)() from /dev/null:0 - in $=CODE(0x182528)() from lib/Config.pm:2 - Package lib/Exporter.pm. - out $=CODE(0x182528)() from lib/Config.pm:0 - scalar context return from CODE(0x182528): undef - Package lib/Config.pm. - in $=Config::TIEHASH('Config') from lib/Config.pm:628 - out $=Config::TIEHASH('Config') from lib/Config.pm:628 - scalar context return from Config::TIEHASH: empty hash - in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 - in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 - out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171 - scalar context return from Exporter::export: '' - out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0 - scalar context return from Exporter::import: '' - - -=back - -In all the cases indentation of lines shows the call tree, if bit 2 of -C<frame> is set, then a line is printed on exit from a subroutine as -well, if bit 4 is set, then the arguments are printed as well as the -caller info, if bit 8 is set, the arguments are printed even if they -are tied or references, if bit 16 is set, the return value is printed -as well. - -When a package is compiled, a line like this - - Package lib/Carp.pm. - -is printed with proper indentation. +When the C<frame> option is set, the debugger would print entered (and +optionally exited) subroutines in different styles. See L<perldebguts> +for incredibly long examples of these. =back =head2 Debugging compile-time statements -If you have any compile-time executable statements (code within a BEGIN -block or a C<use> statement), these will C<NOT> be stopped by debugger, -although C<require>s will (and compile-time statements can be traced -with C<AutoTrace> option set in C<PERLDB_OPTS>). From your own Perl -code, however, you can +If you have compile-time executable statements (such as code within +BEGIN and CHECK blocks or C<use> statements), these will I<not> be +stopped by debugger, although C<require>s and INIT blocks will, and +compile-time statements can be traced with C<AutoTrace> option set +in C<PERLDB_OPTS>). From your own Perl code, however, you can transfer control back to the debugger using the following statement, which is harmless if the debugger is not running: $DB::single = 1; -If you set C<$DB::single> to the value 2, it's equivalent to having +If you set C<$DB::single> to 2, it's equivalent to having just typed the C<n> command, whereas a value of 1 means the C<s> command. The C<$DB::trace> variable should be set to 1 to simulate having typed the C<t> command. -Another way to debug compile-time code is to start debugger, set a -breakpoint on I<load> of some module thusly +Another way to debug compile-time code is to start the debugger, set a +breakpoint on the I<load> of some module: DB<7> b load f:/perllib/lib/Carp.pm Will stop on load of `f:/perllib/lib/Carp.pm'. -and restart debugger by C<R> command (if possible). One can use C<b +and then restart the debugger using the C<R> command (if possible). One can use C<b compile subname> for the same purpose. =head2 Debugger Customization -Most probably you do not want to modify the debugger, it contains enough -hooks to satisfy most needs. You may change the behaviour of debugger -from the debugger itself, using C<O>ptions, from the command line via -C<PERLDB_OPTS> environment variable, and from I<customization files>. +The debugger probably contains enough configuration hooks that you +won't ever have to modify it yourself. You may change the behaviour +of debugger from within the debugger using its C<O> command, from +the command line via the C<PERLDB_OPTS> environment variable, and +from customization files. -You can do some customization by setting up a F<.perldb> file which +You can do some customization by setting up a F<.perldb> file, which contains initialization code. For instance, you could make aliases like these (the last one is one people expect to be there): $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; $DB::alias{'stop'} = 's/^stop (at|in)/b/'; $DB::alias{'ps'} = 's/^ps\b/p scalar /'; - $DB::alias{'quit'} = 's/^quit(\s*)/exit\$/'; + $DB::alias{'quit'} = 's/^quit(\s*)/exit/'; -One changes options from F<.perldb> file via calls like this one; +You can change options from F<.perldb> by using calls like this one; parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); -(the code is executed in the package C<DB>). Note that F<.perldb> is +The code is executed in the package C<DB>. Note that F<.perldb> is processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the -subroutine C<afterinit>, it is called after all the debugger +subroutine C<afterinit>, that function is called after debugger initialization ends. F<.perldb> may be contained in the current -directory, or in the C<LOGDIR>/C<HOME> directory. +directory, or in the home directory. Because this file is sourced +in by Perl and may contain arbitrary commands, for security reasons, +it must be owned by the superuser or the current user, and writable +by no one but its owner. -If you want to modify the debugger, copy F<perl5db.pl> from the Perl -library to another name and modify it as necessary. You'll also want -to set your C<PERL5DB> environment variable to say something like this: +If you want to modify the debugger, copy F<perl5db.pl> from the +Perl library to another name and hack it to your heart's content. +You'll then want to set your C<PERL5DB> environment variable to say +something like this: BEGIN { require "myperl5db.pl" } -As the last resort, one can use C<PERL5DB> to customize debugger by -directly setting internal variables or calling debugger functions. +As a last resort, you could also use C<PERL5DB> to customize the debugger +by directly setting internal variables or calling debugger functions. + +Note that any variables and functions that are not documented in +this document (or in L<perldebguts>) are considered for internal +use only, and as such are subject to change without notice. =head2 Readline Support -As shipped, the only command line history supplied is a simplistic one +As shipped, the only command-line history supplied is a simplistic one that checks for leading exclamation points. However, if you install the Term::ReadKey and Term::ReadLine modules from CPAN, you will have full editing capabilities much like GNU I<readline>(3) provides. Look for these in the F<modules/by-module/Term> directory on CPAN. +These do not support normal B<vi> command-line editing, however. -A rudimentary command line completion is also available. +A rudimentary command-line completion is also available. Unfortunately, the names of lexical variables are not available for completion. =head2 Editor Support for Debugging -If you have GNU B<emacs> installed on your system, it can interact with -the Perl debugger to provide an integrated software development -environment reminiscent of its interactions with C debuggers. - -Perl is also delivered with a start file for making B<emacs> act like a -syntax-directed editor that understands (some of) Perl's syntax. Look in -the I<emacs> directory of the Perl source distribution. - -(Historically, a similar setup for interacting with B<vi> and the -X11 window system had also been available, but at the time of this -writing, no debugger support for B<vi> currently exists.) - -=head2 The Perl Profiler - -If you wish to supply an alternative debugger for Perl to run, just -invoke your script with a colon and a package argument given to the B<-d> -flag. One of the most popular alternative debuggers for Perl is -B<DProf>, the Perl profiler. As of this writing, B<DProf> is not -included with the standard Perl distribution, but it is expected to -be included soon, for certain values of "soon". - -Meanwhile, you can fetch the Devel::Dprof module from CPAN. Assuming -it's properly installed on your system, to profile your Perl program in -the file F<mycode.pl>, just type: - - perl -d:DProf mycode.pl - -When the script terminates the profiler will dump the profile information -to a file called F<tmon.out>. A tool like B<dprofpp> (also supplied with -the Devel::DProf package) can be used to interpret the information which is -in that profile. - -=head2 Debugger support in perl - -When you call the B<caller> function (see L<perlfunc/caller>) from the -package DB, Perl sets the array @DB::args to contain the arguments the -corresponding stack frame was called with. - -If perl is run with B<-d> option, the following additional features -are enabled (cf. L<perlvar/$^P>): - -=over - -=item * - -Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require -'perl5db.pl'}> if not present) before the first line of the -application. - -=item * - -The array C<@{"_<$filename"}> is the line-by-line contents of -$filename for all the compiled files. Same for C<eval>ed strings which -contain subroutines, or which are currently executed. The $filename -for C<eval>ed strings looks like C<(eval 34)>. - -=item * - -The hash C<%{"_<$filename"}> contains breakpoints and action (it is -keyed by line number), and individual entries are settable (as opposed -to the whole hash). Only true/false is important to Perl, though the -values used by F<perl5db.pl> have the form -C<"$break_condition\0$action">. Values are magical in numeric context: -they are zeros if the line is not breakable. - -Same for evaluated strings which contain subroutines, or which are -currently executed. The $filename for C<eval>ed strings looks like -C<(eval 34)>. - -=item * - -The scalar C<${"_<$filename"}> contains C<"_<$filename">. Same for -evaluated strings which contain subroutines, or which are currently -executed. The $filename for C<eval>ed strings looks like C<(eval -34)>. - -=item * - -After each C<require>d file is compiled, but before it is executed, -C<DB::postponed(*{"_<$filename"})> is called (if subroutine -C<DB::postponed> exists). Here the $filename is the expanded name of -the C<require>d file (as found in values of %INC). - -=item * - -After each subroutine C<subname> is compiled existence of -C<$DB::postponed{subname}> is checked. If this key exists, -C<DB::postponed(subname)> is called (if subroutine C<DB::postponed> -exists). - -=item * - -A hash C<%DB::sub> is maintained, with keys being subroutine names, -values having the form C<filename:startline-endline>. C<filename> has -the form C<(eval 31)> for subroutines defined inside C<eval>s. - -=item * - -When execution of the application reaches a place that can have -a breakpoint, a call to C<DB::DB()> is performed if any one of -variables $DB::trace, $DB::single, or $DB::signal is true. (Note that -these variables are not C<local>izable.) This feature is disabled when -the control is inside C<DB::DB()> or functions called from it (unless -C<$^D & (1<<30)>). - -=item * - -When execution of the application reaches a subroutine call, a call -to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being -the name of the called subroutine. (Unless the subroutine is compiled -in the package C<DB>.) - -=back - -Note that if C<&DB::sub> needs some external data to be setup for it -to work, no subroutine call is possible until this is done. For the -standard debugger C<$DB::deep> (how many levels of recursion deep into -the debugger you can go before a mandatory break) gives an example of -such a dependency. - -The minimal working debugger consists of one line - - sub DB::DB {} - -which is quite handy as contents of C<PERL5DB> environment -variable: - - env "PERL5DB=sub DB::DB {}" perl -d your-script - -Another (a little bit more useful) minimal debugger can be created -with the only line being - - sub DB::DB {print ++$i; scalar <STDIN>} - -This debugger would print the sequential number of encountered -statement, and would wait for your C<CR> to continue. - -The following debugger is quite functional: - - { - package DB; - sub DB {} - sub sub {print ++$i, " $sub\n"; &$sub} - } - -It prints the sequential number of subroutine call and the name of the -called subroutine. Note that C<&DB::sub> should be compiled into the -package C<DB>. - -=head2 Debugger Internals - -At the start, the debugger reads your rc file (F<./.perldb> or -F<~/.perldb> under Unix), which can set important options. This file may -define a subroutine C<&afterinit> to be executed after the debugger is -initialized. - -After the rc file is read, the debugger reads environment variable -PERLDB_OPTS and parses it as a rest of C<O ...> line in debugger prompt. - -It also maintains magical internal variables, such as C<@DB::dbline>, -C<%DB::dbline>, which are aliases for C<@{"::_<current_file"}> -C<%{"::_<current_file"}>. Here C<current_file> is the currently -selected (with the debugger's C<f> command, or by flow of execution) -file. - -Some functions are provided to simplify customization. See L<"Debugger -Customization"> for description of C<DB::parse_options(string)>. The -function C<DB::dump_trace(skip[, count])> skips the specified number -of frames, and returns a list containing info about the caller -frames (all if C<count> is missing). Each entry is a hash with keys -C<context> (C<$> or C<@>), C<sub> (subroutine name, or info about -eval), C<args> (C<undef> or a reference to an array), C<file>, and -C<line>. - -The function C<DB::print_trace(FH, skip[, count[, short]])> prints -formatted info about caller frames. The last two functions may be -convenient as arguments to C<< < >>, C<< << >> commands. - -=head2 Other resources - -You did try the B<-w> switch, didn't you? - -=head2 BUGS - -You cannot get the stack frame information or otherwise debug functions -that were not compiled by Perl, such as C or C++ extensions. - -If you alter your @_ arguments in a subroutine (such as with B<shift> -or B<pop>, the stack backtrace will not show the original values. - -=head1 Debugging Perl memory usage - -Perl is I<very> frivolous with memory. There is a saying that to -estimate memory usage of Perl, assume a reasonable algorithm of -allocation, and multiply your estimates by 10. This is not absolutely -true, but may give you a good grasp of what happens. - -Say, an integer cannot take less than 20 bytes of memory, a float -cannot take less than 24 bytes, a string cannot take less than 32 -bytes (all these examples assume 32-bit architectures, the result are -much worse on 64-bit architectures). If a variable is accessed in two -of three different ways (which require an integer, a float, or a -string), the memory footprint may increase by another 20 bytes. A -sloppy malloc() implementation will make these numbers yet more. - -On the opposite end of the scale, a declaration like - - sub foo; - -may take (on some versions of perl) up to 500 bytes of memory. - -Off-the-cuff anecdotal estimates of a code bloat give a factor around -8. This means that the compiled form of reasonable (commented -indented etc.) code will take approximately 8 times more than the -disk space the code takes. - -There are two Perl-specific ways to analyze the memory usage: -$ENV{PERL_DEBUG_MSTATS} and B<-DL> switch. First one is available -only if perl is compiled with Perl's malloc(), the second one only if -Perl compiled with C<-DDEBUGGING> (as with giving C<-D optimise=-g> -option to F<Configure>). - -=head2 Using C<$ENV{PERL_DEBUG_MSTATS}> - -If your perl is using Perl's malloc(), and compiled with correct -switches (this is the default), then it will print memory usage -statistics after compiling your code (if C<$ENV{PERL_DEBUG_MSTATS}> > -1), and before termination of the script (if -C<$ENV{PERL_DEBUG_MSTATS}> >= 1). The report format is similar to one -in the following example: - - env PERL_DEBUG_MSTATS=2 perl -e "require Carp" - Memory allocation statistics after compilation: (buckets 4(4)..8188(8192) - 14216 free: 130 117 28 7 9 0 2 2 1 0 0 - 437 61 36 0 5 - 60924 used: 125 137 161 55 7 8 6 16 2 0 1 - 74 109 304 84 20 - Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048. - Memory allocation statistics after execution: (buckets 4(4)..8188(8192) - 30888 free: 245 78 85 13 6 2 1 3 2 0 1 - 315 162 39 42 11 - 175816 used: 265 176 1112 111 26 22 11 27 2 1 1 - 196 178 1066 798 39 - Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. - -It is possible to ask for such a statistic at arbitrary moment by -using Devel::Peek::mstats() (module Devel::Peek is available on CPAN). - -Here is the explanation of different parts of the format: - -=over - -=item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)> - -Perl's malloc() uses bucketed allocations. Every request is rounded -up to the closest bucket size available, and a bucket of these size is -taken from the pool of the buckets of this size. +If you have the FSF's version of B<emacs> installed on your system, +it can interact with the Perl debugger to provide an integrated +software development environment reminiscent of its interactions +with C debuggers. -The above line describes limits of buckets currently in use. Each -bucket has two sizes: memory footprint, and the maximal size of user -data which may be put into this bucket. Say, in the above example the -smallest bucket is both sizes 4. The biggest bucket has usable size -8188, and the memory footprint 8192. +Perl comes with a start file for making B<emacs> act like a +syntax-directed editor that understands (some of) Perl's syntax. +Look in the I<emacs> directory of the Perl source distribution. -With debugging Perl some buckets may have negative usable size. This -means that these buckets cannot (and will not) be used. For greater -buckets the memory footprint may be one page greater than a power of -2. In such a case the corresponding power of two is printed instead -in the C<APPROX> field above. +A similar setup by Tom Christiansen for interacting with any +vendor-shipped B<vi> and the X11 window system is also available. +This works similarly to the integrated multiwindow support that +B<emacs> provides, where the debugger drives the editor. At the +time of this writing, however, that tool's eventual location in the +Perl distribution was uncertain. -=item Free/Used +Users of B<vi> should also look into B<vim> and B<gvim>, the mousey +and windy version, for coloring of Perl keywords. -The following 1 or 2 rows of numbers correspond to the number of -buckets of each size between C<SMALLEST> and C<GREATEST>. In the -first row the sizes (memory footprints) of buckets are powers of two -(or possibly one page greater). In the second row (if present) the -memory footprints of the buckets are between memory footprints of two -buckets "above". +Note that only perl can truly parse Perl, so all such CASE tools +fall somewhat short of the mark, especially if you don't program +your Perl as a C programmer might. -Say, with the above example the memory footprints are (with current -algorithm) - - free: 8 16 32 64 128 256 512 1024 2048 4096 8192 - 4 12 24 48 80 - -With non-C<DEBUGGING> perl the buckets starting from C<128>-long ones -have 4-byte overhead, thus 8192-long bucket may take up to -8188-byte-long allocations. - -=item C<Total sbrk(): SBRKed/SBRKs:CONTINUOUS> - -The first two fields give the total amount of memory perl sbrk()ed, -and number of sbrk()s used. The third number is what perl thinks -about continuity of returned chunks. As far as this number is -positive, malloc() will assume that it is probable that sbrk() will -provide continuous memory. - -The amounts sbrk()ed by external libraries is not counted. - -=item C<pad: 0> - -The amount of sbrk()ed memory needed to keep buckets aligned. - -=item C<heads: 2192> - -While memory overhead of bigger buckets is kept inside the bucket, for -smaller buckets it is kept in separate areas. This field gives the -total size of these areas. - -=item C<chain: 0> - -malloc() may want to subdivide a bigger bucket into smaller buckets. -If only a part of the deceased-bucket is left non-subdivided, the rest -is kept as an element of a linked list. This field gives the total -size of these chunks. - -=item C<tail: 6144> - -To minimize amount of sbrk()s malloc() asks for more memory. This -field gives the size of the yet-unused part, which is sbrk()ed, but -never touched. - -=back - -=head2 Example of using B<-DL> switch - -Below we show how to analyse memory usage by - - do 'lib/auto/POSIX/autosplit.ix'; - -The file in question contains a header and 146 lines similar to - - sub getcwd ; - -B<Note:> I<the discussion below supposes 32-bit architecture. In the -newer versions of perl the memory usage of the constructs discussed -here is much improved, but the story discussed below is a real-life -story. This story is very terse, and assumes more than cursory -knowledge of Perl internals.> - -Here is the itemized list of Perl allocations performed during parsing -of this file: - - !!! "after" at test.pl line 3. - Id subtot 4 8 12 16 20 24 28 32 36 40 48 56 64 72 80 80+ - 0 02 13752 . . . . 294 . . . . . . . . . . 4 - 0 54 5545 . . 8 124 16 . . . 1 1 . . . . . 3 - 5 05 32 . . . . . . . 1 . . . . . . . . - 6 02 7152 . . . . . . . . . . 149 . . . . . - 7 02 3600 . . . . . 150 . . . . . . . . . . - 7 03 64 . -1 . 1 . . 2 . . . . . . . . . - 7 04 7056 . . . . . . . . . . . . . . . 7 - 7 17 38404 . . . . . . . 1 . . 442 149 . . 147 . - 9 03 2078 17 249 32 . . . . 2 . . . . . . . . - - -To see this list insert two C<warn('!...')> statements around the call: - - warn('!'); - do 'lib/auto/POSIX/autosplit.ix'; - warn('!!! "after"'); - -and run it with B<-DL> option. The first warn() will print memory -allocation info before the parsing of the file, and will memorize the -statistics at this point (we ignore what it prints). The second warn() -will print increments w.r.t. this memorized statistics. This is the -above printout. - -Different I<Id>s on the left correspond to different subsystems of -perl interpreter, they are just first argument given to perl memory -allocation API New(). To find what C<9 03> means C<grep> the perl -source for C<903>. You will see that it is F<util.c>, function -savepvn(). This function is used to store a copy of existing chunk of -memory. Using C debugger, one can see that it is called either -directly from gv_init(), or via sv_magic(), and gv_init() is called -from gv_fetchpv() - which is called from newSUB(). - -B<Note:> to reach this place in debugger and skip all the calls to -savepvn during the compilation of the main script, set a C breakpoint -in Perl_warn(), C<continue> this point is reached, I<then> set -breakpoint in Perl_savepvn(). Note that you may need to skip a -handful of Perl_savepvn() which do not correspond to mass production -of CVs (there are more C<903> allocations than 146 similar lines of -F<lib/auto/POSIX/autosplit.ix>). Note also that C<Perl_> prefixes are -added by macroization code in perl header files to avoid conflicts -with external libraries. - -Anyway, we see that C<903> ids correspond to creation of globs, twice -per glob - for glob name, and glob stringification magic. - -Here are explanations for other I<Id>s above: - -=over - -=item C<717> - -is for creation of bigger C<XPV*> structures. In the above case it -creates 3 C<AV> per subroutine, one for a list of lexical variable -names, one for a scratchpad (which contains lexical variables and -C<targets>), and one for the array of scratchpads needed for -recursion. - -It also creates a C<GV> and a C<CV> per subroutine (all called from -start_subparse()). - -=item C<002> - -Creates C array corresponding to the C<AV> of scratchpads, and the -scratchpad itself (the first fake entry of this scratchpad is created -though the subroutine itself is not defined yet). - -It also creates C arrays to keep data for the stash (this is one HV, -but it grows, thus there are 4 big allocations: the big chunks are not -freed, but are kept as additional arenas for C<SV> allocations). - -=item C<054> - -creates a C<HEK> for the name of the glob for the subroutine (this -name is a key in a I<stash>). - -Big allocations with this I<Id> correspond to allocations of new -arenas to keep C<HE>. - -=item C<602> - -creates a C<GP> for the glob for the subroutine. - -=item C<702> - -creates the C<MAGIC> for the glob for the subroutine. - -=item C<704> - -creates I<arenas> which keep SVs. - -=back - -=head2 B<-DL> details - -If Perl is run with B<-DL> option, then warn()s which start with `!' -behave specially. They print a list of I<categories> of memory -allocations, and statistics of allocations of different sizes for -these categories. - -If warn() string starts with - -=over - -=item C<!!!> - -print changed categories only, print the differences in counts of allocations; - -=item C<!!> - -print grown categories only; print the absolute values of counts, and totals; - -=item C<!> - -print nonempty categories, print the absolute values of counts and totals. +=head2 The Perl Profiler -=back +If you wish to supply an alternative debugger for Perl to run, just +invoke your script with a colon and a package argument given to the +B<-d> flag. The most popular alternative debuggers for Perl is the +Perl profiler. Devel::DProf is now included with the standard Perl +distribution. To profile your Perl program in the file F<mycode.pl>, +just type: -=head2 Limitations of B<-DL> statistic + $ perl -d:DProf mycode.pl -If an extension or an external library does not use Perl API to -allocate memory, these allocations are not counted. +When the script terminates the profiler will dump the profile +information to a file called F<tmon.out>. A tool like B<dprofpp>, +also supplied with the standard Perl distribution, can be used to +interpret the information in that profile. =head1 Debugging regular expressions -There are two ways to enable debugging output for regular expressions. - -If your perl is compiled with C<-DDEBUGGING>, you may use the -B<-Dr> flag on the command line. - -Otherwise, one can C<use re 'debug'>, which has effects both at -compile time, and at run time (and is I<not> lexically scoped). - -=head2 Compile-time output - -The debugging output for the compile time looks like this: +C<use re 'debug'> enables you to see the gory details of how the +Perl regular expression engine works. In order to understand this +typically voluminous output, one must not only have some idea about +about how regular expression matching works in general, but also +know how Perl's regular expressions are internally compiled into +an automaton. These matters are explored in some detail in +L<perldebguts/"Debugging regular expressions">. - compiling RE `[bc]d(ef*g)+h[ij]k$' - size 43 first at 1 - 1: ANYOF(11) - 11: EXACT <d>(13) - 13: CURLYX {1,32767}(27) - 15: OPEN1(17) - 17: EXACT <e>(19) - 19: STAR(22) - 20: EXACT <f>(0) - 22: EXACT <g>(24) - 24: CLOSE1(26) - 26: WHILEM(0) - 27: NOTHING(28) - 28: EXACT <h>(30) - 30: ANYOF(40) - 40: EXACT <k>(42) - 42: EOL(43) - 43: END(0) - anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating) - stclass `ANYOF' minlen 7 +=head1 Debugging memory usage -The first line shows the pre-compiled form of the regexp, and the -second shows the size of the compiled form (in arbitrary units, -usually 4-byte words) and the label I<id> of the first node which -does a match. +Perl contains internal support for reporting its own memory usage, +but this is a fairly advanced concept that requires some understanding +of how memory allocation works. +See L<perldebguts/"Debugging Perl memory usage"> for the details. -The last line (split into two lines in the above) contains the optimizer -info. In the example shown, the optimizer found that the match -should contain a substring C<de> at the offset 1, and substring C<gh> -at some offset between 3 and infinity. Moreover, when checking for -these substrings (to abandon impossible matches quickly) it will check -for the substring C<gh> before checking for the substring C<de>. The -optimizer may also use the knowledge that the match starts (at the -C<first> I<id>) with a character class, and the match cannot be -shorter than 7 chars. +=head1 SEE ALSO -The fields of interest which may appear in the last line are - -=over - -=item C<anchored> I<STRING> C<at> I<POS> - -=item C<floating> I<STRING> C<at> I<POS1..POS2> - -see above; - -=item C<matching floating/anchored> - -which substring to check first; - -=item C<minlen> - -the minimal length of the match; - -=item C<stclass> I<TYPE> - -The type of the first matching node. - -=item C<noscan> - -which advises to not scan for the found substrings; - -=item C<isall> - -which says that the optimizer info is in fact all that the regular -expression contains (thus one does not need to enter the RE engine at -all); - -=item C<GPOS> - -if the pattern contains C<\G>; - -=item C<plus> - -if the pattern starts with a repeated char (as in C<x+y>); - -=item C<implicit> - -if the pattern starts with C<.*>; +You did try the B<-w> switch, didn't you? -=item C<with eval> +L<perldebguts>, +L<re>, +L<DB>, +L<Devel::Dprof>, +L<dprofpp>, +L<Dumpvalue>, +and +L<perlrun>. -if the pattern contain eval-groups (see L<perlre/(?{ code })>); +=head1 BUGS -=item C<anchored(TYPE)> +You cannot get stack frame information or in any fashion debug functions +that were not compiled by Perl, such as those from C or C++ extensions. -if the pattern may -match only at a handful of places (with C<TYPE> being -C<BOL>, C<MBOL>, or C<GPOS>, see the table below). +If you alter your @_ arguments in a subroutine (such as with C<shift> +or C<pop>, the stack backtrace will not show the original values. -=back +The debugger does not currently work in conjunction with the B<-W> +command-line switch, because it itself is not free of warnings. -If a substring is known to match at end-of-line only, it may be -followed by C<$>, as in C<floating `k'$>. - -The optimizer-specific info is used to avoid entering (a slow) RE -engine on strings which will definitely not match. If C<isall> flag -is set, a call to the RE engine may be avoided even when optimizer -found an appropriate place for the match. - -The rest of the output contains the list of I<nodes> of the compiled -form of the RE. Each line has format - -C< >I<id>: I<TYPE> I<OPTIONAL-INFO> (I<next-id>) - -=head2 Types of nodes - -Here is the list of possible types with short descriptions: - - # TYPE arg-description [num-args] [longjump-len] DESCRIPTION - - # Exit points - END no End of program. - SUCCEED no Return from a subroutine, basically. - - # Anchors: - BOL no Match "" at beginning of line. - MBOL no Same, assuming multiline. - SBOL no Same, assuming singleline. - EOS no Match "" at end of string. - EOL no Match "" at end of line. - MEOL no Same, assuming multiline. - SEOL no Same, assuming singleline. - BOUND no Match "" at any word boundary - BOUNDL no Match "" at any word boundary - NBOUND no Match "" at any word non-boundary - NBOUNDL no Match "" at any word non-boundary - GPOS no Matches where last m//g left off. - - # [Special] alternatives - ANY no Match any one character (except newline). - SANY no Match any one character. - ANYOF sv Match character in (or not in) this class. - ALNUM no Match any alphanumeric character - ALNUML no Match any alphanumeric char in locale - NALNUM no Match any non-alphanumeric character - NALNUML no Match any non-alphanumeric char in locale - SPACE no Match any whitespace character - SPACEL no Match any whitespace char in locale - NSPACE no Match any non-whitespace character - NSPACEL no Match any non-whitespace char in locale - DIGIT no Match any numeric character - NDIGIT no Match any non-numeric character - - # BRANCH The set of branches constituting a single choice are hooked - # together with their "next" pointers, since precedence prevents - # anything being concatenated to any individual branch. The - # "next" pointer of the last BRANCH in a choice points to the - # thing following the whole choice. This is also where the - # final "next" pointer of each individual branch points; each - # branch starts with the operand node of a BRANCH node. - # - BRANCH node Match this alternative, or the next... - - # BACK Normal "next" pointers all implicitly point forward; BACK - # exists to make loop structures possible. - # not used - BACK no Match "", "next" ptr points backward. - - # Literals - EXACT sv Match this string (preceded by length). - EXACTF sv Match this string, folded (prec. by length). - EXACTFL sv Match this string, folded in locale (w/len). - - # Do nothing - NOTHING no Match empty string. - # A variant of above which delimits a group, thus stops optimizations - TAIL no Match empty string. Can jump here from outside. - - # STAR,PLUS '?', and complex '*' and '+', are implemented as circular - # BRANCH structures using BACK. Simple cases (one character - # per match) are implemented with STAR and PLUS for speed - # and to minimize recursive plunges. - # - STAR node Match this (simple) thing 0 or more times. - PLUS node Match this (simple) thing 1 or more times. - - CURLY sv 2 Match this simple thing {n,m} times. - CURLYN no 2 Match next-after-this simple thing - # {n,m} times, set parenths. - CURLYM no 2 Match this medium-complex thing {n,m} times. - CURLYX sv 2 Match this complex thing {n,m} times. - - # This terminator creates a loop structure for CURLYX - WHILEM no Do curly processing and see if rest matches. - - # OPEN,CLOSE,GROUPP ...are numbered at compile time. - OPEN num 1 Mark this point in input as start of #n. - CLOSE num 1 Analogous to OPEN. - - REF num 1 Match some already matched string - REFF num 1 Match already matched string, folded - REFFL num 1 Match already matched string, folded in loc. - - # grouping assertions - IFMATCH off 1 2 Succeeds if the following matches. - UNLESSM off 1 2 Fails if the following matches. - SUSPEND off 1 1 "Independent" sub-RE. - IFTHEN off 1 1 Switch, should be preceeded by switcher . - GROUPP num 1 Whether the group matched. - - # Support for long RE - LONGJMP off 1 1 Jump far away. - BRANCHJ off 1 1 BRANCH with long offset. - - # The heavy worker - EVAL evl 1 Execute some Perl code. - - # Modifiers - MINMOD no Next operator is not greedy. - LOGICAL no Next opcode should set the flag only. - - # This is not used yet - RENUM off 1 1 Group with independently numbered parens. - - # This is not really a node, but an optimized away piece of a "long" node. - # To simplify debugging output, we mark it as if it were a node - OPTIMIZED off Placeholder for dump. - -=head2 Run-time output - -First of all, when doing a match, one may get no run-time output even -if debugging is enabled. this means that the RE engine was never -entered, all of the job was done by the optimizer. - -If RE engine was entered, the output may look like this: - - Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__' - Setting an EVAL scope, savestack=3 - 2 <ab> <cdefg__gh_> | 1: ANYOF - 3 <abc> <defg__gh_> | 11: EXACT <d> - 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767} - 4 <abcd> <efg__gh_> | 26: WHILEM - 0 out of 1..32767 cc=effff31c - 4 <abcd> <efg__gh_> | 15: OPEN1 - 4 <abcd> <efg__gh_> | 17: EXACT <e> - 5 <abcde> <fg__gh_> | 19: STAR - EXACT <f> can match 1 times out of 32767... - Setting an EVAL scope, savestack=3 - 6 <bcdef> <g__gh__> | 22: EXACT <g> - 7 <bcdefg> <__gh__> | 24: CLOSE1 - 7 <bcdefg> <__gh__> | 26: WHILEM - 1 out of 1..32767 cc=effff31c - Setting an EVAL scope, savestack=12 - 7 <bcdefg> <__gh__> | 15: OPEN1 - 7 <bcdefg> <__gh__> | 17: EXACT <e> - restoring \1 to 4(4)..7 - failed, try continuation... - 7 <bcdefg> <__gh__> | 27: NOTHING - 7 <bcdefg> <__gh__> | 28: EXACT <h> - failed... - failed... - -The most significant information in the output is about the particular I<node> -of the compiled RE which is currently being tested against the target string. -The format of these lines is - -C< >I<STRING-OFFSET> <I<PRE-STRING>> <I<POST-STRING>> |I<ID>: I<TYPE> - -The I<TYPE> info is indented with respect to the backtracking level. -Other incidental information appears interspersed within. - -=cut +If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing +from your keyboard or a socket) and haven't set up your own C<$SIG{INT}> +handler, then you won't be able to CTRL-C your way back to the debugger, +because the debugger's own C<$SIG{INT}> handler doesn't understand that +it needs to raise an exception to longjmp(3) out of slow syscalls. diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 87017145d2..a49b9afb13 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -15,8 +15,8 @@ desperation): (X) A very fatal error (nontrappable). (A) An alien error message (not generated by Perl). -The majority of messages from the first three classifications above (W, -D & S) can be controlled using the C<warnings> pragma. +The majority of messages from the first three classifications above +(W, D & S) can be controlled using the C<warnings> pragma. If a message can be controlled by the C<warnings> pragma, its warning category is included with the classification letter in the description @@ -35,140 +35,109 @@ L<perlfunc/eval>. In almost all cases, warnings may be selectively disabled or promoted to fatal errors using the C<warnings> pragma. See L<warnings>. -Some of these messages are generic. Spots that vary are denoted with a %s, -just as in a printf format. Note that some messages start with a %s! -Since the messages are listed in alphabetical order, the symbols -C<"%(-?@> sort before the letters, while C<[> and C<\> sort after. +The messages are in alphabetical order, without regard to upper or +lower-case. Some of these messages are generic. Spots that vary are +denoted with a %s or other printf-style escape. These escapes are +ignored by the alphabetical order, as are all characters other than +letters. To look up your message, just ignore anything that is not a +letter. =over 4 -=item "%s" variable %s masks earlier declaration in same %s - -(W misc) A "my" or "our" variable has been redeclared in the current scope or statement, -effectively eliminating all access to the previous instance. This is almost -always a typographical error. Note that the earlier variable will still exist -until the end of the scope or until all closure referents to it are -destroyed. - -=item "my sub" not yet implemented - -(F) Lexically scoped subroutines are not yet implemented. Don't try that -yet. - -=item "my" variable %s can't be in a package - -(F) Lexically scoped variables aren't in a package, so it doesn't make sense -to try to declare one with a package qualifier on the front. Use local() -if you want to localize a package variable. - -=item "no" not allowed in expression - -(F) The "no" keyword is recognized and executed at compile time, and returns -no useful value. See L<perlmod>. - -=item "our" variable %s redeclared +=item accept() on closed socket %s -(W misc) You seem to have already declared the same global once before in the -current lexical scope. +(W closed) You tried to do an accept on a closed socket. Did you forget +to check the return value of your socket() call? See +L<perlfunc/accept>. -=item "use" not allowed in expression +=item Allocation too large: %lx -(F) The "use" keyword is recognized and executed at compile time, and returns -no useful value. See L<perlmod>. +(X) You can't allocate more than 64K on an MS-DOS machine. =item '!' allowed only after types %s (F) The '!' is allowed in pack() and unpack() only after certain types. See L<perlfunc/pack>. -=item / cannot take a count - -(F) You had an unpack template indicating a counted-length string, -but you have also specified an explicit size for the string. -See L<perlfunc/pack>. - -=item / must be followed by a, A or Z - -(F) You had an unpack template indicating a counted-length string, -which must be followed by one of the letters a, A or Z -to indicate what sort of string is to be unpacked. -See L<perlfunc/pack>. - -=item / must be followed by a*, A* or Z* - -(F) You had a pack template indicating a counted-length string, -Currently the only things that can have their length counted are a*, A* or Z*. -See L<perlfunc/pack>. - -=item / must follow a numeric type - -(F) You had an unpack template that contained a '#', -but this did not follow some numeric unpack specification. -See L<perlfunc/pack>. +=item Ambiguous call resolved as CORE::%s(), qualify as such or use & -=item % may only be used in unpack +(W ambiguous) A subroutine you have declared has the same name as a Perl +keyword, and you have used the name without qualification for calling +one or the other. Perl decided to call the builtin because the +subroutine is not imported. -(F) You can't pack a string by supplying a checksum, because the -checksumming process loses information, and you can't go the other -way. See L<perlfunc/unpack>. +To force interpretation as a subroutine call, either put an ampersand +before the subroutine name, or qualify the name with its package. +Alternatively, you can import the subroutine (or pretend that it's +imported with the C<use subs> pragma). -=item Repeat count in pack overflows +To silently interpret it as the Perl operator, use the C<CORE::> prefix +on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine +to be an object method (see L<perlsub/"Subroutine Attributes"> or +L<attributes>). -(F) You can't specify a repeat count so large that it overflows -your signed integers. See L<perlfunc/pack>. +=item Ambiguous use of %s resolved as %s -=item Repeat count in unpack overflows +(W ambiguous)(S) You said something that may not be interpreted the way +you thought. Normally it's pretty easy to disambiguate it by supplying +a missing quote, operator, parenthesis pair or declaration. -(F) You can't specify a repeat count so large that it overflows -your signed integers. See L<perlfunc/unpack>. +=item '|' and '<' may not both be specified on command line -=item /%s/: Unrecognized escape \\%c passed through +(F) An error peculiar to VMS. Perl does its own command line +redirection, and found that STDIN was a pipe, and that you also tried to +redirect STDIN using '<'. Only one STDIN stream to a customer, please. -(W regexp) You used a backslash-character combination which is not recognized -by Perl. This combination appears in an interpolated variable or a -C<'>-delimited regular expression. The character was understood literally. +=item '|' and '>' may not both be specified on command line -=item /%s/: Unrecognized escape \\%c in character class passed through +(F) An error peculiar to VMS. Perl does its own command line +redirection, and thinks you tried to redirect stdout both to a file and +into a pipe to another command. You need to choose one or the other, +though nothing's stopping you from piping into a program or Perl script +which 'splits' output into two streams, such as -(W regexp) You used a backslash-character combination which is not recognized -by Perl inside character classes. The character was understood literally. + open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!"; + while (<STDIN>) { + print; + print OUT; + } + close OUT; -=item /%s/ should probably be written as "%s" +=item Applying %s to %s will act on scalar(%s) -(W syntax) You have used a pattern where Perl expected to find a string, -as in the first argument to C<join>. Perl will treat the true -or false result of matching the pattern against $_ as the string, -which is probably not what you had in mind. +(W misc) The pattern match (//), substitution (s///), and +transliteration (tr///) operators work on scalar values. If you apply +one of them to an array or a hash, it will convert the array or hash to +a scalar value -- the length of an array, or the population info of a +hash -- and then work on that scalar value. This is probably not what +you meant to do. See L<perlfunc/grep> and L<perlfunc/map> for +alternatives. -=item %s (...) interpreted as function +=item Args must match #! line -(W syntax) You've run afoul of the rule that says that any list operator followed -by parentheses turns into a function, with all the list operators arguments -found inside the parentheses. See L<perlop/Terms and List Operators (Leftward)>. +(F) The setuid emulator requires that the arguments Perl was invoked +with match the arguments specified on the #! line. Since some systems +impose a one-argument limit on the #! line, try combining switches; +for example, turn C<-w -U> into C<-wU>. -=item %s() called too early to check prototype +=item Arg too short for msgsnd -(W prototype) You've called a function that has a prototype before the parser saw a -definition or declaration for it, and Perl could not check that the call -conforms to the prototype. You need to either add an early prototype -declaration for the subroutine in question, or move the subroutine -definition ahead of the call to get proper prototype checking. Alternatively, -if you are certain that you're calling the function correctly, you may put -an ampersand before the name to avoid the warning. See L<perlsub>. +(F) msgsnd() requires a string at least as long as sizeof(long). =item %s argument is not a HASH or ARRAY element (F) The argument to exists() must be a hash or array element, such as: $foo{$bar} - $ref->[12]->["susie"] + $ref->{"susie"}[12] =item %s argument is not a HASH or ARRAY element or slice -(F) The argument to delete() must be either a hash or array element, such as: +(F) The argument to delete() must be either a hash or array element, +such as: $foo{$bar} - $ref->[12]->["susie"] + $ref->{"susie"}[12] or a hash or array slice, such as: @@ -178,191 +147,19 @@ or a hash or array slice, such as: =item %s argument is not a subroutine name (F) The argument to exists() for C<exists &sub> must be a subroutine -name, and not a subroutine call. C<exists &sub()> will generate this error. - -=item %s did not return a true value - -(F) A required (or used) file must return a true value to indicate that -it compiled correctly and ran its initialization code correctly. It's -traditional to end such a file with a "1;", though any true value would -do. See L<perlfunc/require>. - -=item %s found where operator expected - -(S) The Perl lexer knows whether to expect a term or an operator. If it -sees what it knows to be a term when it was expecting to see an operator, -it gives you this warning. Usually it indicates that an operator or -delimiter was omitted, such as a semicolon. - -=item %s had compilation errors - -(F) The final summary message when a C<perl -c> fails. - -=item %s has too many errors - -(F) The parser has given up trying to parse the program after 10 errors. -Further error messages would likely be uninformative. - -=item %s matches null string many times - -(W regexp) The pattern you've specified would be an infinite loop if the -regular expression engine didn't specifically check for that. See L<perlre>. - -=item %s never introduced - -(S internal) The symbol in question was declared but somehow went out of scope -before it could possibly have been used. - -=item %s package attribute may clash with future reserved word: %s - -(W reserved) A lowercase attribute name was used that had a package-specific handler. -That name might have a meaning to Perl itself some day, even though it -doesn't yet. Perhaps you should use a mixed-case attribute name, instead. -See L<attributes>. - -=item %s syntax OK - -(F) The final summary message when a C<perl -c> succeeds. - -=item %s: Command not found - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: Expression syntax - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: Undefined variable - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: not found - -(A) You've accidentally run your script through the Bourne shell -instead of Perl. Check the #! line, or manually feed your script -into Perl yourself. - -=item (in cleanup) %s - -(W misc) This prefix usually indicates that a DESTROY() method raised -the indicated exception. Since destructors are usually called by -the system at arbitrary points during execution, and often a vast -number of times, the warning is issued only once for any number -of failures that would otherwise result in the same message being -repeated. - -Failure of user callbacks dispatched using the C<G_KEEPERR> flag -could also result in this warning. See L<perlcall/G_KEEPERR>. - -=item (Missing semicolon on previous line?) - -(S) This is an educated guess made in conjunction with the message "%s -found where operator expected". Don't automatically put a semicolon on -the previous line just because you saw this message. - -=item B<-P> not allowed for setuid/setgid script - -(F) The script would have to be opened by the C preprocessor by name, -which provides a race condition that breaks security. - -=item C<-T> and C<-B> not implemented on filehandles - -(F) Perl can't peek at the stdio buffer of filehandles when it doesn't -know about your kind of stdio. You'll have to use a filename instead. - -=item C<-p> destination: %s - -(F) An error occurred during the implicit output invoked by the C<-p> -command-line switch. (This output goes to STDOUT unless you've -redirected it with select().) - -=item 500 Server error - -See Server error. - -=item ?+* follows nothing in regexp - -(F) You started a regular expression with a quantifier. Backslash it -if you meant it literally. See L<perlre>. - -=item @ outside of string - -(F) You had a pack template that specified an absolute position outside -the string being unpacked. See L<perlfunc/pack>. - -=item <> should be quotes - -(F) You wrote C<< require <file> >> when you should have written -C<require 'file'>. - -=item accept() on closed socket %s - -(W closed) You tried to do an accept on a closed socket. Did you forget to check -the return value of your socket() call? See L<perlfunc/accept>. - -=item Allocation too large: %lx - -(X) You can't allocate more than 64K on an MS-DOS machine. - -=item Applying %s to %s will act on scalar(%s) - -(W misc) The pattern match (//), substitution (s///), and transliteration (tr///) -operators work on scalar values. If you apply one of them to an array -or a hash, it will convert the array or hash to a scalar value -- the -length of an array, or the population info of a hash -- and then work on -that scalar value. This is probably not what you meant to do. See -L<perlfunc/grep> and L<perlfunc/map> for alternatives. - -=item Arg too short for msgsnd - -(F) msgsnd() requires a string at least as long as sizeof(long). - -=item Ambiguous use of %s resolved as %s - -(W ambiguous)(S) You said something that may not be interpreted the way -you thought. Normally it's pretty easy to disambiguate it by supplying -a missing quote, operator, parenthesis pair or declaration. - -=item Ambiguous call resolved as CORE::%s(), qualify as such or use & - -(W ambiguous) A subroutine you have declared has the same name as a Perl keyword, -and you have used the name without qualification for calling one or the -other. Perl decided to call the builtin because the subroutine is -not imported. - -To force interpretation as a subroutine call, either put an ampersand -before the subroutine name, or qualify the name with its package. -Alternatively, you can import the subroutine (or pretend that it's -imported with the C<use subs> pragma). - -To silently interpret it as the Perl operator, use the C<CORE::> prefix -on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine -to be an object method (see L<perlsub/"Subroutine Attributes"> -or L<attributes>). - -=item Args must match #! line - -(F) The setuid emulator requires that the arguments Perl was invoked -with match the arguments specified on the #! line. Since some systems -impose a one-argument limit on the #! line, try combining switches; -for example, turn C<-w -U> into C<-wU>. +name, and not a subroutine call. C<exists &sub()> will generate this +error. =item Argument "%s" isn't numeric%s -(W numeric) The indicated string was fed as an argument to an operator that -expected a numeric value instead. If you're fortunate the message +(W numeric) The indicated string was fed as an argument to an operator +that expected a numeric value instead. If you're fortunate the message will identify which operator was so unfortunate. =item Array @%s missing the @ in argument %d of %s() -(D deprecated) Really old Perl let you omit the @ on array names in some spots. This -is now heavily deprecated. +(D deprecated) Really old Perl let you omit the @ on array names in some +spots. This is now heavily deprecated. =item assertion botched: %s @@ -380,24 +177,24 @@ know which context to supply to the right side. =item Attempt to free non-arena SV: 0x%lx -(P internal) All SV objects are supposed to be allocated from arenas that will -be garbage collected on exit. An SV was discovered to be outside any -of those arenas. +(P internal) All SV objects are supposed to be allocated from arenas +that will be garbage collected on exit. An SV was discovered to be +outside any of those arenas. =item Attempt to free nonexistent shared string -(P internal) Perl maintains a reference counted internal table of strings to -optimize the storage and access of hash keys and other strings. This -indicates someone tried to decrement the reference count of a string -that can no longer be found in the table. +(P internal) Perl maintains a reference counted internal table of +strings to optimize the storage and access of hash keys and other +strings. This indicates someone tried to decrement the reference count +of a string that can no longer be found in the table. =item Attempt to free temp prematurely -(W debugging) Mortalized values are supposed to be freed by the free_tmps() -routine. This indicates that something else is freeing the SV before -the free_tmps() routine gets a chance, which means that the free_tmps() -routine will be freeing an unreferenced scalar when it does try to free -it. +(W debugging) Mortalized values are supposed to be freed by the +free_tmps() routine. This indicates that something else is freeing the +SV before the free_tmps() routine gets a chance, which means that the +free_tmps() routine will be freeing an unreferenced scalar when it does +try to free it. =item Attempt to free unreferenced glob pointers @@ -405,18 +202,19 @@ it. =item Attempt to free unreferenced scalar -(W internal) Perl went to decrement the reference count of a scalar to see if it -would go to 0, and discovered that it had already gone to 0 earlier, -and should have been freed, and in fact, probably was freed. This -could indicate that SvREFCNT_dec() was called too many times, or that -SvREFCNT_inc() was called too few times, or that the SV was mortalized -when it shouldn't have been, or that memory has been corrupted. +(W internal) Perl went to decrement the reference count of a scalar to +see if it would go to 0, and discovered that it had already gone to 0 +earlier, and should have been freed, and in fact, probably was freed. +This could indicate that SvREFCNT_dec() was called too many times, or +that SvREFCNT_inc() was called too few times, or that the SV was +mortalized when it shouldn't have been, or that memory has been +corrupted. =item Attempt to join self (F) You tried to join a thread from within itself, which is an -impossible task. You may be joining the wrong thread, or you may -need to move the join() to some other thread. +impossible task. You may be joining the wrong thread, or you may need +to move the join() to some other thread. =item Attempt to pack pointer to temporary value @@ -429,33 +227,38 @@ avoid this warning. =item Attempt to use reference as lvalue in substr -(W substr) You supplied a reference as the first argument to substr() used -as an lvalue, which is pretty strange. Perhaps you forgot to +(W substr) You supplied a reference as the first argument to substr() +used as an lvalue, which is pretty strange. Perhaps you forgot to dereference it first. See L<perlfunc/substr>. =item Bad arg length for %s, is %d, should be %d -(F) You passed a buffer of the wrong size to one of msgctl(), semctl() or -shmctl(). In C parlance, the correct sizes are, respectively, +(F) You passed a buffer of the wrong size to one of msgctl(), semctl() +or shmctl(). In C parlance, the correct sizes are, respectively, S<sizeof(struct msqid_ds *)>, S<sizeof(struct semid_ds *)>, and S<sizeof(struct shmid_ds *)>. +=item Bad evalled substitution pattern + +(F) You've used the /e switch to evaluate the replacement for a +substitution, but perl found a syntax error in the code to evaluate, +most likely an unexpected right brace '}'. + =item Bad filehandle: %s -(F) A symbol was passed to something wanting a filehandle, but the symbol -has no filehandle associated with it. Perhaps you didn't do an open(), or -did it in another package. +(F) A symbol was passed to something wanting a filehandle, but the +symbol has no filehandle associated with it. Perhaps you didn't do an +open(), or did it in another package. =item Bad free() ignored -(S malloc) An internal routine called free() on something that had never been -malloc()ed in the first place. Mandatory, but can be disabled by +(S malloc) An internal routine called free() on something that had never +been malloc()ed in the first place. Mandatory, but can be disabled by setting environment variable C<PERL_BADFREE> to 1. -This message can be quite often seen with DB_File on systems with -"hard" dynamic linking, like C<AIX> and C<OS/2>. It is a bug of -C<Berkeley DB> which is left unnoticed if C<DB> uses I<forgiving> -system malloc(). +This message can be quite often seen with DB_File on systems with "hard" +dynamic linking, like C<AIX> and C<OS/2>. It is a bug of C<Berkeley DB> +which is left unnoticed if C<DB> uses I<forgiving> system malloc(). =item Bad hash @@ -467,11 +270,17 @@ system malloc(). pseudo-hash is not legal. Index values must be at 1 or greater. See L<perlref>. +=item Badly placed ()'s + +(A) You've accidentally run your script through B<csh> instead +of Perl. Check the #! line, or manually feed your script into +Perl yourself. + =item Bad name after %s:: -(F) You started to name a symbol by using a package prefix, and then didn't -finish the symbol. In particular, you can't interpolate outside of quotes, -so +(F) You started to name a symbol by using a package prefix, and then +didn't finish the symbol. In particular, you can't interpolate outside +of quotes, so $var = 'myvar'; $sym = mypack::$var; @@ -483,9 +292,9 @@ is not the same as =item Bad realloc() ignored -(S malloc) An internal routine called realloc() on something that had never been -malloc()ed in the first place. Mandatory, but can be disabled by -setting environment variable C<PERL_BADFREE> to 1. +(S malloc) An internal routine called realloc() on something that had +never been malloc()ed in the first place. Mandatory, but can be disabled +by setting environment variable C<PERL_BADFREE> to 1. =item Bad symbol for array @@ -494,60 +303,63 @@ wasn't a symbol table entry. =item Bad symbol for filehandle -(P) An internal request asked to add a filehandle entry to something that -wasn't a symbol table entry. +(P) An internal request asked to add a filehandle entry to something +that wasn't a symbol table entry. =item Bad symbol for hash (P) An internal request asked to add a hash entry to something that wasn't a symbol table entry. -=item Badly placed ()'s - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item Bareword "%s" not allowed while "strict subs" in use - -(F) With "strict subs" in use, a bareword is only allowed as a -subroutine identifier, in curly brackets or to the left of the "=>" symbol. -Perhaps you need to predeclare a subroutine? - -=item Bareword "%s" refers to nonexistent package - -(W bareword) You used a qualified bareword of the form C<Foo::>, but -the compiler saw no other uses of that namespace before that point. -Perhaps you need to predeclare a package? - =item Bareword found in conditional -(W bareword) The compiler found a bareword where it expected a conditional, -which often indicates that an || or && was parsed as part of the -last argument of the previous construct, for example: +(W bareword) The compiler found a bareword where it expected a +conditional, which often indicates that an || or && was parsed as part +of the last argument of the previous construct, for example: open FOO || die; -It may also indicate a misspelled constant that has been interpreted -as a bareword: +It may also indicate a misspelled constant that has been interpreted as +a bareword: use constant TYPO => 1; if (TYOP) { print "foo" } The C<strict> pragma is useful in avoiding such errors. +=item Bareword "%s" not allowed while "strict subs" in use + +(F) With "strict subs" in use, a bareword is only allowed as a +subroutine identifier, in curly brackets or to the left of the "=>" +symbol. Perhaps you need to predeclare a subroutine? + +=item Bareword "%s" refers to nonexistent package + +(W bareword) You used a qualified bareword of the form C<Foo::>, but the +compiler saw no other uses of that namespace before that point. Perhaps +you need to predeclare a package? + =item BEGIN failed--compilation aborted -(F) An untrapped exception was raised while executing a BEGIN subroutine. -Compilation stops immediately and the interpreter is exited. +(F) An untrapped exception was raised while executing a BEGIN +subroutine. Compilation stops immediately and the interpreter is +exited. =item BEGIN not safe after errors--compilation aborted (F) Perl found a C<BEGIN {}> subroutine (or a C<use> directive, which -implies a C<BEGIN {}>) after one or more compilation errors had -already occurred. Since the intended environment for the C<BEGIN {}> -could not be guaranteed (due to the errors), and since subsequent code -likely depends on its correct operation, Perl just gave up. +implies a C<BEGIN {}>) after one or more compilation errors had already +occurred. Since the intended environment for the C<BEGIN {}> could not +be guaranteed (due to the errors), and since subsequent code likely +depends on its correct operation, Perl just gave up. + +=item \1 better written as $1 + +(W syntax) Outside of patterns, backreferences live on as variables. +The use of backslashes is grandfathered on the right-hand side of a +substitution, but stylistically it's better to use the variable form +because other Perl programmers will expect it, and it works better if +there are more than 9 backreferences. =item Binary number > 0b11111111111111111111111111111111 non-portable @@ -557,8 +369,8 @@ L<perlport> for more on portability concerns. =item bind() on closed socket %s -(W closed) You tried to do a bind on a closed socket. Did you forget to check -the return value of your socket() call? See L<perlfunc/bind>. +(W closed) You tried to do a bind on a closed socket. Did you forget to +check the return value of your socket() call? See L<perlfunc/bind>. =item Bit vector size > 32 non-portable @@ -566,65 +378,41 @@ the return value of your socket() call? See L<perlfunc/bind>. =item Bizarre copy of %s in %s -(P) Perl detected an attempt to copy an internal value that is not copiable. +(P) Perl detected an attempt to copy an internal value that is not +copiable. + +=item B<-P> not allowed for setuid/setgid script + +(F) The script would have to be opened by the C preprocessor by name, +which provides a race condition that breaks security. =item Buffer overflow in prime_env_iter: %s -(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over -%ENV, it encountered a logical name or symbol definition which was too long, -so it was truncated to the string shown. +(W internal) A warning peculiar to VMS. While Perl was preparing to +iterate over %ENV, it encountered a logical name or symbol definition +which was too long, so it was truncated to the string shown. =item Callback called exit (F) A subroutine invoked from an external package via call_sv() exited by calling exit. -=item Can't "goto" out of a pseudo block - -(F) A "goto" statement was executed to jump out of what might look -like a block, except that it isn't a proper block. This usually -occurs if you tried to jump out of a sort() block or subroutine, which -is a no-no. See L<perlfunc/goto>. - -=item Can't "goto" into the middle of a foreach loop - -(F) A "goto" statement was executed to jump into the middle of a -foreach loop. You can't get there from here. See L<perlfunc/goto>. - -=item Can't "last" outside a loop block - -(F) A "last" statement was executed to break out of the current block, -except that there's this itty bitty problem called there isn't a -current block. Note that an "if" or "else" block doesn't count as a -"loopish" block, as doesn't a block given to sort(), map() or grep(). -You can usually double the curlies to get the same effect though, -because the inner curlies will be considered a block that loops once. -See L<perlfunc/last>. - -=item Can't "next" outside a loop block - -(F) A "next" statement was executed to reiterate the current block, but -there isn't a current block. Note that an "if" or "else" block doesn't -count as a "loopish" block, as doesn't a block given to sort(), map() -or grep(). You can usually double the curlies to get the same effect -though, because the inner curlies will be considered a block that -loops once. See L<perlfunc/next>. - -=item Can't read CRTL environ +=item %s() called too early to check prototype -(S) A warning peculiar to VMS. Perl tried to read an element of %ENV -from the CRTL's internal environment array and discovered the array was -missing. You need to figure out where your CRTL misplaced its environ -or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched. +(W prototype) You've called a function that has a prototype before the +parser saw a definition or declaration for it, and Perl could not check +that the call conforms to the prototype. You need to either add an +early prototype declaration for the subroutine in question, or move the +subroutine definition ahead of the call to get proper prototype +checking. Alternatively, if you are certain that you're calling the +function correctly, you may put an ampersand before the name to avoid +the warning. See L<perlsub>. -=item Can't "redo" outside a loop block +=item / cannot take a count -(F) A "redo" statement was executed to restart the current block, but -there isn't a current block. Note that an "if" or "else" block doesn't -count as a "loopish" block, as doesn't a block given to sort(), map() -or grep(). You can usually double the curlies to get the same effect -though, because the inner curlies will be considered a block that -loops once. See L<perlfunc/redo>. +(F) You had an unpack template indicating a counted-length string, but +you have also specified an explicit size for the string. See +L<perlfunc/pack>. =item Can't bless non-reference value @@ -633,9 +421,9 @@ encapsulation of objects. See L<perlobj>. =item Can't break at that line -(S internal) A warning intended to only be printed while running within the debugger, indicating -the line number specified wasn't the location of a statement that could -be stopped at. +(S internal) A warning intended to only be printed while running within +the debugger, indicating the line number specified wasn't the location +of a statement that could be stopped at. =item Can't call method "%s" in empty package "%s" @@ -643,31 +431,31 @@ be stopped at. functioning as a class, but that package doesn't have ANYTHING defined in it, let alone methods. See L<perlobj>. -=item Can't call method "%s" on unblessed reference - -(F) A method call must know in what package it's supposed to run. It -ordinarily finds this out from the object reference you supply, but -you didn't supply an object reference in this case. A reference isn't -an object reference until it has been blessed. See L<perlobj>. - -=item Can't call method "%s" without a package or object reference +=item Can't call method "%s" on an undefined value (F) You used the syntax of a method call, but the slot filled by the -object reference or package name contains an expression that returns -a defined value which is neither an object reference nor a package name. -Something like this will reproduce the error: +object reference or package name contains an undefined value. Something +like this will reproduce the error: - $BADREF = 42; + $BADREF = undef; process $BADREF 1,2,3; $BADREF->process(1,2,3); -=item Can't call method "%s" on an undefined value +=item Can't call method "%s" on unblessed reference + +(F) A method call must know in what package it's supposed to run. It +ordinarily finds this out from the object reference you supply, but you +didn't supply an object reference in this case. A reference isn't an +object reference until it has been blessed. See L<perlobj>. + +=item Can't call method "%s" without a package or object reference (F) You used the syntax of a method call, but the slot filled by the -object reference or package name contains an undefined value. +object reference or package name contains an expression that returns a +defined value which is neither an object reference nor a package name. Something like this will reproduce the error: - $BADREF = undef; + $BADREF = 42; process $BADREF 1,2,3; $BADREF->process(1,2,3); @@ -678,7 +466,14 @@ that you can chdir to, possibly because it doesn't exist. =item Can't check filesystem of script "%s" for nosuid -(P) For some reason you can't check the filesystem of the script for nosuid. +(P) For some reason you can't check the filesystem of the script for +nosuid. + +=item Can't coerce array into hash + +(F) You used an array where a hash was expected, but the array has no +information on how to map from keys to array indices. You can do that +only with arrays that have a hash reference at index 0. =item Can't coerce %s to integer in %s @@ -705,16 +500,10 @@ but then $foo no longer contains a glob. (F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are. -=item Can't coerce array into hash - -(F) You used an array where a hash was expected, but the array has no -information on how to map from keys to array indices. You can do that -only with arrays that have a hash reference at index 0. - =item Can't create pipe mailbox -(P) An error peculiar to VMS. The process is suffering from exhausted quotas -or other plumbing problems. +(P) An error peculiar to VMS. The process is suffering from exhausted +quotas or other plumbing problems. =item Can't declare class for non-scalar %s in "%s" @@ -727,15 +516,21 @@ for other types of variables in future. (F) Only scalar, array, and hash variables may be declared as "my" or "our" variables. They must have ordinary identifiers as names. +=item Can't do inplace edit: %s is not a regular file + +(S inplace) You tried to use the B<-i> switch on a special file, such as +a file in /dev, or a FIFO. The file was ignored. + =item Can't do inplace edit on %s: %s -(S inplace) The creation of the new file failed for the indicated reason. +(S inplace) The creation of the new file failed for the indicated +reason. =item Can't do inplace edit without backup -(F) You're on a system such as MS-DOS that gets confused if you try reading -from a deleted (but still opened) file. You have to say C<-i.bak>, or some -such. +(F) You're on a system such as MS-DOS that gets confused if you try +reading from a deleted (but still opened) file. You have to say +C<-i.bak>, or some such. =item Can't do inplace edit: %s would not be unique @@ -743,15 +538,15 @@ such. characters and Perl was unable to create a unique filename during inplace editing with the B<-i> switch. The file was ignored. -=item Can't do inplace edit: %s is not a regular file +=item Can't do {n,m} with n > m -(S inplace) You tried to use the B<-i> switch on a special file, such as a file in -/dev, or a FIFO. The file was ignored. +(F) Minima must be less than or equal to maxima. If you really want +your regexp to match something 0 times, just put {0}. See L<perlre>. =item Can't do setegid! -(P) The setegid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setegid() call failed for some reason in the setuid emulator of +suidperl. =item Can't do seteuid! @@ -759,134 +554,154 @@ of suidperl. =item Can't do setuid -(F) This typically means that ordinary perl tried to exec suidperl to -do setuid emulation, but couldn't exec it. It looks for a name of the -form sperl5.000 in the same directory that the perl executable resides -under the name perl5.000, typically /usr/local/bin on Unix machines. -If the file is there, check the execute permissions. If it isn't, ask -your sysadmin why he and/or she removed it. +(F) This typically means that ordinary perl tried to exec suidperl to do +setuid emulation, but couldn't exec it. It looks for a name of the form +sperl5.000 in the same directory that the perl executable resides under +the name perl5.000, typically /usr/local/bin on Unix machines. If the +file is there, check the execute permissions. If it isn't, ask your +sysadmin why he and/or she removed it. =item Can't do waitpid with flags -(F) This machine doesn't have either waitpid() or wait4(), so only waitpid() -without flags is emulated. - -=item Can't do {n,m} with n > m - -(F) Minima must be less than or equal to maxima. If you really want -your regexp to match something 0 times, just put {0}. See L<perlre>. +(F) This machine doesn't have either waitpid() or wait4(), so only +waitpid() without flags is emulated. =item Can't emulate -%s on #! line -(F) The #! line specifies a switch that doesn't make sense at this point. -For example, it'd be kind of silly to put a B<-x> on the #! line. +(F) The #! line specifies a switch that doesn't make sense at this +point. For example, it'd be kind of silly to put a B<-x> on the #! +line. =item Can't exec "%s": %s -(W exec) An system(), exec(), or piped open call could not execute the named -program for the indicated reason. Typical reasons include: the permissions -were wrong on the file, the file wasn't found in C<$ENV{PATH}>, the -executable in question was compiled for another architecture, or the -#! line in a script points to an interpreter that can't be run for -similar reasons. (Or maybe your system doesn't support #! at all.) +(W exec) An system(), exec(), or piped open call could not execute the +named program for the indicated reason. Typical reasons include: the +permissions were wrong on the file, the file wasn't found in +C<$ENV{PATH}>, the executable in question was compiled for another +architecture, or the #! line in a script points to an interpreter that +can't be run for similar reasons. (Or maybe your system doesn't support +#! at all.) =item Can't exec %s -(F) Perl was trying to execute the indicated program for you because that's -what the #! line said. If that's not what you wanted, you may need to -mention "perl" on the #! line somewhere. +(F) Perl was trying to execute the indicated program for you because +that's what the #! line said. If that's not what you wanted, you may +need to mention "perl" on the #! line somewhere. =item Can't execute %s -(F) You used the B<-S> switch, but the copies of the script to execute found -in the PATH did not have correct permissions. +(F) You used the B<-S> switch, but the copies of the script to execute +found in the PATH did not have correct permissions. -=item Can't find %s on PATH, '.' not in PATH +=item Can't find an opnumber for "%s" -(F) You used the B<-S> switch, but the script to execute could not be found -in the PATH, or at least not with the correct permissions. The script -exists in the current directory, but PATH prohibits running it. +(F) A string of a form C<CORE::word> was given to prototype(), but there +is no builtin with the name C<word>. + +=item Can't find label %s + +(F) You said to goto a label that isn't mentioned anywhere that it's +possible for us to go to. See L<perlfunc/goto>. =item Can't find %s on PATH -(F) You used the B<-S> switch, but the script to execute could not be found -in the PATH. +(F) You used the B<-S> switch, but the script to execute could not be +found in the PATH. -=item Can't find label %s +=item Can't find %s on PATH, '.' not in PATH -(F) You said to goto a label that isn't mentioned anywhere that it's possible -for us to go to. See L<perlfunc/goto>. +(F) You used the B<-S> switch, but the script to execute could not be +found in the PATH, or at least not with the correct permissions. The +script exists in the current directory, but PATH prohibits running it. =item Can't find string terminator %s anywhere before EOF -(F) Perl strings can stretch over multiple lines. This message means that -the closing delimiter was omitted. Because bracketed quotes count nesting -levels, the following is missing its final parenthesis: +(F) Perl strings can stretch over multiple lines. This message means +that the closing delimiter was omitted. Because bracketed quotes count +nesting levels, the following is missing its final parenthesis: print q(The character '(' starts a side comment.); -If you're getting this error from a here-document, you may have -included unseen whitespace before or after your closing tag. A good -programmer's editor will have a way to help you find these characters. +If you're getting this error from a here-document, you may have included +unseen whitespace before or after your closing tag. A good programmer's +editor will have a way to help you find these characters. =item Can't fork -(F) A fatal error occurred while trying to fork while opening a pipeline. +(F) A fatal error occurred while trying to fork while opening a +pipeline. =item Can't get filespec - stale stat buffer? -(S) A warning peculiar to VMS. This arises because of the difference between -access checks under VMS and under the Unix model Perl assumes. Under VMS, -access checks are done by filename, rather than by bits in the stat buffer, so -that ACLs and other protections can be taken into account. Unfortunately, Perl -assumes that the stat buffer contains all the necessary information, and passes -it, instead of the filespec, to the access checking routine. It will try to -retrieve the filespec using the device name and FID present in the stat buffer, -but this works only if you haven't made a subsequent call to the CRTL stat() -routine, because the device name is overwritten with each call. If this warning -appears, the name lookup failed, and the access checking routine gave up and -returned FALSE, just to be conservative. (Note: The access checking routine -knows about the Perl C<stat> operator and file tests, so you shouldn't ever -see this warning in response to a Perl command; it arises only if some internal -code takes stat buffers lightly.) +(S) A warning peculiar to VMS. This arises because of the difference +between access checks under VMS and under the Unix model Perl assumes. +Under VMS, access checks are done by filename, rather than by bits in +the stat buffer, so that ACLs and other protections can be taken into +account. Unfortunately, Perl assumes that the stat buffer contains all +the necessary information, and passes it, instead of the filespec, to +the access checking routine. It will try to retrieve the filespec using +the device name and FID present in the stat buffer, but this works only +if you haven't made a subsequent call to the CRTL stat() routine, +because the device name is overwritten with each call. If this warning +appears, the name lookup failed, and the access checking routine gave up +and returned FALSE, just to be conservative. (Note: The access checking +routine knows about the Perl C<stat> operator and file tests, so you +shouldn't ever see this warning in response to a Perl command; it arises +only if some internal code takes stat buffers lightly.) =item Can't get pipe mailbox device name -(P) An error peculiar to VMS. After creating a mailbox to act as a pipe, Perl -can't retrieve its name for later use. +(P) An error peculiar to VMS. After creating a mailbox to act as a +pipe, Perl can't retrieve its name for later use. =item Can't get SYSGEN parameter value for MAXBUF (P) An error peculiar to VMS. Perl asked $GETSYI how big you want your mailbox buffers to be, and didn't get an answer. -=item Can't goto subroutine outside a subroutine +=item Can't "goto" into the middle of a foreach loop -(F) The deeply magical "goto subroutine" call can only replace one subroutine -call for another. It can't manufacture one out of whole cloth. In general -you should be calling it out of only an AUTOLOAD routine anyway. See -L<perlfunc/goto>. +(F) A "goto" statement was executed to jump into the middle of a foreach +loop. You can't get there from here. See L<perlfunc/goto>. + +=item Can't "goto" out of a pseudo block + +(F) A "goto" statement was executed to jump out of what might look like +a block, except that it isn't a proper block. This usually occurs if +you tried to jump out of a sort() block or subroutine, which is a no-no. +See L<perlfunc/goto>. =item Can't goto subroutine from an eval-string -(F) The "goto subroutine" call can't be used to jump out of an eval "string". -(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.) +(F) The "goto subroutine" call can't be used to jump out of an eval +"string". (You can use it to jump out of an eval {BLOCK}, but you +probably don't want to.) + +=item Can't goto subroutine outside a subroutine + +(F) The deeply magical "goto subroutine" call can only replace one +subroutine call for another. It can't manufacture one out of whole +cloth. In general you should be calling it out of only an AUTOLOAD +routine anyway. See L<perlfunc/goto>. =item Can't ignore signal CHLD, forcing to default -(W signal) Perl has detected that it is being run with the SIGCHLD signal -(sometimes known as SIGCLD) disabled. Since disabling this signal -will interfere with proper determination of exit status of child -processes, Perl has reset the signal to its default value. -This situation typically indicates that the parent program under -which Perl may be running (e.g. cron) is being very careless. +(W signal) Perl has detected that it is being run with the SIGCHLD +signal (sometimes known as SIGCLD) disabled. Since disabling this +signal will interfere with proper determination of exit status of child +processes, Perl has reset the signal to its default value. This +situation typically indicates that the parent program under which Perl +may be running (e.g. cron) is being very careless. -=item Can't localize through a reference +=item Can't "last" outside a loop block -(F) You said something like C<local $$ref>, which Perl can't currently -handle, because when it goes to restore the old value of whatever $ref -pointed to after the scope of the local() is finished, it can't be -sure that $ref will still be a reference. +(F) A "last" statement was executed to break out of the current block, +except that there's this itty bitty problem called there isn't a current +block. Note that an "if" or "else" block doesn't count as a "loopish" +block, as doesn't a block given to sort(), map() or grep(). You can +usually double the curlies to get the same effect though, because the +inner curlies will be considered a block that loops once. See +L<perlfunc/last>. =item Can't localize lexical variable %s @@ -897,27 +712,34 @@ package name. =item Can't localize pseudo-hash element -(F) You said something like C<< local $ar->{'key'} >>, where $ar is -a reference to a pseudo-hash. That hasn't been implemented yet, but -you can get a similar effect by localizing the corresponding array -element directly -- C<< local $ar->[$ar->[0]{'key'}] >>. +(F) You said something like C<< local $ar->{'key'} >>, where $ar is a +reference to a pseudo-hash. That hasn't been implemented yet, but you +can get a similar effect by localizing the corresponding array element +directly -- C<< local $ar->[$ar->[0]{'key'}] >>. -=item Can't locate auto/%s.al in @INC +=item Can't localize through a reference -(F) A function (or method) was called in a package which allows autoload, -but there is no function to autoload. Most probable causes are a misprint -in a function/method name or a failure to C<AutoSplit> the file, say, by -doing C<make install>. +(F) You said something like C<local $$ref>, which Perl can't currently +handle, because when it goes to restore the old value of whatever $ref +pointed to after the scope of the local() is finished, it can't be sure +that $ref will still be a reference. =item Can't locate %s (F) You said to C<do> (or C<require>, or C<use>) a file that couldn't be found. Perl looks for the file in all the locations mentioned in @INC, -unless the file name included the full path to the file. Perhaps you need -to set the PERL5LIB or PERL5OPT environment variable to say where the extra -library is, or maybe the script needs to add the library name to @INC. Or -maybe you just misspelled the name of the file. See L<perlfunc/require> -and L<lib>. +unless the file name included the full path to the file. Perhaps you +need to set the PERL5LIB or PERL5OPT environment variable to say where +the extra library is, or maybe the script needs to add the library name +to @INC. Or maybe you just misspelled the name of the file. See +L<perlfunc/require> and L<lib>. + +=item Can't locate auto/%s.al in @INC + +(F) A function (or method) was called in a package which allows +autoload, but there is no function to autoload. Most probable causes +are a misprint in a function/method name or a failure to C<AutoSplit> +the file, say, by doing C<make install>. =item Can't locate object method "%s" via package "%s" @@ -927,86 +749,115 @@ method, nor does any of its base classes. See L<perlobj>. =item Can't locate package %s for @%s::ISA -(W syntax) The @ISA array contained the name of another package that doesn't seem -to exist. +(W syntax) The @ISA array contained the name of another package that +doesn't seem to exist. =item Can't make list assignment to \%ENV on this system -(F) List assignment to %ENV is not supported on some systems, notably VMS. +(F) List assignment to %ENV is not supported on some systems, notably +VMS. =item Can't modify %s in %s -(F) You aren't allowed to assign to the item indicated, or otherwise try to -change it, such as with an auto-increment. - -=item Can't modify non-lvalue subroutine call - -(F) Subroutines meant to be used in lvalue context should be declared as -such, see L<perlsub/"Lvalue subroutines">. +(F) You aren't allowed to assign to the item indicated, or otherwise try +to change it, such as with an auto-increment. =item Can't modify nonexistent substring (P) The internal routine that does assignment to a substr() was handed a NULL. +=item Can't modify non-lvalue subroutine call + +(F) Subroutines meant to be used in lvalue context should be declared as +such, see L<perlsub/"Lvalue subroutines">. + =item Can't msgrcv to read-only var (F) The target of a msgrcv must be modifiable to be used as a receive buffer. +=item Can't "next" outside a loop block + +(F) A "next" statement was executed to reiterate the current block, but +there isn't a current block. Note that an "if" or "else" block doesn't +count as a "loopish" block, as doesn't a block given to sort(), map() or +grep(). You can usually double the curlies to get the same effect +though, because the inner curlies will be considered a block that loops +once. See L<perlfunc/next>. + =item Can't open %s: %s (S inplace) The implicit opening of a file through use of the C<< <> >> filehandle, either implicitly under the C<-n> or C<-p> command-line switches, or explicitly, failed for the indicated reason. Usually this -is because you don't have read permission for a file which you named -on the command line. +is because you don't have read permission for a file which you named on +the command line. =item Can't open bidirectional pipe -(W pipe) You tried to say C<open(CMD, "|cmd|")>, which is not supported. You can -try any of several modules in the Perl library to do this, such as -IPC::Open2. Alternately, direct the pipe's output to a file using ">", -and then read it in under a different file handle. +(W pipe) You tried to say C<open(CMD, "|cmd|")>, which is not supported. +You can try any of several modules in the Perl library to do this, such +as IPC::Open2. Alternately, direct the pipe's output to a file using +">", and then read it in under a different file handle. =item Can't open error file %s as stderr -(F) An error peculiar to VMS. Perl does its own command line redirection, and -couldn't open the file specified after '2>' or '2>>' on the -command line for writing. +(F) An error peculiar to VMS. Perl does its own command line +redirection, and couldn't open the file specified after '2>' or '2>>' on +the command line for writing. =item Can't open input file %s as stdin -(F) An error peculiar to VMS. Perl does its own command line redirection, and -couldn't open the file specified after '<' on the command line for reading. +(F) An error peculiar to VMS. Perl does its own command line +redirection, and couldn't open the file specified after '<' on the +command line for reading. =item Can't open output file %s as stdout -(F) An error peculiar to VMS. Perl does its own command line redirection, and -couldn't open the file specified after '>' or '>>' on the command -line for writing. +(F) An error peculiar to VMS. Perl does its own command line +redirection, and couldn't open the file specified after '>' or '>>' on +the command line for writing. =item Can't open output pipe (name: %s) -(P) An error peculiar to VMS. Perl does its own command line redirection, and -couldn't open the pipe into which to send data destined for stdout. +(P) An error peculiar to VMS. Perl does its own command line +redirection, and couldn't open the pipe into which to send data destined +for stdout. =item Can't open perl script "%s": %s (F) The script you specified can't be opened for the indicated reason. +=item Can't read CRTL environ + +(S) A warning peculiar to VMS. Perl tried to read an element of %ENV +from the CRTL's internal environment array and discovered the array was +missing. You need to figure out where your CRTL misplaced its environ +or define F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not +searched. + =item Can't redefine active sort subroutine %s (F) Perl optimizes the internal handling of sort subroutines and keeps -pointers into them. You tried to redefine one such sort subroutine when it -was currently active, which is not allowed. If you really want to do +pointers into them. You tried to redefine one such sort subroutine when +it was currently active, which is not allowed. If you really want to do this, you should write C<sort { &func } @x> instead of C<sort func @x>. +=item Can't "redo" outside a loop block + +(F) A "redo" statement was executed to restart the current block, but +there isn't a current block. Note that an "if" or "else" block doesn't +count as a "loopish" block, as doesn't a block given to sort(), map() +or grep(). You can usually double the curlies to get the same effect +though, because the inner curlies will be considered a block that +loops once. See L<perlfunc/redo>. + =item Can't remove %s: %s, skipping file -(S inplace) You requested an inplace edit without creating a backup file. Perl -was unable to remove the original file to replace it with the modified -file. The file was left unmodified. +(S inplace) You requested an inplace edit without creating a backup +file. Perl was unable to remove the original file to replace it with +the modified file. The file was left unmodified. =item Can't rename %s to %s: %s, skipping file @@ -1015,41 +866,47 @@ probably because you don't have write permission to the directory. =item Can't reopen input pipe (name: %s) in binary mode -(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried to -reopen it to accept binary data. Alas, it failed. +(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried +to reopen it to accept binary data. Alas, it failed. + +=item Can't resolve method `%s' overloading `%s' in package `%s' + +(F|P) Error resolving overloading specified by a method name (as opposed +to a subroutine reference): no such method callable via the package. If +method name is C<???>, this is an internal error. =item Can't reswap uid and euid -(P) The setreuid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setreuid() call failed for some reason in the setuid emulator of +suidperl. + +=item Can't return %s from lvalue subroutine + +(F) Perl detected an attempt to return illegal lvalues (such as +temporary or readonly values) from a subroutine used as an lvalue. This +is not allowed. =item Can't return outside a subroutine (F) The return statement was executed in mainline code, that is, where there was no subroutine call to return out of. See L<perlsub>. -=item Can't return %s from lvalue subroutine - -(F) Perl detected an attempt to return illegal lvalues (such -as temporary or readonly values) from a subroutine used as an lvalue. -This is not allowed. - =item Can't stat script "%s" -(P) For some reason you can't fstat() the script even though you have -it open already. Bizarre. +(P) For some reason you can't fstat() the script even though you have it +open already. Bizarre. =item Can't swap uid and euid -(P) The setreuid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setreuid() call failed for some reason in the setuid emulator of +suidperl. =item Can't take log of %g (F) For ordinary real numbers, you can't take the logarithm of a negative number or zero. There's a Math::Complex package that comes -standard with Perl, though, if you really want to do that for -the negative numbers. +standard with Perl, though, if you really want to do that for the +negative numbers. =item Can't take sqrt of %g @@ -1070,16 +927,26 @@ as the main Perl stack. =item Can't upgrade that kind of scalar -(P) The internal sv_upgrade routine adds "members" to an SV, making -it into a more specialized kind of SV. The top several SV types are -so specialized, however, that they cannot be interconverted. This -message indicates that such a conversion was attempted. +(P) The internal sv_upgrade routine adds "members" to an SV, making it +into a more specialized kind of SV. The top several SV types are so +specialized, however, that they cannot be interconverted. This message +indicates that such a conversion was attempted. =item Can't upgrade to undef -(P) The undefined SV is the bottom of the totem pole, in the scheme -of upgradability. Upgrading to undef indicates an error in the -code calling sv_upgrade. +(P) The undefined SV is the bottom of the totem pole, in the scheme of +upgradability. Upgrading to undef indicates an error in the code +calling sv_upgrade. + +=item Can't use an undefined value as %s reference + +(F) A value used as either a hard reference or a symbolic reference must +be a defined value. This helps to delurk some insidious errors. + +=item Can't use bareword ("%s") as %s ref while "strict refs" in use + +(F) Only hard references are allowed by "strict refs". Symbolic +references are disallowed. See L<perlref>. =item Can't use %%! because Errno.pm is not available @@ -1087,6 +954,19 @@ code calling sv_upgrade. Errno.pm module. The Errno module is expected to tie the %! hash to provide symbolic names for C<$!> errno values. +=item Can't use %s for loop variable + +(F) Only a simple scalar variable may be used as a loop variable on a +foreach. + +=item Can't use global %s in "my" + +(F) You tried to declare a magical variable as a lexical variable. This +is not allowed, because the magic can be tied to only one location +(namely the global variable) and it would be incredibly confusing to +have variables in your program that looked like magical variables but +weren't. + =item Can't use "my %s" in sort comparison (F) The global variables $a and $b are reserved for sort comparisons. @@ -1095,52 +975,16 @@ and the variable had earlier been declared as a lexical variable. Either qualify the sort variable with the package name, or rename the lexical variable. -=item Bad evalled substitution pattern - -(F) You've used the /e switch to evaluate the replacement for a -substitution, but perl found a syntax error in the code to evaluate, -most likely an unexpected right brace '}'. - -=item Can't use %s for loop variable - -(F) Only a simple scalar variable may be used as a loop variable on a foreach. - =item Can't use %s ref as %s ref (F) You've mixed up your reference types. You have to dereference a reference of the type needed. You can use the ref() function to test the type of the reference, if need be. -=item Can't use \%c to mean $%c in expression - -(W syntax) In an ordinary expression, backslash is a unary operator that creates -a reference to its argument. The use of backslash to indicate a backreference -to a matched substring is valid only as part of a regular expression pattern. -Trying to do this in ordinary Perl code produces a value that prints -out looking like SCALAR(0xdecaf). Use the $1 form instead. - -=item Can't use bareword ("%s") as %s ref while "strict refs" in use - -(F) Only hard references are allowed by "strict refs". Symbolic references -are disallowed. See L<perlref>. - =item Can't use string ("%s") as %s ref while "strict refs" in use -(F) Only hard references are allowed by "strict refs". Symbolic references -are disallowed. See L<perlref>. - -=item Can't use an undefined value as %s reference - -(F) A value used as either a hard reference or a symbolic reference must -be a defined value. This helps to delurk some insidious errors. - -=item Can't use global %s in "my" - -(F) You tried to declare a magical variable as a lexical variable. This is -not allowed, because the magic can be tied to only one location (namely -the global variable) and it would be incredibly confusing to have -variables in your program that looked like magical variables but -weren't. +(F) Only hard references are allowed by "strict refs". Symbolic +references are disallowed. See L<perlref>. =item Can't use subscript on %s @@ -1148,6 +992,15 @@ weren't. subscript. But to the left of the brackets was an expression that didn't look like an array reference, or anything else subscriptable. +=item Can't use \%c to mean $%c in expression + +(W syntax) In an ordinary expression, backslash is a unary operator that +creates a reference to its argument. The use of backslash to indicate a +backreference to a matched substring is valid only as part of a regular +expression pattern. Trying to do this in ordinary Perl code produces a +value that prints out looking like SCALAR(0xdecaf). Use the $1 form +instead. + =item Can't weaken a nonreference (F) You attempted to weaken something that was not a reference. Only @@ -1155,49 +1008,38 @@ references can be weakened. =item Can't x= to read-only value -(F) You tried to repeat a constant value (often the undefined value) with -an assignment operator, which implies modifying the value itself. +(F) You tried to repeat a constant value (often the undefined value) +with an assignment operator, which implies modifying the value itself. Perhaps you need to copy the value to a temporary, and repeat that. -=item Can't find an opnumber for "%s" - -(F) A string of a form C<CORE::word> was given to prototype(), but -there is no builtin with the name C<word>. - -=item Can't resolve method `%s' overloading `%s' in package `%s' - -(F|P) Error resolving overloading specified by a method name (as -opposed to a subroutine reference): no such method callable via the -package. If method name is C<???>, this is an internal error. - -=item Character class [:%s:] unknown - -(F) The class in the character class [: :] syntax is unknown. -See L<perlre>. - =item Character class syntax [%s] belongs inside character classes (W unsafe) The character class constructs [: :], [= =], and [. .] go -I<inside> character classes, the [] are part of the construct, -for example: /[012[:alpha:]345]/. Note that [= =] and [. .] -are not currently implemented; they are simply placeholders for -future extensions. +I<inside> character classes, the [] are part of the construct, for +example: /[012[:alpha:]345]/. Note that [= =] and [. .] are not +currently implemented; they are simply placeholders for future +extensions. =item Character class syntax [. .] is reserved for future extensions -(W regexp) Within regular expression character classes ([]) the syntax beginning -with "[." and ending with ".]" is reserved for future extensions. -If you need to represent those character sequences inside a regular -expression character class, just quote the square brackets with the -backslash: "\[." and ".\]". +(W regexp) Within regular expression character classes ([]) the syntax +beginning with "[." and ending with ".]" is reserved for future +extensions. If you need to represent those character sequences inside a +regular expression character class, just quote the square brackets with +the backslash: "\[." and ".\]". =item Character class syntax [= =] is reserved for future extensions (W regexp) Within regular expression character classes ([]) the syntax -beginning with "[=" and ending with "=]" is reserved for future extensions. -If you need to represent those character sequences inside a regular -expression character class, just quote the square brackets with the -backslash: "\[=" and "=\]". +beginning with "[=" and ending with "=]" is reserved for future +extensions. If you need to represent those character sequences inside a +regular expression character class, just quote the square brackets with +the backslash: "\[=" and "=\]". + +=item Character class [:%s:] unknown + +(F) The class in the character class [: :] syntax is unknown. See +L<perlre>. =item chmod() mode argument is missing initial 0 @@ -1205,148 +1047,163 @@ backslash: "\[=" and "=\]". chmod 777, $filename -not realizing that 777 will be interpreted as a decimal number, equivalent -to 01411. Octal constants are introduced with a leading 0 in Perl, as in C. +not realizing that 777 will be interpreted as a decimal number, +equivalent to 01411. Octal constants are introduced with a leading 0 in +Perl, as in C. =item Close on unopened file <%s> (W unopened) You tried to close a filehandle that was never opened. +=item %s: Command not found + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + =item Compilation failed in require (F) Perl could not compile a file specified in a C<require> statement. -Perl uses this generic message when none of the errors that it encountered -were severe enough to halt compilation immediately. +Perl uses this generic message when none of the errors that it +encountered were severe enough to halt compilation immediately. =item Complex regular subexpression recursion limit (%d) exceeded -(W regexp) The regular expression engine uses recursion in complex situations -where back-tracking is required. Recursion depth is limited to 32766, -or perhaps less in architectures where the stack cannot grow +(W regexp) The regular expression engine uses recursion in complex +situations where back-tracking is required. Recursion depth is limited +to 32766, or perhaps less in architectures where the stack cannot grow arbitrarily. ("Simple" and "medium" situations are handled without recursion and are not subject to a limit.) Try shortening the string -under examination; looping in Perl code (e.g. with C<while>) rather -than in the regular expression engine; or rewriting the regular -expression so that it is simpler or backtracks less. (See L<perlbook> -for information on I<Mastering Regular Expressions>.) +under examination; looping in Perl code (e.g. with C<while>) rather than +in the regular expression engine; or rewriting the regular expression so +that it is simpler or backtracks less. (See L<perlbook> for information +on I<Mastering Regular Expressions>.) =item connect() on closed socket %s -(W closed) You tried to do a connect on a closed socket. Did you forget to check -the return value of your socket() call? See L<perlfunc/connect>. +(W closed) You tried to do a connect on a closed socket. Did you forget +to check the return value of your socket() call? See +L<perlfunc/connect>. + +=item constant(%s): %s + +(F) The parser found inconsistencies either while attempting to define +an overloaded constant, or when trying to find the character name +specified in the C<\N{...}> escape. Perhaps you forgot to load the +corresponding C<overload> or C<charnames> pragma? See L<charnames> and +L<overload>. =item Constant is not %s reference (F) A constant value (perhaps declared using the C<use constant> pragma) -is being dereferenced, but it amounts to the wrong type of reference. The -message indicates the type of reference that was expected. This usually -indicates a syntax error in dereferencing the constant value. +is being dereferenced, but it amounts to the wrong type of reference. +The message indicates the type of reference that was expected. This +usually indicates a syntax error in dereferencing the constant value. See L<perlsub/"Constant Functions"> and L<constant>. =item Constant subroutine %s redefined -(S|W redefine) You redefined a subroutine which had previously been eligible for -inlining. See L<perlsub/"Constant Functions"> for commentary and -workarounds. +(S|W redefine) You redefined a subroutine which had previously been +eligible for inlining. See L<perlsub/"Constant Functions"> for +commentary and workarounds. =item Constant subroutine %s undefined -(W misc) You undefined a subroutine which had previously been eligible for -inlining. See L<perlsub/"Constant Functions"> for commentary and +(W misc) You undefined a subroutine which had previously been eligible +for inlining. See L<perlsub/"Constant Functions"> for commentary and workarounds. -=item constant(%s): %%^H is not localized +=item Copy method did not return a reference -(F) When setting compile-time-lexicalized hash %^H one should set the -corresponding bit of $^H as well. +(F) The method which overloads "=" is buggy. See L<overload/Copy +Constructor>. -=item constant(%s): %s +=item CORE::%s is not a keyword -(F) Compile-time-substitutions (such as overloaded constants and -character names) were not correctly set up. +(F) The CORE:: namespace is reserved for Perl keywords. -=item Copy method did not return a reference +=item corrupted regexp pointers -(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>. +(P) The regular expression engine got confused by what the regular +expression compiler gave it. -=item CORE::%s is not a keyword +=item corrupted regexp program -(F) The CORE:: namespace is reserved for Perl keywords. +(P) The regular expression engine got passed a regexp program without a +valid magic number. =item Corrupt malloc ptr 0x%lx at 0x%lx (P) The malloc package that comes with Perl had an internal failure. -=item corrupted regexp pointers +=item C<-p> destination: %s -(P) The regular expression engine got confused by what the regular -expression compiler gave it. +(F) An error occurred during the implicit output invoked by the C<-p> +command-line switch. (This output goes to STDOUT unless you've +redirected it with select().) -=item corrupted regexp program +=item C<-T> and C<-B> not implemented on filehandles -(P) The regular expression engine got passed a regexp program without -a valid magic number. +(F) Perl can't peek at the stdio buffer of filehandles when it doesn't +know about your kind of stdio. You'll have to use a filename instead. =item Deep recursion on subroutine "%s" -(W recursion) This subroutine has called itself (directly or indirectly) 100 -times more than it has returned. This probably indicates an infinite -recursion, unless you're writing strange benchmark programs, in which -case it indicates something else. +(W recursion) This subroutine has called itself (directly or indirectly) +100 times more than it has returned. This probably indicates an +infinite recursion, unless you're writing strange benchmark programs, in +which case it indicates something else. =item defined(@array) is deprecated -(D deprecated) defined() is not usually useful on arrays because it checks for an -undefined I<scalar> value. If you want to see if the array is empty, -just use C<if (@array) { # not empty }> for example. +(D deprecated) defined() is not usually useful on arrays because it +checks for an undefined I<scalar> value. If you want to see if the +array is empty, just use C<if (@array) { # not empty }> for example. =item defined(%hash) is deprecated -(D deprecated) defined() is not usually useful on hashes because it checks for an -undefined I<scalar> value. If you want to see if the hash is empty, -just use C<if (%hash) { # not empty }> for example. +(D deprecated) defined() is not usually useful on hashes because it +checks for an undefined I<scalar> value. If you want to see if the hash +is empty, just use C<if (%hash) { # not empty }> for example. =item Delimiter for here document is too long -(F) In a here document construct like C<<<FOO>, the label -C<FOO> is too long for Perl to handle. You have to be seriously -twisted to write code that triggers this error. +(F) In a here document construct like C<<<FOO>, the label C<FOO> is too +long for Perl to handle. You have to be seriously twisted to write code +that triggers this error. =item Did not produce a valid header See Server error. -=item Did you mean &%s instead? +=item %s did not return a true value + +(F) A required (or used) file must return a true value to indicate that +it compiled correctly and ran its initialization code correctly. It's +traditional to end such a file with a "1;", though any true value would +do. See L<perlfunc/require>. + +=item (Did you mean &%s instead?) -(W) You probably referred to an imported subroutine &FOO as $FOO or some such. +(W) You probably referred to an imported subroutine &FOO as $FOO or some +such. -=item Did you mean "local" instead of "our"? +=item (Did you mean "local" instead of "our"?) -(W misc) Remember that "our" does not localize the declared global variable. -You have declared it again in the same lexical scope, which seems superfluous. +(W misc) Remember that "our" does not localize the declared global +variable. You have declared it again in the same lexical scope, which +seems superfluous. -=item Did you mean $ or @ instead of %? +=item (Did you mean $ or @ instead of %?) -(W) You probably said %hash{$key} when you meant $hash{$key} or @hash{@keys}. -On the other hand, maybe you just meant %hash and got carried away. +(W) You probably said %hash{$key} when you meant $hash{$key} or +@hash{@keys}. On the other hand, maybe you just meant %hash and got +carried away. =item Died (F) You passed die() an empty string (the equivalent of C<die "">) or you called it with no args and both C<$@> and C<$_> were empty. -=item Do you need to predeclare %s? - -(S) This is an educated guess made in conjunction with the message "%s -found where operator expected". It often means a subroutine or module -name is being referenced that hasn't been declared yet. This may be -because of ordering problems in your file, or because of a missing -"sub", "package", "require", or "use" statement. If you're -referencing something that isn't defined yet, you don't actually have -to define the subroutine or package before the current location. You -can use an empty "sub foo;" or "package FOO;" to enter a "forward" -declaration. - =item Document contains no data See Server error. @@ -1359,24 +1216,29 @@ See Server error. (P) This should have been caught by safemalloc() instead. +=item (Do you need to predeclare %s?) + +(S) This is an educated guess made in conjunction with the message "%s +found where operator expected". It often means a subroutine or module +name is being referenced that hasn't been declared yet. This may be +because of ordering problems in your file, or because of a missing +"sub", "package", "require", or "use" statement. If you're referencing +something that isn't defined yet, you don't actually have to define the +subroutine or package before the current location. You can use an empty +"sub foo;" or "package FOO;" to enter a "forward" declaration. + =item Duplicate free() ignored -(S malloc) An internal routine called free() on something that had already -been freed. +(S malloc) An internal routine called free() on something that had +already been freed. =item elseif should be elsif -(S) There is no keyword "elseif" in Perl because Larry thinks it's -ugly. Your code will be interpreted as an attempt to call a method -named "elseif" for the class returned by the following block. This is +(S) There is no keyword "elseif" in Perl because Larry thinks it's ugly. +Your code will be interpreted as an attempt to call a method named +"elseif" for the class returned by the following block. This is unlikely to be what you want. -=item %s failed--call queue aborted - -(F) An untrapped exception was raised while executing a CHECK, INIT, or -END subroutine. Processing of the remainder of the queue of such -routines has been prematurely ended. - =item entering effective %s failed (F) While under the C<use filetest> pragma, switching the real and @@ -1386,30 +1248,30 @@ effective uids or gids failed. (F) An error peculiar to VMS. Because Perl may have to deal with file specifications in either VMS or Unix syntax, it converts them to a -single form when it must operate on them directly. Either you've -passed an invalid file specification to Perl, or you've found a -case the conversion routines don't handle. Drat. +single form when it must operate on them directly. Either you've passed +an invalid file specification to Perl, or you've found a case the +conversion routines don't handle. Drat. =item %s: Eval-group in insecure regular expression -(F) Perl detected tainted data when trying to compile a regular expression -that contains the C<(?{ ... })> zero-width assertion, which is unsafe. -See L<perlre/(?{ code })>, and L<perlsec>. +(F) Perl detected tainted data when trying to compile a regular +expression that contains the C<(?{ ... })> zero-width assertion, which +is unsafe. See L<perlre/(?{ code })>, and L<perlsec>. -=item %s: Eval-group not allowed, use re 'eval' +=item %s: Eval-group not allowed at run time -(F) A regular expression contained the C<(?{ ... })> zero-width assertion, -but that construct is only allowed when the C<use re 'eval'> pragma is -in effect. See L<perlre/(?{ code })>. +(F) Perl tried to compile a regular expression containing the +C<(?{ ... })> zero-width assertion at run time, as it would when the +pattern contains interpolated values. Since that is a security risk, it +is not allowed. If you insist, you may still do this by explicitly +building the pattern from an interpolated string at run time and using +that in an eval(). See L<perlre/(?{ code })>. -=item %s: Eval-group not allowed at run time +=item %s: Eval-group not allowed, use re 'eval' -(F) Perl tried to compile a regular expression containing the C<(?{ ... })> -zero-width assertion at run time, as it would when the pattern contains -interpolated values. Since that is a security risk, it is not allowed. -If you insist, you may still do this by explicitly building the pattern -from an interpolated string at run time and using that in an eval(). -See L<perlre/(?{ code })>. +(F) A regular expression contained the C<(?{ ... })> zero-width +assertion, but that construct is only allowed when the C<use re 'eval'> +pragma is in effect. See L<perlre/(?{ code })>. =item Excessively long <> operator @@ -1424,50 +1286,61 @@ variable and glob that. =item Exiting eval via %s -(W exiting) You are exiting an eval by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting an eval by unconventional means, such as a +goto, or a loop control statement. =item Exiting format via %s -(W exiting) You are exiting an eval by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting an eval by unconventional means, such as a +goto, or a loop control statement. =item Exiting pseudo-block via %s -(W exiting) You are exiting a rather special block construct (like a sort block or -subroutine) by unconventional means, such as a goto, or a loop control -statement. See L<perlfunc/sort>. +(W exiting) You are exiting a rather special block construct (like a +sort block or subroutine) by unconventional means, such as a goto, or a +loop control statement. See L<perlfunc/sort>. =item Exiting subroutine via %s -(W exiting) You are exiting a subroutine by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting a subroutine by unconventional means, such +as a goto, or a loop control statement. =item Exiting substitution via %s -(W exiting) You are exiting a substitution by unconventional means, such as -a return, a goto, or a loop control statement. +(W exiting) You are exiting a substitution by unconventional means, such +as a return, a goto, or a loop control statement. =item Explicit blessing to '' (assuming package main) (W misc) You are blessing a reference to a zero length string. This has the effect of blessing the reference into the package main. This is -usually not what you want. Consider providing a default target -package, e.g. bless($ref, $p || 'MyPackage'); +usually not what you want. Consider providing a default target package, +e.g. bless($ref, $p || 'MyPackage'); + +=item %s: Expression syntax + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + +=item %s failed--call queue aborted + +(F) An untrapped exception was raised while executing a CHECK, INIT, or +END subroutine. Processing of the remainder of the queue of such +routines has been prematurely ended. =item false [] range "%s" in regexp -(W regexp) A character class range must start and end at a literal character, not -another character class like C<\d> or C<[:alpha:]>. The "-" in your false -range is interpreted as a literal "-". Consider quoting the "-", "\-". -See L<perlre>. +(W regexp) A character class range must start and end at a literal +character, not another character class like C<\d> or C<[:alpha:]>. The +"-" in your false range is interpreted as a literal "-". Consider +quoting the "-", "\-". See L<perlre>. =item Fatal VMS error at %s, line %d -(P) An error peculiar to VMS. Something untoward happened in a VMS system -service or RTL routine; Perl's exit status should provide more details. The -filename in "at %s" and the line number in "line %d" tell you which section of -the Perl source code is distressed. +(P) An error peculiar to VMS. Something untoward happened in a VMS +system service or RTL routine; Perl's exit status should provide more +details. The filename in "at %s" and the line number in "line %d" tell +you which section of the Perl source code is distressed. =item fcntl is not implemented @@ -1476,45 +1349,54 @@ PDP-11 or something? =item Filehandle %s never opened -(W unopened) An I/O operation was attempted on a filehandle that was never initialized. -You need to do an open() or a socket() call, or call a constructor from -the FileHandle package. +(W unopened) An I/O operation was attempted on a filehandle that was +never initialized. You need to do an open() or a socket() call, or call +a constructor from the FileHandle package. =item Filehandle %s opened only for input -(W io) You tried to write on a read-only filehandle. If you -intended it to be a read-write filehandle, you needed to open it with -"+<" or "+>" or "+>>" instead of with "<" or nothing. If -you intended only to write the file, use ">" or ">>". See -L<perlfunc/open>. +(W io) You tried to write on a read-only filehandle. If you intended it +to be a read-write filehandle, you needed to open it with "+<" or "+>" +or "+>>" instead of with "<" or nothing. If you intended only to write +the file, use ">" or ">>". See L<perlfunc/open>. =item Filehandle %s opened only for output -(W io) You tried to read from a filehandle opened only for writing. If you -intended it to be a read/write filehandle, you needed to open it with -"+<" or "+>" or "+>>" instead of with "<" or nothing. If -you intended only to read from the file, use "<". See -L<perlfunc/open>. +(W io) You tried to read from a filehandle opened only for writing. If +you intended it to be a read/write filehandle, you needed to open it +with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you +intended only to read from the file, use "<". See L<perlfunc/open>. =item Final $ should be \$ or $name (F) You must now decide whether the final $ in a string was meant to be -a literal dollar sign, or was meant to introduce a variable name -that happens to be missing. So you have to put either the backslash or -the name. +a literal dollar sign, or was meant to introduce a variable name that +happens to be missing. So you have to put either the backslash or the +name. =item Final @ should be \@ or @name (F) You must now decide whether the final @ in a string was meant to be -a literal "at" sign, or was meant to introduce a variable name -that happens to be missing. So you have to put either the backslash or -the name. +a literal "at" sign, or was meant to introduce a variable name that +happens to be missing. So you have to put either the backslash or the +name. =item flock() on closed filehandle %s -(W closed) The filehandle you're attempting to flock() got itself closed some -time before now. Check your logic flow. flock() operates on filehandles. -Are you attempting to call flock() on a dirhandle by the same name? +(W closed) The filehandle you're attempting to flock() got itself closed +some time before now. Check your logic flow. flock() operates on +filehandles. Are you attempting to call flock() on a dirhandle by the +same name? + +=item ?+* follows nothing in regexp + +(F) You started a regular expression with a quantifier. Backslash it if +you meant it literally. See L<perlre>. + +=item Format not terminated + +(F) A format must be terminated by a line with a solitary dot. Perl got +to the end of your file without finding such a line. =item Format %s redefined @@ -1525,11 +1407,6 @@ Are you attempting to call flock() on a dirhandle by the same name? eval "format NAME =..."; } -=item Format not terminated - -(F) A format must be terminated by a line with a solitary dot. Perl got -to the end of your file without finding such a line. - =item Found = in conditional, should be == (W syntax) You said @@ -1542,6 +1419,13 @@ when you meant (or something like that). +=item %s found where operator expected + +(S) The Perl lexer knows whether to expect a term or an operator. If it +sees what it knows to be a term when it was expecting to see an +operator, it gives you this warning. Usually it indicates that an +operator or delimiter was omitted, such as a semicolon. + =item gdbm store returned %d, errno %d, key "%s" (S) A warning from the GDBM_File extension that a store failed. @@ -1554,34 +1438,19 @@ on the Internet. =item get%sname() on closed socket %s -(W closed) You tried to get a socket or peer socket name on a closed socket. -Did you forget to check the return value of your socket() call? +(W closed) You tried to get a socket or peer socket name on a closed +socket. Did you forget to check the return value of your socket() call? =item getpwnam returned invalid UIC %#o for user "%s" (S) A warning peculiar to VMS. The call to C<sys$getuai> underlying the C<getpwnam> operator returned an invalid UIC. -=item glob failed (%s) +=item getsockopt() on closed socket %s -(W glob) Something went wrong with the external program(s) used for C<glob> -and C<< <*.c> >>. Usually, this means that you supplied a C<glob> -pattern that caused the external program to fail and exit with a nonzero -status. If the message indicates that the abnormal exit resulted in a -coredump, this may also mean that your csh (C shell) is broken. If so, -you should change all of the csh-related variables in config.sh: If you -have tcsh, make the variables refer to it as if it were csh (e.g. -C<full_csh='/usr/bin/tcsh'>); otherwise, make them all empty (except that -C<d_csh> should be C<'undef'>) so that Perl will think csh is missing. -In either case, after editing config.sh, run C<./Configure -S> and -rebuild Perl. - -=item Glob not terminated - -(F) The lexer saw a left angle bracket in a place where it was expecting -a term, so it's looking for the corresponding right angle bracket, and not -finding it. Chances are you left some needed parentheses out earlier in -the line, and you really meant a "less than". +(W closed) You tried to get a socket option on a closed socket. Did you +forget to check the return value of your socket() call? See +L<perlfunc/getsockopt>. =item Global symbol "%s" requires explicit package name @@ -1590,21 +1459,56 @@ must either be lexically scoped (using "my"), declared beforehand using "our", or explicitly qualified to say which package the global variable is in (using "::"). +=item glob failed (%s) + +(W glob) Something went wrong with the external program(s) used for +C<glob> and C<< <*.c> >>. Usually, this means that you supplied a +C<glob> pattern that caused the external program to fail and exit with a +nonzero status. If the message indicates that the abnormal exit +resulted in a coredump, this may also mean that your csh (C shell) is +broken. If so, you should change all of the csh-related variables in +config.sh: If you have tcsh, make the variables refer to it as if it +were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all +empty (except that C<d_csh> should be C<'undef'>) so that Perl will +think csh is missing. In either case, after editing config.sh, run +C<./Configure -S> and rebuild Perl. + +=item Glob not terminated + +(F) The lexer saw a left angle bracket in a place where it was expecting +a term, so it's looking for the corresponding right angle bracket, and +not finding it. Chances are you left some needed parentheses out +earlier in the line, and you really meant a "less than". + +=item Got an error from DosAllocMem + +(P) An error peculiar to OS/2. Most probably you're using an obsolete +version of Perl, and this should not happen anyway. + =item goto must have label (F) Unlike with "next" or "last", you're not allowed to goto an unspecified destination. See L<perlfunc/goto>. +=item %s had compilation errors + +(F) The final summary message when a C<perl -c> fails. + =item Had to create %s unexpectedly -(S internal) A routine asked for a symbol from a symbol table that ought to have -existed already, but for some reason it didn't, and had to be created on -an emergency basis to prevent a core dump. +(S internal) A routine asked for a symbol from a symbol table that ought +to have existed already, but for some reason it didn't, and had to be +created on an emergency basis to prevent a core dump. =item Hash %%s missing the % in argument %d of %s() -(D deprecated) Really old Perl let you omit the % on hash names in some spots. This -is now heavily deprecated. +(D deprecated) Really old Perl let you omit the % on hash names in some +spots. This is now heavily deprecated. + +=item %s has too many errors + +(F) The parser has given up trying to parse the program after 10 errors. +Further error messages would likely be uninformative. =item Hexadecimal number > 0xffffffff non-portable @@ -1616,99 +1520,102 @@ L<perlport> for more on portability concerns. (F) Perl limits identifiers (names for variables, functions, etc.) to about 250 characters for simple names, and somewhat more for compound -names (like C<$A::B>). You've exceeded Perl's limits. Future -versions of Perl are likely to eliminate these arbitrary limitations. +names (like C<$A::B>). You've exceeded Perl's limits. Future versions +of Perl are likely to eliminate these arbitrary limitations. -=item Ill-formed CRTL environ value "%s" +=item Illegal binary digit %s -(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal -environ array, and encountered an element without the C<=> delimiter -used to spearate keys from values. The element is ignored. +(F) You used a digit other than 0 or 1 in a binary number. -=item Ill-formed message in prime_env_iter: |%s| +=item Illegal binary digit %s ignored -(W internal) A warning peculiar to VMS. Perl tried to read a logical name -or CLI symbol definition when preparing to iterate over %ENV, and -didn't see the expected delimiter between key and value, so the -line was ignored. +(W digit) You may have tried to use a digit other than 0 or 1 in a +binary number. Interpretation of the binary number stopped before the +offending digit. =item Illegal character %s (carriage return) (F) Perl normally treats carriage returns in the program text as it -would any other whitespace, which means you should never see this -error when Perl was built using standard options. For some reason, -your version of Perl appears to have been built without this support. -Talk to your Perl administrator. +would any other whitespace, which means you should never see this error +when Perl was built using standard options. For some reason, your +version of Perl appears to have been built without this support. Talk +to your Perl administrator. =item Illegal division by zero -(F) You tried to divide a number by 0. Either something was wrong in your -logic, or you need to put a conditional in to guard against meaningless input. +(F) You tried to divide a number by 0. Either something was wrong in +your logic, or you need to put a conditional in to guard against +meaningless input. + +=item Illegal hexadecimal digit %s ignored + +(W digit) You may have tried to use a character other than 0 - 9 or +A - F, a - f in a hexadecimal number. Interpretation of the hexadecimal +number stopped before the illegal character. =item Illegal modulus zero -(F) You tried to divide a number by 0 to get the remainder. Most numbers -don't take to this kindly. +(F) You tried to divide a number by 0 to get the remainder. Most +numbers don't take to this kindly. -=item Illegal binary digit %s +=item Illegal number of bits in vec -(F) You used a digit other than 0 or 1 in a binary number. +(F) The number of bits in vec() (the third argument) must be a power of +two from 1 to 32 (or 64, if your platform supports that). =item Illegal octal digit %s (F) You used an 8 or 9 in a octal number. -=item Illegal binary digit %s ignored - -(W digit) You may have tried to use a digit other than 0 or 1 in a binary number. -Interpretation of the binary number stopped before the offending digit. - =item Illegal octal digit %s ignored -(W digit) You may have tried to use an 8 or 9 in a octal number. Interpretation -of the octal number stopped before the 8 or 9. +(W digit) You may have tried to use an 8 or 9 in a octal number. +Interpretation of the octal number stopped before the 8 or 9. -=item Illegal hexadecimal digit %s ignored +=item Illegal switch in PERL5OPT: %s -(W digit) You may have tried to use a character other than 0 - 9 or A - F, a - f -in a hexadecimal number. Interpretation of the hexadecimal number stopped -before the illegal character. +(X) The PERL5OPT environment variable may only be used to set the +following switches: B<-[DIMUdmw]>. -=item Illegal number of bits in vec +=item Ill-formed CRTL environ value "%s" -(F) The number of bits in vec() (the third argument) must be a power of -two from 1 to 32 (or 64, if your platform supports that). +(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's +internal environ array, and encountered an element without the C<=> +delimiter used to separate keys from values. The element is ignored. -=item Illegal switch in PERL5OPT: %s +=item Ill-formed message in prime_env_iter: |%s| -(X) The PERL5OPT environment variable may only be used to set the -following switches: B<-[DIMUdmw]>. +(W internal) A warning peculiar to VMS. Perl tried to read a logical +name or CLI symbol definition when preparing to iterate over %ENV, and +didn't see the expected delimiter between key and value, so the line was +ignored. -=item In string, @%s now must be written as \@%s +=item (in cleanup) %s -(F) It used to be that Perl would try to guess whether you wanted an -array interpolated or a literal @. It did this when the string was first -used at runtime. Now strings are parsed at compile time, and ambiguous -instances of @ must be disambiguated, either by prepending a backslash to -indicate a literal, or by declaring (or using) the array within the -program before the string (lexically). (Someday it will simply assume -that an unbackslashed @ interpolates an array.) +(W misc) This prefix usually indicates that a DESTROY() method raised +the indicated exception. Since destructors are usually called by the +system at arbitrary points during execution, and often a vast number of +times, the warning is issued only once for any number of failures that +would otherwise result in the same message being repeated. + +Failure of user callbacks dispatched using the C<G_KEEPERR> flag could +also result in this warning. See L<perlcall/G_KEEPERR>. =item Insecure dependency in %s (F) You tried to do something that the tainting mechanism didn't like. -The tainting mechanism is turned on when you're running setuid or setgid, -or when you specify B<-T> to turn it on explicitly. The tainting mechanism -labels all data that's derived directly or indirectly from the user, -who is considered to be unworthy of your trust. If any such data is -used in a "dangerous" operation, you get this error. See L<perlsec> -for more information. +The tainting mechanism is turned on when you're running setuid or +setgid, or when you specify B<-T> to turn it on explicitly. The +tainting mechanism labels all data that's derived directly or indirectly +from the user, who is considered to be unworthy of your trust. If any +such data is used in a "dangerous" operation, you get this error. See +L<perlsec> for more information. =item Insecure directory in %s -(F) You can't use system(), exec(), or a piped open in a setuid or setgid -script if C<$ENV{PATH}> contains a directory that is writable by the world. -See L<perlsec>. +(F) You can't use system(), exec(), or a piped open in a setuid or +setgid script if C<$ENV{PATH}> contains a directory that is writable by +the world. See L<perlsec>. =item Insecure $ENV{%s} while running %s @@ -1718,36 +1625,52 @@ C<$ENV{ENV}> or C<$ENV{BASH_ENV}> are derived from data supplied (or potentially supplied) by the user. The script must set the path to a known value, using trustworthy data. See L<perlsec>. +=item In string, @%s now must be written as \@%s + +(F) It used to be that Perl would try to guess whether you wanted an +array interpolated or a literal @. It did this when the string was +first used at runtime. Now strings are parsed at compile time, and +ambiguous instances of @ must be disambiguated, either by prepending a +backslash to indicate a literal, or by declaring (or using) the array +within the program before the string (lexically). (Someday it will +simply assume that an unbackslashed @ interpolates an array.) + =item Integer overflow in %s number -(W overflow) The hexadecimal, octal or binary number you have specified either -as a literal or as an argument to hex() or oct() is too big for your -architecture, and has been converted to a floating point number. On a -32-bit architecture the largest hexadecimal, octal or binary number +(W overflow) The hexadecimal, octal or binary number you have specified +either as a literal or as an argument to hex() or oct() is too big for +your architecture, and has been converted to a floating point number. +On a 32-bit architecture the largest hexadecimal, octal or binary number representable without overflow is 0xFFFFFFFF, 037777777777, or 0b11111111111111111111111111111111 respectively. Note that Perl transparently promotes all numbers to a floating point representation internally--subject to loss of precision errors in subsequent operations. -=item Internal inconsistency in tracking vforks - -(S) A warning peculiar to VMS. Perl keeps track of the number -of times you've called C<fork> and C<exec>, to determine -whether the current call to C<exec> should affect the current -script or a subprocess (see L<perlvms/"exec LIST">). Somehow, this count -has become scrambled, so Perl is making a guess and treating -this C<exec> as a request to terminate the Perl script -and execute the specified command. - =item internal disaster in regexp (P) Something went badly wrong in the regular expression parser. +=item Internal inconsistency in tracking vforks + +(S) A warning peculiar to VMS. Perl keeps track of the number of times +you've called C<fork> and C<exec>, to determine whether the current call +to C<exec> should affect the current script or a subprocess (see +L<perlvms/"exec LIST">). Somehow, this count has become scrambled, so +Perl is making a guess and treating this C<exec> as a request to +terminate the Perl script and execute the specified command. + =item internal urp in regexp at /%s/ (P) Something went badly awry in the regular expression parser. +=item %s (...) interpreted as function + +(W syntax) You've run afoul of the rule that says that any list operator +followed by parentheses turns into a function, with all the list +operators arguments found inside the parentheses. See L<perlop/Terms +and List Operators (Leftward)>. + =item Invalid %s attribute: %s The indicated attribute for a subroutine or variable was not recognized @@ -1755,37 +1678,38 @@ by Perl or by a user-supplied handler. See L<attributes>. =item Invalid %s attributes: %s -The indicated attributes for a subroutine or variable were not recognized -by Perl or by a user-supplied handler. See L<attributes>. +The indicated attributes for a subroutine or variable were not +recognized by Perl or by a user-supplied handler. See L<attributes>. + +=item Invalid conversion in %s: "%s" + +(W printf) Perl does not understand the given format conversion. See +L<perlfunc/sprintf>. =item invalid [] range "%s" in regexp (F) The range specified in a character class had a minimum character greater than the maximum character. See L<perlre>. -=item Invalid conversion in %s: "%s" - -(W printf) Perl does not understand the given format conversion. -See L<perlfunc/sprintf>. - =item Invalid separator character %s in attribute list (F) Something other than a colon or whitespace was seen between the -elements of an attribute list. If the previous attribute -had a parenthesised parameter list, perhaps that list was terminated -too soon. See L<attributes>. +elements of an attribute list. If the previous attribute had a +parenthesised parameter list, perhaps that list was terminated too soon. +See L<attributes>. =item Invalid type in pack: '%s' (F) The given character is not a valid pack type. See L<perlfunc/pack>. -(W pack) The given character is not a valid pack type but used to be silently -ignored. +(W pack) The given character is not a valid pack type but used to be +silently ignored. =item Invalid type in unpack: '%s' -(F) The given character is not a valid unpack type. See L<perlfunc/unpack>. -(W unpack) The given character is not a valid unpack type but used to be silently -ignored. +(F) The given character is not a valid unpack type. See +L<perlfunc/unpack>. +(W unpack) The given character is not a valid unpack type but used to be +silently ignored. =item ioctl is not implemented @@ -1798,9 +1722,9 @@ strange for a machine that supports C. =item Label not found for "last %s" -(F) You named a loop to break out of, but you're not currently in a -loop of that name, not even if you count where you were called from. -See L<perlfunc/last>. +(F) You named a loop to break out of, but you're not currently in a loop +of that name, not even if you count where you were called from. See +L<perlfunc/last>. =item Label not found for "next %s" @@ -1821,14 +1745,42 @@ effective uids or gids failed. =item listen() on closed socket %s -(W closed) You tried to do a listen on a closed socket. Did you forget to check -the return value of your socket() call? See L<perlfunc/listen>. +(W closed) You tried to do a listen on a closed socket. Did you forget +to check the return value of your socket() call? See +L<perlfunc/listen>. =item Lvalue subs returning %s not implemented yet (F) Due to limitations in the current implementation, array and hash -values cannot be returned in subroutines used in lvalue context. -See L<perlsub/"Lvalue subroutines">. +values cannot be returned in subroutines used in lvalue context. See +L<perlsub/"Lvalue subroutines">. + +=item Malformed PERLLIB_PREFIX + +(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form + + prefix1;prefix2 + +or + + prefix1 prefix2 + +with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix of +a builtin library search path, prefix2 is substituted. The error may +appear if components are not found, or are too long. See +"PERLLIB_PREFIX" in F<README.os2>. + +=item %s matches null string many times + +(W regexp) The pattern you've specified would be an infinite loop if the +regular expression engine didn't specifically check for that. See +L<perlre>. + +=item % may only be used in unpack + +(F) You can't pack a string by supplying a checksum, because the +checksumming process loses information, and you can't go the other way. +See L<perlfunc/unpack>. =item Method for operation %s not found in package %s during blessing @@ -1849,12 +1801,6 @@ ended earlier on the current line. (W syntax) An underline in a decimal constant wasn't on a 3-digit boundary. -=item Missing $ on loop variable - -(F) Apparently you've been programming in B<csh> too much. Variables are always -mentioned with the $ in Perl, unlike in the shells, where it can vary from -one line to the next. - =item Missing %sbrace%s on \N{} (F) Wrong syntax of character name literal C<\N{charname}> within @@ -1867,19 +1813,37 @@ double-quotish context. =item Missing command in piped open -(W pipe) You used the C<open(FH, "| command")> or C<open(FH, "command |")> -construction, but the command was missing or blank. +(W pipe) You used the C<open(FH, "| command")> or +C<open(FH, "command |")> construction, but the command was missing or +blank. -=item Missing operator before %s? +=item Missing name in "my sub" + +(F) The reserved syntax for lexically scoped subroutines requires that +they have a name with which they can be found. + +=item Missing $ on loop variable + +(F) Apparently you've been programming in B<csh> too much. Variables +are always mentioned with the $ in Perl, unlike in the shells, where it +can vary from one line to the next. + +=item (Missing operator before %s?) (S) This is an educated guess made in conjunction with the message "%s found where operator expected". Often the missing operator is a comma. =item Missing right curly or square bracket -(F) The lexer counted more opening curly or square brackets than -closing ones. As a general rule, you'll find it's missing near the place -you were last editing. +(F) The lexer counted more opening curly or square brackets than closing +ones. As a general rule, you'll find it's missing near the place you +were last editing. + +=item (Missing semicolon on previous line?) + +(S) This is an educated guess made in conjunction with the message "%s +found where operator expected". Don't automatically put a semicolon on +the previous line just because you saw this message. =item Modification of a read-only value attempted @@ -1892,76 +1856,100 @@ catches that. But an easy way to do the same thing is: Another way is to assign to a substr() that's off the end of the string. -=item Modification of non-creatable array value attempted, subscript %d +=item Modification of non-creatable array value attempted, %s (F) You tried to make an array value spring into existence, and the subscript was probably negative, even counting from end of the array backwards. -=item Modification of non-creatable hash value attempted, subscript "%s" +=item Modification of non-creatable hash value attempted, %s -(P) You tried to make a hash value spring into existence, and it couldn't -be created for some peculiar reason. +(P) You tried to make a hash value spring into existence, and it +couldn't be created for some peculiar reason. =item Module name must be constant (F) Only a bare module name is allowed as the first argument to a "use". +=item Module name required with -%c option + +(F) The C<-M> or C<-m> options say that Perl should load some module, but +you omitted the name of the module. Consult L<perlrun> for full details +about C<-M> and C<-m>. + =item msg%s not implemented (F) You don't have System V message IPC on your system. =item Multidimensional syntax %s not supported -(W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>. They're written -like C<$foo[1][2][3]>, as in C. +(W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>. +They're written like C<$foo[1][2][3]>, as in C. -=item Missing name in "my sub" +=item / must be followed by a*, A* or Z* + +(F) You had a pack template indicating a counted-length string, +Currently the only things that can have their length counted are a*, A* +or Z*. See L<perlfunc/pack>. + +=item / must be followed by a, A or Z + +(F) You had an unpack template indicating a counted-length string, which +must be followed by one of the letters a, A or Z to indicate what sort +of string is to be unpacked. See L<perlfunc/pack>. + +=item / must follow a numeric type + +(F) You had an unpack template that contained a '#', but this did not +follow some numeric unpack specification. See L<perlfunc/pack>. + +=item "my sub" not yet implemented -(F) The reserved syntax for lexically scoped subroutines requires that they -have a name with which they can be found. +(F) Lexically scoped subroutines are not yet implemented. Don't try +that yet. + +=item "my" variable %s can't be in a package + +(F) Lexically scoped variables aren't in a package, so it doesn't make +sense to try to declare one with a package qualifier on the front. Use +local() if you want to localize a package variable. =item Name "%s::%s" used only once: possible typo (W once) Typographical errors often show up as unique variable names. -If you had a good reason for having a unique name, then just mention -it again somehow to suppress the message. The C<our> declaration is +If you had a good reason for having a unique name, then just mention it +again somehow to suppress the message. The C<our> declaration is provided for this purpose. =item Negative length -(F) You tried to do a read/write/send/recv operation with a buffer length -that is less than 0. This is difficult to imagine. +(F) You tried to do a read/write/send/recv operation with a buffer +length that is less than 0. This is difficult to imagine. =item nested *?+ in regexp (F) You can't quantify a quantifier without intervening parentheses. So things like ** or +* or ?* are illegal. -Note, however, that the minimal matching quantifiers, C<*?>, C<+?>, and C<??> appear -to be nested quantifiers, but aren't. See L<perlre>. +Note, however, that the minimal matching quantifiers, C<*?>, C<+?>, and +C<??> appear to be nested quantifiers, but aren't. See L<perlre>. -=item No #! line +=item %s never introduced -(F) The setuid emulator requires that scripts have a well-formed #! line -even on machines that don't support the #! construct. +(S internal) The symbol in question was declared but somehow went out of +scope before it could possibly have been used. =item No %s allowed while running setuid -(F) Certain operations are deemed to be too insecure for a setuid or setgid -script to even be allowed to attempt. Generally speaking there will be -another way to do what you want that is, if not secure, at least securable. -See L<perlsec>. +(F) Certain operations are deemed to be too insecure for a setuid or +setgid script to even be allowed to attempt. Generally speaking there +will be another way to do what you want that is, if not secure, at least +securable. See L<perlsec>. =item No B<-e> allowed in setuid scripts (F) A setuid script can't be specified by the user. -=item No %s specified for -%c - -(F) The indicated command line switch needs a mandatory argument, but -you haven't specified one. - =item No comma allowed after %s (F) A list operator that has a filehandle or "indirect object" is not @@ -1982,18 +1970,17 @@ this error was triggered? =item No command into which to pipe on command line -(F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '|' at the end of the command line, so it doesn't know where you -want to pipe the output from this command. +(F) An error peculiar to VMS. Perl handles its own command line +redirection, and found a '|' at the end of the command line, so it +doesn't know where you want to pipe the output from this command. =item No DB::DB routine defined -(F) The currently executing code was compiled with the B<-d> switch, -but for some reason the perl5db.pl file (or some facsimile thereof) -didn't define a routine to be called at the beginning of each -statement. Which is odd, because the file should have been required -automatically, and should have blown up the require if it didn't parse -right. +(F) The currently executing code was compiled with the B<-d> switch, but +for some reason the perl5db.pl file (or some facsimile thereof) didn't +define a routine to be called at the beginning of each statement. Which +is odd, because the file should have been required automatically, and +should have blown up the require if it didn't parse right. =item No dbm on this machine @@ -2009,33 +1996,43 @@ ordinary subroutine call. =item No error file after 2> or 2>> on command line -(F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '2>' or a '2>>' on the command line, but can't find -the name of the file to which to write data destined for stderr. +(F) An error peculiar to VMS. Perl handles its own command line +redirection, and found a '2>' or a '2>>' on the command line, but can't +find the name of the file to which to write data destined for stderr. =item No input file after < on command line -(F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '<' on the command line, but can't find the name of the file -from which to read data for stdin. +(F) An error peculiar to VMS. Perl handles its own command line +redirection, and found a '<' on the command line, but can't find the +name of the file from which to read data for stdin. + +=item No #! line + +(F) The setuid emulator requires that scripts have a well-formed #! line +even on machines that don't support the #! construct. + +=item "no" not allowed in expression + +(F) The "no" keyword is recognized and executed at compile time, and +returns no useful value. See L<perlmod>. =item No output file after > on command line -(F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a lone '>' at the end of the command line, so it doesn't know -where you wanted to redirect stdout. +(F) An error peculiar to VMS. Perl handles its own command line +redirection, and found a lone '>' at the end of the command line, so it +doesn't know where you wanted to redirect stdout. =item No output file after > or >> on command line -(F) An error peculiar to VMS. Perl handles its own command line redirection, -and found a '>' or a '>>' on the command line, but can't find the -name of the file to which to write data destined for stdout. +(F) An error peculiar to VMS. Perl handles its own command line +redirection, and found a '>' or a '>>' on the command line, but can't +find the name of the file to which to write data destined for stdout. =item No package name allowed for variable %s in "our" -(F) Fully qualified variable names are not allowed in "our" declarations, -because that doesn't make much sense under existing semantics. Such -syntax is reserved for future extensions. +(F) Fully qualified variable names are not allowed in "our" +declarations, because that doesn't make much sense under existing +semantics. Such syntax is reserved for future extensions. =item No Perl script found in input @@ -2054,8 +2051,19 @@ your system. =item No space allowed after -%c -(F) The argument to the indicated command line switch must follow immediately -after the switch, without intervening spaces. +(F) The argument to the indicated command line switch must follow +immediately after the switch, without intervening spaces. + +=item No %s specified for -%c + +(F) The indicated command line switch needs a mandatory argument, but +you haven't specified one. + +=item No such pipe open + +(P) An error peculiar to VMS. The internal routine my_pclose() tried to +close a pipe which hadn't been opened. This should have been caught +earlier as an attempt to close an unopened filehandle. =item No such pseudo-hash field "%s" @@ -2065,36 +2073,23 @@ array indices for that to work. =item No such pseudo-hash field "%s" in variable %s of type %s -(F) You tried to access a field of a typed variable where the type -does not know about the field name. The field names are looked up in -the %FIELDS hash in the type package at compile time. The %FIELDS hash -is usually set up with the 'fields' pragma. - -=item No such pipe open - -(P) An error peculiar to VMS. The internal routine my_pclose() tried to -close a pipe which hadn't been opened. This should have been caught earlier as -an attempt to close an unopened filehandle. +(F) You tried to access a field of a typed variable where the type does +not know about the field name. The field names are looked up in the +%FIELDS hash in the type package at compile time. The %FIELDS hash is +%usually set up with the 'fields' pragma. =item No such signal: SIG%s -(W signal) You specified a signal name as a subscript to %SIG that was not recognized. -Say C<kill -l> in your shell to see the valid signal names on your system. - -=item no UTC offset information; assuming local time is UTC - -(S) A warning peculiar to VMS. Perl was unable to find the local -timezone offset, so it's assuming that local system time is equivalent -to UTC. If it's not, define the logical name F<SYS$TIMEZONE_DIFFERENTIAL> -to translate to the number of seconds which need to be added to UTC to -get local time. +(W signal) You specified a signal name as a subscript to %SIG that was +not recognized. Say C<kill -l> in your shell to see the valid signal +names on your system. =item Not a CODE reference (F) Perl was trying to evaluate a reference to a code value (that is, a subroutine), but found a reference to something else instead. You can -use the ref() function to find out what kind of ref it really was. -See also L<perlref>. +use the ref() function to find out what kind of ref it really was. See +also L<perlref>. =item Not a format reference @@ -2103,16 +2098,22 @@ format, but this indicates you did, and that it didn't exist. =item Not a GLOB reference -(F) Perl was trying to evaluate a reference to a "typeglob" (that is, -a symbol table entry that looks like C<*foo>), but found a reference to -something else instead. You can use the ref() function to find out -what kind of ref it really was. See L<perlref>. +(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a +symbol table entry that looks like C<*foo>), but found a reference to +something else instead. You can use the ref() function to find out what +kind of ref it really was. See L<perlref>. =item Not a HASH reference -(F) Perl was trying to evaluate a reference to a hash value, but -found a reference to something else instead. You can use the ref() -function to find out what kind of ref it really was. See L<perlref>. +(F) Perl was trying to evaluate a reference to a hash value, but found a +reference to something else instead. You can use the ref() function to +find out what kind of ref it really was. See L<perlref>. + +=item Not an ARRAY reference + +(F) Perl was trying to evaluate a reference to an array value, but found +a reference to something else instead. You can use the ref() function +to find out what kind of ref it really was. See L<perlref>. =item Not a perl script @@ -2122,41 +2123,54 @@ mention perl. =item Not a SCALAR reference -(F) Perl was trying to evaluate a reference to a scalar value, but -found a reference to something else instead. You can use the ref() -function to find out what kind of ref it really was. See L<perlref>. +(F) Perl was trying to evaluate a reference to a scalar value, but found +a reference to something else instead. You can use the ref() function +to find out what kind of ref it really was. See L<perlref>. =item Not a subroutine reference (F) Perl was trying to evaluate a reference to a code value (that is, a subroutine), but found a reference to something else instead. You can -use the ref() function to find out what kind of ref it really was. -See also L<perlref>. +use the ref() function to find out what kind of ref it really was. See +also L<perlref>. =item Not a subroutine reference in overload table (F) An attempt was made to specify an entry in an overloading table that doesn't somehow point to a valid subroutine. See L<overload>. -=item Not an ARRAY reference - -(F) Perl was trying to evaluate a reference to an array value, but -found a reference to something else instead. You can use the ref() -function to find out what kind of ref it really was. See L<perlref>. - =item Not enough arguments for %s (F) The function requires more arguments than you specified. =item Not enough format arguments -(W syntax) A format specified more picture fields than the next line supplied. -See L<perlform>. +(W syntax) A format specified more picture fields than the next line +supplied. See L<perlform>. + +=item %s: not found + +(A) You've accidentally run your script through the Bourne shell instead +of Perl. Check the #! line, or manually feed your script into Perl +yourself. + +=item no UTC offset information; assuming local time is UTC + +(S) A warning peculiar to VMS. Perl was unable to find the local +timezone offset, so it's assuming that local system time is equivalent +to UTC. If it's not, define the logical name +F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which +need to be added to UTC to get local time. =item Null filename used -(F) You can't require the null filename, especially because on many machines -that means the current directory! See L<perlfunc/require>. +(F) You can't require the null filename, especially because on many +machines that means the current directory! See L<perlfunc/require>. + +=item NULL OP IN RUN + +(P debugging) Some internal routine called run() with a null opcode +pointer. =item Null picture in formline @@ -2164,10 +2178,6 @@ that means the current directory! See L<perlfunc/require>. specification. It was found to be empty, which probably means you supplied it an uninitialized value. See L<perlform>. -=item NULL OP IN RUN - -(P debugging) Some internal routine called run() with a null opcode pointer. - =item Null realloc (P) An attempt was made to realloc NULL. @@ -2182,36 +2192,37 @@ supplied it an uninitialized value. See L<perlform>. =item Number too long -(F) Perl limits the representation of decimal numbers in programs to about -about 250 characters. You've exceeded that length. Future versions of -Perl are likely to eliminate this arbitrary limitation. In the meantime, -try using scientific notation (e.g. "1e6" instead of "1_000_000"). +(F) Perl limits the representation of decimal numbers in programs to +about about 250 characters. You've exceeded that length. Future +versions of Perl are likely to eliminate this arbitrary limitation. In +the meantime, try using scientific notation (e.g. "1e6" instead of +"1_000_000"). -=item Octal number > 037777777777 non-portable +=item Octal number in vector unsupported -(W portable) The octal number you specified is larger than 2**32-1 (4294967295) -and therefore non-portable between systems. See L<perlport> for more -on portability concerns. +(F) Numbers with a leading C<0> are not currently allowed in vectors. +The octal number interpretation of such numbers may be supported in a +future version. -See also L<perlport> for writing portable code. +=item Octal number > 037777777777 non-portable -=item Octal number in vector unsupported +(W portable) The octal number you specified is larger than 2**32-1 +(4294967295) and therefore non-portable between systems. See +L<perlport> for more on portability concerns. -(F) Numbers with a leading C<0> are not currently allowed in vectors. The -octal number interpretation of such numbers may be supported in a future -version. +See also L<perlport> for writing portable code. =item Odd number of elements in hash assignment -(W misc) You specified an odd number of elements to initialize a hash, which -is odd, because hashes come in key/value pairs. +(W misc) You specified an odd number of elements to initialize a hash, +which is odd, because hashes come in key/value pairs. =item Offset outside string (F) You tried to do a read/write/send/recv operation with an offset -pointing outside the buffer. This is difficult to imagine. -The sole exception to this is that C<sysread()>ing past the buffer -will extend the buffer and zero pad the new area. +pointing outside the buffer. This is difficult to imagine. The sole +exception to this is that C<sysread()>ing past the buffer will extend +the buffer and zero pad the new area. =item oops: oopsAV @@ -2223,59 +2234,81 @@ will extend the buffer and zero pad the new area. =item Operation `%s': no method found, %s -(F) An attempt was made to perform an overloaded operation for which -no handler was defined. While some handlers can be autogenerated in -terms of other handlers, there is no default handler for any -operation, unless C<fallback> overloading key is specified to be -true. See L<overload>. +(F) An attempt was made to perform an overloaded operation for which no +handler was defined. While some handlers can be autogenerated in terms +of other handlers, there is no default handler for any operation, unless +C<fallback> overloading key is specified to be true. See L<overload>. =item Operator or semicolon missing before %s -(S ambiguous) You used a variable or subroutine call where the parser was -expecting an operator. The parser has assumed you really meant -to use an operator, but this is highly likely to be incorrect. -For example, if you say "*foo *foo" it will be interpreted as -if you said "*foo * 'foo'". +(S ambiguous) You used a variable or subroutine call where the parser +was expecting an operator. The parser has assumed you really meant to +use an operator, but this is highly likely to be incorrect. For +example, if you say "*foo *foo" it will be interpreted as if you said +"*foo * 'foo'". + +=item "our" variable %s redeclared + +(W misc) You seem to have already declared the same global once before +in the current lexical scope. =item Out of memory! (X) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. Perl -has no option but to exit immediately. +remaining memory (or virtual memory) to satisfy the request. Perl has +no option but to exit immediately. -=item Out of memory for yacc stack +=item Out of memory during "large" request for %s -(F) The yacc parser wanted to grow its stack so it could continue parsing, -but realloc() wouldn't give it more memory, virtual or otherwise. +(F) The malloc() function returned 0, indicating there was insufficient +remaining memory (or virtual memory) to satisfy the request. However, +the request was judged large enough (compile-time default is 64K), so a +possibility to shut down by trapping this error is granted. =item Out of memory during request for %s -(X|F) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. +(X|F) The malloc() function returned 0, indicating there was +insufficient remaining memory (or virtual memory) to satisfy the +request. The request was judged to be small, so the possibility to trap it depends on the way perl was compiled. By default it is not trappable. -However, if compiled for this, Perl may use the contents of C<$^M> as -an emergency pool after die()ing with this message. In this case the -error is trappable I<once>. - -=item Out of memory during "large" request for %s - -(F) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. However, -the request was judged large enough (compile-time default is 64K), so -a possibility to shut down by trapping this error is granted. +However, if compiled for this, Perl may use the contents of C<$^M> as an +emergency pool after die()ing with this message. In this case the error +is trappable I<once>. =item Out of memory during ridiculously large request (F) You can't allocate more than 2^31+"small amount" bytes. This error -is most likely to be caused by a typo in the Perl program. e.g., C<$arr[time]> -instead of C<$arr[$time]>. +is most likely to be caused by a typo in the Perl program. e.g., +C<$arr[time]> instead of C<$arr[$time]>. + +=item Out of memory for yacc stack + +(F) The yacc parser wanted to grow its stack so it could continue +parsing, but realloc() wouldn't give it more memory, virtual or +otherwise. + +=item @ outside of string + +(F) You had a pack template that specified an absolute position outside +the string being unpacked. See L<perlfunc/pack>. + +=item %s package attribute may clash with future reserved word: %s + +(W reserved) A lowercase attribute name was used that had a +package-specific handler. That name might have a meaning to Perl itself +some day, even though it doesn't yet. Perhaps you should use a +mixed-case attribute name, instead. See L<attributes>. =item page overflow -(W io) A single call to write() produced more lines than can fit on a page. -See L<perlform>. +(W io) A single call to write() produced more lines than can fit on a +page. See L<perlform>. + +=item panic: %s + +(P) An internal error. =item panic: ck_grep @@ -2287,8 +2320,8 @@ See L<perlform>. =item panic: corrupt saved stack index -(P) The savestack was requested to restore more localized values than there -are in the savestack. +(P) The savestack was requested to restore more localized values than +there are in the savestack. =item panic: del_backref @@ -2302,7 +2335,8 @@ it wasn't an eval context. =item panic: do_match -(P) The internal pp_match() routine was called with invalid operational data. +(P) The internal pp_match() routine was called with invalid operational +data. =item panic: do_split @@ -2310,11 +2344,13 @@ it wasn't an eval context. =item panic: do_subst -(P) The internal pp_subst() routine was called with invalid operational data. +(P) The internal pp_subst() routine was called with invalid operational +data. =item panic: do_trans -(P) The internal do_trans() routine was called with invalid operational data. +(P) The internal do_trans() routine was called with invalid operational +data. =item panic: frexp @@ -2344,22 +2380,23 @@ it wasn't a block context. =item panic: leave_scope clearsv -(P) A writable lexical variable became read-only somehow within the scope. +(P) A writable lexical variable became read-only somehow within the +scope. =item panic: leave_scope inconsistency (P) The savestack probably got out of sync. At least, there was an invalid enum on the top of it. -=item panic: malloc - -(P) Something requested a negative number of bytes of malloc. - =item panic: magic_killbackrefs (P) Failed an internal consistency check while trying to reset all weak references to an object. +=item panic: malloc + +(P) Something requested a negative number of bytes of malloc. + =item panic: mapstart (P) The compiler is screwed up with respect to the map() function. @@ -2435,10 +2472,6 @@ was string. (P) The lexer got into a bad state while processing a case modifier. -=item panic: %s - -(P) An internal error. - =item Parentheses missing around "%s" list (W parenthesis) You said something like @@ -2451,11 +2484,37 @@ when you meant Remember that "my", "our", and "local" bind tighter than comma. -=item Perl %3.3f required--this is only version %s, stopped +=item Perl %s required--this is only version %s, stopped + +(F) The module in question uses features of a version of Perl more +recent than the currently running version. How long has it been since +you upgraded, anyway? See L<perlfunc/require>. + +=item PERL_SH_DIR too long + +(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the +C<sh>-shell in. See "PERL_SH_DIR" in F<README.os2>. + +=item perl: warning: Setting locale failed. + +(S) The whole warning message will look something like: + + perl: warning: Setting locale failed. + perl: warning: Please check that your locale settings: + LC_ALL = "En_US", + LANG = (unset) + are supported and installed on your system. + perl: warning: Falling back to the standard locale ("C"). -(F) The module in question uses features of a version of Perl more recent -than the currently running version. How long has it been since you upgraded, -anyway? See L<perlfunc/require>. +Exactly what were the failed locale settings varies. In the above the +settings were that the LC_ALL was "En_US" and the LANG had no value. +This error means that Perl detected that you and/or your system +administrator have set up the so-called variable system but Perl could +not use those settings. This was not dead serious, fortunately: there +is a "default locale" called "C" that Perl can and will use, the script +will be run. Before you really fix the problem, however, you will get +the same error message each time you run Perl. How to really fix the +problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. =item Permission denied @@ -2463,25 +2522,20 @@ anyway? See L<perlfunc/require>. =item pid %x not a child -(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a process which -isn't a subprocess of the current process. While this is fine from VMS' -perspective, it's probably not what you intended. +(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a +process which isn't a subprocess of the current process. While this is +fine from VMS' perspective, it's probably not what you intended. =item POSIX getpgrp can't take an argument (F) Your system has POSIX getpgrp(), which takes no argument, unlike the BSD version, which takes a pid. -=item Possible Y2K bug: %s - -(W y2k) You are concatenating the number 19 with another number, which -could be a potential Year 2000 problem. - =item Possible attempt to put comments in qw() list (W qw) qw() lists contain items separated by whitespace; as with literal -strings, comment characters are not ignored, but are instead treated -as literal data. (You may have used different delimiters than the +strings, comment characters are not ignored, but are instead treated as +literal data. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.) You probably wrote something like this: @@ -2508,10 +2562,10 @@ old-fashioned way, with quotes and commas: =item Possible attempt to separate words with commas -(W qw) qw() lists contain items separated by whitespace; therefore commas -aren't needed to separate the items. (You may have used different -delimiters than the parentheses shown here; braces are also frequently -used.) +(W qw) qw() lists contain items separated by whitespace; therefore +commas aren't needed to separate the items. (You may have used +different delimiters than the parentheses shown here; braces are also +frequently used.) You probably wrote something like this: @@ -2529,6 +2583,29 @@ Perl guesses a reasonable buffer size, but puts a sentinel byte at the end of the buffer just in case. This sentinel byte got clobbered, and Perl assumes that memory is now corrupted. See L<perlfunc/ioctl>. +=item Possible Y2K bug: %s + +(W y2k) You are concatenating the number 19 with another number, which +could be a potential Year 2000 problem. + +=item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead + +(W deprecated) You have written something like this: + + sub doit + { + use attrs qw(locked); + } + +You should use the new declaration syntax instead. + + sub doit : locked + { + ... + +The C<use attrs> pragma is now obsolete, and is only provided for +backward-compatibility. See L<perlsub/"Subroutine Attributes">. + =item Precedence problem: open %s should be open(%s) (S precedence) The old irregular construct @@ -2539,55 +2616,63 @@ is now misinterpreted as open(FOO || die); -because of the strict regularization of Perl 5's grammar into unary -and list operators. (The old open was a little of both.) You must -put parentheses around the filehandle, or use the new "or" operator -instead of "||". +because of the strict regularization of Perl 5's grammar into unary and +list operators. (The old open was a little of both.) You must put +parentheses around the filehandle, or use the new "or" operator instead +of "||". =item Premature end of script headers See Server error. +=item printf() on closed filehandle %s + +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. + =item print() on closed filehandle %s -(W closed) The filehandle you're printing on got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're printing on got itself closed sometime +before now. Check your logic flow. -=item printf() on closed filehandle %s +=item Process terminated by SIG%s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(W) This is a standard message issued by OS/2 applications, while *nix +applications die in silence. It is considered a feature of the OS/2 +port. One can easily disable this by appropriate sighandlers, see +L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT" +in F<README.os2>. =item Prototype mismatch: %s vs %s -(S unsafe) The subroutine being declared or defined had previously been declared -or defined with a different function prototype. +(S unsafe) The subroutine being declared or defined had previously been +declared or defined with a different function prototype. =item Range iterator outside integer range (F) One (or both) of the numeric arguments to the range operator ".." are outside the range which can be represented by integers internally. -One possible workaround is to force Perl to use magical string -increment by prepending "0" to your numbers. +One possible workaround is to force Perl to use magical string increment +by prepending "0" to your numbers. =item readline() on closed filehandle %s -(W closed) The filehandle you're reading from got itself closed sometime before now. -Check your logic flow. - -=item realloc() of freed memory ignored - -(S malloc) An internal routine called realloc() on something that had already -been freed. +(W closed) The filehandle you're reading from got itself closed sometime +before now. Check your logic flow. =item Reallocation too large: %lx (F) You can't allocate more than 64K on an MS-DOS machine. +=item realloc() of freed memory ignored + +(S malloc) An internal routine called realloc() on something that had +already been freed. + =item Recompile perl with B<-D>DEBUGGING to use B<-D> switch -(F debugging) You can't use the B<-D> option unless the code to produce the -desired output is compiled into Perl, which entails some overhead, +(F debugging) You can't use the B<-D> option unless the code to produce +the desired output is compiled into Perl, which entails some overhead, which is why it's currently left out of your copy. =item Recursive inheritance detected in package '%s' @@ -2595,17 +2680,18 @@ which is why it's currently left out of your copy. (F) More than 100 levels of inheritance were used. Probably indicates an unintended loop in your inheritance hierarchy. -=item Recursive inheritance detected while looking for method '%s' in package '%s' +=item Recursive inheritance detected while looking for method %s -(F) More than 100 levels of inheritance were encountered while invoking a -method. Probably indicates an unintended loop in your inheritance hierarchy. +(F) More than 100 levels of inheritance were encountered while invoking +a method. Probably indicates an unintended loop in your inheritance +hierarchy. =item Reference found where even-sized list expected -(W misc) You gave a single reference where Perl was expecting a list with -an even number of elements (for assignment to a hash). This -usually means that you used the anon hash constructor when you meant -to use parens. In any case, a hash requires key/value B<pairs>. +(W misc) You gave a single reference where Perl was expecting a list +with an even number of elements (for assignment to a hash). This usually +means that you used the anon hash constructor when you meant to use +parens. In any case, a hash requires key/value B<pairs>. %hash = { one => 1, two => 2, }; # WRONG %hash = [ qw/ an anon array / ]; # WRONG @@ -2619,27 +2705,38 @@ Doing so has no effect. =item Reference miscount in sv_replace() -(W internal) The internal sv_replace() function was handed a new SV with a -reference count of other than 1. - -=item regexp *+ operand could be empty - -(F) The part of the regexp subject to either the * or + quantifier -could match an empty string. +(W internal) The internal sv_replace() function was handed a new SV with +a reference count of other than 1. =item regexp memory corruption (P) The regular expression engine got confused by what the regular expression compiler gave it. +=item regexp *+ operand could be empty + +(F) The part of the regexp subject to either the * or + quantifier could +match an empty string. + =item regexp out of space -(P) A "can't happen" error, because safemalloc() should have caught it earlier. +(P) A "can't happen" error, because safemalloc() should have caught it +earlier. + +=item Repeat count in pack overflows + +(F) You can't specify a repeat count so large that it overflows your +signed integers. See L<perlfunc/pack>. + +=item Repeat count in unpack overflows + +(F) You can't specify a repeat count so large that it overflows your +signed integers. See L<perlfunc/unpack>. =item Reversed %s= operator -(W syntax) You wrote your assignment operator backwards. The = must always -comes last, to avoid ambiguity with subsequent unary operators. +(W syntax) You wrote your assignment operator backwards. The = must +always comes last, to avoid ambiguity with subsequent unary operators. =item Runaway format @@ -2651,12 +2748,13 @@ shifting or popping (for array variables). See L<perlform>. =item Scalar value @%s[%s] better written as $%s[%s] -(W syntax) You've used an array slice (indicated by @) to select a single element of -an array. Generally it's better to ask for a scalar value (indicated by $). -The difference is that C<$foo[&bar]> always behaves like a scalar, both when -assigning to it and when evaluating its argument, while C<@foo[&bar]> behaves -like a list when you assign to it, and provides a list context to its -subscript, which can do weird things if you're expecting only one subscript. +(W syntax) You've used an array slice (indicated by @) to select a +single element of an array. Generally it's better to ask for a scalar +value (indicated by $). The difference is that C<$foo[&bar]> always +behaves like a scalar, both when assigning to it and when evaluating its +argument, while C<@foo[&bar]> behaves like a list when you assign to it, +and provides a list context to its subscript, which can do weird things +if you're expecting only one subscript. On the other hand, if you were actually hoping to treat the array element as a list, you need to look into how references work, because @@ -2665,16 +2763,17 @@ L<perlref>. =item Scalar value @%s{%s} better written as $%s{%s} -(W syntax) You've used a hash slice (indicated by @) to select a single element of -a hash. Generally it's better to ask for a scalar value (indicated by $). -The difference is that C<$foo{&bar}> always behaves like a scalar, both when -assigning to it and when evaluating its argument, while C<@foo{&bar}> behaves -like a list when you assign to it, and provides a list context to its -subscript, which can do weird things if you're expecting only one subscript. - -On the other hand, if you were actually hoping to treat the hash -element as a list, you need to look into how references work, because -Perl will not magically convert between scalars and lists for you. See +(W syntax) You've used a hash slice (indicated by @) to select a single +element of a hash. Generally it's better to ask for a scalar value +(indicated by $). The difference is that C<$foo{&bar}> always behaves +like a scalar, both when assigning to it and when evaluating its +argument, while C<@foo{&bar}> behaves like a list when you assign to it, +and provides a list context to its subscript, which can do weird things +if you're expecting only one subscript. + +On the other hand, if you were actually hoping to treat the hash element +as a list, you need to look into how references work, because Perl will +not magically convert between scalars and lists for you. See L<perlref>. =item Script is not setuid/setgid in suidperl @@ -2690,41 +2789,36 @@ Missing the leading C<$> from a variable C<$m> may cause this error. =item %sseek() on unopened file -(W unopened) You tried to use the seek() or sysseek() function on a filehandle that -was either never opened or has since been closed. +(W unopened) You tried to use the seek() or sysseek() function on a +filehandle that was either never opened or has since been closed. =item select not implemented (F) This machine doesn't implement the select() system call. -=item sem%s not implemented +=item Semicolon seems to be missing -(F) You don't have System V semaphore IPC on your system. +(W semicolon) A nearby syntax error was probably caused by a missing +semicolon, or possibly some other missing operator, such as a comma. =item semi-panic: attempt to dup freed string -(S internal) The internal newSVsv() routine was called to duplicate a scalar -that had previously been marked as free. +(S internal) The internal newSVsv() routine was called to duplicate a +scalar that had previously been marked as free. -=item Semicolon seems to be missing +=item sem%s not implemented -(W semicolon) A nearby syntax error was probably caused by a missing semicolon, -or possibly some other missing operator, such as a comma. +(F) You don't have System V semaphore IPC on your system. =item send() on closed socket %s -(W closed) The socket you're sending to got itself closed sometime before now. -Check your logic flow. +(W closed) The socket you're sending to got itself closed sometime +before now. Check your logic flow. =item Sequence (? incomplete -(F) A regular expression ended with an incomplete extension (?. -See L<perlre>. - -=item Sequence (?#... not terminated - -(F) A regular expression comment must be terminated by a closing -parenthesis. Embedded parentheses aren't allowed. See L<perlre>. +(F) A regular expression ended with an incomplete extension (?. See +L<perlre>. =item Sequence (?%s...) not implemented @@ -2736,23 +2830,32 @@ but has not yet been written. See L<perlre>. (F) You used a regular expression extension that doesn't make sense. See L<perlre>. +=item Sequence (?#... not terminated + +(F) A regular expression comment must be terminated by a closing +parenthesis. Embedded parentheses aren't allowed. See L<perlre>. + +=item 500 Server error + +See Server error. + =item Server error This is the error message generally seen in a browser window when trying -to run a CGI program (including SSI) over the web. The actual error -text varies widely from server to server. The most frequently-seen -variants are "500 Server error", "Method (something) not permitted", -"Document contains no data", "Premature end of script headers", and -"Did not produce a valid header". +to run a CGI program (including SSI) over the web. The actual error text +varies widely from server to server. The most frequently-seen variants +are "500 Server error", "Method (something) not permitted", "Document +contains no data", "Premature end of script headers", and "Did not +produce a valid header". B<This is a CGI error, not a Perl error>. -You need to make sure your script is executable, is accessible by the user -CGI is running the script under (which is probably not the user account you -tested it under), does not rely on any environment variables (like PATH) -from the user it isn't running under, and isn't in a location where the CGI -server can't find it, basically, more or less. Please see the following -for more information: +You need to make sure your script is executable, is accessible by the +user CGI is running the script under (which is probably not the user +account you tested it under), does not rely on any environment variables +(like PATH) from the user it isn't running under, and isn't in a +location where the CGI server can't find it, basically, more or less. +Please see the following for more information: http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html @@ -2764,50 +2867,70 @@ You should also look at L<perlfaq9>. =item setegid() not implemented -(F) You tried to assign to C<$)>, and your operating system doesn't support -the setegid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$)>, and your operating system doesn't +support the setegid() system call (or equivalent), or at least Configure +didn't think so. =item seteuid() not implemented -(F) You tried to assign to C<< $> >>, and your operating system doesn't support -the seteuid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<< $> >>, and your operating system doesn't +support the seteuid() system call (or equivalent), or at least Configure +didn't think so. =item setpgrp can't take arguments -(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments, -unlike POSIX setpgid(), which takes a process ID and process group ID. +(F) Your system has the setpgrp() from BSD 4.2, which takes no +arguments, unlike POSIX setpgid(), which takes a process ID and process +group ID. =item setrgid() not implemented -(F) You tried to assign to C<$(>, and your operating system doesn't support -the setrgid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$(>, and your operating system doesn't +support the setrgid() system call (or equivalent), or at least Configure +didn't think so. =item setruid() not implemented -(F) You tried to assign to C<$<>, and your operating system doesn't support -the setruid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$<>, and your operating system doesn't +support the setruid() system call (or equivalent), or at least Configure +didn't think so. + +=item setsockopt() on closed socket %s + +(W closed) You tried to set a socket option on a closed socket. Did you +forget to check the return value of your socket() call? See +L<perlfunc/setsockopt>. =item Setuid/gid script is writable by world -(F) The setuid emulator won't run a script that is writable by the world, -because the world might have written on it already. +(F) The setuid emulator won't run a script that is writable by the +world, because the world might have written on it already. =item shm%s not implemented (F) You don't have System V shared memory IPC on your system. +=item <> should be quotes + +(F) You wrote C<< require <file> >> when you should have written +C<require 'file'>. + +=item /%s/ should probably be written as "%s" + +(W syntax) You have used a pattern where Perl expected to find a string, +as in the first argument to C<join>. Perl will treat the true or false +result of matching the pattern against $_ as the string, which is +probably not what you had in mind. + =item shutdown() on closed socket %s -(W closed) You tried to do a shutdown on a closed socket. Seems a bit superfluous. +(W closed) You tried to do a shutdown on a closed socket. Seems a bit +superfluous. =item SIG%s handler "%s" not defined -(W signal) The signal handler named in %SIG doesn't, in fact, exist. Perhaps you -put it into the wrong package? +(W signal) The signal handler named in %SIG doesn't, in fact, exist. +Perhaps you put it into the wrong package? =item sort is now a reserved word @@ -2827,36 +2950,37 @@ or less than one element. See L<perlfunc/sort>. =item Split loop -(P) The split was looping infinitely. (Obviously, a split shouldn't iterate -more times than there are characters of input, which is what happened.) -See L<perlfunc/split>. +(P) The split was looping infinitely. (Obviously, a split shouldn't +iterate more times than there are characters of input, which is what +happened.) See L<perlfunc/split>. -=item Stat on unopened file <%s> +=item Statement unlikely to be reached -(W unopened) You tried to use the stat() function (or an equivalent file test) -on a filehandle that was either never opened or has since been closed. +(W exec) You did an exec() with some statement after it other than a +die(). This is almost always an error, because exec() never returns +unless there was a failure. You probably wanted to use system() +instead, which does return. To suppress this warning, put the exec() in +a block by itself. -=item Statement unlikely to be reached +=item Stat on unopened file <%s> -(W exec) You did an exec() with some statement after it other than a die(). -This is almost always an error, because exec() never returns unless -there was a failure. You probably wanted to use system() instead, -which does return. To suppress this warning, put the exec() in a block -by itself. +(W unopened) You tried to use the stat() function (or an equivalent file +test) on a filehandle that was either never opened or has since been +closed. =item Strange *+?{} on zero-length expression -(W regexp) You applied a regular expression quantifier in a place where it -makes no sense, such as on a zero-width assertion. -Try putting the quantifier inside the assertion instead. For example, -the way to match "abc" provided that it is followed by three -repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. +(W regexp) You applied a regular expression quantifier in a place where +it makes no sense, such as on a zero-width assertion. Try putting the +quantifier inside the assertion instead. For example, the way to match +"abc" provided that it is followed by three repetitions of "xyz" is +C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. -=item Stub found while resolving method `%s' overloading `%s' in package `%s' +=item Stub found while resolving method `%s' overloading %s -(P) Overloading resolution over @ISA tree may be broken by importation stubs. -Stubs should never be implicitely created, but explicit calls to C<can> -may break this. +(P) Overloading resolution over @ISA tree may be broken by importation +stubs. Stubs should never be implicitly created, but explicit calls to +C<can> may break this. =item Subroutine %s redefined @@ -2869,9 +2993,9 @@ may break this. =item Substitution loop -(P) The substitution was looping infinitely. (Obviously, a -substitution shouldn't iterate more times than there are characters of -input, which is what happened.) See the discussion of substitution in +(P) The substitution was looping infinitely. (Obviously, a substitution +shouldn't iterate more times than there are characters of input, which +is what happened.) See the discussion of substitution in L<perlop/"Quote and Quote-like Operators">. =item Substitution pattern not terminated @@ -2888,21 +3012,21 @@ Missing the leading C<$> from variable C<$s> may cause this error. =item substr outside of string -(W substr),(F) You tried to reference a substr() that pointed outside of a -string. That is, the absolute value of the offset was larger than the -length of the string. See L<perlfunc/substr>. This warning is -fatal if substr is used in an lvalue context (as the left hand side -of an assignment or as a subroutine argument for example). +(W substr),(F) You tried to reference a substr() that pointed outside of +a string. That is, the absolute value of the offset was larger than the +length of the string. See L<perlfunc/substr>. This warning is fatal if +substr is used in an lvalue context (as the left hand side of an +assignment or as a subroutine argument for example). =item suidperl is no longer needed since %s -(F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but a -version of the setuid emulator somehow got run anyway. +(F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but +a version of the setuid emulator somehow got run anyway. =item switching effective %s is not implemented -(F) While under the C<use filetest> pragma, we cannot switch the -real and effective uids or gids. +(F) While under the C<use filetest> pragma, we cannot switch the real +and effective uids or gids. =item syntax error @@ -2923,13 +3047,18 @@ before this, because Perl is good at understanding random input. Occasionally the line number may be misleading, and once in a blue moon the only way to figure out what's triggering the error is to call C<perl -c> repeatedly, chopping away half the program each time to see -if the error went away. Sort of the cybernetic version of S<20 questions>. +if the error went away. Sort of the cybernetic version of S<20 +questions>. =item syntax error at line %d: `%s' unexpected -(A) You've accidentally run your script through the Bourne shell -instead of Perl. Check the #! line, or manually feed your script -into Perl yourself. +(A) You've accidentally run your script through the Bourne shell instead +of Perl. Check the #! line, or manually feed your script into Perl +yourself. + +=item %s syntax OK + +(F) The final summary message when a C<perl -c> succeeds. =item System V %s is not implemented on this machine @@ -2940,28 +3069,28 @@ unconfigured. Consult your system support. =item syswrite() on closed filehandle %s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. =item Target of goto is too deeply nested -(F) You tried to use C<goto> to reach a label that was too deeply -nested for Perl to reach. Perl is doing you a favor by refusing. +(F) You tried to use C<goto> to reach a label that was too deeply nested +for Perl to reach. Perl is doing you a favor by refusing. =item tell() on unopened file -(W unopened) You tried to use the tell() function on a filehandle that was either -never opened or has since been closed. +(W unopened) You tried to use the tell() function on a filehandle that +was either never opened or has since been closed. =item Test on unopened file <%s> -(W unopened) You tried to invoke a file test operator on a filehandle that isn't -open. Check your logic. See also L<perlfunc/-X>. +(W unopened) You tried to invoke a file test operator on a filehandle +that isn't open. Check your logic. See also L<perlfunc/-X>. =item That use of $[ is unsupported -(F) Assignment to C<$[> is now strictly circumscribed, and interpreted as -a compiler directive. You may say only one of +(F) Assignment to C<$[> is now strictly circumscribed, and interpreted +as a compiler directive. You may say only one of $[ = 0; $[ = 1; @@ -2970,13 +3099,8 @@ a compiler directive. You may say only one of local $[ = 1; ... -This is to prevent the problem of one module changing the array base -out from under another module inadvertently. See L<perlvar/$[>. - -=item The %s function is unimplemented - -The function indicated isn't implemented on this architecture, according -to the probings of Configure. +This is to prevent the problem of one module changing the array base out +from under another module inadvertently. See L<perlvar/$[>. =item The crypt() function is unimplemented due to excessive paranoia @@ -2986,27 +3110,34 @@ think the U.S. Government thinks it's a secret, or at least that they will continue to pretend that it is. And if you quote me on that, I will deny it. +=item The %s function is unimplemented + +The function indicated isn't implemented on this architecture, according +to the probings of Configure. + =item The stat preceding C<-l _> wasn't an lstat -(F) It makes no sense to test the current stat buffer for symbolic linkhood -if the last stat that wrote to the stat buffer already went past -the symlink to get to the real file. Use an actual filename instead. +(F) It makes no sense to test the current stat buffer for symbolic +linkhood if the last stat that wrote to the stat buffer already went +past the symlink to get to the real file. Use an actual filename +instead. =item This Perl can't reset CRTL environ elements (%s) =item This Perl can't set CRTL environ elements (%s=%s) -(W internal) Warnings peculiar to VMS. You tried to change or delete an element -of the CRTL's internal environ array, but your copy of Perl wasn't -built with a CRTL that contained the setenv() function. You'll need to -rebuild Perl with a CRTL that does, or redefine F<PERL_ENV_TABLES> (see -L<perlvms>) so that the environ array isn't the target of the change to +(W internal) Warnings peculiar to VMS. You tried to change or delete an +element of the CRTL's internal environ array, but your copy of Perl +wasn't built with a CRTL that contained the setenv() function. You'll +need to rebuild Perl with a CRTL that does, or redefine +F<PERL_ENV_TABLES> (see L<perlvms>) so that the environ array isn't the +target of the change to %ENV which produced the warning. =item times not implemented -(F) Your version of the C library apparently doesn't do times(). I suspect -you're not running on Unix. +(F) Your version of the C library apparently doesn't do times(). I +suspect you're not running on Unix. =item Too few args to syscall @@ -3022,9 +3153,9 @@ script, it's too late to properly taint everything from the environment. So Perl gives up. If the Perl script is being executed as a command using the #! -mechanism (or its local equivalent), this error can usually be fixed -by editing the #! line so that the B<-T> option is a part of Perl's -first argument: e.g. change C<perl -n -T> to C<perl -T -n>. +mechanism (or its local equivalent), this error can usually be fixed by +editing the #! line so that the B<-T> option is a part of Perl's first +argument: e.g. change C<perl -n -T> to C<perl -T -n>. If the Perl script is being executed as C<perl scriptname>, then the B<-T> option must appear on the command line: C<perl -T scriptname>. @@ -3035,13 +3166,13 @@ B<-T> option must appear on the command line: C<perl -T scriptname>. B<-M> or B<-m> option. This is an error because B<-M> and B<-m> options are not intended for use inside scripts. Use the C<use> pragma instead. -=item Too many ('s - -=item Too many )'s +=item Too late to run %s block -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. +(W void) A CHECK or INIT block is being defined during run time proper, +when the opportunity to run them has already passed. Perhaps you are +loading a file with C<require> or C<do> when you should be using C<use> +instead. Or perhaps you should put the C<require> or C<do> inside a +BEGIN block. =item Too many args to syscall @@ -3051,10 +3182,17 @@ Perl yourself. (F) The function requires fewer arguments than you specified. +=item Too many )'s + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + +=item Too many ('s + =item trailing \ in regexp -(F) The regular expression ends with an unbackslashed backslash. Backslash -it. See L<perlre>. +(F) The regular expression ends with an unbackslashed backslash. +Backslash it. See L<perlre>. =item Transliteration pattern not terminated @@ -3086,8 +3224,8 @@ literals always start with 0 in Perl, as in C. =item umask not implemented -(F) Your machine doesn't implement the umask function and you tried -to use it to restrict permissions for yourself (EXPR & 0700). +(F) Your machine doesn't implement the umask function and you tried to +use it to restrict permissions for yourself (EXPR & 0700). =item Unable to create sub named "%s" @@ -3095,23 +3233,23 @@ to use it to restrict permissions for yourself (EXPR & 0700). =item Unbalanced context: %d more PUSHes than POPs -(W internal) The exit code detected an internal inconsistency in how many execution -contexts were entered and left. +(W internal) The exit code detected an internal inconsistency in how +many execution contexts were entered and left. =item Unbalanced saves: %d more saves than restores -(W internal) The exit code detected an internal inconsistency in how many -values were temporarily localized. +(W internal) The exit code detected an internal inconsistency in how +many values were temporarily localized. =item Unbalanced scopes: %d more ENTERs than LEAVEs -(W internal) The exit code detected an internal inconsistency in how many blocks -were entered and left. +(W internal) The exit code detected an internal inconsistency in how +many blocks were entered and left. =item Unbalanced tmps: %d more allocs than frees -(W internal) The exit code detected an internal inconsistency in how many mortal -scalars were allocated and freed. +(W internal) The exit code detected an internal inconsistency in how +many mortal scalars were allocated and freed. =item Undefined format "%s" called @@ -3120,13 +3258,13 @@ another package? See L<perlform>. =item Undefined sort subroutine "%s" called -(F) The sort comparison routine specified doesn't seem to exist. Perhaps -it's in a different package? See L<perlfunc/sort>. +(F) The sort comparison routine specified doesn't seem to exist. +Perhaps it's in a different package? See L<perlfunc/sort>. =item Undefined subroutine &%s called -(F) The subroutine indicated hasn't been defined, or if it was, it -has since been undefined. +(F) The subroutine indicated hasn't been defined, or if it was, it has +since been undefined. =item Undefined subroutine called @@ -3135,8 +3273,8 @@ or if it was, it has since been undefined. =item Undefined subroutine in sort -(F) The sort comparison routine specified is declared but doesn't seem to -have been defined yet. See L<perlfunc/sort>. +(F) The sort comparison routine specified is declared but doesn't seem +to have been defined yet. See L<perlfunc/sort>. =item Undefined top format "%s" called @@ -3145,8 +3283,14 @@ another package? See L<perlform>. =item Undefined value assigned to typeglob -(W misc) An undefined value was assigned to a typeglob, a la C<*foo = undef>. -This does nothing. It's possible that you really mean C<undef *foo>. +(W misc) An undefined value was assigned to a typeglob, a la +C<*foo = undef>. This does nothing. It's possible that you really mean +C<undef *foo>. + +=item %s: Undefined variable + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. =item unexec of %s into %s failed! @@ -3155,7 +3299,8 @@ representative, who probably put it there in the first place. =item Unknown BYTEORDER -(F) There are no byte-swapping functions for a machine with this byte order. +(F) There are no byte-swapping functions for a machine with this byte +order. =item Unknown open() mode '%s' @@ -3170,30 +3315,31 @@ iterating over it, and someone else stuck a message in the stream of data Perl expected. Someone's very confused, or perhaps trying to subvert Perl's population of %ENV for nefarious purposes. +=item unmatched [] in regexp + +(F) The brackets around a character class must match. If you wish to +include a closing bracket in a character class, backslash it or put it +first. See L<perlre>. + =item unmatched () in regexp (F) Unbackslashed parentheses must always be balanced in regular -expressions. If you're a vi user, the % key is valuable for finding -the matching parenthesis. See L<perlre>. +expressions. If you're a vi user, the % key is valuable for finding the +matching parenthesis. See L<perlre>. =item Unmatched right %s bracket -(F) The lexer counted more closing curly or square brackets than -opening ones, so you're probably missing a matching opening bracket. -As a general rule, you'll find the missing one (so to speak) near the -place you were last editing. - -=item unmatched [] in regexp - -(F) The brackets around a character class must match. If you wish to -include a closing bracket in a character class, backslash it or put it first. -See L<perlre>. +(F) The lexer counted more closing curly or square brackets than opening +ones, so you're probably missing a matching opening bracket. As a +general rule, you'll find the missing one (so to speak) near the place +you were last editing. =item Unquoted string "%s" may clash with future reserved word -(W reserved) You used a bareword that might someday be claimed as a reserved word. -It's best to put such a word in quotes, or capitalize it somehow, or insert -an underbar into it. You might also declare it as a subroutine. +(W reserved) You used a bareword that might someday be claimed as a +reserved word. It's best to put such a word in quotes, or capitalize it +somehow, or insert an underbar into it. You might also declare it as a +subroutine. =item Unrecognized character %s @@ -3201,238 +3347,283 @@ an underbar into it. You might also declare it as a subroutine. in your Perl script (or eval). Perhaps you tried to run a compressed script, a binary program, or a directory as a Perl program. +=item /%s/: Unrecognized escape \\%c in character class passed through + +(W regexp) You used a backslash-character combination which is not +recognized by Perl inside character classes. The character was +understood literally. + +=item /%s/: Unrecognized escape \\%c passed through + +(W regexp) You used a backslash-character combination which is not +recognized by Perl. This combination appears in an interpolated +variable or a C<'>-delimited regular expression. The character was +understood literally. + =item Unrecognized escape \\%c passed through -(W misc) You used a backslash-character combination which is not recognized -by Perl. +(W misc) You used a backslash-character combination which is not +recognized by Perl. =item Unrecognized signal name "%s" -(F) You specified a signal name to the kill() function that was not recognized. -Say C<kill -l> in your shell to see the valid signal names on your system. +(F) You specified a signal name to the kill() function that was not +recognized. Say C<kill -l> in your shell to see the valid signal names +on your system. =item Unrecognized switch: -%s (-h will show valid options) -(F) You specified an illegal option to Perl. Don't do that. -(If you think you didn't do that, check the #! line to see if it's -supplying the bad switch on your behalf.) +(F) You specified an illegal option to Perl. Don't do that. (If you +think you didn't do that, check the #! line to see if it's supplying the +bad switch on your behalf.) =item Unsuccessful %s on filename containing newline -(W newline) A file operation was attempted on a filename, and that operation -failed, PROBABLY because the filename contained a newline, PROBABLY -because you forgot to chop() or chomp() it off. See L<perlfunc/chomp>. +(W newline) A file operation was attempted on a filename, and that +operation failed, PROBABLY because the filename contained a newline, +PROBABLY because you forgot to chop() or chomp() it off. See +L<perlfunc/chomp>. =item Unsupported directory function "%s" called (F) Your machine doesn't support opendir() and readdir(). -=item Unsupported function fork - -(F) Your version of executable does not support forking. - -Note that under some systems, like OS/2, there may be different flavors of -Perl executables, some of which may support fork, some not. Try changing -the name you call Perl by to C<perl_>, C<perl__>, and so on. - =item Unsupported function %s (F) This machine doesn't implement the indicated function, apparently. At least, Configure doesn't think so. +=item Unsupported function fork + +(F) Your version of executable does not support forking. + +Note that under some systems, like OS/2, there may be different flavors +of Perl executables, some of which may support fork, some not. Try +changing the name you call Perl by to C<perl_>, C<perl__>, and so on. + =item Unsupported socket function "%s" called (F) Your machine doesn't support the Berkeley socket mechanism, or at least that's what Configure thought. -=item Unterminated <> operator +=item Unterminated attribute list -(F) The lexer saw a left angle bracket in a place where it was expecting -a term, so it's looking for the corresponding right angle bracket, and not -finding it. Chances are you left some needed parentheses out earlier in -the line, and you really meant a "less than". +(F) The lexer found something other than a simple identifier at the +start of an attribute, and it wasn't a semicolon or the start of a +block. Perhaps you terminated the parameter list of the previous +attribute too soon. See L<attributes>. =item Unterminated attribute parameter in attribute list -(F) The lexer saw an opening (left) parenthesis character while parsing an -attribute list, but the matching closing (right) parenthesis +(F) The lexer saw an opening (left) parenthesis character while parsing +an attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance. See L<attributes>. -=item Unterminated attribute list +=item Unterminated <> operator -(F) The lexer found something other than a simple identifier at the start -of an attribute, and it wasn't a semicolon or the start of a -block. Perhaps you terminated the parameter list of the previous attribute -too soon. See L<attributes>. +(F) The lexer saw a left angle bracket in a place where it was expecting +a term, so it's looking for the corresponding right angle bracket, and +not finding it. Chances are you left some needed parentheses out +earlier in the line, and you really meant a "less than". -=item Use of $# is deprecated +=item untie attempted while %d inner references still exist -(D deprecated) This was an ill-advised attempt to emulate a poorly defined B<awk> feature. -Use an explicit printf() or sprintf() instead. +(W untie) A copy of the object returned from C<tie> (or C<tied>) was +still valid when C<untie> was called. -=item Use of $* is deprecated +=item Useless use of %s in void context -(D deprecated) This variable magically turned on multi-line pattern matching, both for -you and for any luckless subroutine that you happen to call. You should -use the new C<//m> and C<//s> modifiers now to do that without the dangerous -action-at-a-distance effects of C<$*>. +(W void) You did something without a side effect in a context that does +nothing with the return value, such as a statement that doesn't return a +value from a block, or the left side of a scalar comma operator. Very +often this points not to stupidity on your part, but a failure of Perl +to parse your program the way you thought it would. For example, you'd +get this if you mixed up your C precedence with Python precedence and +said -=item Use of %s in printf format not supported + $one, $two = 1, 2; -(F) You attempted to use a feature of printf that is accessible from -only C. This usually means there's a better way to do it in Perl. +when you meant to say -=item Use of bare << to mean <<"" is deprecated + ($one, $two) = (1, 2); + +Another common error is to use ordinary parentheses to construct a list +reference when you should be using square or curly brackets, for +example, if you say -(D deprecated) You are now encouraged to use the explicitly quoted form if you -wish to use an empty line as the terminator of the here-document. + $array = (1,2); -=item Use of implicit split to @_ is deprecated +when you should have said -(D deprecated) It makes a lot of work for the compiler when you clobber a -subroutine's argument list, so it's better if you assign the results of -a split() explicitly to an array (or list). + $array = [1,2]; -=item Use of inherited AUTOLOAD for non-method %s() is deprecated +The square brackets explicitly turn a list value into a scalar value, +while parentheses do not. So when a parenthesized list is evaluated in +a scalar context, the comma is treated like C's comma operator, which +throws away the left argument, which is not what you want. See +L<perlref> for more on this. -(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> subroutines are -looked up as methods (using the C<@ISA> hierarchy) even when the subroutines -to be autoloaded were called as plain functions (e.g. C<Foo::bar()>), -not as methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>). +=item Useless use of "re" pragma -This bug will be rectified in Perl 5.005, which will use method lookup -only for methods' C<AUTOLOAD>s. However, there is a significant base -of existing code that may be using the old behavior. So, as an -interim step, Perl 5.004 issues an optional warning when non-methods -use inherited C<AUTOLOAD>s. +(W) You did C<use re;> without any arguments. That isn't very useful. -The simple rule is: Inheritance will not work when autoloading -non-methods. The simple fix for old code is: In any module that used to -depend on inheriting C<AUTOLOAD> for non-methods from a base class named -C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup. +=item "use" not allowed in expression -In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> you -should remove AutoLoader from @ISA and change C<use AutoLoader;> to -C<use AutoLoader 'AUTOLOAD';>. +(F) The "use" keyword is recognized and executed at compile time, and +returns no useful value. See L<perlmod>. -=item Use of reserved word "%s" is deprecated +=item Use of bare << to mean <<"" is deprecated -(D deprecated) The indicated bareword is a reserved word. Future versions of perl -may use it as a keyword, so you're better off either explicitly quoting -the word in a manner appropriate for its context of use, or using a -different name altogether. The warning can be suppressed for subroutine -names by either adding a C<&> prefix, or using a package qualifier, -e.g. C<&our()>, or C<Foo::our()>. +(D deprecated) You are now encouraged to use the explicitly quoted form +if you wish to use an empty line as the terminator of the here-document. -=item Use of %s is deprecated +=item Use of implicit split to @_ is deprecated -(D deprecated) The construct indicated is no longer recommended for use, generally -because there's a better way to do it, and also because the old way has -bad side effects. +(D deprecated) It makes a lot of work for the compiler when you clobber +a subroutine's argument list, so it's better if you assign the results +of a split() explicitly to an array (or list). -=item Use of uninitialized value%s +=item Use of inherited AUTOLOAD for non-method %s() is deprecated -(W uninitialized) An undefined value was used as if it were already defined. It was -interpreted as a "" or a 0, but maybe it was a mistake. To suppress this -warning assign a defined value to your variables. +(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> subroutines +are looked up as methods (using the C<@ISA> hierarchy) even when the +subroutines to be autoloaded were called as plain functions (e.g. +C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or C<< +$obj->bar() >>). -=item Useless use of "re" pragma +This bug will be rectified in future by using method lookup only for +methods' C<AUTOLOAD>s. However, there is a significant base of existing +code that may be using the old behavior. So, as an interim step, Perl +currently issues an optional warning when non-methods use inherited +C<AUTOLOAD>s. -(W) You did C<use re;> without any arguments. That isn't very useful. +The simple rule is: Inheritance will not work when autoloading +non-methods. The simple fix for old code is: In any module that used +to depend on inheriting C<AUTOLOAD> for non-methods from a base class +named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during +startup. -=item Useless use of %s in void context +In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> +you should remove AutoLoader from @ISA and change C<use AutoLoader;> to +C<use AutoLoader 'AUTOLOAD';>. -(W void) You did something without a side effect in a context that does nothing -with the return value, such as a statement that doesn't return a value -from a block, or the left side of a scalar comma operator. Very often -this points not to stupidity on your part, but a failure of Perl to parse -your program the way you thought it would. For example, you'd get this -if you mixed up your C precedence with Python precedence and said +=item Use of %s in printf format not supported - $one, $two = 1, 2; +(F) You attempted to use a feature of printf that is accessible from +only C. This usually means there's a better way to do it in Perl. -when you meant to say +=item Use of $* is deprecated - ($one, $two) = (1, 2); +(D deprecated) This variable magically turned on multi-line pattern +matching, both for you and for any luckless subroutine that you happen +to call. You should use the new C<//m> and C<//s> modifiers now to do +that without the dangerous action-at-a-distance effects of C<$*>. -Another common error is to use ordinary parentheses to construct a list -reference when you should be using square or curly brackets, for -example, if you say +=item Use of %s is deprecated - $array = (1,2); +(D deprecated) The construct indicated is no longer recommended for use, +generally because there's a better way to do it, and also because the +old way has bad side effects. -when you should have said +=item Use of $# is deprecated - $array = [1,2]; +(D deprecated) This was an ill-advised attempt to emulate a poorly +defined B<awk> feature. Use an explicit printf() or sprintf() instead. -The square brackets explicitly turn a list value into a scalar value, -while parentheses do not. So when a parenthesized list is evaluated in -a scalar context, the comma is treated like C's comma operator, which -throws away the left argument, which is not what you want. See -L<perlref> for more on this. +=item Use of reserved word "%s" is deprecated -=item untie attempted while %d inner references still exist +(D deprecated) The indicated bareword is a reserved word. Future +versions of perl may use it as a keyword, so you're better off either +explicitly quoting the word in a manner appropriate for its context of +use, or using a different name altogether. The warning can be +suppressed for subroutine names by either adding a C<&> prefix, or using +a package qualifier, e.g. C<&our()>, or C<Foo::our()>. -(W untie) A copy of the object returned from C<tie> (or C<tied>) was still -valid when C<untie> was called. +=item Use of uninitialized value%s + +(W uninitialized) An undefined value was used as if it were already +defined. It was interpreted as a "" or a 0, but maybe it was a mistake. +To suppress this warning assign a defined value to your variables. + +To help you figure out what was undefined, perl tells you what operation +you used the undefined value in. Note, however, that perl optimizes your +program and the operation displayed in the warning may not necessarily +appear literally in your program. For example, C<"that $foo"> is +usually optimized into C<"that " . $foo>, and the warning will refer to +the C<concatenation (.)> operator, even though there is no C<.> in your +program. =item Value of %s can be "0"; test with defined() -(W misc) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>, -or C<readdir()> as a boolean value. Each of these constructs can return a -value of "0"; that would make the conditional expression false, which is -probably not what you intended. When using these constructs in conditional -expressions, test their values with the C<defined> operator. +(W misc) In a conditional expression, you used <HANDLE>, <*> (glob), +C<each()>, or C<readdir()> as a boolean value. Each of these constructs +can return a value of "0"; that would make the conditional expression +false, which is probably not what you intended. When using these +constructs in conditional expressions, test their values with the +C<defined> operator. =item Value of CLI symbol "%s" too long -(W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV -element from a CLI symbol table, and found a resultant string longer -than 1024 characters. The return value has been truncated to 1024 -characters. +(W misc) A warning peculiar to VMS. Perl tried to read the value of an +%ENV element from a CLI symbol table, and found a resultant string +longer than 1024 characters. The return value has been truncated to +1024 characters. =item Variable "%s" is not imported%s -(F) While "use strict" in effect, you referred to a global variable -that you apparently thought was imported from another module, because -something else of the same name (usually a subroutine) is exported -by that module. It usually means you put the wrong funny character -on the front of your variable. +(F) While "use strict" in effect, you referred to a global variable that +you apparently thought was imported from another module, because +something else of the same name (usually a subroutine) is exported by +that module. It usually means you put the wrong funny character on the +front of your variable. + +=item "%s" variable %s masks earlier declaration in same %s + +(W misc) A "my" or "our" variable has been redeclared in the current +scope or statement, effectively eliminating all access to the previous +instance. This is almost always a typographical error. Note that the +earlier variable will still exist until the end of the scope or until +all closure referents to it are destroyed. =item Variable "%s" may be unavailable -(W closure) An inner (nested) I<anonymous> subroutine is inside a I<named> -subroutine, and outside that is another subroutine; and the anonymous -(innermost) subroutine is referencing a lexical variable defined in -the outermost subroutine. For example: +(W closure) An inner (nested) I<anonymous> subroutine is inside a +I<named> subroutine, and outside that is another subroutine; and the +anonymous (innermost) subroutine is referencing a lexical variable +defined in the outermost subroutine. For example: sub outermost { my $a; sub middle { sub { $a } } } If the anonymous subroutine is called or referenced (directly or -indirectly) from the outermost subroutine, it will share the variable -as you would expect. But if the anonymous subroutine is called or -referenced when the outermost subroutine is not active, it will see -the value of the shared variable as it was before and during the -*first* call to the outermost subroutine, which is probably not what -you want. - -In these circumstances, it is usually best to make the middle -subroutine anonymous, using the C<sub {}> syntax. Perl has specific -support for shared variables in nested anonymous subroutines; a named -subroutine in between interferes with this feature. +indirectly) from the outermost subroutine, it will share the variable as +you would expect. But if the anonymous subroutine is called or +referenced when the outermost subroutine is not active, it will see the +value of the shared variable as it was before and during the *first* +call to the outermost subroutine, which is probably not what you want. + +In these circumstances, it is usually best to make the middle subroutine +anonymous, using the C<sub {}> syntax. Perl has specific support for +shared variables in nested anonymous subroutines; a named subroutine in +between interferes with this feature. + +=item Variable syntax + +(A) You've accidentally run your script through B<csh> instead +of Perl. Check the #! line, or manually feed your script into +Perl yourself. =item Variable "%s" will not stay shared -(W closure) An inner (nested) I<named> subroutine is referencing a lexical -variable defined in an outer subroutine. +(W closure) An inner (nested) I<named> subroutine is referencing a +lexical variable defined in an outer subroutine. When the inner subroutine is called, it will probably see the value of -the outer subroutine's variable as it was before and during the -*first* call to the outer subroutine; in this case, after the first -call to the outer subroutine is complete, the inner and outer -subroutines will no longer share a common value for the variable. In -other words, the variable will no longer be shared. +the outer subroutine's variable as it was before and during the *first* +call to the outer subroutine; in this case, after the first call to the +outer subroutine is complete, the inner and outer subroutines will no +longer share a common value for the variable. In other words, the +variable will no longer be shared. Furthermore, if the outer subroutine is anonymous and references a lexical variable outside itself, then the outer and inner subroutines @@ -3440,15 +3631,8 @@ will I<never> share the given variable. This problem can usually be solved by making the inner subroutine anonymous, using the C<sub {}> syntax. When inner anonymous subs that -reference variables in outer subroutines are called or referenced, -they are automatically rebound to the current values of such -variables. - -=item Variable syntax - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. +reference variables in outer subroutines are called or referenced, they +are automatically rebound to the current values of such variables. =item Version number must be a constant number @@ -3456,27 +3640,6 @@ Perl yourself. its equivalent C<BEGIN> block found an internal inconsistency with the version number. -=item perl: warning: Setting locale failed. - -(S) The whole warning message will look something like: - - perl: warning: Setting locale failed. - perl: warning: Please check that your locale settings: - LC_ALL = "En_US", - LANG = (unset) - are supported and installed on your system. - perl: warning: Falling back to the standard locale ("C"). - -Exactly what were the failed locale settings varies. In the above the -settings were that the LC_ALL was "En_US" and the LANG had no value. -This error means that Perl detected that you and/or your system -administrator have set up the so-called variable system but Perl could -not use those settings. This was not dead serious, fortunately: there -is a "default locale" called "C" that Perl can and will use, the -script will be run. Before you really fix the problem, however, you -will get the same error message each time you run Perl. How to really -fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. - =item Warning: something's wrong (W) You passed warn() an empty string (the equivalent of C<warn "">) or @@ -3484,15 +3647,16 @@ you called it with no args and C<$_> was empty. =item Warning: unable to close filehandle %s properly -(S) The implicit close() done by an open() got an error indication on the -close(). This usually indicates your file system ran out of disk space. +(S) The implicit close() done by an open() got an error indication on +the close(). This usually indicates your file system ran out of disk +space. =item Warning: Use of "%s" without parentheses is ambiguous -(S ambiguous) You wrote a unary operator followed by something that looks like a -binary operator that could also have been interpreted as a term or -unary operator. For instance, if you know that the rand function -has a default argument of 1.0, and you write +(S ambiguous) You wrote a unary operator followed by something that +looks like a binary operator that could also have been interpreted as a +term or unary operator. For instance, if you know that the rand +function has a default argument of 1.0, and you write rand + 5; @@ -3508,8 +3672,8 @@ So put in parentheses to say what you really mean. =item write() on closed filehandle %s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. =item X outside of string @@ -3523,99 +3687,34 @@ the end of the string being unpacked. See L<perlfunc/pack>. =item Xsub "%s" called in sort -(F) The use of an external subroutine as a sort comparison is not yet supported. +(F) The use of an external subroutine as a sort comparison is not yet +supported. =item Xsub called in sort -(F) The use of an external subroutine as a sort comparison is not yet supported. +(F) The use of an external subroutine as a sort comparison is not yet +supported. =item You can't use C<-l> on a filehandle -(F) A filehandle represents an opened file, and when you opened the file it -already went past any symlink you are presumably trying to look for. +(F) A filehandle represents an opened file, and when you opened the file +it already went past any symlink you are presumably trying to look for. Use a filename instead. =item YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET! (F) And you probably never will, because you probably don't have the sources to your kernel, and your vendor probably doesn't give a rip -about what you want. Your best bet is to use the wrapsuid script in -the eg directory to put a setuid C wrapper around your script. +about what you want. Your best bet is to use the wrapsuid script in the +eg directory to put a setuid C wrapper around your script. =item You need to quote "%s" -(W syntax) You assigned a bareword as a signal handler name. Unfortunately, you -already have a subroutine of that name declared, which means that Perl 5 -will try to call the subroutine when the assignment is executed, which is -probably not what you want. (If it IS what you want, put an & in front.) - -=item %cetsockopt() on closed socket %s - -(W closed) You tried to get or set a socket option on a closed socket. -Did you forget to check the return value of your socket() call? -See L<perlfunc/getsockopt> and L<perlfunc/setsockopt>. - -=item \1 better written as $1 - -(W syntax) Outside of patterns, backreferences live on as variables. The use -of backslashes is grandfathered on the right-hand side of a -substitution, but stylistically it's better to use the variable form -because other Perl programmers will expect it, and it works better -if there are more than 9 backreferences. - -=item '|' and '<' may not both be specified on command line - -(F) An error peculiar to VMS. Perl does its own command line redirection, and -found that STDIN was a pipe, and that you also tried to redirect STDIN using -'<'. Only one STDIN stream to a customer, please. - -=item '|' and '>' may not both be specified on command line - -(F) An error peculiar to VMS. Perl does its own command line redirection, and -thinks you tried to redirect stdout both to a file and into a pipe to another -command. You need to choose one or the other, though nothing's stopping you -from piping into a program or Perl script which 'splits' output into two -streams, such as - - open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!"; - while (<STDIN>) { - print; - print OUT; - } - close OUT; - -=item Got an error from DosAllocMem - -(P) An error peculiar to OS/2. Most probably you're using an obsolete -version of Perl, and this should not happen anyway. - -=item Malformed PERLLIB_PREFIX - -(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form - - prefix1;prefix2 - -or - - prefix1 prefix2 - -with nonempty prefix1 and prefix2. If C<prefix1> is indeed a prefix -of a builtin library search path, prefix2 is substituted. The error -may appear if components are not found, or are too long. See -"PERLLIB_PREFIX" in F<README.os2>. - -=item PERL_SH_DIR too long - -(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the -C<sh>-shell in. See "PERL_SH_DIR" in F<README.os2>. - -=item Process terminated by SIG%s - -(W) This is a standard message issued by OS/2 applications, while *nix -applications die in silence. It is considered a feature of the OS/2 -port. One can easily disable this by appropriate sighandlers, see -L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT" -in F<README.os2>. +(W syntax) You assigned a bareword as a signal handler name. +Unfortunately, you already have a subroutine of that name declared, +which means that Perl 5 will try to call the subroutine when the +assignment is executed, which is probably not what you want. (If it IS +what you want, put an & in front.) =back diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod index 372e1ffda5..b05b7361c0 100644 --- a/pod/perlfaq3.pod +++ b/pod/perlfaq3.pod @@ -48,7 +48,8 @@ uninteresting, but may still be what you want. =head2 How do I debug my Perl programs? -Have you used C<-w>? It enables warnings for dubious practices. +Have you tried C<use warnings> or used C<-w>? They enable warnings +for dubious practices. Have you tried C<use strict>? It prevents you from using symbolic references, makes you predeclare any subroutines that you call as bare diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod index ad4824577d..e997a8fcb9 100644 --- a/pod/perlfaq4.pod +++ b/pod/perlfaq4.pod @@ -444,11 +444,9 @@ nested patterns, nor can they. For that you'll have to write a parser. If you are serious about writing a parser, there are a number of -modules or oddities that will make your life a lot easier. There is -the CPAN module Parse::RecDescent, the standard module Text::Balanced, -the byacc program, the CPAN module Parse::Yapp, and Mark-Jason -Dominus's excellent I<py> tool at http://www.plover.com/%7Emjd/perl/py/ -. +modules or oddities that will make your life a lot easier. There are +the CPAN modules Parse::RecDescent, Parse::Yapp, and Text::Balanced; +and the byacc program. One simple destructive, inside-out approach that you might try is to pull out the smallest nesting parts one at a time: @@ -940,7 +938,8 @@ with @bad[0] = `same program that outputs several lines`; -The B<-w> flag will warn you about these matters. +The C<use warnings> pragma and the B<-w> flag will warn you about these +matters. =head2 How can I remove duplicate elements from a list or array? @@ -1070,7 +1069,7 @@ strings. Modify if you have other needs. sub compare_arrays { my ($first, $second) = @_; - local $^W = 0; # silence spurious -w undef complaints + no warnings; # silence spurious -w undef complaints return 0 unless @$first == @$second; for (my $i = 0; $i < @$first; $i++) { return 0 if $first->[$i] ne $second->[$i]; diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod index 6ae7755f8b..feb66a45cd 100644 --- a/pod/perlfaq5.pod +++ b/pod/perlfaq5.pod @@ -841,7 +841,7 @@ you see someone do this: You should think long and hard about why you need everything loaded at once. It's just not a scalable solution. You might also find it -more fun to use the the standard DB_File module's $DB_RECNO bindings, +more fun to use the standard DB_File module's $DB_RECNO bindings, which allow you to tie an array to a file so that accessing an element the array actually accesses the corresponding line in the file. diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod index 0afbc0dd34..1ca7893f13 100644 --- a/pod/perlfaq7.pod +++ b/pod/perlfaq7.pod @@ -84,8 +84,17 @@ Another way is to use undef as an element on the left-hand-side: =head2 How do I temporarily block warnings? -The C<$^W> variable (documented in L<perlvar>) controls -runtime warnings for a block: +If you are running Perl 5.6.0 or better, the C<use warnings> pragma +allows fine control of what warning are produced. +See L<perllexwarn> for more details. + + { + no warnings; # temporarily turn off warnings + $a = $b + $c; # I know these might be undef + } + +If you have an older version of Perl, the C<$^W> variable (documented +in L<perlvar>) controls runtime warnings for a block: { local $^W = 0; # temporarily turn off warnings @@ -95,10 +104,6 @@ runtime warnings for a block: Note that like all the punctuation variables, you cannot currently use my() on C<$^W>, only local(). -A new C<use warnings> pragma is in the works to provide finer control -over all this. The curious should check the perl5-porters mailing list -archives for details. - =head2 What's an extension? A way of calling compiled C code from Perl. Reading L<perlxstut> @@ -168,6 +173,7 @@ own module. Make sure to change the names appropriately. package Some::Module; # assumes Some/Module.pm use strict; + use warnings; BEGIN { use Exporter (); @@ -611,7 +617,7 @@ Why do you want to do that? :-) If you want to override a predefined function, such as open(), then you'll have to import the new definition from a different -module. See L<perlsub/"Overriding Builtin Functions">. There's +module. See L<perlsub/"Overriding Built-in Functions">. There's also an example in L<perltoot/"Class::Template">. If you want to overload a Perl operator, such as C<+> or C<**>, diff --git a/pod/perlfilter.pod b/pod/perlfilter.pod index bf287c0873..c3c83153ad 100644 --- a/pod/perlfilter.pod +++ b/pod/perlfilter.pod @@ -410,6 +410,7 @@ Here is the complete Debug filter: package Debug; use strict; + use warnings; use Filter::Util::Call ; use constant TRUE => 1 ; diff --git a/pod/perlfork.pod b/pod/perlfork.pod index d930e9396e..82ac6891db 100644 --- a/pod/perlfork.pod +++ b/pod/perlfork.pod @@ -11,7 +11,7 @@ call is available, Perl's fork() simply calls it. On some platforms such as Windows where the fork() system call is not available, Perl can be built to emulate fork() at the interpreter level. While the emulation is designed to be as compatible as possible with the -real fork() at the the level of the Perl program, there are certain +real fork() at the level of the Perl program, there are certain important differences that stem from the fact that all the pseudo child "processes" created this way live in the same real process as far as the operating system is concerned. @@ -51,7 +51,7 @@ pseudo-processes are launched after others have been wait()-ed on. =item %ENV -Each pseudo-process maintains its own virtual enviroment. Modifications +Each pseudo-process maintains its own virtual environment. Modifications to %ENV affect the virtual environment, and are only visible within that pseudo-process, and in any processes (or pseudo-processes) launched from it. diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 7bae55a802..4e67506e26 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -146,11 +146,11 @@ C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray> =item Keywords related to scoping -C<caller>, C<import>, C<local>, C<my>, C<package>, C<use> +C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use> =item Miscellaneous functions -C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<reset>, +C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>, C<scalar>, C<undef>, C<wantarray> =item Functions for processes and process groups @@ -200,8 +200,8 @@ C<gmtime>, C<localtime>, C<time>, C<times> =item Functions new in perl5 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>, -C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<prototype>, C<qx>, -C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>, +C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>, +C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use> * - C<sub> was a keyword in perl4, but in perl5 it is an @@ -488,7 +488,7 @@ files, but it can be disastrous for binary files. Another consequence of using binmode() (on some systems) is that special end-of-file markers will be seen as part of the data stream. For systems from the Microsoft family this means that if your binary -data contains C<\cZ>, the I/O subsystem will ragard it as the end of +data contains C<\cZ>, the I/O subsystem will regard it as the end of the file, unless you use binmode(). binmode() is not only important for readline() and print() operations, @@ -539,9 +539,10 @@ Here $subroutine may be C<(eval)> if the frame is not a subroutine call, but an C<eval>. In such a case additional elements $evaltext and C<$is_require> are set: C<$is_require> is true if the frame is created by a C<require> or C<use> statement, $evaltext contains the text of the -C<eval EXPR> statement. In particular, for a C<eval BLOCK> statement, +C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement, $filename is C<(eval)>, but $evaltext is undefined. (Note also that each C<use> statement creates a C<require> frame inside an C<eval EXPR>) +frame. C<$hasargs> is true if a new instance of C<@_> was set up for the frame. C<$hints> and C<$bitmask> contain pragmatic hints that the caller was compiled with. The C<$hints> and C<$bitmask> values are subject to change between versions of Perl, and are not meant for external use. @@ -1055,7 +1056,7 @@ If C<$@> is empty then the string C<"Died"> is used. die() can also be called with a reference argument. If this happens to be trapped within an eval(), $@ contains the reference. This behavior permits a more elaborate exception handling implementation using objects that -maintain arbitary state about the nature of the exception. Such a scheme +maintain arbitrary state about the nature of the exception. Such a scheme is sometimes preferable to matching particular string values of $@ using regular expressions. Here's an example: @@ -1432,6 +1433,12 @@ program, passing it C<"surprise"> an argument. The second version didn't--it tried to run a program literally called I<"echo surprise">, didn't find it, and set C<$?> to a non-zero value indicating failure. +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before the exec, but this may not be supported on some platforms +(see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH +in English) or call the C<autoflush()> method of C<IO::Handle> on any +open handles in order to avoid lost output. + Note that C<exec> will not call your C<END> blocks, nor will it call any C<DESTROY> methods in your objects. @@ -1650,7 +1657,11 @@ fork(), great care has gone into making it extremely efficient (for example, using copy-on-write technology on data pages), making it the dominant paradigm for multitasking over the last few decades. -All files opened for output are flushed before forking the child process. +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before forking the child process, but this may not be supported +on some platforms (see L<perlport>). To be safe, you may need to set +C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of +C<IO::Handle> on any open handles in order to avoid duplicate output. If you C<fork> without ever waiting on your children, you will accumulate zombies. On some systems, you can avoid this by setting @@ -1849,6 +1860,14 @@ various get routines are as follows: (If the entry doesn't exist you get a null list.) +The exact meaning of the $gcos field varies but it usually contains +the real name of the user (as opposed to the login name) and other +information pertaining to the user. Beware, however, that in many +system users are able to change this information and therefore it +cannot be trusted and therefore the $gcos is tainted (see +L<perlsec>). The $passwd and $shell, user's encrypted password and +login shell, are also tainted, because of the same reason. + In scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. (If the entry doesn't exist you get the undefined value.) For example: @@ -1861,26 +1880,27 @@ lookup by name, in which case you get the other thing, whatever it is. $name = getgrent(); #etc. -In I<getpw*()> the fields $quota, $comment, and $expire are -special cases in the sense that in many systems they are unsupported. -If the $quota is unsupported, it is an empty scalar. If it is -supported, it usually encodes the disk quota. If the $comment -field is unsupported, it is an empty scalar. If it is supported it -usually encodes some administrative comment about the user. In some -systems the $quota field may be $change or $age, fields that have -to do with password aging. In some systems the $comment field may -be $class. The $expire field, if present, encodes the expiration -period of the account or the password. For the availability and the -exact meaning of these fields in your system, please consult your -getpwnam(3) documentation and your F<pwd.h> file. You can also find -out from within Perl what your $quota and $comment fields mean -and whether you have the $expire field by using the C<Config> module -and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>, -and C<d_pwexpire>. Shadow password files are only supported if your -vendor has implemented them in the intuitive fashion that calling the -regular C library routines gets the shadow versions if you're running -under privilege. Those that incorrectly implement a separate library -call are not supported. +In I<getpw*()> the fields $quota, $comment, and $expire are special +cases in the sense that in many systems they are unsupported. If the +$quota is unsupported, it is an empty scalar. If it is supported, it +usually encodes the disk quota. If the $comment field is unsupported, +it is an empty scalar. If it is supported it usually encodes some +administrative comment about the user. In some systems the $quota +field may be $change or $age, fields that have to do with password +aging. In some systems the $comment field may be $class. The $expire +field, if present, encodes the expiration period of the account or the +password. For the availability and the exact meaning of these fields +in your system, please consult your getpwnam(3) documentation and your +F<pwd.h> file. You can also find out from within Perl what your +$quota and $comment fields mean and whether you have the $expire field +by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>, +C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password +files are only supported if your vendor has implemented them in the +intuitive fashion that calling the regular C library routines gets the +shadow versions if you're running under privilege or if there exists +the shadow(3) functions as found in System V ( this includes Solaris +and Linux.) Those systems which implement a proprietary shadow password +facility are unlikely to be supported. The $members value returned by I<getgr*()> is a space separated list of the login names of the members of the group. @@ -1966,7 +1986,7 @@ itself, in the range C<0..11> with 0 indicating January and 11 indicating December. $year is the number of years since 1900. That is, $year is C<123> in year 2023. $wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<1..365> (or C<1..366> in leap years.) +the year, in the range C<0..364> (or C<0..365> in leap years.) Note that the $year element is I<not> simply the last two digits of the year. If you assume it is, then you create non-Y2K-compliant @@ -2197,6 +2217,9 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } +The returned values are copies of the original keys in the hash, so +modifying them will not affect the original hash. Compare L</values>. + To sort a hash by value, you'll need to use a C<sort> function. Here's a descending numeric sort of a hash by its values: @@ -2334,7 +2357,7 @@ itself, in the range C<0..11> with 0 indicating January and 11 indicating December. $year is the number of years since 1900. That is, $year is C<123> in year 2023. $wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<1..365> (or C<1..366> in leap years.) $isdst +the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst is true if the specified time occurs during daylight savings time, false otherwise. @@ -2480,22 +2503,25 @@ Calls the System V IPC function msgget(2). Returns the message queue id, or the undefined value if there is an error. See also C<IPC::SysV> and C<IPC::Msg> documentation. -=item msgsnd ID,MSG,FLAGS - -Calls the System V IPC function msgsnd to send the message MSG to the -message queue ID. MSG must begin with the native long integer message -type, which may be created with C<pack("l!", $type)>. Returns true if -successful, or false if there is an error. See also C<IPC::SysV> and -C<IPC::SysV::Msg> documentation. - =item msgrcv ID,VAR,SIZE,TYPE,FLAGS Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of -SIZE. Note that if a message is received, the message type will be -the first thing in VAR, and the maximum length of VAR is SIZE plus the -size of the message type. Returns true if successful, or false if -there is an error. See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation. +SIZE. Note that when a message is received, the message type as a +native long integer will be the first thing in VAR, followed by the +actual message. This packing may be opened with C<unpack("l! a*")>. +Taints the variable. Returns true if successful, or false if there is +an error. See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation. + +=item msgsnd ID,MSG,FLAGS + +Calls the System V IPC function msgsnd to send the message MSG to the +message queue ID. MSG must begin with the native long integer message +type, and be followed by the length of the actual message, and finally +the message itself. This kind of packing can be achieved with +C<pack("l! a*", $type, $message)>. Returns true if successful, +or false if there is an error. See also C<IPC::SysV> +and C<IPC::SysV::Msg> documentation. =item my EXPR @@ -2567,7 +2593,10 @@ conversion assumes base 10.) Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the -name of the real filehandle wanted. If EXPR is omitted, the scalar +name of the real filehandle wanted. (This is considered a symbolic +reference, so C<use strict 'refs'> should I<not> be in effect.) + +If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. (Note that lexical variables--those declared with C<my>--will not work for this purpose; so if you're using C<my>, specify EXPR in your call @@ -2599,7 +2628,8 @@ C<'|'>, the filename is interpreted as a command which pipes output to us. See L<perlipc/"Using open() for IPC"> for more examples of this. (You are not allowed to C<open> to a command that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, -and L<perlipc/"Bidirectional Communication"> for alternatives.) +and L<perlipc/"Bidirectional Communication with Another Process"> +for alternatives.) If MODE is C<'|-'>, the filename is interpreted as a command to which output is to be piped, and if MODE is @@ -2753,8 +2783,13 @@ The following triples are more or less equivalent: See L<perlipc/"Safe Pipe Opens"> for more examples of this. -NOTE: On any operation that may do a fork, all files opened for output -are flushed before the fork is attempted. On systems that support a +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before any operation that may do a fork, but this may not be +supported on some platforms (see L<perlport>). To be safe, you may need +to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method +of C<IO::Handle> on any open handles. + +On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptor as determined by the value of $^F. See L<perlvar/$^F>. @@ -2781,7 +2816,7 @@ otherwise it's necessary to protect any leading and trailing whitespace: open(FOO, "< $file\0"); (this may not work on some bizzare filesystems). One should -conscientiously choose between the the I<magic> and 3-arguments form +conscientiously choose between the I<magic> and 3-arguments form of open(): open IN, $ARGV[0]; @@ -2894,7 +2929,7 @@ sequence of characters that give the order and type of values, as follows: a A string with arbitrary binary data, will be null padded. - A An ascii string, will be space padded. + A An ASCII string, will be space padded. Z A null terminated (asciz) string, will be null padded. b A bit string (ascending bit order inside each byte, like vec()). @@ -3898,7 +3933,7 @@ GETALL, then ARG must be a variable which will hold the returned semid_ds structure or semaphore value array. Returns like C<ioctl>: the undefined value for error, "C<0 but true>" for zero, or the actual return value otherwise. The ARG must consist of a vector of native -short integers, which may may be created with C<pack("s!",(0)x$nsem)>. +short integers, which may be created with C<pack("s!",(0)x$nsem)>. See also C<IPC::SysV> and C<IPC::Semaphore> documentation. =item semget KEY,NSEMS,FLAGS @@ -3967,7 +4002,7 @@ C<@ARGV> array at file scopes or within the lexical scopes established by the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}> constructs. -See also C<unshift>, C<push>, and C<pop>. C<Shift()> and C<unshift> do the +See also C<unshift>, C<push>, and C<pop>. C<shift()> and C<unshift> do the same thing to the left end of an array that C<pop> and C<push> do to the right end. @@ -3999,8 +4034,8 @@ detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, or false if there is an error. -See also C<IPC::SysV> documentation and the C<IPC::Shareable> module -from CPAN. +shmread() taints the variable. See also C<IPC::SysV> documentation and +the C<IPC::Shareable> module from CPAN. =item shutdown SOCKET,HOW @@ -4103,9 +4138,9 @@ of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. If the subroutine's prototype is C<($$)>, the elements to be compared -are passed by reference in C<@_>, as for a normal subroutine. If not, -the normal calling code for subroutines is bypassed in the interests of -efficiency, and the elements to be compared are passed into the subroutine +are passed by reference in C<@_>, as for a normal subroutine. This is +slower than unprototyped subroutines, where the elements to be +compared are passed into the subroutine as the package global variables $a and $b (see example below). Note that in the latter case, it is usually counter-productive to declare $a and $b as lexicals. @@ -4625,7 +4660,7 @@ The commonly available S_IF* constants are and the S_IF* functions are - S_IFMODE($mode) the part of $mode containg the permission bits + S_IFMODE($mode) the part of $mode containing the permission bits and the setuid/setgid/sticky bits S_IFMT($mode) the part of $mode containing the file type @@ -4910,7 +4945,11 @@ platforms). If there are no shell metacharacters in the argument, it is split into words and passed directly to C<execvp>, which is more efficient. -All files opened for output are flushed before attempting the exec(). +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before any operation that may do a fork, but this may not be +supported on some platforms (see L<perlport>). To be safe, you may need +to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method +of C<IO::Handle> on any open handles. The return value is the exit status of the program as returned by the C<wait> call. To get the actual exit value divide by @@ -5382,12 +5421,11 @@ subject to change in future versions of perl, but it is guaranteed to be the same order as either the C<keys> or C<each> function would produce on the same (unmodified) hash. -Note that you cannot modify the values of a hash this way, because the -returned list is just a copy. You need to use a hash slice for that, -since it's lvaluable in a way that values() is not. +Note that the values are not copied, which means modifying them will +modify the contents of the hash: - for (values %hash) { s/foo/bar/g } # FAILS! - for (@hash{keys %hash}) { s/foo/bar/g } # ok + for (values %hash) { s/foo/bar/g } # modifies %hash values + for (@hash{keys %hash}) { s/foo/bar/g } # same As a side effect, calling values() resets the HASH's internal iterator. See also C<keys>, C<each>, and C<sort>. diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 6caed3ebf8..5f1dd21a14 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -398,14 +398,13 @@ you to stringify the keys (unlike the previous set of functions). They also return and accept whole hash entries (C<HE*>), making their use more efficient (since the hash number for a particular string -doesn't have to be recomputed every time). See L<API LISTING> later in -this document for detailed descriptions. +doesn't have to be recomputed every time). See L<perlapi> for detailed +descriptions. The following macros must always be used to access the contents of hash entries. Note that the arguments to these macros must be simple variables, since they may get evaluated more than once. See -L<API LISTING> later in this document for detailed descriptions of these -macros. +L<perlapi> for detailed descriptions of these macros. HePV(HE* he, STRLEN len) HeVAL(HE* he) @@ -912,7 +911,7 @@ calling these functions, or by using one of the C<sv_set*_mg()> or C<sv_cat*_mg()> functions. Similarly, generic C code must call the C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV obtained from external sources in functions that don't handle magic. -L<API LISTING> later in this document identifies such functions. +See L<perlapi> for a description of these functions. For example, calls to the C<sv_cat*()> functions typically need to be followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()> since their implementation handles 'get' magic. @@ -1464,13 +1463,13 @@ C<gvsv gvsv add whatever>. =head2 Compile pass 1: check routines -The tree is created by the I<pseudo-compiler> while yacc code feeds it -the constructions it recognizes. Since yacc works bottom-up, so does +The tree is created by the compiler while I<yacc> code feeds it +the constructions it recognizes. Since I<yacc> works bottom-up, so does the first pass of perl compilation. What makes this pass interesting for perl developers is that some optimization may be performed on this pass. This is optimization by -so-called I<check routines>. The correspondence between node names +so-called "check routines". The correspondence between node names and corresponding check routines is described in F<opcode.pl> (do not forget to run C<make regen_headers> if you modify this file). @@ -1524,9 +1523,6 @@ are subject to the same restrictions as in the pass 2. =head1 How multiple interpreters and concurrency are supported -WARNING: This information is subject to radical changes prior to -the Perl 5.6 release. Use with caution. - =head2 Background and PERL_IMPLICIT_CONTEXT The Perl interpreter can be regarded as a closed box: it has an API @@ -1560,8 +1556,8 @@ which will be private. All functions whose names begin C<S_> are private "Perl_", but just because a function begins with "Perl_" does not mean it is part of the API. The easiest way to be B<sure> a function is part of the API is to find its entry in L<perlapi>. If it exists in L<perlapi>, it's part -of the API. If it doesn't, and you think it should be (i.e., you need it fo -r your extension), send mail via L<perlbug> explaining why you think it +of the API. If it doesn't, and you think it should be (i.e., you need it for +your extension), send mail via L<perlbug> explaining why you think it should be. (L<perlapi> itself is generated by embed.pl, a Perl script that generates @@ -1669,7 +1665,7 @@ Thus, something like: sv_setsv(asv, bsv); -in your extesion will translate to this when PERL_IMPLICIT_CONTEXT is +in your extension will translate to this when PERL_IMPLICIT_CONTEXT is in effect: Perl_sv_setsv(Perl_get_context(), asv, bsv); diff --git a/pod/perlhack.pod b/pod/perlhack.pod index 3a84e95513..c640870264 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -269,7 +269,7 @@ way to gain a precise understanding of the overall architecture of the language. If you build a version of the Perl interpreter with C<-DDEBUGGING>, -Perl's B<-D> commandline flag will cause copious debugging information +Perl's B<-D> command line flag will cause copious debugging information to be emitted (see the C<perlrun> manpage). If you build a version of Perl with compiler debugging information (e.g. with the C compiler's C<-g> option instead of C<-O>) then you can step through the execution diff --git a/pod/perlhist.pod b/pod/perlhist.pod index 17a13a2fd3..4311ee2813 100644 --- a/pod/perlhist.pod +++ b/pod/perlhist.pod @@ -333,10 +333,13 @@ the strings?). 5.005_62 1999-Oct-15 5.005_63 1999-Dec-09 5.5.640 2000-Feb-02 - 5.5.650 2000-Feb-08 5.6 beta1 - 5.5.660 2000-Feb-22 5.6 beta2 - 5.5.670 2000-Feb-29 5.6 beta3 - 5.6.0-RC1 2000-Mar-09 5.6 release candidate 1 + 5.5.650 2000-Feb-08 beta1 + 5.5.660 2000-Feb-22 beta2 + 5.5.670 2000-Feb-29 beta3 + 5.6.0-RC1 2000-Mar-09 release candidate 1 + 5.6.0-RC2 2000-Mar-14 release candidate 2 + 5.6.0-RC3 2000-Mar-21 release candidate 3 + 5.6.0 2000-Mar-22 =head2 SELECTED RELEASE SIZES diff --git a/pod/perlintern.pod b/pod/perlintern.pod index 58eeac6e95..b0aab33e2b 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -6,7 +6,7 @@ perlintern - autogenerated documentation of purely B<internal> =head1 DESCRIPTION This file is the autogenerated documentation of functions in the -Perl intrepreter that are documented using Perl's internal documentation +Perl interpreter that are documented using Perl's internal documentation format but are not marked as part of the Perl API. In other words, B<they are not for use in extensions>! @@ -16,7 +16,7 @@ B<they are not for use in extensions>! =head1 AUTHORS -The autodocumentation system was orignally added to the Perl core by +The autodocumentation system was originally added to the Perl core by Benjamin Stuhl. Documentation is by whoever was kind enough to document their functions. diff --git a/pod/perlipc.pod b/pod/perlipc.pod index 3ddea3e41b..475271d071 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -453,8 +453,8 @@ doesn't actually work: open(PROG_FOR_READING_AND_WRITING, "| some program |") -and if you forget to use the B<-w> flag, then you'll miss out -entirely on the diagnostic message: +and if you forget to use the C<use warnings> pragma or the B<-w> flag, +then you'll miss out entirely on the diagnostic message: Can't do bidirectional pipe at -e line 1. @@ -667,7 +667,8 @@ instead. my $port = shift || 2345; my $proto = getprotobyname('tcp'); - $port = $1 if $port =~ /(\d+)/; # untaint port number + + ($port) = $port =~ /^(\d+)$/ || die "invalid port"; socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, @@ -710,7 +711,8 @@ go back to service a new client. my $port = shift || 2345; my $proto = getprotobyname('tcp'); - $port = $1 if $port =~ /(\d+)/; # untaint port number + + ($port) = $port =~ /^(\d+)$/ || die "invalid port"; socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, @@ -922,7 +924,7 @@ For those preferring a higher-level interface to socket programming, the IO::Socket module provides an object-oriented approach. IO::Socket is included as part of the standard Perl distribution as of the 5.004 release. If you're running an earlier version of Perl, just fetch -IO::Socket from CPAN, where you'll also find find modules providing easy +IO::Socket from CPAN, where you'll also find modules providing easy interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just to name a few. @@ -1022,7 +1024,7 @@ something to the server before fetching the server's response. } The web server handing the "http" service, which is assumed to be at -its standard port, number 80. If your the web server you're trying to +its standard port, number 80. If the web server you're trying to connect to is at a different port (like 1080 or 8080), you should specify as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush> method is used on the socket because otherwise the system would buffer @@ -1305,16 +1307,16 @@ you weren't wanting it to. Here's a small example showing shared memory usage. - use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU S_IRWXG S_IRWXO); + use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU); $size = 2000; - $key = shmget(IPC_PRIVATE, $size, S_IRWXU|S_IRWXG|S_IRWXO) || die "$!"; - print "shm key $key\n"; + $id = shmget(IPC_PRIVATE, $size, S_IRWXU) || die "$!"; + print "shm key $id\n"; $message = "Message #1"; - shmwrite($key, $message, 0, 60) || die "$!"; + shmwrite($id, $message, 0, 60) || die "$!"; print "wrote: '$message'\n"; - shmread($key, $buff, 0, 60) || die "$!"; + shmread($id, $buff, 0, 60) || die "$!"; print "read : '$buff'\n"; # the buffer of shmread is zero-character end-padded. @@ -1322,16 +1324,16 @@ Here's a small example showing shared memory usage. print "un" unless $buff eq $message; print "swell\n"; - print "deleting shm $key\n"; - shmctl($key, IPC_RMID, 0) || die "$!"; + print "deleting shm $id\n"; + shmctl($id, IPC_RMID, 0) || die "$!"; Here's an example of a semaphore: use IPC::SysV qw(IPC_CREAT); $IPC_KEY = 1234; - $key = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!"; - print "shm key $key\n"; + $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!"; + print "shm key $id\n"; Put this code in a separate file to be run in more than one process. Call the file F<take>: @@ -1339,8 +1341,8 @@ Call the file F<take>: # create a semaphore $IPC_KEY = 1234; - $key = semget($IPC_KEY, 0 , 0 ); - die if !defined($key); + $id = semget($IPC_KEY, 0 , 0 ); + die if !defined($id); $semnum = 0; $semflag = 0; @@ -1348,14 +1350,14 @@ Call the file F<take>: # 'take' semaphore # wait for semaphore to be zero $semop = 0; - $opstring1 = pack("sss", $semnum, $semop, $semflag); + $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag); # Increment the semaphore count $semop = 1; - $opstring2 = pack("sss", $semnum, $semop, $semflag); + $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag); $opstring = $opstring1 . $opstring2; - semop($key,$opstring) || die "$!"; + semop($id,$opstring) || die "$!"; Put this code in a separate file to be run in more than one process. Call this file F<give>: @@ -1365,22 +1367,53 @@ Call this file F<give>: # that the second process continues $IPC_KEY = 1234; - $key = semget($IPC_KEY, 0, 0); - die if !defined($key); + $id = semget($IPC_KEY, 0, 0); + die if !defined($id); $semnum = 0; $semflag = 0; # Decrement the semaphore count $semop = -1; - $opstring = pack("sss", $semnum, $semop, $semflag); + $opstring = pack("s!s!s!", $semnum, $semop, $semflag); - semop($key,$opstring) || die "$!"; + semop($id,$opstring) || die "$!"; The SysV IPC code above was written long ago, and it's definitely clunky looking. For a more modern look, see the IPC::SysV module which is included with Perl starting from Perl 5.005. +A small example demonstrating SysV message queues: + + use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU); + + my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRWXU); + + my $sent = "message"; + my $type = 1234; + my $rcvd; + my $type_rcvd; + + if (defined $id) { + if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) { + if (msgrcv($id, $rcvd, 60, 0, 0)) { + ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd); + if ($rcvd eq $sent) { + print "okay\n"; + } else { + print "not okay\n"; + } + } else { + die "# msgrcv failed\n"; + } + } else { + die "# msgsnd failed\n"; + } + msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n"; + } else { + die "# msgget failed\n"; + } + =head1 NOTES Most of these routines quietly but politely return C<undef> when they diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod index af1a910334..0052d33ff2 100644 --- a/pod/perllexwarn.pod +++ b/pod/perllexwarn.pod @@ -9,7 +9,7 @@ flag B<-w> and the equivalent Perl variable, C<$^W>. The pragma works just like the existing "strict" pragma. This means that the scope of the warning pragma is limited to the -enclosing block. It also means that that the pragma setting will not +enclosing block. It also means that the pragma setting will not leak across files (via C<use>, C<require> or C<do>). This allows authors to independently define the degree of warning checks that will be applied to their module. @@ -195,7 +195,7 @@ or B<-X> command line flags. =back -The combined effect of 3 & 4 is that it will will allow code which uses +The combined effect of 3 & 4 is that it will allow code which uses the C<warnings> pragma to control the warning behavior of $^W-type code (using a C<local $^W=0>) if it really wants to, but not vice-versa. @@ -339,20 +339,49 @@ fatal error. =head2 Reporting Warnings from a Module -The C<warnings> pragma provides two functions, namely C<warnings::enabled> -and C<warnings::warn>, that are useful for module authors. They are -used when you want to report a module-specific warning, but only when -the calling module has enabled warnings via the C<warnings> pragma. +The C<warnings> pragma provides a number of functions that are useful for +module authors. These are used when you want to report a module-specific +warning when the calling module has enabled warnings via the C<warnings> +pragma. -Consider the module C<abc> below. +Consider the module C<MyMod::Abc> below. - package abc; + package MyMod::Abc; - sub open - { + use warnings::register; + + sub open { + my $path = shift ; + if (warnings::enabled() && $path !~ m#^/#) { + warnings::warn("changing relative path to /tmp/"); + $path = "/tmp/$path" ; + } + } + + 1 ; + +The call to C<warnings::register> will create a new warnings category +called "MyMod::abc", i.e. the new category name matches the module +name. The C<open> function in the module will display a warning message +if it gets given a relative path as a parameter. This warnings will only +be displayed if the code that uses C<MyMod::Abc> has actually enabled +them with the C<warnings> pragma like below. + + use MyMod::Abc; + use warnings 'MyMod::Abc'; + ... + abc::open("../fred.txt"); + +It is also possible to test whether the pre-defined warnings categories are +set in the calling module with the C<warnings::enabled> function. Consider +this snippet of code: + + package MyMod::Abc; + + sub open { if (warnings::enabled("deprecated")) { warnings::warn("deprecated", - "abc::open is deprecated. Use abc:new") ; + "open is deprecated, use new instead") ; } new(@_) ; } @@ -366,21 +395,21 @@ display a warning message whenever the calling module has (at least) the "deprecated" warnings category enabled. Something like this, say. use warnings 'deprecated'; - use abc; + use MyMod::Abc; ... - abc::open($filename) ; - + MyMod::Abc::open($filename) ; -If the calling module has escalated the "deprecated" warnings category -into a fatal error like this: +The C<warnings::warn> function should be used to actually display the +warnings message. This is because they can make use of the feature that +allows warnings to be escalated into fatal errors. So in this case - use warnings 'FATAL deprecated'; - use abc; + use MyMod::Abc; + use warnings FATAL => 'MyMod::Abc'; ... - abc::open($filename) ; + MyMod::Abc::open('../fred.txt'); -then C<warnings::warn> will detect this and die after displaying the -warning message. +the C<warnings::warn> function will detect this and die after +displaying the warning message. =head1 TODO diff --git a/pod/perllocale.pod b/pod/perllocale.pod index ea56e1e03e..55ccf441fd 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -289,7 +289,7 @@ than the PERL_BADLANG approach, but setting LC_ALL (or other locale variables) may affect other programs as well, not just Perl. In particular, external programs run from within Perl will see these changes. If you make the new settings permanent (read on), all -programs you run see the changes. See L<ENVIRONMENT> for for +programs you run see the changes. See L<ENVIRONMENT> for the full list of relevant environment variables and L<USING LOCALES> for their effects in Perl. Effects in other programs are easily deducible. For example, the variable LC_COLLATE may well affect @@ -332,9 +332,9 @@ Second, if using the listed commands you see something B<exactly> (prefix matches do not count and case usually counts) like "En_US" without the quotes, then you should be okay because you are using a locale name that should be installed and available in your system. -In this case, see L<Permanently fixing system locale configuration>. +In this case, see L<Permanently fixing your system's locale configuration>. -=head2 Permanently fixing your locale configuration +=head2 Permanently fixing your system's locale configuration This is when you see something like: diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 994c3eb5dc..6bec46b028 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -85,7 +85,7 @@ and L<perlref> regarding closures. The symbol table for a package happens to be stored in the hash of that name with two colons appended. The main symbol table's name is thus -C<%main::>, or C<%::> for short. Likewise symbol table for the nested +C<%main::>, or C<%::> for short. Likewise the symbol table for the nested package mentioned earlier is named C<%OUTER::INNER::>. The value in each entry of the hash is what you are referring to when you @@ -97,7 +97,7 @@ table lookups at compile time: local $main::{foo} = $main::{bar}; You can use this to print out all the variables in a package, for -instance. The standard but antequated F<dumpvar.pl> library and +instance. The standard but antiquated F<dumpvar.pl> library and the CPAN module Devel::Symdump make use of this. Assignment to a typeglob performs an aliasing operation, i.e., @@ -115,7 +115,7 @@ Which makes $richard and $dick the same variable, but leaves @richard and @dick as separate arrays. Tricky, eh? This mechanism may be used to pass and return cheap references -into or from subroutines if you won't want to copy the whole +into or from subroutines if you don't want to copy the whole thing. It only works when assigning to dynamic variables, not lexicals. @@ -132,7 +132,7 @@ lexicals. On return, the reference will overwrite the hash slot in the symbol table specified by the *some_hash typeglob. This is a somewhat tricky way of passing around references cheaply -when you won't want to have to remember to dereference variables +when you don't want to have to remember to dereference variables explicitly. Another use of symbol tables is for making "constant" scalars. @@ -141,9 +141,9 @@ Another use of symbol tables is for making "constant" scalars. Now you cannot alter $PI, which is probably a good thing all in all. This isn't the same as a constant subroutine, which is subject to -optimization at compile-time. This isn't. A constant subroutine is one -prototyped to take no arguments and to return a constant expression. -See L<perlsub> for details on these. The C<use constant> pragma is a +optimization at compile-time. A constant subroutine is one prototyped +to take no arguments and to return a constant expression. See +L<perlsub> for details on these. The C<use constant> pragma is a convenient shorthand for these. You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and @@ -163,7 +163,7 @@ This prints You gave me bar::baz The C<*foo{THING}> notation can also be used to obtain references to the -individual elements of *foo, see L<perlref>. +individual elements of *foo. See L<perlref>. Subroutine definitions (and declarations, for that matter) need not necessarily be situated in the package whose symbol table they @@ -233,7 +233,7 @@ being blown out of the water by a signal--you have to trap that yourself (if you can).) You may have multiple C<END> blocks within a file--they will execute in reverse order of definition; that is: last in, first out (LIFO). C<END> blocks are not executed when you run perl with the -C<-c> switch. +C<-c> switch, or if compilation fails. Inside an C<END> subroutine, C<$?> contains the value that the program is going to pass to C<exit()>. You can modify C<$?> to change the exit @@ -251,10 +251,10 @@ LIFO order. C<CHECK> blocks are again useful in the Perl compiler suite to save the compiled state of the program. When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and -C<END> work just as they do in B<awk>, as a degenerate case. As currently -implemented (and subject to change, since its inconvenient at best), -both C<BEGIN> and<END> blocks are run when you use the B<-c> switch -for a compile-only syntax check, although your main code is not. +C<END> work just as they do in B<awk>, as a degenerate case. +Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c> +switch for a compile-only syntax check, although your main code +is not. =head2 Perl Classes @@ -268,14 +268,14 @@ For more on this, see L<perltoot> and L<perlobj>. =head2 Perl Modules -A module is just a set of related function in a library file a Perl -package with the same name as the file. It is specifically designed -to be reusable by other modules or programs. It may do this by -providing a mechanism for exporting some of its symbols into the +A module is just a set of related functions in a library file, i.e., +a Perl package with the same name as the file. It is specifically +designed to be reusable by other modules or programs. It may do this +by providing a mechanism for exporting some of its symbols into the symbol table of any package using it. Or it may function as a class definition and make its semantics available implicitly through method calls on the class and its objects, without explicitly -exportating anything. Or it can do a little of both. +exporting anything. Or it can do a little of both. For example, to start a traditional, non-OO module called Some::Module, create a file called F<Some/Module.pm> and start with this template: @@ -283,6 +283,7 @@ create a file called F<Some/Module.pm> and start with this template: package Some::Module; # assumes Some/Module.pm use strict; + use warnings; BEGIN { use Exporter (); @@ -418,19 +419,19 @@ that other module. In that case, it's easy to use C<require>s instead. Perl packages may be nested inside other package names, so we can have package names containing C<::>. But if we used that package name -directly as a filename it would makes for unwieldy or impossible +directly as a filename it would make for unwieldy or impossible filenames on some systems. Therefore, if a module's name is, say, C<Text::Soundex>, then its definition is actually found in the library file F<Text/Soundex.pm>. Perl modules always have a F<.pm> file, but there may also be dynamically linked executables (often ending in F<.so>) or autoloaded -subroutine definitions (often ending in F<.al> associated with the +subroutine definitions (often ending in F<.al>) associated with the module. If so, these will be entirely transparent to the user of the module. It is the responsibility of the F<.pm> file to load (or arrange to autoload) any additional functionality. For example, although the POSIX module happens to do both dynamic loading and -autoloading, but the user can say just C<use POSIX> to get it all. +autoloading, the user can say just C<use POSIX> to get it all. =head1 SEE ALSO diff --git a/pod/perlmodinstall.pod b/pod/perlmodinstall.pod index 5f1c62e96d..57f62a5cd5 100644 --- a/pod/perlmodinstall.pod +++ b/pod/perlmodinstall.pod @@ -91,6 +91,11 @@ While still in that directory, type: Make sure you have appropriate permissions to install the module in your Perl 5 library directory. Often, you'll need to be root. +Perl maintains a record of all module installations. To look at +this list, simply type: + + perldoc perllocal + That's all you need to do on Unix systems with dynamic linking. Most Unix systems have dynamic linking--if yours doesn't, or if for another reason you have a statically-linked perl, I<and> the @@ -183,7 +188,7 @@ A. DECOMPRESS In general, all Macintosh decompression utilities mentioned here can be found in the Info-Mac Hyperarchive ( http://hyperarchive.lcs.mit.edu/HyperArchive.html ). -Specificly the "Commpress & Translate" listing +Specifically the "Compress & Translate" listing ( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ). diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod index 38044c9157..164cb643f7 100644 --- a/pod/perlmodlib.pod +++ b/pod/perlmodlib.pod @@ -802,23 +802,28 @@ By-name interface to Perl's built-in getpw*() functions To find out I<all> modules installed on your system, including those without documentation or outside the standard release, -jus tdo this: +just do this: % find `perl -e 'print "@INC"'` -name '*.pm' -print -They should all have their own documentation installed and accessible -via your system man(1) command. If you do not have a B<find> +To get a log of all module distributions which have been installed +since perl was installed, just do: + + % perldoc perllocal + +Modules should all have their own documentation installed and accessible +via your system man(1) command, or via the C<perldoc> program. If you do +not have a B<find> program, you can use the Perl B<find2perl> program instead, which generates Perl code as output you can run through perl. If you have a B<man> program but it doesn't find your modules, you'll have -to fix your manpath. See L<perl> for details. If you have no -system B<man> command, you might try the B<perldoc> program. +to fix your manpath. See L<perl> for details. =head2 Extension Modules Extension modules are written in C (or a mix of Perl and C). They are usually dynamically loaded into Perl if and when you need them, -but may also be be linked in statically. Supported extension modules +but may also be linked in statically. Supported extension modules include Socket, Fcntl, and POSIX. Many popular C extension modules do not come bundled (at least, not @@ -1120,7 +1125,9 @@ scheme as the original author. =item Try to design the new module to be easy to extend and reuse. -Always use B<-w>. +Try to C<use warnings;> (or C<use warnings qw(...);>). +Remember that you can add C<no warnings qw(...);> to individual blocks +of code that need less warnings. Use blessed references. Use the two argument form of bless to bless into the class name given as the first parameter of the constructor, diff --git a/pod/perlnumber.pod b/pod/perlnumber.pod index c05b066b43..d179d8c74a 100644 --- a/pod/perlnumber.pod +++ b/pod/perlnumber.pod @@ -22,11 +22,11 @@ Perl's operator overloading facility is completely ignored here. Operator overloading allows user-defined behaviors for numbers, such as operations over arbitrarily large integers, floating points numbers with arbitrary precision, operations over "exotic" numbers such as modular arithmetic or -p-adic arithmetic, and so on. See L<perlovl> for details. +p-adic arithmetic, and so on. See L<overload> for details. =head1 Storing numbers -Perl can internally represents numbers in 3 different ways: as native +Perl can internally represent numbers in 3 different ways: as native integers, as native floating point numbers, and as decimal strings. Decimal strings may have an exponential notation part, as in C<"12.34e-56">. I<Native> here means "a format supported by the C compiler which was used @@ -36,10 +36,10 @@ The term "native" does not mean quite as much when we talk about native integers, as it does when native floating point numbers are involved. The only implication of the term "native" on integers is that the limits for the maximal and the minimal supported true integral quantities are close to -powers of 2. However, for "native" floats have a most fundamental +powers of 2. However, "native" floats have a most fundamental restriction: they may represent only those numbers which have a relatively "short" representation when converted to a binary fraction. For example, -0.9 cannot be respresented by a native float, since the binary fraction +0.9 cannot be represented by a native float, since the binary fraction for 0.9 is infinite: binary0.1110011001100... @@ -54,14 +54,14 @@ The upshot of all this is that Perl cannot store a number like 12345678901234567 as a floating point number on such architectures without loss of information. -Similarly, decimal strings may represent only those numbers which have a +Similarly, decimal strings can represent only those numbers which have a finite decimal expansion. Being strings, and thus of arbitrary length, there is no practical limit for the exponent or number of decimal digits for these numbers. (But realize that what we are discussing the rules for just the I<storage> of these numbers. The fact that you can store such "large" numbers -does not mean that that the I<operations> over these numbers will use all +does not mean that the I<operations> over these numbers will use all of the significant digits. -See L<"Numeric operations and numeric conversions"> for details.) +See L<"Numeric operators and numeric conversions"> for details.) In fact numbers stored in the native integer format may be stored either in the signed native form, or in the unsigned native form. Thus the limits @@ -182,4 +182,4 @@ Editorial adjustments by Gurusamy Sarathy <gsar@ActiveState.com> =head1 SEE ALSO -L<perlovl> +L<overload> diff --git a/pod/perlop.pod b/pod/perlop.pod index 5e4ce937fa..b4caed9155 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -788,8 +788,8 @@ If "'" is the delimiter, no interpolation is performed on the PATTERN. PATTERN may contain variables, which will be interpolated (and the pattern recompiled) every time the pattern search is evaluated, except -for when the delimiter is a single quote. (Note that C<$)> and C<$|> -might not be interpolated because they look like end-of-string tests.) +for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and +C<$|> are not interpolated because they look like end-of-string tests.) If you want such a pattern to be compiled only once, add a C</o> after the trailing delimiter. This avoids expensive run-time recompilations, and is useful when the value you are interpolating won't change over @@ -1051,6 +1051,12 @@ multiple commands in a single line by separating them with the command separator character, if your shell supports that (e.g. C<;> on many Unix shells; C<&> on the Windows NT C<cmd> shell). +Beginning with v5.6.0, Perl will attempt to flush all files opened for +output before starting the child process, but this may not be supported +on some platforms (see L<perlport>). To be safe, you may need to set +C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of +C<IO::Handle> on any open handles. + Beware that some command shells may place restrictions on the length of the command line. You must ensure your strings don't exceed this limit after any necessary interpolations. See the platform-specific @@ -1091,8 +1097,8 @@ Some frequently seen examples: A common mistake is to try to separate the words with comma or to put comments into a multi-line C<qw>-string. For this reason, the -B<-w> switch (that is, the C<$^W> variable) produces warnings if -the STRING contains the "," or the "#" character. +C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable) +produces warnings if the STRING contains the "," or the "#" character. =item s/PATTERN/REPLACEMENT/egimosx @@ -1134,9 +1140,10 @@ text is not evaluated as a command. If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own pair of quotes, which may or may not be bracketing quotes, e.g., C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the -replacement portion to be interpreted as a full-fledged Perl expression -and eval()ed right then and there. It is, however, syntax checked at -compile-time. +replacement portion to be treated as a full-fledged Perl expression +and evaluated right then and there. It is, however, syntax checked at +compile-time. A second C<e> modifier will cause the replacement portion +to be C<eval>ed before being run as a Perl expression. Examples: @@ -1163,8 +1170,12 @@ Examples: # symbolic dereferencing s/\$(\w+)/${$1}/g; - # /e's can even nest; this will expand - # any embedded scalar variable (including lexicals) in $_ + # Add one to the value of any numbers in the string + s/(\d+)/1 + $1/eg; + + # This will expand any embedded scalar variable + # (including lexicals) in $_ : First $1 is interpolated + # to the variable name, and then evaluated s/(\$\w+)/$1/eeg; # Delete (most) C comments. @@ -1214,6 +1225,12 @@ SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes, e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>. +Note that C<tr> does B<not> do regular expression character classes +such as C<\d> or C<[:lower:]>. The <tr> operator is not equivalent to +the tr(1) utility. If you want to map strings between lower/upper +cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider +using the C<s> operator if you need regular expressions. + Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results you probably didn't expect. A sound principle is to use only ranges @@ -1401,7 +1418,7 @@ as C<"\\\t"> (since TAB is not alphanumeric). Note also that: may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">. Interpolated scalars and arrays are converted internally to the C<join> and -C<.> catentation operations. Thus, C<"$foo XXX '@arr'"> becomes: +C<.> catenation operations. Thus, C<"$foo XXX '@arr'"> becomes: $foo . " XXX '" . (join $", @arr) . "'"; @@ -1452,8 +1469,8 @@ the result is not predictable. It is at this step that C<\1> is begrudgingly converted to C<$1> in the replacement text of C<s///> to correct the incorrigible I<sed> hackers who haven't picked up the saner idiom yet. A warning -is emitted if the B<-w> command-line flag (that is, the C<$^W> variable) -was set. +is emitted if the C<use warnings> pragma or the B<-w> command-line flag +(that is, the C<$^W> variable) was set. The lack of processing of C<\\> creates specific restrictions on the post-processed text. If the delimiter is C</>, one cannot get @@ -1514,7 +1531,7 @@ terminator of a C<{}>-delimited construct. It is possible to inspect both the string given to RE engine and the resulting finite automaton. See the arguments C<debug>/C<debugcolor> in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line -switch documented in L<perlrun/Switches>. +switch documented in L<perlrun/"Command Switches">. =item Optimization of regular expressions @@ -1591,7 +1608,8 @@ to terminate the loop, they should be tested for explicitly: while (<STDIN>) { last unless $_; ... } In other boolean contexts, C<< <I<filehandle>> >> without an -explicit C<defined> test or comparison elicit a warning if the B<-w> +explicit C<defined> test or comparison elicit a warning if the +C<use warnings> pragma or the B<-w> command-line switch (the C<$^W> variable) is in effect. The filehandles STDIN, STDOUT, and STDERR are predefined. (The @@ -1719,7 +1737,7 @@ A (file)glob evaluates its (embedded) argument only when it is starting a new list. All values must be read before it will start over. In list context, this isn't important because you automatically get them all anyway. However, in scalar context the operator returns -the next value each time it's called, or C +the next value each time it's called, or C<undef> when the list has run out. As with filehandle reads, an automatic C<defined> is generated when the glob occurs in the test part of a C<while>, because legal glob returns (e.g. a file called F<0>) would otherwise diff --git a/pod/perlopentut.pod b/pod/perlopentut.pod index 9cb9f6738a..5d2d48e7f1 100644 --- a/pod/perlopentut.pod +++ b/pod/perlopentut.pod @@ -309,7 +309,7 @@ C<O_DEFER>, C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>, C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>. Consult your open(2) manpage or its local equivalent for details. (Note: starting from Perl release 5.6 the O_LARGEFILE flag, if available, is automatically -added to the sysopen() flags because large files are the the default.) +added to the sysopen() flags because large files are the default.) Here's how to use C<sysopen> to emulate the simple C<open> calls we had before. We'll omit the C<|| die $!> checks for clarity, but make sure diff --git a/pod/perlpod.pod b/pod/perlpod.pod index fd0a1de873..6c0c5348c4 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -154,10 +154,11 @@ It will be filled, and maybe even justified. Certain interior sequences are recognized both here and in commands: - I<text> italicize text, used for emphasis or variables - B<text> embolden text, used for switches and programs - S<text> text contains non-breaking spaces - C<code> literal code + I<text> Italicize text, used for emphasis or variables + B<text> Embolden text, used for switches and programs + S<text> Text contains non-breaking spaces + C<code> Render code in a typewriter font, or give some other + indication that this represents program text L<name> A link (cross reference) to name L<name> manual page L<name/ident> item in manual page diff --git a/pod/perlport.pod b/pod/perlport.pod index 10723ee3a4..7f779c955e 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -197,7 +197,7 @@ If you need to distinguish between endian architectures you could use either of the variables set like so: $is_big_endian = unpack("h*", pack("s", 1)) =~ /01/; - $is_litte_endian = unpack("h*", pack("s", 1)) =~ /^1/; + $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/; Differing widths can cause truncation even between platforms of equal endianness. The platform of shorter width loses the upper parts of the @@ -217,7 +217,7 @@ So, it is reasonably safe to assume that all platforms support the notion of a "path" to uniquely identify a file on the system. How that path is really written, though, differs considerably. -Atlhough similar, file path specifications differ between Unix, +Although similar, file path specifications differ between Unix, Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others. Unix, for example, is one of the few OSes that has the elegant idea of a single root directory. @@ -355,7 +355,7 @@ Commands that launch external processes are generally supported on most platforms (though many of them do not support any type of forking). The problem with using them arises from what you invoke them on. External tools are often named differently on different -platforms, may not be available in the same location, migth accept +platforms, may not be available in the same location, might accept different arguments, can behave differently, and often present their results in a platform-dependent way. Thus, you should seldom depend on them to produce consistent results. (Then again, if you're calling @@ -528,7 +528,7 @@ a given module works on a given platform. =item Mailing list: cpan-testers@perl.org -=item Testing results: C<http://testers.cpan.org/> +=item Testing results: http://testers.cpan.org/ =back @@ -654,21 +654,41 @@ Also see: =over 4 -=item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/> +=item * -=item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>, -C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html> or -C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx> +The djgpp environment for DOS, http://www.delorie.com/djgpp/ +and L<perldos>. -=item Build instructions for Win32, L<perlwin32>. +=item * -=item The ActiveState Pages, C<http://www.activestate.com/> +The EMX environment for DOS, OS/2, etc. emx@iaehv.nl, +http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or +ftp://hobbes.nmsu.edu/pub/os2/dev/emx. Also L<perlos2>. -=item The Cygwin environment for Win32; F<README.cygwin> (installed -as L<perlcygwin>), C<http://sourceware.cygnus.com/cygwin/> +=item * -=item The U/WIN environment for Win32, -C<http://www.research.att.com/sw/tools/uwin/> +Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment +in L<perlcygwin>. + +=item * + +The C<Win32::*> modules in L<Win32>. + +=item * + +The ActiveState Pages, http://www.activestate.com/ + +=item * + +The Cygwin environment for Win32; F<README.cygwin> (installed +as L<perlcygwin>), http://sourceware.cygnus.com/cygwin/ + +=item * + +The U/WIN environment for Win32, +<http://www.research.att.com/sw/tools/uwin/ + +=item Build instructions for OS/2, L<perlos2> =back @@ -742,17 +762,23 @@ Also see: =over 4 -=item The MacPerl Pages, C<http://www.macperl.com/>. +=item * + +The MacPerl Pages, http://www.macperl.com/ . + +=item * -=item The MacPerl mailing lists, C<http://www.macperl.org/>. +The MacPerl mailing lists, http://www.macperl.org/ . -=item MacPerl Module Porters, C<http://pudge.net/mmp/>. +=item * + +MacPerl Module Porters, http://pudge.net/mmp/ . =back =head2 VMS -Perl on VMS is discussed in F<vms/perlvms.pod> in the perl distribution. +Perl on VMS is discussed in L<perlvms> in the perl distribution. Perl on VMS can accept either VMS- or Unix-style file specifications as in either of the following: @@ -844,13 +870,19 @@ Also see: =over 4 -=item F<README.vms> (installed as L<README_vms>), L<perlvms> +=item * + +F<README.vms> (installed as L<README_vms>), L<perlvms> + +=item * -=item vmsperl list, C<majordomo@perl.org> +vmsperl list, majordomo@perl.org -Put the words C<subscribe vmsperl> in message body. +(Put the words C<subscribe vmsperl> in message body.) -=item vmsperl on the web, C<http://www.sidhe.org/vmsperl/index.html> +=item * + +vmsperl on the web, http://www.sidhe.org/vmsperl/index.html =back @@ -883,7 +915,7 @@ ftp.stratus.com. The value of C<$^O> on VOS is "VOS". To determine the architecture that you are running on without resorting to loading all of C<%Config> you -can examine the content of the C<@INC> array like so: +can examine the content of the @INC array like so: if ($^O =~ /VOS/) { print "I'm on a Stratus box!\n"; @@ -909,16 +941,22 @@ Also see: =over 4 -=item F<README.vos> +=item * + +F<README.vos> -=item VOS mailing list +=item * + +The VOS mailing list. There is no specific mailing list for Perl on VOS. You can post comments to the comp.sys.stratus newsgroup, or subscribe to the general Stratus mailing list. Send a letter with "Subscribe Info-Stratus" in the message body to majordomo@list.stratagy.com. -=item VOS Perl on the web at C<http://ftp.stratus.com/pub/vos/vos.html> +=item * + +VOS Perl on the web at http://ftp.stratus.com/pub/vos/vos.html =back @@ -931,6 +969,7 @@ Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390 systems). On the mainframe perl currently works under the "Unix system services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater). +See L<perlos390> for details. As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix sub-systems do not support the C<#!> shebang trick for script invocation. @@ -999,15 +1038,22 @@ Also see: =over 4 -=item F<README.os390>, F<README.posix-bc>, F<README.vmesa> +=item * + +* -=item perl-mvs list +L<perlos390>, F<README.os390>, F<README.posix-bc>, F<README.vmesa> + +=item * The perl-mvs@perl.org list is for discussion of porting issues as well as general usage issues for all EBCDIC Perls. Send a message body of "subscribe perl-mvs" to majordomo@perl.org. -=item AS/400 Perl information at C<http://as400.rochester.ibm.com/> +=item * + +AS/400 Perl information at +ttp://as400.rochester.ibm.com/ as well as on CPAN in the F<ports/> directory. =back @@ -1138,23 +1184,33 @@ See also: =over 4 -=item Amiga, F<README.amiga> (installed as L<perlamiga>). +=item * -=item Atari, F<README.mint> and Guido Flohr's web page -C<http://stud.uni-sb.de/~gufl0000/> +Amiga, F<README.amiga> (installed as L<perlamiga>). -=item Be OS, F<README.beos> +=item * -=item HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page -C<http://www.cccd.edu/~markb/perlix.html> +Atari, F<README.mint> and Guido Flohr's web page +http://stud.uni-sb.de/~gufl0000/ -=item Novell Netware +=item * + +Be OS, F<README.beos> + +=item * + +HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page +http://www.cccd.edu/~markb/perlix.html + +=item * A free perl5-based PERL.NLM for Novell Netware is available in -precompiled binary and source code form from C<http://www.novell.com/> +precompiled binary and source code form from http://www.novell.com/ as well as from CPAN. -=item Plan 9, F<README.plan9> +=item + +Plan 9, F<README.plan9> =back @@ -1223,6 +1279,12 @@ suffixes. C<-S> is meaningless. (Win32) C<-x> (or C<-X>) determine if a file has an executable file type. (S<RISC OS>) +=item alarm SECONDS + +=item alarm + +Not implemented. (Win32) + =item binmode FILEHANDLE Meaningless. (S<Mac OS>, S<RISC OS>) @@ -1287,6 +1349,9 @@ Not implemented. (S<Mac OS>) Implemented via Spawn. (VM/ESA) +Does not automatically flush output handles on some platforms. +(SunOS, Solaris, HP-UX) + =item fcntl FILEHANDLE,FUNCTION,SCALAR Not implemented. (Win32, VMS) @@ -1299,7 +1364,12 @@ Available only on Windows NT (not on Windows 95). (Win32) =item fork -Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>, VOS, VM/ESA) +Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VOS, VM/ESA) + +Emulated using multiple interpreters. See L<perlfork>. (Win32) + +Does not automatically flush output handles on some platforms. +(SunOS, Solaris, HP-UX) =item getlogin @@ -1436,14 +1506,8 @@ Not implemented. (S<Mac OS>, Plan9) Globbing built-in, but only C<*> and C<?> metacharacters are supported. (S<Mac OS>) -Features depend on external perlglob.exe or perlglob.bat. May be -overridden with something like File::DosGlob, which is recommended. -(Win32) - -Globbing built-in, but only C<*> and C<?> metacharacters are supported. -Globbing relies on operating system calls, which may return filenames -in any order. As most filesystems are case-insensitive, even "sorted" -filenames will not be in case-sensitive order. (S<RISC OS>) +This operator is implemented via the File::Glob extension on most +platforms. See L<File::Glob> for portability information. =item ioctl FILEHANDLE,FUNCTION,SCALAR @@ -1459,9 +1523,12 @@ Available only for socket handles. (S<RISC OS>) Not implemented, hence not useful for taint checking. (S<Mac OS>, S<RISC OS>) -C<kill($sig, $pid)> makes the process exit immediately with exit -status $sig. As in Unix, if $sig is 0 and the specified process exists, -it returns true without actually terminating it. (Win32) +C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send +a signal to the identified process like it does on Unix platforms. +Instead C<kill($sig, $pid)> terminates the process identified by $pid, +and makes it exit immediately with exit status $sig. As in Unix, if +$sig is 0 and the specified process exists, it returns true without +actually terminating it. (Win32) =item link OLDFILE,NEWFILE @@ -1481,7 +1548,7 @@ under NTFS only. Not implemented. (VMS, S<RISC OS>) -Return values may be bogus. (Win32) +Return values (especially for device and inode) may be bogus. (Win32) =item msgctl ID,CMD,ARG @@ -1502,6 +1569,9 @@ The C<|> variants are supported only if ToolServer is installed. open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>) +Opening a process does not automatically flush output handles on some +platforms. (SunOS, Solaris, HP-UX) + =item pipe READHANDLE,WRITEHANDLE Not implemented. (S<Mac OS>) @@ -1520,6 +1590,8 @@ Only implemented on sockets. (Win32) Only reliable on sockets. (S<RISC OS>) +Note that the C<socket FILEHANDLE> form is generally portable. + =item semctl ID,SEMNUM,CMD,ARG =item semget KEY,NSEMS,FLAGS @@ -1601,7 +1673,10 @@ As an optimization, may not call the command shell specified in C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external process and immediately returns its process designator, without waiting for it to terminate. Return value may be used subsequently -in C<wait> or C<waitpid>. (Win32) +in C<wait> or C<waitpid>. Failure to spawn() a subprocess is indicated +by setting $? to "255 << 8". C<$?> is set in a way compatible with +Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8", +as described in the documentation). (Win32) There is no shell to process metacharacters, and the native standard is to pass a command line terminated by "\n" "\r" or "\0" to the spawned @@ -1618,13 +1693,17 @@ Far from being POSIX compliant. Because there may be no underlying first token in its argument string. Handles basic redirection ("<" or ">") on its own behalf. (MiNT) +Does not automatically flush output handles on some platforms. +(SunOS, Solaris, HP-UX) + =item times Only the first entry returned is nonzero. (S<Mac OS>) -"cumulative" times will be bogus. On anything other than Windows NT, -"system" time will be bogus, and "user" time is actually the time -returned by the clock() function in the C runtime library. (Win32) +"cumulative" times will be bogus. On anything other than Windows NT +or Windows 2000, "system" time will be bogus, and "user" time is +actually the time returned by the clock() function in the C runtime +library. (Win32) Not useful. (S<RISC OS>) @@ -1677,6 +1756,11 @@ Not useful. (S<RISC OS>) =over 4 +=item v1.47, 22 March 2000 + +Various cleanups from Tom Christiansen, including migration of +long platform listings from L<perl>. + =item v1.46, 12 February 2000 Updates for VOS and MPE/iX. (Peter Prymmer) Other small changes. @@ -1752,6 +1836,158 @@ First public release with perl5.005. =back +=head1 Supported Platforms + +As of early March 2000 (the Perl release 5.6.0), the following +platforms are able to build Perl from the standard source code +distribution available at http://www.perl.com/CPAN/src/index.html + + AIX + DOS DJGPP 1) + EPOC + FreeBSD + HP-UX + IRIX + Linux + LynxOS + MachTen + MPE/iX + NetBSD + OpenBSD + OS/2 + QNX + Rhapsody/Darwin 2) + SCO SV + SINIX + Solaris + SVR4 + Tru64 UNIX 3) + UNICOS + UNICOS/mk + Unixware + VMS + VOS + Windows 3.1 1) + Windows 95 1) 4) + Windows 98 1) 4) + Windows NT 1) 4) + + 1) in DOS mode either the DOS or OS/2 ports can be used + 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X + 3) formerly known as Digital UNIX and before that DEC OSF/1 + 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++ + +The following platforms worked for the previous major release +(5.005_03 being the latest maintenance release of that, as of early +March 2000), but be did not manage to test these in time for the 5.6.0 +release of Perl. There is a very good chance that these will work +just fine with 5.6.0. + + A/UX + BeOS + BSD/OS + DG/UX + DYNIX/ptx + DomainOS + Hurd + NextSTEP + OpenSTEP + PowerMAX + SCO ODT/OSR + SunOS + Ultrix + +The following platform worked for the previous major release (5.005_03 +being the latest maintenance release of that, as of early March 2000). +However, standardization on UTF-8 as the internal string representation +in 5.6.0 has introduced incompatibilities in this EBCDIC platform. +Support for this platform may be enabled in a future release: + + OS390 1) + + 1) Previously known as MVS, or OpenEdition MVS. + +Strongly related to the OS390 platform by also being EBCDIC-based +mainframe platforms are the following platforms: + + BS2000 + VM/ESA + +These are also not expected to work under 5.6.0 for the same reasons +as OS390. Contact the mailing list perl-mvs@perl.org for more details. + +MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source +does work with 5.6.0, but additional MacOS specific source code is needed +for a complete port. Contact the mailing list macperl-porters@macperl.org +for more information. + +The following platforms have been known to build Perl from source in +the past, but we haven't been able to verify their status for the +current release, either because the hardware/software platforms are +rare or because we don't have an active champion on these +platforms--or both: + + 3b1 + AmigaOS + ConvexOS + CX/UX + DC/OSx + DDE SMES + DOS EMX + Dynix + EP/IX + ESIX + FPS + GENIX + Greenhills + ISC + MachTen 68k + MiNT + MPC + NEWS-OS + Opus + Plan 9 + PowerUX + RISC/os + Stellar + SVR2 + TI1500 + TitanOS + Unisys Dynix + Unixware + +Support for the following platform is planned for a future Perl release: + + Netware + +The following platforms have their own source code distributions and +binaries available via http://www.perl.com/CPAN/ports/index.html: + + Perl release + + AS/400 5.003 + Netware 5.003_07 + Tandem Guardian 5.004 + +The following platforms have only binaries available via +http://www.perl.com/CPAN/ports/index.html : + + Perl release + + Acorn RISCOS 5.005_02 + AOS 5.002 + LynxOS 5.004_02 + +Although we do suggest that you always build your own Perl from +the source code, both for maximal configurability and for security, +in case you are in a hurry you can check +http://www.perl.com/CPAN/ports/index.html for binary distributions. + +=head1 SEE ALSO + +L<perlamiga>, L<perlcygwin>, L<perldos>, L<perlhpux>, L<perlos2>, +L<perlos390>, L<perlwin32>, L<perlvms>, and L<Win32>. + =head1 AUTHORS / CONTRIBUTORS Abigail <abigail@fnx.com>, @@ -1792,4 +2028,4 @@ This document is maintained by Chris Nandor =head1 VERSION -Version 1.46, last modified 12 February 2000 +Version 1.47, last modified 22 March 2000 diff --git a/pod/perlre.pod b/pod/perlre.pod index 09bee37161..2db4139c30 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -662,7 +662,8 @@ which uses C<< (?>...) >> matches exactly when the one above does (verifying this yourself would be a productive exercise), but finishes in a fourth the time when used on a similar string with 1000000 C<a>s. Be aware, however, that this pattern currently triggers a warning message under -B<-w> saying it C<"matches the null string many times">): +the C<use warnings> pragma or B<-w> switch saying it +C<"matches the null string many times">): On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable effect may be achieved by negative look-ahead, as in C<[^()]+ (?! [^()] )>. @@ -672,7 +673,7 @@ The "grab all you can, and do not give anything back" semantic is desirable in many situations where on the first sight a simple C<()*> looks like the correct solution. Suppose we parse text with comments being delimited by C<#> followed by some optional (horizontal) whitespace. Contrary to -its appearence, C<#[ \t]*> I<is not> the correct subexpression to match +its appearance, C<#[ \t]*> I<is not> the correct subexpression to match the comment delimiter, because it may "give up" some whitespace if the remainder of the pattern can be made to match that way. The correct answer is either one of these: diff --git a/pod/perlref.pod b/pod/perlref.pod index 274f43d029..2727e95ae9 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -528,7 +528,8 @@ makes it more than a bareword: $array{ +shift } $array{ shift @_ } -The B<-w> switch will warn you if it interprets a reserved word as a string. +The C<use warnings> pragma or the B<-w> switch will warn you if it +interprets a reserved word as a string. But it will no longer warn you about using lowercase words, because the string is effectively quoted. diff --git a/pod/perlrequick.pod b/pod/perlrequick.pod new file mode 100644 index 0000000000..d151e26a0c --- /dev/null +++ b/pod/perlrequick.pod @@ -0,0 +1,473 @@ +=head1 NAME + +perlrequick - Perl regular expressions quick start + +=head1 DESCRIPTION + +This page covers the very basics of understanding, creating and +using regular expressions ('regexps') in Perl. + +=head1 The Guide + +=head2 Simple word matching + +The simplest regexp is simply a word, or more generally, a string of +characters. A regexp consisting of a word matches any string that +contains that word: + + "Hello World" =~ /World/; # matches + +In this statement, C<World> is a regexp and the C<//> enclosing +C</World/> tells perl to search a string for a match. The operator +C<=~> associates the string with the regexp match and produces a true +value if the regexp matched, or false if the regexp did not match. In +our case, C<World> matches the second word in C<"Hello World">, so the +expression is true. This idea has several variations. + +Expressions like this are useful in conditionals: + + print "It matches\n" if "Hello World" =~ /World/; + +The sense of the match can be reversed by using C<!~> operator: + + print "It doesn't match\n" if "Hello World" !~ /World/; + +The literal string in the regexp can be replaced by a variable: + + $greeting = "World"; + print "It matches\n" if "Hello World" =~ /$greeting/; + +If you're matching against C<$_>, the C<$_ =~> part can be omitted: + + $_ = "Hello World"; + print "It matches\n" if /World/; + +Finally, the C<//> default delimiters for a match can be changed to +arbitrary delimiters by putting an C<'m'> out front: + + "Hello World" =~ m!World!; # matches, delimited by '!' + "Hello World" =~ m{World}; # matches, note the matching '{}' + "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin', + # '/' becomes an ordinary char + +Regexps must match a part of the string I<exactly> in order for the +statement to be true: + + "Hello World" =~ /world/; # doesn't match, case sensitive + "Hello World" =~ /o W/; # matches, ' ' is an ordinary char + "Hello World" =~ /World /; # doesn't match, no ' ' at end + +perl will always match at the earliest possible point in the string: + + "Hello World" =~ /o/; # matches 'o' in 'Hello' + "That hat is red" =~ /hat/; # matches 'hat' in 'That' + +Not all characters can be used 'as is' in a match. Some characters, +called B<metacharacters>, are reserved for use in regexp notation. +The metacharacters are + + {}[]()^$.|*+?\ + +A metacharacter can be matched by putting a backslash before it: + + "2+2=4" =~ /2+2/; # doesn't match, + is a metacharacter + "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary + + 'C:\WIN32' =~ /C:\\WIN/; # matches + "/usr/bin/perl" =~ /\/usr\/local\/bin\/perl/; # matches + +In the last regexp, the forward slash C<'/'> is also backslashed, +because it is used to delimit the regexp. + +Non-printable ASCII characters are represented by B<escape sequences>. +Common examples are C<\t> for a tab, C<\n> for a newline, and C<\r> +for a carriage return. Arbitrary bytes are represented by octal +escape sequences, e.g., C<\033>, or hexadecimal escape sequences, +e.g., C<\x1B>: + + "1000\t2000" =~ m(0\t2) # matches + "cat" =~ /\143\x61\x74/ # matches, but a weird way to spell cat + +Regexps are treated mostly as double quoted strings, so variable +substitution works: + + $foo = 'house'; + 'cathouse' =~ /cat$foo/; # matches + 'housecat' =~ /${foo}cat/; # matches + +With all of the regexps above, if the regexp matched anywhere in the +string, it was considered a match. To specify I<where> it should +match, we would use the B<anchor> metacharacters C<^> and C<$>. The +anchor C<^> means match at the beginning of the string and the anchor +C<$> means match at the end of the string, or before a newline at the +end of the string. Some examples: + + "housekeeper" =~ /keeper/; # matches + "housekeeper" =~ /^keeper/; # doesn't match + "housekeeper" =~ /keeper$/; # matches + "housekeeper\n" =~ /keeper$/; # matches + +=head2 Using character classes + +A B<character class> allows a set of possible characters, rather than +just a single character, to match at a particular point in a regexp. +Character classes are denoted by brackets C<[...]>, with the set of +characters to be possibly matched inside. Here are some examples: + + /cat/; # matches 'cat' + /[bcr]at/; # matches 'bat, 'cat', or 'rat' + "abc" =~ /[cab]/; # matches 'a' + +In the last statement, even though C<'c'> is the first character in +the class, the earliest point at which the regexp can match is C<'a'>. + + /[yY][eE][sS]/; # match 'yes' in a case-insensitive way + # 'yes', 'Yes', 'YES', etc. + /yes/i; # also match 'yes' in a case-insensitive way + +The last example shows a match with an C<'i'> B<modifier>, which makes +the match case-insensitive. + +Character classes also have ordinary and special characters, but the +sets of ordinary and special characters inside a character class are +different than those outside a character class. The special +characters for a character class are C<-]\^$> and are matched using an +escape: + + /[\]c]def/; # matches ']def' or 'cdef' + $x = 'bcr'; + /[$x]at/; # matches 'bat, 'cat', or 'rat' + /[\$x]at/; # matches '$at' or 'xat' + /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat' + +The special character C<'-'> acts as a range operator within character +classes, so that the unwieldy C<[0123456789]> and C<[abc...xyz]> +become the svelte C<[0-9]> and C<[a-z]>: + + /item[0-9]/; # matches 'item0' or ... or 'item9' + /[0-9a-fA-F]/; # matches a hexadecimal digit + +If C<'-'> is the first or last character in a character class, it is +treated as an ordinary character. + +The special character C<^> in the first position of a character class +denotes a B<negated character class>, which matches any character but +those in the bracket. Both C<[...]> and C<[^...]> must match a +character, or the match fails. Then + + /[^a]at/; # doesn't match 'aat' or 'at', but matches + # all other 'bat', 'cat, '0at', '%at', etc. + /[^0-9]/; # matches a non-numeric character + /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary + +Perl has several abbreviations for common character classes: + +=over 4 + +=item * +\d is a digit and represents [0-9] + +=item * +\s is a whitespace character and represents [\ \t\r\n\f] + +=item * +\w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_] + +=item * +\D is a negated \d; it represents any character but a digit [^0-9] + +=item * +\S is a negated \s; it represents any non-whitespace character [^\s] + +=item * +\W is a negated \w; it represents any non-word character [^\w] + +=item * +The period '.' matches any character but "\n" + +=back + +The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside +of character classes. Here are some in use: + + /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format + /[\d\s]/; # matches any digit or whitespace character + /\w\W\w/; # matches a word char, followed by a + # non-word char, followed by a word char + /..rt/; # matches any two chars, followed by 'rt' + /end\./; # matches 'end.' + /end[.]/; # same thing, matches 'end.' + +The S<B<word anchor> > C<\b> matches a boundary between a word +character and a non-word character C<\w\W> or C<\W\w>: + + $x = "Housecat catenates house and cat"; + $x =~ /\bcat/; # matches cat in 'catenates' + $x =~ /cat\b/; # matches cat in 'housecat' + $x =~ /\bcat\b/; # matches 'cat' at end of string + +In the last example, the end of the string is considered a word +boundary. + +=head2 Matching this or that + +We can match match different character strings with the B<alternation> +metacharacter C<'|'>. To match C<dog> or C<cat>, we form the regexp +C<dog|cat>. As before, perl will try to match the regexp at the +earliest possible point in the string. At each character position, +perl will first try to match the the first alternative, C<dog>. If +C<dog> doesn't match, perl will then try the next alternative, C<cat>. +If C<cat> doesn't match either, then the match fails and perl moves to +the next position in the string. Some examples: + + "cats and dogs" =~ /cat|dog|bird/; # matches "cat" + "cats and dogs" =~ /dog|cat|bird/; # matches "cat" + +Even though C<dog> is the first alternative in the second regexp, +C<cat> is able to match earlier in the string. + + "cats" =~ /c|ca|cat|cats/; # matches "c" + "cats" =~ /cats|cat|ca|c/; # matches "cats" + +At a given character position, the first alternative that allows the +regexp match to succeed wil be the one that matches. Here, all the +alternatives match at the first string position, so th first matches. + +=head2 Grouping things and hierarchical matching + +The B<grouping> metacharacters C<()> allow a part of a regexp to be +treated as a single unit. Parts of a regexp are grouped by enclosing +them in parentheses. The regexp C<house(cat|keeper)> means match +C<house> followed by either C<cat> or C<keeper>. Some more examples +are + + /(a|b)b/; # matches 'ab' or 'bb' + /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere + + /house(cat|)/; # matches either 'housecat' or 'house' + /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or + # 'house'. Note groups can be nested. + + "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d', + # because '20\d\d' can't match + +=head2 Extracting matches + +The grouping metacharacters C<()> also allow the extraction of the +parts of a string that matched. For each grouping, the part that +matched inside goes into the special variables C<$1>, C<$2>, etc. +They can be used just as ordinary variables: + + # extract hours, minutes, seconds + $time =~ /(\d\d):(\d\d):(\d\d)/; # match hh:mm:ss format + $hours = $1; + $minutes = $2; + $seconds = $3; + +In list context, a match C</regexp/ with groupings will return the +list of matched values C<($1,$2,...)>. So we could rewrite it as + + ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/); + +If the groupings in a regexp are nested, C<$1> gets the group with the +leftmost opening parenthesis, C<$2> the next opening parenthesis, +etc. For example, here is a complex regexp and the matching variables +indicated below it: + + /(ab(cd|ef)((gi)|j))/; + 1 2 34 + +Associated with the matching variables C<$1>, C<$2>, ... are +the B<backreferences> C<\1>, C<\2>, ... Backreferences are +matching variables that can be used I<inside> a regexp: + + /(\w\w\w)\s\1/; # find sequences like 'the the' in string + +C<$1>, C<$2>, ... should only be used outside of a regexp, and C<\1>, +C<\2>, ... only inside a regexp. + +=head2 Matching repetitions + +The B<quantifier> metacharacters C<?>, C<*>, C<+>, and C<{}> allow us +to determine the number of repeats of a portion of a regexp we +consider to be a match. Quantifiers are put immediately after the +character, character class, or grouping that we want to specify. They +have the following meanings: + +=over 4 + +=item * C<a?> = match 'a' 1 or 0 times + +=item * C<a*> = match 'a' 0 or more times, i.e., any number of times + +=item * C<a+> = match 'a' 1 or more times, i.e., at least once + +=item * C<a{n,m}> = match at least C<n> times, but not more than C<m> +times. + +=item * C<a{n,}> = match at least C<n> or more times + +=item * C<a{n}> = match exactly C<n> times + +=back + +Here are some examples: + + /[a-z]+\s+\d*/; # match a lowercase word, at least some space, and + # any number of digits + /(\w+)\s+\1/; # match doubled words of arbitrary length + $year =~ /\d{2,4}/; # make sure year is at least 2 but not more + # than 4 digits + $year =~ /\d{4}|\d{2}/; # better match; throw out 3 digit dates + +These quantifiers will try to match as much of the string as possible, +while still allowing the regexp to match. So we have + + $x =~ /^(.*)(at)(.*)$/; # matches, + # $1 = 'the cat in the h' + # $2 = 'at' + # $3 = '' (0 matches) + +The first quantifier C<.*> grabs as much of the string as possible +while still having the regexp match. The second quantifier C<.*> has +no string left to it, so it matches 0 times. + +=head2 More matching + +There are a few more things you might want to know about matching +operators. In the code + + $pattern = 'Seuss'; + while (<>) { + print if /$pattern/; + } + +perl has to re-evaluate C<$pattern> each time through the loop. If +C<$pattern> won't be changing, use the C<//o> modifier, to only +perform variable substitutions once. If you don't want any +substitutions at all, use the special delimiter C<m''>: + + $pattern = 'Seuss'; + m'$pattern'; # matches '$pattern', not 'Seuss' + +The global modifier C<//g> allows the matching operator to match +within a string as many times as possible. In scalar context, +successive matches against a string will have C<//g> jump from match +to match, keeping track of position in the string as it goes along. +You can get or set the position with the C<pos()> function. +For example, + + $x = "cat dog house"; # 3 words + while ($x =~ /(\w+)/g) { + print "Word is $1, ends at position ", pos $x, "\n"; + } + +prints + + Word is cat, ends at position 3 + Word is dog, ends at position 7 + Word is house, ends at position 13 + +A failed match or changing the target string resets the position. If +you don't want the position reset after failure to match, add the +C<//c>, as in C</regexp/gc>. + +In list context, C<//g> returns a list of matched groupings, or if +there are no groupings, a list of matches to the whole regexp. So + + @words = ($x =~ /(\w+)/g); # matches, + # $word[0] = 'cat' + # $word[1] = 'dog' + # $word[2] = 'house' + +=head2 Search and replace + +Search and replace is perform using C<s/regexp/replacement/modifiers>. +The C<replacement> is a Perl double quoted string that replaces in the +string whatever is matched with the C<regexp>. The operator C<=~> is +also used here to associate a string with C<s///>. If matching +against C<$_>, the S<C<$_ =~> > can be dropped. If there is a match, +C<s///> returns the number of substitutions made, otherwise it returns +false. Here are a few examples: + + $x = "Time to feed the cat!"; + $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!" + $y = "'quoted words'"; + $y =~ s/^'(.*)'$/$1/; # strip single quotes, + # $y contains "quoted words" + +With the C<s///> operator, the matched variables C<$1>, C<$2>, etc. +are immediately available for use in the replacement expression. With +the global modifier, C<s///g> will search and replace all occurrences +of the regexp in the string: + + $x = "I batted 4 for 4"; + $x =~ s/4/four/; # $x contains "I batted four for 4" + $x = "I batted 4 for 4"; + $x =~ s/4/four/g; # $x contains "I batted four for four" + +The evaluation modifier C<s///e> wraps an C<eval{...}> around the +replacement string and the evaluated result is substituted for the +matched substring. This counts character frequencies in a line: + + $x = "the cat"; + $x =~ s/(.)/$chars{$1}++;$1/eg; # final $1 replaces char with itself + print "frequency of '$_' is $chars{$_}\n" + foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars); + +This prints + + frequency of 't' is 2 + frequency of 'e' is 1 + frequency of ' ' is 1 + frequency of 'h' is 1 + frequency of 'a' is 1 + frequency of 'c' is 1 + +C<s///> can use other delimiters, such as C<s!!!> and C<s{}{}>, and +even C<s{}//>. If single quotes are used C<s'''>, then the regexp and +replacement are treated as single quoted strings. + +=head2 The split operator + +C<split /regexp/, string> splits C<string> into a list of substrings +and returns that list. The regexp determines the character sequence +that C<string> is split with respect to. For example, to split a +string into words, use + + $x = "Calvin and Hobbes"; + @words = split /\s+/, $x; # $word[0] = 'Calvin' + # $word[1] = 'and' + # $word[2] = 'Hobbes' + +If the empty regexp C<//> is used, the string is split into individual +characters. If the regexp has groupings, then list produced contains +the matched substrings from the groupings as well: + + $x = "/usr/bin"; + @parts = split m!(/)!, $x; # $parts[0] = '' + # $parts[1] = '/' + # $parts[2] = 'usr' + # $parts[3] = '/' + # $parts[4] = 'bin' + +Since the first character of $x matched the regexp, C<split> prepended +an empty initial element to the list. + +=head1 BUGS + +None. + +=head1 SEE ALSO + +This is just a quick start guide. For a more in-depth tutorial on +regexps, see L<perlretut> and for the reference page, see L<perlre>. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 2000 Mark Kvale +All rights reserved. + +This document may be distributed under the same terms as Perl itself. + +=cut + diff --git a/pod/perlretut.pod b/pod/perlretut.pod new file mode 100644 index 0000000000..5ff4298012 --- /dev/null +++ b/pod/perlretut.pod @@ -0,0 +1,2382 @@ +=head1 NAME + +perlretut - Perl regular expressions tutorial + +=head1 DESCRIPTION + +This page provides a basic tutorial on understanding, creating and +using regular expressions in Perl. It serves as a complement to the +reference page on regular expressions L<perlre>. Regular expressions +are an integral part of the C<m//>, C<s///>, C<qr//> and C<split> +operators and so this tutorial also overlaps with +L<perlop/"Regexp Quote-Like Operators"> and L<perlfunc/split>. + +Perl is widely renowned for excellence in text processing, and regular +expressions are one of the big factors behind this fame. Perl regular +expressions display an efficiency and flexibility unknown in most +other computer languages. Mastering even the basics of regular +expressions will allow you to manipulate text with surprising ease. + +What is a regular expression? A regular expression is simply a string +that describes a pattern. Patterns are in common use these days; +examples are the patterns typed into a search engine to find web pages +and the patterns used to list files in a directory, e.g., C<ls *.txt> +or C<dir *.*>. In Perl, the patterns described by regular expressions +are used to search strings, extract desired parts of strings, and to +do search and replace operations. + +Regular expressions have the undeserved reputation of being abstract +and difficult to understand. Regular expressions are constructed using +simple concepts like conditionals and loops and are no more difficult +to understand than the corresponding C<if> conditionals and C<while> +loops in the Perl language itself. In fact, the main challenge in +learning regular expressions is just getting used to the terse +notation used to express these concepts. + +This tutorial flattens the learning curve by discussing regular +expression concepts, along with their notation, one at a time and with +many examples. The first part of the tutorial will progress from the +simplest word searches to the basic regular expression concepts. If +you master the first part, you will have all the tools needed to solve +about 98% of your needs. The second part of the tutorial is for those +comfortable with the basics and hungry for more power tools. It +discusses the more advanced regular expression operators and +introduces the latest cutting edge innovations in 5.6.0. + +A note: to save time, 'regular expression' is often abbreviated as +regexp or regex. Regexp is a more natural abbreviation than regex, but +is harder to pronounce. The Perl pod documentation is evenly split on +regexp vs regex; in Perl, there is more than one way to abbreviate it. +We'll use regexp in this tutorial. + +=head1 Part 1: The basics + +=head2 Simple word matching + +The simplest regexp is simply a word, or more generally, a string of +characters. A regexp consisting of a word matches any string that +contains that word: + + "Hello World" =~ /World/; # matches + +What is this perl statement all about? C<"Hello World"> is a simple +double quoted string. C<World> is the regular expression and the +C<//> enclosing C</World/> tells perl to search a string for a match. +The operator C<=~> associates the string with the regexp match and +produces a true value if the regexp matched, or false if the regexp +did not match. In our case, C<World> matches the second word in +C<"Hello World">, so the expression is true. Expressions like this +are useful in conditionals: + + if ("Hello World" =~ /World/) { + print "It matches\n"; + } + else { + print "It doesn't match\n"; + } + +There are useful variations on this theme. The sense of the match can +be reversed by using C<!~> operator: + + if ("Hello World" !~ /World/) { + print "It doesn't match\n"; + } + else { + print "It matches\n"; + } + +The literal string in the regexp can be replaced by a variable: + + $greeting = "World"; + if ("Hello World" =~ /$greeting/) { + print "It matches\n"; + } + else { + print "It doesn't match\n"; + } + +If you're matching against the special default variable C<$_>, the +C<$_ =~> part can be omitted: + + $_ = "Hello World"; + if (/World/) { + print "It matches\n"; + } + else { + print "It doesn't match\n"; + } + +And finally, the C<//> default delimiters for a match can be changed +to arbitrary delimiters by putting an C<'m'> out front: + + "Hello World" =~ m!World!; # matches, delimited by '!' + "Hello World" =~ m{World}; # matches, note the matching '{}' + "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin', + # '/' becomes an ordinary char + +C</World/>, C<m!World!>, and C<m{World}> all represent the +same thing. When, e.g., C<""> is used as a delimiter, the forward +slash C<'/'> becomes an ordinary character and can be used in a regexp +without trouble. + +Let's consider how different regexps would match C<"Hello World">: + + "Hello World" =~ /world/; # doesn't match + "Hello World" =~ /o W/; # matches + "Hello World" =~ /oW/; # doesn't match + "Hello World" =~ /World /; # doesn't match + +The first regexp C<world> doesn't match because regexps are +case-sensitive. The second regexp matches because the substring +S<C<'o W'> > occurs in the string S<C<"Hello World"> >. The space +character ' ' is treated like any other character in a regexp and is +needed to match in this case. The lack of a space character is the +reason the third regexp C<'oW'> doesn't match. The fourth regexp +C<'World '> doesn't match because there is a space at the end of the +regexp, but not at the end of the string. The lesson here is that +regexps must match a part of the string I<exactly> in order for the +statement to be true. + +If a regexp matches in more than one place in the string, perl will +always match at the earliest possible point in the string: + + "Hello World" =~ /o/; # matches 'o' in 'Hello' + "That hat is red" =~ /hat/; # matches 'hat' in 'That' + +With respect to character matching, there are a few more points you +need to know about. First of all, not all characters can be used 'as +is' in a match. Some characters, called B<metacharacters>, are reserved +for use in regexp notation. The metacharacters are + + {}[]()^$.|*+?\ + +The significance of each of these will be explained +in the rest of the tutorial, but for now, it is important only to know +that a metacharacter can be matched by putting a backslash before it: + + "2+2=4" =~ /2+2/; # doesn't match, + is a metacharacter + "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary + + "The interval is [0,1)." =~ /[0,1)./ # is a syntax error! + "The interval is [0,1)." =~ /\[0,1\)\./ # matches + "/usr/bin/perl" =~ /\/usr\/local\/bin\/perl/; # matches + +In the last regexp, the forward slash C<'/'> is also backslashed, +because it is used to delimit the regexp. This can lead to LTS +(leaning toothpick syndrome), however, and it is often more readable +to change delimiters. + + +The backslash character C<'\'> is a metacharacter itself and needs to +be backslashed: + + 'C:\WIN32' =~ /C:\\WIN/; # matches + +In addition to the metacharacters, there are some ASCII characters +which don't have printable character equivalents and are instead +represented by B<escape sequences>. Common examples are C<\t> for a +tab, C<\n> for a newline, C<\r> for a carriage return and C<\a> for a +bell. If your string is better thought of as a sequence of arbitrary +bytes, the octal escape sequence, e.g., C<\033>, or hexadecimal escape +sequence, e.g., C<\x1B> may be a more natural representation for your +bytes. Here are some examples of escapes: + + "1000\t2000" =~ m(0\t2) # matches + "1000\n2000" =~ /0\n20/ # matches + "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne "\000" + "cat" =~ /\143\x61\x74/ # matches, but a weird way to spell cat + +If you've been around Perl a while, all this talk of escape sequences +may seem familiar. Similar escape sequences are used in double-quoted +strings and in fact the regexps in Perl are mostly treated as +double-quoted strings. This means that variables can be used in +regexps as well. Just like double-quoted strings, the values of the +variables in the regexp will be substituted in before the regexp is +evaluated for matching purposes. So we have: + + $foo = 'house'; + 'housecat' =~ /$foo/; # matches + 'cathouse' =~ /cat$foo/; # matches + 'housecat' =~ /${foo}cat/; # matches + +So far, so good. With the knowledge above you can already perform +searches with just about any literal string regexp you can dream up. +Here is a I<very simple> emulation of the Unix grep program: + + % cat > simple_grep + #!/usr/bin/perl + $regexp = shift; + while (<>) { + print if /$regexp/; + } + ^D + + % chmod +x simple_grep + + % simple_grep abba /usr/dict/words + Babbage + cabbage + cabbages + sabbath + Sabbathize + Sabbathizes + sabbatical + scabbard + scabbards + +This program is easy to understand. C<#!/usr/bin/perl> is the standard +way to invoke a perl program from the shell. +S<C<$regexp = shift;> > saves the first command line argument as the +regexp to be used, leaving the rest of the command line arguments to +be treated as files. S<C<< while (<>) >> > loops over all the lines in +all the files. For each line, S<C<print if /$regexp/;> > prints the +line if the regexp matches the line. In this line, both C<print> and +C</$regexp/> use the default variable C<$_> implicitly. + +With all of the regexps above, if the regexp matched anywhere in the +string, it was considered a match. Sometimes, however, we'd like to +specify I<where> in the string the regexp should try to match. To do +this, we would use the B<anchor> metacharacters C<^> and C<$>. The +anchor C<^> means match at the beginning of the string and the anchor +C<$> means match at the end of the string, or before a newline at the +end of the string. Here is how they are used: + + "housekeeper" =~ /keeper/; # matches + "housekeeper" =~ /^keeper/; # doesn't match + "housekeeper" =~ /keeper$/; # matches + "housekeeper\n" =~ /keeper$/; # matches + +The second regexp doesn't match because C<^> constrains C<keeper> to +match only at the beginning of the string, but C<"housekeeper"> has +keeper starting in the middle. The third regexp does match, since the +C<$> constrains C<keeper> to match only at the end of the string. + +When both C<^> and C<$> are used at the same time, the regexp has to +match both the beginning and the end of the string, i.e., the regexp +matches the whole string. Consider + + "keeper" =~ /^keep$/; # doesn't match + "keeper" =~ /^keeper$/; # matches + "" =~ /^$/; # ^$ matches an empty string + +The first regexp doesn't match because the string has more to it than +C<keep>. Since the second regexp is exactly the string, it +matches. Using both C<^> and C<$> in a regexp forces the complete +string to match, so it gives you complete control over which strings +match and which don't. Suppose you are looking for a fellow named +bert, off in a string by himself: + + "dogbert" =~ /bert/; # matches, but not what you want + + "dilbert" =~ /^bert/; # doesn't match, but .. + "bertram" =~ /^bert/; # matches, so still not good enough + + "bertram" =~ /^bert$/; # doesn't match, good + "dilbert" =~ /^bert$/; # doesn't match, good + "bert" =~ /^bert$/; # matches, perfect + +Of course, in the case of a literal string, one could just as easily +use the string equivalence S<C<$string eq 'bert'> > and it would be +more efficient. The C<^...$> regexp really becomes useful when we +add in the more powerful regexp tools below. + +=head2 Using character classes + +Although one can already do quite a lot with the literal string +regexps above, we've only scratched the surface of regular expression +technology. In this and subsequent sections we will introduce regexp +concepts (and associated metacharacter notations) that will allow a +regexp to not just represent a single character sequence, but a I<whole +class> of them. + +One such concept is that of a B<character class>. A character class +allows a set of possible characters, rather than just a single +character, to match at a particular point in a regexp. Character +classes are denoted by brackets C<[...]>, with the set of characters +to be possibly matched inside. Here are some examples: + + /cat/; # matches 'cat' + /[bcr]at/; # matches 'bat, 'cat', or 'rat' + /item[0123456789]/; # matches 'item0' or ... or 'item9' + "abc" =~ /[cab]/; # matches 'a' + +In the last statement, even though C<'c'> is the first character in +the class, C<'a'> matches because the first character position in the +string is the earliest point at which the regexp can match. + + /[yY][eE][sS]/; # match 'yes' in a case-insensitive way + # 'yes', 'Yes', 'YES', etc. + +This regexp displays a common task: perform a a case-insensitive +match. Perl provides away of avoiding all those brackets by simply +appending an C<'i'> to the end of the match. Then C</[yY][eE][sS]/;> +can be rewritten as C</yes/i;>. The C<'i'> stands for +case-insensitive and is an example of a B<modifier> of the matching +operation. We will meet other modifiers later in the tutorial. + +We saw in the section above that there were ordinary characters, which +represented themselves, and special characters, which needed a +backslash C<\> to represent themselves. The same is true in a +character class, but the sets of ordinary and special characters +inside a character class are different than those outside a character +class. The special characters for a character class are C<-]\^$>. C<]> +is special because it denotes the end of a character class. C<$> is +special because it denotes a scalar variable. C<\> is special because +it is used in escape sequences, just like above. Here is how the +special characters C<]$\> are handled: + + /[\]c]def/; # matches ']def' or 'cdef' + $x = 'bcr'; + /[$x]at/; # matches 'bat', 'cat', or 'rat' + /[\$x]at/; # matches '$at' or 'xat' + /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat' + +The last two are a little tricky. in C<[\$x]>, the backslash protects +the dollar sign, so the character class has two members C<$> and C<x>. +In C<[\\$x]>, the backslash is protected, so C<$x> is treated as a +variable and substituted in double quote fashion. + +The special character C<'-'> acts as a range operator within character +classes, so that a contiguous set of characters can be written as a +range. With ranges, the unwieldy C<[0123456789]> and C<[abc...xyz]> +become the svelte C<[0-9]> and C<[a-z]>. Some examples are + + /item[0-9]/; # matches 'item0' or ... or 'item9' + /[0-9bx-z]aa/; # matches '0aa', ..., '9aa', + # 'baa', 'xaa', 'yaa', or 'zaa' + /[0-9a-fA-F]/; # matches a hexadecimal digit + /[0-9a-zA-Z_]/; # matches an alphanumeric character, + # like those in a perl variable name + +If C<'-'> is the first or last character in a character class, it is +treated as an ordinary character; C<[-ab]>, C<[ab-]> and C<[a\-b]> are +all equivalent. + +The special character C<^> in the first position of a character class +denotes a B<negated character class>, which matches any character but +those in the brackets. Both C<[...]> and C<[^...]> must match a +character, or the match fails. Then + + /[^a]at/; # doesn't match 'aat' or 'at', but matches + # all other 'bat', 'cat, '0at', '%at', etc. + /[^0-9]/; # matches a non-numeric character + /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary + +Now, even C<[0-9]> can be a bother the write multiple times, so in the +interest of saving keystrokes and making regexps more readable, Perl +has several abbreviations for common character classes: + +=over 4 + +=item * +\d is a digit and represents [0-9] + +=item * +\s is a whitespace character and represents [\ \t\r\n\f] + +=item * +\w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_] + +=item * +\D is a negated \d; it represents any character but a digit [^0-9] + +=item * +\S is a negated \s; it represents any non-whitespace character [^\s] + +=item * +\W is a negated \w; it represents any non-word character [^\w] + +=item * +The period '.' matches any character but "\n" + +=back + +The C<\d\s\w\D\S\W> abbreviations can be used both inside and outside +of character classes. Here are some in use: + + /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format + /[\d\s]/; # matches any digit or whitespace character + /\w\W\w/; # matches a word char, followed by a + # non-word char, followed by a word char + /..rt/; # matches any two chars, followed by 'rt' + /end\./; # matches 'end.' + /end[.]/; # same thing, matches 'end.' + +Because a period is a metacharacter, it needs to be escaped to match +as an ordinary period. Because, for example, C<\d> and C<\w> are sets +of characters, it is incorrect to think of C<[^\d\w]> as C<[\D\W]>; in +fact C<[^\d\w]> is the same as C<[^\w]>, which is the same as +C<[\W]>. Think DeMorgan's laws. + +An anchor useful in basic regexps is the S<B<word anchor> > +C<\b>. This matches a boundary between a word character and a non-word +character C<\w\W> or C<\W\w>: + + $x = "Housecat catenates house and cat"; + $x =~ /cat/; # matches cat in 'housecat' + $x =~ /\bcat/; # matches cat in 'catenates' + $x =~ /cat\b/; # matches cat in 'housecat' + $x =~ /\bcat\b/; # matches 'cat' at end of string + +Note in the last example, the end of the string is considered a word +boundary. + +You might wonder why C<'.'> matches everything but C<"\n"> - why not +every character? The reason is that often one is matching against +lines and would like to ignore the newline characters. For instance, +while the string C<"\n"> represents one line, we would like to think +of as empty. Then + + "" =~ /^$/; # matches + "\n" =~ /^$/; # matches, "\n" is ignored + + "" =~ /./; # doesn't match; it needs a char + "" =~ /^.$/; # doesn't match; it needs a char + "\n" =~ /^.$/; # doesn't match; it needs a char other than "\n" + "a" =~ /^.$/; # matches + "a\n" =~ /^.$/; # matches, ignores the "\n" + +This behavior is convenient, because we usually want to ignore +newlines when we count and match characters in a line. Sometimes, +however, we want to keep track of newlines. We might even want C<^> +and C<$> to anchor at the beginning and end of lines within the +string, rather than just the beginning and end of the string. Perl +allows us to choose between ignoring and paying attention to newlines +by using the C<//s> and C<//m> modifiers. C<//s> and C<//m> stand for +single line and multi-line and they determine whether a string is to +be treated as one continuous string, or as a set of lines. The two +modifiers affect two aspects of how the regexp is interpreted: 1) how +the C<'.'> character class is defined, and 2) where the anchors C<^> +and C<$> are able to match. Here are the four possible combinations: + +=over 4 + +=item * +no modifiers (//): Default behavior. C<'.'> matches any character +except C<"\n">. C<^> matches only at the beginning of the string and +C<$> matches only at the end or before a newline at the end. + +=item * +s modifier (//s): Treat string as a single long line. C<'.'> matches +any character, even C<"\n">. C<^> matches only at the beginning of +the string and C<$> matches only at the end or before a newline at the +end. + +=item * +m modifier (//m): Treat string as a set of multiple lines. C<'.'> +matches any character except C<"\n">. C<^> and C<$> are able to match +at the start or end of I<any> line within the string. + +=item * +both s and m modifiers (//sm): Treat string as a single long line, but +detect multiple lines. C<'.'> matches any character, even +C<"\n">. C<^> and C<$>, however, are able to match at the start or end +of I<any> line within the string. + +=back + +Here are examples of C<//s> and C<//m> in action: + + $x = "There once was a girl\nWho programmed in Perl\n"; + + $x =~ /^Who/; # doesn't match, "Who" not at start of string + $x =~ /^Who/s; # doesn't match, "Who" not at start of string + $x =~ /^Who/m; # matches, "Who" at start of second line + $x =~ /^Who/sm; # matches, "Who" at start of second line + + $x =~ /girl.Who/; # doesn't match, "." doesn't match "\n" + $x =~ /girl.Who/s; # matches, "." matches "\n" + $x =~ /girl.Who/m; # doesn't match, "." doesn't match "\n" + $x =~ /girl.Who/sm; # matches, "." matches "\n" + +Most of the time, the default behavior is what is want, but C<//s> and +C<//m> are occasionally very useful. If C<//m> is being used, the start +of the string can still be matched with C<\A> and the end of string +can still be matched with the anchors C<\Z> (matches both the end and +the newline before, like C<$>), and C<\z> (matches only the end): + + $x =~ /^Who/m; # matches, "Who" at start of second line + $x =~ /\AWho/m; # doesn't match, "Who" is not at start of string + + $x =~ /girl$/m; # matches, "girl" at end of first line + $x =~ /girl\Z/m; # doesn't match, "girl" is not at end of string + + $x =~ /Perl\Z/m; # matches, "Perl" is at newline before end + $x =~ /Perl\z/m; # doesn't match, "Perl" is not at end of string + +We now know how to create choices among classes of characters in a +regexp. What about choices among words or character strings? Such +choices are described in the next section. + +=head2 Matching this or that + +Sometimes we would like to our regexp to be able to match different +possible words or character strings. This is accomplished by using +the B<alternation> metacharacter C<|>. To match C<dog> or C<cat>, we +form the regexp C<dog|cat>. As before, perl will try to match the +regexp at the earliest possible point in the string. At each +character position, perl will first try to match the first +alternative, C<dog>. If C<dog> doesn't match, perl will then try the +next alternative, C<cat>. If C<cat> doesn't match either, then the +match fails and perl moves to the next position in the string. Some +examples: + + "cats and dogs" =~ /cat|dog|bird/; # matches "cat" + "cats and dogs" =~ /dog|cat|bird/; # matches "cat" + +Even though C<dog> is the first alternative in the second regexp, +C<cat> is able to match earlier in the string. + + "cats" =~ /c|ca|cat|cats/; # matches "c" + "cats" =~ /cats|cat|ca|c/; # matches "cats" + +Here, all the alternatives match at the first string position, so the +first alternative is the one that matches. If some of the +alternatives are truncations of the others, put the longest ones first +to give them a chance to match. + + "cab" =~ /a|b|c/ # matches "c" + # /a|b|c/ == /[abc]/ + +The last example points out that character classes are like +alternations of characters. At a given character position, the first +alternative that allows the regexp match to succeed wil be the one +that matches. + +=head2 Grouping things and hierarchical matching + +Alternation allows a regexp to choose among alternatives, but by +itself it unsatisfying. The reason is that each alternative is a whole +regexp, but sometime we want alternatives for just part of a +regexp. For instance, suppose we want to search for housecats or +housekeepers. The regexp C<housecat|housekeeper> fits the bill, but is +inefficient because we had to type C<house> twice. It would be nice to +have parts of the regexp be constant, like C<house>, and and some +parts have alternatives, like C<cat|keeper>. + +The B<grouping> metacharacters C<()> solve this problem. Grouping +allows parts of a regexp to be treated as a single unit. Parts of a +regexp are grouped by enclosing them in parentheses. Thus we could solve +the C<housecat|housekeeper> by forming the regexp as +C<house(cat|keeper)>. The regexp C<house(cat|keeper)> means match +C<house> followed by either C<cat> or C<keeper>. Some more examples +are + + /(a|b)b/; # matches 'ab' or 'bb' + /(ac|b)b/; # matches 'acb' or 'bb' + /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere + /(a|[bc])d/; # matches 'ad', 'bd', or 'cd' + + /house(cat|)/; # matches either 'housecat' or 'house' + /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or + # 'house'. Note groups can be nested. + + /(19|20|)\d\d/; # match years 19xx, 20xx, or the Y2K problem, xx + "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d', + # because '20\d\d' can't match + +Alternations behave the same way in groups as out of them: at a given +string position, the leftmost alternative that allows the regexp to +match is taken. So in the last example at tth first string position, +C<"20"> matches the second alternative, but there is nothing left over +to match the next two digits C<\d\d>. So perl moves on to the next +alternative, which is the null alternative and that works, since +C<"20"> is two digits. + +The process of trying one alternative, seeing if it matches, and +moving on to the next alternative if it doesn't, is called +B<backtracking>. The term 'backtracking' comes from the idea that +matching a regexp is like a walk in the woods. Successfully matching +a regexp is like arriving at a destination. There are many possible +trailheads, one for each string position, and each one is tried in +order, left to right. From each trailhead there may be many paths, +some of which get you there, and some which are dead ends. When you +walk along a trail and hit a dead end, you have to backtrack along the +trail to an earlier point to try another trail. If you hit your +destination, you stop immediately and forget about trying all the +other trails. You are persistent, and only if you have tried all the +trails from all the trailheads and not arrived at your destination, do +you declare failure. To be concrete, here is a step-by-step analysis +of what perl does when it tries to match the regexp + + "abcde" =~ /(abd|abc)(df|d|de)/; + +=over 4 + +=item 0 Start with the first letter in the string 'a'. + +=item 1 Try the first alternative in the first group 'abd'. + +=item 2 Match 'a' followed by 'b'. So far so good. + +=item 3 'd' in the regexp doesn't match 'c' in the string - a dead +end. So backtrack two characters and pick the second alternative in +the first group 'abc'. + +=item 4 Match 'a' followed by 'b' followed by 'c'. We are on a roll +and have satisfied the first group. Set $1 to 'abc'. + +=item 5 Move on to the second group and pick the first alternative +'df'. + +=item 6 Match the 'd'. + +=item 7 'f' in the regexp doesn't match 'e' in the string, so a dead +end. Backtrack one character and pick the second alternative in the +second group 'd'. + +=item 8 'd' matches. The second grouping is satisfied, so set $2 to +'d'. + +=item 9 We are at the end of the regexp, so we are done! We have +matched 'abcd' out of the string "abcde". + +=back + +There are a couple of things to note about this analysis. First, the +third alternative in the second group 'de' also allows a match, but we +stopped before we got to it - at a given character position, leftmost +wins. Second, we were able to get a match at the first character +position of the string 'a'. If there were no matches at the first +position, perl would move to the second character position 'b' and +attempt the match all over again. Only when all possible paths at all +possible character positions have been exhausted does perl give give +up and declare S<C<$string =~ /(abd|abc)(df|d|de)/;> > to be false. + +Even with all this work, regexp matching happens remarkably fast. To +speed things up, during compilation stage, perl compiles the regexp +into a compact sequence of opcodes that can often fit inside a +processor cache. When the code is executed, these opcodes can then run +at full throttle and search very quickly. + +=head2 Extracting matches + +The grouping metacharacters C<()> also serve another completely +different function: they allow the extraction of the parts of a string +that matched. This is very useful to find out what matched and for +text processing in general. For each grouping, the part that matched +inside goes into the special variables C<$1>, C<$2>, etc. They can be +used just as ordinary variables: + + # extract hours, minutes, seconds + $time =~ /(\d\d):(\d\d):(\d\d)/; # match hh:mm:ss format + $hours = $1; + $minutes = $2; + $seconds = $3; + +Now, we know that in scalar context, +S<C<$time =~ /(\d\d):(\d\d):(\d\d)/> > returns a true or false +value. In list context, however, it returns the list of matched values +C<($1,$2,$3)>. So we could write the code more compactly as + + # extract hours, minutes, seconds + ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/); + +If the groupings in a regexp are nested, C<$1> gets the group with the +leftmost opening parenthesis, C<$2> the next opening parenthesis, +etc. For example, here is a complex regexp and the matching variables +indicated below it: + + /(ab(cd|ef)((gi)|j))/; + 1 2 34 + +so that if the regexp matched, e.g., C<$2> would contain 'cd' or 'ef'. +For convenience, perl sets C<$+> to the highest numbered C<$1>, C<$2>, +... that got assigned. + +Closely associated with the matching variables C<$1>, C<$2>, ... are +the B<backreferences> C<\1>, C<\2>, ... . Backreferences are simply +matching variables that can be used I<inside> a regexp. This is a +really nice feature - what matches later in a regexp can depend on +what matched earlier in the regexp. Suppose we wanted to look +for doubled words in text, like 'the the'. The following regexp finds +all 3-letter doubles with a space in between: + + /(\w\w\w)\s\1/; + +The grouping assigns a value to \1, so that the same 3 letter sequence +is used for both parts. Here are some words with repeated parts: + + % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\1$' /usr/dict/words + beriberi + booboo + coco + mama + murmur + papa + +The regexp has a single grouping which considers 4-letter +combinations, then 3-letter combinations, etc. and uses C<\1> to look for +a repeat. Although C<$1> and C<\1> represent the same thing, care should be +taken to use matched variables C<$1>, C<$2>, ... only outside a regexp +and backreferences C<\1>, C<\2>, ... only inside a regexp; not doing +so may lead to surprising and/or undefined results. + +In addition to what was matched, Perl 5.6.0 also provides the +positions of what was matched with the C<@-> and C<@+> +arrays. C<$-[0]> is the position of the start of the entire match and +C<$+[0]> is the position of the end. Similarly, C<$-[n]> is the +position of the start of the C<$n> match and C<$+[n]> is the position +of the end. If C<$n> is undefined, so are C<$-[n]> and C<$+[n]>. Then +this code + + $x = "Mmm...donut, thought Homer"; + $x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches + foreach $expr (1..$#-) { + print "Match $expr: '${$expr}' at position ($-[$expr],$+[$expr])\n"; + } + +prints + + Match 1: 'Mmm' at position (0,3) + Match 2: 'donut' at position (6,11) + +Even if there are no groupings in a regexp, it is still possible to +find out what exactly matched in a string. If you use them, perl +will set C<$`> to the part of the string before the match, will set C<$&> +to the part of the string that matched, and will set C<$'> to the part +of the string after the match. An example: + + $x = "the cat caught the mouse"; + $x =~ /cat/; # $` = 'the ', $& = 'cat', $' = ' caught the mouse' + $x =~ /the/; # $` = '', $& = 'the', $' = ' cat caught the mouse' + +In the second match, S<C<$` = ''> > because the regexp matched at the +first character position in the string and stopped, it never saw the +second 'the'. It is important to note that using C<$`> and C<$'> +slows down regexp matching quite a bit, and C< $& > slows it down to a +lesser extent, because if they are used in one regexp in a program, +they are generated for <all> regexps in the program. So if raw +performance is a goal of your application, they should be avoided. +If you need them, use C<@-> and C<@+> instead: + + $` is the same as substr( $x, 0, $-[0] ) + $& is the same as substr( $x, $-[0], $+[0]-$-[0] ) + $' is the same as substr( $x, $+[0] ) + +=head2 Matching repetitions + +The examples in the previous section display an annoying weakness. We +were only matching 3-letter words, or syllables of 4 letters or +less. We'd like to be able to match words or syllables of any length, +without writing out tedious alternatives like +C<\w\w\w\w|\w\w\w|\w\w|\w>. + +This is exactly the problem the B<quantifier> metacharacters C<?>, +C<*>, C<+>, and C<{}> were created for. They allow us to determine the +number of repeats of a portion of a regexp we consider to be a +match. Quantifiers are put immediately after the character, character +class, or grouping that we want to specify. They have the following +meanings: + +=over 4 + +=item * C<a?> = match 'a' 1 or 0 times + +=item * C<a*> = match 'a' 0 or more times, i.e., any number of times + +=item * C<a+> = match 'a' 1 or more times, i.e., at least once + +=item * C<a{n,m}> = match at least C<n> times, but not more than C<m> +times. + +=item * C<a{n,}> = match at least C<n> or more times + +=item * C<a{n}> = match exactly C<n> times + +=back + +Here are some examples: + + /[a-z]+\s+\d*/; # match a lowercase word, at least some space, and + # any number of digits + /(\w+)\s+\1/; # match doubled words of arbitrary length + /y(es)?/i; # matches 'y', 'Y', or a case-insensitive 'yes' + $year =~ /\d{2,4}/; # make sure year is at least 2 but not more + # than 4 digits + $year =~ /\d{4}|\d{2}/; # better match; throw out 3 digit dates + $year =~ /\d{2}(\d{2})?/; # same thing written differently. However, + # this produces $1 and the other does not. + + % simple_grep '^(\w+)\1$' /usr/dict/words # isn't this easier? + beriberi + booboo + coco + mama + murmur + papa + +For all of these quantifiers, perl will try to match as much of the +string as possible, while still allowing the regexp to succeed. Thus +with C</a?.../>, perl will first try to match the regexp with the C<a> +present; if that fails, perl will try to match the regexp without the +C<a> present. For the quantifier C<*>, we get the following: + + $x = "the cat in the hat"; + $x =~ /^(.*)(cat)(.*)$/; # matches, + # $1 = 'the ' + # $2 = 'cat' + # $3 = ' in the hat' + +Which is what we might expect, the match finds the only C<cat> in the +string and locks onto it. Consider, however, this regexp: + + $x =~ /^(.*)(at)(.*)$/; # matches, + # $1 = 'the cat in the h' + # $2 = 'at' + # $3 = '' (0 matches) + +One might initially guess that perl would find the C<at> in C<cat> and +stop there, but that wouldn't give the longest possible string to the +first quantifier C<.*>. Instead, the first quantifier C<.*> grabs as +much of the string as possible while still having the regexp match. In +this example, that means having the C<at> sequence with the final C<at> +in the string. The other important principle illustrated here is that +when there are two or more elements in a regexp, the I<leftmost> +quantifier, if there is one, gets to grab as much the string as +possible, leaving the rest of the regexp to fight over scraps. Thus in +our example, the first quantifier C<.*> grabs most of the string, while +the second quantifier C<.*> gets the empty string. Quantifiers that +grab as much of the string as possible are called B<maximal match> or +B<greedy> quantifiers. + +When a regexp can match a string in several different ways, we can use +the principles above to predict which way the regexp will match: + +=over 4 + +=item * +Principle 0: Taken as a whole, any regexp will be matched at the +earliest possible position in the string. + +=item * +Principle 1: In an alternation C<a|b|c...>, the leftmost alternative +that allows a match for the whole regexp will be the one used. + +=item * +Principle 2: The maximal matching quantifiers C<?>, C<*>, C<+> and +C<{n,m}> will in general match as much of the string as possible while +still allowing the whole regexp to match. + +=item * +Principle 3: If there are two or more elements in a regexp, the +leftmost greedy quantifier, if any, will match as much of the string +as possible while still allowing the whole regexp to match. The next +leftmost greedy quantifier, if any, will try to match as much of the +string remaining available to it as possible, while still allowing the +whole regexp to match. And so on, until all the regexp elements are +satisfied. + +=back + +As we have seen above, Principle 0 overrides the others - the regexp +will be matched as early as possible, with the other principles +determining how the regexp matches at that earliest character +position. + +Here is an example of these principles in action: + + $x = "The programming republic of Perl"; + $x =~ /^(.+)(e|r)(.*)$/; # matches, + # $1 = 'The programming republic of Pe' + # $2 = 'r' + # $3 = 'l' + +This regexp matches at the earliest string position, C<'T'>. One +might think that C<e>, being leftmost in the alternation, would be +matched, but C<r> produces the longest string in the first quantifier. + + $x =~ /(m{1,2})(.*)$/; # matches, + # $1 = 'mm' + # $2 = 'ing republic of Perl' + +Here, The earliest possible match is at the first C<'m'> in +C<programming>. C<m{1,2}> is the first quantifier, so it gets to match +a maximal C<mm>. + + $x =~ /.*(m{1,2})(.*)$/; # matches, + # $1 = 'm' + # $2 = 'ing republic of Perl' + +Here, the regexp matches at the start of the string. The first +quantifier C<.*> grabs as much as possible, leaving just a single +C<'m'> for the second quantifier C<m{1,2}>. + + $x =~ /(.?)(m{1,2})(.*)$/; # matches, + # $1 = 'a' + # $2 = 'mm' + # $3 = 'ing republic of Perl' + +Here, C<.?> eats its maximal one character at the earliest possible +position in the string, C<'a'> in C<programming>, leaving C<m{1,2}> +the opportunity to match both C<m>'s. Finally, + + "aXXXb" =~ /(X*)/; # matches with $1 = '' + +because it can match zero copies of C<'X'> at the beginning of the +string. If you definitely want to match at least one C<'X'>, use +C<X+>, not C<X*>. + +Sometimes greed is not good. At times, we would like quantifiers to +match a I<minimal> piece of string, rather than a maximal piece. For +this purpose, Larry Wall created the S<B<minimal match> > or +B<non-greedy> quantifiers C<??>,C<*?>, C<+?>, and C<{}?>. These are +the usual quantifiers with a C<?> appended to them. They have the +following meanings: + +=over 4 + +=item * C<a??> = match 'a' 0 or 1 times. Try 0 first, then 1. + +=item * C<a*?> = match 'a' 0 or more times, i.e., any number of times, +but as few times as possible + +=item * C<a+?> = match 'a' 1 or more times, i.e., at least once, but +as few times as possible + +=item * C<a{n,m}?> = match at least C<n> times, not more than C<m> +times, as few times as possible + +=item * C<a{n,}?> = match at least C<n> times, but as few times as +possible + +=item * C<a{n}?> = match exactly C<n> times. Because we match exactly +C<n> times, C<a{n}?> is equivalent to C<a{n}> and is just there for +notational consistency. + +=back + +Let's look at the example above, but with minimal quantifiers: + + $x = "The programming republic of Perl"; + $x =~ /^(.+?)(e|r)(.*)$/; # matches, + # $1 = 'Th' + # $2 = 'e' + # $3 = ' programming republic of Perl' + +The minimal string that will allow both the start of the string C<^> +and the alternation to match is C<Th>, with the alternation C<e|r> +matching C<e>. The second quantifier C<.*> is free to gobble up the +rest of the string. + + $x =~ /(m{1,2}?)(.*?)$/; # matches, + # $1 = 'm' + # $2 = 'ming republic of Perl' + +The first string position that this regexp can match is at the first +C<'m'> in C<programming>. At this position, the minimal C<m{1,2}?> +matches just one C<'m'>. Although the second quantifier C<.*?> would +prefer to match no characters, it is constrained by the end-of-string +anchor C<$> to match the rest of the string. + + $x =~ /(.*?)(m{1,2}?)(.*)$/; # matches, + # $1 = 'The progra' + # $2 = 'm' + # $3 = 'ming republic of Perl' + +In this regexp, you might expect the first minimal quantifier C<.*?> +to match the empty string, because it is not constrained by a C<^> +anchor to match the beginning of the word. Principle 0 applies here, +however. Because it is possible for the whole regexp to match at the +start of the string, it I<will> match at the start of the string. Thus +the first quantifier has to match everything up to the first C<m>. The +second minimal quantifier matches just one C<m> and the third +quantifier matches the rest of the string. + + $x =~ /(.??)(m{1,2})(.*)$/; # matches, + # $1 = 'a' + # $2 = 'mm' + # $3 = 'ing republic of Perl' + +Just as in the previous regexp, the first quantifier C<.??> can match +earliest at position C<'a'>, so it does. The second quantifier is +greedy, so it matches C<mm>, and the third matches the rest of the +string. + +We can modify principle 3 above to take into account non-greedy +quantifiers: + +=over 4 + +=item * +Principle 3: If there are two or more elements in a regexp, the +leftmost greedy (non-greedy) quantifier, if any, will match as much +(little) of the string as possible while still allowing the whole +regexp to match. The next leftmost greedy (non-greedy) quantifier, if +any, will try to match as much (little) of the string remaining +available to it as possible, while still allowing the whole regexp to +match. And so on, until all the regexp elements are satisfied. + +=back + +Just like alternation, quantifiers are also susceptible to +backtracking. Here is a step-by-step analysis of the example + + $x = "the cat in the hat"; + $x =~ /^(.*)(at)(.*)$/; # matches, + # $1 = 'the cat in the h' + # $2 = 'at' + # $3 = '' (0 matches) + +=over 4 + +=item 0 Start with the first letter in the string 't'. + +=item 1 The first quantifier '.*' starts out by matching the whole +string 'the cat in the hat'. + +=item 2 'a' in the regexp element 'at' doesn't match the end of the +string. Backtrack one character. + +=item 3 'a' in the regexp element 'at' still doesn't match the last +letter of the string 't', so backtrack one more character. + +=item 4 Now we can match the 'a' and the 't'. + +=item 5 Move on to the third element '.*'. Since we are at the end of +the string and '.*' can match 0 times, assign it the empty string. + +=item 6 We are done! + +=back + +Most of the time, all this moving forward and backtracking happens +quickly and searching is fast. There are some pathological regexps, +however, whose execution time exponentially grows with the size of the +string. A typical structure that blows up in your face is of the form + + /(a|b+)*/; + +The problem is the nested indeterminate quantifiers. There are many +different ways of partitioning a string of length n between the C<+> +and C<*>: one repetition with C<b+> of length n, two repetitions with +the first C<b+> length k and the second with length n-k, m repetitions +whose bits add up to length n, etc. In fact there are an exponential +number of ways to partition a string as a function of length. A +regexp may get lucky and match early in the process, but if there is +no match, perl will try I<every> possibility before giving up. So be +careful with nested C<*>'s, C<{n,m}>'s, and C<+>'s. The book +I<Mastering regular expressions> by Jeffrey Friedl gives a wonderful +discussion of this and other efficiency issues. + +=head2 Building a regexp + +At this point, we have all the basic regexp concepts covered, so let's +give a more involved example of a regular expression. We will build a +regexp that matches numbers. + +The first task in building a regexp is to decide what we want to match +and what we want to exclude. In our case, we want to match both +integers and floating point numbers and we want to reject any string +that isn't a number. + +The next task is to break the problem down into smaller problems that +are easily converted into a regexp. + +The simplest case is integers. These consist of a sequence of digits, +with an optional sign in front. The digits we can represent with +C<\d+> and the sign can be matched with C<[+-]>. Thus the integer +regexp is + + /[+-]?\d+/; # matches integers + +A floating point number potentially has a sign, an integral part, a +decimal point, a fractional part, and an exponent. One or more of these +parts is optional, so we need to check out the different +possibilities. Floating point numbers which are in proper form include +123., 0.345, .34, -1e6, and 25.4E-72. As with integers, the sign out +front is completely optional and can be matched by C<[+-]?>. We can +see that if there is no exponent, floating point numbers must have a +decimal point, otherwise they are integers. We might be tempted to +model these with C<\d*\.\d*>, but this would also match just a single +decimal point, which is not a number. So the three cases of floating +point number sans exponent are + + /[+-]?\d+\./; # 1., 321., etc. + /[+-]?\.\d+/; # .1, .234, etc. + /[+-]?\d+\.\d+/; # 1.0, 30.56, etc. + +These can be combined into a single regexp with a three-way alternation: + + /[+-]?(\d+\.\d+|\d+\.|\.\d+)/; # floating point, no exponent + +In this alternation, it is important to put C<'\d+\.\d+'> before +C<'\d+\.'>. If C<'\d+\.'> were first, the regexp would happily match that +and ignore the fractional part of the number. + +Now consider floating point numbers with exponents. The key +observation here is that I<both> integers and numbers with decimal +points are allowed in front of an exponent. Then exponents, like the +overall sign, are independent of whether we are matching numbers with +or without decimal points, and can be 'decoupled' from the +mantissa. The overall form of the regexp now becomes clear: + + /^(optional sign)(integer | f.p. mantissa)(optional exponent)$/; + +The exponent is an C<e> or C<E>, followed by an integer. So the +exponent regexp is + + /[eE][+-]?\d+/; # exponent + +Putting all the parts together, we get a regexp that matches numbers: + + /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/; # Ta da! + +Long regexps like this may impress your friends, but can be hard to +decipher. In complex situations like this, the C<//x> modifier for a +match is invaluable. It allows one to put nearly arbitrary whitespace +and comments into a regexp without affecting their meaning. Using it, +we can rewrite our 'extended' regexp in the more pleasing form + + /^ + [+-]? # first, match an optional sign + ( # then match integers or f.p. mantissas: + \d+\.\d+ # mantissa of the form a.b + |\d+\. # mantissa of the form a. + |\.\d+ # mantissa of the form .b + |\d+ # integer of the form a + ) + ([eE][+-]?\d+)? # finally, optionally match an exponent + $/x; + +If whitespace is mostly irrelevant, how does one include space +characters in an extended regexp? The answer is to backslash it +S<C<'\ '> > or put it in a character class S<C<[ ]> >. The same thing +goes for pound signs, use C<\#> or C<[#]>. For instance, Perl allows +a space between the sign and the mantissa/integer, and we could add +this to our regexp as follows: + + /^ + [+-]?\ * # first, match an optional sign *and space* + ( # then match integers or f.p. mantissas: + \d+\.\d+ # mantissa of the form a.b + |\d+\. # mantissa of the form a. + |\.\d+ # mantissa of the form .b + |\d+ # integer of the form a + ) + ([eE][+-]?\d+)? # finally, optionally match an exponent + $/x; + +In this form, it is easier to see a way to simplify the +alternation. Alternatives 1, 2, and 4 all start with C<\d+>, so it +could be factored out: + + /^ + [+-]?\ * # first, match an optional sign + ( # then match integers or f.p. mantissas: + \d+ # start out with a ... + ( + \.\d* # mantissa of the form a.b or a. + )? # ? takes care of integers of the form a + |\.\d+ # mantissa of the form .b + ) + ([eE][+-]?\d+)? # finally, optionally match an exponent + $/x; + +or written in the compact form, + + /^[+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/; + +This is our final regexp. To recap, we built a regexp by + +=over 4 + +=item * specifying the task in detail, + +=item * breaking down the problem into smaller parts, + +=item * translating the small parts into regexps, + +=item * combining the regexps, + +=item * and optimizing the final combined regexp. + +=back + +These are also the typical steps involved in writing a computer +program. This makes perfect sense, because regular expressions are +essentially programs written a little computer language that specifies +patterns. + +=head2 Using regular expressions in Perl + +The last topic of Part 1 briefly covers how regexps are used in Perl +programs. Where do they fit into Perl syntax? + +We have already introduced the matching operator in its default +C</regexp/> and arbitrary delimiter C<m!regexp!> forms. We have used +the binding operator C<=~> and its negation C<!~> to test for string +matches. Associated with the matching operator, we have discussed the +single line C<//s>, multi-line C<//m>, case-insensitive C<//i> and +extended C<//x> modifiers. + +There are a few more things you might want to know about matching +operators. First, we pointed out earlier that variables in regexps are +substituted before the regexp is evaluated: + + $pattern = 'Seuss'; + while (<>) { + print if /$pattern/; + } + +This will print any lines containing the word C<Seuss>. It is not as +efficient as it could be, however, because perl has to re-evaluate +C<$pattern> each time through the loop. If C<$pattern> won't be +changing over the lifetime of the script, we can add the C<//o> +modifier, which directs perl to only perform variable substitutions +once: + + #!/usr/bin/perl + # Improved simple_grep + $regexp = shift; + while (<>) { + print if /$regexp/o; # a good deal faster + } + +If you change C<$pattern> after the first substitution happens, perl +will ignore it. If you don't want any substitutions at all, use the +special delimiter C<m''>: + + $pattern = 'Seuss'; + while (<>) { + print if m'$pattern'; # matches '$pattern', not 'Seuss' + } + +C<m''> acts like single quotes on a regexp; all other C<m> delimiters +act like double quotes. If the regexp evaluates to the empty string, +the regexp in the I<last successful match> is used instead. So we have + + "dog" =~ /d/; # 'd' matches + "dogbert =~ //; # this matches the 'd' regexp used before + +The final two modifiers C<//g> and C<//c> concern multiple matches. +The modifier C<//g> stands for global matching and allows the the +matching operator to match within a string as many times as possible. +In scalar context, successive invocations against a string will have +`C<//g> jump from match to match, keeping track of position in the +string as it goes along. You can get or set the position with the +C<pos()> function. + +The use of C<//g> is shown in the following example. Suppose we have +a string that consists of words separated by spaces. If we know how +many words there are in advance, we could extract the words using +groupings: + + $x = "cat dog house"; # 3 words + $x =~ /^\s*(\w+)\s+(\w+)\s+(\w+)\s*$/; # matches, + # $1 = 'cat' + # $2 = 'dog' + # $3 = 'house' + +But what if we had an indeterminate number of words? This is the sort +of task C<//g> was made for. To extract all words, form the simple +regexp C<(\w+)> and loop over all matches with C</(\w+)/g>: + + while ($x =~ /(\w+)/g) { + print "Word is $1, ends at position ", pos $x, "\n"; + } + +prints + + Word is cat, ends at position 3 + Word is dog, ends at position 7 + Word is house, ends at position 13 + +A failed match or changing the target string resets the position. If +you don't want the position reset after failure to match, add the +C<//c>, as in C</regexp/gc>. The current position in the string is +associated with the string, not the regexp. This means that different +strings have different positions and their respective positions can be +set or read independently. + +In list context, C<//g> returns a list of matched groupings, or if +there are no groupings, a list of matches to the whole regexp. So if +we wanted just the words, we could use + + @words = ($x =~ /(\w+)/g); # matches, + # $word[0] = 'cat' + # $word[1] = 'dog' + # $word[2] = 'house' + +Closely associated with the C<//g> modifier is the C<\G> anchor. The +C<\G> anchor matches at the point where the previous C<//g> match left +off. C<\G> allows us to easily do context-sensitive matching: + + $metric = 1; # use metric units + ... + $x = <FILE>; # read in measurement + $x =~ /^([+-]?\d+)\s*/g; # get magnitude + $weight = $1; + if ($metric) { # error checking + print "Units error!" unless $x =~ /\Gkg\./g; + } + else { + print "Units error!" unless $x =~ /\Glbs\./g; + } + $x =~ /\G\s+(widget|sprocket)/g; # continue processing + +The combination of C<//g> and C<\G> allows us to process the string a +bit at a time and use arbitrary Perl logic to decide what to do next. + +C<\G> is also invaluable in processing fixed length records with +regexps. Suppose we have a snippet of coding region DNA, encoded as +base pair letters C<ATCGTTGAAT...> and we want to find all the stop +codons C<TGA>. In a coding region, codons are 3-letter sequences, so +we can think of the DNA snippet as a sequence of 3-letter records. The +naive regexp + + # expanded, this is "ATC GTT GAA TGC AAA TGA CAT GAC" + $dna = "ATCGTTGAATGCAAATGACATGAC"; + $dna =~ /TGA/; + +doesn't work; it may match an C<TGA>, but there is no guarantee that +the match is aligned with codon boundaries, e.g., the substring +S<C<GTT GAA> > gives a match. A better solution is + + while ($dna =~ /(\w\w\w)*?TGA/g) { # note the minimal *? + print "Got a TGA stop codon at position ", pos $dna, "\n"; + } + +which prints + + Got a TGA stop codon at position 18 + Got a TGA stop codon at position 23 + +Position 18 is good, but position 23 is bogus. What happened? + +The answer is that our regexp works well until we get past the last +real match. Then the regexp will fail to match a synchronized C<TGA> +and start stepping ahead one character position at a time, not what we +want. The solution is to use C<\G> to anchor the match to the codon +alignment: + + while ($dna =~ /\G(\w\w\w)*?TGA/g) { + print "Got a TGA stop codon at position ", pos $dna, "\n"; + } + +This prints + + Got a TGA stop codon at position 18 + +which is the correct answer. This example illustrates that it is +important not only to match what is desired, but to reject what is not +desired. + +B<search and replace> + +Regular expressions also play a big role in B<search and replace> +operations in Perl. Search and replace is accomplished with the +C<s///> operator. The general form is +C<s/regexp/replacement/modifiers>, with everything we know about +regexps and modifiers applying in this case as well. The +C<replacement> is a Perl double quoted string that replaces in the +string whatever is matched with the C<regexp>. The operator C<=~> is +also used here to associate a string with C<s///>. If matching +against C<$_>, the S<C<$_ =~> > can be dropped. If there is a match, +C<s///> returns the number of substitutions made, otherwise it returns +false. Here are a few examples: + + $x = "Time to feed the cat!"; + $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!" + if ($x =~ s/^(Time.*hacker)!$/$1 now!/) { + $more_insistent = 1; + } + $y = "'quoted words'"; + $y =~ s/^'(.*)'$/$1/; # strip single quotes, + # $y contains "quoted words" + +In the last example, the whole string was matched, but only the part +inside the single quotes was grouped. With the C<s///> operator, the +matched variables C<$1>, C<$2>, etc. are immediately available for use +in the replacement expression, so we use C<$1> to replace the quoted +string with just what was quoted. With the global modifier, C<s///g> +will search and replace all occurrences of the regexp in the string: + + $x = "I batted 4 for 4"; + $x =~ s/4/four/; # doesn't do it all: + # $x contains "I batted four for 4" + $x = "I batted 4 for 4"; + $x =~ s/4/four/g; # does it all: + # $x contains "I batted four for four" + +If you prefer 'regex' over 'regexp' in this tutorial, you could use +the following program to replace it: + + % cat > simple_replace + #!/usr/bin/perl + $regexp = shift; + $replacement = shift; + while (<>) { + s/$regexp/$replacement/go; + print; + } + ^D + + % simple_replace regexp regex perlretut.pod + +In C<simple_replace> we used the C<s///g> modifier to replace all +occurrences of the regexp on each line and the C<s///o> modifier to +compile the regexp only once. As with C<simple_grep>, both the +C<print> and the C<s/$regexp/$replacement/go> use C<$_> implicitly. + +A modifier available specifically to search and replace is the +C<s///e> evaluation modifier. C<s///e> wraps an C<eval{...}> around +the replacement string and the evaluated result is substituted for the +matched substring. C<s///e> is useful if you need to do a bit of +computation in the process of replacing text. This example counts +character frequencies in a line: + + $x = "Bill the cat"; + $x =~ s/(.)/$chars{$1}++;$1/eg; # final $1 replaces char with itself + print "frequency of '$_' is $chars{$_}\n" + foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars); + +This prints + + frequency of ' ' is 2 + frequency of 't' is 2 + frequency of 'l' is 2 + frequency of 'B' is 1 + frequency of 'c' is 1 + frequency of 'e' is 1 + frequency of 'h' is 1 + frequency of 'i' is 1 + frequency of 'a' is 1 + +As with the match C<m//> operator, C<s///> can use other delimiters, +such as C<s!!!> and C<s{}{}>, and even C<s{}//>. If single quotes are +used C<s'''>, then the regexp and replacement are treated as single +quoted strings and there are no substitutions. C<s///> in list context +returns the same thing as in scalar context, i.e., the number of +matches. + +B<The split operator> + +The B<C<split> > function can also optionally use a matching operator +C<m//> to split a string. C<split /regexp/, string, limit> splits +C<string> into a list of substrings and returns that list. The regexp +is used to match the character sequence that the C<string> is split +with respect to. The C<limit>, if present, constrains splitting into +no more than C<limit> number of strings. For example, to split a +string into words, use + + $x = "Calvin and Hobbes"; + @words = split /\s+/, $x; # $word[0] = 'Calvin' + # $word[1] = 'and' + # $word[2] = 'Hobbes' + +If the empty regexp C<//> is used, the regexp always matches and +the string is split into individual characters. If the regexp has +groupings, then list produced contains the matched substrings from the +groupings as well. For instance, + + $x = "/usr/bin/perl"; + @dirs = split m!/!, $x; # $dirs[0] = '' + # $dirs[1] = 'usr' + # $dirs[2] = 'bin' + # $dirs[3] = 'perl' + @parts = split m!(/)!, $x; # $parts[0] = '' + # $parts[1] = '/' + # $parts[2] = 'usr' + # $parts[3] = '/' + # $parts[4] = 'bin' + # $parts[5] = '/' + # $parts[6] = 'perl' + +Since the first character of $x matched the regexp, C<split> prepended +an empty initial element to the list. + +If you have read this far, congratulations! You now have all the basic +tools needed to use regular expressions to solve a wide range of text +processing problems. If this is your first time through the tutorial, +why not stop here and play around with regexps a while... S<Part 2> +concerns the more esoteric aspects of regular expressions and those +concepts certainly aren't needed right at the start. + +=head1 Part 2: Power tools + +OK, you know the basics of regexps and you want to know more. If +matching regular expressions is analogous to a walk in the woods, then +the tools discussed in Part 1 are analogous to topo maps and a +compass, basic tools we use all the time. Most of the tools in part 2 +are are analogous to flare guns and satellite phones. They aren't used +too often on a hike, but when we are stuck, they can be invaluable. + +What follows are the more advanced, less used, or sometimes esoteric +capabilities of perl regexps. In Part 2, we will assume you are +comfortable with the basics and concentrate on the new features. + +=head2 More on characters, strings, and character classes + +There are a number of escape sequences and character classes that we +haven't covered yet. + +There are several escape sequences that convert characters or strings +between upper and lower case. C<\l> and C<\u> convert the next +character to lower or upper case, respectively: + + $x = "perl"; + $string =~ /\u$x/; # matches 'Perl' in $string + $x = "M(rs?|s)\\."; # note the double backslash + $string =~ /\l$x/; # matches 'mr.', 'mrs.', and 'ms.', + +C<\L> and C<\U> converts a whole substring, delimited by C<\L> or +C<\U> and C<\E>, to lower or upper case: + + $x = "This word is in lower case:\L SHOUT\E"; + $x =~ /shout/; # matches + $x = "I STILL KEYPUNCH CARDS FOR MY 360" + $x =~ /\Ukeypunch/; # matches punch card string + +If there is no C<\E>, case is converted until the end of the +string. The regexps C<\L\u$word> or C<\u\L$word> convert the first +character of C<$word> to uppercase and the rest of the characters to +lowercase. + +Control characters can be escaped with C<\c>, so that a control-Z +character would be matched with C<\cZ>. The escape sequence +C<\Q>...C<\E> quotes, or protects most non-alphabetic characters. For +instance, + + $x = "\QThat !^*&%~& cat!"; + $x =~ /\Q!^*&%~&\E/; # check for rough language + +It does not protect C<$> or C<@>, so that variables can still be +substituted. + +With the advent of 5.6.0, perl regexps can handle more than just the +standard ASCII character set. Perl now supports B<Unicode>, a standard +for encoding the character sets from many of the world's written +languages. Unicode does this by allowing characters to be more than +one byte wide. Perl uses the UTF-8 encoding, in which ASCII characters +are still encoded as one byte, but characters greater than C<chr(127)> +may be stored as two or more bytes. + +What does this mean for regexps? Well, regexp users don't need to know +much about perl's internal representation of strings. But they do need +to know 1) how to represent Unicode characters in a regexp and 2) when +a matching operation will treat the string to be searched as a +sequence of bytes (the old way) or as a sequence of Unicode characters +(the new way). The answer to 1) is that Unicode characters greater +than C<chr(127)> may be represented using the C<\x{hex}> notation, +with C<hex> a hexadecimal integer: + + use utf8; # We will be doing Unicode processing + /\x{263a}/; # match a Unicode smiley face :) + +Unicode characters in the range of 128-255 use two hexadecimal digits +with braces: C<\x{ab}>. Note that this is different than C<\xab>, +which is just a hexadecimal byte with no Unicode +significance. + +Figuring out the hexadecimal sequence of a Unicode character you want +or deciphering someone else's hexadecimal Unicode regexp is about as +much fun as programming in machine code. So another way to specify +Unicode characters is to use the S<B<named character> > escape +sequence C<\N{name}>. C<name> is a name for the Unicode character, as +specified in the Unicode standard. For instance, if we wanted to +represent or match the astrological sign for the planet Mercury, we +could use + + use utf8; # We will be doing Unicode processing + use charnames ":full"; # use named chars with Unicode full names + $x = "abc\N{MERCURY}def"; + $x =~ /\N{MERCURY}/; # matches + +One can also use short names or restrict names to a certain alphabet: + + use utf8; # We will be doing Unicode processing + + use charnames ':full'; + print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n"; + + use charnames ":short"; + print "\N{greek:Sigma} is an upper-case sigma.\n"; + + use charnames qw(greek); + print "\N{sigma} is Greek sigma\n"; + +A list of full names is found in the file Names.txt in the +lib/perl5/5.6.0/unicode directory. + +The answer to requirement 2), as of 5.6.0, is that if a regexp +contains Unicode characters, the string is searched as a sequence of +Unicode characters. Otherwise, the string is searched as a sequence of +bytes. If the string is being searched as a sequence of Unicode +characters, but matching a single byte is required, we can use the C<\C> +escape sequence. C<\C> is a character class akin to C<.> except that +it matches I<any> byte 0-255. So + + use utf8; # We will be doing Unicode processing + use charnames ":full"; # use named chars with Unicode full names + $x = "a"; + $x =~ /\C/; # matches 'a', eats one byte + $x = ""; + $x =~ /\C/; # doesn't match, no bytes to match + $x = "\N{MERCURY}"; # two-byte Unicode character + $x =~ /\C/; # matches, but dangerous! + +The last regexp matches, but is dangerous because the string +I<character> position is no longer synchronized to the string I<byte> +position. This generates the warning 'Malformed UTF-8 +character'. C<\C> is best used for matching the binary data in strings +with binary data intermixed with Unicode characters. + +Let us now discuss the rest of the character classes. Just as with +Unicode characters, there are named Unicode character classes +represented by the C<\p{name}> escape sequence. Closely associated is +the C<\P{name}> character class, which is the negation of the +C<\p{name}> class. For example, to match lower and uppercase +characters, + + use utf8; # We will be doing Unicode processing + use charnames ":full"; # use named chars with Unicode full names + $x = "BOB"; + $x =~ /^\p{IsUpper}/; # matches, uppercase char class + $x =~ /^\P{IsUpper}/; # doesn't match, char class sans uppercase + $x =~ /^\p{IsLower}/; # doesn't match, lowercase char class + $x =~ /^\P{IsLower}/; # matches, char class sans lowercase + +If a C<name> is just one letter, the braces can be dropped. For +instance, C<\pM> is the character class of Unicode 'marks'. Here is +the association between some Perl named classes and the traditional +Unicode classes: + + Perl class name Unicode class name + + IsAlpha Lu, Ll, or Lo + IsAlnum Lu, Ll, Lo, or Nd + IsASCII $code le 127 + IsCntrl C + IsDigit Nd + IsGraph [^C] and $code ne "0020" + IsLower Ll + IsPrint [^C] + IsPunct P + IsSpace Z, or ($code lt "0020" and chr(hex $code) is a \s) + IsUpper Lu + IsWord Lu, Ll, Lo, Nd or $code eq "005F" + IsXDigit $code =~ /^00(3[0-9]|[46][1-6])$/ + +For a full list of Perl class names, consult the mktables.PL program +in the lib/perl5/5.6.0/unicode directory. + +C<\X> is an abbreviation for a character class sequence that includes +the Unicode 'combining character sequences'. A 'combining character +sequence' is a base character followed by any number of combining +characters. An example of a combining character is an accent. Using +the Unicode full names, e.g., S<C<A + COMBINING RING> > is a combining +character sequence with base character C<A> and combining character +S<C<COMBINING RING> >, which translates in Danish to A with the circle +atop it, as in the word Angstrom. C<\X> is equivalent to C<\PM\pM*}>, +i.e., a non-mark followed by one or more marks. + +As if all those classes weren't enough, Perl also defines POSIX style +character classes. These have the form C<[:name:]>, with C<name> the +name of the POSIX class. The POSIX classes are alpha, alnum, ascii, +cntrl, digit, graph, lower, print, punct, space, upper, word, and +xdigit. If C<utf8> is being used, then these classes are defined the +same as their corresponding perl Unicode classes: C<[:upper:]> is the +same as C<\p{IsUpper}>, etc. The POSIX character classes, however, +don't require using C<utf8>. The C<[:digit:]>, C<[:word:]>, and +C<[:space:]> correspond to the familiar C<\d>, C<\w>, and C<\s> +character classes. To negate a POSIX class, put a C<^> in front of the +name, so that, e.g., C<[:^digit:]> corresponds to C<\D> and under +C<utf8>, C<\P{IsDigit}>. The Unicode and POSIX character classes can +be used just like C<\d>, both inside and outside of character classes: + + /\s+[abc[:digit:]xyz]\s*/; # match a,b,c,x,y,z, or a digit + /^=item\s[:digit:]/; # match '=item', + # followed by a space and a digit + use utf8; + use charnames ":full"; + /\s+[abc\p{IsDigit}xyz]\s+/; # match a,b,c,x,y,z, or a digit + /^=item\s\p{IsDigit}/; # match '=item', + # followed by a space and a digit + +Whew! That is all the rest of the characters and character classes. + +=head2 Compiling and saving regular expressions + +In Part 1 we discussed the C<//o> modifier, which compiles a regexp +just once. This suggests that a compiled regexp is some data structure +that can be stored once and used again and again. The regexp quote +C<qr//> does exactly that: C<qr/string/> compiles the C<string> as a +regexp and transforms the result into a form that can be assigned to a +variable: + + $reg = qr/foo+bar?/; # reg contains a compiled regexp + +Then C<$reg> can be used as a regexp: + + $x = "fooooba"; + $x =~ $reg; # matches, just like /foo+bar?/ + $x =~ /$reg/; # same thing, alternate form + +C<$reg> can also be interpolated into a larger regexp: + + $x =~ /(abc)?$reg/; # still matches + +As with the matching operator, the regexp quote can use different +delimiters, e.g., C<qr!!>, C<qr{}> and C<qr~~>. The single quote +delimiters C<qr''> prevent any interpolation from taking place. + +Pre-compiled regexps are useful for creating dynamic matches that +don't need to be recompiled each time they are encountered. Using +pre-compiled regexps, C<simple_grep> program can be expanded into a +program that matches multiple patterns: + + % cat > multi_grep + #!/usr/bin/perl + # multi_grep - match any of <number> regexps + # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ... + + $number = shift; + $regexp[$_] = shift foreach (0..$number-1); + @compiled = map qr/$_/, @regexp; + while ($line = <>) { + foreach $pattern (@compiled) { + if ($line =~ /$pattern/) { + print $line; + last; # we matched, so move onto the next line + } + } + } + ^D + + % multi_grep 2 last for multi_grep + $regexp[$_] = shift foreach (0..$number-1); + foreach $pattern (@compiled) { + last; + +Storing pre-compiled regexps in an array C<@compiled> allows us to +simply loop through the regexps without any recompilation, thus gaining +flexibility without sacrificing speed. + +=head2 Embedding comments and modifiers in a regular expression + +Starting with this section, we will be discussing Perl's set of +B<extended patterns>. These are extensions to the traditional regular +expression syntax that provide powerful new tools for pattern +matching. We have already seen extensions in the form of the minimal +matching constructs C<??>, C<*?>, C<+?>, C<{n,m}?>, and C<{n,}?>. The +rest of the extensions below have the form C<(?char...)>, where the +C<char> is a character that determines the type of extension. + +The first extension is an embedded comment C<(?#text)>. This embeds a +comment into the regular expression without affecting its meaning. The +comment should not have any closing parentheses in the text. An +example is + + /(?# Match an integer:)[+-]?\d+/; + +This style of commenting has been largely superseded by the raw, +freeform commenting that is allowed with the C<//x> modifier. + +The modifiers C<//i>, C<//m>, C<//s>, and C<//x> can also embedded in +a regexp using C<(?i)>, C<(?m)>, C<(?s)>, and C<(?x)>. For instance, + + /(?i)yes/; # match 'yes' case insensitively + /yes/i; # same thing + /(?x)( # freeform version of an integer regexp + [+-]? # match an optional sign + \d+ # match a sequence of digits + ) + /x; + +Embedded modifiers can have two important advantages over the usual +modifiers. Embedded modifiers allow a custom set of modifiers to +I<each> regexp pattern. This is great for matching an array of regexps +that must have different modifiers: + + $pattern[0] = '(?i)doctor'; + $pattern[1] = 'Johnson'; + ... + while (<>) { + foreach $patt (@pattern) { + print if /$patt/; + } + } + +The second advantage is that embedded modifiers only affect the regexp +inside the group the embedded modifier is contained in. So grouping +can be used to localize the modifier's effects: + + /Answer: ((?i)yes)/; # matches 'Answer: yes', 'Answer: YES', etc. + +Embedded modifiers can also turn off any modifiers already present +by using, e.g., C<(?-i)>. Modifiers can also be combined into +a single expression, e.g., C<(?s-i)> turns on single line mode and +turns off case insensitivity. + +=head2 Non-capturing groupings + +We noted in Part 1 that groupings C<()> had two distinct functions: 1) +group regexp elements together as a single unit, and 2) extract, or +capture, substrings that matched the regexp in the +grouping. Non-capturing groupings, denoted by C<(?:regexp)>, allow the +regexp to be treated as a single unit, but don't extract substrings or +set matching variables C<$1>, etc. Both capturing and non-capturing +groupings are allowed to co-exist in the same regexp. Because there is +no extraction, non-capturing groupings are faster than capturing +groupings. Non-capturing groupings are also handy for choosing exactly +which parts of a regexp are to be extracted to matching variables: + + # match a number, $1-$4 are set, but we only want $1 + /([+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?)/; + + # match a number faster , only $1 is set + /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/; + + # match a number, get $1 = whole number, $2 = exponent + /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?)/; + +Non-capturing groupings are also useful for removing nuisance +elements gathered from a split operation: + + $x = '12a34b5'; + @num = split /(a|b)/, $x; # @num = ('12','a','34','b','5') + @num = split /(?:a|b)/, $x; # @num = ('12','34','5') + +Non-capturing groupings may also have embedded modifiers: +C<(?i-m:regexp)> is a non-capturing grouping that matches C<regexp> +case insensitively and turns off multi-line mode. + +=head2 Looking ahead and looking behind + +This section concerns the lookahead and lookbehind assertions. First, +a little background. + +In Perl regular expressions, most regexp elements 'eat up' a certain +amount of string when they match. For instance, the regexp element +C<[abc}]> eats up one character of the string when it matches, in the +sense that perl moves to the next character position in the string +after the match. There are some elements, however, that don't eat up +characters (advance the character position) if they match. The examples +we have seen so far are the anchors. The anchor C<^> matches the +beginning of the line, but doesn't eat any characters. Similarly, the +word boundary anchor C<\b> matches, e.g., if the character to the left +is a word character and the character to the right is a non-word +character, but it doesn't eat up any characters itself. Anchors are +examples of 'zero-width assertions'. Zero-width, because they consume +no characters, and assertions, because they test some property of the +string. In the context of our walk in the woods analogy to regexp +matching, most regexp elements move us along a trail, but anchors have +us stop a moment and check our surroundings. If the local environment +checks out, we can proceed forward. But if the local environment +doesn't satisfy us, we must backtrack. + +Checking the environment entails either looking ahead on the trail, +looking behind, or both. C<^> looks behind, to see that there are no +characters before. C<$> looks ahead, to see that there are no +characters after. C<\b> looks both ahead and behind, to see if the +characters on either side differ in their 'word'-ness. + +The lookahead and lookbehind assertions are generalizations of the +anchor concept. Lookahead and lookbehind are zero-width assertions +that let us specify which characters we want to test for. The +lookahead assertion is denoted by C<(?=regexp)> and the lookbehind +assertion is denoted by C<< (?<=fixed-regexp) >>. Some examples are + + $x = "I catch the housecat 'Tom-cat' with catnip"; + $x =~ /cat(?=\s+)/; # matches 'cat' in 'housecat' + @catwords = ($x =~ /(?<=\s)cat\w+/g); # matches, + # $catwords[0] = 'catch' + # $catwords[1] = 'catnip' + $x =~ /\bcat\b/; # matches 'cat' in 'Tom-cat' + $x =~ /(?<=\s)cat(?=\s)/; # doesn't match; no isolated 'cat' in + # middle of $x + +Note that the parentheses in C<(?=regexp)> and C<< (?<=regexp) >> are +non-capturing, since these are zero-width assertions. Thus in the +second regexp, the substrings captured are those of the whole regexp +itself. Lookahead C<(?=regexp)> can match arbitrary regexps, but +lookbehind C<< (?<=fixed-regexp) >> only works for regexps of fixed +width, i.e., a fixed number of characters long. Thus +C<< (?<=(ab|bc)) >> is fine, but C<< (?<=(ab)*) >> is not. The +negated versions of the lookahead and lookbehind assertions are +denoted by C<(?!regexp)> and C<< (?<!fixed-regexp) >> respectively. +They evaluate true if the regexps do I<not> match: + + $x = "foobar"; + $x =~ /foo(?!bar)/; # doesn't match, 'bar' follows 'foo' + $x =~ /foo(?!baz)/; # matches, 'baz' doesn't follow 'foo' + $x =~ /(?<!\s)foo/; # matches, there is no \s before 'foo' + +=head2 Using independent subexpressions to prevent backtracking + +The last few extended patterns in this tutorial are experimental as of +5.6.0. Play with them, use them in some code, but don't rely on them +just yet for production code. + +S<B<Independent subexpressions> > are regular expressions, in the +context of a larger regular expression, that function independently of +the larger regular expression. That is, they consume as much or as +little of the string as they wish without regard for the ability of +the larger regexp to match. Independent subexpressions are represented +by C<< (?>regexp) >>. We can illustrate their behavior by first +considering an ordinary regexp: + + $x = "ab"; + $x =~ /a*ab/; # matches + +This obviously matches, but in the process of matching, the +subexpression C<a*> first grabbed the C<a>. Doing so, however, +wouldn't allow the whole regexp to match, so after backtracking, C<a*> +eventually gave back the C<a> and matched the empty string. Here, what +C<a*> matched was I<dependent> on what the rest of the regexp matched. + +Contrast that with an independent subexpression: + + $x =~ /(?>a*)ab/; # doesn't match! + +The independent subexpression C<< (?>a*) >> doesn't care about the rest +of the regexp, so it sees an C<a> and grabs it. Then the rest of the +regexp C<ab> cannot match. Because C<< (?>a*) >> is independent, there +is no backtracking and and the independent subexpression does not give +up its C<a>. Thus the match of the regexp as a whole fails. A similar +behavior occurs with completely independent regexps: + + $x = "ab"; + $x =~ /a*/g; # matches, eats an 'a' + $x =~ /\Gab/g; # doesn't match, no 'a' available + +Here C<//g> and C<\G> create a 'tag team' handoff of the string from +one regexp to the other. Regexps with an independent subexpression are +much like this, with a handoff of the string to the independent +subexpression, and a handoff of the string back to the enclosing +regexp. + +The ability of an independent subexpression to prevent backtracking +can be quite useful. Suppose we want to match a non-empty string +enclosed in parentheses up to two levels deep. Then the following +regexp matches: + + $x = "abc(de(fg)h"; # unbalanced parentheses + $x =~ /\( ( [^()]+ | \([^()]*\) )+ \)/x; + +The regexp matches an open parenthesis, one or more copies of an +alternation, and a close parenthesis. The alternation is two-way, with +the first alternative C<[^()]+> matching a substring with no +parentheses and the second alternative C<\([^()]*\)> matching a +substring delimited by parentheses. The problem with this regexp is +that it is pathological: it has nested indeterminate quantifiers + of the form C<(a+|b)+>. We discussed in Part 1 how nested quantifiers +like this could take an exponentially long time to execute if there +was no match possible. To prevent the exponential blowup, we need to +prevent useless backtracking at some point. This can be done by +enclosing the inner quantifier as an independent subexpression: + + $x =~ /\( ( (?>[^()]+) | \([^()]*\) )+ \)/x; + +Here, C<< (?>[^()]+) >> breaks the degeneracy of string partitioning +by gobbling up as much of the string as possible and keeping it. Then +match failures fail much more quickly. + +=head2 Conditional expressions + +A S<B<conditional expression> > is a form of if-then-else statement +that allows one to choose which patterns are to be matched, based on +some condition. There are two types of conditional expression: +C<(?(condition)yes-regexp)> and +C<(?(condition)yes-regexp|no-regexp)>. C<(?(condition)yes-regexp)> is +like an S<C<'if () {}'> > statement in Perl. If the C<condition> is true, +the C<yes-regexp> will be matched. If the C<condition> is false, the +C<yes-regexp> will be skipped and perl will move onto the next regexp +element. The second form is like an S<C<'if () {} else {}'> > statement +in Perl. If the C<condition> is true, the C<yes-regexp> will be +matched, otherwise the C<no-regexp> will be matched. + +The C<condition> can have two forms. The first form is simply an +integer in parentheses C<(integer)>. It is true if the corresponding +backreference C<\integer> matched earlier in the regexp. The second +form is a bare zero width assertion C<(?...)>, either a +lookahead, a lookbehind, or a code assertion (discussed in the next +section). + +The integer form of the C<condition> allows us to choose, with more +flexibility, what to match based on what matched earlier in the +regexp. This searches for words of the form C<"$x$x"> or +C<"$x$y$y$x">: + + % simple_grep '^(\w+)(\w+)?(?(2)\2\1|\1)$' /usr/dict/words + beriberi + coco + couscous + deed + ... + toot + toto + tutu + +The lookbehind C<condition> allows, along with backreferences, +an earlier part of the match to influence a later part of the +match. For instance, + + /[ATGC]+(?(?<=AA)G|C)$/; + +matches a DNA sequence such that it either ends in C<AAG>, or some +other base pair combination and C<C>. Note that the form is +C<< (?(?<=AA)G|C) >> and not C<< (?((?<=AA))G|C) >>; for the +lookahead, lookbehind or code assertions, the parentheses around the +conditional are not needed. + +=head2 A bit of magic: executing Perl code in a regular expression + +Normally, regexps are a part of Perl expressions. +S<B<Code evaluation> > expressions turn that around by allowing +arbitrary Perl code to be a part of of a regexp. A code evaluation +expression is denoted C<(?{code})>, with C<code> a string of Perl +statements. + +Code expressions are zero-width assertions, and the value they return +depends on their environment. There are two possibilities: either the +code expression is used as a conditional in a conditional expression +C<(?(condition)...)>, or it is not. If the code expression is a +conditional, the code is evaluated and the result (i.e., the result of +the last statement) is used to determine truth or falsehood. If the +code expression is not used as a conditional, the assertion always +evaluates true and the result is put into the special variable +C<$^R>. The variable C<$^R> can then be used in code expressions later +in the regexp. Here are some silly examples: + + $x = "abcdef"; + $x =~ /abc(?{print "Hi Mom!";})def/; # matches, + # prints 'Hi Mom!' + $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn't match, + # no 'Hi Mom!' + $x =~ /abc(?{print "Hi Mom!";})ddd/; # doesn't match, + # no 'Hi Mom!' + $x =~ /(?{print "Hi Mom!";})/; # matches, + # prints 'Hi Mom!' + $x =~ /(?{$c = 1;})(?{print "$c";})/; # matches, + # prints '1' + $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches, + # prints '1' + +The bit of magic mentioned in the section title occurs when the regexp +backtracks in the process of searching for a match. If the regexp +backtracks over a code expression and if the variables used within are +localized using C<local>, the changes in the variables produced by the +code expression are undone! Thus, if we wanted to count how many times +a character got matched inside a group, we could use, e.g., + + $x = "aaaa"; + $count = 0; # initialize 'a' count + $c = "bob"; # test if $c gets clobbered + $x =~ /(?{local $c = 0;}) # initialize count + ( a # match 'a' + (?{local $c = $c + 1;}) # increment count + )* # do this any number of times, + aa # but match 'aa' at the end + (?{$count = $c;}) # copy local $c var into $count + /x; + print "'a' count is $count, \$c variable is '$c'\n"; + +This prints + + 'a' count is 2, $c variable is 'bob' + +If we replace the S<C< (?{local $c = $c + 1;})> > with +S<C< (?{$c = $c + 1;})> >, the variable changes are I<not> undone +during backtracking, and we get + + 'a' count is 4, $c variable is 'bob' + +Note that only localized variable changes are undone. Other side +effects of code expression execution are permanent. Thus + + $x = "aaaa"; + $x =~ /(a(?{print "Yow\n";}))*aa/; + +produces + + Yow + Yow + Yow + Yow + +The result C<$^R> is automatically localized, so that it will behave +properly in the presence of backtracking. + +This example uses a code expression in a conditional to match the +article 'the' in either English or German: + + $lang = 'DE'; # use German + ... + $text = "das"; + print "matched\n" + if $text =~ /(?(?{ + $lang eq 'EN'; # is the language English? + }) + the | # if so, then match 'the' + (die|das|der) # else, match 'die|das|der' + ) + /xi; + +Note that the syntax here is C<(?(?{...})yes-regexp|no-regexp)>, not +C<(?((?{...}))yes-regexp|no-regexp)>. In other words, in the case of a +code expression, we don't need the extra parentheses around the +conditional. + +If you try to use code expressions with interpolating variables, perl +may surprise you: + + $bar = 5; + $pat = '(?{ 1 })'; + /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated + /foo(?{ 1 })$bar/; # compile error! + /foo${pat}bar/; # compile error! + + $pat = qr/(?{ $foo = 1 })/; # precompile code regexp + /foo${pat}bar/; # compiles ok + +If a regexp has (1) code expressions and interpolating variables,or +(2) a variable that interpolates a code expression, perl treats the +regexp as an error. If the code expression is precompiled into a +variable, however, interpolating is ok. The question is, why is this +an error? + +The reason is that variable interpolation and code expressions +together pose a security risk. The combination is dangerous because +many programmers who write search engines often take user input and +plug it directly into a regexp: + + $regexp = <>; # read user-supplied regexp + $chomp $regexp; # get rid of possible newline + $text =~ /$regexp/; # search $text for the $regexp + +If the C<$regexp> variable contains a code expression, the user could +then execute arbitrary Perl code. For instance, some joker could +search for S<C<system('rm -rf *');> > to erase your files. In this +sense, the combination of interpolation and code expressions B<taints> +your regexp. So by default, using both interpolation and code +expressions in the same regexp is not allowed. If you're not +concerned about malicious users, it is possible to bypass this +security check by invoking S<C<use re 'eval'> >: + + use re 'eval'; # throw caution out the door + $bar = 5; + $pat = '(?{ 1 })'; + /foo(?{ 1 })$bar/; # compiles ok + /foo${pat}bar/; # compiles ok + +Another form of code expression is the S<B<pattern code expression> >. +The pattern code expression is like a regular code expression, except +that the result of the code evaluation is treated as a regular +expression and matched immediately. A simple example is + + $length = 5; + $char = 'a'; + $x = 'aaaaabb'; + $x =~ /(??{$char x $length})/x; # matches, there are 5 of 'a' + + +This final example contains both ordinary and pattern code +expressions. It detects if a binary string C<1101010010001...> has a +Fibonacci spacing 0,1,1,2,3,5,... of the C<1>'s: + + $s0 = 0; $s1 = 1; # initial conditions + $x = "1101010010001000001"; + print "It is a Fibonacci sequence\n" + if $x =~ /^1 # match an initial '1' + ( + (??{'0' x $s0}) # match $s0 of '0' + 1 # and then a '1' + (?{ + $largest = $s0; # largest seq so far + $s2 = $s1 + $s0; # compute next term + $s0 = $s1; # in Fibonacci sequence + $s1 = $s2; + }) + )+ # repeat as needed + $ # that is all there is + /x; + print "Largest sequence matched was $largest\n"; + +This prints + + It is a Fibonacci sequence + Largest sequence matched was 5 + +Ha! Try that with your garden variety regexp package... + +Note that the variables C<$s0> and C<$s1> are not substituted when the +regexp is compiled, as happens for ordinary variables outside a code +expression. Rather, the code expressions are evaluated when perl +encounters them during the search for a match. + +The regexp without the C<//x> modifier is + + /^1((??{'0'x$s0})1(?{$largest=$s0;$s2=$s1+$s0$s0=$s1;$s1=$s2;}))+$/; + +and is a great start on an Obfuscated Perl entry :-) When working with +code and conditional expressions, the extended form of regexps is +almost necessary in creating and debugging regexps. + +=head2 Pragmas and debugging + +Speaking of debugging, there are several pragmas available to control +and debug regexps in Perl. We have already encountered one pragma in +the previous section, S<C<use re 'eval';> >, that allows variable +interpolation and code expressions to coexist in a regexp. The other +pragmas are + + use re 'taint'; + $tainted = <>; + @parts = ($tainted =~ /(\w+)\s+(\w+)/; # @parts is now tainted + +The C<taint> pragma causes any substrings from a match with a tainted +variable to be tainted as well. This is not normally the case, as +regexps are often used to extract the safe bits from a tainted +variable. Use C<taint> when you are not extracting safe bits, but are +performing some other processing. Both C<taint> and C<eval> pragmas +are lexically scoped, which means they are in effect only until +the end of the block enclosing the pragmas. + + use re 'debug'; + /^(.*)$/s; # output debugging info + + use re 'debugcolor'; + /^(.*)$/s; # output debugging info in living color + +The global C<debug> and C<debugcolor> pragmas allow one to get +detailed debugging info about regexp compilation and +execution. C<debugcolor> is the same as debug, except the debugging +information is displayed in color on terminals that can display +termcap color sequences. Here is example output: + + % perl -e 'use re "debug"; "abc" =~ /a*b+c/;' + Compiling REx `a*b+c' + size 9 first at 1 + 1: STAR(4) + 2: EXACT <a>(0) + 4: PLUS(7) + 5: EXACT <b>(0) + 7: EXACT <c>(9) + 9: END(0) + floating `bc' at 0..2147483647 (checking floating) minlen 2 + Guessing start of match, REx `a*b+c' against `abc'... + Found floating substr `bc' at offset 1... + Guessed: match at offset 0 + Matching REx `a*b+c' against `abc' + Setting an EVAL scope, savestack=3 + 0 <> <abc> | 1: STAR + EXACT <a> can match 1 times out of 32767... + Setting an EVAL scope, savestack=3 + 1 <a> <bc> | 4: PLUS + EXACT <b> can match 1 times out of 32767... + Setting an EVAL scope, savestack=3 + 2 <ab> <c> | 7: EXACT <c> + 3 <abc> <> | 9: END + Match successful! + Freeing REx: `a*b+c' + +If you have gotten this far into the tutorial, you can probably guess +what the different parts of the debugging output tell you. The first +part + + Compiling REx `a*b+c' + size 9 first at 1 + 1: STAR(4) + 2: EXACT <a>(0) + 4: PLUS(7) + 5: EXACT <b>(0) + 7: EXACT <c>(9) + 9: END(0) + +describes the compilation stage. C<STAR(4)> means that there is a +starred object, in this case C<'a'>, and if it matches, goto line 4, +i.e., C<PLUS(7)>. The middle lines describe some heuristics and +optimizations performed before a match: + + floating `bc' at 0..2147483647 (checking floating) minlen 2 + Guessing start of match, REx `a*b+c' against `abc'... + Found floating substr `bc' at offset 1... + Guessed: match at offset 0 + +Then the match is executed and the remaining lines describe the +process: + + Matching REx `a*b+c' against `abc' + Setting an EVAL scope, savestack=3 + 0 <> <abc> | 1: STAR + EXACT <a> can match 1 times out of 32767... + Setting an EVAL scope, savestack=3 + 1 <a> <bc> | 4: PLUS + EXACT <b> can match 1 times out of 32767... + Setting an EVAL scope, savestack=3 + 2 <ab> <c> | 7: EXACT <c> + 3 <abc> <> | 9: END + Match successful! + Freeing REx: `a*b+c' + +Each step is of the form S<C<< n <x> <y> >> >, with C<< <x> >> the +part of the string matched and C<< <y> >> the part not yet +matched. The S<C<< | 1: STAR >> > says that perl is at line number 1 +n the compilation list above. See +L<perldebguts/"Debugging regular expressions"> for much more detail. + +An alternative method of debugging regexps is to embed C<print> +statements within the regexp. This provides a blow-by-blow account of +the backtracking in an alternation: + + "that this" =~ m@(?{print "Start at position ", pos, "\n";}) + t(?{print "t1\n";}) + h(?{print "h1\n";}) + i(?{print "i1\n";}) + s(?{print "s1\n";}) + | + t(?{print "t2\n";}) + h(?{print "h2\n";}) + a(?{print "a2\n";}) + t(?{print "t2\n";}) + (?{print "Done at position ", pos, "\n";}) + @x; + +prints + + Start at position 0 + t1 + h1 + t2 + h2 + a2 + t2 + Done at position 4 + +=head1 BUGS + +Code expressions, conditional expressions, and independent expressions +are B<experimental>. Don't use them in production code. Yet. + +=head1 SEE ALSO + +This is just a tutorial. For the full story on perl regular +expressions, see the L<perlre> regular expressions reference page. + +For more information on the matching C<m//> and substitution C<s///> +operators, see L<perlop/"Regexp Quote-Like Operators">. For +information on the C<split> operation, see L<perlfunc/split>. + +For an excellent all-around resource on the care and feeding of +regular expressions, see the book I<Mastering Regular Expressions> by +Jeffrey Friedl (published by O'Reilly, ISBN 1556592-257-3). + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 2000 Mark Kvale +All rights reserved. + +This document may be distributed under the same terms as Perl itself. + +=head2 Acknowledgments + +The inspiration for the stop codon DNA example came from the ZIP +code example in chapter 7 of I<Mastering Regular Expressions>. + +The author would like to thank Jeff Pinyan, Andrew Johnson, Peter +Haworth, Ronald J Kimball, and Joe Smith for all their helpful +comments. + +=cut + diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 5cc1969c60..e105b00a7a 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -701,8 +701,7 @@ can disable or promote into fatal errors specific warnings using C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>. See also L<perldiag> and L<perltrap>. A new, fine-grained warning facility is also available if you want to manipulate entire classes -of warnings; see L<warnings> (or better yet, its source code) about -that. +of warnings; see L<warnings> or L<perllexwarn>. =item B<-W> @@ -810,6 +809,18 @@ Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other references. +=item PERL_ROOT (specific to the VMS port) + +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 +L<perlvms> and in F<README.vms> in the Perl source distribution. + +=item SYS$LOGIN (specific to the VMS port) + +Used if chdir has no argument and HOME and LOGDIR are not set. + =back Perl also has environment variables that control how Perl handles data diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 40374870a1..4185e84803 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -32,17 +32,19 @@ program more secure than the corresponding C program. You may not use data derived from outside your program to affect something else outside your program--at least, not by accident. All command line arguments, environment variables, locale information (see -L<perllocale>), results of certain system calls (readdir, readlink, -the gecos field of getpw* calls), and all file input are marked as -"tainted". Tainted data may not be used directly or indirectly in any -command that invokes a sub-shell, nor in any command that modifies -files, directories, or processes. (B<Important exception>: If you pass -a list of arguments to either C<system> or C<exec>, the elements of -that list are B<NOT> checked for taintedness.) Any variable set -to a value derived from tainted data will itself be tainted, -even if it is logically impossible for the tainted data -to alter the variable. Because taintedness is associated with each -scalar value, some elements of an array can be tainted and others not. +L<perllocale>), results of certain system calls (readdir(), +readlink(), the variable of shmread(), the messages returned by +msgrcv(), the password, gcos and shell fields returned by the +getpwxxx() calls), and all file input are marked as "tainted". +Tainted data may not be used directly or indirectly in any command +that invokes a sub-shell, nor in any command that modifies files, +directories, or processes. (B<Important exception>: If you pass a list +of arguments to either C<system> or C<exec>, the elements of that list +are B<NOT> checked for taintedness.) Any variable set to a value +derived from tainted data will itself be tainted, even if it is +logically impossible for the tainted data to alter the variable. +Because taintedness is associated with each scalar value, some +elements of an array can be tainted and others not. For example: diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod index 04aab9854a..bfe5b76713 100644 --- a/pod/perlstyle.pod +++ b/pod/perlstyle.pod @@ -10,7 +10,8 @@ make your programs easier to read, understand, and maintain. The most important thing is to run your programs under the B<-w> flag at all times. You may turn it off explicitly for particular -portions of code via the C<$^W> variable if you must. You should +portions of code via the C<use warnings> pragma or the C<$^W> variable +if you must. You should also always run under C<use strict> or know the reason why not. The C<use sigtrap> and even C<use diagnostics> pragmas may also prove useful. @@ -260,7 +261,8 @@ Line up your transliterations when it makes sense: Think about reusability. Why waste brainpower on a one-shot when you might want to do something like it again? Consider generalizing your code. Consider writing a module or object class. Consider making your -code run cleanly with C<use strict> and B<-w> in effect. Consider giving away +code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in effect +Consider giving away your code. Consider changing your whole world view. Consider... oh, never mind. diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 46d1a2a2b0..f1b87923ef 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -154,7 +154,7 @@ of changing them in place: } Notice how this (unprototyped) function doesn't care whether it was -passed real scalars or arrays. Perl sees all arugments as one big, +passed real scalars or arrays. Perl sees all arguments as one big, long, flat parameter list in C<@_>. This is one area where Perl's simple argument-passing style shines. The C<upcase()> function would work perfectly well without changing the C<upcase()> @@ -1270,7 +1270,7 @@ see L<attributes>. See L<perlref/"Function Templates"> for more about references and closures. See L<perlxs> if you'd like to learn about calling C subroutines from Perl. -See L<perlembed> if you'd like to learn about calling PErl subroutines from C. +See L<perlembed> if you'd like to learn about calling Perl subroutines from C. See L<perlmod> to learn about bundling up your functions in separate files. See L<perlmodlib> to learn what library modules come standard on your system. See L<perltoot> to learn how to make object method calls. diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index 7b9590e4de..dfded2ecde 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -171,7 +171,8 @@ statements C<next>, C<last>, and C<redo>. If the LABEL is omitted, the loop control statement refers to the innermost enclosing loop. This may include dynamically looking back your call-stack at run time to find the LABEL. Such -desperate behavior triggers a warning if you use the B<-w> flag. +desperate behavior triggers a warning if you use the C<use warnings> +pragma or the B<-w> flag. Unlike a C<foreach> statement, a C<while> statement never implicitly localises any variables. @@ -323,7 +324,7 @@ Examples: for (@ary) { s/foo/bar/ } - foreach my $elem (@elements) { + for my $elem (@elements) { $elem *= 2; } @@ -352,8 +353,8 @@ Here's how a C programmer might code up a particular algorithm in Perl: Whereas here's how a Perl programmer more comfortable with the idiom might do it: - OUTER: foreach my $wid (@ary1) { - INNER: foreach my $jet (@ary2) { + OUTER: for my $wid (@ary1) { + INNER: for my $jet (@ary2) { next OUTER if $wid > $jet; $wid += $jet; } @@ -482,7 +483,7 @@ Or Or if you are certainly that all the C<&&> clauses are true, you can use something like this, which "switches" on the value of the -C<HTTP_USER_AGENT> envariable. +C<HTTP_USER_AGENT> environment variable. #!/usr/bin/perl # pick out jargon file page based on browser @@ -524,7 +525,7 @@ The C<goto>-EXPR form expects a label name, whose scope will be resolved dynamically. This allows for computed C<goto>s per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability: - goto ("FOO", "BAR", "GLARCH")[$i]; + goto(("FOO", "BAR", "GLARCH")[$i]); The C<goto>-&NAME form is highly magical, and substitutes a call to the named subroutine for the currently running subroutine. This is used by diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod index 88849dd662..3a1cf866e2 100644 --- a/pod/perlthrtut.pod +++ b/pod/perlthrtut.pod @@ -4,6 +4,14 @@ perlthrtut - tutorial on threads in Perl =head1 DESCRIPTION + WARNING: Threading is an experimental feature. Both the interface + and implementation are subject to change drastically. In fact, this + documentation describes the flavor of threads that was in version + 5.005. Perl 5.6.0 and later have the beginnings of support for + interpreter threads, which (when finished) is expected to be + significantly different from what is described here. The information + contained here may therefore soon be obsolete. Use at your own risk! + One of the most prominent new features of Perl 5.005 is the inclusion of threads. Threads make a number of things a lot easier, and are a very useful addition to your bag of programming tricks. @@ -389,7 +397,7 @@ to get them. =head2 Ignoring A Thread -join() does three things:it waits for a thread to exit, cleans up +join() does three things: it waits for a thread to exit, cleans up after it, and returns any data the thread may have produced. But what if you're not interested in the thread's return values, and you don't really care when the thread finishes? All you want is for the thread @@ -435,10 +443,10 @@ more than one thread can be accessing this data at once. Perl's scoping rules don't change because you're using threads. If a subroutine (or block, in the case of async()) could see a variable if you weren't running with threads, it can see it if you are. This is -especially important for the subroutines that create, and makes my +especially important for the subroutines that create, and makes C<my> variables even more important. Remember--if your variables aren't -lexically scoped (declared with C<my>) you're probably sharing it between -threads. +lexically scoped (declared with C<my>) you're probably sharing them +between threads. =head2 Thread Pitfall: Races @@ -710,7 +718,7 @@ In addition to synchronizing access to data or resources, you might find it useful to synchronize access to subroutines. You may be accessing a singular machine resource (perhaps a vector processor), or find it easier to serialize calls to a particular subroutine than to -have a set of locks and sempahores. +have a set of locks and semaphores. One of the additions to Perl 5.005 is subroutine attributes. The Thread package uses these to provide several flavors of @@ -1021,7 +1029,7 @@ LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1. Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, -1995, ISBN 0-13-143934-0 (great textbook). +1995, ISBN 0-13-219908-4 (great textbook). Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4 diff --git a/pod/perltie.pod b/pod/perltie.pod index 92040528e9..95de3bb928 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -743,6 +743,7 @@ a scalar. package Remember; use strict; + use warnings; use IO::File; sub TIESCALAR { @@ -845,7 +846,8 @@ have not been flushed to disk. Now that you know what the problem is, what can you do to avoid it? Well, the good old C<-w> flag will spot any instances where you call untie() and there are still valid references to the tied object. If -the second script above is run with the C<-w> flag, Perl prints this +the second script above this near the top C<use warnings 'untie'> +or was run with the C<-w> flag, Perl prints this warning message: untie attempted while 1 inner references still exist @@ -860,14 +862,11 @@ called: =head1 SEE ALSO See L<DB_File> or L<Config> for some interesting tie() implementations. +A good starting point for many tie() implementations is with one of the +modules L<Tie::Scalar>, L<Tie::Array>, L<Tie::Hash>, or L<Tie::Handle>. =head1 BUGS -Tied arrays are I<incomplete>. They are also distinctly lacking something -for the C<$#ARRAY> access (which is hard, as it's an lvalue), as well as -the other obvious array functions, like push(), pop(), shift(), unshift(), -and splice(). - You cannot easily tie a multilevel data structure (such as a hash of hashes) to a dbm file. The first problem is that all but GDBM and Berkeley DB have size limitations, but beyond that, you also have problems diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 0a67fdc232..6397388e5d 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -95,8 +95,8 @@ line?, Why don't perl one-liners work on my DOS/Mac/VMS system?, Where can I learn about CGI or Web programming in Perl?, Where can I learn about object-oriented Perl programming?, Where can I learn about linking C with Perl? [h2xs, xsubpp], I've read perlembed, perlguts, etc., but I can't -embed perl inmy C program, what am I doing wrong?, When I tried to run my -script, I got this message. What does itmean?, What's MakeMaker?, +embed perl in my C program, what am I doing wrong?, When I tried to run my +script, I got this message. What does it mean?, What's MakeMaker?, L<perlfaq4>: Data Manipulation, Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?, Why isn't my octal data interpreted correctly?, Does Perl have a round() @@ -121,10 +121,10 @@ How do I strip blank space from the beginning/end of a string?, How do I pad a string with blanks or pad a number with zeroes?, How do I extract selected columns from a string?, How do I find the soundex value of a string?, How can I expand variables in text strings?, What's wrong with -always quoting "$vars"?, Why don't my E<lt>E<lt>HERE documents work?, What -is the difference between a list and an array?, What is the difference -between $array[1] and @array[1]?, How can I remove duplicate elements from -a list or array?, How can I tell whether a list or array contains a certain +always quoting "$vars"?, Why don't my <<HERE documents work?, What is the +difference between a list and an array?, What is the difference between +$array[1] and @array[1]?, How can I remove duplicate elements from a list +or array?, How can I tell whether a list or array contains a certain element?, How do I compute the difference of two arrays? How do I compute the intersection of two arrays?, How do I test whether two arrays or hashes are equal?, How do I find the first array element for which a condition is @@ -161,16 +161,16 @@ How can I use a filehandle indirectly?, How can I set up a footer format to be used with write()?, How can I write() into a string?, How can I output my numbers with commas added?, How can I translate tildes (~) in a filename?, How come when I open a file read-write it wipes it out?, Why do -I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?, Is -there a leak/bug in glob()?, How can I open a file with a leading "E<gt>" -or trailing blanks?, How can I reliably rename a file?, How can I lock a -file?, Why can't I just open(FH, ">file.lock")?, I still don't get locking. - I just want to increment the number in the file. How can I do this?, How -do I randomly update a binary file?, How do I get a file's timestamp in -perl?, How do I set a file's timestamp in perl?, How do I print to more -than one file at once?, How can I read in an entire file all at once?, How -can I read in a file by paragraphs?, How can I read a single character from -a file? From the keyboard?, How can I tell whether there's a character +I sometimes get an "Argument list too long" when I use <*>?, Is there a +leak/bug in glob()?, How can I open a file with a leading ">" or trailing +blanks?, How can I reliably rename a file?, How can I lock a file?, Why +can't I just open(FH, ">file.lock")?, I still don't get locking. I just +want to increment the number in the file. How can I do this?, How do I +randomly update a binary file?, How do I get a file's timestamp in perl?, +How do I set a file's timestamp in perl?, How do I print to more than one +file at once?, How can I read in an entire file all at once?, How can I +read in a file by paragraphs?, How can I read a single character from a +file? From the keyboard?, How can I tell whether there's a character waiting on a filehandle?, How do I do a C<tail -f> in perl?, How do I dup() a filehandle in Perl?, How do I close a file descriptor by number?, Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` @@ -210,10 +210,10 @@ Array, Hash, Method, Regex}?, How do I create a static variable?, What's the difference between dynamic and lexical (static) scoping? Between local() and my()?, How can I access a dynamic variable while a similarly named lexical is in scope?, What's the difference between deep and shallow -binding?, Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?, How do I -redefine a builtin function, operator, or method?, What's the difference -between calling a function as &foo and foo()?, How do I create a switch or -case statement?, How can I catch accesses to undefined +binding?, Why doesn't "my($foo) = <FILE>;" work right?, How do I redefine a +builtin function, operator, or method?, What's the difference between +calling a function as &foo and foo()?, How do I create a switch or case +statement?, How can I catch accesses to undefined variables/functions/methods?, Why can't a method included in this same file be found?, How can I find out my current package?, How can I comment out a large block of perl code?, How do I clear a package?, How can I use a @@ -382,10 +382,7 @@ What does CPAN/src/... mean? =item Perl Books -References, Tutorials - *Learning Perl [2nd edition] - by Randal L. Schwartz and Tom Christiansen - with foreword by Larry Wall, Task-Oriented, Special Topics +References, Tutorials, Task-Oriented, Special Topics =item Perl in Magazines @@ -585,7 +582,7 @@ string? =item What's wrong with always quoting "$vars"? -=item Why don't my E<lt>E<lt>HERE documents work? +=item Why don't my <<HERE documents work? 1. There must be no space after the << part, 2. There (probably) should be a semicolon at the end, 3. You can't (easily) have any space in front of @@ -736,12 +733,11 @@ filehandles between subroutines? How do I make an array of filehandles? =item How come when I open a file read-write it wipes it out? -=item Why do I sometimes get an "Argument list too long" when I use -E<lt>*E<gt>? +=item Why do I sometimes get an "Argument list too long" when I use <*>? =item Is there a leak/bug in glob()? -=item How can I open a file with a leading "E<gt>" or trailing blanks? +=item How can I open a file with a leading ">" or trailing blanks? =item How can I reliably rename a file? @@ -911,7 +907,7 @@ is in scope? =item What's the difference between deep and shallow binding? -=item Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right? +=item Why doesn't "my($foo) = <FILE>;" work right? =item How do I redefine a builtin function, operator, or method? @@ -1133,222 +1129,207 @@ CGI script to do bad things? =back -=head2 perldelta - what's new for perl v5.6 (as of v5.005_64) +=head2 perldelta - what's new for perl v5.6.0 =over =item DESCRIPTION -=item Incompatible Changes +=item Core Enhancements =over -=item Perl Source Incompatibilities - -CHECK is a new keyword, Treatment of list slices of undef has changed - -=item Perl's version numbering has changed - -Literals of the form C<1.2.3> parse differently, Possibly changed -pseudo-random number generator, Hashing function for hash keys has changed, -C<undef> fails on read only values, Close-on-exec bit may be set on pipe -and socket handles, Writing C<"$$1"> to mean C<"${$}1"> is unsupported, -delete(), values() and C<\(%h)> operate on aliases to values, not copies, -vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic -output has changed, C<%@> has been removed, Parenthesized not() behaves -like a list operator, Semantics of bareword prototype C<(*)> have changed - -=item On 64-bit platforms the semantics of bit operators have changed - -=item C Source Incompatibilities +=item Interpreter cloning, threads, and concurrency -C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC> +=item Lexically scoped warning categories -=item Compatible C Source API Changes +=item Unicode and UTF-8 support -C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions +=item Support for interpolating named characters -=item Binary Incompatibilities +=item "our" declarations -=back +=item Support for strings represented as a vector of ordinals -=item Installation and Configuration Improvements +=item Improved Perl version numbering system -=over +=item New syntax for declaring subroutine attributes -=item -Dusethreads means something different +=item File and directory handles can be autovivified -=item New Configure flags +=item open() with more than two arguments -=item Threadedness and 64-bitness now more daring +=item 64-bit support -=item Long Doubles +=item Large file support -=item -Dusemorebits +=item Long doubles -=item -Duselargefiles +=item "more bits" -=item installusrbinperl +=item Enhanced support for sort() subroutines -=item SOCKS support +=item C<sort $coderef @foo> allowed -=item C<-A> flag +=item File globbing implemented internally -=item Enhanced Installation Directories +Support for CHECK blocks -=back +=item POSIX character class syntax [: :] supported -=item Core Changes +Better pseudo-random number generator -=over +=item Improved C<qw//> operator -=item Unicode and UTF-8 support +Better worst-case behavior of hashes -=item Interpreter cloning, threads, and concurrency - -=item Lexically scoped warning categories +=item pack() format 'Z' supported -=item Lvalue subroutines +=item pack() format modifier '!' supported -=item "our" declarations +=item pack() and unpack() support counted strings -=item Support for strings represented as a vector of ordinals +=item Comments in pack() templates =item Weak references -=item File globbing implemented internally - =item Binary numbers supported +=item Lvalue subroutines + =item Some arrows may be omitted in calls through references +=item Boolean assignment operators are legal lvalues + =item exists() is supported on subroutine names =item exists() and delete() are supported on array elements -=item syswrite() ease-of-use - -=item File and directory handles can be autovivified - -=item 64-bit support - -=item Large file support - -=item Long doubles - -=item "more bits" +=item Pseudo-hashes work better -=item Enhanced support for sort() subroutines +=item Automatic flushing of output buffers -=item Better syntax checks on parenthesized unary operators +=item Better diagnostics on meaningless filehandle operations -=item POSIX character class syntax [: :] supported +=item Where possible, buffered data discarded from duped input filehandle -=item Improved C<qw//> operator +=item eof() has the same old magic as <> -=item pack() format 'Z' supported +=item binmode() can be used to set :crlf and :raw modes -=item pack() format modifier '!' supported +=item C<-T> filetest recognizes UTF-8 encoded files as "text" -=item pack() and unpack() support counted strings +=item system(), backticks and pipe open now reflect exec() failure -=item Comments in pack() templates +=item Improved diagnostics -=item $^X variables may now have names longer than one character +=item Diagnostics follow STDERR -=item C<use attrs> implicit in subroutine attributes +More consistent close-on-exec behavior -=item Regular expression improvements +=item syswrite() ease-of-use -=item Overloading improvements +=item Better syntax checks on parenthesized unary operators -=item open() with more than two arguments +=item Bit operators support full native integer width -=item Support for interpolating named characters +=item Improved security features -=item Experimental support for user-hooks in @INC +More functional bareword prototype (*) =item C<require> and C<do> may be overridden +=item $^X variables may now have names longer than one character + =item New variable $^C reflects C<-c> switch -=item New variable $^V contains Perl version in v5.6.0 format +=item New variable $^V contains Perl version as a string =item Optional Y2K warnings =back -=item Significant bug fixes +=item Modules and Pragmata =over -=item E<lt>HANDLEE<gt> on empty files +=item Modules -=item C<eval '...'> improvements +attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper, +DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English, +Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec, +File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt, +Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker, +podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage, +pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname, +Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters -=item All compilation errors are true errors +=item Pragmata -=item Automatic flushing of output buffers +=back -=item Better diagnostics on meaningless filehandle operations +=item Utility Changes -=item Where possible, buffered data discarded from duped input filehandle +=over -=item eof() has the same old magic as <> +=item dprofpp -=item system(), backticks and pipe open now reflect exec() failure +=item find2perl -=item Implicitly closed filehandles are safer +=item h2xs -=item C<(\$)> prototype and C<$foo{a}> +=item perlcc -=item Pseudo-hashes work better +=item perldoc -=item C<goto &sub> and AUTOLOAD +=item The Perl Debugger -=item C<-bareword> allowed under C<use integer> +=back -=item Boolean assignment operators are legal lvalues +=item Improved Documentation -=item C<sort $coderef @foo> allowed +perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod, +perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod, +perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod, +perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod -=item Failures in DESTROY() +=item Performance enhancements -=item Locale bugs fixed +=over -=item Memory leaks +=item Simple sort() using { $a <=> $b } and the like are optimized -=item Spurious subroutine stubs after failed subroutine calls +=item Optimized assignments to lexical variables -=item Consistent numeric conversions +=item Faster subroutine calls -=item Taint failures under C<-U> +delete(), each(), values() and hash iteration are faster -=item END blocks and the C<-c> switch +=back -=item Potential to leak DATA filehandles +=item Installation and Configuration Improvements -=item Diagnostics follow STDERR +=over -=item Other fixes for better diagnostics +=item -Dusethreads means something different -=back +=item New Configure flags -=item Performance enhancements +=item Threadedness and 64-bitness now more daring -=over +=item Long Doubles -=item Simple sort() using { $a <=> $b } and the like are optimized +=item -Dusemorebits -=item Optimized assignments to lexical variables +=item -Duselargefiles -=item Method lookups optimized +=item installusrbinperl -=item Faster mechanism to invoke XSUBs +=item SOCKS support -=item Perl_malloc() improvements +=item C<-A> flag -=item Faster subroutine calls +=item Enhanced Installation Directories =back @@ -1356,11 +1337,11 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions =over -=item Additional supported platforms +=item Supported platforms =item DOS -=item OS/2 +=item OS390 (OpenEdition MVS) =item VMS @@ -1368,44 +1349,41 @@ C<PATCHLEVEL> is now C<PERL_VERSION>, Support for C++ exceptions =back -=item New tests - -=item Modules and Pragmata +=item Significant bug fixes =over -=item Modules +=item <HANDLE> on empty files -attributes, B, ByteLoader, constant, charnames, Data::Dumper, DB, DB_File, -Devel::DProf, Dumpvalue, Benchmark, Devel::Peek, English, -ExtUtils::MakeMaker, Fcntl, File::Compare, File::Find, File::Glob, -File::Spec, File::Spec::Functions, Getopt::Long, IO, JPL, lib, -Math::BigInt, Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, -Pod::Checker, podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, -podselect, Pod::Usage, pod2usage, Pod::Text and Pod::Man, SDBM_File, -Sys::Syslog, Sys::Hostname, Time::Local, Win32, DBM Filters +=item C<eval '...'> improvements -=item Pragmata +=item All compilation errors are true errors -=back +=item Implicitly closed filehandles are safer -=item Utility Changes +=item Behavior of list slices is more consistent -=over +=item C<(\$)> prototype and C<$foo{a}> -=item h2ph +=item C<goto &sub> and AUTOLOAD -=item perlcc +=item C<-bareword> allowed under C<use integer> -=item h2xs +=item Failures in DESTROY() -=back +=item Locale bugs fixed -=item Documentation Changes +=item Memory leaks + +=item Spurious subroutine stubs after failed subroutine calls -perlapi.pod, perlcompile.pod, perlfilter.pod, perlhack.pod, perlintern.pod, -perlopentut.pod, perlreftut.pod, perlboot.pod, perltootc.pod, -perlunicode.pod +=item Taint failures under C<-U> + +=item END blocks and the C<-c> switch + +=item Potential to leak DATA filehandles + +=back =item New or Changed Diagnostics @@ -1418,46 +1396,114 @@ passed through, /%s/ should probably be written as "%s", %s() called too early to check prototype, %s argument is not a HASH or ARRAY element, %s argument is not a HASH or ARRAY element or slice, %s argument is not a subroutine name, %s package attribute may clash with future reserved word: -%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad -evalled substitution pattern, Bad realloc() ignored, Bareword found in -conditional, Binary number > 0b11111111111111111111111111111111 -non-portable, Bit vector size > 32 non-portable, Buffer overflow in -prime_env_iter: %s, Can't check filesystem of script "%s", Can't declare -class for non-scalar %s in "%s", Can't declare %s in "%s", Can't ignore -signal CHLD, forcing to default, Can't modify non-lvalue subroutine call, -Can't read CRTL environ, Can't remove %s: %s, skipping file, Can't return -%s from lvalue subroutine, Can't weaken a nonreference, Character class -[:%s:] unknown, Character class syntax [%s] belongs inside character -classes, Constant is not %s reference, constant(%s): %%^H is not localized, -constant(%s): %s, defined(@array) is deprecated, defined(%hash) is -deprecated, Did not produce a valid header, Did you mean "local" instead of -"our"?, Document contains no data, entering effective %s failed, false [] -range "%s" in regexp, Filehandle %s opened only for output, flock() on -closed filehandle %s, Global symbol "%s" requires explicit package name, -Hexadecimal number > 0xffffffff non-portable, Ill-formed CRTL environ value -"%s", Ill-formed message in prime_env_iter: |%s|, Illegal binary digit %s, -Illegal binary digit %s ignored, Illegal number of bits in vec, Integer -overflow in %s number, Invalid %s attribute: %s, Invalid %s attributes: %s, -invalid [] range "%s" in regexp, Invalid separator character %s in -attribute list, Invalid separator character %s in subroutine attribute -list, leaving effective %s failed, Lvalue subs returning %s not implemented -yet, Method %s not permitted, Missing %sbrace%s on \N{}, Missing command in -piped open, Missing name in "my sub", No %s specified for -%c, No package -name allowed for variable %s in "our", No space allowed after -%c, no UTC -offset information; assuming local time is UTC, Octal number > 037777777777 -non-portable, panic: del_backref, panic: kid popen errno read, panic: -magic_killbackrefs, Parentheses missing around "%s" list, Possible Y2K bug: -%s, Premature end of script headers, Repeat count in pack overflows, Repeat -count in unpack overflows, realloc() of freed memory ignored, Reference is -already weak, setpgrp can't take arguments, Strange *+?{} on zero-length -expression, switching effective %s is not implemented, This Perl can't -reset CRTL environ elements (%s), This Perl can't set CRTL environ elements -(%s=%s), Unknown open() mode '%s', Unknown process %x sent message to -prime_env_iter: %s, Unrecognized escape \\%c passed through, Unterminated -attribute parameter in attribute list, Unterminated attribute list, -Unterminated attribute parameter in subroutine attribute list, Unterminated -subroutine attribute list, Value of CLI symbol "%s" too long, Version -number must be a constant number +%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled +substitution pattern, Bad realloc() ignored, Bareword found in conditional, +Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector +size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check +filesystem of script "%s", Can't declare class for non-scalar %s in "%s", +Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default, +Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't +remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't +weaken a nonreference, Character class [:%s:] unknown, Character class +syntax [%s] belongs inside character classes, Constant is not %s reference, +constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated, +defined(%hash) is deprecated, Did not produce a valid header, (Did you mean +"local" instead of "our"?), Document contains no data, entering effective +%s failed, false [] range "%s" in regexp, Filehandle %s opened only for +output, flock() on closed filehandle %s, Global symbol "%s" requires +explicit package name, Hexadecimal number > 0xffffffff non-portable, +Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter: +|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal +number of bits in vec, Integer overflow in %s number, Invalid %s attribute: +%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid +separator character %s in attribute list, Invalid separator character %s in +subroutine attribute list, leaving effective %s failed, Lvalue subs +returning %s not implemented yet, Method %s not permitted, Missing +%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub", +No %s specified for -%c, No package name allowed for variable %s in "our", +No space allowed after -%c, no UTC offset information; assuming local time +is UTC, Octal number > 037777777777 non-portable, panic: del_backref, +panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing +around "%s" list, Possible Y2K bug: %s, pragma "attrs" is deprecated, use +"sub NAME : ATTRS" instead, Premature end of script headers, Repeat count +in pack overflows, Repeat count in unpack overflows, realloc() of freed +memory ignored, Reference is already weak, setpgrp can't take arguments, +Strange *+?{} on zero-length expression, switching effective %s is not +implemented, This Perl can't reset CRTL environ elements (%s), This Perl +can't set CRTL environ elements (%s=%s), Too late to run %s block, Unknown +open() mode '%s', Unknown process %x sent message to prime_env_iter: %s, +Unrecognized escape \\%c passed through, Unterminated attribute parameter +in attribute list, Unterminated attribute list, Unterminated attribute +parameter in subroutine attribute list, Unterminated subroutine attribute +list, Value of CLI symbol "%s" too long, Version number must be a constant +number + +=item New tests + +=item Incompatible Changes + +=over + +=item Perl Source Incompatibilities + +CHECK is a new keyword, Treatment of list slices of undef has changed + +=item Format of $English::PERL_VERSION is different + +Literals of the form C<1.2.3> parse differently, Possibly changed +pseudo-random number generator, Hashing function for hash keys has changed, +C<undef> fails on read only values, Close-on-exec bit may be set on pipe +and socket handles, Writing C<"$$1"> to mean C<"${$}1"> is unsupported, +delete(), values() and C<\(%h)> operate on aliases to values, not copies, +vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic +output has changed, C<%@> has been removed, Parenthesized not() behaves +like a list operator, Semantics of bareword prototype C<(*)> have changed + +=item Semantics of bit operators may have changed on 64-bit platforms + +=item More builtins taint their results + +=item C Source Incompatibilities + +C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC> + +=item Compatible C Source API Changes + +C<PATCHLEVEL> is now C<PERL_VERSION> + +=item Binary Incompatibilities + +=back + +=item Known Problems + +=over + +=item Thread test failures + +=item EBCDIC platforms not supported + +=item In 64-bit HP-UX the lib/io_multihomed test may hang + +=item NEXTSTEP 3.3 POSIX test failure + +=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with +gcc + +=item UNICOS/mk CC failures during Configure run + +=item Arrow operator and arrays + +=item Windows 2000 + +=item Experimental features + +Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The +pseudo-hash data type, The Compiler suite, Internal implementation of file +globbing, The DB module, The regular expression constructs C<(?{ code })> +and C<(??{ code })> + +=back =item Obsolete Diagnostics @@ -1465,7 +1511,7 @@ Character class syntax [: :] is reserved for future extensions, Ill-formed logical name |%s| in prime_env_iter, Probable precedence problem on %s, regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated -=item BUGS +=item Reporting Bugs =item SEE ALSO @@ -1618,8 +1664,6 @@ regular expressions =item Bitwise String Operators -=item Strings of Character - =item Integer Arithmetic =item Floating-point Arithmetic @@ -1647,8 +1691,8 @@ cntrl, graph, print, punct, xdigit =item Extended Patterns C<(?#text)>, C<(?imsx-imsx)>, C<(?:pattern)>, C<(?imsx-imsx:pattern)>, -C<(?=pattern)>, C<(?!pattern)>, C<(?E<lt>=pattern)>, C<(?<!pattern)>, C<(?{ -code })>, C<(??{ code })>, C<(?E<gt>pattern)>, +C<(?=pattern)>, C<(?!pattern)>, C<(?<=pattern)>, C<(?<!pattern)>, C<(?{ +code })>, C<(??{ code })>, C<< (?>pattern) >>, C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)> =item Backtracking @@ -1662,7 +1706,7 @@ C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)> =item Combining pieces together C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>, -C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<(?E<gt>S)>, C<(?=S)>, C<(?<=S)>, +C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>, C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>, C<(?(condition)yes-pattern|no-pattern)> @@ -1739,45 +1783,45 @@ in perl5 I<-X> FILEHANDLE, I<-X> EXPR, I<-X>, abs VALUE, abs, accept NEWSOCKET,GENERICSOCKET, alarm SECONDS, alarm, atan2 Y,X, bind SOCKET,NAME, -binmode FILEHANDLE, bless REF,CLASSNAME, bless REF, caller EXPR, caller, -chdir EXPR, chmod LIST, chomp VARIABLE, chomp LIST, chomp, chop VARIABLE, -chop LIST, chop, chown LIST, chr NUMBER, chr, chroot FILENAME, chroot, -close FILEHANDLE, close, closedir DIRHANDLE, connect SOCKET,NAME, continue -BLOCK, cos EXPR, crypt PLAINTEXT,SALT, dbmclose HASH, dbmopen -HASH,DBNAME,MASK, defined EXPR, defined, delete EXPR, die LIST, do BLOCK, -do SUBROUTINE(LIST), do EXPR, dump LABEL, dump, each HASH, eof FILEHANDLE, -eof (), eof, eval EXPR, eval BLOCK, exec LIST, exec PROGRAM LIST, exists -EXPR, exit EXPR, exp EXPR, exp, fcntl FILEHANDLE,FUNCTION,SCALAR, fileno -FILEHANDLE, flock FILEHANDLE,OPERATION, fork, format, formline -PICTURE,LIST, getc FILEHANDLE, getc, getlogin, getpeername SOCKET, getpgrp -PID, getppid, getpriority WHICH,WHO, getpwnam NAME, getgrnam NAME, -gethostbyname NAME, getnetbyname NAME, getprotobyname NAME, getpwuid UID, -getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr ADDR,ADDRTYPE, -getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport -PORT,PROTO, getpwent, getgrent, gethostent, getnetent, getprotoent, -getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent STAYOPEN, -setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent, endhostent, -endnetent, endprotoent, endservent, getsockname SOCKET, getsockopt -SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, goto EXPR, -goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, import, index -STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl +binmode FILEHANDLE, DISCIPLINE, binmode FILEHANDLE, bless REF,CLASSNAME, +bless REF, caller EXPR, caller, chdir EXPR, chmod LIST, chomp VARIABLE, +chomp LIST, chomp, chop VARIABLE, chop LIST, chop, chown LIST, chr NUMBER, +chr, chroot FILENAME, chroot, close FILEHANDLE, close, closedir DIRHANDLE, +connect SOCKET,NAME, continue BLOCK, cos EXPR, crypt PLAINTEXT,SALT, +dbmclose HASH, dbmopen HASH,DBNAME,MASK, defined EXPR, defined, delete +EXPR, die LIST, do BLOCK, do SUBROUTINE(LIST), do EXPR, dump LABEL, dump, +each HASH, eof FILEHANDLE, eof (), eof, eval EXPR, eval BLOCK, exec LIST, +exec PROGRAM LIST, exists EXPR, exit EXPR, exp EXPR, exp, fcntl +FILEHANDLE,FUNCTION,SCALAR, fileno FILEHANDLE, flock FILEHANDLE,OPERATION, +fork, format, formline PICTURE,LIST, getc FILEHANDLE, getc, getlogin, +getpeername SOCKET, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam +NAME, getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname +NAME, getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr +ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER, +getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent, +getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent +STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent, +endhostent, endnetent, endprotoent, endservent, getsockname SOCKET, +getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, +goto EXPR, goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, +import, index STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys HASH, kill SIGNAL, LIST, last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length, link OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR, lock, log EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK LIST, map EXPR,LIST, mkdir FILENAME,MASK, mkdir FILENAME, msgctl -ID,CMD,ARG, msgget KEY,FLAGS, msgsnd ID,MSG,FLAGS, msgrcv -ID,VAR,SIZE,TYPE,FLAGS, my EXPR, my EXPR : ATTRIBUTES, next LABEL, next, no -Module LIST, oct EXPR, oct, open FILEHANDLE,MODE,EXPR, open -FILEHANDLE,EXPR, open FILEHANDLE, opendir DIRHANDLE,EXPR, ord EXPR, ord, -our EXPR, pack TEMPLATE,LIST, package, package NAMESPACE, pipe -READHANDLE,WRITEHANDLE, pop ARRAY, pop, pos SCALAR, pos, print FILEHANDLE -LIST, print LIST, print, printf FILEHANDLE FORMAT, LIST, printf FORMAT, -LIST, prototype FUNCTION, push ARRAY,LIST, q/STRING/, qq/STRING/, -qr/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR, quotemeta, rand EXPR, -rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, -readdir DIRHANDLE, readline EXPR, readlink EXPR, readlink, readpipe EXPR, -recv SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo, ref EXPR, ref, rename +ID,CMD,ARG, msgget KEY,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, msgsnd +ID,MSG,FLAGS, my EXPR, my EXPR : ATTRIBUTES, next LABEL, next, no Module +LIST, oct EXPR, oct, open FILEHANDLE,MODE,LIST, open FILEHANDLE,EXPR, open +FILEHANDLE, opendir DIRHANDLE,EXPR, ord EXPR, ord, our EXPR, pack +TEMPLATE,LIST, package, package NAMESPACE, pipe READHANDLE,WRITEHANDLE, pop +ARRAY, pop, pos SCALAR, pos, print FILEHANDLE LIST, print LIST, print, +printf FILEHANDLE FORMAT, LIST, printf FORMAT, LIST, prototype FUNCTION, +push ARRAY,LIST, q/STRING/, qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, +quotemeta EXPR, quotemeta, rand EXPR, rand, read +FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, readdir +DIRHANDLE, readline EXPR, readlink EXPR, readlink, readpipe EXPR, recv +SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo, ref EXPR, ref, rename OLDNAME,NEWNAME, require VERSION, require EXPR, require, reset EXPR, reset, return EXPR, return, reverse LIST, rewinddir DIRHANDLE, rindex STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar @@ -1824,7 +1868,7 @@ LIST, write FILEHANDLE, write EXPR, write, y/// =item Predefined Names -$ARG, $_, $E<lt>I<digits>E<gt>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $', +$ARG, $_, $<I<digits>>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $', $LAST_PAREN_MATCH, $+, @+, $MULTILINE_MATCHING, $*, input_line_number HANDLE EXPR, $INPUT_LINE_NUMBER, $NR, $, input_record_separator HANDLE EXPR, $INPUT_RECORD_SEPARATOR, $RS, $/, autoflush HANDLE EXPR, @@ -2152,7 +2196,7 @@ localization) =item Permanently fixing locale problems -=item Permanently fixing your locale configuration +=item Permanently fixing your system's locale configuration =item Fixing system locale configuration @@ -2843,24 +2887,28 @@ B<filter_fetch_value> =item Debugger Commands h [command], p expr, x expr, V [pkg [vars]], X [vars], T, s [expr], n -[expr], E<lt>CRE<gt>, c [line|sub], l, l min+incr, l min-max, l line, l -subname, -, w [line], f filename, /pattern/, ?pattern?, L, S [[!]pattern], -t, t expr, b [line] [condition], b subname [condition], b postpone subname +[expr], r, <CR>, c [line|sub], l, l min+incr, l min-max, l line, l subname, +-, w [line], f filename, /pattern/, ?pattern?, L, S [[!]regex], t, t expr, +b [line] [condition], b subname [condition], b postpone subname [condition], b load filename, b compile subname, d [line], D, a [line] -command, A, W [expr], W, O [opt[=val]] [opt"val"] [opt?].., +command, a [line], A, W expr, W, O booloption .., O anyoption? .., O +option=value .., < ?, < [ command ], << command, > ?, > command, >> +command, { ?, { [ command ], {{ command, ! number, ! -number, ! pattern, !! +cmd, H -number, q or ^D, R, |dbcmd, ||dbcmd, command, m expr, man [manpage] + +=item Configurable Options + C<recallCommand>, C<ShellBang>, C<pager>, C<tkRunning>, C<signalLevel>, C<warnLevel>, C<dieLevel>, C<AutoTrace>, C<LineInfo>, C<inhibit_exit>, C<PrintRet>, C<ornaments>, C<frame>, C<maxTraceLen>, C<arrayDepth>, C<hashDepth>, C<compactDump>, C<veryCompact>, C<globPrint>, C<DumpDBFiles>, C<DumpPackages>, C<DumpReused>, C<quote>, C<HighBit>, C<undefPrint>, -C<UsageOnly>, C<TTY>, C<noTTY>, C<ReadLine>, C<NonStop>, E<lt> [ command ], -E<lt>E<lt> command, E<gt> command, E<gt>E<gt> command, { [ command ], {{ -command, ! number, ! -number, ! pattern, !! cmd, H -number, q or ^D, R, -|dbcmd, ||dbcmd, command, m expr, m package +C<UsageOnly>, C<TTY>, C<noTTY>, C<ReadLine>, C<NonStop> =item Debugger input/output -Prompt, Multiline commands, Stack backtrace, Listing, Frame listing +Prompt, Multiline commands, Stack backtrace, Line Listing Format, Frame +listing =item Debugging compile-time statements @@ -2872,38 +2920,59 @@ Prompt, Multiline commands, Stack backtrace, Listing, Frame listing =item The Perl Profiler -=item Debugger support in perl +=back -=item Debugger Internals +=item Debugging regular expressions -=item Other resources +=item Debugging memory usage + +=item SEE ALSO =item BUGS =back -=item Debugging Perl memory usage +=head2 perlnumber - semantics of numbers and numeric operations in Perl =over -=item Using C<$ENV{PERL_DEBUG_MSTATS}> +=item SYNOPSIS -C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk(): -SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail: -6144> +=item DESCRIPTION -=item Example of using B<-DL> switch +=item Storing numbers -C<717>, C<002>, C<054>, C<602>, C<702>, C<704> +=item Numeric operators and numeric conversions -=item B<-DL> details +=item Flavors of Perl numeric operations -C<!!!>, C<!!>, C<!> +Arithmetic operators except, C<no integer>, Arithmetic operators except, +C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use +integer>, Operators which expect an integer, Operators which expect a +string + +=item AUTHOR -=item Limitations of B<-DL> statistic +=item SEE ALSO =back +=head2 perldebguts - Guts of Perl debugging + +=over + +=item DESCRIPTION + +=item Debugger Internals + +=over + +=item Writing Your Own Debugger + +=back + +=item Frame Listing Output Examples + =item Debugging regular expressions =over @@ -2921,28 +2990,27 @@ C<anchored(TYPE)> =back -=back - -=head2 perlnumber - semantics of numbers and numeric operations in Perl +=item Debugging Perl memory usage =over -=item SYNOPSIS +=item Using C<$ENV{PERL_DEBUG_MSTATS}> -=item DESCRIPTION +C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk(): +SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail: +6144> -=item Storing numbers +=item Example of using B<-DL> switch -=item Numeric operators and numeric conversions +C<717>, C<002>, C<054>, C<602>, C<702>, C<704> -=item Flavors of Perl numeric operations +=item B<-DL> details -Arithmetic operators except, C<no integer>, Arithmetic operators except, -C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use -integer>, Operators which expect an integer, Operators which expect a -string +C<!!!>, C<!!>, C<!> -=item AUTHOR +=item Limitations of B<-DL> statistics + +=back =item SEE ALSO @@ -3109,7 +3177,7 @@ portable =item CPAN Testers Mailing list: cpan-testers@perl.org, Testing results: -C<http://testers.cpan.org/> +http://testers.cpan.org/ =item PLATFORMS @@ -3119,49 +3187,20 @@ C<http://testers.cpan.org/> =item DOS and Derivatives -The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>, The EMX -environment for DOS, OS/2, etc. -C<emx@iaehv.nl>,C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index. -html> or -C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>, Build instructions for Win32, -L<perlwin32>, The ActiveState Pages, C<http://www.activestate.com/>, The -Cygwin environment for Win32; F<README.cygwin> (installed as -L<perlcygwin>), C<http://sourceware.cygnus.com/cygwin/>, The U/WIN -environment for Win32,C<http://www.research.att.com/sw/tools/uwin/> +Build instructions for OS/2, L<perlos2> =item S<Mac OS> -The MacPerl Pages, C<http://www.macperl.com/>, The MacPerl mailing lists, -C<http://www.macperl.org/>, MacPerl Module Porters, -C<http://pudge.net/mmp/> - =item VMS -F<README.vms> (installed as L<README_vms>), L<perlvms>, vmsperl list, -C<majordomo@perl.org>, vmsperl on the web, -C<http://www.sidhe.org/vmsperl/index.html> - =item VOS -F<README.vos>, VOS mailing list, VOS Perl on the web at -C<http://ftp.stratus.com/pub/vos/vos.html> - =item EBCDIC Platforms -F<README.os390>, F<README.posix-bc>, F<README.vmesa>, perl-mvs list, AS/400 -Perl information at C<http://as400.rochester.ibm.com/>as well as on CPAN in -the F<ports/> directory - =item Acorn RISC OS =item Other perls -Amiga, F<README.amiga> (installed as L<perlamiga>), Atari, F<README.mint> -and Guido Flohr's web pageC<http://stud.uni-sb.de/~gufl0000/>, Be OS, -F<README.beos>, HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web -pageC<http://www.cccd.edu/~markb/perlix.html>, Novell Netware, Plan 9, -F<README.plan9> - =back =item FUNCTION IMPLEMENTATIONS @@ -3170,22 +3209,22 @@ F<README.plan9> =item Alphabetical Listing of Perl Functions --I<X> FILEHANDLE, -I<X> EXPR, -I<X>, binmode FILEHANDLE, chmod LIST, chown -LIST, chroot FILENAME, chroot, crypt PLAINTEXT,SALT, dbmclose HASH, dbmopen -HASH,DBNAME,MODE, dump LABEL, exec LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, -flock FILEHANDLE,OPERATION, fork, getlogin, getpgrp PID, getppid, -getpriority WHICH,WHO, getpwnam NAME, getgrnam NAME, getnetbyname NAME, -getpwuid UID, getgrgid GID, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber -NUMBER, getservbyport PORT,PROTO, getpwent, getgrent, gethostent, -getnetent, getprotoent, getservent, setpwent, setgrent, sethostent -STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, -endpwent, endgrent, endhostent, endnetent, endprotoent, endservent, -getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, ioctl -FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE, lstat -FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS, msgsnd -ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR, open -FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink, select -RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget +-I<X> FILEHANDLE, -I<X> EXPR, -I<X>, alarm SECONDS, alarm, binmode +FILEHANDLE, chmod LIST, chown LIST, chroot FILENAME, chroot, crypt +PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, dump LABEL, exec +LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, flock FILEHANDLE,OPERATION, fork, +getlogin, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME, +getgrnam NAME, getnetbyname NAME, getpwuid UID, getgrgid GID, getnetbyaddr +ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent, +getgrent, gethostent, getnetent, getprotoent, getservent, setpwent, +setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN, +setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent, +endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, +ioctl FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE, +lstat FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS, +msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR, +open FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink, +select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP, setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, @@ -3200,11 +3239,16 @@ wait, waitpid PID,FLAGS =item CHANGES -v1.46, 12 February 2000, v1.45, 20 December 1999, v1.44, 19 July 1999, -v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May 1999, v1.40, 11 April -1999, v1.39, 11 February 1999, v1.38, 31 December 1998, v1.37, 19 December -1998, v1.36, 9 September 1998, v1.35, 13 August 1998, v1.33, 06 August -1998, v1.32, 05 August 1998, v1.30, 03 August 1998, v1.23, 10 July 1998 +v1.47, 22 March 2000, v1.46, 12 February 2000, v1.45, 20 December 1999, +v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May +1999, v1.40, 11 April 1999, v1.39, 11 February 1999, v1.38, 31 December +1998, v1.37, 19 December 1998, v1.36, 9 September 1998, v1.35, 13 August +1998, v1.33, 06 August 1998, v1.32, 05 August 1998, v1.30, 03 August 1998, +v1.23, 10 July 1998 + +=item Supported Platforms + +=item SEE ALSO =item AUTHORS / CONTRIBUTORS @@ -3738,13 +3782,13 @@ B::Bytecode, B::C, B::CC, B::Lint, B::Deparse, B::Xref =over -=item The Cross Referencing Back End (B::Xref) +=item The Cross Referencing Back End i, &, s, r =item The Decompiling Back End -=item The Lint Back End (B::Lint) +=item The Lint Back End =item The Simple C Back End @@ -3785,33 +3829,34 @@ isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, LEAVE, looks_like_number, MARK, mg_clear, mg_copy, mg_find, mg_free, mg_get, mg_length, mg_magical, mg_set, Move, New, newAV, Newc, newCONSTSUB, newHV, newRV_inc, newRV_noinc, NEWSV, newSViv, newSVnv, newSVpv, newSVpvf, newSVpvn, newSVrv, newSVsv, -newXS, newXSproto, Newz, Nullav, Nullch, Nullcv, Nullhv, Nullsv, ORIGMARK, -perl_alloc, perl_construct, perl_destruct, perl_free, perl_parse, perl_run, -PL_DBsingle, PL_DBsub, PL_DBtrace, PL_dowarn, PL_modglobal, PL_na, -PL_sv_no, PL_sv_undef, PL_sv_yes, POPi, POPl, POPn, POPp, POPs, PUSHi, -PUSHMARK, PUSHn, PUSHp, PUSHs, PUSHu, PUTBACK, Renew, Renewc, require_pv, -RETVAL, Safefree, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, -strGT, strLE, strLT, strNE, strnEQ, strnNE, StructCopy, SvCUR, SvCUR_set, -SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, SvIOK_off, SvIOK_on, SvIOK_only, -SvIV, SvIVX, SvLEN, SvNIOK, SvNIOKp, SvNIOK_off, SvNOK, SvNOKp, SvNOK_off, -SvNOK_on, SvNOK_only, SvNV, SvNVX, SvOK, SvOOK, SvPOK, SvPOKp, SvPOK_off, -SvPOK_on, SvPOK_only, SvPV, SvPVX, SvPV_force, SvPV_nolen, SvREFCNT, -SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, SvROK_on, SvRV, SvSETMAGIC, -SvSetSV, SvSetSV_nosteal, SvSTASH, SvTAINT, SvTAINTED, SvTAINTED_off, -SvTAINTED_on, SvTRUE, SvTYPE, svtype, SVt_IV, SVt_NV, SVt_PV, SVt_PVAV, -SVt_PVCV, SVt_PVHV, SVt_PVMG, SvUPGRADE, SvUV, SvUVX, sv_2mortal, sv_bless, -sv_catpv, sv_catpvf, sv_catpvf_mg, sv_catpvn, sv_catpvn_mg, sv_catpv_mg, -sv_catsv, sv_catsv_mg, sv_chop, sv_cmp, sv_dec, sv_derived_from, sv_eq, -sv_grow, sv_inc, sv_insert, sv_isa, sv_isobject, sv_len, sv_magic, -sv_mortalcopy, sv_newmortal, sv_setiv, sv_setiv_mg, sv_setnv, sv_setnv_mg, -sv_setpv, sv_setpvf, sv_setpvf_mg, sv_setpviv, sv_setpviv_mg, sv_setpvn, -sv_setpvn_mg, sv_setpv_mg, sv_setref_iv, sv_setref_nv, sv_setref_pv, -sv_setref_pvn, sv_setsv, sv_setsv_mg, sv_setuv, sv_setuv_mg, sv_unref, -sv_upgrade, sv_usepvn, sv_usepvn_mg, sv_vcatpvfn, sv_vsetpvfn, THIS, -toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, XPUSHu, XS, -XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, XSRETURN_NV, -XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNO, XST_mNV, -XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, Zero +newSVuv, newXS, newXSproto, Newz, Nullav, Nullch, Nullcv, Nullhv, Nullsv, +ORIGMARK, perl_alloc, perl_construct, perl_destruct, perl_free, perl_parse, +perl_run, PL_DBsingle, PL_DBsub, PL_DBtrace, PL_dowarn, PL_modglobal, +PL_na, PL_sv_no, PL_sv_undef, PL_sv_yes, POPi, POPl, POPn, POPp, POPs, +PUSHi, PUSHMARK, PUSHn, PUSHp, PUSHs, PUSHu, PUTBACK, Renew, Renewc, +require_pv, RETVAL, Safefree, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, +strEQ, strGE, strGT, strLE, strLT, strNE, strnEQ, strnNE, StructCopy, +SvCUR, SvCUR_set, SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, SvIOK_off, +SvIOK_on, SvIOK_only, SvIV, SvIVX, SvLEN, SvNIOK, SvNIOKp, SvNIOK_off, +SvNOK, SvNOKp, SvNOK_off, SvNOK_on, SvNOK_only, SvNV, SvNVX, SvOK, SvOOK, +SvPOK, SvPOKp, SvPOK_off, SvPOK_on, SvPOK_only, SvPV, SvPVX, SvPV_force, +SvPV_nolen, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, +SvROK_on, SvRV, SvSETMAGIC, SvSetSV, SvSetSV_nosteal, SvSTASH, SvTAINT, +SvTAINTED, SvTAINTED_off, SvTAINTED_on, SvTRUE, SvTYPE, svtype, SVt_IV, +SVt_NV, SVt_PV, SVt_PVAV, SVt_PVCV, SVt_PVHV, SVt_PVMG, SvUPGRADE, SvUV, +SvUVX, sv_2mortal, sv_bless, sv_catpv, sv_catpvf, sv_catpvf_mg, sv_catpvn, +sv_catpvn_mg, sv_catpv_mg, sv_catsv, sv_catsv_mg, sv_chop, sv_cmp, sv_dec, +sv_derived_from, sv_eq, sv_grow, sv_inc, sv_insert, sv_isa, sv_isobject, +sv_len, sv_magic, sv_mortalcopy, sv_newmortal, sv_setiv, sv_setiv_mg, +sv_setnv, sv_setnv_mg, sv_setpv, sv_setpvf, sv_setpvf_mg, sv_setpviv, +sv_setpviv_mg, sv_setpvn, sv_setpvn_mg, sv_setpv_mg, sv_setref_iv, +sv_setref_nv, sv_setref_pv, sv_setref_pvn, sv_setsv, sv_setsv_mg, sv_setuv, +sv_setuv_mg, sv_unref, sv_upgrade, sv_usepvn, sv_usepvn_mg, sv_vcatpvfn, +sv_vsetpvfn, THIS, toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, +XPUSHu, XS, XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, +XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNO, +XST_mNV, XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, +Zero =item AUTHORS @@ -4081,13 +4126,6 @@ new, phash =item SYNOPSIS - $can_perhaps_read = -r "file"; # use the mode bits - { - use filetest 'access'; # intuit harder - $can_really_read = -r "file"; - } - $can_perhaps_read = -r "file"; # use the mode bits again - =item DESCRIPTION =over @@ -4154,6 +4192,20 @@ operations =back +=head2 open - perl pragma to set default disciplines for input and output + +=over + +=item SYNOPSIS + +=item DESCRIPTION + +=item UNIMPLEMENTED FUNCTIONALITY + +=item SEE ALSO + +=back + =head2 ops - Perl pragma to restrict unsafe operations when compiling =over @@ -4354,7 +4406,8 @@ C<strict refs>, C<strict vars>, C<strict subs> =item DESCRIPTION -warnings::enabled($category), warnings::warn($category, $message) +use warnings::register, warnings::enabled([$category]), +warnings::warn([$category,] $message) =back @@ -5124,8 +5177,7 @@ parameters in the B<header()> and B<redirect()> statements: =item Server Push -multipart_init() - multipart_init(-boundary=>$boundary);, multipart_start(), multipart_end() +multipart_init(), multipart_start(), multipart_end() =item Avoiding Denial of Service Attacks @@ -5564,45 +5616,46 @@ C<d_getspent>, C<d_getspnam>, C<d_gettimeod>, C<d_gnulibc>, C<d_grpasswd>, C<d_hasmntopt>, C<d_htonl>, C<d_iconv>, C<d_index>, C<d_inetaton>, C<d_int64_t>, C<d_isascii>, C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>, C<d_link>, C<d_locconv>, C<d_lockf>, C<d_longdbl>, C<d_longlong>, -C<d_lseekproto>, C<d_lstat>, C<d_mblen>, C<d_mbstowcs>, C<d_mbtowc>, -C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>, C<d_memset>, -C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>, C<d_mkstemps>, -C<d_mktime>, C<d_mmap>, C<d_mprotect>, C<d_msg>, C<d_msg_ctrunc>, -C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, C<d_msg_proxy>, -C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>, C<d_msync>, -C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nv_preserves_uv>, C<d_off64_t>, -C<d_old_pthread_create_joinable>, C<d_oldpthreads>, C<d_oldsock>, -C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_phostname>, C<d_pipe>, -C<d_poll>, C<d_portable>, C<d_PRId64>, C<d_PRIeldbl>, C<d_PRIEldbl>, -C<d_PRIfldbl>, C<d_PRIFldbl>, C<d_PRIgldbl>, C<d_PRIGldbl>, C<d_PRIi64>, -C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, C<d_PRIX64>, C<d_pthread_yield>, -C<d_pwage>, C<d_pwchange>, C<d_pwclass>, C<d_pwcomment>, C<d_pwexpire>, -C<d_pwgecos>, C<d_pwpasswd>, C<d_pwquota>, C<d_quad>, C<d_readdir>, -C<d_readlink>, C<d_rename>, C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, -C<d_safemcpy>, C<d_sanemcmp>, C<d_sched_yield>, C<d_scm_rights>, -C<d_seekdir>, C<d_select>, C<d_sem>, C<d_semctl>, C<d_semctl_semid_ds>, -C<d_semctl_semun>, C<d_semget>, C<d_semop>, C<d_setegid>, C<d_seteuid>, -C<d_setgrent>, C<d_setgrps>, C<d_sethent>, C<d_setlinebuf>, C<d_setlocale>, -C<d_setnent>, C<d_setpent>, C<d_setpgid>, C<d_setpgrp2>, C<d_setpgrp>, -C<d_setprior>, C<d_setpwent>, C<d_setregid>, C<d_setresgid>, -C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>, -C<d_setsid>, C<d_setspent>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, C<d_shmat>, -C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, C<d_sigaction>, -C<d_sigsetjmp>, C<d_socket>, C<d_socklen_t>, C<d_sockpair>, C<d_sqrtl>, -C<d_statblks>, C<d_statfs_f_flags>, C<d_statfs_s>, C<d_statvfs>, -C<d_stdio_cnt_lval>, C<d_stdio_ptr_lval>, C<d_stdio_stream_array>, -C<d_stdiobase>, C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, -C<d_strerrm>, C<d_strerror>, C<d_strtod>, C<d_strtol>, C<d_strtold>, -C<d_strtoll>, C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, -C<d_suidsafe>, C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>, -C<d_syserrlst>, C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>, +C<d_lseekproto>, C<d_lstat>, C<d_madvise>, C<d_mblen>, C<d_mbstowcs>, +C<d_mbtowc>, C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>, +C<d_memset>, C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>, +C<d_mkstemps>, C<d_mktime>, C<d_mmap>, C<d_mprotect>, C<d_msg>, +C<d_msg_ctrunc>, C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, +C<d_msg_proxy>, C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>, +C<d_msync>, C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nv_preserves_uv>, +C<d_off64_t>, C<d_old_pthread_create_joinable>, C<d_oldpthreads>, +C<d_oldsock>, C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_phostname>, +C<d_pipe>, C<d_poll>, C<d_portable>, C<d_PRId64>, C<d_PRIeldbl>, +C<d_PRIEldbl>, C<d_PRIfldbl>, C<d_PRIFldbl>, C<d_PRIgldbl>, C<d_PRIGldbl>, +C<d_PRIi64>, C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, C<d_PRIX64>, +C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>, C<d_pwclass>, +C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>, C<d_pwquota>, +C<d_qgcvt>, C<d_quad>, C<d_readdir>, C<d_readlink>, C<d_rename>, +C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>, C<d_sanemcmp>, +C<d_sched_yield>, C<d_scm_rights>, C<d_seekdir>, C<d_select>, C<d_sem>, +C<d_semctl>, C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>, +C<d_semop>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>, C<d_setgrps>, +C<d_sethent>, C<d_setlinebuf>, C<d_setlocale>, C<d_setnent>, C<d_setpent>, +C<d_setpgid>, C<d_setpgrp2>, C<d_setpgrp>, C<d_setprior>, C<d_setpwent>, +C<d_setregid>, C<d_setresgid>, C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, +C<d_setruid>, C<d_setsent>, C<d_setsid>, C<d_setspent>, C<d_setvbuf>, +C<d_sfio>, C<d_shm>, C<d_shmat>, C<d_shmatprototype>, C<d_shmctl>, +C<d_shmdt>, C<d_shmget>, C<d_sigaction>, C<d_sigsetjmp>, C<d_socket>, +C<d_socklen_t>, C<d_sockpair>, C<d_sqrtl>, C<d_statblks>, +C<d_statfs_f_flags>, C<d_statfs_s>, C<d_statvfs>, C<d_stdio_cnt_lval>, +C<d_stdio_ptr_lval>, C<d_stdio_stream_array>, C<d_stdiobase>, +C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>, +C<d_strerror>, C<d_strtod>, C<d_strtol>, C<d_strtold>, C<d_strtoll>, +C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, C<d_suidsafe>, +C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>, C<d_syserrlst>, +C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>, C<d_telldirproto>, C<d_time>, C<d_times>, C<d_truncate>, C<d_tzname>, -C<d_umask>, C<d_uname>, C<d_union_semun>, C<d_ustat>, C<d_vendorbin>, -C<d_vendorlib>, C<d_vfork>, C<d_void_closedir>, C<d_voidsig>, C<d_voidtty>, -C<d_volatile>, C<d_vprintf>, C<d_wait4>, C<d_waitpid>, C<d_wcstombs>, -C<d_wctomb>, C<d_xenix>, C<date>, C<db_hashtype>, C<db_prefixtype>, -C<defvoidused>, C<direntrytype>, C<dlext>, C<dlsrc>, C<doublesize>, -C<drand01>, C<dynamic_ext> +C<d_umask>, C<d_uname>, C<d_union_semun>, C<d_ustat>, C<d_vendorarch>, +C<d_vendorbin>, C<d_vendorlib>, C<d_vfork>, C<d_void_closedir>, +C<d_voidsig>, C<d_voidtty>, C<d_volatile>, C<d_vprintf>, C<d_wait4>, +C<d_waitpid>, C<d_wcstombs>, C<d_wctomb>, C<d_xenix>, C<date>, +C<db_hashtype>, C<db_prefixtype>, C<defvoidused>, C<direntrytype>, +C<dlext>, C<dlsrc>, C<doublesize>, C<drand01>, C<dynamic_ext> =item e @@ -5628,24 +5681,25 @@ C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<huge> C<i16size>, C<i16type>, C<i32size>, C<i32type>, C<i64size>, C<i64type>, C<i8size>, C<i8type>, C<i_arpainet>, C<i_bsdioctl>, C<i_db>, C<i_dbm>, C<i_dirent>, C<i_dld>, C<i_dlfcn>, C<i_fcntl>, C<i_float>, C<i_gdbm>, -C<i_grp>, C<i_iconv>, C<i_inttypes>, C<i_limits>, C<i_locale>, +C<i_grp>, C<i_iconv>, C<i_ieeefp>, C<i_inttypes>, C<i_limits>, C<i_locale>, C<i_machcthr>, C<i_malloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>, C<i_netdb>, C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>, C<i_pthread>, C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>, C<i_socks>, C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>, -C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, C<i_sysin>, -C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>, C<i_sysmount>, -C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>, C<i_sysselct>, -C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>, C<i_sysstatvfs>, -C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>, C<i_sysuio>, -C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>, C<i_termio>, -C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>, C<i_values>, -C<i_varargs>, C<i_varhdr>, C<i_vfork>, C<ignore_versioned_solibs>, -C<inc_version_list>, C<inc_version_list_init>, C<incpath>, C<inews>, -C<installarchlib>, C<installbin>, C<installman1dir>, C<installman3dir>, -C<installprefix>, C<installprefixexp>, C<installprivlib>, C<installscript>, -C<installsitearch>, C<installsitebin>, C<installsitelib>, C<installstyle>, -C<installusrbinperl>, C<installvendorbin>, C<installvendorlib>, C<intsize>, +C<i_sunmath>, C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, +C<i_sysin>, C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>, +C<i_sysmount>, C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>, +C<i_sysselct>, C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>, +C<i_sysstatvfs>, C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>, +C<i_sysuio>, C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>, +C<i_termio>, C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>, +C<i_values>, C<i_varargs>, C<i_varhdr>, C<i_vfork>, +C<ignore_versioned_solibs>, C<inc_version_list>, C<inc_version_list_init>, +C<incpath>, C<inews>, C<installarchlib>, C<installbin>, C<installman1dir>, +C<installman3dir>, C<installprefix>, C<installprefixexp>, +C<installprivlib>, C<installscript>, C<installsitearch>, C<installsitebin>, +C<installsitelib>, C<installstyle>, C<installusrbinperl>, +C<installvendorarch>, C<installvendorbin>, C<installvendorlib>, C<intsize>, C<ivdformat>, C<ivsize>, C<ivtype> =item k @@ -5712,15 +5766,15 @@ C<selectminbits>, C<selecttype>, C<sendmail>, C<sh>, C<shar>, C<sharpbang>, C<shmattype>, C<shortsize>, C<shrpenv>, C<shsharp>, C<sig_count>, C<sig_name>, C<sig_name_init>, C<sig_num>, C<sig_num_init>, C<signal_t>, C<sitearch>, C<sitearchexp>, C<sitebin>, C<sitebinexp>, C<sitelib>, -C<sitelibexp>, C<siteprefix>, C<siteprefixexp>, C<sizetype>, C<sleep>, -C<smail>, C<small>, C<so>, C<sockethdr>, C<socketlib>, C<socksizetype>, -C<sort>, C<spackage>, C<spitshell>, C<split>, C<sPRId64>, C<sPRIeldbl>, -C<sPRIEldbl>, C<sPRIfldbl>, C<sPRIFldbl>, C<sPRIgldbl>, C<sPRIGldbl>, -C<sPRIi64>, C<sPRIo64>, C<sPRIu64>, C<sPRIx64>, C<sPRIX64>, C<src>, -C<ssizetype>, C<startperl>, C<startsh>, C<static_ext>, C<stdchar>, -C<stdio_base>, C<stdio_bufsiz>, C<stdio_cnt>, C<stdio_filbuf>, -C<stdio_ptr>, C<stdio_stream_array>, C<strings>, C<submit>, C<subversion>, -C<sysman> +C<sitelib_stem>, C<sitelibexp>, C<siteprefix>, C<siteprefixexp>, +C<sizesize>, C<sizetype>, C<sleep>, C<smail>, C<small>, C<so>, +C<sockethdr>, C<socketlib>, C<socksizetype>, C<sort>, C<spackage>, +C<spitshell>, C<split>, C<sPRId64>, C<sPRIeldbl>, C<sPRIEldbl>, +C<sPRIfldbl>, C<sPRIFldbl>, C<sPRIgldbl>, C<sPRIGldbl>, C<sPRIi64>, +C<sPRIo64>, C<sPRIu64>, C<sPRIx64>, C<sPRIX64>, C<src>, C<ssizetype>, +C<startperl>, C<startsh>, C<static_ext>, C<stdchar>, C<stdio_base>, +C<stdio_bufsiz>, C<stdio_cnt>, C<stdio_filbuf>, C<stdio_ptr>, +C<stdio_stream_array>, C<strings>, C<submit>, C<subversion>, C<sysman> =item t @@ -5741,8 +5795,9 @@ C<uvxformat> =item v -C<vendorbin>, C<vendorbinexp>, C<vendorlib>, C<vendorlibexp>, -C<vendorprefix>, C<vendorprefixexp>, C<version>, C<vi>, C<voidflags> +C<vendorarch>, C<vendorarchexp>, C<vendorbin>, C<vendorbinexp>, +C<vendorlib>, C<vendorlib_stem>, C<vendorlibexp>, C<vendorprefix>, +C<vendorprefixexp>, C<version>, C<vi>, C<voidflags> =item x @@ -5954,14 +6009,13 @@ printing and C<eval> =item Methods I<PACKAGE>->new(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Dump I<or> -I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Dumpxs I<or> -I<PACKAGE>->Dumpxs(I<ARRAYREF [>, I<ARRAYREF]>), -I<$OBJ>->Seen(I<[HASHREF]>), I<$OBJ>->Values(I<[ARRAYREF]>), -I<$OBJ>->Names(I<[ARRAYREF]>), I<$OBJ>->Reset +I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Seen(I<[HASHREF]>), +I<$OBJ>->Values(I<[ARRAYREF]>), I<$OBJ>->Names(I<[ARRAYREF]>), +I<$OBJ>->Reset =item Functions -Dumper(I<LIST>), DumperX(I<LIST>) +Dumper(I<LIST>) =item Configuration Variables or Methods @@ -6114,7 +6168,7 @@ veryCompact, set, get @dl_library_path, @dl_resolve_using, @dl_require_symbols, @dl_librefs, @dl_modules, dl_error(), $dl_debug, dl_findfile(), dl_expandspec(), -dl_load_file(), dl_loadflags(), dl_find_symbol(), +dl_load_file(), dl_unload_file(), dl_loadflags(), dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(), dl_install_xsub(), bootstrap() @@ -6148,7 +6202,8 @@ variables =back -=head2 Env - perl module that imports environment variables +=head2 Env - perl module that imports environment variables as scalars or +arrays =over @@ -6156,6 +6211,8 @@ variables =item DESCRIPTION +=item LIMITATIONS + =item AUTHOR =back @@ -7254,9 +7311,9 @@ splitdir (override) catpath (override) -splitpath +abs2rel (override) -splitdir +rel2abs (override) =over @@ -7372,8 +7429,7 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =back -=head2 Getopt::Long, GetOptions - extended processing of command line -options +=head2 Getopt::Long - Extended processing of command line options =over @@ -7381,36 +7437,72 @@ options =item DESCRIPTION -!, +, :s, :i, :f +=item Command Line Options, an Introduction + +=item Getting Started with Getopt::Long =over -=item Linkage specification +=item Simple options -=item Aliases and abbreviations +=item A little bit less simple options -=item Non-option call-back routine +=item Mixing command line option with other arguments -=item Option starters +=item Options with values -=item Return values and Errors +=item Options with multiple values + +=item Options with hash values + +=item User-defined subroutines to handle options + +=item Options with multiple names + +=item Case and abbreviations + +=item Summary of Option Specifications + +!, +, s, i, f, : I<type> [ I<desttype> ] =back -=item COMPATIBILITY +=item Advanced Possibilities -=item EXAMPLES +=over + +=item Documentation and help texts + +=item Storing options in a hash + +=item Bundling -=item CONFIGURATION OPTIONS +=item The lonesome dash + +=item Argument call-back + +=back + +=item Configuring Getopt::Long default, auto_abbrev, getopt_compat, require_order, permute, bundling (default: reset), bundling_override (default: reset), ignore_case (default: set), ignore_case_always (default: reset), pass_through (default: reset), prefix, prefix_pattern, debug (default: reset) -=item OTHER USEFUL VARIABLES +=item Return values and Errors + +=item Legacy -$Getopt::Long::VERSION, $Getopt::Long::error +=over + +=item Default destinations + +=item Alternative option starters + +=item Configuration variables + +=back =item AUTHOR @@ -8096,33 +8188,6 @@ Canonical notation, Input, Output =back -=head2 Math::Complex - complex numbers and associated mathematical -functions - -=over - -=item SYNOPSIS - -=item DESCRIPTION - -=item OPERATIONS - -=item CREATION - -=item STRINGIFICATION - -=item USAGE - -=item ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO - -=item ERRORS DUE TO INDIGESTIBLE ARGUMENTS - -=item BUGS - -=item AUTHORS - -=back - =head2 Math::Trig - trigonometric functions =over @@ -8617,9 +8682,9 @@ B<-verbose>, B<-perl>, B<-script>, B<-inc> =item ARGUMENTS -help, htmldir, htmlroot, infile, outfile, podroot, podpath, libpods, -netscape, nonetscape, index, noindex, recurse, norecurse, title, css, -verbose, quiet +backlink, css, flush, header, help, htmldir, htmlroot, index, infile, +libpods, netscape, outfile, podpath, podroot, quiet, recurse, title, +verbose =item EXAMPLE @@ -8881,8 +8946,6 @@ EE<lt>%sE<gt>, Unknown sequence %s, Unmatched =back =item BUGS -=item NOTES - =item SEE ALSO =item AUTHOR @@ -9009,7 +9072,8 @@ idx() =item PARSING OPTIONS -B<-want_nonPODs> (default: unset), B<-process_cut_cmd> (default: unset) +B<-want_nonPODs> (default: unset), B<-process_cut_cmd> (default: unset), +B<-warnings> (default: unset) =back @@ -9231,6 +9295,26 @@ I<code-ref>|I<method-name> =back +=head2 Pod::Plainer - Perl extension for converting Pod to old style Pod. + +=over + +=item SYNOPSIS + +=item DESCRIPTION + +=over + +=item EXPORT + +=back + +=item AUTHOR + +=item SEE ALSO + +=back + =head2 Pod::Select, podselect() - extract selected sections of POD from input @@ -9608,6 +9692,26 @@ closelog =back +=head2 Term::ANSIColor - Color screen output using ANSI escape sequences + +=over + +=item SYNOPSIS + +=item DESCRIPTION + +=item DIAGNOSTICS + +Invalid attribute name %s, Identifier %s used only once: possible typo, No +comma allowed after filehandle, Bareword %s not allowed while "strict subs" +in use + +=item RESTRICTIONS + +=item AUTHORS + +=back + =head2 Term::Cap - Perl termcap interface =over @@ -10065,10 +10169,20 @@ functions =item DESCRIPTION +=over + +=item System Specifics + +=back + =item NOTE =item AUTHOR +=item HISTORY + +March 18th, 2000 + =back =head2 XSLoader - Dynamically load C libraries into Perl code diff --git a/pod/perltodo.pod b/pod/perltodo.pod index f22d4737f8..f12b10f4b9 100644 --- a/pod/perltodo.pod +++ b/pod/perltodo.pod @@ -85,7 +85,7 @@ We need regression/sanity tests for suidperl This value may or may not be accurate, but it certainly is eye-catching. For some things perl5 is faster than perl4, but often -the reliability and extensability have come at a cost of speed. The +the reliability and extensibility have come at a cost of speed. The benchmark suite that Gisle released earlier has been hailed as both a fantastic solution and as a source of entirely meaningless figures. Do we need to test "real applications"? Can you do so? Anyone have @@ -161,7 +161,7 @@ Sarathy, I believe, did the work. Here's what he has to say: Yeah, I hope to implement it someday too. The points that were raised in TPC2 were all to do with calling DESTROY() methods, but -I think we can accomodate that by extending bless() to stash +I think we can accommodate that by extending bless() to stash extra information for objects so we track their lifetime accurately for those that want their DESTROY() to be predictable (this will be a speed hit, naturally, and will therefore be optional, naturally. :) @@ -863,7 +863,7 @@ See Time::HiRes. =head2 autocroak? -This is the Fatal.pm module, so any builtin that that does +This is the Fatal.pm module, so any builtin that does not return success automatically die()s. If you're feeling brave, tie this in with the unified exceptions scheme. diff --git a/pod/perltootc.pod b/pod/perltootc.pod index 64f8233fdb..0bcb638a50 100644 --- a/pod/perltootc.pod +++ b/pod/perltootc.pod @@ -184,7 +184,7 @@ to which beginning Perl programmers attempt to put symbolic references, we have much better approaches, like nested hashes or hashes of arrays. But there's nothing wrong with using symbolic references to manipulate something that is meaningful only from the perspective of the package -symbol symbol table, like method names or package variables. In other +symbol table, like method names or package variables. In other words, when you want to refer to the symbol table, use symbol references. Clustering all the class attributes in one place has several advantages. diff --git a/pod/perltrap.pod b/pod/perltrap.pod index e528254e0e..c477272abe 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -172,12 +172,6 @@ Variables begin with "$", "@" or "%" in Perl. =item * -C<printf()> does not implement the "*" format for interpolating -field widths, but it's trivial to use interpolation of double-quoted -strings to achieve the same effect. - -=item * - Comments begin with "#", not "/*". =item * @@ -392,8 +386,9 @@ Everything else. =back If you find an example of a conversion trap that is not listed here, -please submit it to Bill Middleton <F<wjm@best.com>> for inclusion. -Also note that at least some of these can be caught with B<-w>. +please submit it to <F<perlbug@perl.org>> for inclusion. +Also note that at least some of these can be caught with the +C<use warnings> pragma or the B<-w> switch. =head2 Discontinuance, Deprecation, and BugFix traps diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod index c8e31bf66c..c6866617a2 100644 --- a/pod/perlunicode.pod +++ b/pod/perlunicode.pod @@ -114,12 +114,7 @@ will typically occur directly within the literal strings as UTF-8 characters, but you can also specify a particular character with an extension of the C<\x> notation. UTF-8 characters are specified by putting the hexadecimal code within curlies after the C<\x>. For instance, -a Unicode smiley face is C<\x{263A}>. A character in the Latin-1 range -(128..255) should be written C<\x{ab}> rather than C<\xab>, since the -former will turn into a two-byte UTF-8 code, while the latter will -continue to be interpreted as generating a 8-bit byte rather than a -character. In fact, if C<-w> is turned on, it will produce a warning -that you might be generating invalid UTF-8. +a Unicode smiley face is C<\x{263A}>. =item * diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 04fb3fec96..15308e45aa 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -174,6 +174,8 @@ example: (Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. +=item @LAST_MATCH_END + =item @+ This array holds the offsets of the ends of the last successful @@ -412,6 +414,8 @@ channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.) +=item @LAST_MATCH_START + =item @- $-[0] is the offset of the start of the last successful match. @@ -439,17 +443,17 @@ After a match against some variable $var: =over 5 -=item C<$`> is the same as C<substr($var, 0, $-[0]>) +=item C<$`> is the same as C<substr($var, 0, $-[0])> -=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0]>) +=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> -=item C<$'> is the same as C<substr($var, $+[0]>) +=item C<$'> is the same as C<substr($var, $+[0])> =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> -=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3]>) +=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])> =back @@ -814,7 +818,7 @@ Then $^M = 'a' x (1 << 16); -would allocate a 64K buffer for use when in emergency. See the +would allocate a 64K buffer for use in an emergency. See the F<INSTALL> file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced feature, there is no L<English> long name for this variable. diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 3c0927e28d..c696e19d16 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -534,7 +534,7 @@ the parameters in the correct order for that function. =head2 The PREINIT: Keyword The PREINIT: keyword allows extra variables to be declared immediately -before or after the declartions of the parameters from the INPUT: section +before or after the declarations of the parameters from the INPUT: section are emitted. If a variable is declared inside a CODE: section it will follow any typemap diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 88c04ad300..4756a9edbb 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -114,6 +114,7 @@ The file Mytest.pm should start with something like this: package Mytest; use strict; + use warnings; require Exporter; require DynaLoader; @@ -475,7 +476,7 @@ section on the argument stack. In general, it's not a good idea to write extensions that modify their input parameters, as in Example 3. Instead, you should probably return multiple values in an array and let the caller handle them (we'll do this in a later -example). However, in order to better accomodate calling pre-existing C +example). However, in order to better accommodate calling pre-existing C routines, which often do modify their input parameters, this behavior is tolerated. @@ -905,7 +906,7 @@ to assist in making the interface between Perl and your extension simpler or easier to understand. These routines should live in the .pm file. Whether they are automatically loaded when the extension itself is loaded or only loaded when called depends on where in the .pm file the subroutine -definition is placed. You can also consult L<Autoloader> for an alternate +definition is placed. You can also consult L<AutoLoader> for an alternate way to store and load your extra subroutines. =head2 Documenting your Extension diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 4312e9fbe3..bf35cff4cc 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -36,14 +36,12 @@ $Config{startperl} print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. +# $Id: pod2man.PL,v 1.2 2000/03/16 21:08:23 eagle Exp $ # -# Copyright 1999 by Russ Allbery <rra@stanford.edu> +# Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> # # This program is free software; you can redistribute it and/or modify it # under the same terms as Perl itself. -# -# The driver script for Pod::Man. This script is expected to eventually -# replace pod2man in the standard Perl distribution. require 5.004; @@ -52,12 +50,17 @@ use Pod::Man (); use Pod::Usage qw(pod2usage); use strict; -use vars; + +# Insert -- into @ARGV before any single dash argument to hide it from +# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser +# does correctly). +my $stdin; +@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; # Parse our options, trying to retain backwards compatibility with pod2man # but allowing short forms as well. --lax is currently ignored. my %options; -Getopt::Long::config ('bundling'); +Getopt::Long::config ('bundling_override'); GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'official|o', 'lax|l', 'help|h') or exit 1; @@ -80,13 +83,13 @@ pod2man - Convert POD data to formatted *roff input =head1 SYNOPSIS -pod2txt [B<--section>=I<manext>] [B<--release>=I<version>] +pod2man [B<--section>=I<manext>] [B<--release>=I<version>] [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] [B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input> [I<output>]] -pod2txt B<--help> +pod2man B<--help> =head1 DESCRIPTION @@ -320,11 +323,11 @@ functions. =item ERRORS -Exceptions, error return codes, exit stati, and errno settings. Typically -used for function documentation; program documentation uses DIAGNOSTICS -instead. The general rule of thumb is that errors printed to STDOUT or -STDERR and intended for the end user are documented in DIAGNOSTICS while -errors passed internal to the calling program and intended for other +Exceptions, error return codes, exit statuses, and errno settings. +Typically used for function documentation; program documentation uses +DIAGNOSTICS instead. The general rule of thumb is that errors printed to +STDOUT or STDERR and intended for the end user are documented in DIAGNOSTICS +while errors passed internal to the calling program and intended for other programmers are documented in ERRORS. When documenting a function that sets errno, a full list of the possible errno values should be given here. @@ -463,6 +466,7 @@ page, are taken from the B<pod2man> documentation by Tom. =cut !NO!SUBS! +#'# (cperl-mode) close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; diff --git a/pod/pod2text.PL b/pod/pod2text.PL index 79cf8b219b..c5460aef30 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!'; # pod2text -- Convert POD data to formatted ASCII text. # -# Copyright 1999 by Russ Allbery <rra@stanford.edu> +# Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> # # This program is free software; you can redistribute it and/or modify it # under the same terms as Perl itself. @@ -52,7 +52,6 @@ use Pod::Text (); use Pod::Usage qw(pod2usage); use strict; -use vars qw($ID); # Take an initial pass through our options, looking for one of the form # -<number>. We turn that into -w <number> for compatibility with the @@ -64,14 +63,19 @@ for (my $i = 0; $i < @ARGV; $i++) { } } +# Insert -- into @ARGV before any single dash argument to hide it from +# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Parser +# does correctly). +my $stdin; +@ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; + # Parse our options. Use the same names as Pod::Text for simplicity, and # default to sentence boundaries turned off for compatibility. my %options; -$options{termcap} = -t STDOUT; $options{sentence} = 0; Getopt::Long::config ('bundling'); GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i', - 'loose|l', 'sentence|s', 'termcap|t!', 'width|w=i') or exit 1; + 'loose|l', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1; pod2usage (1) if $options{help}; # Figure out what formatter we're going to use. -c overrides -t. @@ -114,10 +118,6 @@ code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, is the file to which to write the formatted output. If I<output> isn't given, the formatted output is written to STDOUT. -B<pod2text> defaults to trying to use Pod::Text::Termcap if STDOUT is a tty. -To explicitly say not to attempt termcap escape sequences, use -B<--notermcap>. - =head1 OPTIONS =over 4 @@ -160,9 +160,9 @@ Try to determine the width of the screen and the bold and underline sequences for the terminal from termcap, and use that information in formatting the output. Output will be wrapped at two columns less than the width of your terminal device. Using this option requires that your system -have a termcap file somewhere where Term::Cap can find it. With this -option, the output of B<pod2text> will contain terminal control sequences -for your current terminal type. +have a termcap file somewhere where Term::Cap can find it and requires that +your system support termios. With this option, the output of B<pod2text> +will contain terminal control sequences for your current terminal type. =item B<-w>, B<--width=>I<width>, B<->I<width> diff --git a/pod/roffitall b/pod/roffitall index ebfcc7e264..018c0b3475 100644 --- a/pod/roffitall +++ b/pod/roffitall @@ -56,6 +56,7 @@ toroff=` $mandir/perlbot.1 \ $mandir/perlipc.1 \ $mandir/perlthrtut.1 \ + $mandir/perldebguts.1 \ $mandir/perldebug.1 \ $mandir/perlnumber.1 \ $mandir/perldiag.1 \ |