Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1567 insertions, 0 deletions

diff --git a/upstream/fedora-40/man1/perl5004delta.1 b/upstream/fedora-40/man1/perl5004delta.1
new file mode 100644
index 00000000..8acb2ee1
--- /dev/null
+++ b/upstream/fedora-40/man1/perl5004delta.1
@@ -0,0 +1,1567 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERL5004DELTA 1"
+.TH PERL5004DELTA 1 2024-01-25 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perl5004delta \- what's new for perl5.004
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This document describes differences between the 5.003 release (as
+documented in \fIProgramming Perl\fR, second edition\-\-the Camel Book) and
+this one.
+.SH "Supported Environments"
+.IX Header "Supported Environments"
+Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2,
+QNX, AmigaOS, and Windows NT.  Perl runs on Windows 95 as well, but it
+cannot be built there, for lack of a reasonable command interpreter.
+.SH "Core Changes"
+.IX Header "Core Changes"
+Most importantly, many bugs were fixed, including several security
+problems.  See the \fIChanges\fR file in the distribution for details.
+.ie n .SS "List assignment to %ENV works"
+.el .SS "List assignment to \f(CW%ENV\fP works"
+.IX Subsection "List assignment to %ENV works"
+\&\f(CW\*(C`%ENV = ()\*(C'\fR and \f(CW\*(C`%ENV = @list\*(C'\fR now work as expected (except on VMS
+where it generates a fatal error).
+.ie n .SS "Change to ""Can't locate Foo.pm in @INC"" error"
+.el .SS "Change to ""Can't locate Foo.pm in \f(CW@INC\fP"" error"
+.IX Subsection "Change to ""Can't locate Foo.pm in @INC"" error"
+The error "Can't locate Foo.pm in \f(CW@INC\fR" now lists the contents of \f(CW@INC\fR
+for easier debugging.
+.SS "Compilation option: Binary compatibility with 5.003"
+.IX Subsection "Compilation option: Binary compatibility with 5.003"
+There is a new Configure question that asks if you want to maintain
+binary compatibility with Perl 5.003.  If you choose binary
+compatibility, you do not have to recompile your extensions, but you
+might have symbol conflicts if you embed Perl in another application,
+just as in the 5.003 release.  By default, binary compatibility
+is preserved at the expense of symbol table pollution.
+.ie n .SS "$PERL5OPT environment variable"
+.el .SS "\f(CW$PERL5OPT\fP environment variable"
+.IX Subsection "$PERL5OPT environment variable"
+You may now put Perl options in the \f(CW$PERL5OPT\fR environment variable.
+Unless Perl is running with taint checks, it will interpret this
+variable as if its contents had appeared on a "#!perl" line at the
+beginning of your script, except that hyphens are optional.  PERL5OPT
+may only be used to set the following switches: \fB\-[DIMUdmw]\fR.
+.SS "Limitations on \fB\-M\fP, \fB\-m\fP, and \fB\-T\fP options"
+.IX Subsection "Limitations on -M, -m, and -T options"
+The \f(CW\*(C`\-M\*(C'\fR and \f(CW\*(C`\-m\*(C'\fR options are no longer allowed on the \f(CW\*(C`#!\*(C'\fR line of
+a script.  If a script needs a module, it should invoke it with the
+\&\f(CW\*(C`use\*(C'\fR pragma.
+.PP
+The \fB\-T\fR option is also forbidden on the \f(CW\*(C`#!\*(C'\fR line of a script,
+unless it was present on the Perl command line.  Due to the way \f(CW\*(C`#!\*(C'\fR
+works, this usually means that \fB\-T\fR must be in the first argument.
+Thus:
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-T \-w
+.Ve
+.PP
+will probably work for an executable script invoked as \f(CW\*(C`scriptname\*(C'\fR,
+while:
+.PP
+.Vb 1
+\&    #!/usr/bin/perl \-w \-T
+.Ve
+.PP
+will probably fail under the same conditions.  (Non-Unix systems will
+probably not follow this rule.)  But \f(CW\*(C`perl scriptname\*(C'\fR is guaranteed
+to fail, since then there is no chance of \fB\-T\fR being found on the
+command line before it is found on the \f(CW\*(C`#!\*(C'\fR line.
+.SS "More precise warnings"
+.IX Subsection "More precise warnings"
+If you removed the \fB\-w\fR option from your Perl 5.003 scripts because it
+made Perl too verbose, we recommend that you try putting it back when
+you upgrade to Perl 5.004.  Each new perl version tends to remove some
+undesirable warnings, while adding new warnings that may catch bugs in
+your scripts.
+.ie n .SS "Deprecated: Inherited ""AUTOLOAD"" for non-methods"
+.el .SS "Deprecated: Inherited \f(CWAUTOLOAD\fP for non-methods"
+.IX Subsection "Deprecated: Inherited AUTOLOAD for non-methods"
+Before Perl 5.004, \f(CW\*(C`AUTOLOAD\*(C'\fR functions were looked up as methods
+(using the \f(CW@ISA\fR hierarchy), even when the function to be autoloaded
+was called as a plain function (e.g. \f(CWFoo::bar()\fR), not a method
+(e.g. \f(CW\*(C`Foo\->bar()\*(C'\fR or \f(CW\*(C`$obj\->bar()\*(C'\fR).
+.PP
+Perl 5.005 will use method lookup only for methods' \f(CW\*(C`AUTOLOAD\*(C'\fRs.
+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 a non-method uses an inherited \f(CW\*(C`AUTOLOAD\*(C'\fR.
+.PP
+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 \f(CW\*(C`AUTOLOAD\*(C'\fR for non-methods from a base class named
+\&\f(CW\*(C`BaseClass\*(C'\fR, execute \f(CW\*(C`*AUTOLOAD = \e&BaseClass::AUTOLOAD\*(C'\fR during startup.
+.ie n .SS "Previously deprecated %OVERLOAD is no longer usable"
+.el .SS "Previously deprecated \f(CW%OVERLOAD\fP is no longer usable"
+.IX Subsection "Previously deprecated %OVERLOAD is no longer usable"
+Using \f(CW%OVERLOAD\fR to define overloading was deprecated in 5.003.
+Overloading is now defined using the overload pragma. \f(CW%OVERLOAD\fR is
+still used internally but should not be used by Perl scripts. See
+overload for more details.
+.SS "Subroutine arguments created only when they're modified"
+.IX Subsection "Subroutine arguments created only when they're modified"
+In Perl 5.004, nonexistent array and hash elements used as subroutine
+parameters are brought into existence only if they are actually
+assigned to (via \f(CW@_\fR).
+.PP
+Earlier versions of Perl vary in their handling of such arguments.
+Perl versions 5.002 and 5.003 always brought them into existence.
+Perl versions 5.000 and 5.001 brought them into existence only if
+they were not the first argument (which was almost certainly a bug).
+Earlier versions of Perl never brought them into existence.
+.PP
+For example, given this code:
+.PP
+.Vb 5
+\&     undef @a; undef %a;
+\&     sub show { print $_[0] };
+\&     sub change { $_[0]++ };
+\&     show($a[2]);
+\&     change($a{b});
+.Ve
+.PP
+After this code executes in Perl 5.004, \f(CW$a\fR{b} exists but \f(CW$a\fR[2] does
+not.  In Perl 5.002 and 5.003, both \f(CW$a\fR{b} and \f(CW$a\fR[2] would have existed
+(but \f(CW$a\fR[2]'s value would have been undefined).
+.ie n .SS "Group vector changeable with $)"
+.el .SS "Group vector changeable with \f(CW$)\fP"
+.IX Subsection "Group vector changeable with $)"
+The \f(CW$)\fR special variable has always (well, in Perl 5, at least)
+reflected not only the current effective group, but also the group list
+as returned by the \f(CWgetgroups()\fR C function (if there is one).
+However, until this release, there has not been a way to call the
+\&\f(CWsetgroups()\fR C function from Perl.
+.PP
+In Perl 5.004, assigning to \f(CW$)\fR is exactly symmetrical with examining
+it: The first number in its string value is used as the effective gid;
+if there are any numbers after the first one, they are passed to the
+\&\f(CWsetgroups()\fR C function (if there is one).
+.SS "Fixed parsing of $$<digit>, &$<digit>, etc."
+.IX Subsection "Fixed parsing of $$<digit>, &$<digit>, etc."
+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.
+.PP
+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.
+.SS "Fixed localization of $<digit>, $&, etc."
+.IX Subsection "Fixed localization of $<digit>, $&, etc."
+Perl versions before 5.004 did not always properly localize the
+regex-related special variables.  Perl 5.004 does localize them, as
+the documentation has always said it should.  This may result in \f(CW$1\fR,
+\&\f(CW$2\fR, etc. no longer being set where existing programs use them.
+.SS "No resetting of $. on implicit close"
+.IX Subsection "No resetting of $. on implicit close"
+The documentation for Perl 5.0 has always stated that \f(CW$.\fR is \fInot\fR
+reset when an already-open file handle is reopened with no intervening
+call to \f(CW\*(C`close\*(C'\fR.  Due to a bug, perl versions 5.000 through 5.003
+\&\fIdid\fR reset \f(CW$.\fR under that circumstance; Perl 5.004 does not.
+.ie n .SS """wantarray"" may return undef"
+.el .SS "\f(CWwantarray\fP may return undef"
+.IX Subsection "wantarray may return undef"
+The \f(CW\*(C`wantarray\*(C'\fR operator returns true if a subroutine is expected to
+return a list, and false otherwise.  In Perl 5.004, \f(CW\*(C`wantarray\*(C'\fR can
+also return the undefined value if a subroutine's return value will
+not be used at all, which allows subroutines to avoid a time-consuming
+calculation of a return value if it isn't going to be used.
+.ie n .SS """eval EXPR"" determines value of EXPR in scalar context"
+.el .SS "\f(CWeval EXPR\fP determines value of EXPR in scalar context"
+.IX Subsection "eval EXPR determines value of EXPR in scalar context"
+Perl (version 5) used to determine the value of EXPR inconsistently,
+sometimes incorrectly using the surrounding context for the determination.
+Now, the value of EXPR (before being parsed by eval) is always determined in
+a scalar context.  Once parsed, it is executed as before, by providing
+the context that the scope surrounding the eval provided.  This change
+makes the behavior Perl4 compatible, besides fixing bugs resulting from
+the inconsistent behavior.  This program:
+.PP
+.Vb 3
+\&    @a = qw(time now is time);
+\&    print eval @a;
+\&    print \*(Aq|\*(Aq, scalar eval @a;
+.Ve
+.PP
+used to print something like "timenowis881399109|4", but now (and in perl4)
+prints "4|4".
+.SS "Changes to tainting checks"
+.IX Subsection "Changes to tainting checks"
+A bug in previous versions may have failed to detect some insecure
+conditions when taint checks are turned on.  (Taint checks are used
+in setuid or setgid scripts, or when explicitly turned on with the
+\&\f(CW\*(C`\-T\*(C'\fR invocation option.)  Although it's unlikely, this may cause a
+previously-working script to now fail, which should be construed
+as a blessing since that indicates a potentially-serious security
+hole was just plugged.
+.PP
+The new restrictions when tainting include:
+.IP "No \fBglob()\fR or <*>" 4
+.IX Item "No glob() or <*>"
+These operators may spawn the C shell (csh), which cannot be made
+safe.  This restriction will be lifted in a future version of Perl
+when globbing is implemented without the use of an external program.
+.ie n .IP "No spawning if tainted $CDPATH, $ENV, $BASH_ENV" 4
+.el .IP "No spawning if tainted \f(CW$CDPATH\fR, \f(CW$ENV\fR, \f(CW$BASH_ENV\fR" 4
+.IX Item "No spawning if tainted $CDPATH, $ENV, $BASH_ENV"
+These environment variables may alter the behavior of spawned programs
+(especially shells) in ways that subvert security.  So now they are
+treated as dangerous, in the manner of \f(CW$IFS\fR and \f(CW$PATH\fR.
+.ie n .IP "No spawning if tainted $TERM doesn't look like a terminal name" 4
+.el .IP "No spawning if tainted \f(CW$TERM\fR doesn't look like a terminal name" 4
+.IX Item "No spawning if tainted $TERM doesn't look like a terminal name"
+Some termcap libraries do unsafe things with \f(CW$TERM\fR.  However, it would be
+unnecessarily harsh to treat all \f(CW$TERM\fR values as unsafe, since only shell
+metacharacters can cause trouble in \f(CW$TERM\fR.  So a tainted \f(CW$TERM\fR is
+considered to be safe if it contains only alphanumerics, underscores,
+dashes, and colons, and unsafe if it contains other characters (including
+whitespace).
+.SS "New Opcode module and revised Safe module"
+.IX Subsection "New Opcode module and revised Safe module"
+A new Opcode module supports the creation, manipulation and
+application of opcode masks.  The revised Safe module has a new API
+and is implemented using the new Opcode module.  Please read the new
+Opcode and Safe documentation.
+.SS "Embedding improvements"
+.IX Subsection "Embedding improvements"
+In older versions of Perl it was not possible to create more than one
+Perl interpreter instance inside a single process without leaking like a
+sieve and/or crashing.  The bugs that caused this behavior have all been
+fixed.  However, you still must take care when embedding Perl in a C
+program.  See the updated perlembed manpage for tips on how to manage
+your interpreters.
+.SS "Internal change: FileHandle class based on IO::* classes"
+.IX Subsection "Internal change: FileHandle class based on IO::* classes"
+File handles are now stored internally as type IO::Handle.  The
+FileHandle module is still supported for backwards compatibility, but
+it is now merely a front end to the IO::* modules, specifically
+IO::Handle, IO::Seekable, and IO::File.  We suggest, but do not
+require, that you use the IO::* modules in new code.
+.PP
+In harmony with this change, \f(CW*GLOB{FILEHANDLE}\fR is now just a
+backward-compatible synonym for \f(CW*GLOB{IO}\fR.
+.SS "Internal change: PerlIO abstraction interface"
+.IX Subsection "Internal change: PerlIO abstraction interface"
+It is now possible to build Perl with AT&T's sfio IO package
+instead of stdio.  See perlapio for more details, and
+the \fIINSTALL\fR file for how to use it.
+.SS "New and changed syntax"
+.IX Subsection "New and changed syntax"
+.ie n .IP $coderef\->(PARAMS) 4
+.el .IP \f(CW$coderef\fR\->(PARAMS) 4
+.IX Item "$coderef->(PARAMS)"
+A subroutine reference may now be suffixed with an arrow and a
+(possibly empty) parameter list.  This syntax denotes a call of the
+referenced subroutine, with the given parameters (if any).
+.Sp
+This new syntax follows the pattern of \f(CW\*(C`$hashref\->{FOO}\*(C'\fR and
+\&\f(CW\*(C`$aryref\->[$foo]\*(C'\fR: You may now write \f(CW&$subref($foo)\fR as
+\&\f(CW$subref\->($foo)\fR.  All these arrow terms may be chained;
+thus, \f(CW\*(C`&{$table\->{FOO}}($bar)\*(C'\fR may now be written
+\&\f(CW\*(C`$table\->{FOO}\->($bar)\*(C'\fR.
+.SS "New and changed builtin constants"
+.IX Subsection "New and changed builtin constants"
+.IP _\|_PACKAGE_\|_ 4
+.IX Item "__PACKAGE__"
+The current package name at compile time, or the undefined value if
+there is no current package (due to a \f(CW\*(C`package;\*(C'\fR directive).  Like
+\&\f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR does \fInot\fR interpolate
+into strings.
+.SS "New and changed builtin variables"
+.IX Subsection "New and changed builtin variables"
+.IP $^E 4
+.IX Item "$^E"
+Extended error message on some platforms.  (Also known as
+\&\f(CW$EXTENDED_OS_ERROR\fR if you \f(CW\*(C`use English\*(C'\fR).
+.IP $^H 4
+.IX Item "$^H"
+The current set of syntax checks enabled by \f(CW\*(C`use strict\*(C'\fR.  See the
+documentation of \f(CW\*(C`strict\*(C'\fR for more details.  Not actually new, but
+newly documented.
+Because it is intended for internal use by Perl core components,
+there is no \f(CW\*(C`use English\*(C'\fR long name for this variable.
+.IP $^M 4
+.IX Item "$^M"
+By default, running out of memory it is not trappable.  However, if
+compiled for this, Perl may use the contents of \f(CW$^M\fR as an emergency
+pool after \fBdie()\fRing with this message.  Suppose that your Perl were
+compiled with \-DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
+.Sp
+.Vb 1
+\&    $^M = \*(Aqa\*(Aq x (1<<16);
+.Ve
+.Sp
+would allocate a 64K buffer for use when in emergency.
+See the \fIINSTALL\fR file for information on how to enable this option.
+As a disincentive to casual use of this advanced feature,
+there is no \f(CW\*(C`use English\*(C'\fR long name for this variable.
+.SS "New and changed builtin functions"
+.IX Subsection "New and changed builtin functions"
+.IP "delete on slices" 4
+.IX Item "delete on slices"
+This now works.  (e.g. \f(CW\*(C`delete @ENV{\*(AqPATH\*(Aq, \*(AqMANPATH\*(Aq}\*(C'\fR)
+.IP flock 4
+.IX Item "flock"
+is now supported on more platforms, prefers fcntl to lockf when
+emulating, and always flushes before (un)locking.
+.IP "printf and sprintf" 4
+.IX Item "printf and sprintf"
+Perl now implements these functions itself; it doesn't use the C
+library function \fBsprintf()\fR any more, except for floating-point
+numbers, and even then only known flags are allowed.  As a result, it
+is now possible to know which conversions and flags will work, and
+what they will do.
+.Sp
+The new conversions in Perl's \fBsprintf()\fR are:
+.Sp
+.Vb 4
+\&   %i   a synonym for %d
+\&   %p   a pointer (the address of the Perl value, in hexadecimal)
+\&   %n   special: *stores* the number of characters output so far
+\&        into the next variable in the parameter list
+.Ve
+.Sp
+The new flags that go between the \f(CW\*(C`%\*(C'\fR and the conversion are:
+.Sp
+.Vb 3
+\&   #    prefix octal with "0", hex with "0x"
+\&   h    interpret integer as C type "short" or "unsigned short"
+\&   V    interpret integer as Perl\*(Aqs standard integer type
+.Ve
+.Sp
+Also, where a number would appear in the flags, an asterisk ("*") may
+be used instead, in which case Perl uses the next item in the
+parameter list as the given number (that is, as the field width or
+precision).  If a field width obtained through "*" is negative, it has
+the same effect as the '\-' flag: left-justification.
+.Sp
+See "sprintf" in perlfunc for a complete list of conversion and flags.
+.IP "keys as an lvalue" 4
+.IX Item "keys as an lvalue"
+As an lvalue, \f(CW\*(C`keys\*(C'\fR allows you to increase the number of hash buckets
+allocated for the given hash.  This can gain you a measure of efficiency if
+you know the hash is going to get big.  (This is similar to pre-extending
+an array by assigning a larger number to $#array.)  If you say
+.Sp
+.Vb 1
+\&    keys %hash = 200;
+.Ve
+.Sp
+then \f(CW%hash\fR will have at least 200 buckets allocated for it.  These
+buckets will be retained even if you do \f(CW\*(C`%hash = ()\*(C'\fR; use \f(CWundef
+%hash\fR if you want to free the storage while \f(CW%hash\fR is still in scope.
+You can't shrink the number of buckets allocated for the hash using
+\&\f(CW\*(C`keys\*(C'\fR in this way (but you needn't worry about doing this by accident,
+as trying has no effect).
+.IP "\fBmy()\fR in Control Structures" 4
+.IX Item "my() in Control Structures"
+You can now use \fBmy()\fR (with or without the parentheses) in the control
+expressions of control structures such as:
+.Sp
+.Vb 5
+\&    while (defined(my $line = <>)) {
+\&        $line = lc $line;
+\&    } continue {
+\&        print $line;
+\&    }
+\&
+\&    if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
+\&        user_agrees();
+\&    } elsif ($answer =~ /^n(o)?$/i) {
+\&        user_disagrees();
+\&    } else {
+\&        chomp $answer;
+\&        die "\`$answer\*(Aq is neither \`yes\*(Aq nor \`no\*(Aq";
+\&    }
+.Ve
+.Sp
+Also, you can declare a foreach loop control variable as lexical by
+preceding it with the word "my".  For example, in:
+.Sp
+.Vb 3
+\&    foreach my $i (1, 2, 3) {
+\&        some_function();
+\&    }
+.Ve
+.Sp
+\&\f(CW$i\fR is a lexical variable, and the scope of \f(CW$i\fR extends to the end of
+the loop, but not beyond it.
+.Sp
+Note that you still cannot use \fBmy()\fR on global punctuation variables
+such as \f(CW$_\fR and the like.
+.IP "\fBpack()\fR and \fBunpack()\fR" 4
+.IX Item "pack() and unpack()"
+A new format 'w' represents a BER compressed integer (as defined in
+ASN.1).  Its format is a sequence of one or more bytes, each of which
+provides seven bits of the total value, with the most significant
+first.  Bit eight of each byte is set, except for the last byte, in
+which bit eight is clear.
+.Sp
+If 'p' or 'P' are given undef as values, they now generate a NULL
+pointer.
+.Sp
+Both \fBpack()\fR and \fBunpack()\fR now fail when their templates contain invalid
+types.  (Invalid types used to be ignored.)
+.IP \fBsysseek()\fR 4
+.IX Item "sysseek()"
+The new \fBsysseek()\fR operator is a variant of \fBseek()\fR that sets and gets the
+file's system read/write position, using the \fBlseek\fR\|(2) system call.  It is
+the only reliable way to seek before using \fBsysread()\fR or \fBsyswrite()\fR.  Its
+return value is the new position, or the undefined value on failure.
+.IP "use VERSION" 4
+.IX Item "use VERSION"
+If the first argument to \f(CW\*(C`use\*(C'\fR is a number, it is treated as a version
+number instead of a module name.  If the version of the Perl interpreter
+is less than VERSION, then an error message is printed and Perl exits
+immediately.  Because \f(CW\*(C`use\*(C'\fR occurs at compile time, this check happens
+immediately during the compilation process, unlike \f(CW\*(C`require VERSION\*(C'\fR,
+which waits until runtime for the check.  This is often useful if you
+need to check the current Perl version before \f(CW\*(C`use\*(C'\fRing library modules
+which have changed in incompatible ways from older versions of Perl.
+(We try not to do this more than we have to.)
+.IP "use Module VERSION LIST" 4
+.IX Item "use Module VERSION LIST"
+If the VERSION argument is present between Module and LIST, then the
+\&\f(CW\*(C`use\*(C'\fR will call the VERSION method in class Module with the given
+version as an argument.  The default VERSION method, inherited from
+the UNIVERSAL class, croaks if the given version is larger than the
+value of the variable \f(CW$Module::VERSION\fR.  (Note that there is not a
+comma after VERSION!)
+.Sp
+This version-checking mechanism is similar to the one currently used
+in the Exporter module, but it is faster and can be used with modules
+that don't use the Exporter.  It is the recommended method for new
+code.
+.IP prototype(FUNCTION) 4
+.IX Item "prototype(FUNCTION)"
+Returns the prototype of a function as a string (or \f(CW\*(C`undef\*(C'\fR if the
+function has no prototype).  FUNCTION is a reference to or the name of the
+function whose prototype you want to retrieve.
+(Not actually new; just never documented before.)
+.IP srand 4
+.IX Item "srand"
+The default seed for \f(CW\*(C`srand\*(C'\fR, which used to be \f(CW\*(C`time\*(C'\fR, has been changed.
+Now it's a heady mix of difficult-to-predict system-dependent values,
+which should be sufficient for most everyday purposes.
+.Sp
+Previous to version 5.004, calling \f(CW\*(C`rand\*(C'\fR without first calling \f(CW\*(C`srand\*(C'\fR
+would yield the same sequence of random numbers on most or all machines.
+Now, when perl sees that you're calling \f(CW\*(C`rand\*(C'\fR and haven't yet called
+\&\f(CW\*(C`srand\*(C'\fR, it calls \f(CW\*(C`srand\*(C'\fR with the default seed. You should still call
+\&\f(CW\*(C`srand\*(C'\fR manually if your code might ever be run on a pre\-5.004 system,
+of course, or if you want a seed other than the default.
+.ie n .IP "$_ as Default" 4
+.el .IP "\f(CW$_\fR as Default" 4
+.IX Item "$_ as Default"
+Functions documented in the Camel to default to \f(CW$_\fR now in
+fact do, and all those that do are so documented in perlfunc.
+.ie n .IP """m//gc"" does not reset search position on failure" 4
+.el .IP "\f(CWm//gc\fR does not reset search position on failure" 4
+.IX Item "m//gc does not reset search position on failure"
+The \f(CW\*(C`m//g\*(C'\fR match iteration construct has always reset its target
+string's search position (which is visible through the \f(CW\*(C`pos\*(C'\fR operator)
+when a match fails; as a result, the next \f(CW\*(C`m//g\*(C'\fR match after a failure
+starts again at the beginning of the string.  With Perl 5.004, this
+reset may be disabled by adding the "c" (for "continue") modifier,
+i.e. \f(CW\*(C`m//gc\*(C'\fR.  This feature, in conjunction with the \f(CW\*(C`\eG\*(C'\fR zero-width
+assertion, makes it possible to chain matches together.  See perlop
+and perlre.
+.ie n .IP """m//x"" ignores whitespace before ?*+{}" 4
+.el .IP "\f(CWm//x\fR ignores whitespace before ?*+{}" 4
+.IX Item "m//x ignores whitespace before ?*+{}"
+The \f(CW\*(C`m//x\*(C'\fR construct has always been intended to ignore all unescaped
+whitespace.  However, before Perl 5.004, whitespace had the effect of
+escaping repeat modifiers like "*" or "?"; for example, \f(CW\*(C`/a *b/x\*(C'\fR was
+(mis)interpreted as \f(CW\*(C`/a\e*b/x\*(C'\fR.  This bug has been fixed in 5.004.
+.ie n .IP "nested ""sub{}"" closures work now" 4
+.el .IP "nested \f(CWsub{}\fR closures work now" 4
+.IX Item "nested sub{} closures work now"
+Prior to the 5.004 release, nested anonymous functions didn't work
+right.  They do now.
+.IP "formats work right on changing lexicals" 4
+.IX Item "formats work right on changing lexicals"
+Just like anonymous functions that contain lexical variables
+that change (like a lexical index variable for a \f(CW\*(C`foreach\*(C'\fR loop),
+formats now work properly.  For example, this silently failed
+before (printed only zeros), but is fine now:
+.Sp
+.Vb 8
+\&    my $i;
+\&    foreach $i ( 1 .. 10 ) {
+\&        write;
+\&    }
+\&    format =
+\&        my i is @#
+\&        $i
+\&    .
+.Ve
+.Sp
+However, it still fails (without a warning) if the foreach is within a
+subroutine:
+.Sp
+.Vb 11
+\&    my $i;
+\&    sub foo {
+\&      foreach $i ( 1 .. 10 ) {
+\&        write;
+\&      }
+\&    }
+\&    foo;
+\&    format =
+\&        my i is @#
+\&        $i
+\&    .
+.Ve
+.SS "New builtin methods"
+.IX Subsection "New builtin methods"
+The \f(CW\*(C`UNIVERSAL\*(C'\fR package automatically contains the following methods that
+are inherited by all other classes:
+.IP isa(CLASS) 4
+.IX Item "isa(CLASS)"
+\&\f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if its object is blessed into a subclass of \f(CW\*(C`CLASS\*(C'\fR
+.Sp
+\&\f(CW\*(C`isa\*(C'\fR is also exportable and can be called as a sub with two arguments. This
+allows the ability to check what a reference points to. Example:
+.Sp
+.Vb 1
+\&    use UNIVERSAL qw(isa);
+\&
+\&    if(isa($ref, \*(AqARRAY\*(Aq)) {
+\&       ...
+\&    }
+.Ve
+.IP can(METHOD) 4
+.IX Item "can(METHOD)"
+\&\f(CW\*(C`can\*(C'\fR checks to see if its object has a method called \f(CW\*(C`METHOD\*(C'\fR,
+if it does then a reference to the sub is returned; if it does not then
+\&\fIundef\fR is returned.
+.IP "VERSION( [NEED] )" 4
+.IX Item "VERSION( [NEED] )"
+\&\f(CW\*(C`VERSION\*(C'\fR returns the version number of the class (package).  If the
+NEED argument is given then it will check that the current version (as
+defined by the \f(CW$VERSION\fR variable in the given package) not less than
+NEED; it will die if this is not the case.  This method is normally
+called as a class method.  This method is called automatically by the
+\&\f(CW\*(C`VERSION\*(C'\fR form of \f(CW\*(C`use\*(C'\fR.
+.Sp
+.Vb 3
+\&    use A 1.2 qw(some imported subs);
+\&    # implies:
+\&    A\->VERSION(1.2);
+.Ve
+.PP
+\&\fBNOTE:\fR \f(CW\*(C`can\*(C'\fR directly uses Perl's internal code for method lookup, and
+\&\f(CW\*(C`isa\*(C'\fR uses a very similar method and caching strategy. This may cause
+strange effects if the Perl code dynamically changes \f(CW@ISA\fR in any package.
+.PP
+You may add other methods to the UNIVERSAL class via Perl or XS code.
+You do not need to \f(CW\*(C`use UNIVERSAL\*(C'\fR in order to make these methods
+available to your program.  This is necessary only if you wish to
+have \f(CW\*(C`isa\*(C'\fR available as a plain subroutine in the current package.
+.SS "TIEHANDLE now supported"
+.IX Subsection "TIEHANDLE now supported"
+See perltie for other kinds of \fBtie()\fRs.
+.IP "TIEHANDLE classname, LIST" 4
+.IX Item "TIEHANDLE classname, LIST"
+This is the constructor for the class.  That means it is expected to
+return an object of some sort. The reference can be used to
+hold some internal information.
+.Sp
+.Vb 5
+\&    sub TIEHANDLE {
+\&        print "<shout>\en";
+\&        my $i;
+\&        return bless \e$i, shift;
+\&    }
+.Ve
+.IP "PRINT this, LIST" 4
+.IX Item "PRINT this, LIST"
+This method will be triggered every time the tied handle is printed to.
+Beyond its self reference it also expects the list that was passed to
+the print function.
+.Sp
+.Vb 5
+\&    sub PRINT {
+\&        $r = shift;
+\&        $$r++;
+\&        return print join( $, => map {uc} @_), $\e;
+\&    }
+.Ve
+.IP "PRINTF this, LIST" 4
+.IX Item "PRINTF this, LIST"
+This method will be triggered every time the tied handle is printed to
+with the \f(CWprintf()\fR function.
+Beyond its self reference it also expects the format and list that was
+passed to the printf function.
+.Sp
+.Vb 5
+\&    sub PRINTF {
+\&        shift;
+\&          my $fmt = shift;
+\&        print sprintf($fmt, @_)."\en";
+\&    }
+.Ve
+.IP "READ this LIST" 4
+.IX Item "READ this LIST"
+This method will be called when the handle is read from via the \f(CW\*(C`read\*(C'\fR
+or \f(CW\*(C`sysread\*(C'\fR functions.
+.Sp
+.Vb 5
+\&    sub READ {
+\&        $r = shift;
+\&        my($buf,$len,$offset) = @_;
+\&        print "READ called, \e$buf=$buf, \e$len=$len, \e$offset=$offset";
+\&    }
+.Ve
+.IP "READLINE this" 4
+.IX Item "READLINE this"
+This method will be called when the handle is read from. The method
+should return undef when there is no more data.
+.Sp
+.Vb 4
+\&    sub READLINE {
+\&        $r = shift;
+\&        return "PRINT called $$r times\en"
+\&    }
+.Ve
+.IP "GETC this" 4
+.IX Item "GETC this"
+This method will be called when the \f(CW\*(C`getc\*(C'\fR function is called.
+.Sp
+.Vb 1
+\&    sub GETC { print "Don\*(Aqt GETC, Get Perl"; return "a"; }
+.Ve
+.IP "DESTROY this" 4
+.IX Item "DESTROY this"
+As with the other types of ties, this method will be called when the
+tied handle is about to be destroyed. This is useful for debugging and
+possibly for cleaning up.
+.Sp
+.Vb 3
+\&    sub DESTROY {
+\&        print "</shout>\en";
+\&    }
+.Ve
+.SS "Malloc enhancements"
+.IX Subsection "Malloc enhancements"
+If perl is compiled with the malloc included with the perl distribution
+(that is, if \f(CW\*(C`perl \-V:d_mymalloc\*(C'\fR is 'define') then you can print
+memory statistics at runtime by running Perl thusly:
+.PP
+.Vb 1
+\&  env PERL_DEBUG_MSTATS=2 perl your_script_here
+.Ve
+.PP
+The value of 2 means to print statistics after compilation and on
+exit; with a value of 1, the statistics are printed only on exit.
+(If you want the statistics at an arbitrary time, you'll need to
+install the optional module Devel::Peek.)
+.PP
+Three new compilation flags are recognized by malloc.c.  (They have no
+effect if perl is compiled with system \fBmalloc()\fR.)
+.IP \-DPERL_EMERGENCY_SBRK 4
+.IX Item "-DPERL_EMERGENCY_SBRK"
+If this macro is defined, running out of memory need not be a fatal
+error: a memory pool can allocated by assigning to the special
+variable \f(CW$^M\fR.  See "$^M".
+.IP \-DPACK_MALLOC 4
+.IX Item "-DPACK_MALLOC"
+Perl memory allocation is by bucket with sizes close to powers of two.
+Because of these malloc overhead may be big, especially for data of
+size exactly a power of two.  If \f(CW\*(C`PACK_MALLOC\*(C'\fR is defined, perl uses
+a slightly different algorithm for small allocations (up to 64 bytes
+long), which makes it possible to have overhead down to 1 byte for
+allocations which are powers of two (and appear quite often).
+.Sp
+Expected memory savings (with 8\-byte alignment in \f(CW\*(C`alignbytes\*(C'\fR) is
+about 20% for typical Perl usage.  Expected slowdown due to additional
+malloc overhead is in fractions of a percent (hard to measure, because
+of the effect of saved memory on speed).
+.IP \-DTWO_POT_OPTIMIZE 4
+.IX Item "-DTWO_POT_OPTIMIZE"
+Similarly to \f(CW\*(C`PACK_MALLOC\*(C'\fR, this macro improves allocations of data
+with size close to a power of two; but this works for big allocations
+(starting with 16K by default).  Such allocations are typical for big
+hashes and special-purpose scripts, especially image processing.
+.Sp
+On recent systems, the fact that perl requires 2M from system for 1M
+allocation will not affect speed of execution, since the tail of such
+a chunk is not going to be touched (and thus will not require real
+memory).  However, it may result in a premature out-of-memory error.
+So if you will be manipulating very large blocks with sizes close to
+powers of two, it would be wise to define this macro.
+.Sp
+Expected saving of memory is 0\-100% (100% in applications which
+require most memory in such 2**n chunks); expected slowdown is
+negligible.
+.SS "Miscellaneous efficiency enhancements"
+.IX Subsection "Miscellaneous efficiency enhancements"
+Functions that have an empty prototype and that do nothing but return
+a fixed value are now inlined (e.g. \f(CW\*(C`sub PI () { 3.14159 }\*(C'\fR).
+.PP
+Each unique hash key is only allocated once, no matter how many hashes
+have an entry with that key.  So even if you have 100 copies of the
+same hash, the hash keys never have to be reallocated.
+.SH "Support for More Operating Systems"
+.IX Header "Support for More Operating Systems"
+Support for the following operating systems is new in Perl 5.004.
+.SS Win32
+.IX Subsection "Win32"
+Perl 5.004 now includes support for building a "native" perl under
+Windows NT, using the Microsoft Visual C++ compiler (versions 2.0
+and above) or the Borland C++ compiler (versions 5.02 and above).
+The resulting perl can be used under Windows 95 (if it
+is installed in the same directory locations as it got installed
+in Windows NT).  This port includes support for perl extension
+building tools like ExtUtils::MakeMaker and h2xs, so that many extensions
+available on the Comprehensive Perl Archive Network (CPAN) can now be
+readily built under Windows NT.  See http://www.perl.com/ for more
+information on CPAN and \fIREADME.win32\fR in the perl distribution for more
+details on how to get started with building this port.
+.PP
+There is also support for building perl under the Cygwin32 environment.
+Cygwin32 is a set of GNU tools that make it possible to compile and run
+many Unix programs under Windows NT by providing a mostly Unix-like 
+interface for compilation and execution.  See \fIREADME.cygwin32\fR in the
+perl distribution for more details on this port and how to obtain the
+Cygwin32 toolkit.
+.SS "Plan 9"
+.IX Subsection "Plan 9"
+See \fIREADME.plan9\fR in the perl distribution.
+.SS QNX
+.IX Subsection "QNX"
+See \fIREADME.qnx\fR in the perl distribution.
+.SS AmigaOS
+.IX Subsection "AmigaOS"
+See \fIREADME.amigaos\fR in the perl distribution.
+.SH Pragmata
+.IX Header "Pragmata"
+Six new pragmatic modules exist:
+.IP "use autouse MODULE => qw(sub1 sub2 sub3)" 4
+.IX Item "use autouse MODULE => qw(sub1 sub2 sub3)"
+Defers \f(CW\*(C`require MODULE\*(C'\fR until someone calls one of the specified
+subroutines (which must be exported by MODULE).  This pragma should be
+used with caution, and only when necessary.
+.IP "use blib" 4
+.IX Item "use blib"
+.PD 0
+.IP "use blib 'dir'" 4
+.IX Item "use blib 'dir'"
+.PD
+Looks for MakeMaker-like \fI'blib'\fR directory structure starting in
+\&\fIdir\fR (or current directory) and working back up to five levels of
+parent directories.
+.Sp
+Intended for use on command line with \fB\-M\fR option as a way of testing
+arbitrary scripts against an uninstalled version of a package.
+.IP "use constant NAME => VALUE" 4
+.IX Item "use constant NAME => VALUE"
+Provides a convenient interface for creating compile-time constants,
+See "Constant Functions" in perlsub.
+.IP "use locale" 4
+.IX Item "use locale"
+Tells the compiler to enable (or disable) the use of POSIX locales for
+builtin operations.
+.Sp
+When \f(CW\*(C`use locale\*(C'\fR is in effect, the current LC_CTYPE locale is used
+for regular expressions and case mapping; LC_COLLATE for string
+ordering; and LC_NUMERIC for numeric formatting in printf and sprintf
+(but \fBnot\fR in print).  LC_NUMERIC is always used in write, since
+lexical scoping of formats is problematic at best.
+.Sp
+Each \f(CW\*(C`use locale\*(C'\fR or \f(CW\*(C`no locale\*(C'\fR affects statements to the end of
+the enclosing BLOCK or, if not inside a BLOCK, to the end of the
+current file.  Locales can be switched and queried with
+\&\fBPOSIX::setlocale()\fR.
+.Sp
+See perllocale for more information.
+.IP "use ops" 4
+.IX Item "use ops"
+Disable unsafe opcodes, or any named opcodes, when compiling Perl code.
+.IP "use vmsish" 4
+.IX Item "use vmsish"
+Enable VMS-specific language features.  Currently, there are three
+VMS-specific features available: 'status', which makes \f(CW$?\fR and
+\&\f(CW\*(C`system\*(C'\fR return genuine VMS status values instead of emulating POSIX;
+\&'exit', which makes \f(CW\*(C`exit\*(C'\fR take a genuine VMS status value instead of
+assuming that \f(CW\*(C`exit 1\*(C'\fR is an error; and 'time', which makes all times
+relative to the local time zone, in the VMS tradition.
+.SH Modules
+.IX Header "Modules"
+.SS "Required Updates"
+.IX Subsection "Required Updates"
+Though Perl 5.004 is compatible with almost all modules that work
+with Perl 5.003, there are a few exceptions:
+.PP
+.Vb 5
+\&    Module   Required Version for Perl 5.004
+\&    \-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&    Filter   Filter\-1.12
+\&    LWP      libwww\-perl\-5.08
+\&    Tk       Tk400.202 (\-w makes noise)
+.Ve
+.PP
+Also, the majordomo mailing list program, version 1.94.1, doesn't work
+with Perl 5.004 (nor with perl 4), because it executes an invalid
+regular expression.  This bug is fixed in majordomo version 1.94.2.
+.SS "Installation directories"
+.IX Subsection "Installation directories"
+The \fIinstallperl\fR script now places the Perl source files for
+extensions in the architecture-specific library directory, which is
+where the shared libraries for extensions have always been.  This
+change is intended to allow administrators to keep the Perl 5.004
+library directory unchanged from a previous version, without running
+the risk of binary incompatibility between extensions' Perl source and
+shared libraries.
+.SS "Module information summary"
+.IX Subsection "Module information summary"
+Brand new modules, arranged by topic rather than strictly
+alphabetically:
+.PP
+.Vb 6
+\&    CGI.pm               Web server interface ("Common Gateway Interface")
+\&    CGI/Apache.pm        Support for Apache\*(Aqs Perl module
+\&    CGI/Carp.pm          Log server errors with helpful context
+\&    CGI/Fast.pm          Support for FastCGI (persistent server process)
+\&    CGI/Push.pm          Support for server push
+\&    CGI/Switch.pm        Simple interface for multiple server types
+\&
+\&    CPAN                 Interface to Comprehensive Perl Archive Network
+\&    CPAN::FirstTime      Utility for creating CPAN configuration file
+\&    CPAN::Nox            Runs CPAN while avoiding compiled extensions
+\&
+\&    IO.pm                Top\-level interface to IO::* classes
+\&    IO/File.pm           IO::File extension Perl module
+\&    IO/Handle.pm         IO::Handle extension Perl module
+\&    IO/Pipe.pm           IO::Pipe extension Perl module
+\&    IO/Seekable.pm       IO::Seekable extension Perl module
+\&    IO/Select.pm         IO::Select extension Perl module
+\&    IO/Socket.pm         IO::Socket extension Perl module
+\&
+\&    Opcode.pm            Disable named opcodes when compiling Perl code
+\&
+\&    ExtUtils/Embed.pm    Utilities for embedding Perl in C programs
+\&    ExtUtils/testlib.pm  Fixes up @INC to use just\-built extension
+\&
+\&    FindBin.pm           Find path of currently executing program
+\&
+\&    Class/Struct.pm      Declare struct\-like datatypes as Perl classes
+\&    File/stat.pm         By\-name interface to Perl\*(Aqs builtin stat
+\&    Net/hostent.pm       By\-name interface to Perl\*(Aqs builtin gethost*
+\&    Net/netent.pm        By\-name interface to Perl\*(Aqs builtin getnet*
+\&    Net/protoent.pm      By\-name interface to Perl\*(Aqs builtin getproto*
+\&    Net/servent.pm       By\-name interface to Perl\*(Aqs builtin getserv*
+\&    Time/gmtime.pm       By\-name interface to Perl\*(Aqs builtin gmtime
+\&    Time/localtime.pm    By\-name interface to Perl\*(Aqs builtin localtime
+\&    Time/tm.pm           Internal object for Time::{gm,local}time
+\&    User/grent.pm        By\-name interface to Perl\*(Aqs builtin getgr*
+\&    User/pwent.pm        By\-name interface to Perl\*(Aqs builtin getpw*
+\&
+\&    Tie/RefHash.pm       Base class for tied hashes with references as keys
+\&
+\&    UNIVERSAL.pm         Base class for *ALL* classes
+.Ve
+.SS Fcntl
+.IX Subsection "Fcntl"
+New constants in the existing Fcntl modules are now supported,
+provided that your operating system happens to support them:
+.PP
+.Vb 3
+\&    F_GETOWN F_SETOWN
+\&    O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
+\&    O_EXLOCK O_SHLOCK
+.Ve
+.PP
+These constants are intended for use with the Perl operators \fBsysopen()\fR
+and \fBfcntl()\fR and the basic database modules like SDBM_File.  For the
+exact meaning of these and other Fcntl constants please refer to your
+operating system's documentation for \fBfcntl()\fR and \fBopen()\fR.
+.PP
+In addition, the Fcntl module now provides these constants for use
+with the Perl operator \fBflock()\fR:
+.PP
+.Vb 1
+\&        LOCK_SH LOCK_EX LOCK_NB LOCK_UN
+.Ve
+.PP
+These constants are defined in all environments (because where there is
+no \fBflock()\fR system call, Perl emulates it).  However, for historical
+reasons, these constants are not exported unless they are explicitly
+requested with the ":flock" tag (e.g. \f(CW\*(C`use Fcntl \*(Aq:flock\*(Aq\*(C'\fR).
+.SS IO
+.IX Subsection "IO"
+The IO module provides a simple mechanism to load all the IO modules at one
+go.  Currently this includes:
+.PP
+.Vb 5
+\&     IO::Handle
+\&     IO::Seekable
+\&     IO::File
+\&     IO::Pipe
+\&     IO::Socket
+.Ve
+.PP
+For more information on any of these modules, please see its
+respective documentation.
+.SS Math::Complex
+.IX Subsection "Math::Complex"
+The Math::Complex module has been totally rewritten, and now supports
+more operations.  These are overloaded:
+.PP
+.Vb 1
+\&     + \- * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)
+.Ve
+.PP
+And these functions are now exported:
+.PP
+.Vb 11
+\&    pi i Re Im arg
+\&    log10 logn ln cbrt root
+\&    tan
+\&    csc sec cot
+\&    asin acos atan
+\&    acsc asec acot
+\&    sinh cosh tanh
+\&    csch sech coth
+\&    asinh acosh atanh
+\&    acsch asech acoth
+\&    cplx cplxe
+.Ve
+.SS Math::Trig
+.IX Subsection "Math::Trig"
+This new module provides a simpler interface to parts of Math::Complex for
+those who need trigonometric functions only for real numbers.
+.SS DB_File
+.IX Subsection "DB_File"
+There have been quite a few changes made to DB_File. Here are a few of
+the highlights:
+.IP \(bu 4
+Fixed a handful of bugs.
+.IP \(bu 4
+By public demand, added support for the standard hash function \fBexists()\fR.
+.IP \(bu 4
+Made it compatible with Berkeley DB 1.86.
+.IP \(bu 4
+Made negative subscripts work with RECNO interface.
+.IP \(bu 4
+Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default
+mode from 0640 to 0666.
+.IP \(bu 4
+Made DB_File automatically import the \fBopen()\fR constants (O_RDWR,
+O_CREAT etc.) from Fcntl, if available.
+.IP \(bu 4
+Updated documentation.
+.PP
+Refer to the HISTORY section in DB_File.pm for a complete list of
+changes. Everything after DB_File 1.01 has been added since 5.003.
+.SS Net::Ping
+.IX Subsection "Net::Ping"
+Major rewrite \- support added for both udp echo and real icmp pings.
+.SS "Object-oriented overrides for builtin operators"
+.IX Subsection "Object-oriented overrides for builtin operators"
+Many of the Perl builtins returning lists now have
+object-oriented overrides.  These are:
+.PP
+.Vb 9
+\&    File::stat
+\&    Net::hostent
+\&    Net::netent
+\&    Net::protoent
+\&    Net::servent
+\&    Time::gmtime
+\&    Time::localtime
+\&    User::grent
+\&    User::pwent
+.Ve
+.PP
+For example, you can now say
+.PP
+.Vb 3
+\&    use File::stat;
+\&    use User::pwent;
+\&    $his = (stat($filename)\->st_uid == pwent($whoever)\->pw_uid);
+.Ve
+.SH "Utility Changes"
+.IX Header "Utility Changes"
+.SS pod2html
+.IX Subsection "pod2html"
+.IP "Sends converted HTML to standard output" 4
+.IX Item "Sends converted HTML to standard output"
+The \fIpod2html\fR utility included with Perl 5.004 is entirely new.
+By default, it sends the converted HTML to its standard output,
+instead of writing it to a file like Perl 5.003's \fIpod2html\fR did.
+Use the \fB\-\-outfile=FILENAME\fR option to write to a file.
+.SS xsubpp
+.IX Subsection "xsubpp"
+.ie n .IP """void"" XSUBs now default to returning nothing" 4
+.el .IP "\f(CWvoid\fR XSUBs now default to returning nothing" 4
+.IX Item "void XSUBs now default to returning nothing"
+Due to a documentation/implementation bug in previous versions of
+Perl, XSUBs with a return type of \f(CW\*(C`void\*(C'\fR have actually been
+returning one value.  Usually that value was the GV for the XSUB,
+but sometimes it was some already freed or reused value, which would
+sometimes lead to program failure.
+.Sp
+In Perl 5.004, if an XSUB is declared as returning \f(CW\*(C`void\*(C'\fR, it
+actually returns no value, i.e. an empty list (though there is a
+backward-compatibility exception; see below).  If your XSUB really
+does return an SV, you should give it a return type of \f(CW\*(C`SV *\*(C'\fR.
+.Sp
+For backward compatibility, \fIxsubpp\fR tries to guess whether a
+\&\f(CW\*(C`void\*(C'\fR XSUB is really \f(CW\*(C`void\*(C'\fR or if it wants to return an \f(CW\*(C`SV *\*(C'\fR.
+It does so by examining the text of the XSUB: if \fIxsubpp\fR finds
+what looks like an assignment to \f(CWST(0)\fR, it assumes that the
+XSUB's return type is really \f(CW\*(C`SV *\*(C'\fR.
+.SH "C Language API Changes"
+.IX Header "C Language API Changes"
+.ie n .IP """gv_fetchmethod"" and ""perl_call_sv""" 4
+.el .IP "\f(CWgv_fetchmethod\fR and \f(CWperl_call_sv\fR" 4
+.IX Item "gv_fetchmethod and perl_call_sv"
+The \f(CW\*(C`gv_fetchmethod\*(C'\fR function finds a method for an object, just like
+in Perl 5.003.  The GV it returns may be a method cache entry.
+However, in Perl 5.004, method cache entries are not visible to users;
+therefore, they can no longer be passed directly to \f(CW\*(C`perl_call_sv\*(C'\fR.
+Instead, you should use the \f(CW\*(C`GvCV\*(C'\fR macro on the GV to extract its CV,
+and pass the CV to \f(CW\*(C`perl_call_sv\*(C'\fR.
+.Sp
+The most likely symptom of passing the result of \f(CW\*(C`gv_fetchmethod\*(C'\fR to
+\&\f(CW\*(C`perl_call_sv\*(C'\fR is Perl's producing an "Undefined subroutine called"
+error on the \fIsecond\fR call to a given method (since there is no cache
+on the first call).
+.ie n .IP """perl_eval_pv""" 4
+.el .IP \f(CWperl_eval_pv\fR 4
+.IX Item "perl_eval_pv"
+A new function handy for eval'ing strings of Perl code inside C code.
+This function returns the value from the eval statement, which can
+be used instead of fetching globals from the symbol table.  See
+perlguts, perlembed and perlcall for details and examples.
+.IP "Extended API for manipulating hashes" 4
+.IX Item "Extended API for manipulating hashes"
+Internal handling of hash keys has changed.  The old hashtable API is
+still fully supported, and will likely remain so.  The additions to the
+API allow passing keys as \f(CW\*(C`SV*\*(C'\fRs, so that \f(CW\*(C`tied\*(C'\fR hashes can be given
+real scalars as keys rather than plain strings (nontied hashes still
+can only use strings as keys).  New extensions must use the new hash
+access functions and macros if they wish to use \f(CW\*(C`SV*\*(C'\fR keys.  These
+additions also make it feasible to manipulate \f(CW\*(C`HE*\*(C'\fRs (hash entries),
+which can be more efficient.  See perlguts for details.
+.SH "Documentation Changes"
+.IX Header "Documentation Changes"
+Many of the base and library pods were updated.  These
+new pods are included in section 1:
+.IP perldelta 4
+.IX Item "perldelta"
+This document.
+.IP perlfaq 4
+.IX Item "perlfaq"
+Frequently asked questions.
+.IP perllocale 4
+.IX Item "perllocale"
+Locale support (internationalization and localization).
+.IP perltoot 4
+.IX Item "perltoot"
+Tutorial on Perl OO programming.
+.IP perlapio 4
+.IX Item "perlapio"
+Perl internal IO abstraction interface.
+.IP perlmodlib 4
+.IX Item "perlmodlib"
+Perl module library and recommended practice for module creation.
+Extracted from perlmod (which is much smaller as a result).
+.IP perldebug 4
+.IX Item "perldebug"
+Although not new, this has been massively updated.
+.IP perlsec 4
+.IX Item "perlsec"
+Although not new, this has been massively updated.
+.SH "New Diagnostics"
+.IX Header "New Diagnostics"
+Several new conditions will trigger warnings that were
+silent before.  Some only affect certain platforms.
+The following new warnings and errors outline these.
+These messages are classified as follows (listed in
+increasing order of desperation):
+.PP
+.Vb 7
+\&   (W) A warning (optional).
+\&   (D) A deprecation (optional).
+\&   (S) A severe warning (mandatory).
+\&   (F) A fatal error (trappable).
+\&   (P) An internal error you should never see (trappable).
+\&   (X) A very fatal error (nontrappable).
+\&   (A) An alien error message (not generated by Perl).
+.Ve
+.ie n .IP """my"" variable %s masks earlier declaration in same scope" 4
+.el .IP """my"" variable \f(CW%s\fR masks earlier declaration in same scope" 4
+.IX Item """my"" variable %s masks earlier declaration in same scope"
+(W) A lexical variable has been redeclared in the same scope, 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.
+.ie n .IP "%s argument is not a HASH element or slice" 4
+.el .IP "\f(CW%s\fR argument is not a HASH element or slice" 4
+.IX Item "%s argument is not a HASH element or slice"
+(F) The argument to \fBdelete()\fR must be either a hash element, such as
+.Sp
+.Vb 2
+\&    $foo{$bar}
+\&    $ref\->[12]\->{"susie"}
+.Ve
+.Sp
+or a hash slice, such as
+.Sp
+.Vb 2
+\&    @foo{$bar, $baz, $xyzzy}
+\&    @{$ref\->[12]}{"susie", "queue"}
+.Ve
+.ie n .IP "Allocation too large: %lx" 4
+.el .IP "Allocation too large: \f(CW%lx\fR" 4
+.IX Item "Allocation too large: %lx"
+(X) You can't allocate more than 64K on an MS-DOS machine.
+.IP "Allocation too large" 4
+.IX Item "Allocation too large"
+(F) You can't allocate more than 2^31+"small amount" bytes.
+.ie n .IP "Applying %s to %s will act on scalar(%s)" 4
+.el .IP "Applying \f(CW%s\fR to \f(CW%s\fR will act on scalar(%s)" 4
+.IX Item "Applying %s to %s will act on scalar(%s)"
+(W) 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
+"grep" in perlfunc and "map" in perlfunc for alternatives.
+.IP "Attempt to free nonexistent shared string" 4
+.IX Item "Attempt to free nonexistent shared string"
+(P) 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.
+.IP "Attempt to use reference as lvalue in substr" 4
+.IX Item "Attempt to use reference as lvalue in substr"
+(W) You supplied a reference as the first argument to \fBsubstr()\fR used
+as an lvalue, which is pretty strange.  Perhaps you forgot to
+dereference it first.  See "substr" in perlfunc.
+.IP "Bareword ""%s"" refers to nonexistent package" 4
+.IX Item "Bareword ""%s"" refers to nonexistent package"
+(W) You used a qualified bareword of the form \f(CW\*(C`Foo::\*(C'\fR, but
+the compiler saw no other uses of that namespace before that point.
+Perhaps you need to predeclare a package?
+.ie n .IP "Can't redefine active sort subroutine %s" 4
+.el .IP "Can't redefine active sort subroutine \f(CW%s\fR" 4
+.IX 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
+this, you should write \f(CW\*(C`sort { &func } @x\*(C'\fR instead of \f(CW\*(C`sort func @x\*(C'\fR.
+.ie n .IP "Can't use bareword (""%s"") as %s ref while ""strict refs"" in use" 4
+.el .IP "Can't use bareword (""%s"") as \f(CW%s\fR ref while ""strict refs"" in use" 4
+.IX 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 perlref.
+.IP "Cannot resolve method `%s' overloading `%s' in package `%s'" 4
+.IX Item "Cannot resolve method `%s' overloading `%s' in package `%s'"
+(P) Internal error trying to resolve overloading specified by a method
+name (as opposed to a subroutine reference).
+.ie n .IP "Constant subroutine %s redefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR redefined" 4
+.IX Item "Constant subroutine %s redefined"
+(S) You redefined a subroutine which had previously been eligible for
+inlining.  See "Constant Functions" in perlsub for commentary and
+workarounds.
+.ie n .IP "Constant subroutine %s undefined" 4
+.el .IP "Constant subroutine \f(CW%s\fR undefined" 4
+.IX Item "Constant subroutine %s undefined"
+(S) You undefined a subroutine which had previously been eligible for
+inlining.  See "Constant Functions" in perlsub for commentary and
+workarounds.
+.IP "Copy method did not return a reference" 4
+.IX Item "Copy method did not return a reference"
+(F) The method which overloads "=" is buggy. See "Copy Constructor" in overload.
+.IP Died 4
+.IX Item "Died"
+(F) You passed \fBdie()\fR an empty string (the equivalent of \f(CW\*(C`die ""\*(C'\fR) or
+you called it with no args and both \f(CW$@\fR and \f(CW$_\fR were empty.
+.ie n .IP "Exiting pseudo-block via %s" 4
+.el .IP "Exiting pseudo-block via \f(CW%s\fR" 4
+.IX Item "Exiting pseudo-block via %s"
+(W) 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 "sort" in perlfunc.
+.IP "Identifier too long" 4
+.IX Item "Identifier too long"
+(F) Perl limits identifiers (names for variables, functions, etc.) to
+252 characters for simple names, somewhat more for compound names (like
+\&\f(CW$A::B\fR).  You've exceeded Perl's limits.  Future versions of Perl are
+likely to eliminate these arbitrary limitations.
+.ie n .IP "Illegal character %s (carriage return)" 4
+.el .IP "Illegal character \f(CW%s\fR (carriage return)" 4
+.IX Item "Illegal character %s (carriage return)"
+(F) A carriage return character was found in the input.  This is an
+error, and not a warning, because carriage return characters can break
+multi-line strings, including here documents (e.g., \f(CW\*(C`print <<EOF;\*(C'\fR).
+.ie n .IP "Illegal switch in PERL5OPT: %s" 4
+.el .IP "Illegal switch in PERL5OPT: \f(CW%s\fR" 4
+.IX Item "Illegal switch in PERL5OPT: %s"
+(X) The PERL5OPT environment variable may only be used to set the
+following switches: \fB\-[DIMUdmw]\fR.
+.IP "Integer overflow in hex number" 4
+.IX Item "Integer overflow in hex number"
+(S) The literal hex number you have specified is too big for your
+architecture. On a 32\-bit architecture the largest hex literal is
+0xFFFFFFFF.
+.IP "Integer overflow in octal number" 4
+.IX Item "Integer overflow in octal number"
+(S) The literal octal number you have specified is too big for your
+architecture. On a 32\-bit architecture the largest octal literal is
+037777777777.
+.IP "internal error: glob failed" 4
+.IX Item "internal error: glob failed"
+(P) Something went wrong with the external program(s) used for \f(CW\*(C`glob\*(C'\fR
+and \f(CW\*(C`<*.c>\*(C'\fR.  This may 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. \f(CW\*(C`full_csh=\*(Aq/usr/bin/tcsh\*(Aq\*(C'\fR); otherwise, make them all
+empty (except that \f(CW\*(C`d_csh\*(C'\fR should be \f(CW\*(Aqundef\*(Aq\fR) so that Perl will
+think csh is missing.  In either case, after editing config.sh, run
+\&\f(CW\*(C`./Configure \-S\*(C'\fR and rebuild Perl.
+.ie n .IP "Invalid conversion in %s: ""%s""" 4
+.el .IP "Invalid conversion in \f(CW%s:\fR ""%s""" 4
+.IX Item "Invalid conversion in %s: ""%s"""
+(W) Perl does not understand the given format conversion.
+See "sprintf" in perlfunc.
+.IP "Invalid type in pack: '%s'" 4
+.IX Item "Invalid type in pack: '%s'"
+(F) The given character is not a valid pack type.  See "pack" in perlfunc.
+.IP "Invalid type in unpack: '%s'" 4
+.IX Item "Invalid type in unpack: '%s'"
+(F) The given character is not a valid unpack type.  See "unpack" in perlfunc.
+.IP "Name ""%s::%s"" used only once: possible typo" 4
+.IX Item "Name ""%s::%s"" used only once: possible typo"
+(W) 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 \f(CW\*(C`use vars\*(C'\fR pragma is
+provided for just this purpose).
+.IP "Null picture in formline" 4
+.IX Item "Null picture in formline"
+(F) The first argument to formline must be a valid format picture
+specification.  It was found to be empty, which probably means you
+supplied it an uninitialized value.  See perlform.
+.IP "Offset outside string" 4
+.IX 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 \f(CWsysread()\fRing past the buffer
+will extend the buffer and zero pad the new area.
+.IP "Out of memory!" 4
+.IX Item "Out of memory!"
+(X|F) The \fBmalloc()\fR function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request.
+.Sp
+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 \f(CW$^M\fR as
+an emergency pool after \fBdie()\fRing with this message.  In this case the
+error is trappable \fIonce\fR.
+.ie n .IP "Out of memory during request for %s" 4
+.el .IP "Out of memory during request for \f(CW%s\fR" 4
+.IX Item "Out of memory during request for %s"
+(F) The \fBmalloc()\fR 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.
+.IP "panic: frexp" 4
+.IX Item "panic: frexp"
+(P) The library function \fBfrexp()\fR failed, making printf("%f") impossible.
+.IP "Possible attempt to put comments in \fBqw()\fR list" 4
+.IX Item "Possible attempt to put comments in qw() list"
+(W) \fBqw()\fR 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
+parentheses shown here; braces are also frequently used.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a # a comment
+\&        b # another comment
+\&    );
+.Ve
+.Sp
+when you should have written this:
+.Sp
+.Vb 4
+\&    @list = qw(
+\&        a
+\&        b
+\&    );
+.Ve
+.Sp
+If you really want comments, build your list the
+old-fashioned way, with quotes and commas:
+.Sp
+.Vb 4
+\&    @list = (
+\&        \*(Aqa\*(Aq,    # a comment
+\&        \*(Aqb\*(Aq,    # another comment
+\&    );
+.Ve
+.IP "Possible attempt to separate words with commas" 4
+.IX Item "Possible attempt to separate words with commas"
+(W) \fBqw()\fR 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.)
+.Sp
+You probably wrote something like this:
+.Sp
+.Vb 1
+\&    qw! a, b, c !;
+.Ve
+.Sp
+which puts literal commas into some of the list items.  Write it without
+commas if you don't want them to appear in your data:
+.Sp
+.Vb 1
+\&    qw! a b c !;
+.Ve
+.IP "Scalar value @%s{%s} better written as $%s{%s}" 4
+.IX Item "Scalar value @%s{%s} better written as $%s{%s}"
+(W) 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 \f(CW$foo{&bar}\fR always behaves like a scalar, both when
+assigning to it and when evaluating its argument, while \f(CW@foo{&bar}\fR 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.
+.ie n .IP "Stub found while resolving method `%s' overloading `%s' in %s" 4
+.el .IP "Stub found while resolving method `%s' overloading `%s' in \f(CW%s\fR" 4
+.IX Item "Stub found while resolving method `%s' overloading `%s' in %s"
+(P) Overloading resolution over \f(CW@ISA\fR tree may be broken by importing stubs.
+Stubs should never be implicitly created, but explicit calls to \f(CW\*(C`can\*(C'\fR
+may break this.
+.IP "Too late for ""\fB\-T\fR"" option" 4
+.IX Item "Too late for ""-T"" option"
+(X) The #! line (or local equivalent) in a Perl script contains the
+\&\fB\-T\fR option, but Perl was not invoked with \fB\-T\fR in its argument
+list.  This is an error because, by the time Perl discovers a \fB\-T\fR in
+a script, it's too late to properly taint everything from the
+environment.  So Perl gives up.
+.ie n .IP "untie attempted while %d inner references still exist" 4
+.el .IP "untie attempted while \f(CW%d\fR inner references still exist" 4
+.IX Item "untie attempted while %d inner references still exist"
+(W) A copy of the object returned from \f(CW\*(C`tie\*(C'\fR (or \f(CW\*(C`tied\*(C'\fR) was still
+valid when \f(CW\*(C`untie\*(C'\fR was called.
+.ie n .IP "Unrecognized character %s" 4
+.el .IP "Unrecognized character \f(CW%s\fR" 4
+.IX Item "Unrecognized character %s"
+(F) The Perl parser has no idea what to do with the specified character
+in your Perl script (or eval).  Perhaps you tried to run a compressed
+script, a binary program, or a directory as a Perl program.
+.IP "Unsupported function fork" 4
+.IX Item "Unsupported function fork"
+(F) Your version of executable does not support forking.
+.Sp
+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 \f(CW\*(C`perl_\*(C'\fR, \f(CW\*(C`perl_\|_\*(C'\fR, and so on.
+.IP "Use of ""$$<digit>"" to mean ""${$}<digit>"" is deprecated" 4
+.IX 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.
+.Sp
+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.
+.ie n .IP "Value of %s can be ""0""; test with \fBdefined()\fR" 4
+.el .IP "Value of \f(CW%s\fR can be ""0""; test with \fBdefined()\fR" 4
+.IX Item "Value of %s can be ""0""; test with defined()"
+(W) In a conditional expression, you used <HANDLE>, <*> (glob), \f(CWeach()\fR,
+or \f(CWreaddir()\fR 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 \f(CW\*(C`defined\*(C'\fR operator.
+.IP "Variable ""%s"" may be unavailable" 4
+.IX Item "Variable ""%s"" may be unavailable"
+(W) An inner (nested) \fIanonymous\fR subroutine is inside a \fInamed\fR
+subroutine, and outside that is another subroutine; and the anonymous
+(innermost) subroutine is referencing a lexical variable defined in
+the outermost subroutine.  For example:
+.Sp
+.Vb 1
+\&   sub outermost { my $a; sub middle { sub { $a } } }
+.Ve
+.Sp
+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.
+.Sp
+In these circumstances, it is usually best to make the middle
+subroutine anonymous, using the \f(CW\*(C`sub {}\*(C'\fR syntax.  Perl has specific
+support for shared variables in nested anonymous subroutines; a named
+subroutine in between interferes with this feature.
+.IP "Variable ""%s"" will not stay shared" 4
+.IX Item "Variable ""%s"" will not stay shared"
+(W) An inner (nested) \fInamed\fR subroutine is referencing a lexical
+variable defined in an outer subroutine.
+.Sp
+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.
+.Sp
+Furthermore, if the outer subroutine is anonymous and references a
+lexical variable outside itself, then the outer and inner subroutines
+will \fInever\fR share the given variable.
+.Sp
+This problem can usually be solved by making the inner subroutine
+anonymous, using the \f(CW\*(C`sub {}\*(C'\fR 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.
+.IP "Warning: something's wrong" 4
+.IX Item "Warning: something's wrong"
+(W) You passed \fBwarn()\fR an empty string (the equivalent of \f(CW\*(C`warn ""\*(C'\fR) or
+you called it with no args and \f(CW$_\fR was empty.
+.IP "Ill-formed logical name |%s| in prime_env_iter" 4
+.IX 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 \f(CW%ENV\fR which violates the syntactic rules governing logical
+names.  Since it cannot be translated normally, it is skipped, and will not
+appear in \f(CW%ENV\fR.  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.
+.IP "Got an error from DosAllocMem" 4
+.IX 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.
+.IP "Malformed PERLLIB_PREFIX" 4
+.IX Item "Malformed PERLLIB_PREFIX"
+(F) An error peculiar to OS/2.  PERLLIB_PREFIX should be of the form
+.Sp
+.Vb 1
+\&    prefix1;prefix2
+.Ve
+.Sp
+or
+.Sp
+.Vb 1
+\&    prefix1 prefix2
+.Ve
+.Sp
+with nonempty prefix1 and prefix2.  If \f(CW\*(C`prefix1\*(C'\fR 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 \fIREADME.os2\fR.
+.IP "PERL_SH_DIR too long" 4
+.IX Item "PERL_SH_DIR too long"
+(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
+\&\f(CW\*(C`sh\*(C'\fR\-shell in.  See "PERL_SH_DIR" in \fIREADME.os2\fR.
+.IP "Process terminated by SIG%s" 4
+.IX 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
+"Signals" in perlipc.  See also "Process terminated by SIGTERM/SIGINT"
+in \fIREADME.os2\fR.
+.SH BUGS
+.IX Header "BUGS"
+If you find what you think is a bug, you might check the headers of
+recently posted articles in the comp.lang.perl.misc newsgroup.
+There may also be information at http://www.perl.com/perl/ , the Perl
+Home Page.
+.PP
+If you believe you have an unreported bug, please run the \fBperlbug\fR
+program included with your release.  Make sure you trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of \f(CW\*(C`perl \-V\*(C'\fR, will be sent off to <\fIperlbug@perl.com\fR> to be
+analysed by the Perl porting team.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIChanges\fR file for exhaustive details on what changed.
+.PP
+The \fIINSTALL\fR file for how to build Perl.  This file has been
+significantly updated for 5.004, so even veteran users should
+look through it.
+.PP
+The \fIREADME\fR file for general stuff.
+.PP
+The \fICopying\fR file for copyright information.
+.SH HISTORY
+.IX Header "HISTORY"
+Constructed by Tom Christiansen, grabbing material with permission
+from innumerable contributors, with kibitzing by more than a few Perl
+porters.
+.PP
+Last update: Wed May 14 11:14:09 EDT 1997