summaryrefslogtreecommitdiff
path: root/pod
diff options
context:
space:
mode:
Diffstat (limited to 'pod')
-rw-r--r--pod/Makefile106
-rw-r--r--pod/modpods/Abbrev.pod19
-rw-r--r--pod/modpods/AnyDBMFile.pod73
-rw-r--r--pod/modpods/AutoLoader.pod16
-rw-r--r--pod/modpods/AutoSplit.pod11
-rw-r--r--pod/modpods/Basename.pod108
-rw-r--r--pod/modpods/Benchmark.pod159
-rw-r--r--pod/modpods/Carp.pod22
-rw-r--r--pod/modpods/CheckTree.pod37
-rw-r--r--pod/modpods/Collate.pod31
-rw-r--r--pod/modpods/Config.pod40
-rw-r--r--pod/modpods/Cwd.pod26
-rw-r--r--pod/modpods/DB_File.pod319
-rw-r--r--pod/modpods/Dynaloader.pod316
-rw-r--r--pod/modpods/English.pod24
-rw-r--r--pod/modpods/Env.pod31
-rw-r--r--pod/modpods/Exporter.pod60
-rw-r--r--pod/modpods/Fcntl.pod20
-rw-r--r--pod/modpods/FileHandle.pod46
-rw-r--r--pod/modpods/Find.pod44
-rw-r--r--pod/modpods/Finddepth.pod16
-rw-r--r--pod/modpods/GetOptions.pod137
-rw-r--r--pod/modpods/Getopt.pod152
-rw-r--r--pod/modpods/MakeMaker.pod24
-rw-r--r--pod/modpods/Open2.pod33
-rw-r--r--pod/modpods/Open3.pod23
-rw-r--r--pod/modpods/POSIX.pod53
-rw-r--r--pod/modpods/Ping.pod37
-rw-r--r--pod/modpods/Socket.pod23
-rw-r--r--pod/modpods/integer.pod18
-rw-r--r--pod/modpods/less.pod13
-rw-r--r--pod/modpods/sigtrap.pod19
-rw-r--r--pod/modpods/strict.pod65
-rw-r--r--pod/modpods/subs.pod16
-rw-r--r--pod/perl.pod271
-rw-r--r--pod/perlapi.pod951
-rw-r--r--pod/perlbook.pod20
-rw-r--r--pod/perlbot.pod367
-rw-r--r--pod/perlcall.pod838
-rw-r--r--pod/perldata.pod408
-rw-r--r--pod/perldebug.pod249
-rw-r--r--pod/perldiag.pod2002
-rw-r--r--pod/perlembed.pod7
-rw-r--r--pod/perlform.pod314
-rw-r--r--pod/perlfunc.pod2896
-rw-r--r--pod/perlguts.pod521
-rw-r--r--pod/perlipc.pod168
-rw-r--r--pod/perlmod.pod472
-rw-r--r--pod/perlobj.pod251
-rw-r--r--pod/perlop.pod1062
-rw-r--r--pod/perlovl.pod363
-rw-r--r--pod/perlpod.pod81
-rw-r--r--pod/perlre.pod315
-rw-r--r--pod/perlref.pod332
-rw-r--r--pod/perlrun.pod382
-rw-r--r--pod/perlsec.pod125
-rw-r--r--pod/perlstyle.pod225
-rw-r--r--pod/perlsub.pod195
-rw-r--r--pod/perlsyn.pod267
-rw-r--r--pod/perltrap.pod451
-rw-r--r--pod/perlvar.pod608
-rw-r--r--pod/pod2html209
-rwxr-xr-xpod/pod2man625
-rwxr-xr-xpod/splitman46
64 files changed, 17158 insertions, 0 deletions
diff --git a/pod/Makefile b/pod/Makefile
new file mode 100644
index 0000000000..d96fd7da3e
--- /dev/null
+++ b/pod/Makefile
@@ -0,0 +1,106 @@
+all: man
+
+POD = \
+ perl.pod \
+ perlapi.pod \
+ perlbook.pod \
+ perlbot.pod \
+ perlcall.pod \
+ perldata.pod \
+ perldebug.pod \
+ perldiag.pod \
+ perlembed.pod \
+ perlform.pod \
+ perlfunc.pod \
+ perlguts.pod \
+ perlipc.pod \
+ perlmod.pod \
+ perlobj.pod \
+ perlop.pod \
+ perlovl.pod \
+ perlpod.pod \
+ perlre.pod \
+ perlref.pod \
+ perlrun.pod \
+ perlsec.pod \
+ perlstyle.pod \
+ perlsub.pod \
+ perlsyn.pod \
+ perltrap.pod \
+ perlvar.pod
+
+MAN = \
+ perl.man \
+ perlapi.man \
+ perlbook.man \
+ perlbot.man \
+ perlcall.man \
+ perldata.man \
+ perldebug.man \
+ perldiag.man \
+ perlembed.man \
+ perlform.man \
+ perlfunc.man \
+ perlguts.man \
+ perlipc.man \
+ perlmod.man \
+ perlobj.man \
+ perlop.man \
+ perlovl.man \
+ perlpod.man \
+ perlre.man \
+ perlref.man \
+ perlrun.man \
+ perlsec.man \
+ perlstyle.man \
+ perlsub.man \
+ perlsyn.man \
+ perltrap.man \
+ perlvar.man
+
+HTML = \
+ perl.html \
+ perlapi.html \
+ perlbook.html \
+ perlbot.html \
+ perlcall.html \
+ perldata.html \
+ perldebug.html \
+ perldiag.html \
+ perlembed.html \
+ perlform.html \
+ perlfunc.html \
+ perlguts.html \
+ perlipc.html \
+ perlmod.html \
+ perlobj.html \
+ perlop.html \
+ perlovl.html \
+ perlpod.html \
+ perlre.html \
+ perlref.html \
+ perlrun.html \
+ perlsec.html \
+ perlstyle.html \
+ perlsub.html \
+ perlsyn.html \
+ perltrap.html \
+ perlvar.html
+
+man: $(MAN)
+
+html: $(HTML)
+
+.SUFFIXES: .pod .man
+
+.pod.man:
+ ../miniperl pod2man $*.pod >$*.man
+
+.SUFFIXES: .pod .html
+
+.pod.html:
+ ../miniperl pod2html $*.pod >$*.html
+
+clean:
+ rm -f $(MAN) $(HTML)
+
diff --git a/pod/modpods/Abbrev.pod b/pod/modpods/Abbrev.pod
new file mode 100644
index 0000000000..85ec88ef85
--- /dev/null
+++ b/pod/modpods/Abbrev.pod
@@ -0,0 +1,19 @@
+=head1 NAME
+
+abbrev - create an abbreviation table from a list
+
+=head1 SYNOPSIS
+
+ use Abbrev;
+ abbrev *HASH, LIST
+
+
+=head1 DESCRIPTION
+
+Stores all unambiguous truncations of each element of LIST
+as keys key in the associative array indicated by C<*hash>.
+The values are the original list elements.
+
+=head1 EXAMPLE
+
+ abbrev(*hash,qw("list edit send abort gripe"));
diff --git a/pod/modpods/AnyDBMFile.pod b/pod/modpods/AnyDBMFile.pod
new file mode 100644
index 0000000000..7b579ca34c
--- /dev/null
+++ b/pod/modpods/AnyDBMFile.pod
@@ -0,0 +1,73 @@
+=head1 NAME
+
+AnyDBM_File - provide framework for multiple DBMs
+
+NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations
+
+=head1 SYNOPSIS
+
+ use AnyDBM_File;
+
+=head1 DESCRIPTION
+
+This module is a "pure virtual base class"--it has nothing of us its own.
+It's just there to inherit from one of the various DBM packages. It
+prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See
+L<DB_File>), GDBM, SDBM (which is always there -- it comes with Perl), and
+finally ODBM. This way old programs that used to use NDBM via dbmopen() can still
+do so, but new ones can reorder @ISA:
+
+ @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File);
+
+This makes it trivial to copy database formats:
+
+ use POSIX; use NDBM_File; use DB_File;
+ tie %newhash, DB_File, $new_filename, O_CREAT|O_RDWR;
+ tie %oldhash, NDBM_File, $old_filename, 1, 0;
+ %newhash = %oldhash;
+
+=head2 DBM Comparisons
+
+Here's a partial table of features the different packages offer:
+
+ odbm ndbm sdbm gdbm bsd-db
+ ---- ---- ---- ---- ------
+ Linkage comes w/ perl yes yes yes yes yes
+ Src comes w/ perl no no yes no no
+ Comes w/ many unix os yes yes[0] no no no
+ Builds ok on !unix ? ? yes yes ?
+ Code Size ? ? small big big
+ Database Size ? ? small big? ok[1]
+ Speed ? ? slow ok fast
+ FTPable no no yes yes yes
+ Easy to build N/A N/A yes yes ok[2]
+ Size limits 1k 4k 1k[3] none none
+ Byte-order independent no no no no yes
+ Licensing restrictions ? ? no yes no
+
+
+=over 4
+
+=item [0]
+
+on mixed universe machines, may be in the bsd compat library,
+which is often shunned.
+
+=item [1]
+
+Can be trimmed if you compile for one access method.
+
+=item [2]
+
+See L<DB_File>.
+Requires symbolic links.
+
+=item [3]
+
+By default, but can be redefined.
+
+=back
+
+=head1 SEE ALSO
+
+dbm(3), ndbm(3), DB_File(3)
diff --git a/pod/modpods/AutoLoader.pod b/pod/modpods/AutoLoader.pod
new file mode 100644
index 0000000000..203f951e39
--- /dev/null
+++ b/pod/modpods/AutoLoader.pod
@@ -0,0 +1,16 @@
+=head1 NAME
+
+AutoLoader - load functions only on demand
+
+=head1 SYNOPSIS
+
+ package FOOBAR;
+ use Exporter;
+ use AutoLoader;
+ @ISA = (Exporter, AutoLoader);
+
+=head1 DESCRIPTION
+
+This module tells its users that functions in the FOOBAR package are to be
+autoloaded from F<auto/$AUTOLOAD.al>. See L<perlsub/"Autoloading">.
+
diff --git a/pod/modpods/AutoSplit.pod b/pod/modpods/AutoSplit.pod
new file mode 100644
index 0000000000..86df8c018b
--- /dev/null
+++ b/pod/modpods/AutoSplit.pod
@@ -0,0 +1,11 @@
+=head1 NAME
+
+AutoSplit - split a package for autoloading
+
+=head1 DESCRIPTION
+
+This function will split up your program into files that the AutoLoader
+module can handle. Normally only used to build autoloading Perl library
+modules, especially extensions (like POSIX). You should look at how
+they're built out for details.
+
diff --git a/pod/modpods/Basename.pod b/pod/modpods/Basename.pod
new file mode 100644
index 0000000000..11cb15ee77
--- /dev/null
+++ b/pod/modpods/Basename.pod
@@ -0,0 +1,108 @@
+=head1 NAME
+
+Basename - parse file specifications
+
+fileparse - split a pathname into pieces
+
+basename - extract just the filename from a path
+
+dirname - extract just the directory from a path
+
+=head1 SYNOPSIS
+
+ use File::Basename;
+
+ ($name,$path,$suffix) = fileparse($fullname,@suffixlist)
+ fileparse_set_fstype($os_string);
+ $basename = basename($fullname,@suffixlist);
+ $dirname = dirname($fullname);
+
+ ($name,$path,$suffix) = fileparse("lib/File/Basename.pm",".pm");
+ fileparse_set_fstype("VMS");
+ $basename = basename("lib/File/Basename.pm",".pm");
+ $dirname = dirname("lib/File/Basename.pm");
+
+=head1 DESCRIPTION
+
+These routines allow you to parse file specifications into useful
+pieces according using the syntax of different operating systems.
+
+=over 4
+
+=item fileparse_set_fstype
+
+You select the syntax via the routine fileparse_set_fstype().
+If the argument passed to it contains one of the substrings
+"VMS", "MSDOS", or "MacOS", the file specification syntax of that
+operating system is used in future calls to fileparse(),
+basename(), and dirname(). If it contains none of these
+substrings, UNIX syntax is used. This pattern matching is
+case-insensitive. If you've selected VMS syntax, and the file
+specification you pass to one of these routines contains a "/",
+they assume you are using UNIX emulation and apply the UNIX syntax
+rules instead, for that function call only.
+
+If you haven't called fileparse_set_fstype(), the syntax is chosen
+by examining the "osname" entry from the C<Config> package
+according to these rules.
+
+=item fileparse
+
+The fileparse() routine divides a file specification into three
+parts: a leading B<path>, a file B<name>, and a B<suffix>. The
+B<path> contains everything up to and including the last directory
+separator in the input file specification. The remainder of the input
+file specification is then divided into B<name> and B<suffix> based on
+the optional patterns you specify in C<@suffixlist>. Each element of
+this list is interpreted as a regular expression, and is matched
+against the end of B<name>. If this succeeds, the matching portion of
+B<name> is removed and prepended to B<suffix>. By proper use of
+C<@suffixlist>, you can remove file types or versions for examination.
+
+You are guaranteed that if you concatenate B<path>, B<name>, and
+B<suffix> together in that order, the result will be identical to the
+input file specification.
+
+=back
+
+=head1 EXAMPLES
+
+Using UNIX file syntax:
+
+ ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7',
+ '\.book\d+');
+
+would yield
+
+ $base eq 'draft'
+ $path eq '/virgil/aeneid',
+ $tail eq '.book7'
+
+Similarly, using VMS syntax:
+
+ ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh',
+ '\..*');
+
+would yield
+
+ $name eq 'Rhetoric'
+ $dir eq 'Doc_Root:[Help]'
+ $type eq '.Rnh'
+
+=item C<basename>
+
+The basename() routine returns the first element of the list produced
+by calling fileparse() with the same arguments. It is provided for
+compatibility with the UNIX shell command basename(1).
+
+=item C<dirname>
+
+The dirname() routine returns the directory portion of the input file
+specification. When using VMS or MacOS syntax, this is identical to the
+second element of the list produced by calling fileparse() with the same
+input file specification. When using UNIX or MSDOS syntax, the return
+value conforms to the behavior of the UNIX shell command dirname(1). This
+is usually the same as the behavior of fileparse(), but differs in some
+cases. For example, for the input file specification F<lib/>, fileparse()
+considers the directory name to be F<lib/>, while dirname() considers the
+directory name to be F<.>).
diff --git a/pod/modpods/Benchmark.pod b/pod/modpods/Benchmark.pod
new file mode 100644
index 0000000000..bdb3f05700
--- /dev/null
+++ b/pod/modpods/Benchmark.pod
@@ -0,0 +1,159 @@
+=head1 NAME
+
+Benchmark - benchmark running times of code
+
+timethis - run a chunk of code several times
+
+timethese - run several chunks of code several times
+
+timeit - run a chunk of code and see how long it goes
+
+=head1 SYNOPSYS
+
+ timethis ($count, "code");
+
+ timethese($count, {
+ 'Name1' => '...code1...',
+ 'Name2' => '...code2...',
+ });
+
+ $t = timeit($count, '...other code...')
+ print "$count loops of other code took:",timestr($t),"\n";
+
+=head1 DESCRIPTION
+
+The Benchmark module encapsulates a number of routines to help you
+figure out how long it takes to execute some code.
+
+=head2 Methods
+
+=over 10
+
+=item new
+
+Returns the current time. Example:
+
+ use Benchmark;
+ $t0 = new Benchmark;
+ # ... your code here ...
+ $t1 = new Benchmark;
+ $td = timediff($t1, $t0);
+ print "the code took:",timestr($dt),"\n";
+
+=item debug
+
+Enables or disable debugging by setting the C<$Benchmark::Debug> flag:
+
+ debug Benchmark 1;
+ $t = timeit(10, ' 5 ** $Global ');
+ debug Benchmark 0;
+
+=back
+
+=head2 Standard Exports
+
+The following routines will be exported into your namespace
+if you use the Benchmark module:
+
+=over 10
+
+=item timeit(COUNT, CODE)
+
+Arguments: COUNT is the number of time to run the loop, and
+the second is the code to run. CODE may be a string containing the code,
+a reference to the function to run, or a reference to a hash containing
+keys which are names and values which are more CODE specs.
+
+Side-effects: prints out noise to standard out.
+
+Returns: a Benchmark object.
+
+=item timethis
+
+=item timethese
+
+=item timediff
+
+=item timestr
+
+=back
+
+=head2 Optional Exports
+
+The following routines will be exported into your namespace
+if you specifically ask that they be imported:
+
+=over 10
+
+clearcache
+
+clearallcache
+
+disablecache
+
+enablecache
+
+=back
+
+=head1 NOTES
+
+The data is stored as a list of values from the time and times
+functions:
+
+ ($real, $user, $system, $children_user, $children_system)
+
+in seconds for the whole loop (not divided by the number of rounds).
+
+The timing is done using time(3) and times(3).
+
+Code is executed in the caller's package.
+
+Enable debugging by:
+
+ $Benchmark::debug = 1;
+
+The time of the null loop (a loop with the same
+number of rounds but empty loop body) is subtracted
+from the time of the real loop.
+
+The null loop times are cached, the key being the
+number of rounds. The caching can be controlled using
+calls like these:
+
+ clearcache($key);
+ clearallcache();
+
+ disablecache();
+ enablecache();
+
+=head1 INHERITANCE
+
+Benchmark inherits from no other class, except of course
+for Exporter.
+
+=head1 CAVEATS
+
+The real time timing is done using time(2) and
+the granularity is therefore only one second.
+
+Short tests may produce negative figures because perl
+can appear to take longer to execute the empty loop
+than a short test; try:
+
+ timethis(100,'1');
+
+The system time of the null loop might be slightly
+more than the system time of the loop with the actual
+code and therefore the difference might end up being < 0.
+
+More documentation is needed :-( especially for styles and formats.
+
+=head1 AUTHORS
+
+Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>,
+Tim Bunce <Tim.Bunce@ig.co.uk>
+
+=head1 MODIFICATION HISTORY
+
+September 8th, 1994; by Tim Bunce.
+
diff --git a/pod/modpods/Carp.pod b/pod/modpods/Carp.pod
new file mode 100644
index 0000000000..b5439779ac
--- /dev/null
+++ b/pod/modpods/Carp.pod
@@ -0,0 +1,22 @@
+=head1 NAME
+
+carp - warn of errors (from perspective of caller)
+
+croak - die of errors (from perspective of caller)
+
+confess - die of errors with stack backtrace
+
+=head1 SYNOPSIS
+
+ use Carp;
+ croak "We're outta here!";
+
+=head1 DESCRIPTION
+
+The Carp routines are useful in your own modules because
+they act like die() or warn(), but report where the error
+was in the code they were called from. Thus if you have a
+routine Foo() that has a carp() in it, then the carp()
+will report the error as occurring where Foo() was called,
+not where carp() was called.
+
diff --git a/pod/modpods/CheckTree.pod b/pod/modpods/CheckTree.pod
new file mode 100644
index 0000000000..cc06eeeda3
--- /dev/null
+++ b/pod/modpods/CheckTree.pod
@@ -0,0 +1,37 @@
+=head1 NAME
+
+validate - run many filetest checks on a tree
+
+=head1 SYNOPSIS
+
+ use File::CheckTree;
+
+ $warnings += validate( q{
+ /vmunix -e || die
+ /boot -e || die
+ /bin cd
+ csh -ex
+ csh !-ug
+ sh -ex
+ sh !-ug
+ /usr -d || warn "What happened to $file?\n"
+ });
+
+=head1 DESCRIPTION
+
+The validate() routine takes a single multiline string consisting of
+lines containing a filename plus a file test to try on it. (The
+file test may also be a "cd", causing subsequent relative filenames
+to be interpreted relative to that directory.) After the file test
+you may put C<|| die> to make it a fatal error if the file test fails.
+The default is C<|| warn>. The file test may optionally have a "!' prepended
+to test for the opposite condition. If you do a cd and then list some
+relative filenames, you may want to indent them slightly for readability.
+If you supply your own die() or warn() message, you can use $file to
+interpolate the filename.
+
+Filetests may be bunched: "-rwx" tests for all of C<-r>, C<-w>, and C<-x>.
+Only the first failed test of the bunch will produce a warning.
+
+The routine returns the number of warnings issued.
+
diff --git a/pod/modpods/Collate.pod b/pod/modpods/Collate.pod
new file mode 100644
index 0000000000..852fd1f4bd
--- /dev/null
+++ b/pod/modpods/Collate.pod
@@ -0,0 +1,31 @@
+=head1 NAME
+
+Collate - compare 8-bit scalar data according to the current locale
+
+=head1 SYNOPSIS
+
+ use Collate;
+ setlocale(LC_COLLATE, 'locale-of-your-choice');
+ $s1 = new Collate "scalar_data_1";
+ $s2 = new Collate "scalar_data_2";
+
+=head1 DESCRIPTION
+
+This module provides you with objects that will collate
+according to your national character set, providing the
+POSIX setlocale() function should be supported on your system.
+
+You can compare $s1 and $s2 above with
+
+ $s1 le $s2
+
+to extract the data itself, you'll need a dereference: $$s1
+
+This uses POSIX::setlocale The basic collation conversion is done by
+strxfrm() which terminates at NUL characters being a decent C routine.
+collate_xfrm() handles embedded NUL characters gracefully. Due to C<cmp>
+and overload magic, C<lt>, C<le>, C<eq>, C<ge>, and C<gt> work also. The
+available locales depend on your operating system; try whether C<locale
+-a> shows them or the more direct approach C<ls /usr/lib/nls/loc> or C<ls
+/usr/lib/nls>. The locale names are probably something like
+"xx_XX.(ISO)?8859-N".
diff --git a/pod/modpods/Config.pod b/pod/modpods/Config.pod
new file mode 100644
index 0000000000..141fb67393
--- /dev/null
+++ b/pod/modpods/Config.pod
@@ -0,0 +1,40 @@
+=head1 NAME
+
+Config - access Perl configuration option
+
+=head1 SYNOPSIS
+
+ use Config;
+ if ($Config{'cc'} =~ /gcc/) {
+ print "built by gcc\n";
+ }
+
+=head1 DESCRIPTION
+
+The Config module contains everything that was available to the
+C<Configure> program at Perl build time. Shell variables from
+F<config.sh> are stored in the readonly-variable C<%Config>, indexed by
+their names.
+
+=head1 EXAMPLE
+
+Here's a more sophisticated example of using %Config:
+
+ use Config;
+
+ defined $Config{sig_name} || die "No sigs?";
+ foreach $name (split(' ', $Config{sig_name})) {
+ $signo{$name} = $i;
+ $signame[$i] = $name;
+ $i++;
+ }
+
+ print "signal #17 = $signame[17]\n";
+ if ($signo{ALRM}) {
+ print "SIGALRM is $signo{ALRM}\n";
+ }
+
+=head1 NOTE
+
+This module contains a good example of how to make a variable
+readonly to those outside of it.
diff --git a/pod/modpods/Cwd.pod b/pod/modpods/Cwd.pod
new file mode 100644
index 0000000000..ac4e24f74d
--- /dev/null
+++ b/pod/modpods/Cwd.pod
@@ -0,0 +1,26 @@
+=head1 NAME
+
+getcwd - get pathname of current working directory
+
+=head1 SYNOPSIS
+
+ require Cwd;
+ $dir = Cwd::getcwd()'
+
+ use Cwd;
+ $dir = getcwd()'
+
+ use Cwd 'chdir';
+ chdir "/tmp";
+ print $ENV{'PWD'};
+
+=head1 DESCRIPTION
+
+The getcwd() function re-implements the getcwd(3) (or getwd(3)) functions
+in Perl. If you ask to override your chdir() built-in function, then your
+PWD environment variable will be kept up to date. (See
+L<perlsub/Overriding builtin functions>.)
+
+The fastgetcwd() function looks the same as getcwd(), but runs faster.
+It's also more dangerous because you might conceivably chdir() out of a
+directory that you can't chdir() back into.
diff --git a/pod/modpods/DB_File.pod b/pod/modpods/DB_File.pod
new file mode 100644
index 0000000000..919743b7ca
--- /dev/null
+++ b/pod/modpods/DB_File.pod
@@ -0,0 +1,319 @@
+=head1 NAME
+
+DB_File - Perl5 access to Berkeley DB
+
+=head1 SYNOPSIS
+
+ use DB_File ;
+
+ [$X =] tie %hash, DB_File, $filename [, $flags, $mode, $DB_HASH] ;
+ [$X =] tie %hash, DB_File, $filename, $flags, $mode, $DB_BTREE ;
+ [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ;
+
+ $status = $X->del($key [, $flags]) ;
+ $status = $X->put($key, $value [, $flags]) ;
+ $status = $X->get($key, $value [, $flags]) ;
+ $status = $X->seq($key, $value [, $flags]) ;
+ $status = $X->sync([$flags]) ;
+ $status = $X->fd ;
+
+ untie %hash ;
+ untie @array ;
+
+=head1 DESCRIPTION
+
+B<DB_File> is a module which allows Perl programs to make use of
+the facilities provided by Berkeley DB. If you intend to use this
+module you should really have a copy of the Berkeley DB manual
+page at hand. The interface defined here
+mirrors the Berkeley DB interface closely.
+
+Berkeley DB is a C library which provides a consistent interface to a number of
+database formats.
+B<DB_File> provides an interface to all three of the database types currently
+supported by Berkeley DB.
+
+The file types are:
+
+=over 5
+
+=item DB_HASH
+
+This database type allows arbitrary key/data pairs to be stored in data files.
+This is equivalent to the functionality provided by
+other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM.
+Remember though, the files created using DB_HASH are
+not compatible with any of the other packages mentioned.
+
+A default hashing algorithm, which will be adequate for most applications,
+is built into Berkeley DB.
+If you do need to use your own hashing algorithm it is possible to write your
+own in Perl and have B<DB_File> use it instead.
+
+=item DB_BTREE
+
+The btree format allows arbitrary key/data pairs to be stored in a sorted,
+balanced binary tree.
+
+As with the DB_HASH format, it is possible to provide a user defined Perl routine
+to perform the comparison of keys. By default, though, the keys are stored
+in lexical order.
+
+=item DB_RECNO
+
+DB_RECNO allows both fixed-length and variable-length flat text files to be
+manipulated using
+the same key/value pair interface as in DB_HASH and DB_BTREE.
+In this case the key will consist of a record (line) number.
+
+=back
+
+=head2 How does DB_File interface to Berkeley DB?
+
+B<DB_File> allows access to Berkeley DB files using the tie() mechanism
+in Perl 5 (for full details, see L<perlfunc/tie()>).
+This facility allows B<DB_File> to access Berkeley DB files using
+either an associative array (for DB_HASH & DB_BTREE file types) or an
+ordinary array (for the DB_RECNO file type).
+
+In addition to the tie() interface, it is also possible to use most of the
+functions provided in the Berkeley DB API.
+
+=head2 Differences with Berkeley DB
+
+Berkeley DB uses the function dbopen() to open or create a
+database. Below is the C prototype for dbopen().
+
+ DB*
+ dbopen (const char * file, int flags, int mode,
+ DBTYPE type, const void * openinfo)
+
+The parameter C<type> is an enumeration which specifies which of the 3
+interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
+Depending on which of these is actually chosen, the final parameter,
+I<openinfo> points to a data structure which allows tailoring of the
+specific interface method.
+
+This interface is handled
+slightly differently in B<DB_File>. Here is an equivalent call using
+B<DB_File>.
+
+ tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ;
+
+The C<filename>, C<flags> and C<mode> parameters are the direct equivalent
+of their dbopen() counterparts. The final parameter $DB_HASH
+performs the function of both the C<type> and C<openinfo>
+parameters in dbopen().
+
+In the example above $DB_HASH is actually a reference to a hash object.
+B<DB_File> has three of these pre-defined references.
+Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO.
+
+The keys allowed in each of these pre-defined references is limited to the names
+used in the equivalent C structure.
+So, for example, the $DB_HASH reference will only allow keys called C<bsize>,
+C<cachesize>, C<ffactor>, C<hash>, C<lorder> and C<nelem>.
+
+To change one of these elements, just assign to it like this
+
+ $DB_HASH{cachesize} = 10000 ;
+
+
+=head2 RECNO
+
+
+In order to make RECNO more compatible with Perl the array offset for all
+RECNO arrays begins at 0 rather than 1 as in Berkeley DB.
+
+
+=head2 In Memory Databases
+
+Berkeley DB allows the creation of in-memory databases by using NULL (that is, a
+C<(char *)0 in C) in
+place of the filename.
+B<DB_File> uses C<undef> instead of NULL to provide this functionality.
+
+
+=head2 Using the Berkeley DB Interface Directly
+
+As well as accessing Berkeley DB using a tied hash or array, it is also
+possible to make direct use of most of the functions defined in the Berkeley DB
+documentation.
+
+
+To do this you need to remember the return value from the tie.
+
+ $db = tie %hash, DB_File, "filename"
+
+Once you have done that, you can access the Berkeley DB API functions directly.
+
+ $db->put($key, $value, R_NOOVERWRITE) ;
+
+All the functions defined in L<dbx(3X)> are available except
+for close() and dbopen() itself.
+The B<DB_File> interface to these functions have been implemented to mirror
+the the way Berkeley DB works. In particular note that all the functions return
+only a status value. Whenever a Berkeley DB function returns data via one of
+its parameters, the B<DB_File> equivalent does exactly the same.
+
+All the constants defined in L<dbopen> are also available.
+
+Below is a list of the functions available.
+
+=over 5
+
+=item get
+
+Same as in C<recno> except that the flags parameter is optional.
+Remember the value
+associated with the key you request is returned in the $value parameter.
+
+=item put
+
+As usual the flags parameter is optional.
+
+If you use either the R_IAFTER or
+R_IBEFORE flags, the key parameter will have the record number of the inserted
+key/value pair set.
+
+=item del
+
+The flags parameter is optional.
+
+=item fd
+
+As in I<recno>.
+
+=item seq
+
+The flags parameter is optional.
+
+Both the key and value parameters will be set.
+
+=item sync
+
+The flags parameter is optional.
+
+=back
+
+=head1 EXAMPLES
+
+It is always a lot easier to understand something when you see a real example.
+So here are a few.
+
+=head2 Using HASH
+
+ use DB_File ;
+ use Fcntl ;
+
+ tie %h, DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ;
+
+ # Add a key/value pair to the file
+ $h{"apple"} = "orange" ;
+
+ # Check for existence of a key
+ print "Exists\n" if $h{"banana"} ;
+
+ # Delete
+ delete $h{"apple"} ;
+
+ untie %h ;
+
+=head2 Using BTREE
+
+Here is sample of code which used BTREE. Just to make life more interesting
+the default comparision function will not be used. Instead a Perl sub, C<Compare()>,
+will be used to do a case insensitive comparison.
+
+ use DB_File ;
+ use Fcntl ;
+
+ sub Compare
+ {
+ my ($key1, $key2) = @_ ;
+
+ "\L$key1" cmp "\L$key2" ;
+ }
+
+ $DB_BTREE->{compare} = 'Compare' ;
+
+ tie %h, DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ;
+
+ # Add a key/value pair to the file
+ $h{'Wall'} = 'Larry' ;
+ $h{'Smith'} = 'John' ;
+ $h{'mouse'} = 'mickey' ;
+ $h{'duck'} = 'donald' ;
+
+ # Delete
+ delete $h{"duck"} ;
+
+ # Cycle through the keys printing them in order.
+ # Note it is not necessary to sort the keys as
+ # the btree will have kept them in order automatically.
+ foreach (keys %h)
+ { print "$_\n" }
+
+ untie %h ;
+
+Here is the output from the code above.
+
+ mouse
+ Smith
+ Wall
+
+
+=head2 Using RECNO
+
+ use DB_File ;
+ use Fcntl ;
+
+ $DB_RECNO->{psize} = 3000 ;
+
+ tie @h, DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ;
+
+ # Add a key/value pair to the file
+ $h[0] = "orange" ;
+
+ # Check for existence of a key
+ print "Exists\n" if $h[1] ;
+
+ untie @h ;
+
+
+
+=head1 WARNINGS
+
+If you happen find any other functions defined in the source for this module
+that have not been mentioned in this document -- beware.
+I may drop them at a moments notice.
+
+If you cannot find any, then either you didn't look very hard or the moment has
+passed and I have dropped them.
+
+=head1 BUGS
+
+Some older versions of Berkeley DB had problems with fixed length records
+using the RECNO file format. The newest version at the time of writing
+was 1.85 - this seems to have fixed the problems with RECNO.
+
+I am sure there are bugs in the code. If you do find any, or can suggest any
+enhancements, I would welcome your comments.
+
+=head1 AVAILABILITY
+
+Berkeley DB is available via the hold C<ftp.cs.berkeley.edu> in the
+directory C</ucb/4bsd/db.tar.gz>. It is I<not> under the GPL.
+
+=head1 SEE ALSO
+
+L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)>
+
+Berkeley DB is available from F<ftp.cs.berkeley.edu> in the directory F</ucb/4bsd>.
+
+=head1 AUTHOR
+
+The DB_File interface was written by
+Paul Marquess <pmarquess@bfsec.bt.co.uk>.
+Questions about the DB system itself may be addressed to
+Keith Bostic <bostic@cs.berkeley.edu>.
diff --git a/pod/modpods/Dynaloader.pod b/pod/modpods/Dynaloader.pod
new file mode 100644
index 0000000000..9810dad205
--- /dev/null
+++ b/pod/modpods/Dynaloader.pod
@@ -0,0 +1,316 @@
+=head1 NAME
+
+DynaLoader - Dynamically load C libraries into Perl code
+
+dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules
+
+=head1 SYNOPSIS
+
+ require DynaLoader;
+ push (@ISA, 'DynaLoader');
+
+
+=head1 DESCRIPTION
+
+This specification defines a standard generic interface to the dynamic
+linking mechanisms available on many platforms. Its primary purpose is
+to implement automatic dynamic loading of Perl modules.
+
+The DynaLoader is designed to be a very simple high-level
+interface that is sufficiently general to cover the requirements
+of SunOS, HP-UX, NeXT, Linux, VMS and other platforms.
+
+It is also hoped that the interface will cover the needs of OS/2,
+NT etc and allow pseudo-dynamic linking (using C<ld -A> at runtime).
+
+This document serves as both a specification for anyone wishing to
+implement the DynaLoader for a new platform and as a guide for
+anyone wishing to use the DynaLoader directly in an application.
+
+It must be stressed that the DynaLoader, by itself, is practically
+useless for accessing non-Perl libraries because it provides almost no
+Perl-to-C 'glue'. There is, for example, no mechanism for calling a C
+library function or supplying arguments. It is anticipated that any
+glue that may be developed in the future will be implemented in a
+separate dynamically loaded module.
+
+DynaLoader Interface Summary
+
+ @dl_library_path
+ @dl_resolve_using
+ @dl_require_symbols
+ $dl_debug
+ Implemented in:
+ bootstrap($modulename) Perl
+ @filepaths = dl_findfile(@names) Perl
+
+ $libref = dl_load_file($filename) C
+ $symref = dl_find_symbol($libref, $symbol) C
+ @symbols = dl_undef_symbols() C
+ dl_install_xsub($name, $symref [, $filename]) C
+ $message = dl_error C
+
+=over 4
+
+=item @dl_library_path
+
+The standard/default list of directories in which dl_findfile() will
+search for libraries etc. Directories are searched in order:
+$dl_library_path[0], [1], ... etc
+
+@dl_library_path is initialised to hold the list of 'normal' directories
+(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}.). This should
+ensure portability across a wide range of platforms.
+
+@dl_library_path should also be initialised with any other directories
+that can be determined from the environment at runtime (such as
+LD_LIBRARY_PATH for SunOS).
+
+After initialisation @dl_library_path can be manipulated by an
+application using push and unshift before calling dl_findfile().
+Unshift can be used to add directories to the front of the search order
+either to save search time or to override libraries with the same name
+in the 'normal' directories.
+
+The load function that dl_load_file() calls may require an absolute
+pathname. The dl_findfile() function and @dl_library_path can be
+used to search for and return the absolute pathname for the
+library/object that you wish to load.
+
+=item @dl_resolve_using
+
+A list of additional libraries or other shared objects which can be
+used to resolve any undefined symbols that might be generated by a
+later call to load_file().
+
+This is only required on some platforms which do not handle dependent
+libraries automatically. For example the Socket Perl extension library
+(F<auto/Socket/Socket.so>) contains references to many socket functions
+which need to be resolved when it's loaded. Most platforms will
+automatically know where to find the 'dependent' library (e.g.,
+F</usr/lib/libsocket.so>). A few platforms need to to be told the location
+of the dependent library explicitly. Use @dl_resolve_using for this.
+
+Example usage:
+
+ @dl_resolve_using = dl_findfile('-lsocket');
+
+=item @dl_require_symbols
+
+A list of one or more symbol names that are in the library/object file
+to be dynamically loaded. This is only required on some platforms.
+
+=item dl_error()
+
+Syntax:
+
+ $message = dl_error();
+
+Error message text from the last failed DynaLoader function. Note
+that, similar to errno in unix, a successful function call does not
+reset this message.
+
+Implementations should detect the error as soon as it occurs in any of
+the other functions and save the corresponding message for later
+retrieval. This will avoid problems on some platforms (such as SunOS)
+where the error message is very temporary (e.g., dlerror()).
+
+=item $dl_debug
+
+Internal debugging messages are enabled when $dl_debug is set true.
+Currently setting $dl_debug only affects the Perl side of the
+DynaLoader. These messages should help an application developer to
+resolve any DynaLoader usage problems.
+
+$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined.
+
+For the DynaLoader developer/porter there is a similar debugging
+variable added to the C code (see dlutils.c) and enabled if Perl was
+built with the B<-DDEBUGGING> flag. This can also be set via the
+PERL_DL_DEBUG environment variable. Set to 1 for minimal information or
+higher for more.
+
+=item dl_findfile()
+
+Syntax:
+
+ @filepaths = dl_findfile(@names)
+
+Determine the full paths (including file suffix) of one or more
+loadable files given their generic names and optionally one or more
+directories. Searches directories in @dl_library_path by default and
+returns an empty list if no files were found.
+
+Names can be specified in a variety of platform independent forms. Any
+names in the form B<-lname> are converted into F<libname.*>, where F<.*> is
+an appropriate suffix for the platform.
+
+If a name does not already have a suitable prefix and/or suffix then
+the corresponding file will be searched for by trying combinations of
+prefix and suffix appropriate to the platform: "$name.o", "lib$name.*"
+and "$name".
+
+If any directories are included in @names they are searched before
+@dl_library_path. Directories may be specified as B<-Ldir>. Any other names
+are treated as filenames to be searched for.
+
+Using arguments of the form C<-Ldir> and C<-lname> is recommended.
+
+Example:
+
+ @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
+
+
+=item dl_expandspec()
+
+Syntax:
+
+ $filepath = dl_expandspec($spec)
+
+Some unusual systems, such as VMS, require special filename handling in
+order to deal with symbolic names for files (i.e., VMS's Logical Names).
+
+To support these systems a dl_expandspec() function can be implemented
+either in the F<dl_*.xs> file or code can be added to the autoloadable
+dl_expandspec(0 function in F<DynaLoader.pm). See F<DynaLoader.pm> for more
+information.
+
+=item dl_load_file()
+
+Syntax:
+
+ $libref = dl_load_file($filename)
+
+Dynamically load $filename, which must be the path to a shared object
+or library. An opaque 'library reference' is returned as a handle for
+the loaded object. Returns undef on error.
+
+(On systems that provide a handle for the loaded object such as SunOS
+and HPUX, $libref will be that handle. On other systems $libref will
+typically be $filename or a pointer to a buffer containing $filename.
+The application should not examine or alter $libref in any way.)
+
+This is function that does the real work. It should use the current
+values of @dl_require_symbols and @dl_resolve_using if required.
+
+ SunOS: dlopen($filename)
+ HP-UX: shl_load($filename)
+ Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
+ NeXT: rld_load($filename, @dl_resolve_using)
+ VMS: lib$find_image_symbol($filename,$dl_require_symbols[0])
+
+
+=item dl_find_symbol()
+
+Syntax:
+
+ $symref = dl_find_symbol($libref, $symbol)
+
+Return the address of the symbol $symbol or C<undef> if not found. If the
+target system has separate functions to search for symbols of different
+types then dl_find_symbol() should search for function symbols first and
+then other types.
+
+The exact manner in which the address is returned in $symref is not
+currently defined. The only initial requirement is that $symref can
+be passed to, and understood by, dl_install_xsub().
+
+ SunOS: dlsym($libref, $symbol)
+ HP-UX: shl_findsym($libref, $symbol)
+ Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
+ NeXT: rld_lookup("_$symbol")
+ VMS: lib$find_image_symbol($libref,$symbol)
+
+
+=item dl_undef_symbols()
+
+Example
+
+ @symbols = dl_undef_symbols()
+
+Return a list of symbol names which remain undefined after load_file().
+Returns C<()> if not known. Don't worry if your platform does not provide
+a mechanism for this. Most do not need it and hence do not provide it.
+
+
+=item dl_install_xsub()
+
+Syntax:
+
+ dl_install_xsub($perl_name, $symref [, $filename])
+
+Create a new Perl external subroutine named $perl_name using $symref as
+a pointer to the function which implements the routine. This is simply
+a direct call to newXSUB(). Returns a reference to the installed
+function.
+
+The $filename parameter is used by Perl to identify the source file for
+the function if required by die(), caller() or the debugger. If
+$filename is not defined then "DynaLoader" will be used.
+
+
+=item boostrap()
+
+Syntax:
+
+bootstrap($module)
+
+This is the normal entry point for automatic dynamic loading in Perl.
+
+It performs the following actions:
+
+=over 8
+
+=item *
+
+locates an auto/$module directory by searching @INC
+
+=item *
+
+uses dl_findfile() to determine the filename to load
+
+=item *
+
+sets @dl_require_symbols to C<("boot_$module")>
+
+=item *
+
+executes an F<auto/$module/$module.bs> file if it exists
+(typically used to add to @dl_resolve_using any files which
+are required to load the module on the current platform)
+
+=item *
+
+calls dl_load_file() to load the file
+
+=item *
+
+calls dl_undef_symbols() and warns if any symbols are undefined
+
+=item *
+
+calls dl_find_symbol() for "boot_$module"
+
+=item *
+
+calls dl_install_xsub() to install it as "${module}::bootstrap"
+
+=item *
+
+calls &{"${module}::bootstrap"} to bootstrap the module
+
+=back
+
+=back
+
+
+=head1 AUTHOR
+
+This interface is based on the work and comments of (in no particular
+order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno
+Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, and others.
+
+Larry Wall designed the elegant inherited bootstrap mechanism and
+implemented the first Perl 5 dynamic loader using it.
+
+Tim Bunce, 11 August 1994.
diff --git a/pod/modpods/English.pod b/pod/modpods/English.pod
new file mode 100644
index 0000000000..d6b26beaf2
--- /dev/null
+++ b/pod/modpods/English.pod
@@ -0,0 +1,24 @@
+=head1 NAME
+
+English - use nice English (or awk) names for ugly punctuation variables
+
+=head1 SYNOPSIS
+
+ use English;
+ ...
+ if ($ERRNO =~ /denied/) { ... }
+
+=head1 DESCRIPTION
+
+This module provides aliases for the built-in variables whose
+names no one seems to like to read. Variables with side-effects
+which get triggered just by accessing them (like $0) will still
+be affected.
+
+For those variables that have an B<awk> version, both long
+and short English alternatives are provided. For example,
+the C<$/> variable can be referred to either $RS or
+$INPUT_RECORD_SEPARATOR if you are using the English module.
+
+See L<perlvar> for a complete list of these.
+
diff --git a/pod/modpods/Env.pod b/pod/modpods/Env.pod
new file mode 100644
index 0000000000..44344998bd
--- /dev/null
+++ b/pod/modpods/Env.pod
@@ -0,0 +1,31 @@
+=head1 NAME
+
+Env - Perl module that imports environment variables
+
+=head1 DESCRIPTION
+
+Perl maintains environment variables in a pseudo-associative-array
+named %ENV. For when this access method is inconvenient, the Perl
+module C<Env> allows environment variables to be treated as simple
+variables.
+
+The Env::import() function ties environment variables with suitable
+names to global Perl variables with the same names. By default it
+does so with all existing environment variables (C<keys %ENV>). If
+the import function receives arguments, it takes them to be a list of
+environment variables to tie; it's okay if they don't yet exist.
+
+After an environment variable is tied, merely use it like a normal variable.
+You may access its value
+
+ @path = split(/:/, $PATH);
+
+or modify it
+
+ $PATH .= ":.";
+
+however you'd like.
+To remove a tied environment variable from
+the environment, assign it the undefined value
+
+ undef $PATH;
diff --git a/pod/modpods/Exporter.pod b/pod/modpods/Exporter.pod
new file mode 100644
index 0000000000..03e6a1c92d
--- /dev/null
+++ b/pod/modpods/Exporter.pod
@@ -0,0 +1,60 @@
+=head1 NAME
+
+Exporter - module to control namespace manipulations
+
+import - import functions into callers namespace
+
+=head1 SYNOPSYS
+
+ package WhatEver;
+ require Exporter;
+ @ISA = (Exporter);
+ @EXPORT = qw(func1, $foo, %tabs);
+ @EXPORT_OK = qw(sin cos);
+ ...
+ use Whatever;
+ use WhatEver 'sin';
+
+=head1 DESCRIPTION
+
+The Exporter module is used by well-behaved Perl modules to
+control what they will export into their user's namespace.
+The WhatEver module above has placed in its export list
+the function C<func1()>, the scalar C<$foo>, and the
+hash C<%tabs>. When someone decides to
+C<use WhatEver>, they get those identifier grafted
+onto their own namespace. That means the user of
+package whatever can use the function func1() instead
+of fully qualifying it as WhatEver::func1().
+
+You should be careful of such namespace pollution.
+Of course, the user of the WhatEver module is free to
+use a C<require> instead of a C<use>, which will
+preserve the sanctity of their namespace.
+
+In particular, you almost certainly shouldn't
+automatically export functions whose names are
+already used in the language. For this reason,
+the @EXPORT_OK list contains those function which
+may be selectively imported, as the sin() function
+was above.
+See L<perlsub/Overriding builtin functions>.
+
+You can't import names that aren't in either the @EXPORT
+or the @EXPORT_OK list.
+
+Remember that these two constructs are identical:
+
+ use WhatEver;
+
+ BEGIN {
+ require WhatEver;
+ import Module;
+ }
+
+The import() function above is not predefined in the
+language. Rather, it's a method in the Exporter module.
+A sneaky library writer could conceivably have an import()
+method that behaved differently from the standard one, but
+that's not very friendly.
+
diff --git a/pod/modpods/Fcntl.pod b/pod/modpods/Fcntl.pod
new file mode 100644
index 0000000000..165153e475
--- /dev/null
+++ b/pod/modpods/Fcntl.pod
@@ -0,0 +1,20 @@
+=head1 NAME
+
+Fcntl - load the C Fcntl.h defines
+
+=head1 SYNOPSIS
+
+ use Fcntl;
+
+=head1 DESCRIPTION
+
+This module is just a translation of the C F<fnctl.h> file.
+Unlike the old mechanism of requiring a translated F<fnctl.ph>
+file, this uses the B<h2xs> program (see the Perl source distribution)
+and your native C compiler. This means that it has a
+far more likely chance of getting the numbers right.
+
+=head1 NOTE
+
+Only C<#define> symbols get translated; you must still correctly
+pack up your own arguments to pass as args for locking functions, etc.
diff --git a/pod/modpods/FileHandle.pod b/pod/modpods/FileHandle.pod
new file mode 100644
index 0000000000..d595617973
--- /dev/null
+++ b/pod/modpods/FileHandle.pod
@@ -0,0 +1,46 @@
+=head1 NAME
+
+FileHandle - supply object methods for filehandles
+
+cacheout - keep more files open than the system permits
+
+=head1 SYNOPSIS
+
+ use FileHandle;
+ autoflush STDOUT 1;
+
+ cacheout($path);
+ print $path @data;
+
+=head1 DESCRIPTION
+
+See L<perlvar> for complete descriptions of each of the following supported C<FileHandle>
+methods:
+
+ print
+ autoflush
+ output_field_separator
+ output_record_separator
+ input_record_separator
+ input_line_number
+ format_page_number
+ format_lines_per_page
+ format_lines_left
+ format_name
+ format_top_name
+ format_line_break_characters
+ format_formfeed
+
+The cacheout() function will make sure that there's a filehandle
+open for writing available as the pathname you give it. It automatically
+closes and re-opens files if you exceed your system file descriptor maximum.
+
+=head1 BUGS
+
+F<sys/param.h> lies with its C<NOFILE> define on some systems,
+so you may have to set $cacheout::maxopen yourself.
+
+Due to backwards compatibility, all filehandles resemble objects
+of class C<FileHandle>, or actually classes derived from that class.
+They actually aren't. Which means you can't derive your own
+class from C<FileHandle> and inherit those methods.
diff --git a/pod/modpods/Find.pod b/pod/modpods/Find.pod
new file mode 100644
index 0000000000..81b46a9879
--- /dev/null
+++ b/pod/modpods/Find.pod
@@ -0,0 +1,44 @@
+=head1 NAME
+
+find - traverse a file tree
+
+=head1 SYNOPSYS
+
+ use File::Find;
+ find(\&wanted, '/foo','/bar');
+ sub wanted { ... }
+
+=head1 DESCRIPTION
+
+The wanted() function does whatever verificationsyou want. $dir contains
+the current directory name, and $_ the current filename within that
+directory. $name contains C<"$dir/$_">. You are chdir()'d to $dir when
+the function is called. The function may set $prune to prune the tree.
+
+This library is primarily for the C<find2perl> tool, which when fed,
+
+ find2perl / -name .nfs\* -mtime +7 \
+ -exec rm -f {} \; -o -fstype nfs -prune
+
+produces something like:
+
+ sub wanted {
+ /^\.nfs.*$/ &&
+ (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
+ int(-M _) > 7 &&
+ unlink($_)
+ ||
+ ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) &&
+ $dev < 0 &&
+ ($prune = 1);
+ }
+
+Set the variable $dont_use_nlink if you're using AFS, since AFS cheats.
+
+Here's another interesting wanted function. It will find all symlinks
+that don't resolve:
+
+ sub wanted {
+ -l && !-e && print "bogus link: $name\n";
+ }
+
diff --git a/pod/modpods/Finddepth.pod b/pod/modpods/Finddepth.pod
new file mode 100644
index 0000000000..022ddaf9f4
--- /dev/null
+++ b/pod/modpods/Finddepth.pod
@@ -0,0 +1,16 @@
+=head1 NAME
+
+finddepth - traverse a directory structure depth-first
+
+=head1 SYNOPSYS
+
+ use File::Finddepth;
+ finddepth(\&wanted, '/foo','/bar');
+ sub wanted { ... }
+
+=head2 DESCRIPTION
+
+This is just like C<File::Find>, except that it does a depthfirst
+search uses finddepth() rather than find(), and performs a
+depth-first search.
+
diff --git a/pod/modpods/GetOptions.pod b/pod/modpods/GetOptions.pod
new file mode 100644
index 0000000000..ca64639968
--- /dev/null
+++ b/pod/modpods/GetOptions.pod
@@ -0,0 +1,137 @@
+=head1 NAME
+
+Getopt::Long, GetOptions - extended getopt processing
+
+=head1 SYNOPSIS
+
+ use Getopt::Long;
+ $result = GetOptions (...option-descriptions...);
+
+=head1 DESCRIPTION
+
+This package implements an extended getopt function. This function adheres
+to the new syntax (long option names, no bundling).
+It tries to implement the better functionality of traditional, GNU and
+POSIX getopt() functions.
+
+Each description should designate a valid Perl identifier, optionally
+followed by an argument specifier.
+
+Values for argument specifiers are:
+
+ <none> option does not take an argument
+ ! option does not take an argument and may be negated
+ =s :s option takes a mandatory (=) or optional (:) string argument
+ =i :i option takes a mandatory (=) or optional (:) integer argument
+ =f :f option takes a mandatory (=) or optional (:) real number argument
+
+If option "name" is set, it will cause the Perl variable $opt_name to
+be set to the specified value. The calling program can use this
+variable to detect whether the option has been set. Options that do
+not take an argument will be set to 1 (one).
+
+Options that take an optional argument will be defined, but set to ''
+if no actual argument has been supplied.
+
+If an "@" sign is appended to the argument specifier, the option is
+treated as an array. Value(s) are not set, but pushed into array
+@opt_name.
+
+Options that do not take a value may have an "!" argument spacifier to
+indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which
+sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0).
+
+The option name may actually be a list of option names, separated by
+'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and
+'blech' will set $opt_foo instead.
+
+Option names may be abbreviated to uniqueness, depending on
+configuration variable $autoabbrev.
+
+Dashes in option names are allowed (e.g. pcc-struct-return) and will
+be translated to underscores in the corresponding Perl variable (e.g.
+$opt_pcc_struct_return). Note that a lone dash "-" is considered an
+option, corresponding Perl identifier is $opt_ .
+
+A double dash "--" signals end of the options list.
+
+If the first option of the list consists of non-alphanumeric
+characters only, it is interpreted as a generic option starter.
+Everything starting with one of the characters from the starter will
+be considered an option.
+
+The default values for the option starters are "-" (traditional), "--"
+(POSIX) and "+" (GNU, being phased out).
+
+Options that start with "--" may have an argument appended, separated
+with an "=", e.g. "--foo=bar".
+
+If configuration varaible $getopt_compat is set to a non-zero value,
+options that start with "+" may also include their arguments,
+e.g. "+foo=bar".
+
+A return status of 0 (false) indicates that the function detected
+one or more errors.
+
+=head1 EXAMPLES
+
+If option "one:i" (i.e. takes an optional integer argument), then
+the following situations are handled:
+
+ -one -two -> $opt_one = '', -two is next option
+ -one -2 -> $opt_one = -2
+
+Also, assume "foo=s" and "bar:s" :
+
+ -bar -xxx -> $opt_bar = '', '-xxx' is next option
+ -foo -bar -> $opt_foo = '-bar'
+ -foo -- -> $opt_foo = '--'
+
+In GNU or POSIX format, option names and values can be combined:
+
+ +foo=blech -> $opt_foo = 'blech'
+ --bar= -> $opt_bar = ''
+ --bar=-- -> $opt_bar = '--'
+
+=over 12
+
+=item $autoabbrev
+
+Allow option names to be abbreviated to uniqueness.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $getopt_compat
+
+Allow '+' to start options.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $option_start
+
+Regexp with option starters.
+Default is (--|-) if environment variable
+POSIXLY_CORRECT has been set, (--|-|\+) otherwise.
+
+=item $order
+
+Whether non-options are allowed to be mixed with
+options.
+Default is $REQUIRE_ORDER if environment variable
+POSIXLY_CORRECT has been set, $PERMUTE otherwise.
+
+=item $ignorecase
+
+Ignore case when matching options. Default is 1.
+
+=item $debug
+
+Enable debugging output. Default is 0.
+
+=back
+
+=head1 NOTE
+
+Does not yet use the Exporter--or even packages!!
+Thus, it's not a real module.
+
diff --git a/pod/modpods/Getopt.pod b/pod/modpods/Getopt.pod
new file mode 100644
index 0000000000..2f607257ba
--- /dev/null
+++ b/pod/modpods/Getopt.pod
@@ -0,0 +1,152 @@
+=head1 NAME
+
+getopt - Process single-character switches with switch clustering
+
+getopts - Process single-character switches with switch clustering
+
+GetOptions - extended getopt processing
+
+=head1 SYNOPSIS
+
+ use Getopt::Std;
+ getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect.
+ getopts('oif:'); # likewise, but all of them
+
+ use Getopt::Long;
+ $result = GetOptions (...option-descriptions...);
+
+=head1 DESCRIPTION
+
+The getopt() functions processes single-character switches with switch
+clustering. Pass one argument which is a string containing all switches
+that take an argument. For each switch found, sets $opt_x (where x is the
+switch name) to the value of the argument, or 1 if no argument. Switches
+which take an argument don't care whether there is a space between the
+switch and the argument.
+
+The Getopt::Long module implements an extended getopt function called
+GetOptions(). This function adheres to the new syntax (long option names,
+no bundling). It tries to implement the better functionality of
+traditional, GNU and POSIX getopt() functions.
+
+Each description should designate a valid Perl identifier, optionally
+followed by an argument specifier.
+
+Values for argument specifiers are:
+
+ <none> option does not take an argument
+ ! option does not take an argument and may be negated
+ =s :s option takes a mandatory (=) or optional (:) string argument
+ =i :i option takes a mandatory (=) or optional (:) integer argument
+ =f :f option takes a mandatory (=) or optional (:) real number argument
+
+If option "name" is set, it will cause the Perl variable $opt_name to
+be set to the specified value. The calling program can use this
+variable to detect whether the option has been set. Options that do
+not take an argument will be set to 1 (one).
+
+Options that take an optional argument will be defined, but set to ''
+if no actual argument has been supplied.
+
+If an "@" sign is appended to the argument specifier, the option is
+treated as an array. Value(s) are not set, but pushed into array
+@opt_name.
+
+Options that do not take a value may have an "!" argument specifier to
+indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which
+sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0).
+
+The option name may actually be a list of option names, separated by
+'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and
+'blech' will set $opt_foo instead.
+
+Option names may be abbreviated to uniqueness, depending on
+configuration variable $autoabbrev.
+
+Dashes in option names are allowed (e.g. pcc-struct-return) and will
+be translated to underscores in the corresponding Perl variable (e.g.
+$opt_pcc_struct_return). Note that a lone dash "-" is considered an
+option, corresponding Perl identifier is $opt_ .
+
+A double dash "--" signals end of the options list.
+
+If the first option of the list consists of non-alphanumeric
+characters only, it is interpreted as a generic option starter.
+Everything starting with one of the characters from the starter will
+be considered an option.
+
+The default values for the option starters are "-" (traditional), "--"
+(POSIX) and "+" (GNU, being phased out).
+
+Options that start with "--" may have an argument appended, separated
+with an "=", e.g. "--foo=bar".
+
+If configuration variable $getopt_compat is set to a non-zero value,
+options that start with "+" may also include their arguments,
+e.g. "+foo=bar".
+
+A return status of 0 (false) indicates that the function detected
+one or more errors.
+
+=head1 EXAMPLES
+
+If option "one:i" (i.e. takes an optional integer argument), then
+the following situations are handled:
+
+ -one -two -> $opt_one = '', -two is next option
+ -one -2 -> $opt_one = -2
+
+Also, assume "foo=s" and "bar:s" :
+
+ -bar -xxx -> $opt_bar = '', '-xxx' is next option
+ -foo -bar -> $opt_foo = '-bar'
+ -foo -- -> $opt_foo = '--'
+
+In GNU or POSIX format, option names and values can be combined:
+
+ +foo=blech -> $opt_foo = 'blech'
+ --bar= -> $opt_bar = ''
+ --bar=-- -> $opt_bar = '--'
+
+=over 12
+
+=item $autoabbrev
+
+Allow option names to be abbreviated to uniqueness.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $getopt_compat
+
+Allow '+' to start options.
+Default is 1 unless environment variable
+POSIXLY_CORRECT has been set.
+
+=item $option_start
+
+Regexp with option starters.
+Default is (--|-) if environment variable
+POSIXLY_CORRECT has been set, (--|-|\+) otherwise.
+
+=item $order
+
+Whether non-options are allowed to be mixed with
+options.
+Default is $REQUIRE_ORDER if environment variable
+POSIXLY_CORRECT has been set, $PERMUTE otherwise.
+
+=item $ignorecase
+
+Ignore case when matching options. Default is 1.
+
+=item $debug
+
+Enable debugging output. Default is 0.
+
+=back
+
+=head1 NOTE
+
+Does not yet use the Exporter--or even packages!!
+Thus, it's not a real module.
+
diff --git a/pod/modpods/MakeMaker.pod b/pod/modpods/MakeMaker.pod
new file mode 100644
index 0000000000..4db758fb20
--- /dev/null
+++ b/pod/modpods/MakeMaker.pod
@@ -0,0 +1,24 @@
+=head1 NAME
+
+MakeMaker - generate a Makefile for Perl extension
+
+=head1 SYNOPSIS
+
+ use ExtUtils::MakeMaker;
+
+=head1 DESCRIPTION
+
+This utility is designed to write a Makefile for an extension module from
+a Makefile.PL. It splits the task of generating the Makefile into several
+subroutines that can be individually overridden. Each subroutines returns
+the text it wishes to have written to the Makefile.
+
+The best way to learn to use this is to look at how some of the
+extensions are generated, such as Socket.
+
+=head1 AUTHOR
+
+Andy Dougherty <F<doughera@lafcol.lafayette.edu>>,
+Andreas Koenig <F<k@franz.ww.TU-Berlin.DE>>,
+and
+Tim Bunce <F<Tim.Bunce@ig.co.uk>>.
diff --git a/pod/modpods/Open2.pod b/pod/modpods/Open2.pod
new file mode 100644
index 0000000000..19f0369cfd
--- /dev/null
+++ b/pod/modpods/Open2.pod
@@ -0,0 +1,33 @@
+=head1 NAME
+
+IPC::Open2, open2 - open a process for both reading and writing
+
+=head1 SYNOPSIS
+
+ use IPC::Open2;
+ $pid = open2('rdr', 'wtr', 'some cmd and args');
+ # or
+ $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args');
+
+=head1 DESCRIPTION
+
+The open2() function spawns the given $cmd and connects $rdr for
+reading and $wtr for writing. It's what you think should work
+when you try
+
+ open(HANDLE, "|cmd args");
+
+open2() returns the process ID of the child process. It doesn't return on
+failure: it just raises an exception matching C</^open2:/>.
+
+=head1 WARNING
+
+It will not create these file handles for you. You have to do this yourself.
+So don't pass it empty variables expecting them to get filled in for you.
+
+Additionally, this is very dangerous as you may block forever.
+It assumes it's going to talk to something like B<bc>, both writing to
+it and reading from it. This is presumably safe because you "know"
+that commands like B<bc> will read a line at a time and output a line at
+a time. Programs like B<sort> that read their entire input stream first,
+however, are quite apt to cause deadlock. See L<open3> for an alternative.
diff --git a/pod/modpods/Open3.pod b/pod/modpods/Open3.pod
new file mode 100644
index 0000000000..690d8ffdfb
--- /dev/null
+++ b/pod/modpods/Open3.pod
@@ -0,0 +1,23 @@
+=head1 NAME
+
+IPC::Open3, open3 - open a process for reading, writing, and error handling
+
+=head1 SYNOPSIS
+
+ $pid = open3('WTRFH', 'RDRFH', 'ERRFH'
+ 'some cmd and args', 'optarg', ...);
+
+=head1 DESCRIPTION
+
+Extremely similar to open2(), open3() spawns the given $cmd and
+connects RDRFH for reading, WTRFH for writing, and ERRFH for errors. If
+ERRFH is '', or the same as RDRFH, then STDOUT and STDERR of the child are
+on the same file handle.
+
+If WTRFH begins with ">&", then WTRFH will be closed in the parent, and
+the child will read from it directly. if RDRFH or ERRFH begins with
+">&", then the child will send output directly to that file handle. In both
+cases, there will be a dup(2) instead of a pipe(2) made.
+
+All caveats from open2() continue to apply. See L<open2> for details.
+
diff --git a/pod/modpods/POSIX.pod b/pod/modpods/POSIX.pod
new file mode 100644
index 0000000000..30539ad36f
--- /dev/null
+++ b/pod/modpods/POSIX.pod
@@ -0,0 +1,53 @@
+=head1 NAME
+
+POSIX - Perl interface to IEEE 1003.1 namespace
+
+=head1 SYNOPSIS
+
+ use POSIX;
+ use POSIX 'strftime';
+
+=head1 DESCRIPTION
+
+The POSIX module permits you to access all (or nearly all) the standard
+POSIX 1003.1 identifiers. Things which are C<#defines> in C, like EINTR
+or O_NDELAY, are automatically exported into your namespace. All
+functions are only exported if you ask for them explicitly. Most likely
+people will prefer to use the fully-qualified function names.
+
+To get a list of all the possible identifiers available to you--and
+their semantics--you should pick up a 1003.1 spec, or look in the
+F<POSIX.pm> module.
+
+=head1 EXAMPLES
+
+ printf "EENTR is %d\n", EINTR;
+
+ POSIX::setsid(0);
+
+ $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
+ # note: that's a filedescriptor, *NOT* a filehandle
+
+=head1 NOTE
+
+The POSIX module is probably the most complex Perl module supplied with
+the standard distribution. It incorporates autoloading, namespace games,
+and dynamic loading of code that's in Perl, C, or both. It's a great
+source of wisdom.
+
+=head1 CAVEATS
+
+A few functions are not implemented because they are C specific. If you
+attempt to call these, they will print a message telling you that they
+aren't implemented because they're, supplying the Perl equivalent if one
+exists. For example, trying to access the setjmp() call will elicit the
+message "setjmp() is C-specific: use eval {} instead".
+
+Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
+are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
+For example, one vendor may not define EDEADLK, or the semantics of the
+errno values set by open(2) might not be quite right. Perl does not
+attempt to verify POSIX compliance. That means you can currently
+successfully say "use POSIX", and then later in your program you find
+that your vendor has been lax and there's no usable ICANON macro after
+all. This could be construed to be a bug.
diff --git a/pod/modpods/Ping.pod b/pod/modpods/Ping.pod
new file mode 100644
index 0000000000..01bc25c64f
--- /dev/null
+++ b/pod/modpods/Ping.pod
@@ -0,0 +1,37 @@
+=head1 NAME
+
+Net::Ping, pingecho - check a host for upness
+
+=head1 SYNOPSIS
+
+ use Net::Ping;
+ print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ;
+
+=head1 DESCRIPTION
+
+This module contains routines to test for the reachability of remote hosts.
+Currently the only routine implemented is pingecho().
+
+pingecho() uses a TCP echo (I<NOT> an ICMP one) to determine if the
+remote host is reachable. This is usually adequate to tell that a remote
+host is available to rsh(1), ftp(1), or telnet(1) onto.
+
+=head2 Parameters
+
+=over 5
+
+=item hostname
+
+The remote host to check, specified either as a hostname or as an IP address.
+
+=item timeout
+
+The timeout in seconds. If not specified it will default to 5 seconds.
+
+=back
+
+=head1 WARNING
+
+pingecho() uses alarm to implement the timeout, so don't set another alarm
+while you are using it.
+
diff --git a/pod/modpods/Socket.pod b/pod/modpods/Socket.pod
new file mode 100644
index 0000000000..7dfab25b26
--- /dev/null
+++ b/pod/modpods/Socket.pod
@@ -0,0 +1,23 @@
+=head1 NAME
+
+Socket - load the C socket.h defines
+
+=head1 SYNOPSIS
+
+ use Socket;
+
+ $proto = (getprotobyname('udp'))[2];
+ socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
+
+=head1 DESCRIPTION
+
+This module is just a translation of the C F<socket.h> file.
+Unlike the old mechanism of requiring a translated F<socket.ph>
+file, this uses the B<h2xs> program (see the Perl source distribution)
+and your native C compiler. This means that it has a
+far more likely chance of getting the numbers right.
+
+=head1 NOTE
+
+Only C<#define> symbols get translated; you must still correctly
+pack up your own arguments to pass to bind(), etc.
diff --git a/pod/modpods/integer.pod b/pod/modpods/integer.pod
new file mode 100644
index 0000000000..d459bca385
--- /dev/null
+++ b/pod/modpods/integer.pod
@@ -0,0 +1,18 @@
+=head1 NAME
+
+integer - Perl pragma to compute arithmetic in integer instead of double
+
+=head1 SYNOPSIS
+
+ use integer;
+ $x = 10/3;
+ # $x is now 3, not 3.33333333333333333
+
+=head1 DESCRIPTION
+
+This tells the compiler that it's okay to use integer operations
+from here to the end of the enclosing BLOCK. On many machines,
+this doesn't matter a great deal for most computations, but on those
+without floating point hardware, it can make a big difference.
+
+See L<perlmod/Pragmatic Modules>.
diff --git a/pod/modpods/less.pod b/pod/modpods/less.pod
new file mode 100644
index 0000000000..bccc5341d1
--- /dev/null
+++ b/pod/modpods/less.pod
@@ -0,0 +1,13 @@
+=head1 NAME
+
+less - Perl pragma to request less of something from the compiler
+
+=head1 DESCRIPTION
+
+Currently unimplemented, this may someday be a compiler directive
+to make certain trade-off, such as perhaps
+
+ use less 'memory';
+ use less 'CPU';
+ use less 'fat';
+
diff --git a/pod/modpods/sigtrap.pod b/pod/modpods/sigtrap.pod
new file mode 100644
index 0000000000..ecc35421cc
--- /dev/null
+++ b/pod/modpods/sigtrap.pod
@@ -0,0 +1,19 @@
+=head1 NAME
+
+sigtrap - Perl pragma to enable stack backtrace on unexpected signals
+
+=head1 SYNOPSIS
+
+ use sigtrap;
+ use sigtrap qw(BUS SEGV PIPE SYS ABRT TRAP);
+
+=head1 DESCRIPTION
+
+The C<sigtrap> pragma initializes some default signal handlers that print
+a stack dump of your Perl program, then sends itself a SIGABRT. This
+provides a nice starting point if something horrible goes wrong.
+
+By default, handlers are installed for the ABRT, BUS, EMT, FPE, ILL, PIPE,
+QUIT, SEGV, SYS, TERM, and TRAP signals.
+
+See L<perlmod/Pragmatic Modules>.
diff --git a/pod/modpods/strict.pod b/pod/modpods/strict.pod
new file mode 100644
index 0000000000..e994ed2bc5
--- /dev/null
+++ b/pod/modpods/strict.pod
@@ -0,0 +1,65 @@
+=head1 NAME
+
+strict - Perl pragma to restrict unsafe constructs
+
+=head1 SYNOPSIS
+
+ use strict;
+
+ use strict "vars";
+ use strict "refs";
+ use strict "subs";
+
+ use strict;
+ no strict "vars";
+
+=head1 DESCRIPTION
+
+If no import list is supplied, all possible restrictions are assumed.
+(This the safest mode to operate in, but is sometimes too strict for
+casual programming.) Currently, there are three possible things to be
+strict about: "subs", "vars", or "refs".
+
+=over 6
+
+=item C<strict refs>
+
+This generates a runtime error if you
+use symbolic references (see L<perlref>).
+
+ use strict 'refs';
+ $ref = \$foo;
+ print $$ref; # ok
+ $ref = "foo";
+ print $$ref; # runtime error; normally ok
+
+=item C<strict vars>
+
+This generates a compile-time error if you access a variable that wasn't
+localized via C<my()> or wasn't fully qualified. Because this is to avoid
+variable suicide problems and subtle dynamic scoping issues, a merely
+local() variable isn't good enough. See L<perlfunc/my> and
+L<perlfunc/local>.
+
+ use strict 'vars';
+ $X::foo = 1; # ok, fully qualified
+ my $foo = 10; # ok, my() var
+ local $foo = 9; # blows up
+
+The local() generated a compile-time error because you just touched a global
+name without fully qualifying it.
+
+=item C<strict subs>
+
+This disables the poetry optimization,
+generating a compile-time error if you
+try to use a bareword identifiers that's not a subroutine.
+
+ use strict 'subs';
+ $SIG{PIPE} = Plumber; # blows up
+ $SIG{"PIPE"} = "Plumber"; # just fine
+
+=back
+
+See L<perlmod/Pragmatic Modules>.
+
diff --git a/pod/modpods/subs.pod b/pod/modpods/subs.pod
new file mode 100644
index 0000000000..b54b6754ce
--- /dev/null
+++ b/pod/modpods/subs.pod
@@ -0,0 +1,16 @@
+=head1 NAME
+
+subs - Perl pragma to predeclare sub names
+
+=head1 SYNOPSIS
+
+ use subs qw(frob);
+ frob 3..10;
+
+=head1 DESCRIPTION
+
+This will predeclare all the subroutine whose names are
+in the list, allowing you to use them without parentheses
+even before they're declared.
+
+See L<perlmod/Pragmatic Modules> and L<strict/subs>.
diff --git a/pod/perl.pod b/pod/perl.pod
new file mode 100644
index 0000000000..9306d5c9c7
--- /dev/null
+++ b/pod/perl.pod
@@ -0,0 +1,271 @@
+=head1 NAME
+
+perl - Practical Extraction and Report Language
+
+=head1 SYNOPSIS
+
+For ease of access, the Perl manual has been split up into a number
+of sections:
+
+ perl Perl overview (this section)
+ perldata Perl data structures
+ perlsyn Perl syntax
+ perlop Perl operators and precedence
+ perlre Perl regular expressions
+ perlrun Perl execution and options
+ perlfunc Perl builtin functions
+ perlvar Perl predefined variables
+ perlsub Perl subroutines
+ perlmod Perl modules
+ perlref Perl references and nested data structures
+ perlobj Perl objects
+ perlbot Perl OO tricks and examples
+ perldebug Perl debugging
+ perldiag Perl diagnostic messages
+ perlform Perl formats
+ perlipc Perl interprocess communication
+ perlsec Perl security
+ perltrap Perl traps for the unwary
+ perlstyle Perl style guide
+ perlapi Perl application programming interface
+ perlguts Perl internal functions for those doing extensions
+ perlcall Perl calling conventions from C
+ perlovl Perl overloading semantics
+ perlbook Perl book information
+
+(If you're intending to read these straight through for the first time,
+the suggested order will tend to reduce the number of forward references.)
+
+If something strange has gone wrong with your program and you're not
+sure where you should look for help, try the B<-w> switch first. It
+will often point out exactly where the trouble is.
+
+=head1 DESCRIPTION
+
+Perl is an interpreted language optimized for scanning arbitrary
+text files, extracting information from those text files, and printing
+reports based on that information. It's also a good language for many
+system management tasks. The language is intended to be practical
+(easy to use, efficient, complete) rather than beautiful (tiny,
+elegant, minimal). It combines (in the author's opinion, anyway) some
+of the best features of C, B<sed>, B<awk>, and B<sh>, so people
+familiar with those languages should have little difficulty with it.
+(Language historians will also note some vestiges of B<csh>, Pascal,
+and even BASIC-PLUS.) Expression syntax corresponds quite closely to C
+expression syntax. Unlike most Unix utilities, Perl does not
+arbitrarily limit the size of your data--if you've got the memory,
+Perl can slurp in your whole file as a single string. Recursion is
+of unlimited depth. And the hash tables used by associative arrays
+grow as necessary to prevent degraded performance. Perl uses
+sophisticated pattern matching techniques to scan large amounts of data
+very quickly. Although optimized for scanning text, Perl can also
+deal with binary data, and can make dbm files look like associative
+arrays (where dbm is available). Setuid Perl scripts are safer than
+C programs through a dataflow tracing mechanism which prevents many
+stupid security holes. If you have a problem that would ordinarily use
+B<sed> or B<awk> or B<sh>, but it exceeds their capabilities or must
+run a little faster, and you don't want to write the silly thing in C,
+then Perl may be for you. There are also translators to turn your
+B<sed> and B<awk> scripts into Perl scripts.
+
+But wait, there's more...
+
+Perl version 5 is nearly a complete rewrite, and provides
+the following additional benefits:
+
+=over 5
+
+=item * Many usability enhancements
+
+It is now possible to write much more readable Perl code (even within
+regular expressions). Formerly cryptic variable names can be replaced
+by mnemonic identifiers. Error messages are more informative, and the
+optional warnings will catch many of the mistakes a novice might make.
+This cannot be stressed enough. Whenever you get mysterious behavior,
+try the B<-w> switch!!! Whenever you don't get mysterious behavior,
+try using B<-w> anyway.
+
+=item * Simplified grammar
+
+The new yacc grammar is one half the size of the old one. Many of the
+arbitrary grammar rules have been regularized. The number of reserved
+words has been cut by 2/3. Despite this, nearly all old Perl scripts
+will continue to work unchanged.
+
+=item * Lexical scoping
+
+Perl variables may now be declared within a lexical scope, like "auto"
+variables in C. Not only is this more efficient, but it contributes
+to better privacy for "programming in the large".
+
+=item * Arbitrarily nested data structures
+
+Any scalar value, including any array element, may now contain a
+reference to any other variable or subroutine. You can easily create
+anonymous variables and subroutines. Perl manages your reference
+counts for you.
+
+=item * Modularity and reusability
+
+The Perl library is now defined in terms of modules which can be easily
+shared among various packages. A package may choose to import all or a
+portion of a module's published interface. Pragmas (that is, compiler
+directives) are defined and used by the same mechanism.
+
+=item * Object-oriented programming
+
+A package can function as a class. Dynamic multiple inheritance and
+virtual methods are supported in a straightforward manner and with very
+little new syntax. Filehandles may now be treated as objects.
+
+=item * Embeddible and Extensible
+
+Perl may now be embedded easily in your C or C++ application, and can
+either call or be called by your routines through a documented
+interface. The XS preprocessor is provided to make it easy to glue
+your C or C++ routines into Perl. Dynamic loading of modules is
+supported.
+
+=item * POSIX compliant
+
+A major new module is the POSIX module, which provides access to all
+available POSIX routines and definitions, via object classes where
+appropriate.
+
+=item * Package constructors and destructors
+
+The new BEGIN and END blocks provide means to capture control as
+a package is being compiled, and after the program exits. As a
+degenerate case they work just like awk's BEGIN and END when you
+use the B<-p> or B<-n> switches.
+
+=item * Multiple simultaneous DBM implementations
+
+A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
+files from the same script simultaneously. In fact, the old dbmopen
+interface has been generalized to allow any variable to be tied
+to an object class which defines its access methods.
+
+=item * Subroutine definitions may now be autoloaded
+
+In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
+semantics for undefined subroutine calls. It's not just for autoloading.
+
+=item * Regular expression enhancements
+
+You can now specify non-greedy quantifiers. You can now do grouping
+without creating a backreference. You can now write regular expressions
+with embedded whitespace and comments for readability. A consistent
+extensibility mechanism has been added that is upwardly compatible with
+all old regular expressions.
+
+=back
+
+Ok, that's I<definitely> enough hype.
+
+=head1 ENVIRONMENT
+
+=over 12
+
+=item HOME
+
+Used if chdir has no argument.
+
+=item LOGDIR
+
+Used if chdir has no argument and HOME is not set.
+
+=item PATH
+
+Used in executing subprocesses, and in finding the script if B<-S> is
+used.
+
+=item PERL5LIB
+
+A colon-separated list of directories in which to look for Perl library
+files before looking in the standard library and the current
+directory. If PERL5LIB is not defined, PERLLIB is used.
+
+=item PERL5DB
+
+The command used to get the debugger code. If unset, uses
+
+ BEGIN { require 'perl5db.pl' }
+
+=item PERLLIB
+
+A colon-separated list of directories in which to look for Perl library
+files before looking in the standard library and the current
+directory. If PERL5LIB is defined, PERLLIB is not used.
+
+
+=back
+
+Apart from these, Perl uses no other environment variables, except
+to make them available to the script being executed, and to child
+processes. However, scripts running setuid would do well to execute
+the following lines before doing anything else, just to keep people
+honest:
+
+ $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need
+ $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
+ $ENV{'IFS'} = '' if defined $ENV{'IFS'};
+
+=head1 AUTHOR
+
+Larry Wall <F<lwall@netlabs.com.>, with the help of oodles of other folks.
+
+=head1 FILES
+
+ "/tmp/perl-e$$" temporary file for -e commands
+ "@INC" locations of perl 5 libraries
+
+=head1 SEE ALSO
+
+ a2p awk to perl translator
+ s2p sed to perl translator
+
+=head1 DIAGNOSTICS
+
+The B<-w> switch produces some lovely diagnostics.
+
+See L<perldiag> for explanations of all Perl's diagnostics.
+
+Compilation errors will tell you the line number of the error, with an
+indication of the next token or token type that was to be examined.
+(In the case of a script passed to Perl via B<-e> switches, each
+B<-e> is counted as one line.)
+
+Setuid scripts have additional constraints that can produce error
+messages such as "Insecure dependency". See L<perlsec>.
+
+Did we mention that you should definitely consider using the B<-w>
+switch?
+
+=head1 BUGS
+
+The B<-w> switch is not mandatory.
+
+Perl is at the mercy of your machine's definitions of various
+operations such as type casting, atof() and sprintf().
+
+If your stdio requires an seek or eof between reads and writes on a
+particular stream, so does Perl. (This doesn't apply to sysread()
+and syswrite().)
+
+While none of the built-in data types have any arbitrary size limits
+(apart from memory size), there are still a few arbitrary limits: a
+given identifier may not be longer than 255 characters, and no
+component of your PATH may be longer than 255 if you use B<-S>. A regular
+expression may not compile to more than 32767 bytes internally.
+
+Perl actually stands for Pathologically Eclectic Rubbish Lister, but
+don't tell anyone I said that.
+
+=head1 NOTES
+
+The Perl motto is "There's more than one way to do it." Divining
+how many more is left as an exercise to the reader.
+
+The three principle virtues of a programmer are Laziness,
+Impatience, and Hubris. See the Camel Book for why.
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
new file mode 100644
index 0000000000..f76d877f9b
--- /dev/null
+++ b/pod/perlapi.pod
@@ -0,0 +1,951 @@
+=head1 NAME
+
+perlapi - Perl 5 application programming interface for C extensions
+
+=head1 DESCRIPTION
+
+=head2 Introduction
+
+XS is a language used to create an extension interface
+between Perl and some C library which one wishes to use with
+Perl. The XS interface is combined with the library to
+create a new library which can be linked to Perl. An B<XSUB>
+is a function in the XS language and is the core component
+of the Perl application interface.
+
+The XS compiler is called B<xsubpp>. This compiler will embed
+the constructs necessary to let an XSUB, which is really a C
+function in disguise, manipulate Perl values and creates the
+glue necessary to let Perl access the XSUB. The compiler
+uses B<typemaps> to determine how to map C function parameters
+and variables to Perl values. The default typemap handles
+many common C types. A supplement typemap must be created
+to handle special structures and types for the library being
+linked.
+
+Many of the examples which follow will concentrate on creating an
+interface between Perl and the ONC+RPC bind library functions.
+Specifically, the rpcb_gettime() function will be used to demonstrate many
+features of the XS language. This function has two parameters; the first
+is an input parameter and the second is an output parameter. The function
+also returns a status value.
+
+ bool_t rpcb_gettime(const char *host, time_t *timep);
+
+From C this function will be called with the following
+statements.
+
+ #include <rpc/rpc.h>
+ bool_t status;
+ time_t timep;
+ status = rpcb_gettime( "localhost", &timep );
+
+If an XSUB is created to offer a direct translation between this function
+and Perl, then this XSUB will be used from Perl with the following code.
+The $status and $timep variables will contain the output of the function.
+
+ use RPC;
+ $status = rpcb_gettime( "localhost", $timep );
+
+The following XS file shows an XS subroutine, or XSUB, which
+demonstrates one possible interface to the rpcb_gettime()
+function. This XSUB represents a direct translation between
+C and Perl and so preserves the interface even from Perl.
+This XSUB will be invoked from Perl with the usage shown
+above. Note that the first three #include statements, for
+C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
+beginning of an XS file. This approach and others will be
+expanded later in this document.
+
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+ #include <rpc/rpc.h>
+
+ MODULE = RPC PACKAGE = RPC
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char * host
+ time_t &timep
+ OUTPUT:
+ timep
+
+Any extension to Perl, including those containing XSUBs,
+should have a Perl module to serve as the bootstrap which
+pulls the extension into Perl. This module will export the
+extension's functions and variables to the Perl program and
+will cause the extension's XSUBs to be linked into Perl.
+The following module will be used for most of the examples
+in this document and should be used from Perl with the C<use>
+command as shown earlier. Perl modules are explained in
+more detail later in this document.
+
+ package RPC;
+
+ require Exporter;
+ require DynaLoader;
+ @ISA = qw(Exporter DynaLoader);
+ @EXPORT = qw( rpcb_gettime );
+
+ bootstrap RPC;
+ 1;
+
+Throughout this document a variety of interfaces to the rpcb_gettime()
+XSUB will be explored. The XSUBs will take their parameters in different
+orders or will take different numbers of parameters. In each case the
+XSUB is an abstraction between Perl and the real C rpcb_gettime()
+function, and the XSUB must always ensure that the real rpcb_gettime()
+function is called with the correct parameters. This abstraction will
+allow the programmer to create a more Perl-like interface to the C
+function.
+
+=head2 The Anatomy of an XSUB
+
+The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C
+function which takes a single argument and returns a single
+value.
+
+ double
+ sin(x)
+ double<tab>x
+
+The compiler expects a tab between the parameter name and its type, and
+any or no whitespace before the type. When using C pointers the
+indirection operator C<*> should be considered part of the type and the
+address operator C<&> should be considered part of the variable, as is
+demonstrated in the rpcb_gettime() function above. See the section on
+typemaps for more about handling qualifiers and unary operators in C
+types.
+
+The parameter list of a function must not have whitespace
+after the open-parenthesis or before the close-parenthesis.
+
+ INCORRECT CORRECT
+
+ double double
+ sin( x ) sin(x)
+ double x double x
+
+The function name and the return type must be placed on
+separate lines.
+
+ INCORRECT CORRECT
+
+ double sin(x) double
+ double x sin(x)
+ double x
+
+=head2 The Argument Stack
+
+The argument stack is used to store the values which are
+sent as parameters to the XSUB and to store the XSUB's
+return value. In reality all Perl functions keep their
+values on this stack at the same time, each limited to its
+own range of positions on the stack. In this document the
+first position on that stack which belongs to the active
+function will be referred to as position 0 for that function.
+
+XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> refers
+to a position in this XSUB's part of the stack. Position 0 for that
+function would be known to the XSUB as ST(0). The XSUB's incoming
+parameters and outgoing return values always begin at ST(0). For many
+simple cases the B<xsubpp> compiler will generate the code necessary to
+handle the argument stack by embedding code fragments found in the
+typemaps. In more complex cases the programmer must supply the code.
+
+=head2 The RETVAL Variable
+
+The RETVAL variable is a magic variable which always matches
+the return type of the C library function. The B<xsubpp> compiler will
+supply this variable in each XSUB and by default will use it to hold the
+return value of the C library function being called. In simple cases the
+value of RETVAL will be placed in ST(0) of the argument stack where it can
+be received by Perl as the return value of the XSUB.
+
+If the XSUB has a return type of C<void> then the compiler will
+not supply a RETVAL variable for that function. When using
+the PPCODE: directive the RETVAL variable may not be needed.
+
+=head2 The MODULE Keyword
+
+The MODULE keyword is used to start the XS code and to
+specify the package of the functions which are being
+defined. All text preceding the first MODULE keyword is
+considered C code and is passed through to the output
+untouched. Every XS module will have a bootstrap function
+which is used to hook the XSUBs into Perl. The package name
+of this bootstrap function will match the value of the last
+MODULE statement in the XS source files. The value of
+MODULE should always remain constant within the same XS
+file, though this is not required.
+
+The following example will start the XS code and will place
+all functions in a package named RPC.
+
+ MODULE = RPC
+
+=head2 The PACKAGE Keyword
+
+When functions within an XS source file must be separated into packages
+the PACKAGE keyword should be used. This keyword is used with the MODULE
+keyword and must follow immediately after it when used.
+
+ MODULE = RPC PACKAGE = RPC
+
+ [ XS code in package RPC ]
+
+ MODULE = RPC PACKAGE = RPCB
+
+ [ XS code in package RPCB ]
+
+ MODULE = RPC PACKAGE = RPC
+
+ [ XS code in package RPC ]
+
+Although this keyword is optional and in some cases provides redundant
+information it should always be used. This keyword will ensure that the
+XSUBs appear in the desired package.
+
+=head2 The PREFIX Keyword
+
+The PREFIX keyword designates prefixes which should be
+removed from the Perl function names. If the C function is
+C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
+see this function as C<gettime()>.
+
+This keyword should follow the PACKAGE keyword when used.
+If PACKAGE is not used then PREFIX should follow the MODULE
+keyword.
+
+ MODULE = RPC PREFIX = rpc_
+
+ MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
+
+=head2 The OUTPUT: Keyword
+
+The OUTPUT: keyword indicates that certain function parameters should be
+updated (new values made visible to Perl) when the XSUB terminates or that
+certain values should be returned to the calling Perl function. For
+simple functions, such as the sin() function above, the RETVAL variable is
+automatically designated as an output value. In more complex functions
+the B<xsubpp> compiler will need help to determine which variables are output
+variables.
+
+This keyword will normally be used to complement the CODE: keyword.
+The RETVAL variable is not recognized as an output variable when the
+CODE: keyword is present. The OUTPUT: keyword is used in this
+situation to tell the compiler that RETVAL really is an output
+variable.
+
+The OUTPUT: keyword can also be used to indicate that function parameters
+are output variables. This may be necessary when a parameter has been
+modified within the function and the programmer would like the update to
+be seen by Perl. If function parameters are listed under OUTPUT: along
+with the RETVAL variable then the RETVAL variable must be the last one
+listed.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char * host
+ time_t &timep
+ OUTPUT:
+ timep
+
+The OUTPUT: keyword will also allow an output parameter to
+be mapped to a matching piece of code rather than to a
+typemap.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char * host
+ time_t &timep
+ OUTPUT:
+ timep<tab>sv_setnv(ST(1), (double)timep);
+
+=head2 The CODE: Keyword
+
+This keyword is used in more complicated XSUBs which require
+special handling for the C function. The RETVAL variable is
+available but will not be returned unless it is specified
+under the OUTPUT: keyword.
+
+The following XSUB is for a C function which requires special handling of
+its parameters. The Perl usage is given first.
+
+ $status = rpcb_gettime( "localhost", $timep );
+
+The XSUB follows.
+
+ bool_t rpcb_gettime(host,timep)
+ char * host
+ time_t timep
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+In many of the examples shown here the CODE: block (and
+other blocks) will often be contained within braces ( C<{> and
+C<}> ). This protects the CODE: block from complex INPUT
+typemaps and ensures the resulting C code is legal.
+
+=head2 The NO_INIT Keyword
+
+The NO_INIT keyword is used to indicate that a function
+parameter is being used only as an output value. The B<xsubpp>
+compiler will normally generate code to read the values of
+all function parameters from the argument stack and assign
+them to C variables upon entry to the function. NO_INIT
+will tell the compiler that some parameters will be used for
+output rather than for input and that they will be handled
+before the function terminates.
+
+The following example shows a variation of the rpcb_gettime() function.
+This function uses the timep variable only as an output variable and does
+not care about its initial contents.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char * host
+ time_t &timep = NO_INIT
+ OUTPUT:
+ timep
+
+=head2 Initializing Function Parameters
+
+Function parameters are normally initialized with their
+values from the argument stack. The typemaps contain the
+code segments which are used to transfer the Perl values to
+the C parameters. The programmer, however, is allowed to
+override the typemaps and supply alternate initialization
+code.
+
+The following code demonstrates how to supply initialization code for
+function parameters. The initialization code is eval'd by the compiler
+before it is added to the output so anything which should be interpreted
+literally, such as double quotes, must be protected with backslashes.
+
+ bool_t
+ rpcb_gettime(host,timep)
+ char * host = (char *)SvPV(ST(0),na);
+ time_t &timep = 0;
+ OUTPUT:
+ timep
+
+This should not be used to supply default values for parameters. One
+would normally use this when a function parameter must be processed by
+another library function before it can be used. Default parameters are
+covered in the next section.
+
+=head2 Default Parameter Values
+
+Default values can be specified for function parameters by
+placing an assignment statement in the parameter list. The
+default value may be a number or a string. Defaults should
+always be used on the right-most parameters only.
+
+To allow the XSUB for rpcb_gettime() to have a default host
+value the parameters to the XSUB could be rearranged. The
+XSUB will then call the real rpcb_gettime() function with
+the parameters in the correct order. Perl will call this
+XSUB with either of the following statements.
+
+ $status = rpcb_gettime( $timep, $host );
+
+ $status = rpcb_gettime( $timep );
+
+The XSUB will look like the code which follows. A CODE:
+block is used to call the real rpcb_gettime() function with
+the parameters in the correct order for that function.
+
+ bool_t
+ rpcb_gettime(timep,host="localhost")
+ char * host
+ time_t timep = NO_INIT
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 Variable-length Parameter Lists
+
+XSUBs can have variable-length parameter lists by specifying an ellipsis
+C<(...)> in the parameter list. This use of the ellipsis is similar to that
+found in ANSI C. The programmer is able to determine the number of
+arguments passed to the XSUB by examining the C<items> variable which the
+B<xsubpp> compiler supplies for all XSUBs. By using this mechanism one can
+create an XSUB which accepts a list of parameters of unknown length.
+
+The I<host> parameter for the rpcb_gettime() XSUB can be
+optional so the ellipsis can be used to indicate that the
+XSUB will take a variable number of parameters. Perl should
+be able to call this XSUB with either of the following statments.
+
+ $status = rpcb_gettime( $timep, $host );
+
+ $status = rpcb_gettime( $timep );
+
+The XS code, with ellipsis, follows.
+
+ bool_t
+ rpcb_gettime(timep, ...)
+ time_t timep = NO_INIT
+ CODE:
+ {
+ char *host = "localhost";
+
+ if( items > 1 )
+ host = (char *)SvPV(ST(1), na);
+ RETVAL = rpcb_gettime( host, &timep );
+ }
+ OUTPUT:
+ timep
+ RETVAL
+
+=head2 The PPCODE: Keyword
+
+The PPCODE: keyword is an alternate form of the CODE: keyword and is used
+to tell the B<xsubpp> compiler that the programmer is supplying the code to
+control the argument stack for the XSUBs return values. Occassionally one
+will want an XSUB to return a list of values rather than a single value.
+In these cases one must use PPCODE: and then explicitly push the list of
+values on the stack. The PPCODE: and CODE: keywords are not used
+together within the same XSUB.
+
+The following XSUB will call the C rpcb_gettime() function
+and will return its two output values, timep and status, to
+Perl as a single list.
+
+ void rpcb_gettime(host)
+ char * host
+ PPCODE:
+ {
+ time_t timep;
+ bool_t status;
+ status = rpcb_gettime( host, &timep );
+ EXTEND(sp, 2);
+ PUSHs(sv_2mortal(newSVnv(status)));
+ PUSHs(sv_2mortal(newSVnv(timep)));
+ }
+
+Notice that the programmer must supply the C code necessary
+to have the real rpcb_gettime() function called and to have
+the return values properly placed on the argument stack.
+
+The C<void> return type for this function tells the B<xsubpp> compiler that
+the RETVAL variable is not needed or used and that it should not be created.
+In most scenarios the void return type should be used with the PPCODE:
+directive.
+
+The EXTEND() macro is used to make room on the argument
+stack for 2 return values. The PPCODE: directive causes the
+B<xsubpp> compiler to create a stack pointer called C<sp>, and it
+is this pointer which is being used in the EXTEND() macro.
+The values are then pushed onto the stack with the PUSHs()
+macro.
+
+Now the rpcb_gettime() function can be used from Perl with
+the following statement.
+
+ ($status, $timep) = rpcb_gettime("localhost");
+
+=head2 Returning Undef And Empty Lists
+
+Occassionally the programmer will want to simply return
+C<undef> or an empty list if a function fails rather than a
+separate status value. The rpcb_gettime() function offers
+just this situation. If the function succeeds we would like
+to have it return the time and if it fails we would like to
+have undef returned. In the following Perl code the value
+of $timep will either be undef or it will be a valid time.
+
+ $timep = rpcb_gettime( "localhost" );
+
+The following XSUB uses the C<void> return type to disable the generation of
+the RETVAL variable and uses a CODE: block to indicate to the compiler
+that the programmer has supplied all the necessary code. The
+sv_newmortal() call will initialize the return value to undef, making that
+the default return value.
+
+ void
+ rpcb_gettime(host)
+ char * host
+ CODE:
+ {
+ time_t timep;
+ bool_t x;
+ ST(0) = sv_newmortal();
+ if( rpcb_gettime( host, &timep ) )
+ sv_setnv( ST(0), (double)timep);
+ }
+
+The next example demonstrates how one would place an explicit undef in the
+return value, should the need arise.
+
+ void
+ rpcb_gettime(host)
+ char * host
+ CODE:
+ {
+ time_t timep;
+ bool_t x;
+ ST(0) = sv_newmortal();
+ if( rpcb_gettime( host, &timep ) ){
+ sv_setnv( ST(0), (double)timep);
+ }
+ else{
+ ST(0) = &sv_undef;
+ }
+ }
+
+To return an empty list one must use a PPCODE: block and
+then not push return values on the stack.
+
+ void
+ rpcb_gettime(host)
+ char * host
+ PPCODE:
+ {
+ time_t timep;
+ if( rpcb_gettime( host, &timep ) )
+ PUSHs(sv_2mortal(newSVnv(timep)));
+ else{
+ /* Nothing pushed on stack, so an empty */
+ /* list is implicitly returned. */
+ }
+ }
+
+=head2 The CLEANUP: Keyword
+
+This keyword can be used when an XSUB requires special cleanup procedures
+before it terminates. When the CLEANUP: keyword is used it must follow
+any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The
+code specified for the cleanup block will be added as the last statements
+in the XSUB.
+
+=head2 The BOOT: Keyword
+
+The BOOT: keyword is used to add code to the extension's bootstrap
+function. The bootstrap function is generated by the B<xsubpp> compiler and
+normally holds the statements necessary to register any XSUBs with Perl.
+With the BOOT: keyword the programmer can tell the compiler to add extra
+statements to the bootstrap function.
+
+This keyword may be used any time after the first MODULE keyword and should
+appear on a line by itself. The first blank line after the keyword will
+terminate the code block.
+
+ BOOT:
+ # The following message will be printed when the
+ # bootstrap function executes.
+ printf("Hello from the bootstrap!\n");
+
+=head2 Inserting Comments and C Preprocessor Directives
+
+Comments and C preprocessor directives are allowed within
+CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler
+will pass the preprocessor directives through untouched and
+will remove the commented lines. Comments can be added to
+XSUBs by placing a C<#> at the beginning of the line. Care
+should be taken to avoid making the comment look like a C
+preprocessor directive, lest it be interpreted as such.
+
+=head2 Using XS With C++
+
+If a function is defined as a C++ method then it will assume
+its first argument is an object pointer. The object pointer
+will be stored in a variable called THIS. The object should
+have been created by C++ with the new() function and should
+be blessed by Perl with the sv_setptrobj() macro. The
+blessing of the object by Perl can be handled by the
+T_PTROBJ typemap.
+
+If the method is defined as static it will call the C++
+function using the class::method() syntax. If the method is not static
+the function will be called using the THIS->method() syntax.
+
+=head2 Perl Variables
+
+The following demonstrates how the Perl variable $host can
+be accessed from an XSUB. The function B<perl_get_sv()> is
+used to obtain a pointer to the variable, known as an B<SV>
+(Scalar Variable) internally. The package name C<RPC> will be
+added to the name of the variable so perl_get_sv() will know
+in which package $host can be found. If the package name is
+not supplied then perl_get_sv() will search package C<main> for
+the variable. The macro B<SvPVX()> is then used to dereference
+the SV to obtain a C<char*> pointer to its contents.
+
+ void
+ rpcb_gettime()
+ PPCODE:
+ {
+ char *host;
+ SV *hostsv;
+ time_t timep;
+
+ hostsv = perl_get_sv( "RPC::host", FALSE );
+ if( hostsv != NULL ){
+ host = SvPVX( hostsv );
+ if( rpcb_gettime( host, &timep ) )
+ PUSHs(sv_2mortal(newSVnv(timep)));
+ }
+ }
+
+This Perl code can be used to call that XSUB.
+
+ $RPC::host = "localhost";
+ $timep = rpcb_gettime();
+
+In the above example the SV contained a C C<char*> but a Perl
+scalar variable may also contain numbers and references. If
+the SV is expected to have a C C<int> then the macro B<SvIVX()>
+should be used to dereference the SV. When the SV contains
+a C double then B<SvNVX()> should be used.
+
+The macro B<SvRV()> can be used to dereference an SV when it is a Perl
+reference. The result will be another SV which points to the actual Perl
+variable. This can then be dereferenced with SvPVX(), SvNVX(), or
+SvIVX(). The following XSUB will use SvRV().
+
+ void rpcb_gettime()
+ PPCODE:
+ {
+ char *host;
+ SV *rv;
+ SV *hostsv;
+ time_t timep;
+
+ rv = perl_get_sv( "RPC::host", FALSE );
+ if( rv != NULL ){
+ hostsv = SvRV( rv );
+ host = SvPVX( hostsv );
+ if( rpcb_gettime( host, &timep ) )
+ PUSHs(sv_2mortal(newSVnv(timep)));
+ }
+ }
+
+This Perl code will create a variable $RPC::host which is a
+reference to $MY::host. The variable $MY::host contains the
+hostname which will be used.
+
+ $MY::host = "localhost";
+ $RPC::host = \$MY::host;
+ $timep = rpcb_gettime();
+
+The second argument to perl_get_sv() will normally be B<FALSE>
+as shown in the above examples. An argument of B<TRUE> will
+cause variables to be created if they do not already exist.
+One should not use TRUE unless steps are taken to deal with
+a possibly empty SV.
+
+XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to
+access Perl arrays, hashes, and code values.
+
+=head2 Interface Stategy
+
+When designing an interface between Perl and a C library a straight
+translation from C to XS is often sufficient. The interface will often be
+very C-like and occasionally nonintuitive, especially when the C function
+modifies one of its parameters. In cases where the programmer wishes to
+create a more Perl-like interface the following strategy may help to
+identify the more critical parts of the interface.
+
+Identify the C functions which modify their parameters. The XSUBs for
+these functions may be able to return lists to Perl, or may be
+candidates to return undef or an empty list in case of failure.
+
+Identify which values are used only by the C and XSUB functions
+themselves. If Perl does not need to access the contents of the value
+then it may not be necessary to provide a translation for that value
+from C to Perl.
+
+Identify the pointers in the C function parameter lists and return
+values. Some pointers can be handled in XS with the & unary operator on
+the variable name while others will require the use of the * operator on
+the type name. In general it is easier to work with the & operator.
+
+Identify the structures used by the C functions. In many
+cases it may be helpful to use the T_PTROBJ typemap for
+these structures so they can be manipulated by Perl as
+blessed objects.
+
+=head2 The Perl Module
+
+The Perl module is the link between the extension library,
+which was generated from XS code, and the Perl interpreter.
+The module is used to tell Perl what the extension library
+contains. The name and package of the module should match
+the name of the library.
+
+The following is a Perl module for an extension containing
+some ONC+ RPC bind library functions.
+
+ package RPC;
+
+ require Exporter;
+ require DynaLoader;
+ @ISA = qw(Exporter DynaLoader);
+ @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr
+ rpcb_rmtcall rpcb_set rpcb_unset );
+
+ bootstrap RPC;
+ 1;
+
+The RPC extension contains the functions found in the
+@EXPORT list. By using the C<Exporter> module the RPC module
+can make these function names visible to the rest of the
+Perl program. The C<DynaLoader> module will allow the RPC
+module to bootstrap the extension library. To load this
+extension and make the functions available, the following
+Perl statement should be used.
+
+ use RPC;
+
+For more information about the DynaLoader consult its documentation in the
+ext/DynaLoader directory in the Perl source.
+
+=head2 Perl Objects And C Structures
+
+When dealing with C structures one should select either
+B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
+designed to handle pointers to complex objects. The
+T_PTRREF type will allow the Perl object to be unblessed
+while the T_PTROBJ type requires that the object be blessed.
+By using T_PTROBJ one can achieve a form of type-checking
+since the XSUB will attempt to verify that the Perl object
+is of the expected type.
+
+The following XS code shows the getnetconfigent() function which is used
+with ONC TIRPC. The getnetconfigent() function will return a pointer to a
+C structure and has the C prototype shown below. The example will
+demonstrate how the C pointer will become a Perl reference. Perl will
+consider this reference to be a pointer to a blessed object and will
+attempt to call a destructor for the object. A destructor will be
+provided in the XS source to free the memory used by getnetconfigent().
+Destructors in XS can be created by specifying an XSUB function whose name
+ends with the word B<DESTROY>. XS destructors can be used to free memory
+which may have been malloc'd by another XSUB.
+
+ struct netconfig *getnetconfigent(const char *netid);
+
+A C<typedef> will be created for C<struct netconfig>. The Perl
+object will be blessed in a class matching the name of the C
+type, with the tag C<Ptr> appended, and the name should not
+have embedded spaces if it will be a Perl package name. The
+destructor will be placed in a class corresponding to the
+class of the object and the PREFIX keyword will be used to
+trim the name to the word DESTROY as Perl will expect.
+
+ typedef struct netconfig Netconfig;
+
+ MODULE = RPC PACKAGE = RPC
+
+ Netconfig *
+ getnetconfigent(netid)
+ char * netid
+
+ MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
+
+ void
+ rpcb_DESTROY(netconf)
+ Netconfig * netconf
+ CODE:
+ printf("Now in NetconfigPtr::DESTROY\n");
+ free( netconf );
+
+This example requires the following typemap entry. Consult the typemap
+section for more information about adding new typemaps for an extension.
+
+ TYPEMAP
+ Netconfig * T_PTROBJ
+
+This example will be used with the following Perl statements.
+
+ use RPC;
+ $netconf = getnetconfigent("udp");
+
+When Perl destroys the object referenced by $netconf it will send the
+object to the supplied XSUB DESTROY function. Perl cannot determine, and
+does not care, that this object is a C struct and not a Perl object. In
+this sense, there is no difference between the object created by the
+getnetconfigent() XSUB and an object created by a normal Perl subroutine.
+
+=head2 C Headers and Perl
+
+The B<h2xs> compiler is designed to convert C header files in
+/usr/include into Perl extensions. This compiler will
+create a directory under the C<ext> directory of the Perl
+source and will populate it with a Makefile, a Perl Module,
+an XS source file, and a MANIFEST file.
+
+The following command will create an extension called C<Rusers>
+from the <rpcsvc/rusers.h> header.
+
+ h2xs rpcsvc/rusers
+
+When the Rusers extension has been compiled and installed
+Perl can use it to retrieve any C<#define> statements which
+were in the C header.
+
+ use Rusers;
+ print "RPC program number for rusers service: ";
+ print &RUSERSPROG, "\n";
+
+=head2 Creating A New Extension
+
+The B<h2xs> compiler can generate template source files and
+Makefiles. These templates offer a suitable starting point
+for most extensions. The following example demonstrates how
+one might use B<h2xs> to create an extension containing the RPC
+functions in this document.
+
+The extension will not use autoloaded functions and will not define
+constants, so the B<-A> option will be given to B<h2xs>. When run from the
+Perl source directory, the B<h2xs> compiler will create the directory
+ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL,
+and MANIFEST. The XS code for the RPC functions should be added to the
+RPC.xs file. The @EXPORT list in RPC.pm should be updated to include the
+functions from RPC.xs.
+
+ h2xs -An RPC
+
+To compile the extension for dynamic loading the following
+command should be executed from the ext/RPC directory.
+
+ make dynamic
+
+If the extension will be statically linked into the Perl
+binary then the makefile (use C<makefile>, not C<Makefile>) in the
+Perl source directory should be edited to add C<ext/RPC/RPC.a>
+to the C<static_ext> variable. Before making this change Perl
+should have already been built. After the makefile has been
+updated the following command should be executed from the
+Perl source directory.
+
+ make
+
+Perl's B<Configure> script can also be used to add extensions. The extension
+should be placed in the C<ext> directory under the Perl source before Perl
+has been built and prior to running Configure. When Configure is run it
+will find the extension along with the other extensions in the C<ext>
+directory and will add it to the list of extensions to be built. When make
+is run the extension will be built along with the other extensions.
+
+Configure recognizes extensions if they have an XS source
+file which matches the name of the extension directory. If
+the extension directory includes a MANIFEST file Configure
+will search that file for any B<.SH> files and extract them
+after it extracts all the other .SH files listed in the main
+MANIFEST. The main Perl Makefile will then run B<make> in the
+extension's directory if it finds an XS file matching the
+name of the extension's directory.
+
+=head2 The Typemap
+
+The typemap is a collection of code fragments which are used by the B<xsubpp>
+compiler to map C function parameters and values to Perl values. The
+typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
+C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values
+into variables of certain C types. The OUTPUT section tells the compiler
+how to translate the values from certain C types into values Perl can
+understand. The TYPEMAP section tells the compiler which of the INPUT and
+OUTPUT code fragments should be used to map a given C type to a Perl value.
+Each of the sections of the typemap must be preceded by one of the TYPEMAP,
+INPUT, or OUTPUT keywords.
+
+The default typemap in the C<ext> directory of the Perl source contains many
+useful types which can be used by Perl extensions. Some extensions define
+additional typemaps which they keep in their own directory. These
+additional typemaps may reference INPUT and OUTPUT maps in the main
+typemap. The B<xsubpp> compiler will allow the extension's own typemap to
+override any mappings which are in the default typemap.
+
+Most extensions which require a custom typemap will need only the TYPEMAP
+section of the typemap file. The custom typemap used in the
+getnetconfigent() example shown earlier demonstrates what may be the typical
+use of extension typemaps. That typemap is used to equate a C structure
+with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown
+here. Note that the C type is separated from the XS type with a tab and
+that the C unary operator C<*> is considered to be a part of the C type name.
+
+ TYPEMAP
+ Netconfig *<tab>T_PTROBJ
+
+=head1 EXAMPLES
+
+File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
+
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ #include <rpc/rpc.h>
+
+ typedef struct netconfig Netconfig;
+
+ MODULE = RPC PACKAGE = RPC
+
+ void
+ rpcb_gettime(host="localhost")
+ char * host
+ CODE:
+ {
+ time_t timep;
+ ST(0) = sv_newmortal();
+ if( rpcb_gettime( host, &timep ) )
+ sv_setnv( ST(0), (double)timep );
+ }
+
+ Netconfig *
+ getnetconfigent(netid="udp")
+ char * netid
+
+ MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
+
+ void
+ rpcb_DESTROY(netconf)
+ Netconfig * netconf
+ CODE:
+ printf("NetconfigPtr::DESTROY\n");
+ free( netconf );
+
+File C<typemap>: Custom typemap for RPC.xs.
+
+ TYPEMAP
+ Netconfig * T_PTROBJ
+
+File C<RPC.pm>: Perl module for the RPC extension.
+
+ package RPC;
+
+ require Exporter;
+ require DynaLoader;
+ @ISA = qw(Exporter DynaLoader);
+ @EXPORT = qw(rpcb_gettime getnetconfigent);
+
+ bootstrap RPC;
+ 1;
+
+File C<rpctest.pl>: Perl test program for the RPC extension.
+
+ use RPC;
+
+ $netconf = getnetconfigent();
+ $a = rpcb_gettime();
+ print "time = $a\n";
+ print "netconf = $netconf\n";
+
+ $netconf = getnetconfigent("tcp");
+ $a = rpcb_gettime("poplar");
+ print "time = $a\n";
+ print "netconf = $netconf\n";
+
+
+=head1 AUTHOR
+
+Dean Roehrich <roehrich@cray.com>
+September 27, 1994
diff --git a/pod/perlbook.pod b/pod/perlbook.pod
new file mode 100644
index 0000000000..441c43aabf
--- /dev/null
+++ b/pod/perlbook.pod
@@ -0,0 +1,20 @@
+=head1 NAME
+
+perlbook - Perl book information
+
+=head1 DESCRIPTION
+
+You can order 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. I<Programming Perl> is a
+reference work that covers nearly all of Perl (version 4, alas), while
+I<Learning Perl> is a tutorial that covers the most frequently used subset
+of the language.
+
+ Programming Perl (the Camel Book):
+ ISBN 0-937175-64-1 (English)
+ ISBN 4-89052-384-7 (Japanese)
+
+ Learning Perl (the Llama Book):
+ ISBN 1-56592-042-2 (English)
+
diff --git a/pod/perlbot.pod b/pod/perlbot.pod
new file mode 100644
index 0000000000..3df273be7d
--- /dev/null
+++ b/pod/perlbot.pod
@@ -0,0 +1,367 @@
+=head1 NAME
+
+perlbot - Bag'o Object Tricks For Perl5 (the BOT)
+
+=head1 INTRODUCTION
+
+The following collection of tricks and hints is intended to whet curious
+appetites about such things as the use of instance variables and the
+mechanics of object and class relationships. The reader is encouraged to
+consult relevant textbooks for discussion of Object Oriented definitions and
+methodology. This is not intended as a comprehensive guide to Perl5's
+object oriented features, nor should it be construed as a style guide.
+
+The Perl motto still holds: There's more than one way to do it.
+
+=head1 INSTANCE VARIABLES
+
+An anonymous array or anonymous hash can be used to hold instance
+variables. Named parameters are also demonstrated.
+
+ package Foo;
+
+ sub new {
+ my $type = shift;
+ my %params = @_;
+ my $self = {};
+ $self->{'High'} = $params{'High'};
+ $self->{'Low'} = $params{'Low'};
+ bless $self;
+ }
+
+
+ package Bar;
+
+ sub new {
+ my $type = shift;
+ my %params = @_;
+ my $self = [];
+ $self->[0] = $params{'Left'};
+ $self->[1] = $params{'Right'};
+ bless $self;
+ }
+
+ package main;
+
+ $a = new Foo ( 'High' => 42, 'Low' => 11 );
+ print "High=$a->{'High'}\n";
+ print "Low=$a->{'Low'}\n";
+
+ $b = new Bar ( 'Left' => 78, 'Right' => 40 );
+ print "Left=$b->[0]\n";
+ print "Right=$b->[1]\n";
+
+
+=head1 SCALAR INSTANCE VARIABLES
+
+An anonymous scalar can be used when only one instance variable is needed.
+
+ package Foo;
+
+ sub new {
+ my $type = shift;
+ my $self;
+ $self = shift;
+ bless \$self;
+ }
+
+ package main;
+
+ $a = new Foo 42;
+ print "a=$$a\n";
+
+
+=head1 INSTANCE VARIABLE INHERITANCE
+
+This example demonstrates how one might inherit instance variables from a
+superclass for inclusion in the new class. This requires calling the
+superclass's constructor and adding one's own instance variables to the new
+object.
+
+ package Bar;
+
+ sub new {
+ my $self = {};
+ $self->{'buz'} = 42;
+ bless $self;
+ }
+
+ package Foo;
+ @ISA = qw( Bar );
+
+ sub new {
+ my $self = new Bar;
+ $self->{'biz'} = 11;
+ bless $self;
+ }
+
+ package main;
+
+ $a = new Foo;
+ print "buz = ", $a->{'buz'}, "\n";
+ print "biz = ", $a->{'biz'}, "\n";
+
+
+
+=head1 OBJECT RELATIONSHIPS
+
+The following demonstrates how one might implement "containing" and "using"
+relationships between objects.
+
+ package Bar;
+
+ sub new {
+ my $self = {};
+ $self->{'buz'} = 42;
+ bless $self;
+ }
+
+ package Foo;
+
+ sub new {
+ my $self = {};
+ $self->{'Bar'} = new Bar ();
+ $self->{'biz'} = 11;
+ bless $self;
+ }
+
+ package main;
+
+ $a = new Foo;
+ print "buz = ", $a->{'Bar'}->{'buz'}, "\n";
+ print "biz = ", $a->{'biz'}, "\n";
+
+
+
+=head1 OVERRIDING SUPERCLASS METHODS
+
+The following example demonstrates how one might override a superclass
+method and then call the method after it has been overridden. The
+Foo::Inherit class allows the programmer to call an overridden superclass
+method without actually knowing where that method is defined.
+
+
+ package Buz;
+ sub goo { print "here's the goo\n" }
+
+ package Bar; @ISA = qw( Buz );
+ sub google { print "google here\n" }
+
+ package Baz;
+ sub mumble { print "mumbling\n" }
+
+ package Foo;
+ @ISA = qw( Bar Baz );
+ @Foo::Inherit::ISA = @ISA; # Access to overridden methods.
+
+ sub new { bless [] }
+ sub grr { print "grumble\n" }
+ sub goo {
+ my $self = shift;
+ $self->Foo::Inherit::goo();
+ }
+ sub mumble {
+ my $self = shift;
+ $self->Foo::Inherit::mumble();
+ }
+ sub google {
+ my $self = shift;
+ $self->Foo::Inherit::google();
+ }
+
+ package main;
+
+ $foo = new Foo;
+ $foo->mumble;
+ $foo->grr;
+ $foo->goo;
+ $foo->google;
+
+
+=head1 USING RELATIONSHIP WITH SDBM
+
+This example demonstrates an interface for the SDBM class. This creates a
+"using" relationship between the SDBM class and the new class Mydbm.
+
+ use SDBM_File;
+ use POSIX;
+
+ package Mydbm;
+
+ sub TIEHASH {
+ my $self = shift;
+ my $ref = SDBM_File->new(@_);
+ bless {'dbm' => $ref};
+ }
+ sub FETCH {
+ my $self = shift;
+ my $ref = $self->{'dbm'};
+ $ref->FETCH(@_);
+ }
+ sub STORE {
+ my $self = shift;
+ if (defined $_[0]){
+ my $ref = $self->{'dbm'};
+ $ref->STORE(@_);
+ } else {
+ die "Cannot STORE an undefined key in Mydbm\n";
+ }
+ }
+
+ package main;
+
+ tie %foo, Mydbm, "Sdbm", O_RDWR|O_CREAT, 0640;
+ $foo{'bar'} = 123;
+ print "foo-bar = $foo{'bar'}\n";
+
+ tie %bar, Mydbm, "Sdbm2", O_RDWR|O_CREAT, 0640;
+ $bar{'Cathy'} = 456;
+ print "bar-Cathy = $bar{'Cathy'}\n";
+
+=head1 THINKING OF CODE REUSE
+
+One strength of Object-Oriented languages is the ease with which old code
+can use new code. The following examples will demonstrate first how one can
+hinder code reuse and then how one can promote code reuse.
+
+This first example illustrates a class which uses a fully-qualified method
+call to access the "private" method BAZ(). The second example will show
+that it is impossible to override the BAZ() method.
+
+ package FOO;
+
+ sub new { bless {} }
+ sub bar {
+ my $self = shift;
+ $self->FOO::private::BAZ;
+ }
+
+ package FOO::private;
+
+ sub BAZ {
+ print "in BAZ\n";
+ }
+
+ package main;
+
+ $a = FOO->new;
+ $a->bar;
+
+Now we try to override the BAZ() method. We would like FOO::bar() to call
+GOOP::BAZ(), but this cannot happen since FOO::bar() explicitly calls
+FOO::private::BAZ().
+
+ package FOO;
+
+ sub new { bless {} }
+ sub bar {
+ my $self = shift;
+ $self->FOO::private::BAZ;
+ }
+
+ package FOO::private;
+
+ sub BAZ {
+ print "in BAZ\n";
+ }
+
+ package GOOP;
+ @ISA = qw( FOO );
+ sub new { bless {} }
+
+ sub BAZ {
+ print "in GOOP::BAZ\n";
+ }
+
+ package main;
+
+ $a = GOOP->new;
+ $a->bar;
+
+To create reusable code we must modify class FOO, flattening class
+FOO::private. The next example shows a reusable class FOO which allows the
+method GOOP::BAZ() to be used in place of FOO::BAZ().
+
+ package FOO;
+
+ sub new { bless {} }
+ sub bar {
+ my $self = shift;
+ $self->BAZ;
+ }
+
+ sub BAZ {
+ print "in BAZ\n";
+ }
+
+ package GOOP;
+ @ISA = qw( FOO );
+
+ sub new { bless {} }
+ sub BAZ {
+ print "in GOOP::BAZ\n";
+ }
+
+ package main;
+
+ $a = GOOP->new;
+ $a->bar;
+
+=head1 CLASS CONTEXT AND THE OBJECT
+
+Use the object to solve package and class context problems. Everything a
+method needs should be available via the object or should be passed as a
+parameter to the method.
+
+A class will sometimes have static or global data to be used by the
+methods. A subclass may want to override that data and replace it with new
+data. When this happens the superclass may not know how to find the new
+copy of the data.
+
+This problem can be solved by using the object to define the context of the
+method. Let the method look in the object for a reference to the data. The
+alternative is to force the method to go hunting for the data ("Is it in my
+class, or in a subclass? Which subclass?"), and this can be inconvenient
+and will lead to hackery. It is better to just let the object tell the
+method where that data is located.
+
+ package Bar;
+
+ %fizzle = ( 'Password' => 'XYZZY' );
+
+ sub new {
+ my $self = {};
+ $self->{'fizzle'} = \%fizzle;
+ bless $self;
+ }
+
+ sub enter {
+ my $self = shift;
+
+ # Don't try to guess if we should use %Bar::fizzle
+ # or %Foo::fizzle. The object already knows which
+ # we should use, so just ask it.
+ #
+ my $fizzle = $self->{'fizzle'};
+
+ print "The word is ", $fizzle->{'Password'}, "\n";
+ }
+
+ package Foo;
+ @ISA = qw( Bar );
+
+ %fizzle = ( 'Password' => 'Rumple' );
+
+ sub new {
+ my $self = Bar->new;
+ $self->{'fizzle'} = \%fizzle;
+ bless $self;
+ }
+
+ package main;
+
+ $a = Bar->new;
+ $b = Foo->new;
+ $a->enter;
+ $b->enter;
+
diff --git a/pod/perlcall.pod b/pod/perlcall.pod
new file mode 100644
index 0000000000..d81ee4a9ec
--- /dev/null
+++ b/pod/perlcall.pod
@@ -0,0 +1,838 @@
+=head1 NAME
+
+perlcall - Perl calling conventions from C
+
+=head1 DESCRIPTION
+
+B<WARNING : This document is still under construction.
+There are bound to be a number of inaccuracies, so tread very carefully for now.>
+
+The purpose of this document is to show you how to write I<callbacks>,
+i.e. how to call Perl from C. The main
+focus is on how to interface back to Perl from a bit of C code that has itself
+been run by Perl, i.e. the 'main' program is a Perl script; you are using it
+to execute
+a section of code written in C; that bit of C code wants you to do something
+with a particular event, so you want a Perl sub to be executed whenever it
+happens.
+
+Examples where this is necessary include
+
+=over 5
+
+=item *
+
+You have created an XSUB interface to an application's C API.
+
+A fairly common feature in applications is to allow you to define a C
+function that will get called whenever something nasty occurs.
+What we would like is for a Perl sub to be called instead.
+
+=item *
+
+The classic example of where callbacks are used is in an event driven program
+like for X-windows.
+In this case your register functions to be called whenever a specific events
+occur, e.g. a mouse button is pressed.
+
+=back
+
+Although the techniques described are applicable to embedding Perl
+in a C program, this is not the primary goal of this document. For details
+on embedding Perl in C refer to L<perlembed> (currently unwritten).
+
+Before you launch yourself head first into the rest of this document, it would
+be a good idea to have read the following two documents - L<perlapi> and L<perlguts>.
+
+This stuff is easier to explain using examples. But first here are a few
+definitions anyway.
+
+=head2 Definitions
+
+Perl has a number of C functions which allow you to call Perl subs. They are
+
+ I32 perl_call_sv(SV* sv, I32 flags) ;
+ I32 perl_call_pv(char *subname, I32 flags) ;
+ I32 perl_call_method(char *methname, I32 flags) ;
+ I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;
+
+The key function is I<perl_call_sv>. All the other functions make use of
+I<perl_call_sv> to do what they do.
+
+I<perl_call_sv> takes two parameters, the first is an SV*. This allows you to
+specify the Perl sub to be called either as a C string (which has first been
+converted to an SV) or a reference to a
+sub. Example 7, shows you how you can make use of I<perl_call_sv>.
+The second parameter, C<flags>, is a general purpose option command.
+This parameter is common to all the I<perl_call_*> functions.
+It is discussed in the next section.
+
+The function, I<perl_call_pv>, is similar as I<perl_call_sv> except it
+expects it's first parameter has to be a C char* which identifies the Perl
+sub you want to call, e.g. C<perl_call_pv("fred", 0)>.
+
+The function I<perl_call_method> expects its first argument to contain a
+blessed reference to a class. Using that reference it looks up and calls C<methname>
+from that class. See example 9.
+
+I<perl_call_argv> calls the Perl sub specified by the C<subname> parameter.
+It also takes the usual C<flags> parameter.
+The final parameter, C<argv>, consists of a
+list of C strings to be sent to the Perl sub. See example 8.
+
+All the functions return a number. This is a count of the number of items
+returned by the Perl sub on the stack.
+
+As a general rule you should I<always> check the return value from these
+functions.
+Even if you are only expecting a particular number of values to be returned
+from the Perl sub, there is nothing to stop someone from doing something
+unexpected - don't say you havn't been warned.
+
+=head2 Flag Values
+
+The C<flags> parameter in all the I<perl_call_*> functions consists of any
+combination of the symbols defined below, OR'ed together.
+
+=over 5
+
+=item G_SCALAR
+
+Calls the Perl sub in a scalar context.
+
+Whatever the Perl sub actually returns, we only want a scalar. If the perl sub
+does return a scalar, the return value from the I<perl_call_*> function
+will be 1 or 0. If 1, then the value actually returned by the Perl sub will
+be contained
+on the top of the stack.
+If 0, then the sub has probably called I<die> or you have
+used the G_DISCARD flag.
+
+If the Perl sub returns a list, the I<perl_call_*> function will still
+only return 1 or 0. If 1, then the number of elements in the list
+will be stored on top of the stack.
+The actual values of the list will not be accessable.
+
+
+G_SCALAR is the default flag setting for all the functions.
+
+=item G_ARRAY
+
+Calls the Perl sub in a list context.
+
+The return code from the I<perl_call_*> functions will indicate how
+many elements of the stack are used to store the array.
+
+=item G_DISCARD
+
+If you are not interested in the values returned by the Perl sub then setting
+this flag will make Perl get rid of them automatically for you. This will take
+precedence to either G_SCALAR or G_ARRAY.
+
+If you do
+not set this flag then you may need to explicitly get rid of temporary values.
+See example 3 for details.
+
+=item G_NOARGS
+
+If you are not passing any parameters to the Perl sub, you can save a bit of
+time by setting this flag. It has the effect of of not creating the C<@_> array
+for the Perl sub.
+
+A point worth noting is that if this flag is specified the Perl sub called can
+still access an C<@_> array from a previous Perl sub.
+This functionality can be illustrated with the perl code below
+
+ sub fred
+ { print "@_\n" }
+
+ sub joe
+ { &fred }
+
+ &joe(1,2,3) ;
+
+This will print
+
+ 1 2 3
+
+What has happened is that C<fred> accesses the C<@_> array which belongs to C<joe>.
+
+=item G_EVAL
+
+If the Perl sub you are calling has the ability to terminate
+abnormally, e.g. by calling I<die> or by not actually existing, and
+you want to catch this type of event, specify this flag setting. It will put
+an I<eval { }> around the sub call.
+
+Whenever control returns from the I<perl_call_*> function you need to
+check the C<$@> variable as you would in a normal Perl script.
+See example 6 for details of how to do this.
+
+
+=back
+
+
+=head1 EXAMPLES
+
+Enough of the definition talk, let's have a few examples.
+
+Perl provides many macros to assist in accessing the Perl stack.
+These macros should always be used when interfacing to Perl internals.
+Hopefully this should make the code less vulnerable to changes made to
+Perl in the future.
+
+Another point worth noting is that in the first series of examples I have
+only made use of the I<perl_call_pv> function.
+This has only been done to ease you into the
+topic. Wherever possible, if the choice is between using I<perl_call_pv>
+and I<perl_call_sv>, I would always try to use I<perl_call_sv>.
+
+The code for these examples is stored in the file F<perlcall.tar>.
+(Once this document settles down, all the example code will be available in the file).
+
+=head2 Example1: No Parameters, Nothing returned
+
+This first trivial example will call a Perl sub, I<PrintUID>, to print
+out the UID of the process.
+
+ sub PrintUID
+ {
+ print "UID is $<\n" ;
+ }
+
+and here is the C to call it
+
+ void
+ call_PrintUID()
+ {
+ dSP ;
+
+ PUSHMARK(sp) ;
+ perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
+ }
+
+Simple, eh.
+
+A few points to note about this example.
+
+=over 5
+
+=item 1.
+
+We aren't passing any parameters to I<PrintUID> so G_NOARGS
+can be specified.
+
+=item 2.
+
+Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in the next
+example.
+
+=item 3.
+
+We aren't interested in anything returned from I<PrintUID>, so
+G_DISCARD is specified. Even if I<PrintUID> was changed to actually
+return some value(s), having specified G_DISCARD will mean that they
+will be wiped by the time control returns from I<perl_call_pv>.
+
+=item 4.
+
+Because we specified G_DISCARD, it is not necessary to check
+the value returned from I<perl_call_sv>. It will always be 0.
+
+=item 5.
+
+As I<perl_call_pv> is being used, the Perl sub is specified as a C string.
+
+=back
+
+=head2 Example 2: Passing Parameters
+
+Now let's make a slightly more complex example. This time we want
+to call a Perl sub
+which will take 2 parameters - a string (C<$s>) and an integer (C<$n>).
+The sub will simply print the first C<$n> characters of the string.
+
+So the Perl sub would look like this
+
+ sub LeftString
+ {
+ my($s, $n) = @_ ;
+ print substr($s, 0, $n), "\n" ;
+ }
+
+The C function required to call I<LeftString> would look like this.
+
+ static void
+ call_LeftString(a, b)
+ char * a ;
+ int b ;
+ {
+ dSP ;
+
+ PUSHMARK(sp) ;
+ XPUSHs(sv_2mortal(newSVpv(a, 0)));
+ XPUSHs(sv_2mortal(newSViv(b)));
+ PUTBACK ;
+
+ perl_call_pv("LeftString", G_DISCARD);
+ }
+
+
+Here are a few notes on the C function I<call_LeftString>.
+
+=over 5
+
+=item 1.
+
+The only flag specified this time is G_DISCARD. As we are passing 2
+parameters to the Perl sub this time, we have not specified G_NOARGS.
+
+=item 2.
+
+Parameters are passed to the Perl sub using the Perl stack.
+This is the purpose of the code beginning with the line C<dSP> and ending
+with the line C<PUTBACK>.
+
+
+=item 3.
+
+If you are going to put something onto the Perl stack, you need to know
+where to put it. This is the purpose of the macro C<dSP> -
+it declares and initialises a local copy of the Perl stack pointer.
+
+All the other macros which will be used in this example require you to
+have used this macro.
+
+If you are calling a Perl sub directly from an XSUB function, it is
+not necessary to explicitly use the C<dSP> macro - it will be declared for you.
+
+=item 4.
+
+Any parameters to be pushed onto the stack should be bracketed by the
+C<PUSHMARK> and C<PUTBACK> macros.
+The purpose of these two macros, in this context, is to automatically count
+the number of parameters you are pushing. Then whenever Perl is creating
+the C<@_> array for the sub, it knows how big to make it.
+
+The C<PUSHMARK> macro tells Perl to make a mental note of the current stack
+pointer. Even if you aren't passing any parameters (like in Example 1) you must
+still call the C<PUSHMARK> macro before you can call any of
+the I<perl_call_*> functions - Perl still needs to know that there are
+no parameters.
+
+The C<PUTBACK> macro sets the global copy of the stack pointer to be the
+same as our local copy. If we didn't do this I<perl_call_pv> wouldn't
+know where the two parameters we pushed were - remember that up to now
+all the stack pointer manipulation we have done is with our local copy,
+I<not> the global copy.
+
+=item 5.
+
+Next, we come to XPUSHs. This is where the parameters actually get
+pushed onto the stack. In this case we are pushing a string and an integer.
+
+See the section I<XSUB's AND THE ARGUMENT STACK> in L<perlguts> for
+details on how the XPUSH macros work.
+
+=item 6.
+
+Finally, I<LeftString> can now be called via the I<perl_call_pv> function.
+
+=back
+
+=head2 Example 3: Returning a Scalar
+
+Now for an example of dealing with the values returned from a Perl sub.
+
+Here is a Perl sub, I<Adder>, which takes 2 integer parameters and simply
+returns their sum.
+
+ sub Adder
+ {
+ my($a, $b) = @_ ;
+ $a + $b ;
+ }
+
+As we are now concerned with the return value from I<Adder>, the C function
+is now a bit more complex.
+
+ static void
+ call_Adder(a, b)
+ int a ;
+ int b ;
+ {
+ dSP ;
+ int count ;
+
+ ENTER ;
+ SAVETMPS;
+
+ PUSHMARK(sp) ;
+ XPUSHs(sv_2mortal(newSViv(a)));
+ XPUSHs(sv_2mortal(newSViv(b)));
+ PUTBACK ;
+
+ count = perl_call_pv("Adder", G_SCALAR);
+
+ SPAGAIN ;
+
+ if (count != 1)
+ croak("Big trouble\n") ;
+
+ printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
+
+ PUTBACK ;
+ FREETMPS ;
+ LEAVE ;
+ }
+
+
+Points to note this time are
+
+=over 5
+
+=item 1.
+
+The only flag specified this time was G_SCALAR. That means the @_ array
+will be created and that the value returned by I<Adder> will still
+exist after the call to I<perl_call_pv>.
+
+
+
+=item 2.
+
+Because we are interested in what is returned from I<Adder> we cannot specify
+G_DISCARD. This means that we will have to tidy up the Perl stack and dispose
+of any temporary values ourselves. This is the purpose of
+
+ ENTER ;
+ SAVETMPS ;
+
+at the start of the function, and
+
+ FREETMPS ;
+ LEAVE ;
+
+at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
+temporaries we create.
+This means that the temporaries we get rid of will be limited to those which
+were created after these calls.
+
+The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by the Perl
+sub, plus it will also dump the mortal SV's we created.
+Having C<ENTER>/C<SAVETMPS> at the beginning
+of the code makes sure that no other mortals are destroyed.
+
+=item 3.
+
+The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
+stack pointer. This is necessary because it is possible that the memory
+allocated to the Perl stack has been re-allocated whilst in the I<perl_call_pv>
+call.
+
+If you are making use of the Perl stack pointer in your code you must always
+refresh the your local copy using SPAGAIN whenever you make use of
+of the I<perl_call_*> functions or any other Perl internal function.
+
+=item 4.
+
+Although only a single value was expected to be returned from I<Adder>, it is
+still good practice to check the return code from I<perl_call_pv> anyway.
+
+Expecting a single value is not quite the same as knowing that there will
+be one. If someone modified I<Adder> to return a list and we didn't check
+for that possibility and take appropriate action the Perl stack would end
+up in an inconsistant state. That is something you I<really> don't want
+to ever happen.
+
+=item 5.
+
+The C<POPi> macro is used here to pop the return value from the stack. In this
+case we wanted an integer, so C<POPi> was used.
+
+
+Here is the complete list of POP macros available, along with the types they
+return.
+
+ POPs SV
+ POPp pointer
+ POPn double
+ POPi integer
+ POPl long
+
+=item 6.
+
+The final C<PUTBACK> is used to leave the Perl stack in a consistant state
+before exiting the function. This is
+necessary because when we popped the return value from the stack with C<POPi> it
+only updated our local copy of the stack pointer. Remember, C<PUTBACK> sets the
+global stack pointer to be the same as our local copy.
+
+=back
+
+
+=head2 Example 4: Returning a list of values
+
+Now, let's extend the previous example to return both the sum of the parameters
+and the difference.
+
+Here is the Perl sub
+
+ sub AddSubtract
+ {
+ my($a, $b) = @_ ;
+ ($a+$b, $a-$b) ;
+ }
+
+
+and this is the C function
+
+ static void
+ call_AddSubtract(a, b)
+ int a ;
+ int b ;
+ {
+ dSP ;
+ int count ;
+
+ ENTER ;
+ SAVETMPS;
+
+ PUSHMARK(sp) ;
+ XPUSHs(sv_2mortal(newSViv(a)));
+ XPUSHs(sv_2mortal(newSViv(b)));
+ PUTBACK ;
+
+ count = perl_call_pv("AddSubtract", G_ARRAY);
+
+ SPAGAIN ;
+
+ if (count != 2)
+ croak("Big trouble\n") ;
+
+ printf ("%d - %d = %d\n", a, b, POPi) ;
+ printf ("%d + %d = %d\n", a, b, POPi) ;
+
+ PUTBACK ;
+ FREETMPS ;
+ LEAVE ;
+ }
+
+
+Notes
+
+=over 5
+
+=item 1.
+
+We wanted array context, so we used G_ARRAY.
+
+=item 2.
+
+Not surprisingly there are 2 POPi's this time because we were retrieving 2
+values from the stack. The main point to note is that they came off the stack in
+reverse order.
+
+=back
+
+=head2 Example 5: Returning Data from Perl via the parameter list
+
+It is also possible to return values directly via the parameter list -
+whether it is actually desirable to do it is another matter entirely.
+
+The Perl sub, I<Inc>, below takes 2 parameters and increments each.
+
+ sub Inc
+ {
+ ++ $_[0] ;
+ ++ $_[1] ;
+ }
+
+and here is a C function to call it.
+
+ static void
+ call_Inc(a, b)
+ int a ;
+ int b ;
+ {
+ dSP ;
+ int count ;
+ SV * sva ;
+ SV * svb ;
+
+ ENTER ;
+ SAVETMPS;
+
+ sva = sv_2mortal(newSViv(a)) ;
+ svb = sv_2mortal(newSViv(b)) ;
+
+ PUSHMARK(sp) ;
+ XPUSHs(sva);
+ XPUSHs(svb);
+ PUTBACK ;
+
+ count = perl_call_pv("Inc", G_DISCARD);
+
+ if (count != 0)
+ croak ("call_Inc : expected 0 return value from 'Inc', got %d\n", count) ;
+
+ printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
+ printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
+
+ FREETMPS ;
+ LEAVE ;
+ }
+
+
+
+To be able to access the two parameters that were pushed onto the stack
+after they return from I<perl_call_pv> it is necessary to make a note of
+their addresses - thus the two variables C<sva> and C<svb>.
+
+The reason this is necessary is that
+the area of the Perl stack which held them
+will very likely have been overwritten by something else by the time control
+returns from I<perl_call_pv>.
+
+
+
+
+=head2 Example 6: Using G_EVAL
+
+Now an example using G_EVAL. Below is a Perl sub which computes the
+difference of its 2 parameters. If this would result in a negative result,
+the sub calls I<die>.
+
+
+ sub Subtract
+ {
+ my ($a, $b) = @_ ;
+
+ die "death can be fatal\n" if $a < $b ;
+
+ $a - $b ;
+ }
+
+and some C to call it
+
+ static void
+ call_Subtract(a, b)
+ int a ;
+ int b ;
+ {
+ dSP ;
+ int count ;
+ SV * sv ;
+
+ ENTER ;
+ SAVETMPS;
+
+ PUSHMARK(sp) ;
+ XPUSHs(sv_2mortal(newSViv(a)));
+ XPUSHs(sv_2mortal(newSViv(b)));
+ PUTBACK ;
+
+ count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);
+
+ /* Check the eval first */
+ sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
+ if (SvTRUE(sv))
+ printf ("Uh oh - %s\n", SvPV(sv, na)) ;
+
+ SPAGAIN ;
+
+ if (count != 1)
+ croak ("call_Subtract : expected 1 return value from 'Subtract', got %d\n", count) ;
+
+
+ printf ("%d - %d = %d\n", a, b, POPi) ;
+
+ PUTBACK ;
+ FREETMPS ;
+ LEAVE ;
+
+ }
+
+If I<call_Subtract> is called thus
+
+ call_Subtract(4, 5)
+
+the following will be printed
+
+ Uh oh - death can be fatal
+
+Notes
+
+=over 5
+
+=item 1.
+
+We want to be able to catch the I<die> so we have used the G_EVAL flag.
+Not specifying this flag would mean that the program would terminate.
+
+=item 2.
+
+The code
+
+ sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
+ if (SvTRUE(sv))
+ printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
+
+is the equivalent of this bit of Perl
+
+ print "Uh oh - $@\n" if $@ ;
+
+
+
+=back
+
+
+=head2 Example 7: Using perl_call_sv
+
+In all the previous examples I have 'hard-wried' the name of the Perl sub to
+be called from C.
+Sometimes though, it is necessary to be able to specify the name
+of the Perl sub from within the Perl script.
+
+Consider the Perl code below
+
+ sub fred
+ {
+ print "Hello there\n" ;
+ }
+
+ CallSub("fred") ;
+
+
+here is a snippet of XSUB which defines I<CallSub>.
+
+ void
+ CallSub(name)
+ char * name
+ CODE:
+ PUSHMARK(sp) ;
+ perl_call_pv(name, G_DISCARD|G_NOARGS) ;
+
+That is fine as far as it goes. The thing is, it only allows the Perl sub to be
+specified as a string.
+For perl 4 this was adequate, but Perl 5 allows references to
+subs and anonymous subs. This is where I<perl_call_sv> is useful.
+
+The code below for I<CallSub> is identical to the previous time except that the
+C<name> parameter is now defined as an SV* and we use I<perl_call_sv> instead of
+I<perl_call_pv>.
+
+ void
+ CallSub(name)
+ SV* name
+ CODE:
+ PUSHMARK(sp) ;
+ perl_call_sv(name, G_DISCARD|G_NOARGS) ;
+
+As we are using an SV to call I<fred> the following can all be used
+
+ CallSub("fred") ;
+ Callsub(\&fred) ;
+ $ref = \&fred ;
+ CallSub($ref) ;
+ CallSub( sub { print "Hello there\n" } ) ;
+
+As you can see, I<perl_call_sv> gives you greater flexibility in how you
+can specify the Perl sub.
+
+=head2 Example 8: Using perl_call_argv
+
+Here is a Perl sub which prints whatever parameters are passed to it.
+
+ sub PrintList
+ {
+ my(@list) = @_ ;
+
+ foreach (@list) { print "$_\n" }
+ }
+
+and here is an example of I<perl_call_argv> which will call I<PrintList>.
+
+ call_PrintList
+ {
+ dSP ;
+ char * words[] = {"alpha", "beta", "gamma", "delta", NULL } ;
+
+ perl_call_argv("PrintList", words, G_DISCARD) ;
+ }
+
+Note that it is not necessary to call C<PUSHMARK> in this instance. This is
+because I<perl_call_argv> will do it for you.
+
+=head2 Example 9: Using perl_call_method
+
+[This section is under construction]
+
+Consider the following Perl code
+
+ {
+ package Mine ;
+
+ sub new { bless [@_] }
+ sub Display { print $_[0][1], "\n" }
+ }
+
+ $a = new Mine ('red', 'green', 'blue') ;
+ call_Display($a, 'Display') ;
+
+The method C<Display> just prints out the first element of the list.
+Here is a XSUB implementation of I<call_Display>.
+
+ void
+ call_Display(ref, method)
+ SV * ref
+ char * method
+ CODE:
+ PUSHMARK(sp);
+ XPUSHs(ref);
+ PUTBACK;
+
+ perl_call_method(method, G_DISCARD) ;
+
+
+
+
+=head2 Strategies for storing Context Information
+
+[This section is under construction]
+
+One of the trickiest problems to overcome when designing a callback interface
+is figuring
+out how to store the mapping between the C callback functions and the
+Perl equivalent.
+
+Consider the following example.
+
+=head2 Alternate Stack Manipulation
+
+[This section is under construction]
+
+Although I have only made use of the POP* macros to access values returned
+from Perl subs, it is also possible to bypass these macros and read the
+stack directly.
+
+The code below is example 4 recoded to
+
+=head1 SEE ALSO
+
+L<perlapi>, L<perlguts>, L<perlembed>
+
+=head1 AUTHOR
+
+Paul Marquess <pmarquess@bfsec.bt.co.uk>
+
+Special thanks to the following people who assisted in the creation of the
+document.
+
+Jeff Okamoto, Tim Bunce.
+
+=head1 DATE
+
+Version 0.4, 17th October 1994
+
+
diff --git a/pod/perldata.pod b/pod/perldata.pod
new file mode 100644
index 0000000000..6b4f7a4053
--- /dev/null
+++ b/pod/perldata.pod
@@ -0,0 +1,408 @@
+=head1 NAME
+
+perldata - Perl data structures
+
+=head1 DESCRIPTION
+
+=head2 Variable names
+
+Perl has three data structures: scalars, arrays of scalars, and
+associative arrays of scalars, known as "hashes". Normal arrays are
+indexed by number, starting with 0. (Negative subscripts count from
+the end.) Hash arrays are indexed by string.
+
+Scalar values are always named with '$', even when referring to a scalar
+that is part of an array. It works like the English word "the". Thus
+we have:
+
+ $days # the simple scalar value "days"
+ $days[28] # the 29th element of array @days
+ $days{'Feb'} # the 'Feb' value from hash %days
+ $#days # the last index of array @days
+
+but entire arrays or array slices are denoted by '@', which works much like
+the word "these" or "those":
+
+ @days # ($days[0], $days[1],... $days[n])
+ @days[3,4,5] # same as @days[3..5]
+ @days{'a','c'} # same as ($days{'a'},$days{'c'})
+
+and entire hashes are denoted by '%':
+
+ %days # (key1, val1, key2, val2 ...)
+
+In addition, subroutines are named with an initial '&', though this is
+optional when it's otherwise unambiguous (just as "do" is often
+redundant in English). Symbol table entries can be named with an
+initial '*', but you don't really care about that yet.
+
+Every variable type has its own namespace. You can, without fear of
+conflict, use the same name for a scalar variable, an array, or a hash
+(or, for that matter, a filehandle, a subroutine name, or a label).
+This means that $foo and @foo are two different variables. It also
+means that $foo[1] is a part of @foo, not a part of $foo. This may
+seem a bit weird, but that's okay, because it is weird.
+
+Since variable and array references always start with '$', '@', or '%',
+the "reserved" words aren't in fact reserved with respect to variable
+names. (They ARE reserved with respect to labels and filehandles,
+however, which don't have an initial special character. You can't have
+a filehandle named "log", for instance. Hint: you could say
+C<open(LOG,'logfile')> rather than C<open(log,'logfile')>. Using uppercase
+filehandles also improves readability and protects you from conflict
+with future reserved words.) Case I<IS> significant--"FOO", "Foo" and
+"foo" are all different names. Names that start with a letter or
+underscore may also contain digits and underscores.
+
+It is possible to replace such an alphanumeric name with an expression
+that returns a reference to an object of that type. For a description
+of this, see L<perlref>.
+
+Names that start with a digit may only contain more digits. Names
+which do not start with a letter, underscore, or digit are limited to
+one character, e.g. "$%" or "$$". (Most of these one character names
+have a predefined significance to Perl. For instance, $$ is the
+current process id.)
+
+=head2 Context
+
+The interpretation of operations and values in Perl sometimes depends
+on the requirements of the context around the operation or value.
+There are two major contexts: scalar and list. Certain operations
+return list values in contexts wanting a list, and scalar values
+otherwise. (If this is true of an operation it will be mentioned in
+the documentation for that operation.) In other words, Perl overloads
+certain operations based on whether the expected return value is
+singular or plural. (Some words in English work this way, like "fish"
+and "sheep".)
+
+In a reciprocal fashion, an operation provides either a scalar or a
+list context to each of its arguments. For example, if you say
+
+ int( <STDIN> )
+
+the integer operation provides a scalar context for the <STDIN>
+operator, which responds by reading one line from STDIN and passing it
+back to the integer operation, which will then find the integer value
+of that line and return that. If, on the other hand, you say
+
+ sort( <STDIN> )
+
+then the sort operation provides a list context for <STDIN>, which
+will proceed to read every line available up to the end of file, and
+pass that list of lines back to the sort routine, which will then
+sort those lines and return them as a list to whatever the context
+of the sort was.
+
+Assignment is a little bit special in that it uses its left argument to
+determine the context for the right argument. Assignment to a scalar
+evaluates the righthand side in a scalar context, while assignment to
+an array or array slice evaluates the righthand side in a list
+context. Assignment to a list also evaluates the righthand side in a
+list context.
+
+User defined subroutines may choose to care whether they are being
+called in a scalar or list context, but most subroutines do not
+need to care, because scalars are automatically interpolated into
+lists. See L<perlfunc/wantarray>.
+
+=head2 Scalar values
+
+Scalar variables may contain various kinds of singular data, such as
+numbers, strings and references. In general, conversion from one form
+to another is transparent. (A scalar may not contain multiple values,
+but may contain a reference to an array or hash containing multiple
+values.) Because of the automatic conversion of scalars, operations and
+functions that return scalars don't need to care (and, in fact, can't
+care) whether the context is looking for a string or a number.
+
+A scalar value is interpreted as TRUE in the Boolean sense if it is not
+the null string or the number 0 (or its string equivalent, "0"). The
+Boolean context is just a special kind of scalar context.
+
+There are actually two varieties of null scalars: defined and
+undefined. Undefined null scalars are returned when there is no real
+value for something, such as when there was an error, or at end of
+file, or when you refer to an uninitialized variable or element of an
+array. An undefined null scalar may become defined the first time you
+use it as if it were defined, but prior to that you can use the
+defined() operator to determine whether the value is defined or not.
+
+The length of an array is a scalar value. You may find the length of
+array @days by evaluating C<$#days>, as in B<csh>. (Actually, it's not
+the length of the array, it's the subscript of the last element, since
+there is (ordinarily) a 0th element.) Assigning to C<$#days> changes the
+length of the array. Shortening an array by this method destroys
+intervening values. Lengthening an array that was previously shortened
+I<NO LONGER> recovers the values that were in those elements. (It used to
+in Perl 4, but we had to break this make to make sure destructors were
+called when expected.) You can also gain some measure of efficiency by
+preextending an array that is going to get big. (You can also extend
+an array by assigning to an element that is off the end of the array.)
+You can truncate an array down to nothing by assigning the null list ()
+to it. The following are equivalent:
+
+ @whatever = ();
+ $#whatever = $[ - 1;
+
+If you evaluate a named array in a scalar context, it returns the length of
+the array. (Note that this is not true of lists, which return the
+last value, like the C comma operator.) The following is always true:
+
+ scalar(@whatever) == $#whatever - $[ + 1;
+
+Version 5 of Perl changed the semantics of $[: files that don't set
+the value of $[ no longer need to worry about whether another
+file changed its value. (In other words, use of $[ is deprecated.)
+So in general you can just assume that
+
+ scalar(@whatever) == $#whatever + 1;
+
+If you evaluate a hash in a scalar context, it returns a value which is
+true if and only if the hash contains any key/value pairs. (If there
+are any key/value pairs, the value returned is a string consisting of
+the number of used buckets and the number of allocated buckets, separated
+by a slash. This is pretty much only useful to find out whether Perl's
+(compiled in) hashing algorithm is performing poorly on your data set.
+For example, you stick 10,000 things in a hash, but evaluating %HASH in
+scalar context reveals "1/16", which means only one out of sixteen buckets
+has been touched, and presumably contains all 10,000 of your items. This
+isn't supposed to happen.)
+
+=head2 Scalar value constructors
+
+Numeric literals are specified in any of the customary floating point or
+integer formats:
+
+
+ 12345
+ 12345.67
+ .23E-10
+ 0xffff # hex
+ 0377 # octal
+ 4_294_967_296 # underline for legibility
+
+String literals are delimited by either single or double quotes. They
+work much like shell quotes: double-quoted string literals are subject
+to backslash and variable substitution; single-quoted strings are not
+(except for "C<\'>" and "C<\\>"). The usual Unix backslash rules apply for making
+characters such as newline, tab, etc., as well as some more exotic
+forms. See L<perlop/qq> for a list.
+
+You can also embed newlines directly in your strings, i.e. they can end
+on a different line than they begin. This is nice, but if you forget
+your trailing quote, the error will not be reported until Perl finds
+another line containing the quote character, which may be much further
+on in the script. Variable substitution inside strings is limited to
+scalar variables, arrays, and array slices. (In other words,
+identifiers beginning with $ or @, followed by an optional bracketed
+expression as a subscript.) The following code segment prints out "The
+price is $100."
+
+ $Price = '$100'; # not interpreted
+ print "The price is $Price.\n"; # interpreted
+
+As in some shells, you can put curly brackets around the identifier to
+delimit it from following alphanumerics. Also note that a
+single-quoted string must be separated from a preceding word by a
+space, since single quote is a valid (though discouraged) character in
+an identifier (see L<perlmod/Packages>).
+
+Two special literals are __LINE__ and __FILE__, which represent the
+current line number and filename at that point in your program. They
+may only be used as separate tokens; they will not be interpolated into
+strings. In addition, the token __END__ may be used to indicate the
+logical end of the script before the actual end of file. Any following
+text is ignored, but may be read via the DATA filehandle. (The DATA
+filehandle may read data only from the main script, but not from any
+required file or evaluated string.) The two control characters ^D and
+^Z are synonyms for __END__.
+
+A word that doesn't have any 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
+such words. Some people may wish to outlaw barewords entirely. If you
+say
+
+ use strict 'subs';
+
+then any bareword that would NOT be interpreted as a subroutine call
+produces a compile-time error instead. The restriction lasts to the
+end of the enclosing block. An inner block may countermand this
+by saying C<no strict 'subs'>.
+
+Array variables are interpolated into double-quoted strings by joining all
+the elements of the array with the delimiter specified in the C<$">
+variable, space by default. The following are equivalent:
+
+ $temp = join($",@ARGV);
+ system "echo $temp";
+
+ system "echo @ARGV";
+
+Within search patterns (which also undergo double-quotish substitution)
+there is a bad ambiguity: Is C</$foo[bar]/> to be interpreted as
+C</${foo}[bar]/> (where C<[bar]> is a character class for the regular
+expression) or as C</${foo[bar]}/> (where C<[bar]> is the subscript to array
+@foo)? If @foo doesn't otherwise exist, then it's obviously a
+character class. If @foo exists, Perl takes a good guess about C<[bar]>,
+and is almost always right. If it does guess wrong, or if you're just
+plain paranoid, you can force the correct interpretation with curly
+brackets as above.
+
+A line-oriented form of quoting is based on the shell "here-doc" syntax.
+Following a C<E<lt>E<lt>> you specify a string to terminate the quoted material,
+and all lines following the current line down to the terminating string
+are the value of the item. The terminating string may be either an
+identifier (a word), or some quoted text. If quoted, the type of
+quotes you use determines the treatment of the text, just as in regular
+quoting. An unquoted identifier works like double quotes. There must
+be no space between the C<E<lt>E<lt>> and the identifier. (If you put a space it
+will be treated as a null identifier, which is valid, and matches the
+first blank line--see the Merry Christmas example below.) The terminating
+string must appear by itself (unquoted and with no surrounding
+whitespace) on the terminating line.
+
+ print <<EOF; # same as above
+ The price is $Price.
+ EOF
+
+ print <<"EOF"; # same as above
+ The price is $Price.
+ EOF
+
+ print << x 10; # Legal but discouraged. Use <<"".
+ Merry Christmas!
+
+ print <<`EOC`; # execute commands
+ echo hi there
+ echo lo there
+ EOC
+
+ print <<"foo", <<"bar"; # you can stack them
+ I said foo.
+ foo
+ I said bar.
+ bar
+
+ myfunc(<<"THIS", 23, <<'THAT'');
+ Here's a line
+ or two.
+ THIS
+ and here another.
+ THAT
+
+Just don't forget that you have to put a semicolon on the end
+to finish the statement, as Perl doesn't know you're not going to
+try to do this:
+
+ print <<ABC
+ 179231
+ ABC
+ + 20;
+
+
+=head2 List value constructors
+
+List values are denoted by separating individual values by commas
+(and enclosing the list in parentheses where precedence requires it):
+
+ (LIST)
+
+In a context not requiring an list value, the value of the list
+literal is the value of the final element, as with the C comma operator.
+For example,
+
+ @foo = ('cc', '-E', $bar);
+
+assigns the entire list value to array foo, but
+
+ $foo = ('cc', '-E', $bar);
+
+assigns the value of variable bar to variable foo. Note that the value
+of an actual array in a scalar context is the length of the array; the
+following assigns to $foo the value 3:
+
+ @foo = ('cc', '-E', $bar);
+ $foo = @foo; # $foo gets 3
+
+You may have an optional comma before the closing parenthesis of an
+list literal, so that you can say:
+
+ @foo = (
+ 1,
+ 2,
+ 3,
+ );
+
+LISTs do automatic interpolation of sublists. That is, when a LIST is
+evaluated, each element of the list is evaluated in a list context, and
+the resulting list value is interpolated into LIST just as if each
+individual element were a member of LIST. Thus arrays lose their
+identity in a LIST--the list
+
+ (@foo,@bar,&SomeSub)
+
+contains all the elements of @foo followed by all the elements of @bar,
+followed by all the elements returned by the subroutine named SomeSub.
+To make a list reference that does I<NOT> interpolate, see L<perlref>.
+
+The null list is represented by (). Interpolating it in a list
+has no effect. Thus ((),(),()) is equivalent to (). Similarly,
+interpolating an array with no elements is the same as if no
+array had been interpolated at that point.
+
+A list value may also be subscripted like a normal array. You must
+put the list in parentheses to avoid ambiguity. Examples:
+
+ # Stat returns list value.
+ $time = (stat($file))[8];
+
+ # Find a hex digit.
+ $hexdigit = ('a','b','c','d','e','f')[$digit-10];
+
+ # A "reverse comma operator".
+ return (pop(@foo),pop(@foo))[0];
+
+Lists may be assigned to if and only if each element of the list
+is legal to assign to:
+
+ ($a, $b, $c) = (1, 2, 3);
+
+ ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
+
+The final element may be an array or a hash:
+
+ ($a, $b, @rest) = split;
+ local($a, $b, %rest) = @_;
+
+You can actually put an array anywhere in the list, but the first array
+in the list will soak up all the values, and anything after it will get
+a null value. This may be useful in a local() or my().
+
+A hash literal contains pairs of values to be interpreted
+as a key and a value:
+
+ # same as map assignment above
+ %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
+
+It is often more readable to use the C<=E<gt>> operator between key/value pairs
+(the C<=E<gt>> operator is actually nothing more than a more visually
+distinctive synonym for a comma):
+
+ %map = (
+ 'red' => 0x00f,
+ 'blue' => 0x0f0,
+ 'green' => 0xf00,
+ );
+
+Array assignment in a scalar context returns the number of elements
+produced by the expression on the right side of the assignment:
+
+ $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
+
+This is very handy when you want to do a list assignment in a Boolean
+context, since most list functions return a null list when finished,
+which when assigned produces a 0, which is interpreted as FALSE.
diff --git a/pod/perldebug.pod b/pod/perldebug.pod
new file mode 100644
index 0000000000..17fe25926f
--- /dev/null
+++ b/pod/perldebug.pod
@@ -0,0 +1,249 @@
+=head1 NAME
+
+perldebug - Perl debugging
+
+=head1 DESCRIPTION
+
+First of all, have you tried using the B<-w> switch?
+
+=head2 Debugging
+
+If you invoke Perl with a B<-d> switch, your script will be run under the
+debugger. However, the Perl debugger is not a separate program as it is
+in a C environment. Instead, the B<-d> flag tells the compiler to insert
+source information into the pseudocode it's about to hand to the
+interpreter. (That means your code must compile correctly for the
+debugger to work on it.) Then when the interpreter starts up, it
+pre-loads a Perl library file containing the debugger itself. The program
+will halt before the first executable statement (but see below) and ask
+you for one of the following commands:
+
+=over 12
+
+=item h
+
+Prints out a help message.
+
+=item T
+
+Stack trace.
+If you do bizarre things to your @_ arguments in a subroutine, the stack
+backtrace will not always show the original values.
+
+=item s
+
+Single step. Executes until it reaches the beginning of another
+statement.
+
+=item n
+
+Next. Executes over subroutine calls, until it reaches the beginning
+of the next statement.
+
+=item f
+
+Finish. Executes statements until it has finished the current
+subroutine.
+
+=item c
+
+Continue. Executes until the next breakpoint is reached.
+
+=item c line
+
+Continue to the specified line. Inserts a one-time-only breakpoint at
+the specified line.
+
+=item <CR>
+
+Repeat last n or s.
+
+=item l min+incr
+
+List incr+1 lines starting at min. If min is omitted, starts where
+last listing left off. If incr is omitted, previous value of incr is
+used.
+
+=item l min-max
+
+List lines in the indicated range.
+
+=item l line
+
+List just the indicated line.
+
+=item l
+
+List next window.
+
+=item -
+
+List previous window.
+
+=item w line
+
+List window (a few lines worth of code) around line.
+
+=item l subname
+
+List subroutine. If it's a long subroutine it just lists the
+beginning. Use "l" to list more.
+
+=item /pattern/
+
+Regular expression search forward in the source code for pattern; the
+final / is optional.
+
+=item ?pattern?
+
+Regular expression search backward in the source code for pattern; the
+final ? is optional.
+
+=item L
+
+List lines that have breakpoints or actions.
+
+=item S
+
+Lists the names of all subroutines.
+
+=item t
+
+Toggle trace mode on or off.
+
+=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 is
+evaluated each time the statement is reached and 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 33 /pattern/i
+
+=item b subname [ condition ]
+
+Set breakpoint at first executable line of subroutine.
+
+=item d line
+
+Delete breakpoint. If line is omitted, deletes the breakpoint on the
+line that is about to be executed.
+
+=item D
+
+Delete all breakpoints.
+
+=item a line command
+
+Set an action for line. A multiline command may be entered by
+backslashing the newlines. This command is Perl code, not another
+debugger command.
+
+=item A
+
+Delete all line actions.
+
+=item < command
+
+Set an action to happen before every debugger prompt. A multiline
+command may be entered by backslashing the newlines.
+
+=item > command
+
+Set an action to happen after the prompt when you've just given a
+command to return to executing the script. A multiline command may be
+entered by backslashing the newlines.
+
+=item V package [symbols]
+
+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 $) there, just the symbol
+names, like this:
+
+ V DB filename line
+
+=item X [symbols]
+
+Same as as "V" command, but within the current package.
+
+=item ! number
+
+Redo a debugging command. If number is omitted, redoes the previous
+command.
+
+=item ! -number
+
+Redo the command that was that many commands ago.
+
+=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.)
+
+=item command
+
+Execute command as a Perl statement. A missing semicolon will be
+supplied.
+
+=item p expr
+
+Same as C<print DB::OUT expr>. The DB::OUT filehandle is opened to
+/dev/tty, regardless of where STDOUT may be redirected to.
+
+=back
+
+Any command you type in that isn't recognized by the debugger will be
+directly executed (C<eval>'d) as Perl code. Leading white space will
+cause the debugger to think it's C<NOT> a debugger command.
+
+If you have any compile-time executable statements (code within a BEGIN
+block or a C<use> statement), these will I<NOT> be stopped by debugger,
+although C<require>s will. From your own 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;
+
+=head2 Customization
+
+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 environment variable PERL5DB to say something like this:
+
+ BEGIN { require "myperl5db.pl" }
+
+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 in particular most people seem to expect to
+be there):
+
+ $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
+ $DB::alias{'stop'} = 's/^stop (at|in)/b/';
+ $DB::alias{'.'} = 's/^\./p '
+ . '"\$DB::sub(\$DB::filename:\$DB::line):\t"'
+ . ',\$DB::dbline[\$DB::line]/' ;
+
+
+=head2 Other resources
+
+You did try the B<-w> switch, didn't you?
+
+=head1 BUGS
+
+If your program exit()s or die()s, so does the debugger.
+
+There's no builtin way to restart the debugger without exiting and coming back
+into it. You could use an alias like this:
+
+ $DB::alias{'rerun'} = 'exec "perl -d $DB::filename"';
+
+But you'd lose any pending breakpoint information, and that might not
+be the right path, etc.
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
new file mode 100644
index 0000000000..43b0f3f5b8
--- /dev/null
+++ b/pod/perldiag.pod
@@ -0,0 +1,2002 @@
+=head1 NAME
+
+perldiag - various Perl diagnostics
+
+=head1 DESCRIPTION
+
+These messages are classified as follows (listed in increasing order of
+desperation):
+
+ (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 (non-trappable).
+
+Optional warnings are enabled by using the B<-w> switch. Trappable
+errors may be trapped using the eval operator. See L<perlfunc/eval>.
+
+Some of these messages are generic. Spots that vary are denoted with a %s,
+just as in a printf format. Note that some message start with a %s!
+The symbols C<"%-?@> sort before the letters, while C<[> and C<\> sort after.
+
+=over 4
+
+=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 "use" not allowed in expression
+
+(F) The "use" keyword is recognized and executed at compile time, and returns
+no useful value. See L<perlmod>.
+
+=item % may only be used in unpack
+
+(F) You can't pack a string by supplying a checksum, since the
+checksumming process loses information, and you can't go the other
+way. See L<perlfunc/unpack>.
+
+=item %s (...) interpreted as function
+
+(W) 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 parens. See L<perlop/Terms and List Operators (Leftward)>.
+
+=item %s argument is not a HASH element
+
+(F) The argument to delete() or exists() must be a hash element, such as
+
+ $foo{$bar}
+ $ref->[12]->{"susie"}
+
+=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) 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) The symbol in question was declared but somehow went out of scope
+before it could possibly have been used.
+
+=item %s syntax OK
+
+(F) The final summary message when a C<perl -c> succeeds.
+
+=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 ?+* 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 absolution position outside
+the string being unpacked. See L<perlfunc/pack>.
+
+=item accept() on closed fd
+
+(W) 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
+
+(F) You can't allocate more than 64K on an MSDOS machine.
+
+=item Arg too short for msgsnd
+
+(F) msgsnd() requires a string at least as long as sizeof(long).
+
+=item Args must match #! line
+
+(F) The setuid emulator requires that the arguments Perl was invoked
+with match the arguments specified on the #! line.
+
+=item Argument "%s" isn't numeric
+
+(W) 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) Really old Perl let you omit the @ on array names in some spots. This
+is now heavily deprecated.
+
+=item assertion botched: %s
+
+(P) The malloc package that comes with Perl had an internal failure.
+
+=item Assertion failed: file "%s"
+
+(P) A general assertion failed. The file in question must be examined.
+
+=item Assignment to both a list and a scalar
+
+(F) If you assign to a conditional operator, the 2nd and 3rd arguments
+must either both be scalars or both be lists. Otherwise Perl won't
+know which context to supply to the right side.
+
+=item Attempt to free non-arena SV: 0x%lx
+
+(P) 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 temp prematurely
+
+(W) 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
+
+(P) The reference counts got screwed up on symbol aliases.
+
+=item Attempt to free unreferenced scalar
+
+(W) 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 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 sized are, respectively,
+S<sizeof(struct msqid_ds *)>, S<sizeof(struct semid_ds *)> and
+S<sizeof(struct shmid_ds *)>.
+
+=item Bad associative array
+
+(P) One of the internal hash routines was passed a null HV pointer.
+
+=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.
+
+=item Bad free() ignored
+
+(S) An internal routine called free() on something that had never been
+malloc()ed in the first place.
+
+=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
+
+ $var = 'myvar';
+ $sym = mypack::$var;
+
+is not the same as
+
+ $var = 'myvar';
+ $sym = "mypack::$var";
+
+=item Bad symbol for array
+
+(P) An internal request asked to add an array entry to something that
+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.
+
+=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 BEGIN failed--compilation aborted
+
+(F) An untrapped exception was raised while executing a BEGIN subroutine.
+Compilation stops immediately and the interpreter is exited.
+
+=item bind() on closed fd
+
+(W) 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 Callback called exit
+
+(F) A subroutine invoked from an external package via perl_call_sv()
+exited by calling exit.
+
+=item Can't "last" outside a 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. You can usually double the curlies to get the same
+effect though, since the inner curlies will be considered a block
+that loops once. See L<perlfunc/last>.
+
+=item Can't "next" outside a 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. You can usually double the curlies to get
+the same effect though, since the inner curlies will be considered a block
+that loops once. See L<perlfunc/last>.
+
+=item Can't "redo" outside a 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. You can usually double the curlies to get
+the same effect though, since the inner curlies will be considered a block
+that loops once. See L<perlfunc/last>.
+
+=item Can't bless non-reference value
+
+(F) Only hard references may be blessed. This is how Perl "enforces"
+encapsulation of objects. See L<perlobj>.
+
+=item Can't break at that line
+
+(S) A warning intended for 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"
+
+(F) You called a method correctly, and it correctly indicated a package
+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 what package it's supposed to run in. 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 expression that returns
+neither an object reference nor a package name. (Perhaps it's null?)
+Something like this will reproduce the error:
+
+ $BADREF = undef;
+ process $BADREF 1,2,3;
+ $BADREF->process(1,2,3);
+
+=item Can't chdir to %s
+
+(F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory
+that you can chdir to, possibly because it doesn't exist.
+
+=item Can't coerce %s to integer in %s
+
+(F) Certain types of SVs, in particular real symbol table entries
+(type GLOB), can't be forced to stop being what they are. So you can't
+say things like:
+
+ *foo += 1;
+
+You CAN say
+
+ $foo = *foo;
+ $foo += 1;
+
+but then $foo no longer contains a glob.
+
+=item Can't coerce %s to number in %s
+
+(F) Certain types of SVs, in particular real symbol table entries
+(type GLOB), can't be forced to stop being what they are.
+
+=item Can't coerce %s to string in %s
+
+(F) Certain types of SVs, in particular real symbol table entries
+(type GLOB), can't be forced to stop being what they are.
+
+=item Can't create pipe mailbox
+
+(F) An error peculiar to VMS.
+
+=item Can't declare %s in my
+
+(F) Only scalar, array and hash variables may be declared as lexical variables.
+They must have ordinary identifiers as names.
+
+=item Can't do inplace edit on %s: %s
+
+(S) 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 MSDOS that gets confused if you try reading
+from a deleted (but still opened) file. You have to say B<-i>C<.bak>, or some
+such.
+
+=item Can't do inplace edit: %s > 14 characters
+
+(S) There isn't enough room in the filename to make a backup name for the file.
+
+=item Can't do inplace edit: %s is not a regular file
+
+(S) 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 setegid!
+
+(P) The setegid() call failed for some reason in the setuid emulator
+of suidperl.
+
+=item Can't do seteuid!
+
+(P) The setuid emulator of suidperl failed for some reason.
+
+=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.
+
+=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>.
+
+=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.
+
+=item Can't exec "%s": %s
+
+(W) 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.
+
+=item Can't execute %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.
+
+=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 string terminator %s anywhere before EOF
+
+(F) Perl strings can stretch over multiple lines. This message means that
+the closing delimiter was omitted. Since bracketed quotes count nesting
+levels, the following is missing its final parenthesis:
+
+ print q(The character '(' starts a side comment.)
+
+=item Can't fork
+
+(F) A fatal error occurred while trying to fork while opening a pipeline.
+
+=item Can't get pipe mailbox device name
+
+(F) An error peculiar to VMS.
+
+=item Can't get SYSGEN parameter value for MAXBUF
+
+(F) An error peculiar to VMS.
+
+=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 only be calling it out of an AUTOLOAD routine anyway. See
+L<perlfunc/goto>.
+
+=item Can't locate %s in @INC
+
+(F) You said to do (or require, or use) a file that couldn't be found
+in any of the libraries mentioned in @INC. Perhaps you need to set
+the PERL5LIB 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>.
+
+=item Can't locate object method "%s" via package "%s"
+
+(F) You called a method correctly, and it correctly indicated a package
+functioning as a class, but that package doesn't define that particular
+method, nor does any of it's base classes. See L<perlobj>.
+
+=item Can't locate package %s for @%s::ISA
+
+(W) The @ISA array contained the name of another package that doesn't seem
+to exist.
+
+=item Can't mktemp()
+
+(F) The mktemp() routine failed for some reason while trying to process
+a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
+
+=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 autoincrement.
+
+=item Can't modify non-existent substring
+
+(P) The internal routine that does assignment to a substr() was handed
+a NULL.
+
+=item Can't msgrcv to readonly var
+
+(F) The target of a msgrcv must be modifiable in order to be used as a receive
+buffer.
+
+=item Can't open %s: %s
+
+(S) An inplace edit couldn't open the original file for the indicated reason.
+Usually this is because you don't have read permission for the file.
+
+=item Can't open bidirectional pipe
+
+(W) 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
+"open2.pl". Alternately, direct the pipe's output to a file using ">",
+and then read it in under a different file handle.
+
+=item Can't open perl script "%s": %s
+
+(F) The script you specified can't be opened for the indicated reason.
+
+=item Can't rename %s to %s: %s, skipping file
+
+(S) The rename done by the B<-i> switch failed for some reason, probably because
+you don't have write permission to the directory.
+
+=item Can't reswap uid and euid
+
+(P) The setreuid() call failed for some reason in the setuid emulator
+of suidperl.
+
+=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 stat script "%s"
+
+(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.
+
+=item Can't take log of %g
+
+(F) Logarithms are only defined on positive real numbers.
+
+=item Can't take sqrt of %g
+
+(F) For ordinary real numbers, you can't take the square root of a
+negative number. There's a Complex package available for Perl, though,
+if you really want to do that.
+
+=item Can't undef active subroutine
+
+(F) You can't undefine a routine that's currently running. You can,
+however, redefine it while it's running, and you can even undef the
+redefined subroutine while the old routine is running. Go figure.
+
+=item Can't unshift
+
+(F) You tried to unshift an "unreal" array that can't be unshifted, such
+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.
+
+=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.
+
+=item Can't use %s as left arg of an implicit ->
+
+(F) The compiler tried to interpret a bracketed expression as a subscript
+to an array reference. But to the left of the brackets was an expression
+that didn't end in an arrow (->), or look like a subscripted expression.
+Only subscripted expressions with multiple subscripts are allowed to omit
+the intervening arrow.
+
+=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 a string 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 de-lurk some insidious errors.
+
+=item Can't use delimiter brackets within expression
+
+(F) The ${name} construct is for disambiguating identifiers in strings, not
+in ordinary code.
+
+=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 only be tied to 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 write to temp file for B<-e>: %s
+
+(F) The write routine failed for some reason while trying to process
+a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
+
+=item Can't x= to readonly value
+
+(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 Cannot open temporary file
+
+(F) The create routine failed for some reaon while trying to process
+a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
+
+=item chmod: mode argument is missing initial 0
+
+(W) A novice will sometimes say
+
+ 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.
+
+=item Close on unopened file <%s>
+
+(W) You tried to close a filehandle that was never opened.
+
+=item connect() on closed fd
+
+(W) 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 Corrupt malloc ptr 0x%lx at 0x%lx
+
+(P) The malloc package that comes with Perl had an internal failure.
+
+=item corrupted regexp pointers
+
+(P) The regular expression engine got confused by what the regular
+expression compiler gave it.
+
+=item corrupted regexp program
+
+(P) The regular expression engine got passed a regexp program without
+a valid magic number.
+
+=item Deep recursion on subroutine "%s"
+
+(W) This subroutine has called itself (directly or indirectly) 100
+times 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 Did you mean $ instead of %?
+
+(W) You probably said %hash{$key} when you meant $hash{$key}.
+
+=item Don't know how to handle magic of type '%s'
+
+(P) The internal handling of magical variables has been cursed.
+
+=item do_study: out of memory
+
+(P) This should have been caught by safemalloc() instead.
+
+=item Duplicate free() ignored
+
+(S) An internal routine called free() on something that had already
+been freed.
+
+=item END failed--cleanup aborted
+
+(F) An untrapped exception was raised while executing an END subroutine.
+The interpreter is immediately exited.
+
+=item Execution of %s aborted due to compilation errors.
+
+(F) The final summary message when a Perl compilation fails.
+
+=item Exiting eval via %s
+
+(W) You are exiting an eval by unconventional means, such as a
+a goto, or a loop control statement.
+
+=item Exiting subroutine via %s
+
+(W) You are exiting a subroutine by unconventional means, such as a
+a goto, or a loop control statement.
+
+=item Exiting substitution via %s
+
+(W) You are exiting a substitution by unconventional means, such as a
+a return, a goto, or a loop control statement.
+
+=item Fatal $PUTMSG error: %d
+
+(F) An error peculiar to VMS.
+
+=item fcntl is not implemented
+
+(F) Your machine apparently doesn't implement fcntl(). What is this, a
+PDP-11 or something?
+
+=item Filehandle %s never opened
+
+(W) 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) 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 only
+intended to write the file, use ">" or ">>". See L<perlfunc/open>.
+
+=item Filehandle only opened for input
+
+(W) 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 only
+intended to write the file, use ">" or ">>". 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.
+
+=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.
+
+=item Format %s redefined
+
+(W) You redefined a format. To suppress this warning, say
+
+ {
+ local $^W = 0;
+ 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) You said
+
+ if ($foo = 123)
+
+when you meant
+
+ if ($foo == 123)
+
+(or something like that).
+
+=item gdbm store returned %d, errno %d, key "%s"
+
+(S) A warning from the GDBM_File extension that a store failed.
+
+=item gethostent not implemented
+
+(F) Your C library apparently doesn't implement gethostent(), probably
+because if it did, it'd feel morally obligated to return every hostname
+on the Internet.
+
+=item get{sock,peer}name() on closed fd
+
+(W) 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 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 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"), or explicitly qualified to
+say which package the global variable is in (using "::").
+
+=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 Had to create %s unexpectedly
+
+(S) 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) Really old Perl let you omit the % on hash names in some spots. This
+is now heavily deprecated.
+
+=item Identifier "%s::%s" used only once: possible typo
+
+(W) Typographical errors often show up as unique identifiers. If you
+had a good reason for having a unique identifier, then just mention it
+again somehow to suppress the message.
+
+=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.
+
+=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.
+
+=item Illegal octal digit
+
+(F) You used an 8 or 9 in a octal number.
+
+=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.
+
+=item Insecure directory in %s
+
+(F) You can't use system(), exec(), or a piped open in a setuid or setgid
+script if $ENV{PATH} contains a directory that is writable by the world.
+See L<perlsec>.
+
+=item Insecure PATH
+
+(F) You can't use system(), exec(), or a piped open in a setuid or
+setgid script if $ENV{PATH} is 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 internal disaster in regexp
+
+(P) Something went badly wrong in the regular expression parser.
+
+=item internal urp in regexp at /%s/
+
+(P) Something went badly awry in the regular expression parser.
+
+=item invalid [] range in regexp
+
+(F) The range specified in a character class had a minimum character
+greater than the maximum character. See L<perlre>.
+
+=item ioctl is not implemented
+
+(F) Your machine apparently doesn't implement ioctl(), which is pretty
+strange for a machine that supports C.
+
+=item junk on end of regexp
+
+(P) The regular expression parser is confused.
+
+=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>.
+
+=item Label not found for "next %s"
+
+(F) You named a loop to continue, 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 "redo %s"
+
+(F) You named a loop to restart, 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 listen() on closed fd
+
+(W) 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 Literal @%s now requires backslash
+
+(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 putting 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 Method for operation %s not found in package %s during blessing
+
+(F) An attempt was made to specify an entry in an overloading table that
+doesn't somehow point to a valid method. See L<perlovl>.
+
+=item Might be a runaway multi-line %s string starting on line %d
+
+(S) An advisory indicating that the previous error may have been caused
+by a missing delimiter on a string or pattern, because it eventually
+ended earlier on the current line.
+
+=item Misplaced _ in number
+
+(W) 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 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 comma after first argument to %s function
+
+(F) While certain functions allow you to specify a filehandle or an
+"indirect object" before the argument list, this ain't one of them.
+
+=item Missing right bracket
+
+(F) The lexer counted more opening curly brackets (braces) 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
+
+(F) You tried, directly or indirectly, to change the value of a
+constant. You didn't, of course, try "2 = 1", since the compiler
+catches that. But an easy way to do the same thing is:
+
+ sub mod { $_[0] = 1 }
+ mod(2);
+
+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
+
+(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"
+
+(F) 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 msg%s not implemented
+
+(F) You don't have System V message IPC on your system.
+
+=item Multidimensional syntax %s not supported
+
+(W) Multidimensional arrays aren't written like $foo[1,2,3]. They're written
+like $foo[1][2][3], as in C.
+
+=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.
+
+=item nested *?+ in regexp
+
+(F) You can't quantify a quantifier without intervening parens. So
+things like ** or +* or ?* are illegal.
+
+Note, however, that the minimal matching quantifiers, *?, +? and ?? appear
+to be nested quantifiers, but aren't. See L<perlre>.
+
+=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 %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>.
+
+=item No B<-e> allowed in setuid scripts
+
+(F) A setuid script can't be specified by the user.
+
+=item No comma allowed after %s
+
+(F) A list operator that has a filehandle or "indirect object" is not
+allowed to have a comma between that and the following arguments.
+Otherwise it'd be just another one of the arguments.
+
+=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.
+
+=item No dbm on this machine
+
+(P) This is counted as an internal error, because every machine should
+supply dbm nowadays, since Perl comes with SDBM. See L<SDBM_File>.
+
+=item No DBsub routine
+
+(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 DB::sub routine to be called at the beginning of each
+ordinary subroutine call.
+
+=item No Perl script found in input
+
+(F) You called C<perl -x>, but no line was found in the file beginning
+with #! and containing the word "perl".
+
+=item No setregid available
+
+(F) Configure didn't find anything resembling the setregid() call for
+your system.
+
+=item No setreuid available
+
+(F) Configure didn't find anything resembling the setreuid() call for
+your system.
+
+=item No space allowed after B<-I>
+
+(F) The argument to B<-I> must follow the B<-I> immediately with no
+intervening space.
+
+=item No such signal: SIG%s
+
+(W) 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>.
+
+=item Not a format reference
+
+(F) I'm not sure how you managed to generate a reference to an anonymous
+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 "type glob" (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>.
+
+=item Not a perl script
+
+(F) The setuid emulator requires that scripts have a well-formed #! line
+even on machines that don't support the #! construct. The line must
+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>.
+
+=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>.
+
+=item Not a subroutine reference in %OVERLOAD
+
+(F) An attempt was made to specify an entry in an overloading table that
+doesn't somehow point to a valid subroutine. See L<perlovl>.
+
+=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) A format specified more picture fields than the next line supplied.
+See L<perlform>.
+
+=item Null filename used
+
+(F) You can't require the null filename, especially since on many machines
+that means the current directory! See L<perlfunc/require>.
+
+=item NULL OP IN RUN
+
+(P) Some internal routine called run() with a null opcode pointer.
+
+=item Null realloc
+
+(P) An attempt was made to realloc NULL.
+
+=item NULL regexp argument
+
+(P) The internal pattern matching routines blew it bigtime.
+
+=item NULL regexp parameter
+
+(P) The internal pattern matching routines are out of their gourd.
+
+=item Odd number of elements in hash list
+
+(S) You specified an odd number of elements to a hash list, which is odd,
+since hash lists come in key/value pairs.
+
+=item oops: oopsAV
+
+(S) An internal warning that the grammar is screwed up.
+
+=item oops: oopsHV
+
+(S) An internal warning that the grammar is screwed up.
+
+=item Operation `%s' %s: no method found,
+
+(F) An attempt was made to use an entry in an overloading table that
+somehow no longer points to a valid method. See L<perlovl>.
+
+=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 Out of memory!
+
+(X) The malloc() function returned 0, indicating there was insufficient
+remaining memory (or virtual memory) to satisfy the request.
+
+=item page overflow
+
+(W) A single call to write() produced more lines than can fit on a page.
+See L<perlform>.
+
+=item panic: ck_grep
+
+(P) Failed an internal consistency check trying to compile a grep.
+
+=item panic: ck_split
+
+(P) Failed an internal consistency check trying to compile a split.
+
+=item panic: corrupt saved stack index
+
+(P) The savestack was requested to restore more localized values than there
+are in the savestack.
+
+=item panic: die %s
+
+(P) We popped the context stack to an eval context, and then discovered
+it wasn't an eval context.
+
+=item panic: do_match
+
+(P) The internal pp_match() routine was called with invalid operational data.
+
+=item panic: do_split
+
+(P) Something terrible went wrong in setting up for the split.
+
+=item panic: do_subst
+
+(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.
+
+=item panic: goto
+
+(P) We popped the context stack to a context with the specified label,
+and then discovered it wasn't a context we know how to do a goto in.
+
+=item panic: INTERPCASEMOD
+
+(P) The lexer got into a bad state at a case modifier.
+
+=item panic: INTERPCONCAT
+
+(P) The lexer got into a bad state parsing a string with brackets.
+
+=item panic: last
+
+(P) We popped the context stack to a block context, and then discovered
+it wasn't a block context.
+
+=item panic: leave_scope clearsv
+
+(P) A writable lexical variable became readonly 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: mapstart
+
+(P) The compiler is screwed up with respect to the map() function.
+
+=item panic: null array
+
+(P) One of the internal array routines was passed a null AV pointer.
+
+=item panic: pad_alloc
+
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+
+=item panic: pad_free curpad
+
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+
+=item panic: pad_free po
+
+(P) An invalid scratch pad offset was detected internally.
+
+=item panic: pad_reset curpad
+
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+
+=item panic: pad_sv po
+
+(P) An invalid scratch pad offset was detected internally.
+
+=item panic: pad_swipe curpad
+
+(P) The compiler got confused about which scratch pad it was allocating
+and freeing temporaries and lexicals from.
+
+=item panic: pad_swipe po
+
+(P) An invalid scratch pad offset was detected internally.
+
+=item panic: pp_iter
+
+(P) The foreach iterator got called in a non-loop context frame.
+
+=item panic: realloc
+
+(P) Something requested a negative number of bytes of realloc.
+
+=item panic: restartop
+
+(P) Some internal routine requested a goto (or something like it), and
+didn't supply the destination.
+
+=item panic: return
+
+(P) We popped the context stack to a subroutine or eval context, and
+then discovered it wasn't a subroutine or eval context.
+
+=item panic: scan_num
+
+(P) scan_num() got called on something that wasn't a number.
+
+=item panic: sv_insert
+
+(P) The sv_insert() routine was told to remove more string than there
+was string.
+
+=item panic: top_env
+
+(P) The compiler attempted to do a goto, or something weird like that.
+
+=item panic: yylex
+
+(P) The lexer got into a bad state while processing a case modifier.
+
+=item Parens missing around "%s" list
+
+(W) You said something like
+
+ my $foo, $bar = @_;
+
+when you meant
+
+ my ($foo, $bar) = @_;
+
+Remember that "my" and "local" bind closer than comma.
+
+=item Perl %3.3f 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 Permission denied
+
+(F) The setuid emulator in suidperl decided you were up to no good.
+
+=item POSIX getpgrp can't take an argument
+
+(F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike
+the BSD version, which takes a pid.
+
+=item Possible memory corruption: %s overflowed 3rd argument
+
+(F) An ioctl() or fcntl() returned more than Perl was bargaining for.
+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 Precedence problem: open %s should be open(%s)
+
+(S) The old irregular construct
+
+ open FOO || die;
+
+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
+parens around the filehandle, or use the new "or" operator instead of "||".
+
+=item print on closed filehandle %s
+
+(W) The filehandle you're printing on got itself closed sometime before now.
+Check your logic flow.
+
+=item printf on closed filehandle %s
+
+(W) The filehandle you're writing to got itself closed sometime before now.
+Check your logic flow.
+
+=item Probable precedence problem on %s
+
+(W) The compiler found a bare word 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 Read on closed filehandle <%s>
+
+(W) 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 MSDOS machine.
+
+=item Recompile perl with B<-D>DEBUGGING to use B<-D> switch
+
+(F) 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
+
+(F) More than 100 levels of inheritance were used. Probably indicates
+an unintended loop in your inheritance hierarchy.
+
+=item Reference miscount in sv_replace()
+
+(W) 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 out of space
+
+(P) A "can't happen" error, because safemalloc() should have caught it earlier.
+
+=item regexp too big
+
+(F) The current implementation of regular expression 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 Reversed %s= operator
+
+(W) You wrote your assignment operator backwards. The = must always
+comes last, to avoid ambiguity with subsequent unary operators.
+
+=item Runaway format
+
+(F) Your format contained the ~~ repeat-until-blank sequence, but it
+produced 200 lines at once, and the 200th line looked exactly like the
+199th line. Apparently you didn't arrange for the arguments to exhaust
+themselves, either by using ^ instead of @ (for scalar variables), or by
+shifting or popping (for array variables). See L<perlform>.
+
+=item Scalar value @%s[%s] better written as $%s[%s]
+
+(W) You've used an array slice (indicated by @) to select a single value of
+an array. Generally it's better to ask for a scalar value (indicated by $).
+The difference is that $foo[&bar] always behaves like a scalar, both when
+assigning to it and when evaluating its argument, while @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 only expecting one subscript.
+
+=item Script is not setuid/setgid in suidperl
+
+(F) Oddly, the suidperl program was invoked on a script with its setuid
+or setgid bit set. This doesn't make much sense.
+
+=item Search pattern not terminated
+
+(F) The lexer couldn't find the final delimiter of a // or m{}
+construct. Remember that bracketing delimiters count nesting level.
+
+=item seek() on unopened file
+
+(W) You tried to use the seek() function on a filehandle that was either
+never opened or has been closed since.
+
+=item select not implemented
+
+(F) This machine doesn't implement the select() system call.
+
+=item sem%s not implemented
+
+(F) You don't have System V semaphore IPC on your system.
+
+=item semi-panic: attempt to dup freed string
+
+(S) The internal newSVsv() routine was called to duplicate a scalar
+that had previously been marked as free.
+
+=item Semicolon seems to be missing
+
+(W) A nearby syntax error was probably caused by a missing semicolon,
+or possibly some other missing operator, such as a comma.
+
+=item Send on closed socket
+
+(W) The filehandle you're sending to got itself closed sometime before now.
+Check your logic flow.
+
+=item Sequence (?#... not terminated
+
+(F) A regular expression comment must be terminated by a closing
+parenthesis. Embedded parens aren't allowed. See L<perlre>.
+
+=item Sequence (?%s...) not implemented
+
+(F) A proposed regular expression extension has the character reserved
+but has not yet been written. See L<perlre>.
+
+=item Sequence (?%s...) not recognized
+
+(F) You used a regular expression extension that doesn't make sense.
+See L<perlre>.
+
+=item setegid() not implemented
+
+(F) You tried to assign to $), 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 $>, and your operating system doesn't support
+the seteuid() system call (or equivalent), or at least Configure didn't
+think so.
+
+=item setrgid() not implemented
+
+(F) You tried to assign to $(, 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 $<, and your operating system doesn't support
+the setruid() system call (or equivalent), or at least Configure didn't
+think so.
+
+=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.
+
+=item shm%s not implemented
+
+(F) You don't have System V shared memory IPC on your system.
+
+=item shutdown() on closed fd
+
+(W) You tried to do a shutdown on a closed socket. Seems a bit superfluous.
+
+=item SIG%s handler "%s" not defined.
+
+(W) 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
+
+(F) An ancient error message that almost nobody ever runs into anymore.
+But before sort was a keyword, people sometimes used it as a filehandle.
+
+=item Sort subroutine didn't return a numeric value
+
+(F) A sort comparison routine must return a number. You probably blew
+it by not using C<E<lt>=E<gt> or C<cmp>, or by not using them correctly.
+See L<perlfunc/sort>.
+
+=item Sort subroutine didn't return single value
+
+(F) A sort comparison subroutine may not return a list value with more
+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>.
+
+=item Stat on unopened file <%s>
+
+(W) You tried to use the stat() function (or an equivalent file test)
+on a filehandle that was either never opened or has been closed since.
+
+=item Statement unlikely to be reached
+
+(W) 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 Subroutine %s redefined
+
+(W) You redefined a subroutine. To suppress this warning, say
+
+ {
+ local $^W = 0;
+ eval "sub name { ... }";
+ }
+
+=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
+L<perlop/"Quote and Quotelike Operators">.
+
+=item Substitution pattern not terminated
+
+(F) The lexer couldn't find the interior delimiter of a s/// or s{}{}
+construct. Remember that bracketing delimiters count nesting level.
+
+=item Substitution replacement not terminated
+
+(F) The lexer couldn't find the final delimiter of a s/// or s{}{}
+construct. Remember that bracketing delimiters count nesting level.
+
+=item substr outside of string
+
+(W) 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>.
+
+=item suidperl is no longer needed since...
+
+(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 syntax error
+
+(F) Probably means you had a syntax error. Common reasons include:
+
+ A keyword is misspelled.
+ A semicolon is missing.
+ A comma is missing.
+ An opening or closing parenthesis is missing.
+ An opening or closing brace is missing.
+ A closing quote is missing.
+
+Often there will be another error message associated with the syntax
+error giving more information. (Sometimes it helps to turn on B<-w>.)
+The error message itself often tells you where it was in the line when
+it decided to give up. Sometimes the actual error is several tokens
+before this, since 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>.
+
+=item System V IPC is not implemented on this machine
+
+(F) You tried to do something with a function beginning with "sem", "shm"
+or "msg". See L<perlfunc/semctl>, for example.
+
+=item Syswrite on closed filehandle
+
+(W) The filehandle you're writing to got itself closed sometime before now.
+Check your logic flow.
+
+=item tell() on unopened file
+
+(W) You tried to use the tell() function on a filehandle that was either
+never opened or has been closed since.
+
+=item Test on unopened file <%s>
+
+(W) 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 $[ is now strictly circumscribed, and interpreted as
+a compiler directive. You may only say one of
+
+ $[ = 0;
+ $[ = 1;
+ ...
+ local $[ = 0;
+ 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.
+
+=item The crypt() function is unimplemented due to excessive paranoia.
+
+(F) Configure couldn't find the crypt() function on your machine,
+probably because your vendor didn't supply it, probably because they
+think the U.S. Govermnment 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 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.
+
+=item times not implemented
+
+(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
+
+(F) There has to be at least one argument to syscall() to specify the
+system call to call, silly dilly.
+
+=item Too many args to syscall
+
+(F) Perl only supports a maximum of 14 args to syscall().
+
+=item Too many arguments for %s
+
+(F) The function requires fewer arguments than you specified.
+
+=item trailing \ in regexp
+
+(F) The regular expression ends with an unbackslashed backslash. Backslash
+it. See L<perlre>.
+
+=item Translation pattern not terminated
+
+(F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
+construct.
+
+=item Translation replacement not terminated
+
+(F) The lexer couldn't find the final delimiter of a tr/// or tr[][]
+construct.
+
+=item truncate not implemented
+
+(F) Your machine doesn't implement a file truncation mechanism that
+Configure knows about.
+
+=item Type of arg %d to %s must be %s (not %s)
+
+(F) This function requires the argument in that position to be of a
+certain type. Arrays must be @NAME or @{EXPR}. Hashes must be
+%NAME or %{EXPR}. No implicit dereferencing is allowed--use the
+{EXPR} forms as an explicit dereference. See L<perlref>.
+
+=item umask: argument is missing initial 0
+
+(W) A umask of 222 is incorrect. It should be 0222, since octal literals
+always start with 0 in Perl, as in C.
+
+=item Unbalanced context: %d more PUSHes than POPs
+
+(W) 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) The exit code detected an internal inconsistency in how many
+values were temporarily localized.
+
+=item Unbalanced scopes: %d more ENTERs than LEAVEs
+
+(W) The exit code detected an internal inconsistency in how many blocks
+were entered and left.
+
+=item Unbalanced tmps: %d more allocs than frees
+
+(W) The exit code detected an internal inconsistency in how many mortal
+scalars were allocated and freed.
+
+=item Undefined format "%s" called
+
+(F) The format indicated doesn't seem to exist. Perhaps it's really in
+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>.
+
+=item Undefined subroutine &%s called
+
+(F) The subroutine indicated hasn't been defined, or if it was, it
+has since been undefined.
+
+=item Undefined subroutine called
+
+(F) The anonymous subroutine you're trying to call hasn't been defined,
+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>.
+
+=item unexec of %s into %s failed!
+
+(F) The unexec() routine failed for some reason. See your local FSF
+representative, who probably put it there in the first place.
+
+=item Unknown BYTEORDER
+
+(F) There are no byteswapping functions for a machine with this byte order.
+
+=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 paren. See L<perlre>.
+
+=item Unmatched right bracket
+
+(F) The lexer counted more closing curly brackets (braces) than opening
+ones, so you're probably missing an 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>.
+
+=item Unquoted string "%s" may clash with future reserved word
+
+(W) You used a bare word 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 \%03o ignored
+
+(S) A garbage character was found in the input, and ignored, in case it's
+a weird control character on an EBCDIC machine, or some such.
+
+=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.
+
+=item Unrecognized switch: -%s
+
+(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) 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/chop>.
+
+=item Unsupported directory function "%s" called
+
+(F) Your machine doesn't support opendir() and readdir().
+
+=item Unsupported function %s
+
+(F) This machines doesn't implement the indicated function, apparently.
+At least, Configure doesn't think so.
+
+=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
+
+(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
+
+(D) This was an ill-advised attempt to emulate a poorly defined awk feature.
+Use an explicit printf() or sprintf() instead.
+
+=item Use of $* is deprecated
+
+(D) This variable magically turned on multiline 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<$*>.
+
+=item Use of %s is deprecated
+
+(D) 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.
+
+=item Use of implicit split to @_ is deprecated
+
+(D) 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
+
+(W) 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 an initial value to your variables.
+
+=item Useless use of %s in void context
+
+(W) 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
+
+ $one, $two = 1, 2;
+
+when you meant to say
+
+ ($one, $two) = (1, 2);
+
+=item Warning: unable to close filehandle %s properly.
+
+(S) The implicit close() done by an open() got an error indication on the
+close(0. This usually indicates your filesystem ran out of disk space.
+
+=item Warning: Use of "%s" without parens is ambiguous
+
+(S) 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;
+
+you may THINK you wrote the same thing as
+
+ rand() + 5;
+
+but in actual fact, you got
+
+ rand(+5);
+
+So put in parens to say what you really mean.
+
+=item Write on closed filehandle
+
+(W) The filehandle you're writing to got itself closed sometime before now.
+Check your logic flow.
+
+=item X outside of string
+
+(F) You had a pack template that specified a relative position before
+the beginning of the string being unpacked. See L<perlfunc/pack>.
+
+=item x outside of string
+
+(F) You had a pack template that specified a relative position after
+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.
+
+=item Xsub called in sort
+
+(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.
+Use a filename instead.
+
+=item YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!
+
+(F) And you probably never will, since 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.
+
+=item You need to quote "%s"
+
+(W) 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 [gs]etsockopt() on closed fd
+
+(W) 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>.
+
+=item \1 better written as $1
+
+(W) Outside of patterns, backreferences live on as variables. The use
+of backslashes is grandfathered on the righthand 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.
+
+=back
+
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
new file mode 100644
index 0000000000..5ac5a9e0c6
--- /dev/null
+++ b/pod/perlembed.pod
@@ -0,0 +1,7 @@
+=head1 NAME
+
+perlembed - how to embed perl in your C or C++ app
+
+=head1 DESCRIPTION
+
+Look at perlmain.c, and do something like that.
diff --git a/pod/perlform.pod b/pod/perlform.pod
new file mode 100644
index 0000000000..38d7153e8b
--- /dev/null
+++ b/pod/perlform.pod
@@ -0,0 +1,314 @@
+=head1 NAME
+
+perlform - Perl formats
+
+=head1 DESCRIPTION
+
+Perl has a mechanism to help you generate simple reports and charts. To
+facilitate this, Perl helps you lay out your output page in your code in a
+fashion that's close to how it will look when it's printed. It can keep
+track of things like how many lines on a page, what page you're, when to
+print page headers, etc. The keywords used are borrowed from FORTRAN:
+format() to declare and write() to execute; see their entries in
+L<manfunc>. Fortunately, the layout is much more legible, more like
+BASIC's PRINT USING statement. Think of it as a poor man's nroff(1).
+
+Formats, like packages and subroutines, are declared rather than executed,
+so they may occur at any point in your program. (Usually it's best to
+keep them all together though.) They have their own namespace apart from
+all the other "types" in Perl. This means that if you have a function
+named "Foo", it is not the same thing as having a format named "Foo".
+However, the default name for the format associated with a given
+filehandle is the same as the name of the filehandle. Thus, the default
+format for STDOUT is name "STDOUT", and the default format for filehandle
+TEMP is name "TEMP". They just look the same. They aren't.
+
+Output record formats are declared as follows:
+
+ format NAME =
+ FORMLIST
+ .
+
+If name is omitted, format "STDOUT" is defined. FORMLIST consists of a
+sequence of lines, each of which may be of one of three types:
+
+=over 4
+
+=item 1.
+
+A comment, indicated by putting a '#' in the first column.
+
+=item 2.
+
+A "picture" line giving the format for one output line.
+
+=item 3.
+
+An argument line supplying values to plug into the previous picture line.
+
+=back
+
+Picture lines are printed exactly as they look, except for certain fields
+that substitute values into the line. Each field in a picture line starts
+with either "@" (at) or "^" (caret). These lines do not undergo any kind
+of variable interpolation. The at field (not to be confused with the array
+marker @) is the normal kind of field; the other kind, caret fields, are used
+to do rudimentary multi-line text block filling. The length of the field
+is supplied by padding out the field with multiple "<", ">", or "|"
+characters to specify, respectively, left justification, right
+justification, or centering. If the variable would exceed the width
+specified, it is truncated.
+
+As an alternate form of right justification, you may also use "#"
+characters (with an optional ".") to specify a numeric field. This way
+you can line up the decimal points. If any value supplied for these
+fields contains a newline, only the text up to the newline is printed.
+Finally, the special field "@*" can be used for printing multi-line,
+non-truncated values; it should appear by itself on a line.
+
+The values are specified on the following line in the same order as
+the picture fields. The expressions providing the values should be
+separated by commas. The expressions are all evaluated in a list context
+before the line is processed, so a single list expression could produce
+multiple list elements. The expressions may be spread out to more than
+one line if enclosed in braces. If so, the opening brace must be the first
+token on the first line.
+
+Picture fields that begin with ^ rather than @ are treated specially.
+With a # field, the field is blanked out if the value is undefined. For
+other field types, the caret enables a kind of fill mode. Instead of an
+arbitrary expression, the value supplied must be a scalar variable name
+that contains a text string. Perl puts as much text as it can into the
+field, and then chops off the front of the string so that the next time
+the variable is referenced, more of the text can be printed. (Yes, this
+means that the variable itself is altered during execution of the write()
+call, and is not returned.) Normally you would use a sequence of fields
+in a vertical stack to print out a block of text. You might wish to end
+the final field with the text "...", which will appear in the output if
+the text was too long to appear in its entirety. You can change which
+characters are legal to break on by changing the variable C<$:> (that's
+$FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
+list of the desired characters.
+
+Since use of caret fields can produce variable length records. If the text
+to be formatted is short, you can suppress blank lines by putting a
+"~" (tilde) character anywhere in the line. The tilde will be translated
+to a space upon output. If you put a second tilde contiguous to the
+first, the line will be repeated until all the fields on the line are
+exhausted. (If you use a field of the at variety, the expression you
+supply had better not give the same value every time forever!)
+
+Top-of-form processing is by default handled by a format with the
+same name as the current filehandle with "_TOP" concatenated to it.
+It's triggered at the top of each page. See <perlfunc/write()>.
+
+Examples:
+
+ # a report on the /etc/passwd file
+ format STDOUT_TOP =
+ Passwd File
+ Name Login Office Uid Gid Home
+ ------------------------------------------------------------------
+ .
+ format STDOUT =
+ @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
+ $name, $login, $office,$uid,$gid, $home
+ .
+
+
+ # a report from a bug report form
+ format STDOUT_TOP =
+ Bug Reports
+ @<<<<<<<<<<<<<<<<<<<<<<< @||| @>>>>>>>>>>>>>>>>>>>>>>>
+ $system, $%, $date
+ ------------------------------------------------------------------
+ .
+ format STDOUT =
+ Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $subject
+ Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $index, $description
+ Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $priority, $date, $description
+ From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $from, $description
+ Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $programmer, $description
+ ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $description
+ ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $description
+ ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $description
+ ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $description
+ ~ ^<<<<<<<<<<<<<<<<<<<<<<<...
+ $description
+ .
+
+It is possible to intermix print()s with write()s on the same output
+channel, but you'll have to handle $- ($FORMAT_LINES_LEFT)
+yourself.
+
+=head2 Format Variables
+
+The current format name is stored in the variable C<$~> ($FORMAT_NAME),
+and the current top of form format name is in C<$^> ($FORMAT_TOP_NAME).
+The current output page number is stored in C<$%> ($FORMAT_PAGE_NUMBER),
+and the number of lines on the page is in C<$=> ($FORMAT_LINES_PER_PAGE).
+Whether to autoflush output on this handle is stored in $<$|>
+($OUTPUT_AUTOFLUSH). The string output before each top of page (except
+the first) is stored in C<$^L> ($FORMAT_FORMFEED). These variables are
+set on a per-filehandle basis, so you'll need to select() into a different
+one to affect them:
+
+ select((select(OUTF),
+ $~ = "My_Other_Format",
+ $^ = "My_Top_Format"
+ )[0]);
+
+Pretty ugly, eh? It's a common idiom though, so don't be too surprised
+when you see it. You can at least use a temporary variable to hold
+the previous filehandle: (this is a much better approach in general,
+because not only does legibility improve, you now have intermediary
+stage in the expression to single-step the debugger through):
+
+ $ofh = select(OUTF);
+ $~ = "My_Other_Format";
+ $^ = "My_Top_Format";
+ select($ofh);
+
+If you use the English module, you can even read the variable names:
+
+ use English;
+ $ofh = select(OUTF);
+ $FORMAT_NAME = "My_Other_Format";
+ $FORMAT_TOP_NAME = "My_Top_Format";
+ select($ofh);
+
+But you still have those funny select()s. So just use the FileHandle
+module. Now, you can access these special variables using lower-case
+method names instead:
+
+ use FileHandle;
+ format_name OUTF "My_Other_Format";
+ format_top_name OUTF "My_Top_Format";
+
+Much better!
+
+=head1 NOTES
+
+Since the values line may contain arbitrary expression (for at fields,
+not caret fields), you can farm out any more sophisticated processing
+to other functions, like sprintf() or one of your own. For example:
+
+ format Ident =
+ @<<<<<<<<<<<<<<<
+ &commify($n)
+ .
+
+To get a real at or caret into the field, do this:
+
+ format Ident =
+ I have an @ here.
+ "@"
+ .
+
+To center a whole line of text, do something like this:
+
+ format Ident =
+ @|||||||||||||||||||||||||||||||||||||||||||||||
+ "Some text line"
+ .
+
+There is no builtin way to say "float this to the right hand side
+of the page, however wide it is." You have to specify where it goes.
+The truly desperate can generate their own format on the fly, based
+on the current number of columns, and then eval() it:
+
+ $format = "format STDOUT = \n";
+ . '^' . '<' x $cols . "\n";
+ . '$entry' . "\n";
+ . "\t^" . "<" x ($cols-8) . "~~\n";
+ . '$entry' . "\n";
+ . ".\n";
+ print $format if $Debugging;
+ eval $format;
+ die $@ if $@;
+
+Which would generate a format looking something like this:
+
+ format STDOUT =
+ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+ $entry
+ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
+ $entry
+ .
+
+Here's a little program that's somewhat like fmt(1):
+
+ format =
+ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
+ $_
+
+ .
+
+ $/ = '';
+ while (<>) {
+ s/\s*\n\s*/ /g;
+ write;
+ }
+
+=head2 Footers
+
+While $FORMAT_TOP_NAME contains the name of the current header format,
+there is no corresponding mechanism to automatically do the same thing
+for a footer. Not knowing how big a format is going to be until you
+evaluate it is one of the major problems. It's on the TODO list.
+
+Here's one strategy: If you have a fixed-size footer, you can get footers
+by checking $FORMAT_LINES_LEFT before each write() and print the footer
+yourself if necessary.
+
+Here's another strategy; open a pipe to yourself, using C<open(MESELF, "|-")>
+(see L<perlfunc/open()>) and always write() to MESELF instead of
+STDOUT. Have your child process postprocesses its STDIN to rearrange
+headers and footers however you like. Not very convenient, but doable.
+
+=head2 Accessing Formatting Internals
+
+For low-level access to the formatting mechanism. you may use formline()
+and access C<$^A> (the $ACCUMULATOR variable) directly.
+
+For example:
+
+ $str = formline <<'END', 1,2,3;
+ @<<< @||| @>>>
+ END
+
+ print "Wow, I just stored `$^A' in the accumulator!\n";
+
+Or to make an swrite() subroutine which is to write() what sprintf()
+is to printf(), do this:
+
+ use English;
+ use Carp;
+ sub swrite {
+ croak "usage: swrite PICTURE ARGS" unless @ARG;
+ local($ACCUMULATOR);
+ formline(@ARG);
+ return $ACCUMULATOR;
+ }
+
+ $string = swrite(<<'END', 1, 2, 3);
+ Check me out
+ @<<< @||| @>>>
+ END
+ print $string;
+
+=head1 WARNING
+
+During the execution of a format, only global variables are visible,
+or dynamically-scoped ones declared with local(). Lexically scoped
+variables declared with my() are I<NOT> available, as they are not
+considered to reside in the same lexical scope as the format.
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
new file mode 100644
index 0000000000..d5aa3aa0b3
--- /dev/null
+++ b/pod/perlfunc.pod
@@ -0,0 +1,2896 @@
+=head1 NAME
+
+perlfunc - Perl builtin functions
+
+=head1 DESCRIPTION
+
+The functions in this section can serve as terms in an expression.
+They fall into two major categories: list operators and named unary
+operators. These differ in their precedence relationship with a
+following comma. (See the precedence table in L<perlop>.) List
+operators take more than one argument, while unary operators can never
+take more than one argument. Thus, a comma terminates the argument of
+a unary operator, but merely separates the arguments of a list
+operator. A unary operator generally provides a scalar context to its
+argument, while a list operator may provide either scalar and list
+contexts for its arguments. If it does both, the scalar arguments will
+be first, and the list argument will follow. (Note that there can only
+ever be one list argument.) For instance, splice() has three scalar
+arguments followed by a list.
+
+In the syntax descriptions that follow, list operators that expect a
+list (and provide list context for the elements of the list) are shown
+with LIST as an argument. Such a list may consist of any combination
+of scalar arguments or list values; the list values will be included
+in the list as if each individual element were interpolated at that
+point in the list, forming a longer single-dimensional list value.
+Elements of the LIST should be separated by commas.
+
+Any function in the list below may be used either with or without
+parentheses around its arguments. (The syntax descriptions omit the
+parens.) If you use the parens, the simple (but occasionally
+surprising) rule is this: It I<LOOKS> like a function, therefore it I<IS> a
+function, and precedence doesn't matter. Otherwise it's a list
+operator or unary operator, and precedence does matter. And whitespace
+between the function and left parenthesis doesn't count--so you need to
+be careful sometimes:
+
+ print 1+2+3; # Prints 6.
+ print(1+2) + 3; # Prints 3.
+ print (1+2)+3; # Also prints 3!
+ print +(1+2)+3; # Prints 6.
+ print ((1+2)+3); # Prints 6.
+
+If you run Perl with the B<-w> switch it can warn you about this. For
+example, the third line above produces:
+
+ print (...) interpreted as function at - line 1.
+ Useless use of integer addition in void context at - line 1.
+
+For functions that can be used in either a scalar or list context,
+non-abortive failure is generally indicated in a scalar context by
+returning the undefined value, and in a list context by returning the
+null list.
+
+Remember the following rule:
+
+=over 5
+
+=item *
+
+I<THERE IS NO GENERAL RULE FOR CONVERTING A LIST INTO A SCALAR!>
+
+=back
+
+Each operator and function decides which sort of value it would be most
+appropriate to return in a scalar context. Some operators return the
+length of the list that would have been returned in a list context. Some
+operators return the first value in the list. Some operators return the
+last value in the list. Some operators return a count of successful
+operations. In general, they do what you want, unless you want
+consistency.
+
+=over 8
+
+=item -X FILEHANDLE
+
+=item -X EXPR
+
+=item -X
+
+A file test, where X is one of the letters listed below. This unary
+operator takes one argument, either a filename or a filehandle, and
+tests the associated file to see if something is true about it. If the
+argument is omitted, tests $_, except for C<-t>, which tests STDIN.
+Unless otherwise documented, it returns C<1> for TRUE and C<''> for FALSE, or
+the undefined value if the file doesn't exist. Despite the funny
+names, precedence is the same as any other named unary operator, and
+the argument may be parenthesized like any other unary operator. The
+operator may be any of:
+
+ -r File is readable by effective uid/gid.
+ -w File is writable by effective uid/gid.
+ -x File is executable by effective uid/gid.
+ -o File is owned by effective uid.
+
+ -R File is readable by real uid/gid.
+ -W File is writable by real uid/gid.
+ -X File is executable by real uid/gid.
+ -O File is owned by real uid.
+
+ -e File exists.
+ -z File has zero size.
+ -s File has non-zero size (returns size).
+
+ -f File is a plain file.
+ -d File is a directory.
+ -l File is a symbolic link.
+ -p File is a named pipe (FIFO).
+ -S File is a socket.
+ -b File is a block special file.
+ -c File is a character special file.
+ -t Filehandle is opened to a tty.
+
+ -u File has setuid bit set.
+ -g File has setgid bit set.
+ -k File has sticky bit set.
+
+ -T File is a text file.
+ -B File is a binary file (opposite of -T).
+
+ -M Age of file in days when script started.
+ -A Same for access time.
+ -C Same for inode change time.
+
+The interpretation of the file permission operators C<-r>, C<-R>, C<-w>,
+C<-W>, C<-x> and C<-X> is based solely on the mode of the file and the
+uids and gids of the user. There may be other reasons you can't actually
+read, write or execute the file. Also note that, for the superuser,
+C<-r>, C<-R>, C<-w> and C<-W> always return 1, and C<-x> and C<-X> return
+1 if any execute bit is set in the mode. Scripts run by the superuser may
+thus need to do a stat() in order to determine the actual mode of the
+file, or temporarily set the uid to something else.
+
+Example:
+
+ while (<>) {
+ chop;
+ next unless -f $_; # ignore specials
+ ...
+ }
+
+Note that C<-s/a/b/> does not do a negated substitution. Saying
+C<-exp($foo)> still works as expected, however--only single letters
+following a minus are interpreted as file tests.
+
+The C<-T> and C<-B> switches work as follows. The first block or so of the
+file is examined for odd characters such as strange control codes or
+characters with the high bit set. If too many odd characters (>30%)
+are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file
+containing null in the first block is considered a binary file. If C<-T>
+or C<-B> is used on a filehandle, the current stdio buffer is examined
+rather than the first block. Both C<-T> and C<-B> return TRUE on a null
+file, or a file at EOF when testing a filehandle.
+
+If any of the file tests (or either the stat() or lstat() operators) are given the
+special filehandle consisting of a solitary underline, then the stat
+structure of the previous file test (or stat operator) is used, saving
+a system call. (This doesn't work with C<-t>, and you need to remember
+that lstat() and C<-l> will leave values in the stat structure for the
+symbolic link, not the real file.) Example:
+
+ print "Can do.\n" if -r $a || -w _ || -x _;
+
+ stat($filename);
+ print "Readable\n" if -r _;
+ print "Writable\n" if -w _;
+ print "Executable\n" if -x _;
+ print "Setuid\n" if -u _;
+ print "Setgid\n" if -g _;
+ print "Sticky\n" if -k _;
+ print "Text\n" if -T _;
+ print "Binary\n" if -B _;
+
+=item abs VALUE
+
+Returns the absolute value of its argument.
+
+=item accept NEWSOCKET,GENERICSOCKET
+
+Accepts an incoming socket connect, just as the accept(2) system call
+does. Returns the packed address if it succeeded, FALSE otherwise.
+See example in L<perlipc>.
+
+=item alarm SECONDS
+
+Arranges to have a SIGALRM delivered to this process after the
+specified number of seconds have elapsed. (On some machines,
+unfortunately, the elapsed time may be up to one second less than you
+specified because of how seconds are counted.) Only one timer may be
+counting at once. Each call disables the previous timer, and an
+argument of 0 may be supplied to cancel the previous timer without
+starting a new one. The returned value is the amount of time remaining
+on the previous timer.
+
+For sleeps of finer granularity than one second, you may use Perl's
+syscall() interface to access setitimer(2) if your system supports it,
+or else see L</select()> below.
+
+=item atan2 Y,X
+
+Returns the arctangent of Y/X in the range -PI to PI.
+
+=item bind SOCKET,NAME
+
+Binds a network address to a socket, just as the bind system call
+does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a
+packed address of the appropriate type for the socket. See example in
+L<perlipc>.
+
+=item binmode FILEHANDLE
+
+Arranges for the file to be read or written in "binary" mode in
+operating systems that distinguish between binary and text files.
+Files that are not in binary mode have CR LF sequences translated to LF
+on input and LF translated to CR LF on output. Binmode has no effect
+under Unix; in DOS, it may be imperative. If FILEHANDLE is an expression,
+the value is taken as the name of the filehandle.
+
+=item bless REF,PACKAGE
+
+=item bless REF
+
+This function tells the referenced object (passed as REF) that it is now
+an object in PACKAGE--or the current package if no PACKAGE is specified,
+which is the usual case. It returns the reference for convenience, since
+a bless() is often the last thing in a constructor. See L<perlobj> for
+more about the blessing (and blessings) of objects.
+
+=item caller EXPR
+
+=item caller
+
+Returns the context of the current subroutine call. In a scalar context,
+returns TRUE if there is a caller, that is, if we're in a subroutine or
+eval() or require(), and FALSE otherwise. In a list context, returns
+
+ ($package,$filename,$line) = caller;
+
+With EXPR, it returns some extra information that the debugger uses to
+print a stack trace. The value of EXPR indicates how many call frames
+to go back before the current one.
+
+=item chdir EXPR
+
+Changes the working directory to EXPR, if possible. If EXPR is
+omitted, changes to home directory. Returns TRUE upon success, FALSE
+otherwise. See example under die().
+
+=item chmod LIST
+
+Changes the permissions of a list of files. The first element of the
+list must be the numerical mode. Returns the number of files
+successfully changed.
+
+ $cnt = chmod 0755, 'foo', 'bar';
+ chmod 0755, @executables;
+
+=item chomp VARIABLE
+
+=item chomp LIST
+
+=item chomp
+
+This is a slightly safer version of chop (see below). It removes any
+line ending that corresponds to the current value of C<$/> (also known as
+$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the number
+of characters removed. It's often used to remove the newline from the
+end of an input record when you're worried that the final record may be
+missing its newline. When in paragraph mode (C<$/ = "">), it removes all
+trailing newlines from the string. If VARIABLE is omitted, it chomps
+$_. Example:
+
+ while (<>) {
+ chomp; # avoid \n on last field
+ @array = split(/:/);
+ ...
+ }
+
+You can actually chomp anything that's an lvalue, including an assignment:
+
+ chomp($cwd = `pwd`);
+ chomp($answer = <STDIN>);
+
+If you chomp a list, each element is chomped, and the total number of
+characters removed is returned.
+
+=item chop VARIABLE
+
+=item chop LIST
+
+=item chop
+
+Chops off the last character of a string and returns the character
+chopped. It's used primarily to remove the newline from the end of an
+input record, but is much more efficient than C<s/\n//> because it neither
+scans nor copies the string. If VARIABLE is omitted, chops $_.
+Example:
+
+ while (<>) {
+ chop; # avoid \n on last field
+ @array = split(/:/);
+ ...
+ }
+
+You can actually chop anything that's an lvalue, including an assignment:
+
+ chop($cwd = `pwd`);
+ chop($answer = <STDIN>);
+
+If you chop a list, each element is chopped. Only the value of the
+last chop is returned.
+
+=item chown LIST
+
+Changes the owner (and group) of a list of files. The first two
+elements of the list must be the I<NUMERICAL> uid and gid, in that order.
+Returns the number of files successfully changed.
+
+ $cnt = chown $uid, $gid, 'foo', 'bar';
+ chown $uid, $gid, @filenames;
+
+Here's an example that looks up non-numeric uids in the passwd file:
+
+ print "User: ";
+ chop($user = <STDIN>);
+ print "Files: "
+ chop($pattern = <STDIN>);
+
+ ($login,$pass,$uid,$gid) = getpwnam($user)
+ or die "$user not in passwd file";
+
+ @ary = <${pattern}>; # expand filenames
+ chown $uid, $gid, @ary;
+
+=item chr NUMBER
+
+Returns the character represented by that NUMBER in the character set.
+For example, C<chr(65)> is "A" in ASCII.
+
+=item chroot FILENAME
+
+Does the same as the system call of that name. If you don't know what
+it does, don't worry about it. If FILENAME is omitted, does chroot to
+$_.
+
+=item close FILEHANDLE
+
+Closes the file or pipe associated with the file handle, returning TRUE
+only if stdio successfully flushes buffers and closes the system file
+descriptor. You don't have to close FILEHANDLE if you are immediately
+going to do another open on it, since open will close it for you. (See
+open().) However, an explicit close on an input file resets the line
+counter ($.), while the implicit close done by open() does not. Also,
+closing a pipe will wait for the process executing on the pipe to
+complete, in case you want to look at the output of the pipe
+afterwards. Closing a pipe explicitly also puts the status value of
+the command into C<$?>. Example:
+
+ open(OUTPUT, '|sort >foo'); # pipe to sort
+ ... # print stuff to output
+ close OUTPUT; # wait for sort to finish
+ open(INPUT, 'foo'); # get sort's results
+
+FILEHANDLE may be an expression whose value gives the real filehandle name.
+
+=item closedir DIRHANDLE
+
+Closes a directory opened by opendir().
+
+=item connect SOCKET,NAME
+
+Attempts to connect to a remote socket, just as the connect system call
+does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a
+package address of the appropriate type for the socket. See example in
+L<perlipc>.
+
+=item cos EXPR
+
+Returns the cosine of EXPR (expressed in radians). If EXPR is omitted
+takes cosine of $_.
+
+=item crypt PLAINTEXT,SALT
+
+Encrypts a string exactly like the crypt(3) function in the C library.
+Useful for checking the password file for lousy passwords, amongst
+other things. Only the guys wearing white hats should do this.
+
+Here's an example that makes sure that whoever runs this program knows
+their own password:
+
+ $pwd = (getpwuid($<))[1];
+ $salt = substr($pwd, 0, 2);
+
+ system "stty -echo";
+ print "Password: ";
+ chop($word = <STDIN>);
+ print "\n";
+ system "stty echo";
+
+ if (crypt($word, $salt) ne $pwd) {
+ die "Sorry...\n";
+ } else {
+ print "ok\n";
+ }
+
+Of course, typing in your own password to whoever asks you
+for it is unwise at best.
+
+=item dbmclose ASSOC_ARRAY
+
+[This function has been superseded by the untie() function.]
+
+Breaks the binding between a DBM file and an associative array.
+
+=item dbmopen ASSOC,DBNAME,MODE
+
+[This function has been superseded by the tie() function.]
+
+This binds a dbm(3) or ndbm(3) file to an associative array. ASSOC is the
+name of the associative array. (Unlike normal open, the first argument
+is I<NOT> a filehandle, even though it looks like one). DBNAME is the
+name of the database (without the F<.dir> or F<.pag> extension). If the
+database does not exist, it is created with protection specified by
+MODE (as modified by the umask()). If your system only supports the
+older DBM functions, you may perform only one dbmopen() in your program.
+If your system has neither DBM nor ndbm, calling dbmopen() produces a
+fatal error.
+
+If you don't have write access to the DBM file, you can only read
+associative array variables, not set them. If you want to test whether
+you can write, either use file tests or try setting a dummy array entry
+inside an eval(), which will trap the error.
+
+Note that functions such as keys() and values() may return huge array
+values when used on large DBM files. You may prefer to use the each()
+function to iterate over large DBM files. Example:
+
+ # print out history file offsets
+ dbmopen(%HIST,'/usr/lib/news/history',0666);
+ while (($key,$val) = each %HIST) {
+ print $key, ' = ', unpack('L',$val), "\n";
+ }
+ dbmclose(%HIST);
+
+=item defined EXPR
+
+Returns a boolean value saying whether the lvalue EXPR has a real value
+or not. Many operations return the undefined value under exceptional
+conditions, such as end of file, uninitialized variable, system error
+and such. This function allows you to distinguish between an undefined
+null scalar and a defined null scalar with operations that might return
+a real null string, such as referencing elements of an array. You may
+also check to see if arrays or subroutines exist. Use of defined on
+predefined variables is not guaranteed to produce intuitive results.
+
+When used on a hash array element, it tells you whether the value
+is defined, not whether the key exists in the hash. Use exists() for that.
+
+Examples:
+
+ print if defined $switch{'D'};
+ print "$val\n" while defined($val = pop(@ary));
+ die "Can't readlink $sym: $!"
+ unless defined($value = readlink $sym);
+ eval '@foo = ()' if defined(@foo);
+ die "No XYZ package defined" unless defined %_XYZ;
+ sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
+
+See also undef().
+
+=item delete EXPR
+
+Deletes the specified value from its hash array. Returns the deleted
+value, or the undefined value if nothing was deleted. Deleting from
+C<$ENV{}> modifies the environment. Deleting from an array tied to a DBM
+file deletes the entry from the DBM file. (But deleting from a tie()d
+hash doesn't necessarily return anything.)
+
+The following deletes all the values of an associative array:
+
+ foreach $key (keys %ARRAY) {
+ delete $ARRAY{$key};
+ }
+
+(But it would be faster to use the undef() command.) Note that the
+EXPR can be arbitrarily complicated as long as the final operation is
+a hash key lookup:
+
+ delete $ref->[$x][$y]{$key};
+
+=item die LIST
+
+Outside of an eval(), prints the value of LIST to C<STDERR> and exits with
+the current value of $! (errno). If $! is 0, exits with the value of
+C<($? E<gt>E<gt> 8)> (`command` status). If C<($? E<gt>E<gt> 8)> is 0,
+exits with 255. Inside an eval(), the error message is stuffed into C<$@>.
+and the eval() is terminated with the undefined value.
+
+Equivalent examples:
+
+ die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
+ chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
+
+If the value of EXPR does not end in a newline, the current script line
+number and input line number (if any) are also printed, and a newline
+is supplied. Hint: sometimes appending ", stopped" to your message
+will cause it to make better sense when the string "at foo line 123" is
+appended. Suppose you are running script "canasta".
+
+ die "/etc/games is no good";
+ die "/etc/games is no good, stopped";
+
+produce, respectively
+
+ /etc/games is no good at canasta line 123.
+ /etc/games is no good, stopped at canasta line 123.
+
+See also exit() and warn().
+
+=item do BLOCK
+
+Not really a function. Returns the value of the last command in the
+sequence of commands indicated by BLOCK. When modified by a loop
+modifier, executes the BLOCK once before testing the loop condition.
+(On other statements the loop modifiers test the conditional first.)
+
+=item do SUBROUTINE(LIST)
+
+A deprecated form of subroutine call. See L<perlsub>.
+
+=item do EXPR
+
+Uses the value of EXPR as a filename and executes the contents of the
+file as a Perl script. Its primary use is to include subroutines
+from a Perl subroutine library.
+
+ do 'stat.pl';
+
+is just like
+
+ eval `cat stat.pl`;
+
+except that it's more efficient, more concise, keeps track of the
+current filename for error messages, and searches all the B<-I>
+libraries if the file isn't in the current directory (see also the @INC
+array in L<perlvar/Predefined Names>). It's the same, however, in that it does
+reparse the file every time you call it, so you probably don't want to
+do this inside a loop.
+
+Note that inclusion of library modules is better done with the
+use() and require() operators.
+
+=item dump LABEL
+
+This causes an immediate core dump. Primarily this is so that you can
+use the B<undump> program to turn your core dump into an executable binary
+after having initialized all your variables at the beginning of the
+program. When the new binary is executed it will begin by executing a
+C<goto LABEL> (with all the restrictions that C<goto> suffers). Think of
+it as a goto with an intervening core dump and reincarnation. If LABEL
+is omitted, restarts the program from the top. WARNING: any files
+opened at the time of the dump will NOT be open any more when the
+program is reincarnated, with possible resulting confusion on the part
+of Perl. See also B<-u> option in L<perlrun>.
+
+Example:
+
+ #!/usr/bin/perl
+ require 'getopt.pl';
+ require 'stat.pl';
+ %days = (
+ 'Sun' => 1,
+ 'Mon' => 2,
+ 'Tue' => 3,
+ 'Wed' => 4,
+ 'Thu' => 5,
+ 'Fri' => 6,
+ 'Sat' => 7,
+ );
+
+ dump QUICKSTART if $ARGV[0] eq '-d';
+
+ QUICKSTART:
+ Getopt('f');
+
+=item each ASSOC_ARRAY
+
+Returns a 2 element array consisting of the key and value for the next
+value of an associative array, so that you can iterate over it.
+Entries are returned in an apparently random order. When the array is
+entirely read, a null array is returned (which when assigned produces a
+FALSE (0) value). The next call to each() after that will start
+iterating again. The iterator can be reset only by reading all the
+elements from the array. You should not add elements to an array while
+you're iterating over it. There is a single iterator for each
+associative array, shared by all each(), keys() and values() function
+calls in the program. The following prints out your environment like
+the printenv(1) program, only in a different order:
+
+ while (($key,$value) = each %ENV) {
+ print "$key=$value\n";
+ }
+
+See also keys() and values().
+
+=item eof FILEHANDLE
+
+=item eof
+
+Returns 1 if the next read on FILEHANDLE will return end of file, or if
+FILEHANDLE is not open. FILEHANDLE may be an expression whose value
+gives the real filehandle name. (Note that this function actually
+reads a character and then ungetc()s it, so it is not very useful in an
+interactive context.) An C<eof> without an argument returns the eof status
+for the last file read. Empty parentheses () may be used to indicate
+the pseudo file formed of the files listed on the command line, i.e.
+C<eof()> is reasonable to use inside a while (<>) loop to detect the end
+of only the last file. Use C<eof(ARGV)> or eof without the parentheses to
+test I<EACH> file in a while (<>) loop. Examples:
+
+ # insert dashes just before last line of last file
+ while (<>) {
+ if (eof()) {
+ print "--------------\n";
+ }
+ print;
+ }
+
+ # reset line numbering on each input file
+ while (<>) {
+ print "$.\t$_";
+ if (eof) { # Not eof().
+ close(ARGV);
+ }
+ }
+
+Practical hint: you almost never need to use C<eof> in Perl, because the
+input operators return undef when they run out of data.
+
+=item eval EXPR
+
+=item eval BLOCK
+
+EXPR is parsed and executed as if it were a little Perl program. It
+is executed in the context of the current Perl program, so that any
+variable settings, subroutine or format definitions remain afterwards.
+The value returned is the value of the last expression evaluated, or a
+return statement may be used, just as with subroutines.
+
+If there is a syntax error or runtime error, or a die() statement is
+executed, an undefined value is returned by eval(), and C<$@> is set to the
+error message. If there was no error, C<$@> is guaranteed to be a null
+string. If EXPR is omitted, evaluates $_. The final semicolon, if
+any, may be omitted from the expression.
+
+Note that, since eval() traps otherwise-fatal errors, it is useful for
+determining whether a particular feature (such as dbmopen() or symlink())
+is implemented. It is also Perl's exception trapping mechanism, where
+the die operator is used to raise exceptions.
+
+If the code to be executed doesn't vary, you may use the eval-BLOCK
+form to trap run-time errors without incurring the penalty of
+recompiling each time. The error, if any, is still returned in C<$@>.
+Examples:
+
+ # make divide-by-zero non-fatal
+ eval { $answer = $a / $b; }; warn $@ if $@;
+
+ # same thing, but less efficient
+ eval '$answer = $a / $b'; warn $@ if $@;
+
+ # a compile-time error
+ eval { $answer = };
+
+ # a run-time error
+ eval '$answer ='; # sets $@
+
+With an eval(), you should be especially careful to remember what's
+being looked at when:
+
+ eval $x; # CASE 1
+ eval "$x"; # CASE 2
+
+ eval '$x'; # CASE 3
+ eval { $x }; # CASE 4
+
+ eval "\$$x++" # CASE 5
+ $$x++; # CASE 6
+
+Cases 1 and 2 above behave identically: they run the code contained in the
+variable $x. (Although case 2 has misleading double quotes making the
+reader wonder what else might be happening (nothing is).) Cases 3 and 4
+likewise behave in the same way: they run the code <$x>, which does
+nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5
+is a place where normally you I<WOULD> like to use double quotes, except
+that in particular situation, you can just use symbolic references
+instead, as in case 6.
+
+=item exec LIST
+
+The exec() function executes a system command I<AND NEVER RETURNS>. Use
+the system() function if you want it to return.
+
+If there is more than one argument in LIST, or if LIST is an array with
+more than one value, calls execvp(3) with the arguments in LIST. If
+there is only one scalar argument, the argument is checked for shell
+metacharacters. If there are any, the entire argument is passed to
+C</bin/sh -c> for parsing. If there are none, the argument is split
+into words and passed directly to execvp(), which is more efficient.
+Note: exec() (and system(0) do not flush your output buffer, so you may
+need to set C<$|> to avoid lost output. Examples:
+
+ exec '/bin/echo', 'Your arguments are: ', @ARGV;
+ exec "sort $outfile | uniq";
+
+If you don't really want to execute the first argument, but want to lie
+to the program you are executing about its own name, you can specify
+the program you actually want to run as an "indirect object" (without a
+comma) in front of the LIST. (This always forces interpretation of the
+LIST as a multi-valued list, even if there is only a single scalar in
+the list.) Example:
+
+ $shell = '/bin/csh';
+ exec $shell '-sh'; # pretend it's a login shell
+
+or, more directly,
+
+ exec {'/bin/csh'} '-sh'; # pretend it's a login shell
+
+=item exists EXPR
+
+Returns TRUE if the specified hash key exists in its hash array, even
+if the corresponding value is undefined.
+
+ print "Exists\n" if exists $array{$key};
+ print "Defined\n" if defined $array{$key};
+ print "True\n" if $array{$key};
+
+A hash element can only be TRUE if it's defined, and defined if
+it exists, but the reverse doesn't necessarily hold true.
+
+Note that the EXPR can be arbitrarily complicated as long as the final
+operation is a hash key lookup:
+
+ if (exists $ref->[$x][$y]{$key}) { ... }
+
+=item exit EXPR
+
+Evaluates EXPR and exits immediately with that value. (Actually, it
+calls any defined C<END> routines first, but the C<END> routines may not
+abort the exit. Likewise any object destructors that need to be called
+are called before exit.) Example:
+
+ $ans = <STDIN>;
+ exit 0 if $ans =~ /^[Xx]/;
+
+See also die(). If EXPR is omitted, exits with 0 status.
+
+=item exp EXPR
+
+Returns I<e> (the natural logarithm base) to the power of EXPR.
+If EXPR is omitted, gives C<exp($_)>.
+
+=item fcntl FILEHANDLE,FUNCTION,SCALAR
+
+Implements the fcntl(2) function. You'll probably have to say
+
+ use Fcntl;
+
+first to get the correct function definitions. Argument processing and
+value return works just like ioctl() below. Note that fcntl() will produce
+a fatal error if used on a machine that doesn't implement fcntl(2).
+For example:
+
+ use Fcntl;
+ fcntl($filehandle, F_GETLK, $packed_return_buffer);
+
+=item fileno FILEHANDLE
+
+Returns the file descriptor for a filehandle. This is useful for
+constructing bitmaps for select(). If FILEHANDLE is an expression, the
+value is taken as the name of the filehandle.
+
+=item flock FILEHANDLE,OPERATION
+
+Calls flock(2) on FILEHANDLE. See L<flock(2)> for
+definition of OPERATION. Returns TRUE for success, FALSE on failure.
+Will produce a fatal error if used on a machine that doesn't implement
+flock(2). Here's a mailbox appender for BSD systems.
+
+ $LOCK_SH = 1;
+ $LOCK_EX = 2;
+ $LOCK_NB = 4;
+ $LOCK_UN = 8;
+
+ sub lock {
+ flock(MBOX,$LOCK_EX);
+ # and, in case someone appended
+ # while we were waiting...
+ seek(MBOX, 0, 2);
+ }
+
+ sub unlock {
+ flock(MBOX,$LOCK_UN);
+ }
+
+ open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
+ or die "Can't open mailbox: $!";
+
+ lock();
+ print MBOX $msg,"\n\n";
+ unlock();
+
+Note that flock() can't lock things over the network. You need to do
+locking with fcntl() for that.
+
+=item fork
+
+Does a fork(2) system call. Returns the child pid to the parent process
+and 0 to the child process, or undef if the fork is unsuccessful.
+Note: unflushed buffers remain unflushed in both processes, which means
+you may need to set C<$|> ($AUTOFLUSH in English) or call the
+autoflush() FileHandle method to avoid duplicate output.
+
+If you fork() without ever waiting on your children, you will accumulate
+zombies:
+
+ $SIG{'CHLD'} = sub { wait };
+
+There's also the double-fork trick (error checking on
+fork() returns omitted);
+
+ unless ($pid = fork) {
+ unless (fork) {
+ exec "what you really wanna do";
+ die "no exec";
+ # ... or ...
+ some_perl_code_here;
+ exit 0;
+ }
+ exit 0;
+ }
+ waitpid($pid,0);
+
+
+=item formline PICTURE, LIST
+
+This is an internal function used by formats, though you may call it
+too. It formats (see L<perlform>) a list of values according to the
+contents of PICTURE, placing the output into the format output
+accumulator, C<$^A>. Eventually, when a write() is done, the contents of
+C<$^A> are written to some filehandle, but you could also read C<$^A>
+yourself and then set C<$^A> back to "". Note that a format typically
+does one formline() per line of form, but the formline() function itself
+doesn't care how many newlines are embedded in the PICTURE. Be careful
+if you put double quotes around the picture, since an "C<@>" character may
+be taken to mean the beginning of an array name. formline() always
+returns TRUE.
+
+=item getc FILEHANDLE
+
+=item getc
+
+Returns the next character from the input file attached to FILEHANDLE,
+or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN.
+
+=item getlogin
+
+Returns the current login from F</etc/utmp>, if any. If null, use
+getpwuid().
+
+ $login = getlogin || (getpwuid($<))[0] || "Kilroy";
+
+=item getpeername SOCKET
+
+Returns the packed sockaddr address of other end of the SOCKET connection.
+
+ # An internet sockaddr
+ $sockaddr = 'S n a4 x8';
+ $hersockaddr = getpeername(S);
+ ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
+
+=item getpgrp PID
+
+Returns the current process group for the specified PID, 0 for the
+current process. Will produce a fatal error if used on a machine that
+doesn't implement getpgrp(2). If PID is omitted, returns process
+group of current process.
+
+=item getppid
+
+Returns the process id of the parent process.
+
+=item getpriority WHICH,WHO
+
+Returns the current priority for a process, a process group, or a
+user. (See L<getpriority(2)>.) Will produce a fatal error if used on a
+machine that doesn't implement getpriority(2).
+
+=item getpwnam NAME
+
+=item getgrnam NAME
+
+=item gethostbyname NAME
+
+=item getnetbyname NAME
+
+=item getprotobyname NAME
+
+=item getpwuid UID
+
+=item getgrgid GID
+
+=item getservbyname NAME,PROTO
+
+=item gethostbyaddr ADDR,ADDRTYPE
+
+=item getnetbyaddr ADDR,ADDRTYPE
+
+=item getprotobynumber NUMBER
+
+=item getservbyport PORT,PROTO
+
+=item getpwent
+
+=item getgrent
+
+=item gethostent
+
+=item getnetent
+
+=item getprotoent
+
+=item getservent
+
+=item setpwent
+
+=item setgrent
+
+=item sethostent STAYOPEN
+
+=item setnetent STAYOPEN
+
+=item setprotoent STAYOPEN
+
+=item setservent STAYOPEN
+
+=item endpwent
+
+=item endgrent
+
+=item endhostent
+
+=item endnetent
+
+=item endprotoent
+
+=item endservent
+
+These routines perform the same functions as their counterparts in the
+system library. Within a list context, the return values from the
+various get routines are as follows:
+
+ ($name,$passwd,$uid,$gid,
+ $quota,$comment,$gcos,$dir,$shell) = getpw*
+ ($name,$passwd,$gid,$members) = getgr*
+ ($name,$aliases,$addrtype,$length,@addrs) = gethost*
+ ($name,$aliases,$addrtype,$net) = getnet*
+ ($name,$aliases,$proto) = getproto*
+ ($name,$aliases,$port,$proto) = getserv*
+
+(If the entry doesn't exist you get a null list.)
+
+Within a 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:
+
+ $uid = getpwnam
+ $name = getpwuid
+ $name = getpwent
+ $gid = getgrnam
+ $name = getgrgid
+ $name = getgrent
+ etc.
+
+The $members value returned by I<getgr*()> is a space separated list of
+the login names of the members of the group.
+
+For the I<gethost*()> functions, if the C<h_errno> variable is supported in
+C, it will be returned to you via C<$?> if the function call fails. The
+@addrs value returned by a successful call is a list of the raw
+addresses returned by the corresponding system library call. In the
+Internet domain, each address is four bytes long and you can unpack it
+by saying something like:
+
+ ($a,$b,$c,$d) = unpack('C4',$addr[0]);
+
+=item getsockname SOCKET
+
+Returns the packed sockaddr address of this end of the SOCKET connection.
+
+ # An internet sockaddr
+ $sockaddr = 'S n a4 x8';
+ $mysockaddr = getsockname(S);
+ ($family, $port, $myaddr) =
+ unpack($sockaddr,$mysockaddr);
+
+=item getsockopt SOCKET,LEVEL,OPTNAME
+
+Returns the socket option requested, or undefined if there is an error.
+
+=item glob EXPR
+
+Returns the value of EXPR with filename expansions such as a shell
+would do. This is the internal function implementing the <*.*>
+operator.
+
+=item gmtime EXPR
+
+Converts a time as returned by the time function to a 9-element array
+with the time analyzed for the Greenwich timezone. Typically used as
+follows:
+
+
+ ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
+ gmtime(time);
+
+All array elements are numeric, and come straight out of a struct tm.
+In particular this means that $mon has the range 0..11 and $wday has
+the range 0..6. If EXPR is omitted, does C<gmtime(time())>.
+
+=item goto LABEL
+
+=item goto &NAME
+
+The goto-LABEL form finds the statement labeled with LABEL and resumes
+execution there. It may not be used to go into any construct that
+requires initialization, such as a subroutine or a foreach loop. It
+also can't be used to go into a construct that is optimized away. It
+can be used to go almost anywhere else within the dynamic scope,
+including out of subroutines, but it's usually better to use some other
+construct such as last or die. The author of Perl has never felt the
+need to use this form of goto (in Perl, that is--C is another matter).
+
+The goto-&NAME form is highly magical, and substitutes a call to the
+named subroutine for the currently running subroutine. This is used by
+AUTOLOAD subroutines that wish to load another subroutine and then
+pretend that the other subroutine had been called in the first place
+(except that any modifications to @_ in the current subroutine are
+propagated to the other subroutine.) After the goto, not even caller()
+will be able to tell that this routine was called first.
+
+=item grep BLOCK LIST
+
+=item grep EXPR,LIST
+
+Evaluates the BLOCK or EXPR for each element of LIST (locally setting
+$_ to each element) and returns the list value consisting of those
+elements for which the expression evaluated to TRUE. In a scalar
+context, returns the number of times the expression was TRUE.
+
+ @foo = grep(!/^#/, @bar); # weed out comments
+
+or equivalently,
+
+ @foo = grep {!/^#/} @bar; # weed out comments
+
+Note that, since $_ is a reference into the list value, it can be used
+to modify the elements of the array. While this is useful and
+supported, it can cause bizarre results if the LIST is not a named
+array.
+
+=item hex EXPR
+
+Returns the decimal value of EXPR interpreted as an hex string. (To
+interpret strings that might start with 0 or 0x see oct().) If EXPR is
+omitted, uses $_.
+
+=item import
+
+There is no built-in import() function. It is merely an ordinary
+method subroutine defined (or inherited) by modules that wish to export
+names to another module. The use() function calls the import() method
+for the package used. See also L</use> below and L<perlmod>.
+
+=item index STR,SUBSTR,POSITION
+
+=item index STR,SUBSTR
+
+Returns the position of the first occurrence of SUBSTR in STR at or
+after POSITION. If POSITION is omitted, starts searching from the
+beginning of the string. The return value is based at 0, or whatever
+you've set the $[ variable to. If the substring is not found, returns
+one less than the base, ordinarily -1.
+
+=item int EXPR
+
+Returns the integer portion of EXPR. If EXPR is omitted, uses $_.
+
+=item ioctl FILEHANDLE,FUNCTION,SCALAR
+
+Implements the ioctl(2) function. You'll probably have to say
+
+ require "ioctl.ph"; # probably /usr/local/lib/perl/ioctl.ph
+
+first to get the correct function definitions. If ioctl.ph doesn't
+exist or doesn't have the correct definitions you'll have to roll your
+own, based on your C header files such as <sys/ioctl.h>. (There is a
+Perl script called B<h2ph> that comes with the Perl kit which may help you
+in this.) SCALAR will be read and/or written depending on the
+FUNCTION--a pointer to the string value of SCALAR will be passed as the
+third argument of the actual ioctl call. (If SCALAR has no string
+value but does have a numeric value, that value will be passed rather
+than a pointer to the string value. To guarantee this to be TRUE, add
+a 0 to the scalar before using it.) The pack() and unpack() functions
+are useful for manipulating the values of structures used by ioctl().
+The following example sets the erase character to DEL.
+
+ require 'ioctl.ph';
+ $sgttyb_t = "ccccs"; # 4 chars and a short
+ if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
+ @ary = unpack($sgttyb_t,$sgttyb);
+ $ary[2] = 127;
+ $sgttyb = pack($sgttyb_t,@ary);
+ ioctl(STDIN,$TIOCSETP,$sgttyb)
+ || die "Can't ioctl: $!";
+ }
+
+The return value of ioctl (and fcntl) is as follows:
+
+ if OS returns: then Perl returns:
+ -1 undefined value
+ 0 string "0 but true"
+ anything else that number
+
+Thus Perl returns TRUE on success and FALSE on failure, yet you can
+still easily determine the actual value returned by the operating
+system:
+
+ ($retval = ioctl(...)) || ($retval = -1);
+ printf "System returned %d\n", $retval;
+
+=item join EXPR,LIST
+
+Joins the separate strings of LIST or ARRAY into a single string with
+fields separated by the value of EXPR, and returns the string.
+Example:
+
+ $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
+
+See L<perlfunc/split>.
+
+=item keys ASSOC_ARRAY
+
+Returns a normal array consisting of all the keys of the named
+associative array. (In a scalar context, returns the number of keys.)
+The keys are returned in an apparently random order, but it is the same
+order as either the values() or each() function produces (given that
+the associative array has not been modified). Here is yet another way
+to print your environment:
+
+ @keys = keys %ENV;
+ @values = values %ENV;
+ while ($#keys >= 0) {
+ print pop(@keys), '=', pop(@values), "\n";
+ }
+
+or how about sorted by key:
+
+ foreach $key (sort(keys %ENV)) {
+ print $key, '=', $ENV{$key}, "\n";
+ }
+
+=item kill LIST
+
+Sends a signal to a list of processes. The first element of the list
+must be the signal to send. Returns the number of processes
+successfully signaled.
+
+ $cnt = kill 1, $child1, $child2;
+ kill 9, @goners;
+
+Unlike in the shell, in Perl
+if the I<SIGNAL> is negative, it kills process groups instead of processes.
+(On System V, a negative I<PROCESS> number will also kill process
+groups, but that's not portable.) That means you usually want to use
+positive not negative signals. You may also use a signal name in quotes.
+
+=item last LABEL
+
+=item last
+
+The C<last> command is like the C<break> statement in C (as used in
+loops); it immediately exits the loop in question. If the LABEL is
+omitted, the command refers to the innermost enclosing loop. The
+C<continue> block, if any, is not executed:
+
+ line: while (<STDIN>) {
+ last line if /^$/; # exit when done with header
+ ...
+ }
+
+=item lc EXPR
+
+Returns an lowercased version of EXPR. This is the internal function
+implementing the \L escape in double-quoted strings.
+
+=item lcfirst EXPR
+
+Returns the value of EXPR with the first character lowercased. This is
+the internal function implementing the \l escape in double-quoted strings.
+
+=item length EXPR
+
+Returns the length in characters of the value of EXPR. If EXPR is
+omitted, returns length of $_.
+
+=item link OLDFILE,NEWFILE
+
+Creates a new filename linked to the old filename. Returns 1 for
+success, 0 otherwise.
+
+=item listen SOCKET,QUEUESIZE
+
+Does the same thing that the listen system call does. Returns TRUE if
+it succeeded, FALSE otherwise. See example in L<perlipc>.
+
+=item local EXPR
+
+In general, you should be using "my" instead of "local", because it's
+faster and safer. Format variables have to use "local" though, as
+do any other variables whose local value must be visible to called
+subroutines. This is known as dynamic scoping. Lexical scoping is
+done with "my", which works more like C's auto declarations.
+
+A local modifies the listed variables to be local to the enclosing block,
+subroutine, eval or "do". If more than one value is listed, the list
+must be placed in parens. All the listed elements must be legal
+lvalues. This operator works by saving the current values of those
+variables in LIST on a hidden stack and restoring them upon exiting the
+block, subroutine or eval. This means that called subroutines can also
+reference the local variable, but not the global one. The LIST may be
+assigned to if desired, which allows you to initialize your local
+variables. (If no initializer is given for a particular variable, it
+is created with an undefined value.) Commonly this is used to name the
+parameters to a subroutine. Examples:
+
+ sub RANGEVAL {
+ local($min, $max, $thunk) = @_;
+ local $result = '';
+ local $i;
+
+ # Presumably $thunk makes reference to $i
+
+ for ($i = $min; $i < $max; $i++) {
+ $result .= eval $thunk;
+ }
+
+ $result;
+ }
+
+
+ if ($sw eq '-v') {
+ # init local array with global array
+ local @ARGV = @ARGV;
+ unshift(@ARGV,'echo');
+ system @ARGV;
+ }
+ # @ARGV restored
+
+
+ # temporarily add to digits associative array
+ if ($base12) {
+ # (NOTE: not claiming this is efficient!)
+ local(%digits) = (%digits,'t',10,'e',11);
+ parse_num();
+ }
+
+Note that local() is a run-time command, and so gets executed every
+time through a loop. In Perl 4 it used up more stack storage each
+time until the loop was exited. Perl 5 reclaims the space each time
+through, but it's still more efficient to declare your variables
+outside the loop.
+
+When you assign to a localized EXPR, the local doesn't change whether
+EXPR is viewed as a scalar or an array. So
+
+ local($foo) = <STDIN>;
+ local @FOO = <STDIN>;
+
+both supply a list context to the righthand side, while
+
+ local $foo = <STDIN>;
+
+supplies a scalar context.
+
+=item localtime EXPR
+
+Converts a time as returned by the time function to a 9-element array
+with the time analyzed for the local timezone. Typically used as
+follows:
+
+ ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
+ localtime(time);
+
+All array elements are numeric, and come straight out of a struct tm.
+In particular this means that $mon has the range 0..11 and $wday has
+the range 0..6. If EXPR is omitted, does localtime(time).
+
+In a scalar context, prints out the ctime(3) value:
+
+ $now_string = localtime; # e.g. "Thu Oct 13 04:54:34 1994"
+
+See also L<perlmod/timelocal> and the strftime(3) function available
+via the POSIX modulie.
+
+=item log EXPR
+
+Returns logarithm (base I<e>) of EXPR. If EXPR is omitted, returns log
+of $_.
+
+=item lstat FILEHANDLE
+
+=item lstat EXPR
+
+Does the same thing as the stat() function, but stats a symbolic link
+instead of the file the symbolic link points to. If symbolic links are
+unimplemented on your system, a normal stat() is done.
+
+=item m//
+
+The match operator. See L<perlop>.
+
+=item map BLOCK LIST
+
+=item map EXPR,LIST
+
+Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each
+element) and returns the list value composed of the results of each such
+evaluation. Evaluates BLOCK or EXPR in a list context, so each element of LIST
+may produce zero, one, or more elements in the returned value.
+
+ @chars = map(chr, @nums);
+
+translates a list of numbers to the corresponding characters. And
+
+ %hash = map {&key($_), $_} @array;
+
+is just a funny way to write
+
+ %hash = ();
+ foreach $_ (@array) {
+ $hash{&key($_)} = $_;
+ }
+
+=item mkdir FILENAME,MODE
+
+Creates the directory specified by FILENAME, with permissions specified
+by MODE (as modified by umask). If it succeeds it returns 1, otherwise
+it returns 0 and sets $! (errno).
+
+=item msgctl ID,CMD,ARG
+
+Calls the System V IPC function msgctl. If CMD is &IPC_STAT, then ARG
+must be a variable which will hold the returned msqid_ds structure.
+Returns like ioctl: the undefined value for error, "0 but true" for
+zero, or the actual return value otherwise.
+
+=item msgget KEY,FLAGS
+
+Calls the System V IPC function msgget. Returns the message queue id,
+or the undefined value if there is an error.
+
+=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 long integer message type,
+which may be created with C<pack("L", $type)>. Returns TRUE if
+successful, or FALSE if there is an error.
+
+=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.
+
+=item my EXPR
+
+A "my" declares the listed variables to be local (lexically) to the
+enclosing block, subroutine, eval or "do". If more than one value is
+listed, the list must be placed in parens. All the listed elements
+must be legal lvalues. Only alphanumeric identifiers may be lexically
+scoped--magical builtins like $/ must be localized with "local"
+instead. In particular, you're not allowed to say
+
+ my $_; # Illegal.
+
+Unlike the "local" declaration, variables declared with "my"
+are totally hidden from the outside world, including any called
+subroutines (even if it's the same subroutine--every call gets its own
+copy).
+
+(An eval(), however, can see the lexical variables of the scope it is
+being evaluated in so long as the names aren't hidden by declarations within
+the eval() itself. See L<perlref>.)
+
+The EXPR may be assigned to if desired, which allows you to initialize
+your variables. (If no initializer is given for a particular
+variable, it is created with an undefined value.) Commonly this is
+used to name the parameters to a subroutine. Examples:
+
+ sub RANGEVAL {
+ my($min, $max, $thunk) = @_;
+ my $result = '';
+ my $i;
+
+ # Presumably $thunk makes reference to $i
+
+ for ($i = $min; $i < $max; $i++) {
+ $result .= eval $thunk;
+ }
+
+ $result;
+ }
+
+
+ if ($sw eq '-v') {
+ # init my array with global array
+ my @ARGV = @ARGV;
+ unshift(@ARGV,'echo');
+ system @ARGV;
+ }
+ # Outer @ARGV again visible
+
+When you assign to the EXPR, the "my" doesn't change whether
+EXPR is viewed as a scalar or an array. So
+
+ my($foo) = <STDIN>;
+ my @FOO = <STDIN>;
+
+both supply a list context to the righthand side, while
+
+ my $foo = <STDIN>;
+
+supplies a scalar context.
+
+Some users may wish to encourage the use of lexically scoped variables.
+As an aid to catching implicit references to package variables,
+if you say
+
+ use strict 'vars';
+
+then any variable reference from there to the end of the enclosing
+block must either refer to a lexical variable, or must be fully
+qualified with the package name. A compilation error results
+otherwise. An inner block may countermand this with S<"no strict 'vars'">.
+
+=item next LABEL
+
+=item next
+
+The C<next> command is like the C<continue> statement in C; it starts
+the next iteration of the loop:
+
+ line: while (<STDIN>) {
+ next line if /^#/; # discard comments
+ ...
+ }
+
+Note that if there were a C<continue> block on the above, it would get
+executed even on discarded lines. If the LABEL is omitted, the command
+refers to the innermost enclosing loop.
+
+=item no Module LIST
+
+See the "use" function, which "no" is the opposite of.
+
+=item oct EXPR
+
+Returns the decimal value of EXPR interpreted as an octal string. (If
+EXPR happens to start off with 0x, interprets it as a hex string
+instead.) The following will handle decimal, octal, and hex in the
+standard Perl or C notation:
+
+ $val = oct($val) if $val =~ /^0/;
+
+If EXPR is omitted, uses $_.
+
+=item open FILEHANDLE,EXPR
+
+=item open FILEHANDLE
+
+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
+variable of the same name as the FILEHANDLE contains the filename. If
+the filename begins with "<" or nothing, the file is opened for input.
+If the filename begins with ">", the file is opened for output. If the
+filename begins with ">>", the file is opened for appending. (You can
+put a '+' in front of the '>' or '<' to indicate that you want both
+read and write access to the file.) If the filename begins with "|",
+the filename is interpreted as a command to which output is to be
+piped, and if the filename ends with a "|", the filename is interpreted
+as command which pipes input to us. (You may not have a command that
+pipes both in and out.) Opening '-' opens STDIN and opening '>-'
+opens STDOUT. Open returns non-zero upon success, the undefined
+value otherwise. If the open involved a pipe, the return value happens
+to be the pid of the subprocess. Examples:
+
+ $ARTICLE = 100;
+ open ARTICLE or die "Can't find article $ARTICLE: $!\n";
+ while (<ARTICLE>) {...
+
+ open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+
+ open(article, "caesar <$article |"); # decrypt article
+
+ open(extract, "|sort >/tmp/Tmp$$"); # $$ is our process id
+
+ # process argument list of files along with any includes
+
+ foreach $file (@ARGV) {
+ process($file, 'fh00');
+ }
+
+ sub process {
+ local($filename, $input) = @_;
+ $input++; # this is a string increment
+ unless (open($input, $filename)) {
+ print STDERR "Can't open $filename: $!\n";
+ return;
+ }
+
+ while (<$input>) { # note use of indirection
+ if (/^#include "(.*)"/) {
+ process($1, $input);
+ next;
+ }
+ ... # whatever
+ }
+ }
+
+You may also, in the Bourne shell tradition, specify an EXPR beginning
+with ">&", in which case the rest of the string is interpreted as the
+name of a filehandle (or file descriptor, if numeric) which is to be
+duped and opened. You may use & after >, >>, <, +>, +>> and +<. The
+mode you specify should match the mode of the original filehandle.
+Here is a script that saves, redirects, and restores STDOUT and
+STDERR:
+
+ #!/usr/bin/perl
+ open(SAVEOUT, ">&STDOUT");
+ open(SAVEERR, ">&STDERR");
+
+ open(STDOUT, ">foo.out") || die "Can't redirect stdout";
+ open(STDERR, ">&STDOUT") || die "Can't dup stdout";
+
+ select(STDERR); $| = 1; # make unbuffered
+ select(STDOUT); $| = 1; # make unbuffered
+
+ print STDOUT "stdout 1\n"; # this works for
+ print STDERR "stderr 1\n"; # subprocesses too
+
+ close(STDOUT);
+ close(STDERR);
+
+ open(STDOUT, ">&SAVEOUT");
+ open(STDERR, ">&SAVEERR");
+
+ print STDOUT "stdout 2\n";
+ print STDERR "stderr 2\n";
+
+
+If you specify "<&=N", where N is a number, then Perl will do an
+equivalent of C's fdopen() of that file descriptor. For example:
+
+ open(FILEHANDLE, "<&=$fd")
+
+If you open a pipe on the command "-", i.e. either "|-" or "-|", then
+there is an implicit fork done, and the return value of open is the pid
+of the child within the parent process, and 0 within the child
+process. (Use defined($pid) to determine whether the open was successful.)
+The filehandle behaves normally for the parent, but i/o to that
+filehandle is piped from/to the STDOUT/STDIN of the child process.
+In the child process the filehandle isn't opened--i/o happens from/to
+the new STDOUT or STDIN. Typically this is used like the normal
+piped open when you want to exercise more control over just how the
+pipe command gets executed, such as when you are running setuid, and
+don't want to have to scan shell commands for metacharacters. The
+following pairs are more or less equivalent:
+
+ open(FOO, "|tr '[a-z]' '[A-Z]'");
+ open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
+
+ open(FOO, "cat -n '$file'|");
+ open(FOO, "-|") || exec 'cat', '-n', $file;
+
+Explicitly closing any piped filehandle causes the parent process to
+wait for the child to finish, and returns the status value in $?.
+Note: on any operation which may do a fork, unflushed buffers remain
+unflushed in both processes, which means you may need to set $| to
+avoid duplicate output.
+
+The filename that is passed to open will have leading and trailing
+whitespace deleted. In order to open a file with arbitrary weird
+characters in it, it's necessary to protect any leading and trailing
+whitespace thusly:
+
+ $file =~ s#^(\s)#./$1#;
+ open(FOO, "< $file\0");
+
+=item opendir DIRHANDLE,EXPR
+
+Opens a directory named EXPR for processing by readdir(), telldir(),
+seekdir(), rewinddir() and closedir(). Returns TRUE if successful.
+DIRHANDLEs have their own namespace separate from FILEHANDLEs.
+
+=item ord EXPR
+
+Returns the numeric ascii value of the first character of EXPR. If
+EXPR is omitted, uses $_.
+
+=item pack TEMPLATE,LIST
+
+Takes an array or list of values and packs it into a binary structure,
+returning the string containing the structure. The TEMPLATE is a
+sequence of characters that give the order and type of values, as
+follows:
+
+ A An ascii string, will be space padded.
+ a An ascii string, will be null padded.
+ b A bit string (ascending bit order, like vec()).
+ B A bit string (descending bit order).
+ h A hex string (low nybble first).
+ H A hex string (high nybble first).
+
+ c A signed char value.
+ C An unsigned char value.
+ s A signed short value.
+ S An unsigned short value.
+ i A signed integer value.
+ I An unsigned integer value.
+ l A signed long value.
+ L An unsigned long value.
+
+ n A short in "network" order.
+ N A long in "network" order.
+ v A short in "VAX" (little-endian) order.
+ V A long in "VAX" (little-endian) order.
+
+ f A single-precision float in the native format.
+ d A double-precision float in the native format.
+
+ p A pointer to a null-terminated string.
+ P A pointer to a structure (fixed-length string).
+
+ u A uuencoded string.
+
+ x A null byte.
+ X Back up a byte.
+ @ Null fill to absolute position.
+
+Each letter may optionally be followed by a number which gives a repeat
+count. With all types except "a", "A", "b", "B", "h" and "H", and "P" the
+pack function will gobble up that many values from the LIST. A * for the
+repeat count means to use however many items are left. The "a" and "A"
+types gobble just one value, but pack it as a string of length count,
+padding with nulls or spaces as necessary. (When unpacking, "A" strips
+trailing spaces and nulls, but "a" does not.) Likewise, the "b" and "B"
+fields pack a string that many bits long. The "h" and "H" fields pack a
+string that many nybbles long. The "P" packs a pointer to a structure of
+the size indicated by the length. Real numbers (floats and doubles) are
+in the native machine format only; due to the multiplicity of floating
+formats around, and the lack of a standard "network" representation, no
+facility for interchange has been made. This means that packed floating
+point data written on one machine may not be readable on another - even if
+both use IEEE floating point arithmetic (as the endian-ness of the memory
+representation is not part of the IEEE spec). Note that Perl uses doubles
+internally for all numeric calculation, and converting from double into
+float and thence back to double again will lose precision (i.e.
+C<unpack("f", pack("f", $foo)>) will not in general equal $foo).
+
+Examples:
+
+ $foo = pack("cccc",65,66,67,68);
+ # foo eq "ABCD"
+ $foo = pack("c4",65,66,67,68);
+ # same thing
+
+ $foo = pack("ccxxcc",65,66,67,68);
+ # foo eq "AB\0\0CD"
+
+ $foo = pack("s2",1,2);
+ # "\1\0\2\0" on little-endian
+ # "\0\1\0\2" on big-endian
+
+ $foo = pack("a4","abcd","x","y","z");
+ # "abcd"
+
+ $foo = pack("aaaa","abcd","x","y","z");
+ # "axyz"
+
+ $foo = pack("a14","abcdefg");
+ # "abcdefg\0\0\0\0\0\0\0"
+
+ $foo = pack("i9pl", gmtime);
+ # a real struct tm (on my system anyway)
+
+ sub bintodec {
+ unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
+ }
+
+The same template may generally also be used in the unpack function.
+
+=item pipe READHANDLE,WRITEHANDLE
+
+Opens a pair of connected pipes like the corresponding system call.
+Note that if you set up a loop of piped processes, deadlock can occur
+unless you are very careful. In addition, note that Perl's pipes use
+stdio buffering, so you may need to set $| to flush your WRITEHANDLE
+after each command, depending on the application.
+
+=item pop ARRAY
+
+Pops and returns the last value of the array, shortening the array by
+1. Has a similar effect to
+
+ $tmp = $ARRAY[$#ARRAY--];
+
+If there are no elements in the array, returns the undefined value.
+
+=item pos SCALAR
+
+Returns the offset of where the last m//g search left off for the variable
+in question. May be modified to change that offset.
+
+=item print FILEHANDLE LIST
+
+=item print LIST
+
+=item print
+
+Prints a string or a comma-separated list of strings. Returns non-zero
+if successful. FILEHANDLE may be a scalar variable name, in which case
+the variable contains the name of the filehandle, thus introducing one
+level of indirection. (NOTE: If FILEHANDLE is a variable and the next
+token is a term, it may be misinterpreted as an operator unless you
+interpose a + or put parens around the arguments.) If FILEHANDLE is
+omitted, prints by default to standard output (or to the last selected
+output channel--see select()). If LIST is also omitted, prints $_ to
+STDOUT. To set the default output channel to something other than
+STDOUT use the select operation. Note that, because print takes a
+LIST, anything in the LIST is evaluated in a list context, and any
+subroutine that you call will have one or more of its expressions
+evaluated in a list context. Also be careful not to follow the print
+keyword with a left parenthesis unless you want the corresponding right
+parenthesis to terminate the arguments to the print--interpose a + or
+put parens around all the arguments.
+
+=item printf FILEHANDLE LIST
+
+=item printf LIST
+
+Equivalent to a "print FILEHANDLE sprintf(LIST)". The first argument
+of the list will be interpreted as the printf format.
+
+=item push ARRAY,LIST
+
+Treats ARRAY as a stack, and pushes the values of LIST
+onto the end of ARRAY. The length of ARRAY increases by the length of
+LIST. Has the same effect as
+
+ for $value (LIST) {
+ $ARRAY[++$#ARRAY] = $value;
+ }
+
+but is more efficient. Returns the new number of elements in the array.
+
+=item q/STRING/
+
+=item qq/STRING/
+
+=item qx/STRING/
+
+=item qw/STRING/
+
+Generalized quotes. See L<perlop>.
+
+=item quotemeta EXPR
+
+Returns the value of EXPR with with all regular expression
+metacharacters backslashed. This is the internal function implementing
+the \Q escape in double-quoted strings.
+
+=item rand EXPR
+
+=item rand
+
+Returns a random fractional number between 0 and the value of EXPR.
+(EXPR should be positive.) If EXPR is omitted, returns a value between
+0 and 1. This function produces repeatable sequences unless srand()
+is invoked. See also srand().
+
+(Note: if your rand function consistently returns numbers that are too
+large or too small, then your version of Perl was probably compiled
+with the wrong number of RANDBITS. As a workaround, you can usually
+multiply EXPR by the correct power of 2 to get the range you want.
+This will make your script unportable, however. It's better to recompile
+if you can.)
+
+=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
+
+=item read FILEHANDLE,SCALAR,LENGTH
+
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE. Returns the number of bytes actually read, or
+undef if there was an error. SCALAR will be grown or shrunk to the
+length actually read. An OFFSET may be specified to place the read
+data at some other place than the beginning of the string. This call
+is actually implemented in terms of stdio's fread call. To get a true
+read system call, see sysread().
+
+=item readdir DIRHANDLE
+
+Returns the next directory entry for a directory opened by opendir().
+If used in a list context, returns all the rest of the entries in the
+directory. If there are no more entries, returns an undefined value in
+a scalar context or a null list in a list context.
+
+=item readlink EXPR
+
+Returns the value of a symbolic link, if symbolic links are
+implemented. If not, gives a fatal error. If there is some system
+error, returns the undefined value and sets $! (errno). If EXPR is
+omitted, uses $_.
+
+=item recv SOCKET,SCALAR,LEN,FLAGS
+
+Receives a message on a socket. Attempts to receive LENGTH bytes of
+data into variable SCALAR from the specified SOCKET filehandle.
+Actually does a C recvfrom(), so that it can returns the address of the
+sender. Returns the undefined value if there's an error. SCALAR will
+be grown or shrunk to the length actually read. Takes the same flags
+as the system call of the same name.
+
+=item redo LABEL
+
+=item redo
+
+The C<redo> command restarts the loop block without evaluating the
+conditional again. The C<continue> block, if any, is not executed. If
+the LABEL is omitted, the command refers to the innermost enclosing
+loop. This command is normally used by programs that want to lie to
+themselves about what was just input:
+
+ # a simpleminded Pascal comment stripper
+ # (warning: assumes no { or } in strings)
+ line: while (<STDIN>) {
+ while (s|({.*}.*){.*}|$1 |) {}
+ s|{.*}| |;
+ if (s|{.*| |) {
+ $front = $_;
+ while (<STDIN>) {
+ if (/}/) { # end of comment?
+ s|^|$front{|;
+ redo line;
+ }
+ }
+ }
+ print;
+ }
+
+=item ref EXPR
+
+Returns a TRUE value if EXPR is a reference, FALSE otherwise. The value
+returned depends on the type of thing the reference is a reference to.
+Builtin types include:
+
+ REF
+ SCALAR
+ ARRAY
+ HASH
+ CODE
+ GLOB
+
+If the referenced object has been blessed into a package, then that package
+name is returned instead. You can think of ref() as a typeof() operator.
+
+ if (ref($r) eq "HASH") {
+ print "r is a reference to an associative array.\n";
+ }
+ if (!ref ($r) {
+ print "r is not a reference at all.\n";
+ }
+
+See also L<perlref>.
+
+=item rename OLDNAME,NEWNAME
+
+Changes the name of a file. Returns 1 for success, 0 otherwise. Will
+not work across filesystem boundaries.
+
+=item require EXPR
+
+=item require
+
+Demands some semantics specified by EXPR, or by $_ if EXPR is not
+supplied. If EXPR is numeric, demands that the current version of Perl
+($] or $PERL_VERSION) be equal or greater than EXPR.
+
+Otherwise, demands that a library file be included if it hasn't already
+been included. The file is included via the do-FILE mechanism, which is
+essentially just a variety of eval(). Has semantics similar to the following
+subroutine:
+
+ sub require {
+ local($filename) = @_;
+ return 1 if $INC{$filename};
+ local($realfilename,$result);
+ ITER: {
+ foreach $prefix (@INC) {
+ $realfilename = "$prefix/$filename";
+ if (-f $realfilename) {
+ $result = do $realfilename;
+ last ITER;
+ }
+ }
+ die "Can't find $filename in \@INC";
+ }
+ die $@ if $@;
+ die "$filename did not return true value" unless $result;
+ $INC{$filename} = $realfilename;
+ $result;
+ }
+
+Note that the file will not be included twice under the same specified
+name. The file must return TRUE as the last statement to indicate
+successful execution of any initialization code, so it's customary to
+end such a file with "1;" unless you're sure it'll return TRUE
+otherwise. But it's better just to put the "C<1;>", in case you add more
+statements.
+
+If EXPR is a bare word, the require assumes a "F<.pm>" extension for you,
+to make it easy to load standard modules. This form of loading of
+modules does not risk altering your namespace.
+
+For a yet more powerful import facility, see the L</use()> below, and
+also L<perlmod>.
+
+=item reset EXPR
+
+=item reset
+
+Generally used in a C<continue> block at the end of a loop to clear
+variables and reset ?? searches so that they work again. The
+expression is interpreted as a list of single characters (hyphens
+allowed for ranges). All variables and arrays beginning with one of
+those letters are reset to their pristine state. If the expression is
+omitted, one-match searches (?pattern?) are reset to match again. Only
+resets variables or searches in the current package. Always returns
+1. Examples:
+
+ reset 'X'; # reset all X variables
+ reset 'a-z'; # reset lower case variables
+ reset; # just reset ?? searches
+
+Resetting "A-Z" is not recommended since you'll wipe out your
+ARGV and ENV arrays. Only resets package variables--lexical variables
+are unaffected, but they clean themselves up on scope exit anyway,
+so anymore you probably want to use them instead. See L</my>.
+
+=item return LIST
+
+Returns from a subroutine or eval with the value specified. (Note that
+in the absence of a return a subroutine or eval will automatically
+return the value of the last expression evaluated.)
+
+=item reverse LIST
+
+In a list context, returns a list value consisting of the elements
+of LIST in the opposite order. In a scalar context, returns a string
+value consisting of the bytes of the first element of LIST in the
+opposite order.
+
+=item rewinddir DIRHANDLE
+
+Sets the current position to the beginning of the directory for the
+readdir() routine on DIRHANDLE.
+
+=item rindex STR,SUBSTR,POSITION
+
+=item rindex STR,SUBSTR
+
+Works just like index except that it returns the position of the LAST
+occurrence of SUBSTR in STR. If POSITION is specified, returns the
+last occurrence at or before that position.
+
+=item rmdir FILENAME
+
+Deletes the directory specified by FILENAME if it is empty. If it
+succeeds it returns 1, otherwise it returns 0 and sets $! (errno). If
+FILENAME is omitted, uses $_.
+
+=item s///
+
+The substitution operator. See L<perlop>.
+
+=item scalar EXPR
+
+Forces EXPR to be interpreted in a scalar context and returns the value
+of EXPR.
+
+=item seek FILEHANDLE,POSITION,WHENCE
+
+Randomly positions the file pointer for FILEHANDLE, just like the fseek()
+call of stdio. FILEHANDLE may be an expression whose value gives the name
+of the filehandle. The values for WHENCE are 0 to set the file pointer to
+POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF
+plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for
+this is usin the POSIX module. Returns 1 upon success, 0 otherwise.
+
+=item seekdir DIRHANDLE,POS
+
+Sets the current position for the readdir() routine on DIRHANDLE. POS
+must be a value returned by telldir(). Has the same caveats about
+possible directory compaction as the corresponding system library
+routine.
+
+=item select FILEHANDLE
+
+=item select
+
+Returns the currently selected filehandle. Sets the current default
+filehandle for output, if FILEHANDLE is supplied. This has two
+effects: first, a C<write> or a C<print> without a filehandle will
+default to this FILEHANDLE. Second, references to variables related to
+output will refer to this output channel. For example, if you have to
+set the top of form format for more than one output channel, you might
+do the following:
+
+ select(REPORT1);
+ $^ = 'report1_top';
+ select(REPORT2);
+ $^ = 'report2_top';
+
+FILEHANDLE may be an expression whose value gives the name of the
+actual filehandle. Thus:
+
+ $oldfh = select(STDERR); $| = 1; select($oldfh);
+
+With Perl 5, filehandles are objects with methods, and the last example
+is preferably written
+
+ use FileHandle;
+ STDERR->autoflush(1);
+
+=item select RBITS,WBITS,EBITS,TIMEOUT
+
+This calls the select system(2) call with the bitmasks specified, which
+can be constructed using fileno() and vec(), along these lines:
+
+ $rin = $win = $ein = '';
+ vec($rin,fileno(STDIN),1) = 1;
+ vec($win,fileno(STDOUT),1) = 1;
+ $ein = $rin | $win;
+
+If you want to select on many filehandles you might wish to write a
+subroutine:
+
+ sub fhbits {
+ local(@fhlist) = split(' ',$_[0]);
+ local($bits);
+ for (@fhlist) {
+ vec($bits,fileno($_),1) = 1;
+ }
+ $bits;
+ }
+ $rin = &fhbits('STDIN TTY SOCK');
+
+The usual idiom is:
+
+ ($nfound,$timeleft) =
+ select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
+
+or to block until something becomes ready:
+
+ $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
+
+Any of the bitmasks can also be undef. The timeout, if specified, is
+in seconds, which may be fractional. Note: not all implementations are
+capable of returning the $timeleft. If not, they always return
+$timeleft equal to the supplied $timeout.
+
+You can effect a 250 microsecond sleep this way:
+
+ select(undef, undef, undef, 0.25);
+
+
+=item semctl ID,SEMNUM,CMD,ARG
+
+Calls the System V IPC function semctl. If CMD is &IPC_STAT or
+&GETALL, then ARG must be a variable which will hold the returned
+semid_ds structure or semaphore value array. Returns like ioctl: the
+undefined value for error, "0 but true" for zero, or the actual return
+value otherwise.
+
+=item semget KEY,NSEMS,FLAGS
+
+Calls the System V IPC function semget. Returns the semaphore id, or
+the undefined value if there is an error.
+
+=item semop KEY,OPSTRING
+
+Calls the System V IPC function semop to perform semaphore operations
+such as signaling and waiting. OPSTRING must be a packed array of
+semop structures. Each semop structure can be generated with
+C<pack("sss", $semnum, $semop, $semflag)>. The number of semaphore
+operations is implied by the length of OPSTRING. Returns TRUE if
+successful, or FALSE if there is an error. As an example, the
+following code waits on semaphore $semnum of semaphore id $semid:
+
+ $semop = pack("sss", $semnum, -1, 0);
+ die "Semaphore trouble: $!\n" unless semop($semid, $semop);
+
+To signal the semaphore, replace "-1" with "1".
+
+=item send SOCKET,MSG,FLAGS,TO
+
+=item send SOCKET,MSG,FLAGS
+
+Sends a message on a socket. Takes the same flags as the system call
+of the same name. On unconnected sockets you must specify a
+destination to send TO, in which case it does a C sendto(). Returns
+the number of characters sent, or the undefined value if there is an
+error.
+
+=item setpgrp PID,PGRP
+
+Sets the current process group for the specified PID, 0 for the current
+process. Will produce a fatal error if used on a machine that doesn't
+implement setpgrp(2).
+
+=item setpriority WHICH,WHO,PRIORITY
+
+Sets the current priority for a process, a process group, or a user.
+(See Lsetpriority(2)>.) Will produce a fatal error if used on a machine
+that doesn't implement setpriority(2).
+
+=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+
+Sets the socket option requested. Returns undefined if there is an
+error. OPTVAL may be specified as undef if you don't want to pass an
+argument.
+
+=item shift ARRAY
+
+=item shift
+
+Shifts the first value of the array off and returns it, shortening the
+array by 1 and moving everything down. If there are no elements in the
+array, returns the undefined value. If ARRAY is omitted, shifts the
+@ARGV array in the main program, and the @_ array in subroutines.
+(This is determined lexically.) See also unshift(), push(), and pop().
+Shift() and unshift() do the same thing to the left end of an array
+that push() and pop() do to the right end.
+
+=item shmctl ID,CMD,ARG
+
+Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG
+must be a variable which will hold the returned shmid_ds structure.
+Returns like ioctl: the undefined value for error, "0 but true" for
+zero, or the actual return value otherwise.
+
+=item shmget KEY,SIZE,FLAGS
+
+Calls the System V IPC function shmget. Returns the shared memory
+segment id, or the undefined value if there is an error.
+
+=item shmread ID,VAR,POS,SIZE
+
+=item shmwrite ID,STRING,POS,SIZE
+
+Reads or writes the System V shared memory segment ID starting at
+position POS for size SIZE by attaching to it, copying in/out, and
+detaching from it. When reading, VAR must be a variable which 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.
+
+=item shutdown SOCKET,HOW
+
+Shuts down a socket connection in the manner indicated by HOW, which
+has the same interpretation as in the system call of the same name.
+
+=item sin EXPR
+
+Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
+returns sine of $_.
+
+=item sleep EXPR
+
+=item sleep
+
+Causes the script to sleep for EXPR seconds, or forever if no EXPR.
+May be interrupted by sending the process a SIGALRM. Returns the
+number of seconds actually slept. You probably cannot mix alarm() and
+sleep() calls, since sleep() is often implemented using alarm().
+
+On some older systems, it may sleep up to a full second less than what
+you requested, depending on how it counts seconds. Most modern systems
+always sleep the full amount.
+
+=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
+
+Opens a socket of the specified kind and attaches it to filehandle
+SOCKET. DOMAIN, TYPE and PROTOCOL are specified the same as for the
+system call of the same name. You should "use Socket;" first to get
+the proper definitions imported. See the example in L<perlipc>.
+
+=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+
+Creates an unnamed pair of sockets in the specified domain, of the
+specified type. DOMAIN, TYPE and PROTOCOL are specified the same as
+for the system call of the same name. If unimplemented, yields a fatal
+error. Returns TRUE if successful.
+
+=item sort SUBNAME LIST
+
+=item sort BLOCK LIST
+
+=item sort LIST
+
+Sorts the LIST and returns the sorted list value. Nonexistent values
+of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts
+in standard string comparison order. If SUBNAME is specified, it
+gives the name of a subroutine that returns an integer less than, equal
+to, or greater than 0, depending on how the elements of the array are
+to be ordered. (The <=> and cmp operators are extremely useful in such
+routines.) SUBNAME may be a scalar variable name, in which case the
+value provides the name of the subroutine to use. In place of a
+SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
+subroutine.
+
+In the interests of efficiency the normal calling code for subroutines
+is bypassed, with the following effects: the subroutine may not be a
+recursive subroutine, and the two elements to be compared are passed
+into the subroutine not via @_ but as $a and $b (see example below).
+They are passed by reference, so don't modify $a and $b.
+
+Examples:
+
+ # sort lexically
+ @articles = sort @files;
+
+ # same thing, but with explicit sort routine
+ @articles = sort {$a cmp $b} @files;
+
+ # same thing in reversed order
+ @articles = sort {$b cmp $a} @files;
+
+ # sort numerically ascending
+ @articles = sort {$a <=> $b} @files;
+
+ # sort numerically descending
+ @articles = sort {$b <=> $a} @files;
+
+ # sort using explicit subroutine name
+ sub byage {
+ $age{$a} <=> $age{$b}; # presuming integers
+ }
+ @sortedclass = sort byage @class;
+
+ sub backwards { $b cmp $a; }
+ @harry = ('dog','cat','x','Cain','Abel');
+ @george = ('gone','chased','yz','Punished','Axed');
+ print sort @harry;
+ # prints AbelCaincatdogx
+ print sort backwards @harry;
+ # prints xdogcatCainAbel
+ print sort @george, 'to', @harry;
+ # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
+
+=item splice ARRAY,OFFSET,LENGTH,LIST
+
+=item splice ARRAY,OFFSET,LENGTH
+
+=item splice ARRAY,OFFSET
+
+Removes the elements designated by OFFSET and LENGTH from an array, and
+replaces them with the elements of LIST, if any. Returns the elements
+removed from the array. The array grows or shrinks as necessary. If
+LENGTH is omitted, removes everything from OFFSET onward. The
+following equivalencies hold (assuming $[ == 0):
+
+ push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y)
+ pop(@a) splice(@a,-1)
+ shift(@a) splice(@a,0,1)
+ unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
+ $a[$x] = $y splice(@a,$x,1,$y);
+
+Example, assuming array lengths are passed before arrays:
+
+ sub aeq { # compare two list values
+ local(@a) = splice(@_,0,shift);
+ local(@b) = splice(@_,0,shift);
+ return 0 unless @a == @b; # same len?
+ while (@a) {
+ return 0 if pop(@a) ne pop(@b);
+ }
+ return 1;
+ }
+ if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
+
+=item split /PATTERN/,EXPR,LIMIT
+
+=item split /PATTERN/,EXPR
+
+=item split /PATTERN/
+
+=item split
+
+Splits a string into an array of strings, and returns it.
+
+If not in a list context, returns the number of fields found and splits into
+the @_ array. (In a list context, you can force the split into @_ by
+using C<??> as the pattern delimiters, but it still returns the array
+value.) The use of implicit split to @_ is deprecated, however.
+
+If EXPR is omitted, splits the $_ string. If PATTERN is also omitted,
+splits on whitespace (C</[ \t\n]+/>). Anything matching PATTERN is taken
+to be a delimiter separating the fields. (Note that the delimiter may
+be longer than one character.) If LIMIT is specified and is not
+negative, splits into no more than that many fields (though it may
+split into fewer). If LIMIT is unspecified, trailing null fields are
+stripped (which potential users of pop() would do well to remember).
+If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
+had been specified.
+
+A pattern matching the null string (not to be confused with
+a null pattern C<//., which is just one member of the set of patterns
+matching a null string) will split the value of EXPR into separate
+characters at each point it matches that way. For example:
+
+ print join(':', split(/ */, 'hi there'));
+
+produces the output 'h:i:t:h:e:r:e'.
+
+The LIMIT parameter can be used to partially split a line
+
+ ($login, $passwd, $remainder) = split(/:/, $_, 3);
+
+When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT
+one larger than the number of variables in the list, to avoid
+unnecessary work. For the list above LIMIT would have been 4 by
+default. In time critical applications it behooves you not to split
+into more fields than you really need.
+
+If the PATTERN contains parentheses, additional array elements are
+created from each matching substring in the delimiter.
+
+ split(/([,-])/, "1-10,20");
+
+produces the list value
+
+ (1, '-', 10, ',', 20)
+
+The pattern C</PATTERN/> may be replaced with an expression to specify
+patterns that vary at runtime. (To do runtime compilation only once,
+use C</$variable/o>.) As a special case, specifying a space S<(' ')> will
+split on white space just as split with no arguments does, but leading
+white space does I<NOT> produce a null first field. Thus, split(' ') can
+be used to emulate B<awk>'s default behavior, whereas C<split(/ /)> will
+give you as many null initial fields as there are leading spaces.
+
+Example:
+
+ open(passwd, '/etc/passwd');
+ while (<passwd>) {
+ ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/);
+ ...
+ }
+
+(Note that $shell above will still have a newline on it. See L</chop>,
+L</chomp>, and L</join>.)
+
+=item sprintf FORMAT,LIST
+
+Returns a string formatted by the usual printf conventions of the C
+language. (The * character for an indirectly specified length is not
+supported, but you can get the same effect by interpolating a variable
+into the pattern.)
+
+=item sqrt EXPR
+
+Return the square root of EXPR. If EXPR is omitted, returns square
+root of $_.
+
+=item srand EXPR
+
+Sets the random number seed for the C<rand> operator. If EXPR is
+omitted, does C<srand(time)>. Of course, you'd need something much more
+random than that for cryptographic purposes, since it's easy to guess
+the current time. Checksumming the compressed output of rapidly
+changing operating system status programs is the usual method.
+Examples are posted regularly to comp.security.unix.
+
+=item stat FILEHANDLE
+
+=item stat EXPR
+
+Returns a 13-element array giving the status info for a file, either the
+file opened via FILEHANDLE, or named by EXPR. Returns a null list if
+the stat fails. Typically used as follows:
+
+ ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
+ $atime,$mtime,$ctime,$blksize,$blocks)
+ = stat($filename);
+
+If stat is passed the special filehandle consisting of an underline, no
+stat is done, but the current contents of the stat structure from the
+last stat or filetest are returned. Example:
+
+ if (-x $file && (($d) = stat(_)) && $d < 0) {
+ print "$file is executable NFS file\n";
+ }
+
+(This only works on machines for which the device number is negative under NFS.)
+
+=item study SCALAR
+
+=item study
+
+Takes extra time to study SCALAR ($_ if unspecified) in anticipation of
+doing many pattern matches on the string before it is next modified.
+This may or may not save time, depending on the nature and number of
+patterns you are searching on, and on the distribution of character
+frequencies in the string to be searched--you probably want to compare
+runtimes with and without it to see which runs faster. Those loops
+which scan for many short constant strings (including the constant
+parts of more complex patterns) will benefit most. You may have only
+one study active at a time--if you study a different scalar the first
+is "unstudied". (The way study works is this: a linked list of every
+character in the string to be searched is made, so we know, for
+example, where all the 'k' characters are. From each search string,
+the rarest character is selected, based on some static frequency tables
+constructed from some C programs and English text. Only those places
+that contain this "rarest" character are examined.)
+
+For example, here is a loop which inserts index producing entries
+before any line containing a certain pattern:
+
+ while (<>) {
+ study;
+ print ".IX foo\n" if /\bfoo\b/;
+ print ".IX bar\n" if /\bbar\b/;
+ print ".IX blurfl\n" if /\bblurfl\b/;
+ ...
+ print;
+ }
+
+In searching for /\bfoo\b/, only those locations in $_ that contain "f"
+will be looked at, because "f" is rarer than "o". In general, this is
+a big win except in pathological cases. The only question is whether
+it saves you more time than it took to build the linked list in the
+first place.
+
+Note that if you have to look for strings that you don't know till
+runtime, you can build an entire loop as a string and eval that to
+avoid recompiling all your patterns all the time. Together with
+undefining $/ to input entire files as one record, this can be very
+fast, often faster than specialized programs like fgrep(1). The following
+scans a list of files (@files) for a list of words (@words), and prints
+out the names of those files that contain a match:
+
+ $search = 'while (<>) { study;';
+ foreach $word (@words) {
+ $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
+ }
+ $search .= "}";
+ @ARGV = @files;
+ undef $/;
+ eval $search; # this screams
+ $/ = "\n"; # put back to normal input delim
+ foreach $file (sort keys(%seen)) {
+ print $file, "\n";
+ }
+
+=item substr EXPR,OFFSET,LEN
+
+=item substr EXPR,OFFSET
+
+Extracts a substring out of EXPR and returns it. First character is at
+offset 0, or whatever you've set $[ to. If OFFSET is negative, starts
+that far from the end of the string. If LEN is omitted, returns
+everything to the end of the string. You can use the substr() function
+as an lvalue, in which case EXPR must be an lvalue. If you assign
+something shorter than LEN, the string will shrink, and if you assign
+something longer than LEN, the string will grow to accommodate it. To
+keep the string the same length you may need to pad or chop your value
+using sprintf().
+
+=item symlink OLDFILE,NEWFILE
+
+Creates a new filename symbolically linked to the old filename.
+Returns 1 for success, 0 otherwise. On systems that don't support
+symbolic links, produces a fatal error at run time. To check for that,
+use eval:
+
+ $symlink_exists = (eval 'symlink("","");', $@ eq '');
+
+=item syscall LIST
+
+Calls the system call specified as the first element of the list,
+passing the remaining elements as arguments to the system call. If
+unimplemented, produces a fatal error. The arguments are interpreted
+as follows: if a given argument is numeric, the argument is passed as
+an int. If not, the pointer to the string value is passed. You are
+responsible to make sure a string is pre-extended long enough to
+receive any result that might be written into a string. If your
+integer arguments are not literals and have never been interpreted in a
+numeric context, you may need to add 0 to them to force them to look
+like numbers.
+
+ require 'syscall.ph'; # may need to run h2ph
+ syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
+
+Note that Perl only supports passing of up to 14 arguments to your system call,
+which in practice should usually suffice.
+
+=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+
+=item sysread FILEHANDLE,SCALAR,LENGTH
+
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE, using the system call read(2). It bypasses
+stdio, so mixing this with other kinds of reads may cause confusion.
+Returns the number of bytes actually read, or undef if there was an
+error. SCALAR will be grown or shrunk to the length actually read. An
+OFFSET may be specified to place the read data at some other place than
+the beginning of the string.
+
+=item system LIST
+
+Does exactly the same thing as "exec LIST" except that a fork is done
+first, and the parent process waits for the child process to complete.
+Note that argument processing varies depending on the number of
+arguments. The return value is the exit status of the program as
+returned by the wait() call. To get the actual exit value divide by
+256. See also L</exec>.
+
+=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+
+=item syswrite FILEHANDLE,SCALAR,LENGTH
+
+Attempts to write LENGTH bytes of data from variable SCALAR to the
+specified FILEHANDLE, using the system call write(2). It bypasses
+stdio, so mixing this with prints may cause confusion. Returns the
+number of bytes actually written, or undef if there was an error. An
+OFFSET may be specified to place the read data at some other place than
+the beginning of the string.
+
+=item tell FILEHANDLE
+
+=item tell
+
+Returns the current file position for FILEHANDLE. FILEHANDLE may be an
+expression whose value gives the name of the actual filehandle. If
+FILEHANDLE is omitted, assumes the file last read.
+
+=item telldir DIRHANDLE
+
+Returns the current position of the readdir() routines on DIRHANDLE.
+Value may be given to seekdir() to access a particular location in a
+directory. Has the same caveats about possible directory compaction as
+the corresponding system library routine.
+
+=item tie VARIABLE,PACKAGENAME,LIST
+
+This function binds a variable to a package that will provide the
+implementation for the variable. VARIABLE is the name of the variable
+to be enchanted. PACKAGENAME is the name of a package implementing
+objects of correct type. Any additional arguments are passed to the
+"new" method of the package. Typically these are arguments such as
+might be passed to the dbm_open() function of C.
+
+Note that functions such as keys() and values() may return huge array
+values when used on large DBM files. You may prefer to use the each()
+function to iterate over large DBM files. Example:
+
+ # print out history file offsets
+ tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0);
+ while (($key,$val) = each %HIST) {
+ print $key, ' = ', unpack('L',$val), "\n";
+ }
+ untie(%HIST);
+
+A package implementing an associative array should have the following
+methods:
+
+ TIEHASH objectname, LIST
+ DESTROY this
+ FETCH this, key
+ STORE this, key, value
+ DELETE this, key
+ EXISTS this, key
+ FIRSTKEY this
+ NEXTKEY this, lastkey
+
+A package implementing an ordinary array should have the following methods:
+
+ TIEARRAY objectname, LIST
+ DESTROY this
+ FETCH this, key
+ STORE this, key, value
+ [others TBD]
+
+A package implementing a scalar should have the following methods:
+
+ TIESCALAR objectname, LIST
+ DESTROY this
+ FETCH this,
+ STORE this, value
+
+=item time
+
+Returns the number of non-leap seconds since 00:00:00 UTC, January 1,
+1970. Suitable for feeding to gmtime() and localtime().
+
+=item times
+
+Returns a four-element array giving the user and system times, in
+seconds, for this process and the children of this process.
+
+ ($user,$system,$cuser,$csystem) = times;
+
+=item tr///
+
+The translation operator. See L<perlop>.
+
+=item truncate FILEHANDLE,LENGTH
+
+=item truncate EXPR,LENGTH
+
+Truncates the file opened on FILEHANDLE, or named by EXPR, to the
+specified length. Produces a fatal error if truncate isn't implemented
+on your system.
+
+=item uc EXPR
+
+Returns an uppercased version of EXPR. This is the internal function
+implementing the \U escape in double-quoted strings.
+
+=item ucfirst EXPR
+
+Returns the value of EXPR with the first character uppercased. This is
+the internal function implementing the \u escape in double-quoted strings.
+
+=item umask EXPR
+
+=item umask
+
+Sets the umask for the process and returns the old one. If EXPR is
+omitted, merely returns current umask.
+
+=item undef EXPR
+
+=item undef
+
+Undefines the value of EXPR, which must be an lvalue. Use only on a
+scalar value, an entire array, or a subroutine name (using "&"). (Using undef()
+will probably not do what you expect on most predefined variables or
+DBM list values, so don't do that.) Always returns the undefined value. You can omit
+the EXPR, in which case nothing is undefined, but you still get an
+undefined value that you could, for instance, return from a
+subroutine. Examples:
+
+ undef $foo;
+ undef $bar{'blurfl'};
+ undef @ary;
+ undef %assoc;
+ undef &mysub;
+ return (wantarray ? () : undef) if $they_blew_it;
+
+=item unlink LIST
+
+Deletes a list of files. Returns the number of files successfully
+deleted.
+
+ $cnt = unlink 'a', 'b', 'c';
+ unlink @goners;
+ unlink <*.bak>;
+
+Note: unlink will not delete directories unless you are superuser and
+the B<-U> flag is supplied to Perl. Even if these conditions are
+met, be warned that unlinking a directory can inflict damage on your
+filesystem. Use rmdir instead.
+
+=item unpack TEMPLATE,EXPR
+
+Unpack does the reverse of pack: it takes a string representing a
+structure and expands it out into a list value, returning the array
+value. (In a scalar context, it merely returns the first value
+produced.) The TEMPLATE has the same format as in the pack function.
+Here's a subroutine that does substring:
+
+ sub substr {
+ local($what,$where,$howmuch) = @_;
+ unpack("x$where a$howmuch", $what);
+ }
+
+and then there's
+
+ sub ordinal { unpack("c",$_[0]); } # same as ord()
+
+In addition, you may prefix a field with a %<number> to indicate that
+you want a <number>-bit checksum of the items instead of the items
+themselves. Default is a 16-bit checksum. For example, the following
+computes the same number as the System V sum program:
+
+ while (<>) {
+ $checksum += unpack("%16C*", $_);
+ }
+ $checksum %= 65536;
+
+The following efficiently counts the number of set bits in a bit vector:
+
+ $setbits = unpack("%32b*", $selectmask);
+
+=item untie VARIABLE
+
+Breaks the binding between a variable and a package. (See tie().)
+
+=item unshift ARRAY,LIST
+
+Does the opposite of a C<shift>. Or the opposite of a C<push>,
+depending on how you look at it. Prepends list to the front of the
+array, and returns the new number of elements in the array.
+
+ unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
+
+Note the LIST is prepended whole, not one element at a time, so the
+prepended elements stay in the same order. Use reverse to do the
+reverse.
+
+=item use Module LIST
+
+=item use Module
+
+Imports some semantics into the current package from the named module,
+generally by aliasing certain subroutine or variable names into your
+package. It is exactly equivalent to
+
+ BEGIN { require Module; import Module LIST; }
+
+If you don't want your namespace altered, use require instead.
+
+The BEGIN forces the require and import to happen at compile time. The
+require makes sure the module is loaded into memory if it hasn't been
+yet. The import is not a builtin--it's just an ordinary static method
+call into the "Module" package to tell the module to import the list of
+features back into the current package. The module can implement its
+import method any way it likes, though most modules just choose to
+derive their import method via inheritance from the Exporter class that
+is defined in the Exporter module.
+
+Because this is a wide-open interface, pragmas (compiler directives)
+are also implemented this way. Currently implemented pragmas are:
+
+ use integer;
+ use sigtrap qw(SEGV BUS);
+ use strict qw(subs vars refs);
+ use subs qw(afunc blurfl);
+
+These pseudomodules import semantics into the current block scope, unlike
+ordinary modules, which import symbols into the current package (which are
+effective through the end of the file).
+
+There's a corresponding "no" command that unimports meanings imported
+by use.
+
+ no integer;
+ no strict 'refs';
+
+See L<perlmod> for a list of standard modules and pragmas.
+
+=item utime LIST
+
+Changes the access and modification times on each file of a list of
+files. The first two elements of the list must be the NUMERICAL access
+and modification times, in that order. Returns the number of files
+successfully changed. The inode modification time of each file is set
+to the current time. Example of a "touch" command:
+
+ #!/usr/bin/perl
+ $now = time;
+ utime $now, $now, @ARGV;
+
+=item values ASSOC_ARRAY
+
+Returns a normal array consisting of all the values of the named
+associative array. (In a scalar context, returns the number of
+values.) The values are returned in an apparently random order, but it
+is the same order as either the keys() or each() function would produce
+on the same array. See also keys() and each().
+
+=item vec EXPR,OFFSET,BITS
+
+Treats a string as a vector of unsigned integers, and returns the value
+of the bitfield specified. May also be assigned to. BITS must be a
+power of two from 1 to 32.
+
+Vectors created with vec() can also be manipulated with the logical
+operators |, & and ^, which will assume a bit vector operation is
+desired when both operands are strings.
+
+To transform a bit vector into a string or array of 0's and 1's, use these:
+
+ $bits = unpack("b*", $vector);
+ @bits = split(//, unpack("b*", $vector));
+
+If you know the exact length in bits, it can be used in place of the *.
+
+=item wait
+
+Waits for a child process to terminate and returns the pid of the
+deceased process, or -1 if there are no child processes. The status is
+returned in $?.
+
+=item waitpid PID,FLAGS
+
+Waits for a particular child process to terminate and returns the pid
+of the deceased process, or -1 if there is no such child process. The
+status is returned in $?. If you say
+
+ use POSIX "wait_h";
+ ...
+ waitpid(-1,&WNOHANG);
+
+then you can do a non-blocking wait for any process. Non-blocking wait
+is only available on machines supporting either the waitpid(2) or
+wait4(2) system calls. However, waiting for a particular pid with
+FLAGS of 0 is implemented everywhere. (Perl emulates the system call
+by remembering the status values of processes that have exited but have
+not been harvested by the Perl script yet.)
+
+=item wantarray
+
+Returns TRUE if the context of the currently executing subroutine is
+looking for a list value. Returns FALSE if the context is looking
+for a scalar.
+
+ return wantarray ? () : undef;
+
+=item warn LIST
+
+Produces a message on STDERR just like die(), but doesn't exit or
+throw an exception.
+
+=item write FILEHANDLE
+
+=item write EXPR
+
+=item write
+
+Writes a formatted record (possibly multi-line) to the specified file,
+using the format associated with that file. By default the format for
+a file is the one having the same name is the filehandle, but the
+format for the current output channel (see the select() function) may be set
+explicitly by assigning the name of the format to the $~ variable.
+
+Top of form processing is handled automatically: if there is
+insufficient room on the current page for the formatted record, the
+page is advanced by writing a form feed, a special top-of-page format
+is used to format the new page header, and then the record is written.
+By default the top-of-page format is the name of the filehandle with
+"_TOP" appended, but it may be dynamically set to the format of your
+choice by assigning the name to the $^ variable while the filehandle is
+selected. The number of lines remaining on the current page is in
+variable $-, which can be set to 0 to force a new page.
+
+If FILEHANDLE is unspecified, output goes to the current default output
+channel, which starts out as STDOUT but may be changed by the
+C<select> operator. If the FILEHANDLE is an EXPR, then the expression
+is evaluated and the resulting string is used to look up the name of
+the FILEHANDLE at run time. For more on formats, see L<perlform>.
+
+Note that write is I<NOT> the opposite of read. Unfortunately.
+
+=item y///
+
+The translation operator. See L<perlop/tr///>.
+
+=back
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
new file mode 100644
index 0000000000..a08ac95340
--- /dev/null
+++ b/pod/perlguts.pod
@@ -0,0 +1,521 @@
+=head1 NAME
+
+perlguts - Perl's Internal Functions
+
+=head1 DESCRIPTION
+
+This document attempts to describe some of the internal functions of the
+Perl executable. It is far from complete and probably contains many errors.
+Please refer any questions or comments to the author below.
+
+=head1 Datatypes
+
+Perl has three typedefs that handle Perl's three main data types:
+
+ SV Scalar Value
+ AV Array Value
+ HV Hash Value
+
+Each typedef has specific routines that manipulate the various data type.
+
+=head2 What is an "IV"?
+
+Perl uses a special typedef IV which is large enough to hold either an
+integer or a pointer.
+
+Perl also uses a special typedef I32 which will always be a 32-bit integer.
+
+=head2 Working with SV's
+
+An SV can be created and loaded with one command. There are four types of
+values that can be loaded: an integer value (IV), a double (NV), a string,
+(PV), and another scalar (SV).
+
+The four routines are:
+
+ SV* newSViv(IV);
+ SV* newSVnv(double);
+ SV* newSVpv(char*, int);
+ SV* newSVsv(SV*);
+
+To change the value of an *already-existing* scalar, there are five routines:
+
+ void sv_setiv(SV*, IV);
+ void sv_setnv(SV*, double);
+ void sv_setpvn(SV*, char*, int)
+ void sv_setpv(SV*, char*);
+ void sv_setsv(SV*, SV*);
+
+Notice that you can choose to specify the length of the string to be
+assigned by using C<sv_setpvn>, or allow Perl to calculate the length by
+using C<sv_setpv>. Be warned, though, that C<sv_setpv> determines the
+string's length by using C<strlen>, which depends on the string terminating
+with a NUL character.
+
+To access the actual value that an SV points to, you can use the macros:
+
+ SvIV(SV*)
+ SvNV(SV*)
+ SvPV(SV*, STRLEN len)
+
+which will automatically coerce the actual scalar type into an IV, double,
+or string.
+
+In the C<SvPV> macro, the length of the string returned is placed into the
+variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not
+care what the length of the data is, use the global variable C<na>. Remember,
+however, that Perl allows arbitrary strings of data that may both contain
+NUL's and not be terminated by a NUL.
+
+If you simply want to know if the scalar value is TRUE, you can use:
+
+ SvTRUE(SV*)
+
+Although Perl will automatically grow strings for you, if you need to force
+Perl to allocate more memory for your SV, you can use the macro
+
+ SvGROW(SV*, STRLEN newlen)
+
+which will determine if more memory needs to be allocated. If so, it will
+call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
+decrease, the allocated memory of an SV.
+
+If you have an SV and want to know what kind of data Perl thinks is stored
+in it, you can use the following macros to check the type of SV you have.
+
+ SvIOK(SV*)
+ SvNOK(SV*)
+ SvPOK(SV*)
+
+You can get and set the current length of the string stored in an SV with
+the following macros:
+
+ SvCUR(SV*)
+ SvCUR_set(SV*, I32 val)
+
+But note that these are valid only if C<SvPOK()> is true.
+
+If you know the name of a scalar variable, you can get a pointer to its SV
+by using the following:
+
+ SV* perl_get_sv("varname", FALSE);
+
+This returns NULL if the variable does not exist.
+
+If you want to know if this variable (or any other SV) is actually defined,
+you can call:
+
+ SvOK(SV*)
+
+The scalar C<undef> value is stored in an SV instance called C<sv_undef>. Its
+address can be used whenever an C<SV*> is needed.
+
+There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
+TRUE and FALSE values, respectively. Like C<sv_undef>, their addresses can
+be used whenever an C<SV*> is needed.
+
+Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
+Take this code:
+
+ SV* sv = (SV*) 0;
+ if (I-am-to-return-a-real-value) {
+ sv = sv_2mortal(newSViv(42));
+ }
+ sv_setsv(ST(0), sv);
+
+This code tries to return a new SV (which contains the value 42) if it should
+return a real value, or undef otherwise. Instead it has returned a null
+pointer which, somewhere down the line, will cause a segmentation violation,
+or just weird results. Change the zero to C<&sv_undef> in the first line and
+all will be well.
+
+To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
+call is not necessary. See the section on B<MORTALITY>.
+
+=head2 Private and Public Values
+
+Recall that the usual method of determining the type of scalar you have is
+to use C<Sv[INP]OK> macros. Since a scalar can be both a number and a string,
+usually these macros will always return TRUE and calling the C<Sv[INP]V>
+macros will do the appropriate conversion of string to integer/double or
+integer/double to string.
+
+If you I<really> need to know if you have an integer, double, or string
+pointer in an SV, you can use the following three macros instead:
+
+ SvIOKp(SV*)
+ SvNOKp(SV*)
+ SvPOKp(SV*)
+
+These will tell you if you truly have an integer, double, or string pointer
+stored in your SV.
+
+In general, though, it's best to just use the C<Sv[INP]V> macros.
+
+=head2 Working with AV's
+
+There are two ways to create and load an AV. The first method just creates
+an empty AV:
+
+ AV* newAV();
+
+The second method both creates the AV and initially populates it with SV's:
+
+ AV* av_make(I32 num, SV **ptr);
+
+The second argument points to an array containing C<num> C<SV*>'s.
+
+Once the AV has been created, the following operations are possible on AV's:
+
+ void av_push(AV*, SV*);
+ SV* av_pop(AV*);
+ SV* av_shift(AV*);
+ void av_unshift(AV*, I32 num);
+
+These should be familiar operations, with the exception of C<av_unshift>.
+This routine adds C<num> elements at the front of the array with the C<undef>
+value. You must then use C<av_store> (described below) to assign values
+to these new elements.
+
+Here are some other functions:
+
+ I32 av_len(AV*); /* Returns length of array */
+
+ SV** av_fetch(AV*, I32 key, I32 lval);
+ /* Fetches value at key offset, but it seems to
+ set the value to lval if lval is non-zero */
+ SV** av_store(AV*, I32 key, SV* val);
+ /* Stores val at offset key */
+
+ void av_clear(AV*);
+ /* Clear out all elements, but leave the array */
+ void av_undef(AV*);
+ /* Undefines the array, removing all elements */
+
+If you know the name of an array variable, you can get a pointer to its AV
+by using the following:
+
+ AV* perl_get_av("varname", FALSE);
+
+This returns NULL if the variable does not exist.
+
+=head2 Working with HV's
+
+To create an HV, you use the following routine:
+
+ HV* newHV();
+
+Once the HV has been created, the following operations are possible on HV's:
+
+ SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
+ SV** hv_fetch(HV*, char* key, U32 klen, I32 lval);
+
+The C<klen> parameter is the length of the key being passed in. The C<val>
+argument contains the SV pointer to the scalar being stored, and C<hash> is
+the pre-computed hash value (zero if you want C<hv_store> to calculate it
+for you). The C<lval> parameter indicates whether this fetch is actually a
+part of a store operation.
+
+Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
+C<SV*>. In order to access the scalar value, you must first dereference
+the return value. However, you should check to make sure that the return
+value is not NULL before dereferencing it.
+
+These two functions check if a hash table entry exists, and deletes it.
+
+ bool hv_exists(HV*, char* key, U32 klen);
+ SV* hv_delete(HV*, char* key, U32 klen);
+
+And more miscellaneous functions:
+
+ void hv_clear(HV*);
+ /* Clears all entries in hash table */
+ void hv_undef(HV*);
+ /* Undefines the hash table */
+
+ I32 hv_iterinit(HV*);
+ /* Prepares starting point to traverse hash table */
+ HE* hv_iternext(HV*);
+ /* Get the next entry, and return a pointer to a
+ structure that has both the key and value */
+ char* hv_iterkey(HE* entry, I32* retlen);
+ /* Get the key from an HE structure and also return
+ the length of the key string */
+ SV* hv_iterval(HV*, HE* entry);
+ /* Return a SV pointer to the value of the HE
+ structure */
+
+If you know the name of a hash variable, you can get a pointer to its HV
+by using the following:
+
+ HV* perl_get_hv("varname", FALSE);
+
+This returns NULL if the variable does not exist.
+
+The hash algorithm, for those who are interested, is:
+
+ i = klen;
+ hash = 0;
+ s = key;
+ while (i--)
+ hash = hash * 33 + *s++;
+
+=head2 References
+
+References are a special type of scalar that point to other scalar types
+(including references). To treat an AV or HV as a scalar, it is simply
+a matter of casting an AV or HV to an SV.
+
+To create a reference, use the following command:
+
+ SV* newRV((SV*) pointer);
+
+Once you have a reference, you can use the following macro with a cast to
+the appropriate typedef (SV, AV, HV):
+
+ SvRV(SV*)
+
+then call the appropriate routines, casting the returned C<SV*> to either an
+C<AV*> or C<HV*>.
+
+To determine, after dereferencing a reference, if you still have a reference,
+you can use the following macro:
+
+ SvROK(SV*)
+
+=head1 XSUB'S and the Argument Stack
+
+The XSUB mechanism is a simple way for Perl programs to access C subroutines.
+An XSUB routine will have a stack that contains the arguments from the Perl
+program, and a way to map from the Perl data structures to a C equivalent.
+
+The stack arguments are accessible through the C<ST(n)> macro, which returns
+the C<n>'th stack argument. Argument 0 is the first argument passed in the
+Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
+an C<SV*> is used.
+
+Most of the time, output from the C routine can be handled through use of
+the RETVAL and OUTPUT directives. However, there are some cases where the
+argument stack is not already long enough to handle all the return values.
+An example is the POSIX tzname() call, which takes no arguments, but returns
+two, the local timezone's standard and summer time abbreviations.
+
+To handle this situation, the PPCODE directive is used and the stack is
+extended using the macro:
+
+ EXTEND(sp, num);
+
+where C<sp> is the stack pointer, and C<num> is the number of elements the
+stack should be extended by.
+
+Now that there is room on the stack, values can be pushed on it using the
+macros to push IV's, doubles, strings, and SV pointers respectively:
+
+ PUSHi(IV)
+ PUSHn(double)
+ PUSHp(char*, I32)
+ PUSHs(SV*)
+
+And now the Perl program calling C<tzname>, the two values will be assigned
+as in:
+
+ ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
+
+An alternate (and possibly simpler) method to pushing values on the stack is
+to use the macros:
+
+ XPUSHi(IV)
+ XPUSHn(double)
+ XPUSHp(char*, I32)
+ XPUSHs(SV*)
+
+These macros automatically adjust the stack for you, if needed.
+
+=head1 Mortality
+
+In Perl, values are normally "immortal" -- that is, they are not freed unless
+explicitly done so (via the Perl C<undef> call or other routines in Perl
+itself).
+
+In the above example with C<tzname>, we needed to create two new SV's to push
+onto the argument stack, that being the two strings. However, we don't want
+these new SV's to stick around forever because they will eventually be
+copied into the SV's that hold the two scalar variables.
+
+An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal"
+SV, AV, or HV, but is only valid in the "current context". When the Perl
+interpreter leaves the current context, the mortal SV, AV, or HV is
+automatically freed. Generally the "current context" means a single
+Perl statement.
+
+To create a mortal variable, use the functions:
+
+ SV* sv_newmortal()
+ SV* sv_2mortal(SV*)
+ SV* sv_mortalcopy(SV*)
+
+The first call creates a mortal SV, the second converts an existing SV to
+a mortal SV, the third creates a mortal copy of an existing SV.
+
+The mortal routines are not just for SV's -- AV's and HV's can be made mortal
+by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
+C<sv_mortalcopy> routines.
+
+=head1 Creating New Variables
+
+To create a new Perl variable, which can be accessed from your Perl script,
+use the following routines, depending on the variable type.
+
+ SV* perl_get_sv("varname", TRUE);
+ AV* perl_get_av("varname", TRUE);
+ HV* perl_get_hv("varname", TRUE);
+
+Notice the use of TRUE as the second parameter. The new variable can now
+be set, using the routines appropriate to the data type.
+
+=head1 Stashes and Objects
+
+A stash is a hash table (associative array) that contains all of the
+different objects that are contained within a package. Each key of the
+hash table is a symbol name (shared by all the different types of
+objects that have the same name), and each value in the hash table is
+called a GV (for Glob Value). The GV in turn contains references to
+the various objects of that name, including (but not limited to) the
+following:
+
+ Scalar Value
+ Array Value
+ Hash Value
+ File Handle
+ Directory Handle
+ Format
+ Subroutine
+
+Perl stores various stashes in a GV structure (for global variable) but
+represents them with an HV structure.
+
+To get the HV pointer for a particular package, use the function:
+
+ HV* gv_stashpv(char* name, I32 create)
+ HV* gv_stashsv(SV*, I32 create)
+
+The first function takes a literal string, the second uses the string stored
+in the SV.
+
+The name that C<gv_stash*v> wants is the name of the package whose symbol table
+you want. The default package is called C<main>. If you have multiply nested
+packages, it is legal to pass their names to C<gv_stash*v>, separated by
+C<::> as in the Perl language itself.
+
+Alternately, if you have an SV that is a blessed reference, you can find
+out the stash pointer by using:
+
+ HV* SvSTASH(SvRV(SV*));
+
+then use the following to get the package name itself:
+
+ char* HvNAME(HV* stash);
+
+If you need to return a blessed value to your Perl script, you can use the
+following function:
+
+ SV* sv_bless(SV*, HV* stash)
+
+where the first argument, an C<SV*>, must be a reference, and the second
+argument is a stash. The returned C<SV*> can now be used in the same way
+as any other SV.
+
+=head1 Magic
+
+[This section under construction]
+
+=head1 Double-Typed SV's
+
+Scalar variables normally contain only one type of value, an integer,
+double, pointer, or reference. Perl will automatically convert the
+actual scalar data from the stored type into the requested type.
+
+Some scalar variables contain more than one type of scalar data. For
+example, the variable C<$!> contains either the numeric value of C<errno>
+or its string equivalent from C<sys_errlist[]>.
+
+To force multiple data values into an SV, you must do two things: use the
+C<sv_set*v> routines to add the additional scalar type, then set a flag
+so that Perl will believe it contains more than one type of data. The
+four macros to set the flags are:
+
+ SvIOK_on
+ SvNOK_on
+ SvPOK_on
+ SvROK_on
+
+The particular macro you must use depends on which C<sv_set*v> routine
+you called first. This is because every C<sv_set*v> routine turns on
+only the bit for the particular type of data being set, and turns off
+all the rest.
+
+For example, to create a new Perl variable called "dberror" that contains
+both the numeric and descriptive string error values, you could use the
+following code:
+
+ extern int dberror;
+ extern char *dberror_list;
+
+ SV* sv = perl_get_sv("dberror", TRUE);
+ sv_setiv(sv, (IV) dberror);
+ sv_setpv(sv, dberror_list[dberror]);
+ SvIOK_on(sv);
+
+If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
+macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+
+=head1 Calling Perl Routines from within C Programs
+
+There are four routines that can be used to call a Perl subroutine from
+within a C program. These four are:
+
+ I32 perl_call_sv(SV*, I32);
+ I32 perl_call_pv(char*, I32);
+ I32 perl_call_method(char*, I32);
+ I32 perl_call_argv(char*, I32, register char**);
+
+The routine most often used should be C<perl_call_sv>. The C<SV*> argument
+contains either the name of the Perl subroutine to be called, or a reference
+to the subroutine. The second argument tells the appropriate routine what,
+if any, variables are being returned by the Perl subroutine.
+
+All four routines return the number of arguments that the subroutine returned
+on the Perl stack.
+
+When using these four routines, the programmer must manipulate the Perl stack.
+These include the following macros and functions:
+
+ dSP
+ PUSHMARK()
+ PUTBACK
+ SPAGAIN
+ ENTER
+ SAVETMPS
+ FREETMPS
+ LEAVE
+ XPUSH*()
+
+For more information, consult L<perlcall>.
+
+=head1 Memory Allocation
+
+[This section under construction]
+
+=head1 AUTHOR
+
+Jeff Okamoto <okamoto@corp.hp.com>
+
+With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
+Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, and Neil
+Bowers.
+
+=head1 DATE
+
+Version 12: 1994/10/16
+
+
diff --git a/pod/perlipc.pod b/pod/perlipc.pod
new file mode 100644
index 0000000000..a2f3f8b16d
--- /dev/null
+++ b/pod/perlipc.pod
@@ -0,0 +1,168 @@
+=head1 NAME
+
+perlipc - Perl interprocess communication
+
+=head1 DESCRIPTION
+
+The IPC facilities of Perl are built on the Berkeley socket mechanism.
+If you don't have sockets, you can ignore this section. The calls have
+the same names as the corresponding system calls, but the arguments
+tend to differ, for two reasons. First, Perl file handles work
+differently than C file descriptors. Second, Perl already knows the
+length of its strings, so you don't need to pass that information.
+
+=head2 Client/Server Communication
+
+Here's a sample TCP client.
+
+ ($them,$port) = @ARGV;
+ $port = 2345 unless $port;
+ $them = 'localhost' unless $them;
+
+ $SIG{'INT'} = 'dokill';
+ sub dokill { kill 9,$child if $child; }
+
+ use Socket;
+
+ $sockaddr = 'S n a4 x8';
+ chop($hostname = `hostname`);
+
+ ($name, $aliases, $proto) = getprotobyname('tcp');
+ ($name, $aliases, $port) = getservbyname($port, 'tcp')
+ unless $port =~ /^\d+$/;
+ ($name, $aliases, $type, $len, $thisaddr) =
+ gethostbyname($hostname);
+ ($name, $aliases, $type, $len, $thataddr) = gethostbyname($them);
+
+ $this = pack($sockaddr, &AF_INET, 0, $thisaddr);
+ $that = pack($sockaddr, &AF_INET, $port, $thataddr);
+
+ socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
+ bind(S, $this) || die "bind: $!";
+ connect(S, $that) || die "connect: $!";
+
+ select(S); $| = 1; select(stdout);
+
+ if ($child = fork) {
+ while (<>) {
+ print S;
+ }
+ sleep 3;
+ do dokill();
+ }
+ else {
+ while (<S>) {
+ print;
+ }
+ }
+
+And here's a server:
+
+ ($port) = @ARGV;
+ $port = 2345 unless $port;
+
+ use Socket;
+
+ $sockaddr = 'S n a4 x8';
+
+ ($name, $aliases, $proto) = getprotobyname('tcp');
+ ($name, $aliases, $port) = getservbyname($port, 'tcp')
+ unless $port =~ /^\d+$/;
+
+ $this = pack($sockaddr, &AF_INET, $port, "\0\0\0\0");
+
+ select(NS); $| = 1; select(stdout);
+
+ socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
+ bind(S, $this) || die "bind: $!";
+ listen(S, 5) || die "connect: $!";
+
+ select(S); $| = 1; select(stdout);
+
+ for (;;) {
+ print "Listening again\n";
+ ($addr = accept(NS,S)) || die $!;
+ print "accept ok\n";
+
+ ($af,$port,$inetaddr) = unpack($sockaddr,$addr);
+ @inetaddr = unpack('C4',$inetaddr);
+ print "$af $port @inetaddr\n";
+
+ while (<NS>) {
+ print;
+ print NS;
+ }
+ }
+
+=head2 SysV IPC
+
+Here's a small example showing shared memory usage:
+
+ $IPC_PRIVATE = 0;
+ $IPC_RMID = 0;
+ $size = 2000;
+ $key = shmget($IPC_PRIVATE, $size , 0777 );
+ die if !defined($key);
+
+ $message = "Message #1";
+ shmwrite($key, $message, 0, 60 ) || die "$!";
+ shmread($key,$buff,0,60) || die "$!";
+
+ print $buff,"\n";
+
+ print "deleting $key\n";
+ shmctl($key ,$IPC_RMID, 0) || die "$!";
+
+Here's an example of a semaphore:
+
+ $IPC_KEY = 1234;
+ $IPC_RMID = 0;
+ $IPC_CREATE = 0001000;
+ $key = semget($IPC_KEY, $nsems , 0666 | $IPC_CREATE );
+ die if !defined($key);
+ print "$key\n";
+
+Put this code in a separate file to be run in more that one process
+Call the file F<take>:
+
+ # create a semaphore
+
+ $IPC_KEY = 1234;
+ $key = semget($IPC_KEY, 0 , 0 );
+ die if !defined($key);
+
+ $semnum = 0;
+ $semflag = 0;
+
+ # 'take' semaphore
+ # wait for semaphore to be zero
+ $semop = 0;
+ $opstring1 = pack("sss", $semnum, $semop, $semflag);
+
+ # Increment the semaphore count
+ $semop = 1;
+ $opstring2 = pack("sss", $semnum, $semop, $semflag);
+ $opstring = $opstring1 . $opstring2;
+
+ semop($key,$opstring) || die "$!";
+
+Put this code in a separate file to be run in more that one process
+Call this file F<give>:
+
+ #'give' the semaphore
+ # run this in the original process and you will see
+ # that the second process continues
+
+ $IPC_KEY = 1234;
+ $key = semget($IPC_KEY, 0, 0);
+ die if !defined($key);
+
+ $semnum = 0;
+ $semflag = 0;
+
+ # Decrement the semaphore count
+ $semop = -1;
+ $opstring = pack("sss", $semnum, $semop, $semflag);
+
+ semop($key,$opstring) || die "$!";
+
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
new file mode 100644
index 0000000000..d804b1e4ed
--- /dev/null
+++ b/pod/perlmod.pod
@@ -0,0 +1,472 @@
+=head1 NAME
+
+perlmod - Perl modules (packages)
+
+=head1 DESCRIPTION
+
+=head2 Packages
+
+Perl provides a mechanism for alternate namespaces to protect packages
+from stomping on each others variables. By default, a Perl script starts
+compiling into the package known as C<main>. You can switch namespaces
+using the C<package> declaration. The scope of the package declaration is
+from the declaration itself to the end of the enclosing block (the same
+scope as the local() operator). Typically it would be the first
+declaration in a file to be included by the C<require> operator. You can
+switch into a package in more than one place; it merely influences which
+symbol table is used by the compiler for the rest of that block. You can
+refer to variables and filehandles in other packages by prefixing the
+identifier with the package name and a double colon:
+C<$Package::Variable>. If the package name is null, the C<main> package
+as assumed. That is, C<$::sail> is equivalent to C<$main::sail>.
+
+(The old package delimiter was a single quote, but double colon
+is now the preferred delimiter, in part because it's more readable
+to humans, and in part because it's more readable to B<emacs> macros.
+It also makes C++ programmers feel like they know what's going on.)
+
+Packages may be nested inside other packages: C<$OUTER::INNER::var>. This
+implies nothing about the order of name lookups, however. All symbols
+are either local to the current package, or must be fully qualified
+from the outer package name down. For instance, there is nowhere
+within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
+It would treat package C<INNER> as a totally separate global package.
+
+Only identifiers starting with letters (or underscore) are stored in a
+package's symbol table. All other symbols are kept in package C<main>.
+In addition, the identifiers STDIN, STDOUT, STDERR, C<ARGV>,
+ARGVOUT, ENV, INC and SIG are forced to be in package C<main>,
+even when used for other purposes than their built-in one. Note also
+that, if you have a package called C<m>, C<s> or C<y>, then you can't use
+the qualified form of an identifier since it will be interpreted instead
+as a pattern match, a substitution, or a translation.
+
+(Variables beginning with underscore used to be forced into package
+main, but we decided it was more useful for package writers to be able
+to use leading underscore to indicate private variables and method names.)
+
+Eval()ed strings are compiled in the package in which the eval() was
+compiled. (Assignments to C<$SIG{}>, however, assume the signal
+handler specified is in the C<main. package. Qualify the signal handler
+name if you wish to have a signal handler in a package.) For an
+example, examine F<perldb.pl> in the Perl library. It initially switches
+to the C<DB> package so that the debugger doesn't interfere with variables
+in the script you are trying to debug. At various points, however, it
+temporarily switches back to the C<main> package to evaluate various
+expressions in the context of the C<main> package (or wherever you came
+from). See L<perldebug>.
+
+=head2 Symbol Tables
+
+The symbol table for a package happens to be stored in the associative
+array of that name appended with two colons. The main symbol table's
+name is thus C<%main::>, or C<%::> for short. Likewise the nested package
+mentioned earlier is named C<%OUTER::INNER::>.
+
+The value in each entry of the associative array is what you are
+referring to when you use the C<*name> notation. In fact, the following
+have the same effect, though the first is more efficient because it
+does the symbol table lookups at compile time:
+
+ local(*main::foo) = *main::bar; local($main::{'foo'}) =
+ $main::{'bar'};
+
+You can use this to print out all the variables in a package, for
+instance. Here is F<dumpvar.pl> from the Perl library:
+
+ package dumpvar;
+ sub main::dumpvar {
+ ($package) = @_;
+ local(*stab) = eval("*${package}::");
+ while (($key,$val) = each(%stab)) {
+ local(*entry) = $val;
+ if (defined $entry) {
+ print "\$$key = '$entry'\n";
+ }
+
+ if (defined @entry) {
+ print "\@$key = (\n";
+ foreach $num ($[ .. $#entry) {
+ print " $num\t'",$entry[$num],"'\n";
+ }
+ print ")\n";
+ }
+
+ if ($key ne "${package}::" && defined %entry) {
+ print "\%$key = (\n";
+ foreach $key (sort keys(%entry)) {
+ print " $key\t'",$entry{$key},"'\n";
+ }
+ print ")\n";
+ }
+ }
+ }
+
+Note that even though the subroutine is compiled in package C<dumpvar>,
+the name of the subroutine is qualified so that its name is inserted
+into package C<main>.
+
+Assignment to a symbol table entry performs an aliasing operation,
+i.e.,
+
+ *dick = *richard;
+
+causes variables, subroutines and filehandles accessible via the
+identifier C<richard> to also be accessible via the symbol C<dick>. If
+you only want to alias a particular variable or subroutine, you can
+assign a reference instead:
+
+ *dick = \$richard;
+
+makes $richard and $dick the same variable, but leaves
+@richard and @dick as separate arrays. Tricky, eh?
+
+=head2 Package Constructors and Destructors
+
+There are two special subroutine definitions that function as package
+constructors and destructors. These are the C<BEGIN> and C<END>
+routines. The C<sub> is optional for these routines.
+
+A C<BEGIN> subroutine is executed as soon as possible, that is, the
+moment it is completely defined, even before the rest of the containing
+file is parsed. You may have multiple C<BEGIN> blocks within a
+file--they will execute in order of definition. Because a C<BEGIN>
+block executes immediately, it can pull in definitions of subroutines
+and such from other files in time to be visible to the rest of the
+file.
+
+An C<END> subroutine is executed as late as possible, that is, when the
+interpreter is being exited, even if it is exiting as a result of a
+die() function. (But not if it's is 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 wil execute in reverse
+order of definition; that is: last in, first out (LIFO).
+
+Note that 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.
+
+=head2 Perl Classes
+
+There is no special class syntax in Perl 5, but a package may function
+as a class if it provides subroutines that function as methods. Such a
+package may also derive some of its methods from another class package
+by listing the other package name in its @ISA array. For more on
+this, see L<perlobj>.
+
+=head2 Perl Modules
+
+In Perl 5, the notion of packages has been extended into the notion of
+modules. A module is a package that is defined in a library file of
+the same name, and is designed to be reusable. 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 explicit exportation of any
+symbols. Or it can do a little of both.
+
+Perl modules are included by saying
+
+ use Module;
+
+or
+
+ use Module LIST;
+
+This is exactly equivalent to
+
+ BEGIN { require "Module.pm"; import Module; }
+
+or
+
+ BEGIN { require "Module.pm"; import Module LIST; }
+
+All Perl module files have the extension F<.pm>. C<use> assumes this so
+that you don't have to spell out "F<Module.pm>" in quotes. This also
+helps to differentiate new modules from old F<.pl> and F<.ph> files.
+Module names are also capitalized unless they're functioning as pragmas,
+"Pragmas" are in effect compiler directives, and are sometimes called
+"pragmatic modules" (or even "pragmata" if you're a classicist).
+
+Because the C<use> statement implies a C<BEGIN> block, the importation
+of semantics happens at the moment the C<use> statement is compiled,
+before the rest of the file is compiled. This is how it is able
+to function as a pragma mechanism, and also how modules are able to
+declare subroutines that are then visible as list operators for
+the rest of the current file. This will not work if you use C<require>
+instead of C<use>. Therefore, if you're planning on the module altering
+your namespace, use C<use>; otherwise, use C<require>. Otherwise you
+can get into this problem:
+
+ require Cwd; # make Cwd:: accessible
+ $here = Cwd::getcwd();
+
+ use Cwd; # import names from Cwd::
+ $here = getcwd();
+
+ require Cwd; # make Cwd:: accessible
+ $here = getcwd(); # oops! no main::getcwd()
+
+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
+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 or autoloaded subroutine definitions 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. The POSIX module
+happens to do both dynamic loading and autoloading, but the user can
+just say C<use POSIX> to get it all.
+
+For more information on writing extension modules, see L<perlapi>
+and L<perlguts>.
+
+=head1 NOTE
+
+Perl does not enforce private and public parts of its modules as you may
+have been used to in other languages like C++, Ada, or Modula-17. Perl
+doesn't have an infatuation with enforced privacy. It would prefer
+that you stayed out of its living room because you weren't invited, not
+because it has a shotgun.
+
+The module and its user have a contract, part of which is common law,
+and part of which is "written". Part of the common law contract is
+that a module doesn't pollute any namespace it wasn't asked to. The
+written contract for the module (AKA documentation) may make other
+provisions. But then you know when you C<use RedefineTheWorld> that
+you're redefining the world and willing to take the consequences.
+
+=head1 THE PERL MODULE LIBRARY
+
+A number of modules are included the the Perl distribution. These are
+described below, and all end in F<.pm>. You may also discover files in
+the library directory that end in either F<.pl> or F<.ph>. These are old
+libaries supplied so that old programs that use them still run. The
+F<.pl> files will all eventually be converted into standard modules, and
+the F<.ph> files made by B<h2ph> will probably end up as extension modules
+made by B<h2xs>. (Some F<.ph> values may already be available through the
+POSIX module.) The B<pl2pm> file in the distribution may help in your
+conversion, but it's just a mechanical process, so is far from bullet proof.
+
+=head2 Pragmatic Modules
+
+They work somewhat like pragmas in that they tend to affect the compilation of
+your program, and thus will usually only work well when used within a
+C<use>, or C<no>. These are locally scoped, so if an inner BLOCK
+may countermand any of these by saying
+
+ no integer;
+ no strict 'refs';
+
+which lasts until the end of that BLOCK.
+
+The following programs are defined (and have their own documentation).
+
+=over 12
+
+=item C<integer>
+
+Perl pragma to compute arithmetic in integer instead of double
+
+=item C<less>
+
+Perl pragma to request less of something from the compiler
+
+=item C<sigtrap>
+
+Perl pragma to enable stack backtrace on unexpected signals
+
+=item C<strict>
+
+Perl pragma to restrict unsafe constructs
+
+=item C<subs>
+
+Perl pragma to predeclare sub names
+
+=back
+
+=head2 Standard Modules
+
+The following modules are all expacted to behave in a well-defined
+manner with respect to namespace pollution because they use the
+Exporter module.
+See their own documentation for details.
+
+=over 12
+
+=item C<Abbrev>
+
+create an abbreviation table from a list
+
+=item C<AnyDBM_File>
+
+provide framework for multiple DBMs
+
+=item C<AutoLoader>
+
+load functions only on demand
+
+=item C<AutoSplit>
+
+split a package for autoloading
+
+=item C<Basename>
+
+parse file anme and path from a specification
+
+=item C<Benchmark>
+
+benchmark running times of code
+
+=item C<Carp>
+
+warn or die of errors (from perspective of caller)
+
+=item C<CheckTree>
+
+run many filetest checks on a tree
+
+=item C<Collate>
+
+compare 8-bit scalar data according to the current locale
+
+=item C<Config>
+
+access Perl configuration option
+
+=item C<Cwd>
+
+get pathname of current working directory
+
+=item C<DynaLoader>
+
+Dynamically load C libraries into Perl code
+
+=item C<English>
+
+use nice English (or B<awk>) names for ugly punctuation variables
+
+=item C<Env>
+
+Perl module that imports environment variables
+
+=item C<Exporter>
+
+module to control namespace manipulations
+
+=item C<Fcntl>
+
+load the C Fcntl.h defines
+
+=item C<FileHandle>
+
+supply object methods for filehandles
+
+=item C<Find>
+
+traverse a file tree
+
+=item C<Finddepth>
+
+traverse a directory structure depth-first
+
+=item C<Getopt>
+
+basic and extended getopt(3) processing
+
+=item C<MakeMaker>
+
+generate a Makefile for Perl extension
+
+=item C<Open2>
+
+open a process for both reading and writing
+
+=item C<Open3>
+
+open a process for reading, writing, and error handling
+
+=item C<POSIX>
+
+Perl interface to IEEE 1003.1 namespace
+
+=item C<Ping>
+
+check a host for upness
+
+=item C<Socket>
+
+load the C socket.h defines
+
+=back
+
+=head2 Extension Modules
+
+Extension modules are written in C (or a mix of Perl and C) and get
+dynamically loaded into Perl if and when you need them. Supported
+extension modules include the Socket, Fcntl, and POSIX modules.
+
+The following are popular C extension modules, which while available at
+Perl 5.0 release time, do not come not bundled (at least, not completely)
+due to their size, volatility, or simply lack of time for adequate testing
+and configuration across the multitude of platforms on which Perl was
+beta-tested. You are encouraged to look for them in archie(1L), the Perl
+FAQ or Meta-FAQ, the WWW page, and even their authors before randomly
+posting asking for their present condition and disposition. There's no
+guarantee that the names or addresses below have not changed since printing,
+and in fact, they probably have!
+
+=over 12
+
+=item C<Curses>
+
+Written by William Setzer <F<William_Setzer@ncsu.edu>>, while not
+included with the standard distribution, this extension module ports to
+most systems. FTP from your nearest Perl archive site, or try
+
+ ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz
+
+It is currently in alpha test, so the name and ftp location may
+change.
+
+
+=item C<DBI>
+
+This is the portable database interface written by
+<F<Tim.Bunce@ig.co.uk>>. This supersedes the many perl4 ports for
+database extensions. The official archive for DBperl extensions is
+F<ftp.demon.co.uk:/pub/perl/db>. This archive contains copies of perl4
+ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and
+Interbase, as well as rdb and shql and other non-SQL systems.
+
+=item C<DB_File>
+
+Fastest and most restriction-free of the DBM bindings, this extension module
+uses the popular Berkeley DB to tie() into your hashes. This has a
+standardly-distributed man page and dynamic loading extension module, but
+you'll have to fetch the Berkeley code yourself. See L<DB_File> for
+where.
+
+=item C<Sx>
+
+This extension module is a front to the Athena and Xlib libraries for Perl
+GUI progamming, originally written by by Dominic Giampaolo
+<F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric
+Chauveau <F<fmc@pasteur.fr>>. It's available for FTP from
+
+ ftp.pasteur.fr:/pub/Perl/Sx.tar.gz
+
+=item C<Tk>
+
+This extension module is an object-oriented Perl5 binding to the popular
+tcl/tk X11 package. However, you need know no TCL to use it!
+It was written by Malcolm Beattie <F<mbeattie@sable.ox.ac.uk>>.
+If you are unable to locate it using archie(1L) or a similar
+tool, you may try retrieving it from F</private/Tk-october.tar.gz>
+from Malcolm's machine listed above.
+
+=back
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
new file mode 100644
index 0000000000..e4f34ba48d
--- /dev/null
+++ b/pod/perlobj.pod
@@ -0,0 +1,251 @@
+=head1 NAME
+
+perlobj - Perl objects
+
+=head1 DESCRIPTION
+
+First of all, you need to understand what references are in Perl. See
+L<perlref> for that.
+
+Here are three very simple definitions that you should find reassuring.
+
+=over 4
+
+=item 1.
+
+An object is simply a reference that happens to know which class it
+belongs to.
+
+=item 2.
+
+A class is simply a package that happens to provide methods to deal
+with object references.
+
+=item 3.
+
+A method is simply a subroutine that expects an object reference (or
+a package name, for static methods) as the first argument.
+
+=back
+
+We'll cover these points now in more depth.
+
+=head2 An Object is Simply a Reference
+
+Unlike say C++, Perl doesn't provide any special syntax for
+constructors. A constructor is merely a subroutine that returns a
+reference that has been "blessed" into a class, generally the
+class that the subroutine is defined in. Here is a typical
+constructor:
+
+ package Critter;
+ sub new { bless {} }
+
+The C<{}> constructs a reference to an anonymous hash containing no
+key/value pairs. The bless() takes that reference and tells the object
+it references that it's now a Critter, and returns the reference.
+This is for convenience, since the referenced object itself knows that
+it has been blessed, and its reference to it could have been returned
+directly, like this:
+
+ sub new {
+ my $self = {};
+ bless $self;
+ return $self;
+ }
+
+In fact, you often see such a thing in more complicated constructors
+that wish to call methods in the class as part of the construction:
+
+ sub new {
+ my $self = {}
+ bless $self;
+ $self->initialize();
+ $self;
+ }
+
+Within the class package, the methods will typically deal with the
+reference as an ordinary reference. Outside the class package,
+the reference is generally treated as an opaque value that may
+only be accessed through the class's methods.
+
+A constructor may rebless a referenced object currently belonging to
+another class, but then the new class is responsible for all cleanup
+later. The previous blessing is forgotten, as an object may only
+belong to one class at a time. (Although of course it's free to
+inherit methods from many classes.)
+
+A clarification: Perl objects are blessed. References are not. Objects
+know which package they belong to. References do not. The bless()
+function simply uses the reference in order to find the object. Consider
+the following example:
+
+ $a = {};
+ $b = $a;
+ bless $a, BLAH;
+ print "\$b is a ", ref($b), "\n";
+
+This reports $b as being a BLAH, so obviously bless()
+operated on the object and not on the reference.
+
+=head2 A Class is Simply a Package
+
+Unlike say C++, Perl doesn't provide any special syntax for class
+definitions. You just use a package as a class by putting method
+definitions into the class.
+
+There is a special array within each package called @ISA which says
+where else to look for a method if you can't find it in the current
+package. This is how Perl implements inheritance. Each element of the
+@ISA array is just the name of another package that happens to be a
+class package. The classes are searched (depth first) for missing
+methods in the order that they occur in @ISA. The classes accessible
+through @ISA are known as base classes of the current class.
+
+If a missing method is found in one of the base classes, it is cached
+in the current class for efficiency. Changing @ISA or defining new
+subroutines invalidates the cache and causes Perl to do the lookup again.
+
+If a method isn't found, but an AUTOLOAD routine is found, then
+that is called on behalf of the missing method.
+
+If neither a method nor an AUTOLOAD routine is found in @ISA, then one
+last try is made for the method (or an AUTOLOAD routine) in a class
+called UNIVERSAL. If that doesn't work, Perl finally gives up and
+complains.
+
+Perl classes only do method inheritance. Data inheritance is left
+up to the class itself. By and large, this is not a problem in Perl,
+because most classes model the attributes of their object using
+an anonymous hash, which serves as its own little namespace to be
+carved up by the various classes that might want to do something
+with the object.
+
+=head2 A Method is Simply a Subroutine
+
+Unlike say C++, Perl doesn't provide any special syntax for method
+definition. (It does provide a little syntax for method invocation
+though. More on that later.) A method expects its first argument
+to be the object or package it is being invoked on. There are just two
+types of methods, which we'll call static and virtual, in honor of
+the two C++ method types they most closely resemble.
+
+A static method expects a class name as the first argument. It
+provides functionality for the class as a whole, not for any individual
+object belonging to the class. Constructors are typically static
+methods. Many static methods simply ignore their first argument, since
+they already know what package they're in, and don't care what package
+they were invoked via. (These aren't necessarily the same, since
+static methods follow the inheritance tree just like ordinary virtual
+methods.) Another typical use for static methods is to look up an
+object by name:
+
+ sub find {
+ my ($class, $name) = @_;
+ $objtable{$name};
+ }
+
+A virtual method expects an object reference as its first argument.
+Typically it shifts the first argument into a "self" or "this" variable,
+and then uses that as an ordinary reference.
+
+ sub display {
+ my $self = shift;
+ my @keys = @_ ? @_ : sort keys %$self;
+ foreach $key (@keys) {
+ print "\t$key => $self->{$key}\n";
+ }
+ }
+
+=head2 Method Invocation
+
+There are two ways to invoke a method, one of which you're already
+familiar with, and the other of which will look familiar. Perl 4
+already had an "indirect object" syntax that you use when you say
+
+ print STDERR "help!!!\n";
+
+This same syntax can be used to call either static or virtual methods.
+We'll use the two methods defined above, the static method to lookup
+an object reference and the virtual method to print out its attributes.
+
+ $fred = find Critter "Fred";
+ display $fred 'Height', 'Weight';
+
+These could be combined into one statement by using a BLOCK in the
+indirect object slot:
+
+ display {find Critter "Fred"} 'Height', 'Weight';
+
+For C++ fans, there's also a syntax using -> notation that does exactly
+the same thing. The parentheses are required if there are any arguments.
+
+ $fred = Critter->find("Fred");
+ $fred->display('Height', 'Weight');
+
+or in one statement,
+
+ Critter->find("Fred")->display('Height', 'Weight');
+
+There are times when one syntax is more readable, and times when the
+other syntax is more readable. The indirect object syntax is less
+cluttered, but it has the same ambiguity as ordinary list operators.
+Indirect object method calls are parsed using the same rule as list
+operators: "If it looks like a function, it is a function". (Presuming
+for the moment that you think two words in a row can look like a
+function name. C++ programmers seem to think so with some regularity,
+especially when the first word is "new".) Thus, the parens of
+
+ new Critter ('Barney', 1.5, 70)
+
+are assumed to surround ALL the arguments of the method call, regardless
+of what comes after. Saying
+
+ new Critter ('Bam' x 2), 1.4, 45
+
+would be equivalent to
+
+ Critter->new('Bam' x 2), 1.4, 45
+
+which is unlikely to do what you want.
+
+There are times when you wish to specify which class's method to use.
+In this case, you can call your method as an ordinary subroutine
+call, being sure to pass the requisite first argument explicitly:
+
+ $fred = MyCritter::find("Critter", "Fred");
+ MyCritter::display($fred, 'Height', 'Weight');
+
+Note however, that this does not do any inheritance. If you merely
+wish to specify that Perl should I<START> looking for a method in a
+particular package, use an ordinary method call, but qualify the method
+name with the package like this:
+
+ $fred = Critter->MyCritter::find("Fred");
+ $fred->MyCritter::display('Height', 'Weight');
+
+=head2 Destructors
+
+When the last reference to an object goes away, the object is
+automatically destroyed. (This may even be after you exit, if you've
+stored references in global variables.) If you want to capture control
+just before the object is freed, you may define a DESTROY method in
+your class. It will automatically be called at the appropriate moment,
+and you can do any extra cleanup you need to do.
+
+Perl doesn't do nested destruction for you. If your constructor
+reblessed a reference from one of your base classes, your DESTROY may
+need to call DESTROY for any base classes that need it. But this only
+applies to reblessed objects--an object reference that is merely
+I<CONTAINED> in the current object will be freed and destroyed
+automatically when the current object is freed.
+
+=head2 Summary
+
+That's about all there is to it. Now you just need to go off and buy a
+book about object-oriented design methodology, and bang your forehead
+with it for the next six months or so.
+
+=head1 SEE ALSO
+
+You should also check out L<perlbot> for other object tricks, traps, and tips.
diff --git a/pod/perlop.pod b/pod/perlop.pod
new file mode 100644
index 0000000000..d33ce931c2
--- /dev/null
+++ b/pod/perlop.pod
@@ -0,0 +1,1062 @@
+=head1 NAME
+
+perlop - Perl operators and precedence
+
+=head1 SYNOPSIS
+
+Perl operators have the following associativity and precedence,
+listed from highest precedence to lowest. Note that all operators
+borrowed from C keep the same precedence relationship with each other,
+even where C's precedence is slightly screwy. (This makes learning
+Perl easier for C folks.)
+
+ left terms and list operators (leftward)
+ left ->
+ nonassoc ++ --
+ right **
+ right ! ~ \ and unary + and -
+ left =~ !~
+ left * / % x
+ left + - .
+ left << >>
+ nonassoc named unary operators
+ nonassoc < > <= >= lt gt le ge
+ nonassoc == != <=> eq ne cmp
+ left &
+ left | ^
+ left &&
+ left ||
+ nonassoc ..
+ right ?:
+ right = += -= *= etc.
+ left , =>
+ nonassoc list operators (rightward)
+ left not
+ left and
+ left or xor
+
+In the following sections, these operators are covered in precedence order.
+
+=head1 DESCRIPTIONS
+
+=head2 Terms and List Operators (Leftward)
+
+Any TERM is of highest precedence of Perl. These includes variables,
+quote and quotelike operators, any expression in parentheses,
+and any function whose arguments are parenthesized. Actually, there
+aren't really functions in this sense, just list operators and unary
+operators behaving as functions because you put parentheses around
+the arguments. These are all documented in L<perlfunc>.
+
+If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
+is followed by a left parenthesis as the next token, the operator and
+arguments within parentheses are taken to be of highest precedence,
+just like a normal function call.
+
+In the absence of parentheses, the precedence of list operators such as
+C<print>, C<sort>, or C<chmod> is either very high or very low depending on
+whether you look at the left side of operator or the right side of it.
+For example, in
+
+ @ary = (1, 3, sort 4, 2);
+ print @ary; # prints 1324
+
+the commas on the right of the sort are evaluated before the sort, but
+the commas on the left are evaluated after. In other words, list
+operators tend to gobble up all the arguments that follow them, and
+then act like a simple TERM with regard to the preceding expression.
+Note that you have to be careful with parens:
+
+ # These evaluate exit before doing the print:
+ print($foo, exit); # Obviously not what you want.
+ print $foo, exit; # Nor is this.
+
+ # These do the print before evaluating exit:
+ (print $foo), exit; # This is what you want.
+ print($foo), exit; # Or this.
+ print ($foo), exit; # Or even this.
+
+Also note that
+
+ print ($foo & 255) + 1, "\n";
+
+probably doesn't do what you expect at first glance. See
+L<Named Unary Operators> for more discussion of this.
+
+Also parsed as terms are the C<do {}> and C<eval {}> constructs, as
+well as subroutine and method calls, and the anonymous
+constructors C<[]> and C<{}>.
+
+See also L<Quote and Quotelike Operators> toward the end of this section,
+as well as L<I/O Operators>.
+
+=head2 The Arrow Operator
+
+Just as in C and C++, "C<-E<gt>>" is an infix dereference operator. If the
+right side is either a C<[...]> or C<{...}> subscript, then the left side
+must be either a hard or symbolic reference to an array or hash (or
+a location capable of holding a hard reference, if it's an lvalue (assignable)).
+See L<perlref>.
+
+Otherwise, the right side is a method name or a simple scalar variable
+containing the method name, and the left side must either be an object
+(a blessed reference) or a class name (that is, a package name).
+See L<perlobj>.
+
+=head2 Autoincrement and Autodecrement
+
+"++" and "--" work as in C. That is, if placed before a variable, they
+increment or decrement the variable before returning the value, and if
+placed after, increment or decrement the variable after returning the value.
+
+The autoincrement operator has a little extra built-in magic to it. If
+you increment a variable that is numeric, or that has ever been used in
+a numeric context, you get a normal increment. If, however, the
+variable has only been used in string contexts since it was set, and
+has a value that is not null and matches the pattern
+C</^[a-zA-Z]*[0-9]*$/>, the increment is done as a string, preserving each
+character within its range, with carry:
+
+ print ++($foo = '99'); # prints '100'
+ print ++($foo = 'a0'); # prints 'a1'
+ print ++($foo = 'Az'); # prints 'Ba'
+ print ++($foo = 'zz'); # prints 'aaa'
+
+The autodecrement operator is not magical.
+
+=head2 Exponentiation
+
+Binary "**" is the exponentiation operator. Note that it binds even more
+tightly than unary minus, so -2**4 is -(2**4), not (-2)**4.
+
+=head2 Symbolic Unary Operators
+
+Unary "!" performs logical negation, i.e. "not". See also C<not> for a lower
+precedence version of this.
+
+Unary "-" performs arithmetic negation if the operand is numeric. If
+the operand is an identifier, a string consisting of a minus sign
+concatenated with the identifier is returned. Otherwise, if the string
+starts with a plus or minus, a string starting with the opposite sign
+is returned. One effect of these rules is that C<-bareword> is equivalent
+to C<"-bareword">.
+
+Unary "~" performs bitwise negation, i.e. 1's complement.
+
+Unary "+" has no effect whatsoever, even on strings. It is useful
+syntactically for separating a function name from a parenthesized expression
+that would otherwise be interpreted as the complete list of function
+arguments. (See examples above under L<List Operators>.)
+
+Unary "\" creates a reference to whatever follows it. See L<perlref>.
+Do not confuse this behavior with the behavior of backslash within a
+string, although both forms do convey the notion of protecting the next
+thing from interpretation.
+
+=head2 Binding Operators
+
+Binary "=~" binds an expression to a pattern match.
+Certain operations search or modify the string $_ by default. This
+operator makes that kind of operation work on some other string. The
+right argument is a search pattern, substitution, or translation. The
+left argument is what is supposed to be searched, substituted, or
+translated instead of the default $_. The return value indicates the
+success of the operation. (If the right argument is an expression
+rather than a search pattern, substitution, or translation, it is
+interpreted as a search pattern at run time. This is less efficient
+than an explicit search, since the pattern must be compiled every time
+the expression is evaluated--unless you've used C</o>.)
+
+Binary "!~" is just like "=~" except the return value is negated in
+the logical sense.
+
+=head2 Multiplicative Operators
+
+Binary "*" multiplies two numbers.
+
+Binary "/" divides two numbers.
+
+Binary "%" computes the modulus of the two numbers.
+
+Binary "x" is the repetition operator. In a scalar context, it
+returns a string consisting of the left operand repeated the number of
+times specified by the right operand. In a list context, if the left
+operand is a list in parens, it repeats the list.
+
+ print '-' x 80; # print row of dashes
+
+ print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
+
+ @ones = (1) x 80; # a list of 80 1's
+ @ones = (5) x @ones; # set all elements to 5
+
+
+=head2 Additive Operators
+
+Binary "+" returns the sum of two numbers.
+
+Binary "-" returns the difference of two numbers.
+
+Binary "." concatenates two strings.
+
+=head2 Shift Operators
+
+Binary "<<" returns the value of its left argument shifted left by the
+number of bits specified by the right argument. Arguments should be
+integers.
+
+Binary ">>" returns the value of its left argument shifted right by the
+number of bits specified by the right argument. Arguments should be
+integers.
+
+=head2 Named Unary Operators
+
+The various named unary operators are treated as functions with one
+argument, with optional parentheses. These include the filetest
+operators, like C<-f>, C<-M>, etc. See L<perlfunc>.
+
+If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
+is followed by a left parenthesis as the next token, the operator and
+arguments within parentheses are taken to be of highest precedence,
+just like a normal function call. Examples:
+
+ chdir $foo || die; # (chdir $foo) || die
+ chdir($foo) || die; # (chdir $foo) || die
+ chdir ($foo) || die; # (chdir $foo) || die
+ chdir +($foo) || die; # (chdir $foo) || die
+
+but, because * is higher precedence than ||:
+
+ chdir $foo * 20; # chdir ($foo * 20)
+ chdir($foo) * 20; # (chdir $foo) * 20
+ chdir ($foo) * 20; # (chdir $foo) * 20
+ chdir +($foo) * 20; # chdir ($foo * 20)
+
+ rand 10 * 20; # rand (10 * 20)
+ rand(10) * 20; # (rand 10) * 20
+ rand (10) * 20; # (rand 10) * 20
+ rand +(10) * 20; # rand (10 * 20)
+
+See also L<"List Operators">.
+
+=head2 Relational Operators
+
+Binary "<" returns true if the left argument is numerically less than
+the right argument.
+
+Binary ">" returns true if the left argument is numerically greater
+than the right argument.
+
+Binary "<=" returns true if the left argument is numerically less than
+or equal to the right argument.
+
+Binary ">=" returns true if the left argument is numerically greater
+than or equal to the right argument.
+
+Binary "lt" returns true if the left argument is stringwise less than
+the right argument.
+
+Binary "gt" returns true if the left argument is stringwise greater
+than the right argument.
+
+Binary "le" returns true if the left argument is stringwise less than
+or equal to the right argument.
+
+Binary "ge" returns true if the left argument is stringwise greater
+than or equal to the right argument.
+
+=head2 Equality Operators
+
+Binary "==" returns true if the left argument is numerically equal to
+the right argument.
+
+Binary "!=" returns true if the left argument is numerically not equal
+to the right argument.
+
+Binary "<=>" returns -1, 0, or 1 depending on whether the left argument is numerically
+less than, equal to, or greater than the right argument.
+
+Binary "eq" returns true if the left argument is stringwise equal to
+the right argument.
+
+Binary "ne" returns true if the left argument is stringwise not equal
+to the right argument.
+
+Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise
+less than, equal to, or greater than the right argument.
+
+=head2 Bitwise And
+
+Binary "&" returns its operators ANDed together bit by bit.
+
+=head2 Bitwise Or and Exclusive Or
+
+Binary "|" returns its operators ORed together bit by bit.
+
+Binary "^" returns its operators XORed together bit by bit.
+
+=head2 C-style Logical And
+
+Binary "&&" performs a short-circuit logical AND operation. That is,
+if the left operand is false, the right operand is not even evaluated.
+Scalar or list context propagates down to the right operand if it
+is evaluated.
+
+=head2 C-style Logical Or
+
+Binary "||" performs a short-circuit logical OR operation. That is,
+if the left operand is true, the right operand is not even evaluated.
+Scalar or list context propagates down to the right operand if it
+is evaluated.
+
+The C<||> and C<&&> operators differ from C's in that, rather than returning
+0 or 1, they return the last value evaluated. Thus, a reasonably portable
+way to find out the home directory (assuming it's not "0") might be:
+
+ $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
+ (getpwuid($<))[7] || die "You're homeless!\n";
+
+As more readable alternatives to C<&&> and C<||>, Perl provides "and" and
+"or" operators (see below). The short-circuit behavior is identical. The
+precedence of "and" and "or" is much lower, however, so that you can
+safely use them after a list operator without the need for
+parentheses:
+
+ unlink "alpha", "beta", "gamma"
+ or gripe(), next LINE;
+
+With the C-style operators that would have been written like this:
+
+ unlink("alpha", "beta", "gamma")
+ || (gripe(), next LINE);
+
+=head2 Range Operator
+
+Binary ".." is the range operator, which is really two different
+operators depending on the context. In a list context, it returns an
+array of values counting (by ones) from the left value to the right
+value. This is useful for writing C<for (1..10)> loops and for doing
+slice operations on arrays. Be aware that under the current implementation,
+a temporary array is created, so you'll burn a lot of memory if you
+write something like this:
+
+ for (1 .. 1_000_000) {
+ # code
+ }
+
+In a scalar context, ".." returns a boolean value. The operator is
+bistable, like a flip-flop, and emulates the line-range (comma) operator
+of B<sed>, B<awk>, and various editors. Each ".." operator maintains its
+own boolean state. It is false as long as its left operand is false.
+Once the left operand is true, the range operator stays true until the
+right operand is true, I<AFTER> which the range operator becomes false
+again. (It doesn't become false till the next time the range operator is
+evaluated. It can test the right operand and become false on the same
+evaluation it became true (as in B<awk>), but it still returns true once.
+If you don't want it to test the right operand till the next evaluation
+(as in B<sed>), use three dots ("...") instead of two.) The right
+operand is not evaluated while the operator is in the "false" state, and
+the left operand is not evaluated while the operator is in the "true"
+state. The precedence is a little lower than || and &&. The value
+returned is either the null string for false, or a sequence number
+(beginning with 1) for true. The sequence number is reset for each range
+encountered. The final sequence number in a range has the string "E0"
+appended to it, which doesn't affect its numeric value, but gives you
+something to search for if you want to exclude the endpoint. You can
+exclude the beginning point by waiting for the sequence number to be
+greater than 1. If either operand of scalar ".." is a numeric literal,
+that operand is implicitly compared to the C<$.> variable, the current
+line number. Examples:
+
+As a scalar operator:
+
+ if (101 .. 200) { print; } # print 2nd hundred lines
+ next line if (1 .. /^$/); # skip header lines
+ s/^/> / if (/^$/ .. eof()); # quote body
+
+As a list operator:
+
+ for (101 .. 200) { print; } # print $_ 100 times
+ @foo = @foo[$[ .. $#foo]; # an expensive no-op
+ @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
+
+The range operator (in a list context) makes use of the magical
+autoincrement algorithm if the operaands are strings. You
+can say
+
+ @alphabet = ('A' .. 'Z');
+
+to get all the letters of the alphabet, or
+
+ $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
+
+to get a hexadecimal digit, or
+
+ @z2 = ('01' .. '31'); print $z2[$mday];
+
+to get dates with leading zeros. If the final value specified is not
+in the sequence that the magical increment would produce, the sequence
+goes until the next value would be longer than the final value
+specified.
+
+=head2 Conditional Operator
+
+Ternary "?:" is the conditional operator, just as in C. It works much
+like an if-then-else. If the argument before the ? is true, the
+argument before the : is returned, otherwise the argument after the :
+is returned. Scalar or list context propagates downward into the 2nd
+or 3rd argument, whichever is selected. The operator may be assigned
+to if both the 2nd and 3rd arguments are legal lvalues (meaning that you
+can assign to them):
+
+ ($a_or_b ? $a : $b) = $c;
+
+Note that this is not guaranteed to contribute to the readability of
+your program.
+
+=head2 Assigment Operators
+
+"=" is the ordinary assignment operator.
+
+Assignment operators work as in C. That is,
+
+ $a += 2;
+
+is equivalent to
+
+ $a = $a + 2;
+
+although without duplicating any side effects that dereferencing the lvalue
+might trigger, such as from tie(). Other assignment operators work similarly.
+The following are recognized:
+
+ **= += *= &= <<= &&=
+ -= /= |= >>= ||=
+ .= %= ^=
+ x=
+
+Note that while these are grouped by family, they all have the precedence
+of assignment.
+
+Unlike in C, the assignment operator produces a valid lvalue. Modifying
+an assignment is equivalent to doing the assignment and then modifying
+the variable that was assigned to. This is useful for modifying
+a copy of something, like this:
+
+ ($tmp = $global) =~ tr [A-Z] [a-z];
+
+Likewise,
+
+ ($a += 2) *= 3;
+
+is equivalent to
+
+ $a += 2;
+ $a *= 3;
+
+=head2
+
+Binary "," is the comma operator. In a scalar context it evaluates
+its left argument, throws that value away, then evaluates its right
+argument and returns that value. This is just like C's comma operator.
+
+In a list context, it's just the list argument separator, and inserts
+both its arguments into the list.
+
+=head2 List Operators (Rightward)
+
+On the right side of a list operator, it has very low precedence,
+such that it controls all comma-separated expressions found there.
+The only operators with lower precedence are the logical operators
+"and", "or", and "not", which may be used to evaluate calls to list
+operators without the need for extra parentheses:
+
+ open HANDLE, "filename"
+ or die "Can't open: $!\n";
+
+See also discussion of list operators in L<List Operators (Leftward)>.
+
+=head2 Logical Not
+
+Unary "not" returns the logical negation of the expression to its right.
+It's the equivalent of "!" except for the very low precedence.
+
+=head2 Logical And
+
+Binary "and" returns the logical conjunction of the two surrounding
+expressions. It's equivalent to && except for the very low
+precedence. This means that it short-circuits: i.e. the right
+expression is evaluated only if the left expression is true.
+
+=head2 Logical or and Exclusive Or
+
+Binary "or" returns the logical disjunction of the two surrounding
+expressions. It's equivalent to || except for the very low
+precedence. This means that it short-circuits: i.e. the right
+expression is evaluated only if the left expression is false.
+
+Binary "xor" returns the exclusive-OR of the two surrounding expressions.
+It cannot short circuit, of course.
+
+=head2 C Operators Missing From Perl
+
+Here is what C has that Perl doesn't:
+
+=over 8
+
+=item unary &
+
+Address-of operator. (But see the "\" operator for taking a reference.)
+
+=item unary *
+
+Dereference-address operator. (Perl's prefix dereferencing
+operators are typed: $, @, %, and &.)
+
+=item (TYPE)
+
+Type casting operator.
+
+=back
+
+=head2 Quote and Quotelike Operators
+
+While we usually think of quotes as literal values, in Perl they
+function as operators, providing various kinds of interpolating and
+pattern matching capabilities. Perl provides customary quote characters
+for these behaviors, but also provides a way for you to choose your
+quote character for any of them. In the following table, a C<{}> represents
+any pair of delimiters you choose. Non-bracketing delimiters use
+the same character fore and aft, but the 4 sorts of brackets
+(round, angle, square, curly) will all nest.
+
+ Customary Generic Meaning Interpolates
+ '' q{} Literal no
+ "" qq{} Literal yes
+ `` qx{} Command yes
+ qw{} Word list no
+ // m{} Pattern match yes
+ s{}{} Substitution yes
+ tr{}{} Translation no
+
+For constructs that do interpolation, variables beginning with "C<$> or "C<@>"
+are interpolated, as are the following sequences:
+
+ \t tab
+ \n newline
+ \r return
+ \f form feed
+ \v vertical tab, whatever that is
+ \b backspace
+ \a alarm (bell)
+ \e escape
+ \033 octal char
+ \x1b hex char
+ \c[ control char
+ \l lowercase next char
+ \u uppercase next char
+ \L lowercase till \E
+ \U uppercase till \E
+ \E end case modification
+ \Q quote regexp metacharacters till \E
+
+Patterns are subject to an additional level of interpretation as a
+regular expression. This is done as a second pass, after variables are
+interpolated, so that regular expressions may be incorporated into the
+pattern from the variables. If this is not what you want, use C<\Q> to
+interpolate a variable literally.
+
+Apart from the above, there are no multiple levels of interpolation. In
+particular, contrary to the expectations of shell programmers, backquotes
+do I<NOT> interpolate within double quotes, nor do single quotes impede
+evaluation of variables when used within double quotes.
+
+=over 8
+
+=item ?PATTERN?
+
+This is just like the C</pattern/> search, except that it matches only
+once between calls to the reset() operator. This is a useful
+optimization when you only want to see the first occurrence of
+something in each file of a set of files, for instance. Only C<??>
+patterns local to the current package are reset.
+
+This usage is vaguely deprecated, and may be removed in some future
+version of Perl.
+
+=item m/PATTERN/gimosx
+
+=item /PATTERN/gimosx
+
+Searches a string for a pattern match, and in a scalar context returns
+true (1) or false (''). If no string is specified via the C<=~> or
+C<!~> operator, the $_ string is searched. (The string specified with
+C<=~> need not be an lvalue--it may be the result of an expression
+evaluation, but remember the C<=~> binds rather tightly.) See also
+L<perlre>.
+
+Options are:
+
+ g Match globally, i.e. find all occurrences.
+ i Do case-insensitive pattern matching.
+ m Treat string as multiple lines.
+ o Only compile pattern once.
+ s Treat string as single line.
+ x Use extended regular expressions.
+
+If "/" is the delimiter then the initial C<m> is optional. With the C<m>
+you can use any pair of non-alphanumeric, non-whitespace characters as
+delimiters. This is particularly useful for matching Unix path names
+that contain "/", to avoid LTS (leaning toothpick syndrome).
+
+PATTERN may contain variables, which will be interpolated (and the
+pattern recompiled) every time the pattern search is evaluated. (Note
+that C<$)> and C<$|> might not be 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 the life of the script. However, mentioning
+C</o> constitutes a promise that you won't change the variables in the pattern.
+If you change them, Perl won't even notice.
+
+If the PATTERN evaluates to a null string, the most recently executed
+(and successfully compiled) regular expression is used instead.
+
+If used in a context that requires a list value, a pattern match returns a
+list consisting of the subexpressions matched by the parentheses in the
+pattern, i.e. ($1, $2, $3...). (Note that here $1 etc. are also set, and
+that this differs from Perl 4's behavior.) If the match fails, a null
+array is returned. If the match succeeds, but there were no parentheses,
+a list value of (1) is returned.
+
+Examples:
+
+ open(TTY, '/dev/tty');
+ <TTY> =~ /^y/i && foo(); # do foo if desired
+
+ if (/Version: *([0-9.]*)/) { $version = $1; }
+
+ next if m#^/usr/spool/uucp#;
+
+ # poor man's grep
+ $arg = shift;
+ while (<>) {
+ print if /$arg/o; # compile only once
+ }
+
+ if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
+
+This last example splits $foo into the first two words and the
+remainder of the line, and assigns those three fields to $F1, $F2 and
+$Etc. The conditional is true if any variables were assigned, i.e. if
+the pattern matched.
+
+The C</g> modifier specifies global pattern matching--that is, matching
+as many times as possible within the string. How it behaves depends on
+the context. In a list context, it returns a list of all the
+substrings matched by all the parentheses in the regular expression.
+If there are no parentheses, it returns a list of all the matched
+strings, as if there were parentheses around the whole pattern.
+
+In a scalar context, C<m//g> iterates through the string, returning TRUE
+each time it matches, and FALSE when it eventually runs out of
+matches. (In other words, it remembers where it left off last time and
+restarts the search at that point. You can actually find the current
+match position of a string using the pos() function--see L<perlfunc>.)
+If you modify the string in any way, the match position is reset to the
+beginning. Examples:
+
+ # list context
+ ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
+
+ # scalar context
+ $/ = ""; $* = 1; # $* deprecated in Perl 5
+ while ($paragraph = <>) {
+ while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
+ $sentences++;
+ }
+ }
+ print "$sentences\n";
+
+=item q/STRING/
+
+=item C<'STRING'>
+
+A single-quoted, literal string. Backslashes are ignored, unless
+followed by the delimiter or another backslash, in which case the
+delimiter or backslash is interpolated.
+
+ $foo = q!I said, "You said, 'She said it.'"!;
+ $bar = q('This is it.');
+
+=item qq/STRING/
+
+=item "STRING"
+
+A double-quoted, interpolated string.
+
+ $_ .= qq
+ (*** The previous line contains the naughty word "$1".\n)
+ if /(tcl|rexx|python)/; # :-)
+
+=item qx/STRING/
+
+=item `STRING`
+
+A string which is interpolated and then executed as a system command.
+The collected standard output of the command is returned. In scalar
+context, it comes back as a single (potentially multi-line) string.
+In list context, returns a list of lines (however you've defined lines
+with $/ or $INPUT_RECORD_SEPARATOR).
+
+ $today = qx{ date };
+
+See L<I/O Operators> for more discussion.
+
+=item qw/STRING/
+
+Returns a list of the words extracted out of STRING, using embedded
+whitespace as the word delimiters. It is exactly equivalent to
+
+ split(' ', q/STRING/);
+
+Some frequently seen examples:
+
+ use POSIX qw( setlocale localeconv )
+ @EXPORT = qw( foo bar baz );
+
+=item s/PATTERN/REPLACEMENT/egimosx
+
+Searches a string for a pattern, and if found, replaces that pattern
+with the replacement text and returns the number of substitutions
+made. Otherwise it returns false (0).
+
+If no string is specified via the C<=~> or C<!~> operator, the C<$_>
+variable is searched and modified. (The string specified with C<=~> must
+be a scalar variable, an array element, a hash element, or an assignment
+to one of those, i.e. an lvalue.)
+
+If the delimiter chosen is single quote, no variable interpolation is
+done on either the PATTERN or the REPLACEMENT. Otherwise, if the
+PATTERN contains a $ that looks like a variable rather than an
+end-of-string test, the variable will be interpolated into the pattern
+at run-time. If you only want the pattern compiled once the first time
+the variable is interpolated, use the C</o> option. If the pattern
+evaluates to a null string, the most recently executed (and successfully compiled) regular
+expression is used instead. See L<perlre> for further explanation on these.
+
+Options are:
+
+ e Evaluate the right side as an expression.
+ g Replace globally, i.e. all occurrences.
+ i Do case-insensitive pattern matching.
+ m Treat string as multiple lines.
+ o Only compile pattern once.
+ s Treat string as single line.
+ x Use extended regular expressions.
+
+Any non-alphanumeric, non-whitespace delimiter may replace the
+slashes. If single quotes are used, no interpretation is done on the
+replacement string (the C</e> modifier overrides this, however). If
+backquotes are used, the replacement string is a command to execute
+whose output will be used as the actual replacement text. 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<sE<lt>fooE<gt>/bar/>. A C</e> will cause the
+replacement portion to be interpreter as a full-fledged Perl expression
+and eval()ed right then and there. It is, however, syntax checked at
+compile-time.
+
+Examples:
+
+ s/\bgreen\b/mauve/g; # don't change wintergreen
+
+ $path =~ s|/usr/bin|/usr/local/bin|;
+
+ s/Login: $foo/Login: $bar/; # run-time pattern
+
+ ($foo = $bar) =~ s/this/that/;
+
+ $count = ($paragraph =~ s/Mister\b/Mr./g);
+
+ $_ = 'abc123xyz';
+ s/\d+/$&*2/e; # yields 'abc246xyz'
+ s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
+ s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
+
+ s/%(.)/$percent{$1}/g; # change percent escapes; no /e
+ s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
+ s/^=(\w+)/&pod($1)/ge; # use function call
+
+ # /e's can even nest; this will expand
+ # simple embedded variables in $_
+ s/(\$\w+)/$1/eeg;
+
+ # Delete C comments.
+ $program =~ s {
+ /\* (?# Match the opening delimiter.)
+ .*? (?# Match a minimal number of characters.)
+ \*/ (?# Match the closing delimiter.)
+ } []gsx;
+
+ s/^\s*(.*?)\s*$/$1/; # trim white space
+
+ s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
+
+Note the use of $ instead of \ in the last example. Unlike
+B<sed>, we only use the \<I<digit>> form in the left hand side.
+Anywhere else it's $<I<digit>>.
+
+Occasionally, you can't just use a C</g> to get all the changes
+to occur. Here are two common cases:
+
+ # put commas in the right places in an integer
+ 1 while s/(.*\d)(\d\d\d)/$1,$2/g; # perl4
+ 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g; # perl5
+
+ # expand tabs to 8-column spacing
+ 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
+
+
+=item tr/SEARCHLIST/REPLACEMENTLIST/cds
+
+=item y/SEARCHLIST/REPLACEMENTLIST/cds
+
+Translates all occurrences of the characters found in the search list
+with the corresponding character in the replacement list. It returns
+the number of characters replaced or deleted. If no string is
+specified via the =~ or !~ operator, the $_ string is translated. (The
+string specified with =~ must be a scalar variable, an array element,
+or an assignment to one of those, i.e. an lvalue.) For B<sed> devotees,
+C<y> is provided as a synonym for C<tr>. If the 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/>.
+
+Options:
+
+ c Complement the SEARCHLIST.
+ d Delete found but unreplaced characters.
+ s Squash duplicate replaced characters.
+
+If the C</c> modifier is specified, the SEARCHLIST character set is
+complemented. If the C</d> modifier is specified, any characters specified
+by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note
+that this is slightly more flexible than the behavior of some B<tr>
+programs, which delete anything they find in the SEARCHLIST, period.)
+If the C</s> modifier is specified, sequences of characters that were
+translated to the same character are squashed down to a single instance of the
+character.
+
+If the C</d> modifier is used, the REPLACEMENTLIST is always interpreted
+exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter
+than the SEARCHLIST, the final character is replicated till it is long
+enough. If the REPLACEMENTLIST is null, the SEARCHLIST is replicated.
+This latter is useful for counting characters in a class or for
+squashing character sequences in a class.
+
+Examples:
+
+ $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case
+
+ $cnt = tr/*/*/; # count the stars in $_
+
+ $cnt = $sky =~ tr/*/*/; # count the stars in $sky
+
+ $cnt = tr/0-9//; # count the digits in $_
+
+ tr/a-zA-Z//s; # bookkeeper -> bokeper
+
+ ($HOST = $host) =~ tr/a-z/A-Z/;
+
+ tr/a-zA-Z/ /cs; # change non-alphas to single space
+
+ tr [\200-\377]
+ [\000-\177]; # delete 8th bit
+
+Note that because the translation table is built at compile time, neither
+the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote
+interpolation. That means that if you want to use variables, you must use
+an eval():
+
+ eval "tr/$oldlist/$newlist/";
+ die $@ if $@;
+
+ eval "tr/$oldlist/$newlist/, 1" or die $@;
+
+=back
+
+=head2 I/O Operators
+
+There are several I/O operators you should know about.
+A string is enclosed by backticks (grave accents) first undergoes
+variable substitution just like a double quoted string. It is then
+interpreted as a command, and the output of that command is the value
+of the pseudo-literal, like in a shell. In a scalar context, a single
+string consisting of all the output is returned. In a list context,
+a list of values is returned, one for each line of output. (You can
+set C<$/> to use a different line terminator.) The command is executed
+each time the pseudo-literal is evaluated. The status value of the
+command is returned in C<$?> (see L<perlvar> for the interpretation
+of C<$?>). Unlike in B<csh>, no translation is done on the return
+data--newlines remain newlines. Unlike in any of the shells, single
+quotes do not hide variable names in the command from interpretation.
+To pass a $ through to the shell you need to hide it with a backslash.
+The generalized form of backticks is C<qx//>.
+
+Evaluating a filehandle in angle brackets yields the next line from
+that file (newline included, so it's never false until end of file, at which
+time an undefined value is returned). Ordinarily you must assign that
+value to a variable, but there is one situation where an automatic
+assignment happens. I<If and ONLY if> the input symbol is the only
+thing inside the conditional of a C<while> loop, the value is
+automatically assigned to the variable C<$_>. (This may seem like an
+odd thing to you, but you'll use the construct in almost every Perl
+script you write.) Anyway, the following lines are equivalent to each
+other:
+
+ while ($_ = <STDIN>) { print; }
+ while (<STDIN>) { print; }
+ for (;<STDIN>;) { print; }
+ print while $_ = <STDIN>;
+ print while <STDIN>;
+
+The filehandles STDIN, STDOUT and STDERR are predefined. (The
+filehandles C<stdin>, C<stdout> and C<stderr> will also work except in
+packages, where they would be interpreted as local identifiers rather
+than global.) Additional filehandles may be created with the open()
+function.
+
+If a <FILEHANDLE> is used in a context that is looking for a list, a
+list consisting of all the input lines is returned, one line per list
+element. It's easy to make a I<LARGE> data space this way, so use with
+care.
+
+The null filehandle <> is special and can be used to emulate the
+behavior of B<sed> and B<awk>. Input from <> comes either from
+standard input, or from each file listed on the command line. Here's
+how it works: the first time <> is evaluated, the @ARGV array is
+checked, and if it is null, C<$ARGV[0]> is set to "-", which when opened
+gives you standard input. The @ARGV array is then processed as a list
+of filenames. The loop
+
+ while (<>) {
+ ... # code for each line
+ }
+
+is equivalent to the following Perl-like pseudo code:
+
+ unshift(@ARGV, '-') if $#ARGV < $[;
+ while ($ARGV = shift) {
+ open(ARGV, $ARGV);
+ while (<ARGV>) {
+ ... # code for each line
+ }
+ }
+
+except that it isn't so cumbersome to say, and will actually work. It
+really does shift array @ARGV and put the current filename into variable
+$ARGV. It also uses filehandle I<ARGV> internally--<> is just a synonym
+for <ARGV>, which is magical. (The pseudo code above doesn't work
+because it treats <ARGV> as non-magical.)
+
+You can modify @ARGV before the first <> as long as the array ends up
+containing the list of filenames you really want. Line numbers (C<$.>)
+continue as if the input were one big happy file. (But see example
+under eof() for how to reset line numbers on each file.)
+
+If you want to set @ARGV to your own list of files, go right ahead. If
+you want to pass switches into your script, you can use one of the
+Getopts modules or put a loop on the front like this:
+
+ while ($_ = $ARGV[0], /^-/) {
+ shift;
+ last if /^--$/;
+ if (/^-D(.*)/) { $debug = $1 }
+ if (/^-v/) { $verbose++ }
+ ... # other switches
+ }
+ while (<>) {
+ ... # code for each line
+ }
+
+The <> symbol will return FALSE only once. If you call it again after
+this it will assume you are processing another @ARGV list, and if you
+haven't set @ARGV, will input from STDIN.
+
+If the string inside the angle brackets is a reference to a scalar
+variable (e.g. <$foo>), then that variable contains the name of the
+filehandle to input from.
+
+If the string inside angle brackets is not a filehandle, it is
+interpreted as a filename pattern to be globbed, and either a list of
+filenames or the next filename in the list is returned, depending on
+context. One level of $ interpretation is done first, but you can't
+say C<E<lt>$fooE<gt>> because that's an indirect filehandle as explained in the
+previous paragraph. You could insert curly brackets to force
+interpretation as a filename glob: C<E<lt>${foo}E<gt>>. (Alternately, you can
+call the internal function directly as C<glob($foo)>, which is probably
+the right way to have done it in the first place.) Example:
+
+ while (<*.c>) {
+ chmod 0644, $_;
+ }
+
+is equivalent to
+
+ open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
+ while (<FOO>) {
+ chop;
+ chmod 0644, $_;
+ }
+
+In fact, it's currently implemented that way. (Which means it will not
+work on filenames with spaces in them unless you have csh(1) on your
+machine.) Of course, the shortest way to do the above is:
+
+ chmod 0644, <*.c>;
+
+Because globbing invokes a shell, it's often faster to call readdir() yourself
+and just do your own grep() on the filenames. Furthermore, due to its current
+implementation of using a shell, the glob() routine may get "Arg list too
+long" errors (unless you've installed tcsh(1L) as F</bin/csh>).
+
+=head2 Constant Folding
+
+Like C, Perl does a certain amount of expression evaluation at
+compile time, whenever it determines that all of the arguments to an
+operator are static and have no side effects. In particular, string
+concatenation happens at compile time between literals that don't do
+variable substitution. Backslash interpretation also happens at
+compile time. You can say
+
+ 'Now is the time for all' . "\n" .
+ 'good men to come to.'
+
+and this all reduces to one string internally. Likewise, if
+you say
+
+ foreach $file (@filenames) {
+ if (-s $file > 5 + 100 * 2**16) { ... }
+ }
+
+the compiler will pre-compute the number that
+expression represents so that the interpreter
+won't have to.
+
+
+=head2 Integer arithmetic
+
+By default Perl assumes that it must do most of its arithmetic in
+floating point. But by saying
+
+ use integer;
+
+you may tell the compiler that it's okay to use integer operations
+from here to the end of the enclosing BLOCK. An inner BLOCK may
+countermand this by saying
+
+ no integer;
+
+which lasts until the end of that BLOCK.
+
diff --git a/pod/perlovl.pod b/pod/perlovl.pod
new file mode 100644
index 0000000000..db00f4dbf1
--- /dev/null
+++ b/pod/perlovl.pod
@@ -0,0 +1,363 @@
+=head1 NAME
+
+perlovl - perl overloading semantics
+
+=head1 SYNOPSIS
+
+ package SomeThing;
+
+ %OVERLOAD = (
+ '+' => \&myadd,
+ '-' => \&mysub,
+ # etc
+ );
+ ...
+
+ package main;
+ $a = new SomeThing 57;
+ $b=5+$a;
+
+=head1 CAVEAT SCRIPTOR
+
+Overloading of operators is a subject not to be taken lightly.
+Neither its precise implementation, syntax, nor semantics are
+100% endorsed by Larry Wall. So any of these may be changed
+at some point in the future.
+
+=head1 DESCRIPTION
+
+=head2 Declaration of overloaded functions
+
+ package Number;
+ %OVERLOAD = (
+ "+" => \&add,
+ "*=" => "muas"
+ );
+
+declares function Number::add() for addition, and method muas() in
+the "class" C<Number> (or one of its base classes)
+for the assignment form C<*=> of multiplication. Legal values of this
+hash array are values legal inside C<&{ ... }> call, so the name of a
+subroutine, a reference to a subroutine, or an anonymous subroutine
+will all work.
+
+The subroutine C<$OVERLOAD{"+"}> will be called to execute C<$a+$b> if $a
+is a reference to an object blessed into the package C<Number>, or $a is
+not an object from a package with defined mathemagic addition, but $b is a
+reference to a C<Number>. It can be called also in other situations, like
+C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical
+methods refer to methods triggered by an overloaded mathematical
+operator.)
+
+=head2 Calling Conventions for Binary Operations
+
+The functions in C<values %OVERLOAD> are called with three (in one
+particular case with four, see L<Last Resort>) arguments. If the
+corresponding operation is binary, then the first two arguments are the
+two arguments of the operation. However, due to general object calling
+conventions, the first argument should be always an object in the package,
+so in the situation of C<7+$a>, the order of arguments is interchanged.
+Most probably it does not matter for implementation of the addition
+method, but whether the arguments are reversed is vital for the
+subtraction method. The subroutine can query this information by
+examining the third argument, which can take three different values:
+
+=over 7
+
+=item FALSE
+
+the order of arguments is as in the current operation.
+
+=item TRUE
+
+the arguments are reversed.
+
+=item C<undef>
+
+the current operation is an assignment variant (as in
+C<$a+=7>), but the usual function is called instead. This additional
+information can be used to generate some optimizations.
+
+=back
+
+=head2 Calling Conventions for Unary Operations
+
+Unary operation are considered binary operations with the second
+argument being C<undef>. Thus C<$OVERLOAD{"++"}> is called with
+arguments C<($a,undef,'')> when $a++ is executed.
+
+=head2 Overloadable Operations
+
+The following keys of %OVERLOAD are recognized:
+
+=over 5
+
+=item * I<Arithmetic operations>
+
+ "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
+ "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
+
+For these operations a substituted non-assignment variant can be called if
+the assignment variant is not available. Methods for operations "C<+>",
+"C<->", "C<+=>", and "C<-=>" can be called to automatically generate
+increment and decrement methods. The operations "C<->" can be used to
+autogenerate missing methods for unary minus or C<abs>.
+
+=item * I<Comparison operations>
+
+ "<", "<=", ">", ">=", "==", "!=", "<=>",
+ "lt", "le", "gt", "ge", "eq", "ne", "cmp",
+
+If the corresponding "spaceship" variant is available, it can be
+used to substitute for the missing operation. During C<sort>ing
+arrays, C<cmp> is used to compare values subject to %OVERLOAD.
+
+=item * I<Bit operations>
+
+ "&", "^", "|", "neg", "!", "~",
+
+"C<neg>" stands for unary minus. If the method for C<neg> is not
+specified, it can be autogenerated using on the method for subtraction.
+
+=item * I<Increment and decrement>
+
+ "++", "--",
+
+If undefined, addition and subtraction methods can be
+used instead. These operations are called both in prefix and
+postfix form.
+
+=item * I<Transcendental functions>
+
+ "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
+
+If C<abs> is unavailable, it can be autogenerated using methods
+for "<" or "<=>" combined with either unary minus or subtraction.
+
+=item * I<Boolean, string and numeric conversion>
+
+ "bool", "\"\"", "0+",
+
+If one or two of these operations are unavailable, the remaining ones can
+be used instead. C<bool> is used in the flow control operators
+(like C<while>) and for the ternary "C<?:>" operation. These functions can
+return any arbitrary Perl value. If the corresponding operation for this value
+is overloaded too, that operation will be called again with this value.
+
+=item * I<Special>
+
+ "nomethod", "fallback", "=",
+
+see L<SPECIAL KEYS OF %OVERLOAD>.
+
+=back
+
+See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
+
+=head1 SPECIAL KEYS OF %OVERLOAD
+
+Three keys are recognized by Perl that are not covered by the above
+description.
+
+=head2 Last Resort
+
+C<$OVERLOAD{"nomethod"}> is a reference to a function of four parameters.
+If defined, it is called when the overloading mechanism cannot find a
+method for some operation. The first three arguments of this function
+coincide with arguments for the corresponding method if it were found, the
+fourth argument is the key of %OVERLOAD corresponding to the missing
+method. If several methods are tried, the last one is used. Say, C<1-$a>
+can be equivalent to
+
+ &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
+
+If some operation cannot be resolved, and there is no
+C<$OVERLOAD{"nomethod"}>, then an exception will be raised
+via die() -- unless C<$OVERLOAD{"fallback"}> is true.
+
+=head2 Fallback
+
+C<$OVERLOAD{"fallback"}> governs what to do if a method for a particular
+operation is not found. Three different cases are possible depending on
+value of C<$OVERLOAD{"fallback"}>:
+
+=over 16
+
+=item * C<undef>
+
+Perl tries to use a
+substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it
+then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception
+will be raised.
+
+=item * TRUE
+
+The same as for the C<undef> value, but no exception is raised. Instead,
+it silently reverts to what it would have done were there no %OVERLOAD is
+present.
+
+=item * defined, but FALSE
+
+No autogeneration is tried. Perl tries to call
+C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception.
+
+=back
+
+=head2 Copy Constructor
+
+C<$OVERLOAD{"="}> is a reference to a function with three arguments,
+i.e., it looks like a usual value of %OVERLOAD. What is special about
+this subroutine is that it should not return a blessed reference into
+a package (as most other methods are expected to), but rather a freshly made
+copy of its dereferenced argument (see L<"BUGS">, though). This operation
+is called in the situations when a mutator is applied to a reference
+that shares its object with some other reference, such as
+
+ $a=$b;
+ $a++;
+
+To make this change to $a and not to change $b, a freshly made copy of
+C<$$a> is made, and $a is assigned a reference to this object. This
+operation is executed during C<$a++>, (so before this C<$$a> coincides
+with C<$$b>), and only if C<++> is expressed via C<$OPERATOR{'++'}> or
+C<$OPERATOR{'+='}>. Note that if this operation is expressed via 'C<+>',
+i.e., as
+
+ $a=$b;
+ $a=$a+1;
+
+then C<$$a> and C<$$b> do not appear as lvalues.
+
+If the copy constructor is required during execution of some mutator, but
+C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
+copy if an object of
+the package is a plain scalar.
+
+=head1 MAGIC AUTOGENERATION
+
+If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
+TRUE or undefined, Perl tries to to autogenerate a substitute method for
+the missing operation based on defined operations. Autogenerated method
+substitutions are possible for the following operations:
+
+=over 16
+
+=item I<Assignment forms of arithmetic operations>
+
+C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
+is not defined.
+
+=item I<Conversion operations>
+
+String, numeric, and boolean conversion are calculated in terms of one
+another if not all of them are defined.
+
+=item I<Increment and decrement>
+
+The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
+and C<$a--> in terms of C<$a-=1> and C<$a-1>.
+
+=item C<abs($a)>
+
+can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
+
+=item I<Unary minus>
+
+can be expressed in terms of subtraction.
+
+=item I<Concatenation>
+
+can be expressed in terms of string conversion.
+
+=item I<Comparison operations>
+
+can be expressed in terms of its "spaceship" counterpart: either
+C<E<lt>=E<gt>> or C<cmp>:
+
+ <, >, <=, >=, ==, != in terms of <=>
+ lt, gt, le, ge, eq, ne in terms of cmp
+
+=item I<Copy operator>
+
+can be expressed in terms of assignment to the dereferenced value, if this
+value is scalar but not a reference.
+
+=back
+
+=head1 WARNING
+
+The restriction for the comparison operation is that even if, for example,
+`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
+function will produce only a standard logical value based on the
+numerical value of the result of `C<cmp>'. In particular, a working
+numeric conversion is needed in this case (possibly expressed in terms of
+other conversions).
+
+Similarly, C<.=> and C<x=> operators lose their mathemagical properties
+if the string conversion substitution is applied.
+
+When you chop() a mathemagical object, it becomes promoted to a string
+first, and its mathemagical qualities is lost. The same can happen with other
+operations as well.
+
+=head1 IMPLEMENTATION
+
+The table of methods for all operations is cached as a magic for the
+symbol table hash of the package. It is rechecked for changes of
+%OVERLOAD and @ISA only during C<bless>ing; so if it is changed
+dynamically, you'll need an additional fake C<bless>ing to update the
+table.
+
+(Every SVish thing has a magic queue, and a magic is an entry in that queue.
+This is how a single variable may participate in multiple forms of magic
+simultaneously. For instance, environment variables regularly have two
+forms at once: their %ENV magic and their taint magic.)
+
+If an object belongs to a package with %OVERLOAD, it carries a special
+flag. Thus the only speed penalty during arithmetic operations without
+overload is the check of this flag.
+
+In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
+overloadable operations, so most programs should not suffer measurable
+performance penalties. Considerable effort was made minimize overhead
+when %OVERLOAD is accessed and the current operation is overloadable but
+the arguments in question do not belong to packages with %OVERLOAD. When
+in doubt, test your speed with %OVERLOAD and without it. So far there
+have been no reports of substantial speed degradation if Perl is compiled
+with optimization turned on.
+
+There is no size penalty for data if there is no %OVERLOAD.
+
+The copying like C<$a=$b> is shallow; however, a one-level-deep
+copying is
+carried out before any operation that can imply an assignment to the
+object $b (or $a) refers to, like C<$b++>. You can override this
+behavior by defining your copy constructor (see L<"Copy Constructor">).
+
+It is expected that arguments to methods that are not explicitly supposed
+to be changed are constant (but this is not enforced).
+
+=head1 AUTHOR
+
+Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
+
+=head1 DIAGNOSTICS
+
+When Perl is run with the B<-Do> switch or its equivalent, overloading
+induces diagnostic messages.
+
+=head1 BUGS
+
+Because it's used for overloading, the per-package associative array
+%OVERLOAD now has a special meaning in Perl.
+
+Although the copy constructor is specially designed to make overloading
+operations with references to an array simpler, as it now works it's
+useless for this because a subroutine cannot return an array in the same
+way as it returns a scalar (from the point of view of Perl
+internals). Expect a change of interface for the copy constructor.
+
+As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for
+this is available from the author.
+
+This document is confusing.
diff --git a/pod/perlpod.pod b/pod/perlpod.pod
new file mode 100644
index 0000000000..46693f1793
--- /dev/null
+++ b/pod/perlpod.pod
@@ -0,0 +1,81 @@
+=head1 NAME
+
+pod - plain old documentation
+
+=head1 DESCRIPTION
+
+A pod-to-whatever translator reads a pod file paragraph by paragraph,
+and translates it to the appropriate output format. There are
+three kinds of paragraphs:
+
+=over 4
+
+=item *
+
+A verbatim paragraph, distinguished by being indented (that is,
+it starts with space or tab). It should be reproduced exactly,
+with tabs assumed to be on 8-column boundaries. There are no
+special formatting escapes, so you can't italicize or anything
+like that. A \ means \, and nothing else.
+
+=item *
+
+A command. All command paragraphs start with "=", followed by an
+identifier, followed by arbitrary text that the command can
+use however it pleases. Currently recognized commands are
+
+ =head1 heading
+ =head2 heading
+ =item text
+ =over N
+ =back
+
+=item *
+
+An ordinary block of text. 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
+ L<name> A link (cross reference) to name
+ L<name> manpage
+ L<name/ident> item in manpage
+ L<name/"sec"> section in other manpage
+ L<"sec"> section in this manpage
+ (the quotes are optional)
+ F<file> Used for filenames
+ Z<> A zero-width character
+
+That's it. The intent is simplicity, not power. I wanted paragraphs
+to look like paragraphs (block format), so that they stand out
+visually, and so that I could run them through fmt easily to reformat
+them (that's F7 in my version of B<vi>). I wanted the translator (and not
+me) to worry about whether " or ' is a left quote or a right quote
+within filled text, and I wanted it to leave the quotes alone dammit in
+verbatim mode, so I could slurp in a working program, shift it over 4
+spaces, and have it print out, er, verbatim. And presumably in a
+constant width font.
+
+In particular, you can leave things like this verbatim in your text:
+
+ Perl
+ FILEHANDLE
+ $variable
+ function()
+ manpage(3r)
+
+Doubtless a few other commands or sequences will need to be added along
+the way, but I've gotten along surprisingly well with just these.
+
+Note that I'm not at all claiming this to be sufficient for producing a
+book. I'm just trying to make an idiot-proof common source for nroff,
+TeX, and other markup languages, as used for online documentation.
+Both B<pod2html> and B<pod2man> translators exist.
+
+=head1 Author
+
+Larry Wall
+
diff --git a/pod/perlre.pod b/pod/perlre.pod
new file mode 100644
index 0000000000..1324642f71
--- /dev/null
+++ b/pod/perlre.pod
@@ -0,0 +1,315 @@
+=head1 NAME
+
+perlre - Perl regular expressions
+
+=head1 DESCRIPTION
+
+For a description of how to use regular expressions in matching
+operations, see C<m//> and C<s///> in L<perlop>. The matching operations can
+have various modifiers, some of which relate to the interpretation of
+the regular expression inside. These are:
+
+ i Do case-insensitive pattern matching.
+ m Treat string as multiple lines.
+ s Treat string as single line.
+ x Use extended regular expressions.
+
+These are usually written as "the C</x> modifier", even though the delimiter
+in question might not actually be a slash. In fact, any of these
+modifiers may also be embedded within the regular expression itself using
+the new C<(?...)> construct. See below.
+
+The C</x> modifier itself needs a little more explanation. It tells the
+regular expression parser to ignore whitespace that is not backslashed
+or within a character class. You can use this to break up your regular
+expression into (slightly) more readable parts. Together with the
+capability of embedding comments described later, this goes a long
+way towards making Perl 5 a readable language. See the C comment
+deletion code in L<perlop>.
+
+=head2 Regular Expressions
+
+The patterns used in pattern matching are regular expressions such as
+those supplied in the Version 8 regexp routines. (In fact, the
+routines are derived (distantly) from Henry Spencer's freely
+redistributable reimplementation of the V8 routines.)
+See L<Version 8 Regular Expressions> for details.
+
+In particular the following metacharacters have their standard I<egrep>-ish
+meanings:
+
+ \ Quote the next metacharacter
+ ^ Match the beginning of the line
+ . Match any character (except newline)
+ $ Match the end of the line
+ | Alternation
+ () Grouping
+ [] Character class
+
+By default, the "^" character is guaranteed to match only at the
+beginning of the string, the "$" character only at the end (or before the
+newline at the end) and Perl does certain optimizations with the
+assumption that the string contains only one line. Embedded newlines
+will not be matched by "^" or "$". You may, however, wish to treat a
+string as a multi-line buffer, such that the "^" will match after any
+newline within the string, and "$" will match before any newline. At the
+cost of a little more overhead, you can do this by using the /m modifier
+on the pattern match operator. (Older programs did this by setting C<$*>,
+but this practice is deprecated in Perl 5.)
+
+To facilitate multi-line substitutions, the "." character never matches a
+newline unless you use the C</s> modifier, which tells Perl to pretend
+the string is a single line--even if it isn't. The C</s> modifier also
+overrides the setting of C<$*>, in case you have some (badly behaved) older
+code that sets it in another module.
+
+The following standard quantifiers are recognized:
+
+ * Match 0 or more times
+ + Match 1 or more times
+ ? Match 1 or 0 times
+ {n} Match exactly n times
+ {n,} Match at least n times
+ {n,m} Match at least n but not more than m times
+
+(If a curly bracket occurs in any other context, it is treated
+as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+"
+modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. There is no limit to the
+size of n or m, but large numbers will chew up more memory.
+
+By default, a quantified subpattern is "greedy", that is, it will match as
+many times as possible without causing the rest pattern not to match. The
+standard quantifiers are all "greedy", in that they match as many
+occurrences as possible (given a particular starting location) without
+causing the pattern to fail. If you want it to match the minimum number
+of times possible, follow the quantifier with a "?" after any of them.
+Note that the meanings don't change, just the "gravity":
+
+ *? Match 0 or more times
+ +? Match 1 or more times
+ ?? Match 0 or 1 time
+ {n}? Match exactly n times
+ {n,}? Match at least n times
+ {n,m}? Match at least n but not more than m times
+
+Since patterns are processed as double quoted strings, the following
+also work:
+
+ \t tab
+ \n newline
+ \r return
+ \f form feed
+ \v vertical tab, whatever that is
+ \a alarm (bell)
+ \e escape
+ \033 octal char
+ \x1b hex char
+ \c[ control char
+ \l lowercase next char
+ \u uppercase next char
+ \L lowercase till \E
+ \U uppercase till \E
+ \E end case modification
+ \Q quote regexp metacharacters till \E
+
+In addition, Perl defines the following:
+
+ \w Match a "word" character (alphanumeric plus "_")
+ \W Match a non-word character
+ \s Match a whitespace character
+ \S Match a non-whitespace character
+ \d Match a digit character
+ \D Match a non-digit character
+
+Note that C<\w> matches a single alphanumeric character, not a whole
+word. To match a word you'd need to say C<\w+>. You may use C<\w>, C<\W>, C<\s>,
+C<\S>, C<\d> and C<\D> within character classes (though not as either end of a
+range).
+
+Perl defines the following zero-width assertions:
+
+ \b Match a word boundary
+ \B Match a non-(word boundary)
+ \A Match only at beginning of string
+ \Z Match only at end of string
+ \G Match only where previous m//g left off
+
+A word boundary (C<\b>) is defined as a spot between two characters that
+has a C<\w> on one side of it and and a C<\W> on the other side of it (in
+either order), counting the imaginary characters off the beginning and
+end of the string as matching a C<\W>. (Within character classes C<\b>
+represents backspace rather than a word boundary.) The C<\A> and C<\Z> are
+just like "^" and "$" except that they won't match multiple times when the
+C</m> modifier is used, while "^" and "$" will match at every internal line
+boundary.
+
+When the bracketing construct C<( ... )> is used, \<digit> matches the
+digit'th substring. (Outside of the pattern, always use "$" instead of
+"\" in front of the digit. The scope of $<digit> (and C<$`>, C<$&>, and C<$')>
+extends to the end of the enclosing BLOCK or eval string, or to the
+next pattern match with subexpressions.
+If you want to
+use parentheses to delimit subpattern (e.g. a set of alternatives) without
+saving it as a subpattern, follow the ( with a ?.
+The \<digit> notation
+sometimes works outside the current pattern, but should not be relied
+upon.) You may have as many parentheses as you wish. If you have more
+than 9 substrings, the variables $10, $11, ... refer to the
+corresponding substring. Within the pattern, \10, \11, etc. refer back
+to substrings if there have been at least that many left parens before
+the backreference. Otherwise (for backward compatibilty) \10 is the
+same as \010, a backspace, and \11 the same as \011, a tab. And so
+on. (\1 through \9 are always backreferences.)
+
+C<$+> returns whatever the last bracket match matched. C<$&> returns the
+entire matched string. ($0 used to return the same thing, but not any
+more.) C<$`> returns everything before the matched string. C<$'> returns
+everything after the matched string. Examples:
+
+ s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
+
+ if (/Time: (..):(..):(..)/) {
+ $hours = $1;
+ $minutes = $2;
+ $seconds = $3;
+ }
+
+You will note that all backslashed metacharacters in Perl are
+alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression
+languages, there are no backslashed symbols that aren't alphanumeric.
+So anything that looks like \\, \(, \), \<, \>, \{, or \} is always
+interpreted as a literal character, not a metacharacter. This makes it
+simple to quote a string that you want to use for a pattern but that
+you are afraid might contain metacharacters. Simply quote all the
+non-alphanumeric characters:
+
+ $pattern =~ s/(\W)/\\$1/g;
+
+You can also use the built-in quotemeta() function to do this.
+An even easier way to quote metacharacters right in the match operator
+is to say
+
+ /$unquoted\Q$quoted\E$unquoted/
+
+Perl 5 defines a consistent extension syntax for regular expressions.
+The syntax is a pair of parens with a question mark as the first thing
+within the parens (this was a syntax error in Perl 4). The character
+after the question mark gives the function of the extension. Several
+extensions are already supported:
+
+=over 10
+
+=item (?#text)
+
+A comment. The text is ignored.
+
+=item (?:regexp)
+
+This groups things like "()" but doesn't make backrefences like "()" does. So
+
+ split(/\b(?:a|b|c)\b/)
+
+is like
+
+ split(/\b(a|b|c)\b/)
+
+but doesn't spit out extra fields.
+
+=item (?=regexp)
+
+A zero-width positive lookahead assertion. For example, C</\w+(?=\t)/>
+matches a word followed by a tab, without including the tab in C<$&>.
+
+=item (?!regexp)
+
+A zero-width negative lookahead assertion. For example C</foo(?!bar)/>
+matches any occurrence of "foo" that isn't followed by "bar". Note
+however that lookahead and lookbehind are NOT the same thing. You cannot
+use this for lookbehind: C</(?!foo)bar/> will not find an occurrence of
+"bar" that is preceded by something which is not "foo". That's because
+the C<(?!foo)> is just saying that the next thing cannot be "foo"--and
+it's not, it's a "bar", so "foobar" will match. You would have to do
+something like C</(?foo)...bar/> for that. We say "like" because there's
+the case of your "bar" not having three characters before it. You could
+cover that this way: C</(?:(?!foo)...|^..?)bar/>. Sometimes it's still
+easier just to say:
+
+ if (/foo/ && $` =~ /bar$/)
+
+
+=item (?imsx)
+
+One or more embedded pattern-match modifiers. This is particularly
+useful for patterns that are specified in a table somewhere, some of
+which want to be case sensitive, and some of which don't. The case
+insensitive ones merely need to include C<(?i)> at the front of the
+pattern. For example:
+
+ $pattern = "foobar";
+ if ( /$pattern/i )
+
+ # more flexible:
+
+ $pattern = "(?i)foobar";
+ if ( /$pattern/ )
+
+=back
+
+The specific choice of question mark for this and the new minimal
+matching construct was because 1) question mark is pretty rare in older
+regular expressions, and 2) whenever you see one, you should stop
+and "question" exactly what is going on. That's psychology...
+
+=head2 Version 8 Regular Expressions
+
+In case you're not familiar with the "regular" Version 8 regexp
+routines, here are the pattern-matching rules not described above.
+
+Any single character matches itself, unless it is a I<metacharacter>
+with a special meaning described here or above. You can cause
+characters which normally function as metacharacters to be interpreted
+literally by prefixing them with a "\" (e.g. "\." matches a ".", not any
+character; "\\" matches a "\"). A series of characters matches that
+series of characters in the target string, so the pattern C<blurfl>
+would match "blurfl" in the target string.
+
+You can specify a character class, by enclosing a list of characters
+in C<[]>, which will match any one of the characters in the list. If the
+first character after the "[" is "^", the class matches any character not
+in the list. Within a list, the "-" character is used to specify a
+range, so that C<a-z> represents all the characters between "a" and "z",
+inclusive.
+
+Characters may be specified using a metacharacter syntax much like that
+used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
+"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
+of octal digits, matches the character whose ASCII value is I<nnn>.
+Similarly, \xI<nn>, where I<nn> are hexidecimal digits, matches the
+character whose ASCII value is I<nn>. The expression \cI<x> matches the
+ASCII character control-I<x>. Finally, the "." metacharacter matches any
+character except "\n" (unless you use C</s>).
+
+You can specify a series of alternatives for a pattern using "|" to
+separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
+or "foe" in the target string (as would C<f(e|i|o)e>). Note that the
+first alternative includes everything from the last pattern delimiter
+("(", "[", or the beginning of the pattern) up to the first "|", and
+the last alternative contains everything from the last "|" to the next
+pattern delimiter. For this reason, it's common practice to include
+alternatives in parentheses, to minimize confusion about where they
+start and end. Note also that the pattern C<(fee|fie|foe)> differs
+from the pattern C<[fee|fie|foe]> in that the former matches "fee",
+"fie", or "foe" in the target string, while the latter matches
+anything matched by the classes C<[fee]>, C<[fie]>, or C<[foe]> (i.e.
+the class C<[feio]>).
+
+Within a pattern, you may designate subpatterns for later reference by
+enclosing them in parentheses, and you may refer back to the I<n>th
+subpattern later in the pattern using the metacharacter \I<n>.
+Subpatterns are numbered based on the left to right order of their
+opening parenthesis. Note that a backreference matches whatever
+actually matched the subpattern in the string being examined, not the
+rules for that subpattern. Therefore, C<([0|0x])\d*\s\1\d*> will
+match "0x1234 0x4321",but not "0x1234 01234", since subpattern 1
+actually matched "0x", even though the rule C<[0|0x]> could
+potentially match the leading 0 in the second number.
diff --git a/pod/perlref.pod b/pod/perlref.pod
new file mode 100644
index 0000000000..0ad25dfe66
--- /dev/null
+++ b/pod/perlref.pod
@@ -0,0 +1,332 @@
+=head1 NAME
+
+perlref - Perl references and nested data structures
+
+=head1 DESCRIPTION
+
+In Perl 4 it was difficult to represent complex data structures, because
+all references had to be symbolic, and even that was difficult to do when
+you wanted to refer to a variable rather than a symbol table entry. Perl
+5 not only makes it easier to use symbolic references to variables, but
+lets you have "hard" references to any piece of data. Any scalar may hold
+a hard reference. Since arrays and hashes contain scalars, you can now
+easily build arrays of arrays, arrays of hashes, hashes of arrays, arrays
+of hashes of functions, and so on.
+
+Hard references are smart--they keep track of reference counts for you,
+automatically freeing the thing referred to when its reference count
+goes to zero. If that thing happens to be an object, the object is
+destructed. See L<perlobj> for more about objects. (In a sense,
+everything in Perl is an object, but we usually reserve the word for
+references to objects that have been officially "blessed" into a class package.)
+
+A symbolic reference contains the name of a variable, just as a
+symbolic link in the filesystem merely contains the name of a file.
+The C<*glob> notation is a kind of symbolic reference. Hard references
+are more like hard links in the file system: merely another way
+at getting at the same underlying object, irrespective of its name.
+
+"Hard" references are easy to use in Perl. There is just one
+overriding principle: Perl does no implicit referencing or
+dereferencing. When a scalar is holding a reference, it always behaves
+as a scalar. It doesn't magically start being an array or a hash
+unless you tell it so explicitly by dereferencing it.
+
+References can be constructed several ways.
+
+=over 4
+
+=item 1.
+
+By using the backslash operator on a variable, subroutine, or value.
+(This works much like the & (address-of) operator works in C.) Note
+that this typically creates I<ANOTHER> reference to a variable, since
+there's already a reference to the variable in the symbol table. But
+the symbol table reference might go away, and you'll still have the
+reference that the backslash returned. Here are some examples:
+
+ $scalarref = \$foo;
+ $arrayref = \@ARGV;
+ $hashref = \%ENV;
+ $coderef = \&handler;
+
+=item 2.
+
+A reference to an anonymous array can be constructed using square
+brackets:
+
+ $arrayref = [1, 2, ['a', 'b', 'c']];
+
+Here we've constructed a reference to an anonymous array of three elements
+whose final element is itself reference to another anonymous array of three
+elements. (The multidimensional syntax described later can be used to
+access this. For example, after the above, $arrayref->[2][1] would have
+the value "b".)
+
+=item 3.
+
+A reference to an anonymous hash can be constructed using curly
+brackets:
+
+ $hashref = {
+ 'Adam' => 'Eve',
+ 'Clyde' => 'Bonnie',
+ };
+
+Anonymous hash and array constructors can be intermixed freely to
+produce as complicated a structure as you want. The multidimensional
+syntax described below works for these too. The values above are
+literals, but variables and expressions would work just as well, because
+assignment operators in Perl (even within local() or my()) are executable
+statements, not compile-time declarations.
+
+Because curly brackets (braces) are used for several other things
+including BLOCKs, you may occasionally have to disambiguate braces at the
+beginning of a statement by putting a C<+> or a C<return> in front so
+that Perl realizes the opening brace isn't starting a BLOCK. The economy and
+mnemonic value of using curlies is deemed worth this occasional extra
+hassle.
+
+For example, if you wanted a function to make a new hash and return a
+reference to it, you have these options:
+
+ sub hashem { { @_ } } # silently wrong
+ sub hashem { +{ @_ } } # ok
+ sub hashem { return { @_ } } # ok
+
+=item 4.
+
+A reference to an anonymous subroutine can be constructed by using
+C<sub> without a subname:
+
+ $coderef = sub { print "Boink!\n" };
+
+Note the presence of the semicolon. Except for the fact that the code
+inside isn't executed immediately, a C<sub {}> is not so much a
+declaration as it is an operator, like C<do{}> or C<eval{}>. (However, no
+matter how many times you execute that line (unless you're in an
+C<eval("...")>), C<$coderef> will still have a reference to the I<SAME>
+anonymous subroutine.)
+
+For those who worry about these things, the current implementation
+uses shallow binding of local() variables; my() variables are not
+accessible. This precludes true closures. However, you can work
+around this with a run-time (rather than a compile-time) eval():
+
+ {
+ my $x = time;
+ $coderef = eval "sub { \$x }";
+ }
+
+Normally--if you'd used just C<sub{}> or even C<eval{}>--your unew sub
+would only have been able to access the global $x. But because you've
+used a run-time eval(), this will not only generate a brand new subroutine
+reference each time called, it will all grant access to the my() variable
+lexically above it rather than the global one. The particular $x
+accessed will be different for each new sub you create. This mechanism
+yields deep binding of variables. (If you don't know what closures, deep
+binding, or shallow binding are, don't worry too much about it.)
+
+=item 5.
+
+References are often returned by special subroutines called constructors.
+Perl objects are just reference a special kind of object that happens to know
+which package it's associated with. Constructors are just special
+subroutines that know how to create that association. They do so by
+starting with an ordinary reference, and it remains an ordinary reference
+even while it's also being an object. Constructors are customarily
+named new(), but don't have to be:
+
+ $objref = new Doggie (Tail => 'short', Ears => 'long');
+
+=item 6.
+
+References of the appropriate type can spring into existence if you
+dereference them in a context that assumes they exist. Since we haven't
+talked about dereferencing yet, we can't show you any examples yet.
+
+=back
+
+That's it for creating references. By now you're probably dying to
+know how to use references to get back to your long-lost data. There
+are several basic methods.
+
+=over 4
+
+=item 1.
+
+Anywhere you'd put an identifier as part of a variable or subroutine
+name, you can replace the identifier with a simple scalar variable
+containing a reference of the correct type:
+
+ $bar = $$scalarref;
+ push(@$arrayref, $filename);
+ $$arrayref[0] = "January";
+ $$hashref{"KEY"} = "VALUE";
+ &$coderef(1,2,3);
+
+It's important to understand that we are specifically I<NOT> dereferencing
+C<$arrayref[0]> or C<$hashref{"KEY"}> there. The dereference of the
+scalar variable happens I<BEFORE> it does any key lookups. Anything more
+complicated than a simple scalar variable must use methods 2 or 3 below.
+However, a "simple scalar" includes an identifier that itself uses method
+1 recursively. Therefore, the following prints "howdy".
+
+ $refrefref = \\\"howdy";
+ print $$$$refrefref;
+
+=item 2.
+
+Anywhere you'd put an identifier as part of a variable or subroutine
+name, you can replace the identifier with a BLOCK returning a reference
+of the correct type. In other words, the previous examples could be
+written like this:
+
+ $bar = ${$scalarref};
+ push(@{$arrayref}, $filename);
+ ${$arrayref}[0] = "January";
+ ${$hashref}{"KEY"} = "VALUE";
+ &{$coderef}(1,2,3);
+
+Admittedly, it's a little silly to use the curlies in this case, but
+the BLOCK can contain any arbitrary expression, in particular,
+subscripted expressions:
+
+ &{ $dispatch{$index} }(1,2,3); # call correct routine
+
+Because of being able to omit the curlies for the simple case of C<$$x>,
+people often make the mistake of viewing the dereferencing symbols as
+proper operators, and wonder about their precedence. If they were,
+though, you could use parens instead of braces. That's not the case.
+Consider the difference below; case 0 is a short-hand version of case 1,
+I<NOT> case 2:
+
+ $$hashref{"KEY"} = "VALUE"; # CASE 0
+ ${$hashref}{"KEY"} = "VALUE"; # CASE 1
+ ${$hashref{"KEY"}} = "VALUE"; # CASE 2
+ ${$hashref->{"KEY"}} = "VALUE"; # CASE 3
+
+Case 2 is also deceptive in that you're accessing a variable
+called %hashref, not dereferencing through $hashref to the hash
+it's presumably referencing. That would be case 3.
+
+=item 3.
+
+The case of individual array elements arises often enough that it gets
+cumbersome to use method 2. As a form of syntactic sugar, the two
+lines like that above can be written:
+
+ $arrayref->[0] = "January";
+ $hashref->{"KEY} = "VALUE";
+
+The left side of the array can be any expression returning a reference,
+including a previous dereference. Note that C<$array[$x]> is I<NOT> the
+same thing as C<$array-E<gt>[$x]> here:
+
+ $array[$x]->{"foo"}->[0] = "January";
+
+This is one of the cases we mentioned earlier in which references could
+spring into existence when in an lvalue context. Before this
+statement, C<$array[$x]> may have been undefined. If so, it's
+automatically defined with a hash reference so that we can look up
+C<{"foo"}> in it. Likewise C<$array[$x]-E<gt>{"foo"}> will automatically get
+defined with an array reference so that we can look up C<[0]> in it.
+
+One more thing here. The arrow is optional I<BETWEEN> brackets
+subscripts, so you can shrink the above down to
+
+ $array[$x]{"foo"}[0] = "January";
+
+Which, in the degenerate case of using only ordinary arrays, gives you
+multidimensional arrays just like C's:
+
+ $score[$x][$y][$z] += 42;
+
+Well, okay, not entirely like C's arrays, actually. C doesn't know how
+to grow its arrays on demand. Perl does.
+
+=item 4.
+
+If a reference happens to be a reference to an object, then there are
+probably methods to access the things referred to, and you should probably
+stick to those methods unless you're in the class package that defines the
+object's methods. In other words, be nice, and don't violate the object's
+encapsulation without a very good reason. Perl does not enforce
+encapsulation. We are not totalitarians here. We do expect some basic
+civility though.
+
+=back
+
+The ref() operator may be used to determine what type of thing the
+reference is pointing to. See L<perlfunc>.
+
+The bless() operator may be used to associate a reference with a package
+functioning as an object class. See L<perlobj>.
+
+A type glob may be dereferenced the same way a reference can, since
+the dereference syntax always indicates the kind of reference desired.
+So C<${*foo}> and C<${\$foo}> both indicate the same scalar variable.
+
+Here's a trick for interpolating a subroutine call into a string:
+
+ print "My sub returned ${\mysub(1,2,3)}\n";
+
+The way it works is that when the C<${...}> is seen in the double-quoted
+string, it's evaluated as a block. The block executes the call to
+C<mysub(1,2,3)>, and then takes a reference to that. So the whole block
+returns a reference to a scalar, which is then dereferenced by C<${...}>
+and stuck into the double-quoted string.
+
+=head2 Symbolic references
+
+We said that references spring into existence as necessary if they are
+undefined, but we didn't say what happens if a value used as a
+reference is already defined, but I<ISN'T> a hard reference. If you
+use it as a reference in this case, it'll be treated as a symbolic
+reference. That is, the value of the scalar is taken to be the I<NAME>
+of a variable, rather than a direct link to a (possibly) anonymous
+value.
+
+People frequently expect it to work like this. So it does.
+
+ $name = "foo";
+ $$name = 1; # Sets $foo
+ ${$name} = 2; # Sets $foo
+ ${$name x 2} = 3; # Sets $foofoo
+ $name->[0] = 4; # Sets $foo[0]
+ @$name = (); # Clears @foo
+ &$name(); # Calls &foo() (as in Perl 4)
+ $pack = "THAT";
+ ${"${pack}::$name"} = 5; # Sets $THAT::foo without eval
+
+This is very powerful, and slightly dangerous, in that it's possible
+to intend (with the utmost sincerity) to use a hard reference, and
+accidentally use a symbolic reference instead. To protect against
+that, you can say
+
+ use strict 'refs';
+
+and then only hard references will be allowed for the rest of the enclosing
+block. An inner block may countermand that with
+
+ no strict 'refs';
+
+Only package variables are visible to symbolic references. Lexical
+variables (declared with my()) aren't in a symbol table, and thus are
+invisible to this mechanism. For example:
+
+ local($value) = 10;
+ $ref = \$value;
+ {
+ my $value = 20;
+ print $$ref;
+ }
+
+This will still print 10, not 20. Remember that local() affects package
+variables, which are all "global" to the package.
+
+=head2 Further Reading
+
+Besides the obvious documents, source code can be instructive.
+Some rather pathological examples of the use of references can be found
+in the F<t/op/ref.t> regression test in the Perl source directory.
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
new file mode 100644
index 0000000000..5179abccd4
--- /dev/null
+++ b/pod/perlrun.pod
@@ -0,0 +1,382 @@
+=head1 NAME
+
+perlrun - how to execute the Perl interpreter
+
+=head1 SYNOPSIS
+
+B<perl> [switches] filename args
+
+=head1 DESCRIPTION
+
+Upon startup, Perl looks for your script in one of the following
+places:
+
+=over 4
+
+=item 1.
+
+Specified line by line via B<-e> switches on the command line.
+
+=item 2.
+
+Contained in the file specified by the first filename on the command line.
+(Note that systems supporting the #! notation invoke interpreters this way.)
+
+=item 3.
+
+Passed in implicitly via standard input. This only works if there are
+no filename arguments--to pass arguments to a STDIN script you
+must explicitly specify a "-" for the script name.
+
+=back
+
+With methods 2 and 3, Perl starts parsing the input file from the
+beginning, unless you've specified a B<-x> switch, in which case it
+scans for the first line starting with #! and containing the word
+"perl", and starts there instead. This is useful for running a script
+embedded in a larger message. (In this case you would indicate the end
+of the script using the __END__ token.)
+
+As of Perl 5, the #! line is always examined for switches as the line is
+being parsed. Thus, if you're on a machine that only allows one argument
+with the #! line, or worse, doesn't even recognize the #! line, you still
+can get consistent switch behavior regardless of how Perl was invoked,
+even if B<-x> was used to find the beginning of the script.
+
+Because many operating systems silently chop off kernel interpretation of
+the #! line after 32 characters, some switches may be passed in on the
+command line, and some may not; you could even get a "-" without its
+letter, if you're not careful. You probably want to make sure that all
+your switches fall either before or after that 32 character boundary.
+Most switches don't actually care if they're processed redundantly, but
+getting a - instead of a complete switch could cause Perl to try to
+execute standard input instead of your script. And a partial B<-I> switch
+could also cause odd results.
+
+Parsing of the #! switches starts wherever "perl" is mentioned in the line.
+The sequences "-*" and "- " are specifically ignored so that you could,
+if you were so inclined, say
+
+ #!/bin/sh -- # -*- perl -*- -p
+ eval 'exec perl $0 -S ${1+"$@"}'
+ if 0;
+
+to let Perl see the B<-p> switch.
+
+If the #! line does not contain the word "perl", the program named after
+the #! is executed instead of the Perl interpreter. This is slightly
+bizarre, but it helps people on machines that don't do #!, because they
+can tell a program that their SHELL is /usr/bin/perl, and Perl will then
+dispatch the program to the correct interpreter for them.
+
+After locating your script, Perl compiles the entire script to an
+internal form. If there are any compilation errors, execution of the
+script is not attempted. (This is unlike the typical shell script,
+which might run partway through before finding a syntax error.)
+
+If the script is syntactically correct, it is executed. If the script
+runs off the end without hitting an exit() or die() operator, an implicit
+C<exit(0)> is provided to indicate successful completion.
+
+=head2 Switches
+
+A single-character switch may be combined with the following switch, if
+any.
+
+ #!/usr/bin/perl -spi.bak # same as -s -p -i.bak
+
+Switches include:
+
+=over 5
+
+=item B<-0>I<digits>
+
+specifies the record separator (C<$/>) as an octal number. If there are
+no digits, the null character is the separator. Other switches may
+precede or follow the digits. For example, if you have a version of
+B<find> which can print filenames terminated by the null character, you
+can say this:
+
+ find . -name '*.bak' -print0 | perl -n0e unlink
+
+The special value 00 will cause Perl to slurp files in paragraph mode.
+The value 0777 will cause Perl to slurp files whole since there is no
+legal character with that value.
+
+=item B<-a>
+
+turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
+split command to the @F array is done as the first thing inside the
+implicit while loop produced by the B<-n> or B<-p>.
+
+ perl -ane 'print pop(@F), "\n";'
+
+is equivalent to
+
+ while (<>) {
+ @F = split(' ');
+ print pop(@F), "\n";
+ }
+
+An alternate delimiter may be specified using B<-F>.
+
+=item B<-c>
+
+causes Perl to check the syntax of the script and then exit without
+executing it.
+
+=item B<-d>
+
+runs the script under the Perl debugger. See L<perldebug>.
+
+=item B<-D>I<number>
+
+=item B<-D>I<list>
+
+sets debugging flags. To watch how it executes your script, use
+B<-D14>. (This only works if debugging is compiled into your
+Perl.) Another nice value is B<-D1024>, which lists your compiled
+syntax tree. And B<-D512> displays compiled regular expressions. As an
+alternative specify a list of letters instead of numbers (e.g. B<-D14> is
+equivalent to B<-Dtls>):
+
+ 1 p Tokenizing and Parsing
+ 2 s Stack Snapshots
+ 4 l Label Stack Processing
+ 8 t Trace Execution
+ 16 o Operator Node Construction
+ 32 c String/Numeric Conversions
+ 64 P Print Preprocessor Command for -P
+ 128 m Memory Allocation
+ 256 f Format Processing
+ 512 r Regular Expression Parsing
+ 1024 x Syntax Tree Dump
+ 2048 u Tainting Checks
+ 4096 L Memory Leaks (not supported anymore)
+ 8192 H Hash Dump -- usurps values()
+ 16384 X Scratchpad Allocation
+ 32768 D Cleaning Up
+
+=item B<-e> I<commandline>
+
+may be used to enter one line of script.
+If B<-e> is given, Perl
+will not look for a script filename in the argument list.
+Multiple B<-e> commands may
+be given to build up a multi-line script.
+Make sure to use semicolons where you would in a normal program.
+
+=item B<-F>I<regexp>
+
+specifies a regular expression to split on if B<-a> is also in effect.
+If regexp has C<//> around it, the slashes will be ignored.
+
+=item B<-i>I<extension>
+
+specifies that files processed by the C<E<lt>E<gt>> construct are to be edited
+in-place. It does this by renaming the input file, opening the output
+file by the original name, and selecting that output file as the default
+for print() statements. The extension, if supplied, is added to the name
+of the old file to make a backup copy. If no extension is supplied, no
+backup is made. From the shell, saying
+
+ $ perl -p -i.bak -e "s/foo/bar/; ... "
+
+is the same as using the script:
+
+ #!/usr/bin/perl -pi.bak
+ s/foo/bar/;
+
+which is equivalent to
+
+ #!/usr/bin/perl
+ while (<>) {
+ if ($ARGV ne $oldargv) {
+ rename($ARGV, $ARGV . '.bak');
+ open(ARGVOUT, ">$ARGV");
+ select(ARGVOUT);
+ $oldargv = $ARGV;
+ }
+ s/foo/bar/;
+ }
+ continue {
+ print; # this prints to original filename
+ }
+ select(STDOUT);
+
+except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
+know when the filename has changed. It does, however, use ARGVOUT for
+the selected filehandle. Note that STDOUT is restored as the
+default output filehandle after the loop.
+
+You can use C<eof> without parenthesis to locate the end of each input file,
+in case you want to append to each file, or reset line numbering (see
+example in L<perlfunc/eof>).
+
+=item B<-I>I<directory>
+
+may be used in conjunction with B<-P> to tell the C preprocessor where
+to look for include files. By default /usr/include and /usr/lib/perl
+are searched.
+
+=item B<-l>I<octnum>
+
+enables automatic line-ending processing. It has two effects: first,
+it automatically chomps the line terminator when used with B<-n> or
+B<-p>, and second, it assigns "C<$\>" to have the value of I<octnum> so that
+any print statements will have that line terminator added back on. If
+I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>". For
+instance, to trim lines to 80 columns:
+
+ perl -lpe 'substr($_, 80) = ""'
+
+Note that the assignment C<$\ = $/> is done when the switch is processed,
+so the input record separator can be different than the output record
+separator if the B<-l> switch is followed by a B<-0> switch:
+
+ gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
+
+This sets $\ to newline and then sets $/ to the null character.
+
+=item B<-n>
+
+causes Perl to assume the following loop around your script, which
+makes it iterate over filename arguments somewhat like B<sed -n> or
+B<awk>:
+
+ while (<>) {
+ ... # your script goes here
+ }
+
+Note that the lines are not printed by default. See B<-p> to have
+lines printed. Here is an efficient way to delete all files older than
+a week:
+
+ find . -mtime +7 -print | perl -nle 'unlink;'
+
+This is faster than using the C<-exec> switch of B<find> because you don't
+have to start a process on every filename found.
+
+C<BEGIN> and C<END> blocks may be used to capture control before or after
+the implicit loop, just as in B<awk>.
+
+=item B<-p>
+
+causes Perl to assume the following loop around your script, which
+makes it iterate over filename arguments somewhat like B<sed>:
+
+
+ while (<>) {
+ ... # your script goes here
+ } continue {
+ print;
+ }
+
+Note that the lines are printed automatically. To suppress printing
+use the B<-n> switch. A B<-p> overrides a B<-n> switch.
+
+C<BEGIN> and C<END> blocks may be used to capture control before or after
+the implicit loop, just as in awk.
+
+=item B<-P>
+
+causes your script to be run through the C preprocessor before
+compilation by Perl. (Since both comments and cpp directives begin
+with the # character, you should avoid starting comments with any words
+recognized by the C preprocessor such as "if", "else" or "define".)
+
+=item B<-s>
+
+enables some rudimentary switch parsing for switches on the command
+line after the script name but before any filename arguments (or before
+a B<-->). Any switch found there is removed from @ARGV and sets the
+corresponding variable in the Perl script. The following script
+prints "true" if and only if the script is invoked with a B<-xyz> switch.
+
+ #!/usr/bin/perl -s
+ if ($xyz) { print "true\n"; }
+
+=item B<-S>
+
+makes Perl use the PATH environment variable to search for the
+script (unless the name of the script starts with a slash). Typically
+this is used to emulate #! startup on machines that don't support #!,
+in the following manner:
+
+ #!/usr/bin/perl
+ eval "exec /usr/bin/perl -S $0 $*"
+ if $running_under_some_shell;
+
+The system ignores the first line and feeds the script to /bin/sh,
+which proceeds to try to execute the Perl script as a shell script.
+The shell executes the second line as a normal shell command, and thus
+starts up the Perl interpreter. On some systems $0 doesn't always
+contain the full pathname, so the B<-S> tells Perl to search for the
+script if necessary. After Perl locates the script, it parses the
+lines and ignores them because the variable $running_under_some_shell
+is never true. A better construct than C<$*> would be C<${1+"$@"}>, which
+handles embedded spaces and such in the filenames, but doesn't work if
+the script is being interpreted by csh. In order to start up sh rather
+than csh, some systems may have to replace the #! line with a line
+containing just a colon, which will be politely ignored by Perl. Other
+systems can't control that, and need a totally devious construct that
+will work under any of csh, sh or Perl, such as the following:
+
+ eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
+ & eval 'exec /usr/bin/perl -S $0 $argv:q'
+ if 0;
+
+=item B<-T>
+
+forces "taint" checks to be turned on. Ordinarily these checks are
+done only when running setuid or setgid. See L<perlsec>.
+
+=item B<-u>
+
+causes Perl to dump core after compiling your script. You can then
+take this core dump and turn it into an executable file by using the
+B<undump> program (not supplied). This speeds startup at the expense of
+some disk space (which you can minimize by stripping the executable).
+(Still, a "hello world" executable comes out to about 200K on my
+machine.) If you want to execute a portion of your script before dumping,
+use the dump() operator instead. Note: availability of B<undump> is
+platform specific and may not be available for a specific port of
+Perl.
+
+=item B<-U>
+
+allows Perl to do unsafe operations. Currently the only "unsafe"
+operations are the unlinking of directories while running as superuser,
+and running setuid programs with fatal taint checks turned into
+warnings.
+
+=item B<-v>
+
+prints the version and patchlevel of your Perl executable.
+
+=item B<-w>
+
+prints warnings about identifiers that are mentioned only once, and
+scalar variables that are used before being set. Also warns about
+redefined subroutines, and references to undefined filehandles or
+filehandles opened readonly that you are attempting to write on. Also
+warns you if you use values as a number that doesn't look like numbers, using
+a an array as though it were a scalar, if
+your subroutines recurse more than 100 deep, and innumeriable other things.
+See L<perldiag> and L<perltrap>.
+
+=item B<-x> I<directory>
+
+tells Perl that the script is embedded in a message. Leading
+garbage will be discarded until the first line that starts with #! and
+contains the string "perl". Any meaningful switches on that line will
+be applied (but only one group of switches, as with normal #!
+processing). If a directory name is specified, Perl will switch to
+that directory before running the script. The B<-x> switch only
+controls the the disposal of leading garbage. The script must be
+terminated with C<__END__> if there is trailing garbage to be ignored (the
+script can process any or all of the trailing garbage via the DATA
+filehandle if desired).
+
+
+=back
diff --git a/pod/perlsec.pod b/pod/perlsec.pod
new file mode 100644
index 0000000000..0be4f52798
--- /dev/null
+++ b/pod/perlsec.pod
@@ -0,0 +1,125 @@
+=head1 NAME
+
+perlsec - Perl security
+
+=head1 DESCRIPTION
+
+Perl is designed to make it easy to write secure setuid and setgid
+scripts. Unlike shells, which are based on multiple substitution
+passes on each line of the script, Perl uses a more conventional
+evaluation scheme with fewer hidden "gotchas". Additionally, since the
+language has more built-in functionality, it has to rely less upon
+external (and possibly untrustworthy) programs to accomplish its
+purposes.
+
+Beyond the obvious problems that stem from giving special privileges to
+such flexible systems as scripts, on many operating systems, setuid
+scripts are inherently insecure right from the start. This is because
+that between the time that the kernel opens up the file to see what to
+run, and when the now setuid interpreter it ran turns around and reopens
+the file so it can interpret it, things may have changed, especially if
+you have symbolic links on your system.
+
+Fortunately, sometimes this kernel "feature" can be disabled.
+Unfortunately, there are two ways to disable it. The system can simply
+outlaw scripts with the setuid bit set, which doesn't help much.
+Alternately, it can simply ignore the setuid bit on scripts. If the
+latter is true, Perl can emulate the setuid and setgid mechanism when it
+notices the otherwise useless setuid/gid bits on Perl scripts. It does
+this via a special executable called B<suidperl> that is automatically
+invoked for you if it's needed.
+
+If, however, the kernel setuid script feature isn't disabled, Perl will
+complain loudly that your setuid script is insecure. You'll need to
+either disable the kernel setuid script feature, or put a C wrapper around
+the script. See the program B<wrapsuid> in the F<eg> directory of your
+Perl distribution for how to go about doing this.
+
+There are some systems on which setuid scripts are free of this inherent
+security bug. For example, recent releases of Solaris are like this. On
+such systems, when the kernel passes the name of the setuid script to open
+to the interpreter, rather than using a pathname subject to mettling, it
+instead passes /dev/fd/3. This is a special file already opened on the
+script, so that there can be no race condition for evil scripts to
+exploit. On these systems, Perl should be compiled with
+C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure> program that builds
+Perl tries to figure this out for itself.
+
+When Perl is executing a setuid script, it takes special precautions to
+prevent you from falling into any obvious traps. (In some ways, a Perl
+script is more secure than the corresponding C program.) Any command line
+argument, environment variable, or input is marked as "tainted", and may
+not be used, directly or indirectly, in any command that invokes a
+subshell, or in any command that modifies files, directories, or
+processes. Any variable that is set within an expression that has
+previously referenced a tainted value also becomes tainted (even if it is
+logically impossible for the tainted value to influence the variable).
+For example:
+
+ $foo = shift; # $foo is tainted
+ $bar = $foo,'bar'; # $bar is also tainted
+ $xxx = <>; # Tainted
+ $path = $ENV{'PATH'}; # Tainted, but see below
+ $abc = 'abc'; # Not tainted
+
+ system "echo $foo"; # Insecure
+ system "/bin/echo", $foo; # Secure (doesn't use sh)
+ system "echo $bar"; # Insecure
+ system "echo $abc"; # Insecure until PATH set
+
+ $ENV{'PATH'} = '/bin:/usr/bin';
+ $ENV{'IFS'} = '' if $ENV{'IFS'} ne '';
+
+ $path = $ENV{'PATH'}; # Not tainted
+ system "echo $abc"; # Is secure now!
+
+ open(FOO,"$foo"); # OK
+ open(FOO,">$foo"); # Not OK
+
+ open(FOO,"echo $foo|"); # Not OK, but...
+ open(FOO,"-|") || exec 'echo', $foo; # OK
+
+ $zzz = `echo $foo`; # Insecure, zzz tainted
+
+ unlink $abc,$foo; # Insecure
+ umask $foo; # Insecure
+
+ exec "echo $foo"; # Insecure
+ exec "echo", $foo; # Secure (doesn't use sh)
+ exec "sh", '-c', $foo; # Considered secure, alas
+
+The taintedness is associated with each scalar value, so some elements
+of an array can be tainted, and others not.
+
+If you try to do something insecure, you will get a fatal error saying
+something like "Insecure dependency" or "Insecure PATH". Note that you
+can still write an insecure system call or exec, but only by explicitly
+doing something like the last example above. You can also bypass the
+tainting mechanism by referencing subpatterns--Perl presumes that if
+you reference a substring using $1, $2, etc, you knew what you were
+doing when you wrote the pattern:
+
+ $ARGV[0] =~ /^-P(\w+)$/;
+ $printer = $1; # Not tainted
+
+This is fairly secure since C<\w+> doesn't match shell metacharacters.
+Use of C</.+/> would have been insecure, but Perl doesn't check for that,
+so you must be careful with your patterns. This is the I<ONLY> mechanism
+for untainting user supplied filenames if you want to do file operations
+on them (unless you make C<$E<gt>> equal to C<$E<lt>> ).
+
+For "Insecure PATH" messages, you need to set C<$ENV{'PATH}'> to a known
+value, and each directory in the path must be non-writable by the world.
+A frequently voiced gripe is that you can get this message even
+if the pathname to an executable is fully qualified. But Perl can't
+know that the executable in question isn't going to execute some other
+program depending on the PATH.
+
+It's also possible to get into trouble with other operations that don't
+care whether they use tainted values. Make judicious use of the file
+tests in dealing with any user-supplied filenames. When possible, do
+opens and such after setting C<$E<gt> = $E<lt>>. (Remember group IDs,
+too!) Perl doesn't prevent you from opening tainted filenames for reading,
+so be careful what you print out. The tainting mechanism is intended to
+prevent stupid mistakes, not to remove the need for thought.
+
diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod
new file mode 100644
index 0000000000..43d53554f9
--- /dev/null
+++ b/pod/perlstyle.pod
@@ -0,0 +1,225 @@
+=head1 NAME
+
+perlstyle - Perl style guide
+
+=head1 DESCRIPTION
+
+=head2 Style
+
+Each programmer will, of course, have his or her own preferences in
+regards to formatting, but there are some general guidelines that will
+make your programs easier to read, understand, and maintain.
+
+Regarding aesthetics of code lay out, about the only thing Larry
+cares strongly about is that the closing curly brace of
+a multi-line BLOCK should line up with the keyword that started the construct.
+Beyond that, he has other preferences that aren't so strong:
+
+=over 4
+
+=item *
+
+4-column indent.
+
+=item *
+
+Opening curly on same line as keyword, if possible, otherwise line up.
+
+=item *
+
+Space before the opening curly of a multiline BLOCK.
+
+=item *
+
+One-line BLOCK may be put on one line, including curlies.
+
+=item *
+
+No space before the semicolon.
+
+=item *
+
+Semicolon omitted in "short" one-line BLOCK.
+
+=item *
+
+Space around most operators.
+
+=item *
+
+Space around a "complex" subscript (inside brackets).
+
+=item *
+
+Blank lines between chunks that do different things.
+
+=item *
+
+Uncuddled elses.
+
+=item *
+
+No space between function name and its opening paren.
+
+=item *
+
+Space after each comma.
+
+=item *
+
+Long lines broken after an operator (except "and" and "or").
+
+=item *
+
+Space after last paren matching on current line.
+
+=item *
+
+Line up corresponding items vertically.
+
+=item *
+
+Omit redundant punctuation as long as clarity doesn't suffer.
+
+=back
+
+Larry has his reasons for each of these things, but he doen't claim that
+everyone else's mind works the same as his does.
+
+Here are some other more substantive style issues to think about:
+
+=over 4
+
+=item *
+
+Just because you I<CAN> do something a particular way doesn't mean that
+you I<SHOULD> do it that way. Perl is designed to give you several
+ways to do anything, so consider picking the most readable one. For
+instance
+
+ open(FOO,$foo) || die "Can't open $foo: $!";
+
+is better than
+
+ die "Can't open $foo: $!" unless open(FOO,$foo);
+
+because the second way hides the main point of the statement in a
+modifier. On the other hand
+
+ print "Starting analysis\n" if $verbose;
+
+is better than
+
+ $verbose && print "Starting analysis\n";
+
+since the main point isn't whether the user typed B<-v> or not.
+
+Similarly, just because an operator lets you assume default arguments
+doesn't mean that you have to make use of the defaults. The defaults
+are there for lazy systems programmers writing one-shot programs. If
+you want your program to be readable, consider supplying the argument.
+
+Along the same lines, just because you I<CAN> omit parentheses in many
+places doesn't mean that you ought to:
+
+ return print reverse sort num values %array;
+ return print(reverse(sort num (values(%array))));
+
+When in doubt, parenthesize. At the very least it will let some poor
+schmuck bounce on the % key in B<vi>.
+
+Even if you aren't in doubt, consider the mental welfare of the person
+who has to maintain the code after you, and who will probably put
+parens in the wrong place.
+
+=item *
+
+Don't go through silly contortions to exit a loop at the top or the
+bottom, when Perl provides the C<last> operator so you can exit in
+the middle. Just "outdent" it a little to make it more visible:
+
+ LINE:
+ for (;;) {
+ statements;
+ last LINE if $foo;
+ next LINE if /^#/;
+ statements;
+ }
+
+=item *
+
+Don't be afraid to use loop labels--they're there to enhance
+readability as well as to allow multi-level loop breaks. See the
+previous example.
+
+=item *
+
+For portability, when using features that may not be implemented on
+every machine, test the construct in an eval to see if it fails. If
+you know what version or patchlevel a particular feature was
+implemented, you can test C<$]> ($PERL_VERSION in C<English>) to see if it
+will be there. The C<Config> module will also let you interrogate values
+determined by the B<Configure> program when Perl was installed.
+
+=item *
+
+Choose mnemonic identifiers. If you can't remember what mnemonic means,
+you've got a problem.
+
+=item *
+
+If you have a really hairy regular expression, use the C</x> modifier and
+put in some whitespace to make it look a little less like line noise.
+Don't use slash as a delimiter when your regexp has slashes or backslashes.
+
+=item *
+
+Use the new "and" and "or" operators to avoid having to parenthesize
+list operators so much, and to reduce the incidence of punctuational
+operators like C<&&> and C<||>. Call your subroutines as if they were
+functions or list operators to avoid excessive ampersands and parens.
+
+=item *
+
+Use here documents instead of repeated print() statements.
+
+=item *
+
+Line up corresponding things vertically, especially if it'd be too long
+to fit on one line anyway.
+
+ $IDX = $ST_MTIME;
+ $IDX = $ST_ATIME if $opt_u;
+ $IDX = $ST_CTIME if $opt_c;
+ $IDX = $ST_SIZE if $opt_s;
+
+ mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
+ chdir($tmpdir) or die "can't chdir $tmpdir: $!";
+ mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
+
+=item *
+
+Line up your translations when it makes sense:
+
+ tr [abc]
+ [xyz];
+
+=item *
+
+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
+your code. Consider changing your whole world view. Consider... oh,
+never mind.
+
+=item *
+
+Be consistent.
+
+=item *
+
+Be nice.
+
+=back
+
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
new file mode 100644
index 0000000000..cfc8b5611f
--- /dev/null
+++ b/pod/perlsub.pod
@@ -0,0 +1,195 @@
+=head1 NAME
+
+perlsub - Perl subroutines
+
+=head1 SYNOPSIS
+
+To declare subroutines:
+
+ sub NAME; # A "forward" declaration.
+ sub NAME BLOCK # A declaration and a definition.
+
+To import subroutines:
+
+ use PACKAGE qw(NAME1 NAME2 NAME3);
+
+To call subroutines:
+
+ &NAME # Passes current @_ to subroutine.
+ &NAME(LIST); # Parens required with & form.
+ NAME(LIST); # & is optional with parens.
+ NAME LIST; # Parens optional if predeclared/imported.
+
+=head1 DESCRIPTION
+
+Any arguments passed to the routine come in as array @_, that is
+($_[0], $_[1], ...). The array @_ is a local array, but its values are
+references to the actual scalar parameters. The return value of the
+subroutine is the value of the last expression evaluated, and can be
+either an array value or a scalar value. Alternately, a return
+statement may be used to specify the returned value and exit the
+subroutine. To create local variables see the local() and my()
+operators.
+
+A subroutine may called using the "&" prefix. The "&" is optional in Perl
+5, and so are the parens if the subroutine has been predeclared.
+(Note, however, that the "&" is I<NOT> optional when you're just naming the
+subroutine, such as when it's used as an argument to defined() or
+undef(). Nor is it optional when you want to do an indirect subroutine
+call with a subroutine name or reference using the C<&$subref()> or
+C<&{$subref}()> constructs. See L<perlref> for more on that.)
+
+Example:
+
+ sub MAX {
+ my $max = pop(@_);
+ foreach $foo (@_) {
+ $max = $foo if $max < $foo;
+ }
+ $max;
+ }
+
+ ...
+ $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
+
+Example:
+
+ # get a line, combining continuation lines
+ # that start with whitespace
+
+ sub get_line {
+ $thisline = $lookahead;
+ LINE: while ($lookahead = <STDIN>) {
+ if ($lookahead =~ /^[ \t]/) {
+ $thisline .= $lookahead;
+ }
+ else {
+ last LINE;
+ }
+ }
+ $thisline;
+ }
+
+ $lookahead = <STDIN>; # get first line
+ while ($_ = get_line()) {
+ ...
+ }
+
+Use array assignment to a local list to name your formal arguments:
+
+ sub maybeset {
+ my($key, $value) = @_;
+ $foo{$key} = $value unless $foo{$key};
+ }
+
+This also has the effect of turning call-by-reference into
+call-by-value, since the assignment copies the values.
+
+Subroutines may be called recursively. If a subroutine is called using
+the "&" form, the argument list is optional. If omitted, no @_ array is
+set up for the subroutine; the @_ array at the time of the call is
+visible to subroutine instead.
+
+ &foo(1,2,3); # pass three arguments
+ foo(1,2,3); # the same
+
+ foo(); # pass a null list
+ &foo(); # the same
+ &foo; # pass no arguments--more efficient
+
+=head2 Passing Symbol Table Entries
+
+[Note: The mechanism described in this section works fine in Perl 5, but
+the new reference mechanism is generally easier to work with. See L<perlref>.]
+
+Sometimes you don't want to pass the value of an array to a subroutine
+but rather the name of it, so that the subroutine can modify the global
+copy of it rather than working with a local copy. In perl you can
+refer to all the objects of a particular name by prefixing the name
+with a star: C<*foo>. This is often known as a "type glob", since the
+star on the front can be thought of as a wildcard match for all the
+funny prefix characters on variables and subroutines and such.
+
+When evaluated, the type glob produces a scalar value that represents
+all the objects of that name, including any filehandle, format or
+subroutine. When assigned to, it causes the name mentioned to refer to
+whatever "*" value was assigned to it. Example:
+
+ sub doubleary {
+ local(*someary) = @_;
+ foreach $elem (@someary) {
+ $elem *= 2;
+ }
+ }
+ doubleary(*foo);
+ doubleary(*bar);
+
+Note that scalars are already passed by reference, so you can modify
+scalar arguments without using this mechanism by referring explicitly
+to $_[0] etc. You can modify all the elements of an array by passing
+all the elements as scalars, but you have to use the * mechanism (or
+the equivalent reference mechanism) to push, pop or change the size of
+an array. It will certainly be faster to pass the typeglob (or reference).
+
+Even if you don't want to modify an array, this mechanism is useful for
+passing multiple arrays in a single LIST, since normally the LIST
+mechanism will merge all the array values so that you can't extract out
+the individual arrays.
+
+=head2 Overriding builtin functions
+
+Many builtin functions may be overridden, though this should only be
+tried occasionally and for good reason. Typically this might be
+done by a package attempting to emulate missing builtin functionality
+on a non-Unix system.
+
+Overriding may only be done by importing the name from a
+module--ordinary predeclaration isn't good enough. However, the
+C<subs> pragma (compiler directive) lets you, in effect, predeclare subs
+via the import syntax, and these names may then override the builtin ones:
+
+ use subs 'chdir', 'chroot', 'chmod', 'chown';
+ chdir $somewhere;
+ sub chdir { ... }
+
+Library modules should not in general export builtin names like "open"
+or "chdir" as part of their default @EXPORT list, since these may
+sneak into someone else's namespace and change the semantics unexpectedly.
+Instead, if the module adds the name to the @EXPORT_OK list, then it's
+possible for a user to import the name explicitly, but not implicitly.
+That is, they could say
+
+ use Module 'open';
+
+and it would import the open override, but if they said
+
+ use Module;
+
+they would get the default imports without the overrides.
+
+=head2 Autoloading
+
+If you call a subroutine that is undefined, you would ordinarily get an
+immediate fatal error complaining that the subroutine doesn't exist.
+(Likewise for subroutines being used as methods, when the method
+doesn't exist in any of the base classes of the class package.) If,
+however, there is an C<AUTOLOAD> subroutine defined in the package or
+packages that were searched for the original subroutine, then that
+C<AUTOLOAD> subroutine is called with the arguments that would have been
+passed to the original subroutine. The fully qualified name of the
+original subroutine magically appears in the $AUTOLOAD variable in the
+same package as the C<AUTOLOAD> routine. The name is not passed as an
+ordinary argument because, er, well, just because, that's why...
+
+Most C<AUTOLOAD> routines will load in a definition for the subroutine in
+question using eval, and then execute that subroutine using a special
+form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
+without a trace. (See the standard C<AutoLoader> module, for example.)
+But an C<AUTOLOAD> routine can also just emulate the routine and never
+define it. A good example of this is the standard Shell module, which
+can treat undefined subroutine calls as calls to Unix programs.
+
+There are mechanisms available for modules to help them split themselves
+up into autoloadable files to be used with the standard AutoLoader module.
+See the document on extensions.
+
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
new file mode 100644
index 0000000000..3ddb493c8b
--- /dev/null
+++ b/pod/perlsyn.pod
@@ -0,0 +1,267 @@
+=head1 NAME
+
+perlsyn - Perl syntax
+
+=head1 DESCRIPTION
+
+A Perl script consists of a sequence of declarations and statements.
+The only things that need to be declared in Perl are report formats
+and subroutines. See the sections below for more information on those
+declarations. All uninitialized user-created objects are assumed to
+start with a null or 0 value until they are defined by some explicit
+operation such as assignment. (Though you can get warnings about the
+use of undefined values if you like.) The sequence of statements is
+executed just once, unlike in B<sed> and B<awk> scripts, where the
+sequence of statements is executed for each input line. While this means
+that you must explicitly loop over the lines of your input file (or
+files), it also means you have much more control over which files and
+which lines you look at. (Actually, I'm lying--it is possible to do an
+implicit loop with either the B<-n> or B<-p> switch. It's just not the
+mandatory default like it is in B<sed> and B<awk>.)
+
+Perl is, for the most part, a free-form language. (The only
+exception to this is format declarations, for obvious reasons.) Comments
+are indicated by the "#" character, and extend to the end of the line. If
+you attempt to use C</* */> C-style comments, it will be interpreted
+either as division or pattern matching, depending on the context, and C++
+C<//> comments just look like a null regular expression, So don't do
+that.
+
+A declaration can be put anywhere a statement can, but has no effect on
+the execution of the primary sequence of statements--declarations all
+take effect at compile time. Typically all the declarations are put at
+the beginning or the end of the script.
+
+As of Perl 5, declaring a subroutine allows a subroutine name to be used
+as if it were a list operator from that point forward in the program. You
+can declare a subroutine without defining it by saying just
+
+ sub myname;
+ $me = myname $0 or die "can't get myname";
+
+Note that it functions as a list operator though, not a unary
+operator, so be careful to use C<or> instead of C<||> there.
+
+Subroutines declarations can also be imported by a C<use> statement.
+
+Also as of Perl 5, a statement sequence may contain declarations of
+lexically scoped variables, but apart from declaring a variable name,
+the declaration acts like an ordinary statement, and is elaborated within
+the sequence of statements as if it were an ordinary statement.
+
+=head2 Simple statements
+
+The only kind of simple statement is an expression evaluated for its
+side effects. Every simple statement must be terminated with a
+semicolon, unless it is the final statement in a block, in which case
+the semicolon is optional. (A semicolon is still encouraged there if the
+block takes up more than one line, since you may add another line.)
+Note that there are some operators like C<eval {}> and C<do {}> that look
+like compound statements, but aren't (they're just TERMs in an expression),
+and thus need an explicit termination
+if used as the last item in a statement.
+
+Any simple statement may optionally be followed by a I<SINGLE> modifier,
+just before the terminating semicolon (or block ending). The possible
+modifiers are:
+
+ if EXPR
+ unless EXPR
+ while EXPR
+ until EXPR
+
+The C<if> and C<unless> modifiers have the expected semantics,
+presuming you're a speaker of English. The C<while> and C<until>
+modifiers also have the usual "while loop" semantics (conditional
+evaluated first), except when applied to a do-BLOCK (or to the
+now-deprecated do-SUBROUTINE statement), in which case the block
+executes once before the conditional is evaluated. This is so that you
+can write loops like:
+
+ do {
+ $_ = <STDIN>;
+ ...
+ } until $_ eq ".\n";
+
+See L<perlfunc/do>. Note also that the loop control
+statements described later will I<NOT> work in this construct, since
+modifiers don't take loop labels. Sorry. You can always wrap
+another block around it to do that sort of thing.)
+
+=head2 Compound statements
+
+In Perl, a sequence of statements that defines a scope is called a block.
+Sometimes a block is delimited by the file containing it (in the case
+of a required file, or the program as a whole), and sometimes a block
+is delimited by the extent of a string (in the case of an eval).
+
+But generally, a block is delimited by curly brackets, also known as braces.
+We will call this syntactic construct a BLOCK.
+
+The following compound statements may be used to control flow:
+
+ if (EXPR) BLOCK
+ if (EXPR) BLOCK else BLOCK
+ if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+ LABEL while (EXPR) BLOCK
+ LABEL while (EXPR) BLOCK continue BLOCK
+ LABEL for (EXPR; EXPR; EXPR) BLOCK
+ LABEL foreach VAR (ARRAY) BLOCK
+ LABEL BLOCK continue BLOCK
+
+Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
+not statements. This means that the curly brackets are I<required>--no
+dangling statements allowed. If you want to write conditionals without
+curly brackets there are several other ways to do it. The following
+all do the same thing:
+
+ if (!open(FOO)) { die "Can't open $FOO: $!"; }
+ die "Can't open $FOO: $!" unless open(FOO);
+ open(FOO) or die "Can't open $FOO: $!"; # FOO or bust!
+ open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
+ # a bit exotic, that last one
+
+The C<if> statement is straightforward. Since BLOCKs are always
+bounded by curly brackets, there is never any ambiguity about which
+C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
+the sense of the test is reversed.
+
+The C<while> statement executes the block as long as the expression is
+true (does not evaluate to the null string or 0 or "0"). The LABEL is
+optional, and if present, consists of an identifier followed by a
+colon. The LABEL identifies the loop for the loop control statements
+C<next>, C<last>, and C<redo> (see below). If there is a C<continue>
+BLOCK, it is always executed just before the conditional is about to be
+evaluated again, just like the third part of a C<for> loop in C.
+Thus it can be used to increment a loop variable, even when the loop
+has been continued via the C<next> statement (which is similar to the C
+C<continue> statement).
+
+If the word C<while> is replaced by the word C<until>, the sense of the
+test is reversed, but the conditional is still tested before the first
+iteration.
+
+In either the C<if> or the C<while> statement, you may replace "(EXPR)"
+with a BLOCK, and the conditional is true if the value of the last
+statement in that block is true. (This feature continues to work in Perl
+5 but is deprecated. Please change any occurrences of "if BLOCK" to
+"if (do BLOCK)".)
+
+The C-style C<for> loop works exactly like the corresponding C<while> loop:
+
+ for ($i = 1; $i < 10; $i++) {
+ ...
+ }
+
+is the same as
+
+ $i = 1;
+ while ($i < 10) {
+ ...
+ } continue {
+ $i++;
+ }
+
+The foreach loop iterates over a normal list value and sets the
+variable VAR to be each element of the list in turn. The variable is
+implicitly local to the loop (unless declared previously with C<my>),
+and regains its former value upon exiting the loop. The C<foreach>
+keyword is actually a synonym for the C<for> keyword, so you can use
+C<foreach> for readability or C<for> for brevity. If VAR is omitted, $_
+is set to each value. If ARRAY is an actual array (as opposed to an
+expression returning a list value), you can modify each element of the
+array by modifying VAR inside the loop. Examples:
+
+ for (@ary) { s/foo/bar/; }
+
+ foreach $elem (@elements) {
+ $elem *= 2;
+ }
+
+ for ((10,9,8,7,6,5,4,3,2,1,'BOOM')) {
+ print $_, "\n"; sleep(1);
+ }
+
+ for (1..15) { print "Merry Christmas\n"; }
+
+ foreach $item (split(/:[\\\n:]*/, $ENV{'TERMCAP'})) {
+ print "Item: $item\n";
+ }
+
+A BLOCK by itself (labeled or not) is semantically equivalent to a loop
+that executes once. Thus you can use any of the loop control
+statements in it to leave or restart the block. The C<continue> block
+is optional. This construct is particularly nice for doing case
+structures.
+
+ SWITCH: {
+ if (/^abc/) { $abc = 1; last SWITCH; }
+ if (/^def/) { $def = 1; last SWITCH; }
+ if (/^xyz/) { $xyz = 1; last SWITCH; }
+ $nothing = 1;
+ }
+
+There is no official switch statement in Perl, because there are
+already several ways to write the equivalent. In addition to the
+above, you could write
+
+ SWITCH: {
+ $abc = 1, last SWITCH if /^abc/;
+ $def = 1, last SWITCH if /^def/;
+ $xyz = 1, last SWITCH if /^xyz/;
+ $nothing = 1;
+ }
+
+(That's actually not as strange as it looks one you realize that you can
+use loop control "operators" within an expression, That's just the normal
+C comma operator.)
+
+or
+
+ SWITCH: {
+ /^abc/ && do { $abc = 1; last SWITCH; };
+ /^def/ && do { $def = 1; last SWITCH; };
+ /^xyz/ && do { $xyz = 1; last SWITCH; };
+ $nothing = 1;
+ }
+
+or formatted so it stands out more as a "proper" switch statement:
+
+ SWITCH: {
+ /^abc/ && do {
+ $abc = 1;
+ last SWITCH;
+ };
+
+ /^def/ && do {
+ $def = 1;
+ last SWITCH;
+ };
+
+ /^xyz/ && do {
+ $xyz = 1;
+ last SWITCH;
+ };
+ $nothing = 1;
+ }
+
+or
+
+ SWITCH: {
+ /^abc/ and $abc = 1, last SWITCH;
+ /^def/ and $def = 1, last SWITCH;
+ /^xyz/ and $xyz = 1, last SWITCH;
+ $nothing = 1;
+ }
+
+or even, horrors,
+
+ if (/^abc/)
+ { $abc = 1 }
+ elsif (/^def/)
+ { $def = 1 }
+ elsif (/^xyz/)
+ { $xyz = 1 }
+ else
+ { $nothing = 1 }
+
diff --git a/pod/perltrap.pod b/pod/perltrap.pod
new file mode 100644
index 0000000000..51dac4770f
--- /dev/null
+++ b/pod/perltrap.pod
@@ -0,0 +1,451 @@
+=head1 NAME
+
+perltrap - Perl traps for the unwary
+
+=head1 DESCRIPTION
+
+The biggest trap of all is forgetting to use the B<-w> switch;
+see L<perlrun>. Making your entire program runnable under
+
+ use strict;
+
+can help make your program more bullet-proof, but sometimes
+it's too annoying for quick throw-away programs.
+
+=head2 Awk Traps
+
+Accustomed B<awk> users should take special note of the following:
+
+=over 4
+
+=item *
+
+The English module, loaded via
+
+ use English;
+
+allows you to refer to special variables (like $RS) as
+though they were in B<awk>; see L<perlvar> for details.
+
+=item *
+
+Semicolons are required after all simple statements in Perl (except
+at the end of a block). Newline is not a statement delimiter.
+
+=item *
+
+Curly brackets are required on C<if>s and C<while>s.
+
+=item *
+
+Variables begin with "$" or "@" in Perl.
+
+=item *
+
+Arrays index from 0. Likewise string positions in substr() and
+index().
+
+=item *
+
+You have to decide whether your array has numeric or string indices.
+
+=item *
+
+Associative array values do not spring into existence upon mere
+reference.
+
+=item *
+
+You have to decide whether you want to use string or numeric
+comparisons.
+
+=item *
+
+Reading an input line does not split it for you. You get to split it
+yourself to an array. And split() operator has different
+arguments.
+
+=item *
+
+The current input line is normally in $_, not $0. It generally does
+not have the newline stripped. ($0 is the name of the program
+executed.) See L<perlvar>.
+
+=item *
+
+$<I<digit>> does not refer to fields--it refers to substrings matched by
+the last match pattern.
+
+=item *
+
+The print() statement does not add field and record separators unless
+you set C<$,> and C<$.>. You can set $OFS and $ORS if you're using
+the English module.
+
+=item *
+
+You must open your files before you print to them.
+
+=item *
+
+The range operator is "..", not comma. The comma operator works as in
+C.
+
+=item *
+
+The match operator is "=~", not "~". ("~" is the one's complement
+operator, as in C.)
+
+=item *
+
+The exponentiation operator is "**", not "^". "^" is the XOR
+operator, as in C. (You know, one could get the feeling that B<awk> is
+basically incompatible with C.)
+
+=item *
+
+The concatenation operator is ".", not the null string. (Using the
+null string would render C</pat/ /pat/> unparsable, since the third slash
+would be interpreted as a division operator--the tokener is in fact
+slightly context sensitive for operators like "/", "?", and ">".
+And in fact, "." itself can be the beginning of a number.)
+
+=item *
+
+The C<next>, C<exit>, and C<continue> keywords work differently.
+
+=item *
+
+
+The following variables work differently:
+
+ Awk Perl
+ ARGC $#ARGV or scalar @ARGV
+ ARGV[0] $0
+ FILENAME $ARGV
+ FNR $. - something
+ FS (whatever you like)
+ NF $#Fld, or some such
+ NR $.
+ OFMT $#
+ OFS $,
+ ORS $\
+ RLENGTH length($&)
+ RS $/
+ RSTART length($`)
+ SUBSEP $;
+
+=item *
+
+You cannot set $RS to a pattern, only a string.
+
+=item *
+
+When in doubt, run the B<awk> construct through B<a2p> and see what it
+gives you.
+
+=back
+
+=head2 C Traps
+
+Cerebral C programmers should take note of the following:
+
+=over 4
+
+=item *
+
+Curly brackets are required on C<if>'s and C<while>'s.
+
+=item *
+
+You must use C<elsif> rather than C<else if>.
+
+=item *
+
+The C<break> and C<continue> keywords from C become in
+Perl C<last> and C<next>, respectively.
+Unlike in C, these do I<NOT> work within a C<do { } while> construct.
+
+=item *
+
+There's no switch statement. (But it's easy to build one on the fly.)
+
+=item *
+
+Variables begin with "$" or "@" in Perl.
+
+=item *
+
+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 *
+
+You can't take the address of anything, although a similar operator
+in Perl 5 is the backslash, which creates a reference.
+
+=item *
+
+C<ARGV> must be capitalized.
+
+=item *
+
+System calls such as link(), unlink(), rename(), etc. return nonzero for
+success, not 0.
+
+=item *
+
+Signal handlers deal with signal names, not numbers. Use C<kill -l>
+to find their names on your system.
+
+=back
+
+=head2 Sed Traps
+
+Seasoned B<sed> programmers should take note of the following:
+
+=over 4
+
+=item *
+
+Backreferences in substitutions use "$" rather than "\".
+
+=item *
+
+The pattern matching metacharacters "(", ")", and "|" do not have backslashes
+in front.
+
+=item *
+
+The range operator is C<...>, rather than comma.
+
+=back
+
+=head2 Shell Traps
+
+Sharp shell programmers should take note of the following:
+
+=over 4
+
+=item *
+
+The backtick operator does variable interpretation without regard to
+the presence of single quotes in the command.
+
+=item *
+
+The backtick operator does no translation of the return value, unlike B<csh>.
+
+=item *
+
+Shells (especially B<csh>) do several levels of substitution on each
+command line. Perl does substitution only in certain constructs
+such as double quotes, backticks, angle brackets, and search patterns.
+
+=item *
+
+Shells interpret scripts a little bit at a time. Perl compiles the
+entire program before executing it (except for C<BEGIN> blocks, which
+execute at compile time).
+
+=item *
+
+The arguments are available via @ARGV, not $1, $2, etc.
+
+=item *
+
+The environment is not automatically made available as separate scalar
+variables.
+
+=back
+
+=head2 Perl Traps
+
+Practicing Perl Programmers should take note of the following:
+
+=over 4
+
+=item *
+
+Remember that many operations behave differently in a list
+context than they do in a scalar one. See L<perldata> for details.
+
+=item *
+
+Avoid barewords if you can, especially all lower-case ones.
+You can't tell just by looking at it whether a bareword is
+a function or a string. By using quotes on strings and
+parens on function calls, you won't ever get them confused.
+
+=item *
+
+You cannot discern from mere inspection which built-ins
+are unary operators (like chop() and chdir())
+and which are list operators (like print() and unlink()).
+(User-defined subroutines can B<only> be list operators, never
+unary ones.) See L<perlop>.
+
+=item *
+
+People have a hard type remembering that some functions
+default to $_, or @ARGV, or whatever, but that others which
+you might expect to do not.
+
+=item *
+
+Remember not to use "C<=>" when you need "C<=~>";
+these two constructs are quite different:
+
+ $x = /foo/;
+ $x =~ /foo/;
+
+=item *
+
+The C<do {}> construct isn't a real loop that you can use
+loop control on.
+
+=item *
+
+Use my() for local variables whenever you can get away with
+it (but see L<perlform> for where you can't).
+Using local() actually gives a local value to a global
+variable, which leaves you open to unforeseen side-effects
+of dynamic scoping.
+
+=back
+
+=head2 Perl4 Traps
+
+Penitent Perl 4 Programmers should take note of the following
+incompatible changes that occurred between release 4 and release 5:
+
+=over 4
+
+=item *
+
+C<@> now always interpolates an array in double-quotish strings. Some programs
+may now need to use backslash to protect any C<@> that shouldn't interpolate.
+
+=item *
+Barewords that used to look like strings to Perl will now look like subroutine
+calls if a subroutine by that name is defined before the compiler sees them.
+For example:
+
+ sub SeeYa { die "Hasta la vista, baby!" }
+ $SIG{QUIT} = SeeYa;
+
+In Perl 4, that set the signal handler; in Perl 5, it actually calls the
+function! You may use the B<-w> switch to find such places.
+
+=item *
+
+Symbols starting with C<_> are no longer forced into package C<main>, except
+for $_ itself (and @_, etc.).
+
+=item *
+
+C<s'$lhs'$rhs'> now does no interpolation on either side. It used to
+interpolate C<$lhs> but not C<$rhs>.
+
+=item *
+
+The second and third arguments of splice() are now evaluated in scalar
+context (as the book says) rather than list context.
+
+=item *
+
+These are now semantic errors because of precedence:
+
+ shift @list + 20;
+ $n = keys %map + 20;
+
+Because if that were to work, then this couldn't:
+
+ sleep $dormancy + 20;
+
+=item *
+
+C<open FOO || die> is now incorrect. You need parens around the filehandle.
+While temporarily supported, using such a construct will
+generate a non-fatal (but non-suppressible) warning.
+
+=item *
+
+The elements of argument lists for formats are now evaluated in list
+context. This means you can interpolate list values now.
+
+=item *
+
+You can't do a C<goto> into a block that is optimized away. Darn.
+
+=item *
+
+It is no longer syntactically legal to use whitespace as the name
+of a variable, or as a delimiter for any kind of quote construct.
+Double darn.
+
+=item *
+
+The caller() function now returns a false value in a scalar context if there
+is no caller. This lets library files determine if they're being required.
+
+=item *
+
+C<m//g> now attaches its state to the searched string rather than the
+regular expression.
+
+=item *
+
+C<reverse> is no longer allowed as the name of a sort subroutine.
+
+=item *
+
+B<taintperl> is no longer a separate executable. There is now a B<-T>
+switch to turn on tainting when it isn't turned on automatically.
+
+=item *
+
+Double-quoted strings may no longer end with an unescaped C<$> or C<@>.
+
+=item *
+
+The archaic C<while/if> BLOCK BLOCK syntax is no longer supported.
+
+
+=item *
+
+Negative array subscripts now count from the end of the array.
+
+=item *
+
+The comma operator in a scalar context is now guaranteed to give a
+scalar context to its arguments.
+
+=item *
+
+The C<**> operator now binds more tightly than unary minus.
+It was documented to work this way before, but didn't.
+
+=item *
+
+Setting C<$#array> lower now discards array elements.
+
+=item *
+
+delete() is not guaranteed to return the old value for tie()d arrays,
+since this capability may be onerous for some modules to implement.
+
+=item *
+
+Some error messages will be different.
+
+=item *
+
+Some bugs may have been inadvertently removed.
+
+=back
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
new file mode 100644
index 0000000000..bdf24f6c89
--- /dev/null
+++ b/pod/perlvar.pod
@@ -0,0 +1,608 @@
+=head1 NAME
+
+perlvar - Perl predefined variables
+
+=head1 DESCRIPTION
+
+=head2 Predefined Names
+
+The following names have special meaning to Perl. Most of the
+punctuational names have reasonable mnemonics, or analogues in one of
+the shells. Nevertheless, if you wish to use the long variable names,
+you just need to say
+
+ use English;
+
+at the top of your program. This will alias all the short names to the
+long names in the current package. Some of them even have medium names,
+generally borrowed from B<awk>.
+
+To go a step further, those variables that depend on the currently
+selected filehandle may instead be set by calling an object method on
+the FileHandle object. (Summary lines below for this contain the word
+HANDLE.) First you must say
+
+ use FileHandle;
+
+after which you may use either
+
+ method HANDLE EXPR
+
+or
+
+ HANDLE->method(EXPR)
+
+Each of the methods returns the old value of the FileHandle attribute.
+The methods each take an optional EXPR, which if supplied specifies the
+new value for the FileHandle attribute in question. If not supplied,
+most of the methods do nothing to the current value, except for
+autoflush(), which will assume a 1 for you, just to be different.
+
+A few of these variables are considered "read-only". This means that if you
+try to assign to this variable, either directly or indirectly through
+a reference. If you attempt to do so, you'll raise a run-time exception.
+
+=over 8
+
+=item $ARG
+
+=item $_
+
+The default input and pattern-searching space. The following pairs are
+equivalent:
+
+ while (<>) {...} # only equivalent in while!
+ while ($_ = <>) {...}
+
+ /^Subject:/
+ $_ =~ /^Subject:/
+
+ tr/a-z/A-Z/
+ $_ =~ tr/a-z/A-Z/
+
+ chop
+ chop($_)
+
+(Mnemonic: underline is understood in certain operations.)
+
+=item $<I<digit>>
+
+Contains the subpattern from the corresponding set of parentheses in
+the last pattern matched, not counting patterns matched in nested
+blocks that have been exited already. (Mnemonic: like \digit.)
+These variables are all read-only.
+
+=item $MATCH
+
+=item $&
+
+The string matched by the last successful pattern match (not counting
+any matches hidden within a BLOCK or eval() enclosed by the current
+BLOCK). (Mnemonic: like & in some editors.) This variable is read-only.
+
+=item $PREMATCH
+
+=item $`
+
+The string preceding whatever was matched by the last successful
+pattern match (not counting any matches hidden within a BLOCK or eval
+enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted
+string.) This variable is read-only.
+
+=item $POSTMATCH
+
+=item $'
+
+The string following whatever was matched by the last successful
+pattern match (not counting any matches hidden within a BLOCK or eval()
+enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted
+string.) Example:
+
+ $_ = 'abcdefghi';
+ /def/;
+ print "$`:$&:$'\n"; # prints abc:def:ghi
+
+This variable is read-only.
+
+=item $LAST_PAREN_MATCH
+
+=item $+
+
+The last bracket matched by the last search pattern. This is useful if
+you don't know which of a set of alternative patterns matched. For
+example:
+
+ /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+
+(Mnemonic: be positive and forward looking.)
+This variable is read-only.
+
+=item $MULTILINE_MATCHING
+
+=item $*
+
+Set to 1 to do multiline matching within a string, 0 to tell Perl
+that it can assume that strings contain a single line, for the purpose
+of optimizing pattern matches. Pattern matches on strings containing
+multiple newlines can produce confusing results when "C<$*>" is 0. Default
+is 0. (Mnemonic: * matches multiple things.) Note that this variable
+only influences the interpretation of "C<^>" and "C<$>". A literal newline can
+be searched for even when C<$* == 0>.
+
+Use of "C<$*>" is deprecated in Perl 5.
+
+=item input_line_number HANDLE EXPR
+
+=item $INPUT_LINE_NUMBER
+
+=item $NR
+
+=item $.
+
+The current input line number of the last filehandle that was read.
+This variable should be considered read-only.
+Remember that only an explicit close on the filehandle
+resets the line number. Since "C<E<lt>E<gt>>" never does an explicit close, line
+numbers increase across ARGV files (but see examples under eof()).
+(Mnemonic: many programs use "." to mean the current line number.)
+
+=item input_record_separator HANDLE EXPR
+
+=item $INPUT_RECORD_SEPARATOR
+
+=item $RS
+
+=item $/
+
+The input record separator, newline by default. Works like B<awk>'s RS
+variable, including treating blank lines as delimiters if set to the
+null string. You may set it to a multicharacter string to match a
+multi-character delimiter. Note that setting it to C<"\n\n"> means
+something slightly different than setting it to C<"">, if the file
+contains consecutive blank lines. Setting it to C<""> will treat two or
+more consecutive blank lines as a single blank line. Setting it to
+C<"\n\n"> will blindly assume that the next input character belongs to the
+next paragraph, even if it's a newline. (Mnemonic: / is used to
+delimit line boundaries when quoting poetry.)
+
+ undef $/;
+ $_ = <FH>; # whole file now here
+ s/\n[ \t]+/ /g;
+
+=item autoflush HANDLE EXPR
+
+=item $OUTPUT_AUTOFLUSH
+
+=item $|
+
+If set to nonzero, forces a flush after every write or print on the
+currently selected output channel. Default is 0. Note that STDOUT
+will typically be line buffered if output is to the terminal and block
+buffered otherwise. Setting this variable is useful primarily when you
+are outputting to a pipe, such as when you are running a Perl script
+under rsh and want to see the output as it's happening. (Mnemonic:
+when you want your pipes to be piping hot.)
+
+=item output_field_separator HANDLE EXPR
+
+=item $OUTPUT_FIELD_SEPARATOR
+
+=item $OFS
+
+=item $,
+
+The output field separator for the print operator. Ordinarily the
+print operator simply prints out the comma separated fields you
+specify. In order to get behavior more like B<awk>, set this variable
+as you would set B<awk>'s OFS variable to specify what is printed
+between fields. (Mnemonic: what is printed when there is a , in your
+print statement.)
+
+=item output_record_separator HANDLE EXPR
+
+=item $OUTPUT_RECORD_SEPARATOR
+
+=item $ORS
+
+=item $\
+
+The output record separator for the print operator. Ordinarily the
+print operator simply prints out the comma separated fields you
+specify, with no trailing newline or record separator assumed. In
+order to get behavior more like B<awk>, set this variable as you would
+set B<awk>'s ORS variable to specify what is printed at the end of the
+print. (Mnemonic: you set "C<$\>" instead of adding \n at the end of the
+print. Also, it's just like /, but it's what you get "back" from
+Perl.)
+
+=item $LIST_SEPARATOR
+
+=item $"
+
+This is like "C<$,>" except that it applies to array values interpolated
+into a double-quoted string (or similar interpreted string). Default
+is a space. (Mnemonic: obvious, I think.)
+
+=item $SUBSCRIPT_SEPARATOR
+
+=item $SUBSEP
+
+=item $;
+
+The subscript separator for multi-dimensional array emulation. If you
+refer to a hash element as
+
+ $foo{$a,$b,$c}
+
+it really means
+
+ $foo{join($;, $a, $b, $c)}
+
+But don't put
+
+ @foo{$a,$b,$c} # a slice--note the @
+
+which means
+
+ ($foo{$a},$foo{$b},$foo{$c})
+
+Default is "\034", the same as SUBSEP in B<awk>. Note that if your
+keys contain binary data there might not be any safe value for "C<$;>".
+(Mnemonic: comma (the syntactic subscript separator) is a
+semi-semicolon. Yeah, I know, it's pretty lame, but "C<$,>" is already
+taken for something more important.)
+
+Consider using "real" multi-dimensional arrays in Perl 5.
+
+=item $OFMT
+
+=item $#
+
+The output format for printed numbers. This variable is a half-hearted
+attempt to emulate B<awk>'s OFMT variable. There are times, however,
+when B<awk> and Perl have differing notions of what is in fact
+numeric. Also, the initial value is %.20g rather than %.6g, so you
+need to set "C<$#>" explicitly to get B<awk>'s value. (Mnemonic: # is the
+number sign.)
+
+Use of "C<$#>" is deprecated in Perl 5.
+
+=item format_page_number HANDLE EXPR
+
+=item $FORMAT_PAGE_NUMBER
+
+=item $%
+
+The current page number of the currently selected output channel.
+(Mnemonic: % is page number in B<nroff>.)
+
+=item format_lines_per_page HANDLE EXPR
+
+=item $FORMAT_LINES_PER_PAGE
+
+=item $=
+
+The current page length (printable lines) of the currently selected
+output channel. Default is 60. (Mnemonic: = has horizontal lines.)
+
+=item format_lines_left HANDLE EXPR
+
+=item $FORMAT_LINES_LEFT
+
+=item $-
+
+The number of lines left on the page of the currently selected output
+channel. (Mnemonic: lines_on_page - lines_printed.)
+
+=item format_name HANDLE EXPR
+
+=item $FORMAT_NAME
+
+=item $~
+
+The name of the current report format for the currently selected output
+channel. Default is name of the filehandle. (Mnemonic: brother to
+"C<$^>".)
+
+=item format_top_name HANDLE EXPR
+
+=item $FORMAT_TOP_NAME
+
+=item $^
+
+The name of the current top-of-page format for the currently selected
+output channel. Default is name of the filehandle with _TOP
+appended. (Mnemonic: points to top of page.)
+
+=item format_line_break_characters HANDLE EXPR
+
+=item $FORMAT_LINE_BREAK_CHARACTERS
+
+=item $:
+
+The current set of characters after which a string may be broken to
+fill continuation fields (starting with ^) in a format. Default is
+S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in
+poetry is a part of a line.)
+
+=item format_formfeed HANDLE EXPR
+
+=item $FORMAT_FORMFEED
+
+=item $^L
+
+What formats output to perform a formfeed. Default is \f.
+
+=item $ACCUMULATOR
+
+=item $^A
+
+The current value of the write() accumulator for format() lines. A format
+contains formline() commands that put their result into C<$^A>. After
+calling its format, write() prints out the contents of C<$^A> and empties.
+So you never actually see the contents of C<$^A> unless you call
+formline() yourself and then look at it. See L<perlform> and
+L<perlfunc/formline()>.
+
+=item $CHILD_ERROR
+
+=item $?
+
+The status returned by the last pipe close, backtick (C<``>) command,
+or system() operator. Note that this is the status word returned by
+the wait() system call, so the exit value of the subprocess is actually
+(C<$? E<gt>E<gt> 8>). Thus on many systems, C<$? & 255> gives which signal,
+if any, the process died from, and whether there was a core dump.
+(Mnemonic: similar to B<sh> and B<ksh>.)
+
+=item $OS_ERROR
+
+=item $ERRNO
+
+=item $!
+
+If used in a numeric context, yields the current value of errno, with
+all the usual caveats. (This means that you shouldn't depend on the
+value of "C<$!>" to be anything in particular unless you've gotten a
+specific error return indicating a system error.) If used in a string
+context, yields the corresponding system error string. You can assign
+to "C<$!>" in order to set I<errno> if, for instance, you want "C<$!>" to return the
+string for error I<n>, or you want to set the exit value for the die()
+operator. (Mnemonic: What just went bang?)
+
+=item $EVAL_ERROR
+
+=item $@
+
+The Perl syntax error message from the last eval() command. If null, the
+last eval() parsed and executed correctly (although the operations you
+invoked may have failed in the normal fashion). (Mnemonic: Where was
+the syntax error "at"?)
+
+=item $PROCESS_ID
+
+=item $PID
+
+=item $$
+
+The process number of the Perl running this script. (Mnemonic: same
+as shells.)
+
+=item $REAL_USER_ID
+
+=item $UID
+
+=item $<
+
+The real uid of this process. (Mnemonic: it's the uid you came I<FROM>,
+if you're running setuid.)
+
+=item $EFFECTIVE_USER_ID
+
+=item $EUID
+
+=item $>
+
+The effective uid of this process. Example:
+
+ $< = $>; # set real to effective uid
+ ($<,$>) = ($>,$<); # swap real and effective uid
+
+(Mnemonic: it's the uid you went I<TO>, if you're running setuid.) Note:
+"C<$E<lt>>" and "C<$E<gt>>" can only be swapped on machines supporting setreuid().
+
+=item $REAL_GROUP_ID
+
+=item $GID
+
+=item $(
+
+The real gid of this process. If you are on a machine that supports
+membership in multiple groups simultaneously, gives a space separated
+list of groups you are in. The first number is the one returned by
+getgid(), and the subsequent ones by getgroups(), one of which may be
+the same as the first number. (Mnemonic: parentheses are used to I<GROUP>
+things. The real gid is the group you I<LEFT>, if you're running setgid.)
+
+=item $EFFECTIVE_GROUP_ID
+
+=item $EGID
+
+=item $)
+
+The effective gid of this process. If you are on a machine that
+supports membership in multiple groups simultaneously, gives a space
+separated list of groups you are in. The first number is the one
+returned by getegid(), and the subsequent ones by getgroups(), one of
+which may be the same as the first number. (Mnemonic: parentheses are
+used to I<GROUP> things. The effective gid is the group that's I<RIGHT> for
+you, if you're running setgid.)
+
+Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
+that support the corresponding I<set[re][ug]id()> routine. "C<$(>" and "C<$)>"
+can only be swapped on machines supporting setregid().
+
+=item $PROGRAM_NAME
+
+=item $0
+
+Contains the name of the file containing the Perl script being
+executed. Assigning to "C<$0>" modifies the argument area that the ps(1)
+program sees. This is more useful as a way of indicating the
+current program state than it is for hiding the program you're running.
+(Mnemonic: same as B<sh> and B<ksh>.)
+
+=item $[
+
+The index of the first element in an array, and of the first character
+in a substring. Default is 0, but you could set it to 1 to make
+Perl behave more like B<awk> (or Fortran) when subscripting and when
+evaluating the index() and substr() functions. (Mnemonic: [ begins
+subscripts.)
+
+As of Perl 5, assignment to "C<$[>" is treated as a compiler directive,
+and cannot influence the behavior of any other file. Its use is
+discouraged.
+
+=item $PERL_VERSION
+
+=item $]
+
+The string printed out when you say C<perl -v>. It can be used to
+determine at the beginning of a script whether the perl interpreter
+executing the script is in the right range of versions. If used in a
+numeric context, returns the version + patchlevel / 1000. Example:
+
+ # see if getc is available
+ ($version,$patchlevel) =
+ $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/;
+ print STDERR "(No filename completion available.)\n"
+ if $version * 1000 + $patchlevel < 2016;
+
+or, used numerically,
+
+ warn "No checksumming!\n" if $] < 3.019;
+
+(Mnemonic: Is this version of perl in the right bracket?)
+
+=item $DEBUGGING
+
+=item $^D
+
+The current value of the debugging flags. (Mnemonic: value of B<-D>
+switch.)
+
+=item $SYSTEM_FD_MAX
+
+=item $^F
+
+The maximum system file descriptor, ordinarily 2. System file
+descriptors are passed to exec()ed processes, while higher file
+descriptors are not. Also, during an open(), system file descriptors are
+preserved even if the open() fails. (Ordinary file descriptors are
+closed before the open() is attempted.) Note that the close-on-exec
+status of a file descriptor will be decided according to the value of
+C<$^F> at the time of the open, not the time of the exec.
+
+=item $INPLACE_EDIT
+
+=item $^I
+
+The current value of the inplace-edit extension. Use C<undef> to disable
+inplace editing. (Mnemonic: value of B<-i> switch.)
+
+=item $PERLDB
+
+=item $^P
+
+The internal flag that the debugger clears so that it doesn't debug
+itself. You could conceivable disable debugging yourself by clearing
+it.
+
+=item $BASETIME
+
+=item $^T
+
+The time at which the script began running, in seconds since the
+epoch (beginning of 1970). The values returned by the B<-M>, B<-A>
+and B<-C> filetests are
+based on this value.
+
+=item $WARNING
+
+=item $^W
+
+The current value of the warning switch, either TRUE or FALSE. (Mnemonic: related to the
+B<-w> switch.)
+
+=item $EXECUTABLE_NAME
+
+=item $^X
+
+The name that the Perl binary itself was executed as, from C's C<argv[0]>.
+
+=item $ARGV
+
+contains the name of the current file when reading from <>.
+
+=item @ARGV
+
+The array @ARGV contains the command line arguments intended for the
+script. Note that C<$#ARGV> is the generally number of arguments minus
+one, since C<$ARGV[0]> is the first argument, I<NOT> the command name. See
+"C<$0>" for the command name.
+
+=item @INC
+
+The array @INC contains the list of places to look for Perl scripts to
+be evaluated by the C<do EXPR>, C<require>, or C<use> constructs. It
+initially consists of the arguments to any B<-I> command line switches,
+followed by the default Perl library, probably "/usr/local/lib/perl",
+followed by ".", to represent the current directory.
+
+=item %INC
+
+The hash %INC contains entries for each filename that has
+been included via C<do> or C<require>. The key is the filename you
+specified, and the value is the location of the file actually found.
+The C<require> command uses this array to determine whether a given file
+has already been included.
+
+=item $ENV{expr}
+
+The hash %ENV contains your current environment. Setting a
+value in C<ENV> changes the environment for child processes.
+
+=item $SIG{expr}
+
+The hash %SIG is used to set signal handlers for various
+signals. Example:
+
+ sub handler { # 1st argument is signal name
+ local($sig) = @_;
+ print "Caught a SIG$sig--shutting down\n";
+ close(LOG);
+ exit(0);
+ }
+
+ $SIG{'INT'} = 'handler';
+ $SIG{'QUIT'} = 'handler';
+ ...
+ $SIG{'INT'} = 'DEFAULT'; # restore default action
+ $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
+
+The %SIG array only contains values for the signals actually set within
+the Perl script. Here are some other examples:
+
+ $SIG{PIPE} = Plumber; # SCARY!!
+ $SIG{"PIPE"} = "Plumber"; # just fine, assumes main::Plumber
+ $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber
+ $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return??
+
+The one marked scary is problematic because it's a bareword, which means
+sometimes it's a string representing the function, and sometimes it's
+going to call the subroutine call right then and there! Best to be sure
+and quote it or take a reference to it. *Plumber works too. See <perlsubs>.
+
+=back
+
diff --git a/pod/pod2html b/pod/pod2html
new file mode 100644
index 0000000000..1bfc8f6a6a
--- /dev/null
+++ b/pod/pod2html
@@ -0,0 +1,209 @@
+#!../perl
+
+# The beginning of the url for the anchors to the other sections.
+chop($wd=`pwd`);
+$type="<A HREF=\"file://localhost".$wd."/";
+$debug=0;
+$/ = "";
+$p=\%p;
+@exclusions=("perldebug","perlform","perlobj","perlstyle","perltrap","perlmod");
+$indent=0;
+opendir(DIR,".");
+@{$p->{"pods"}}=grep(/\.pod$/,readdir(DIR));
+closedir(DIR);
+
+# learn the important stuff
+
+foreach $tmpod (@{$p->{"pods"}}){
+ ($pod=$tmpod)=~s/\.pod$//;
+ $p->{"podnames"}->{$pod}=1;
+ next if grep(/$pod/,@exclusions);
+ open(POD,"<$tmpod");
+ while(<POD>){
+ s/B<([^<>]*)>/$1/g; # bold
+ s/I<([^<>]*)>/$1/g; # bold
+ if (s/^=//) {
+ s/\n$//s;
+ s/\n/ /g;
+ ($cmd, $_) = split(' ', $_, 2);
+ if ($cmd eq "item") {
+ ($what,$rest)=split(' ', $_, 2);
+ $what=~s#(-.).*#$1#;
+ $what=~s/\s*$//;
+ next if defined $p->{"items"}->{$what};
+ $p->{"items"}->{$what} = $pod."_".$i++;
+ }
+ elsif($cmd =~ /^head/){
+ $_=~s/\s*$//;
+ next if defined($p->{"headers"}->{$_});
+ $p->{"headers"}->{$_} = $pod."_".$i++;
+ }
+ }
+ }
+}
+
+$/="";
+
+# parse the pods, produce html
+foreach $tmpod (@{$p->{"pods"}}){
+ open(POD,"<$tmpod") || die "cant open $pod";
+ ($pod=$tmpod)=~s/\.pod$//;
+ open(HTML,">$pod.html");
+ print HTML "<!-- \$RCSfile\$\$Revision\$\$Date\$ -->\n";
+ print HTML "<!-- \$Log\$ -->\n";
+ print HTML "<HTML>\n";
+ print HTML "<TITLE> \U$pod\E </TITLE>\n";
+ $cutting = 1;
+ while (<POD>) {
+ if ($cutting) {
+ next unless /^=/;
+ $cutting = 0;
+ }
+ chop;
+ length || (print "\n") && next;
+ # Translate verabatim paragraph
+
+ if (/^\s/) {
+ $unordered=0;
+ &pre_escapes;
+ &post_escapes;
+ @lines = split(/\n/);
+ if($lines[0]=~/^\s+(\w*)\t(.*)/){ # listing or unordered list
+ ($key,$rest)=($1,$2);
+ if(defined($p->{"podnames"}->{$key})){
+ print HTML "\n<ul>\n";
+ $unordered = 1;
+ }
+ else{
+ print HTML "\n<listing>\n";
+ }
+ foreach $line (@lines){
+ ($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rest)=($1,$2));
+ print HTML defined($p->{"podnames"}->{$key}) ?
+ "<li>$type$key.html\">$key<\/A>\t$rest\n" : "$line \n";
+ }
+ print HTML $unordered ? "</ul>\n" : "</listing>\n";
+ next;
+ }else{ # preformatted text
+ print HTML "<pre>\n";
+ for(@lines){
+ s/^/ /;
+ s/\t/ /g;
+ print HTML $_,"\n";
+ }
+ print HTML "</pre>\n";
+ next;
+ }
+ }
+ &pre_escapes;
+ s/S<([^<>]*)>/$1/g; # embedded special
+ $_ = &Do_refs($_,$pod);
+ s/Z<>/<p>/g; # ?
+ s/E<([^<>]*)>/\&$1\;/g; # embedded special
+ &post_escapes;
+ if (s/^=//) {
+ s/\n$//s;
+ s/\n/ /g;
+ ($cmd, $_) = split(' ', $_, 2);
+ if ($cmd eq 'cut') {
+ $cutting = 1;
+ }
+ elsif ($cmd eq 'head1') {
+ print HTML qq{<h2>$_</h2>\n};
+ }
+ elsif ($cmd eq 'head2') {
+ print HTML qq{<h3>$_</h3>\n};
+ }
+ elsif ($cmd eq 'over') {
+ push(@indent,$indent);
+ $indent = $_ + 0;
+ print HTML qq{\n<dl>\n};
+ }
+ elsif ($cmd eq 'back') {
+ $indent = pop(@indent);
+ warn "Unmatched =back\n" unless defined $indent;
+ $needspace = 1;
+ print HTML qq{\n</dl>\n\n};
+ }
+ elsif ($cmd eq 'item') {
+ ($what,$rest)=split(' ', $_, 2);
+ $what=~s/\s*$//;
+ if($justdid ne $what){
+ print HTML "\n<A NAME=\"".$p->{"items"}->{$what}."\"></A>\n";
+ $justdid=$what;
+ }
+ print HTML qq{<dt><B>$_</B> </dt>\n};
+ $next_para=1;
+ }
+ else {
+ warn "Unrecognized directive: $cmd\n";
+ }
+ }
+ else {
+ length || next;
+ $next_para && (print HTML qq{<dd>\n});
+ print HTML "$_<p>";
+ $next_para && (print HTML qq{</dd>\n<p>\n}) && ($next_para=0);
+ }
+ }
+}
+print HTML "\n</HTML>\n";
+
+#########################################################################
+
+sub pre_escapes {
+ s/\&/\&amp\;/g;
+ s/<</\&lt\;\&lt\;/g;
+ s/([^ESIBLCF])</$1\&lt\;/g;
+}
+
+sub post_escapes{
+ s/>>/\&gt\;\&gt\;/g;
+ s/([^"AIB])>/$1\&gt\;/g;
+}
+
+sub Do_refs{
+local($para,$pod)=@_;
+foreach $char ("L","C","I","B"){
+ next unless /($char<[^<>]*>)/;
+ local(@ar) = split(/($char<[^<>]*>)/,$para);
+ local($this,$key,$num);
+ for($this=0;$this<=$#ar;$this++){
+ next unless $ar[$this] =~ /${char}<([^<>]*)>/;
+ $key=$1;
+
+ if((defined($p->{"podnames"}->{$key})) && ($char eq "L")){
+ $ar[$this] = "\n$type$key.html\">\nthe $key manpage<\/A>\n"; #
+ }
+ elsif(defined($p->{"items"}->{$key})){
+ ($pod2,$num)=split(/_/,$p->{"items"}->{$key},2);
+ $ar[$this] = (($pod2 eq $pod) && ($para=~/^\=item/)) ?
+ "\n<A NAME=\"".$p->{"items"}->{$key}."\">\n$key</A>\n"
+ :
+ "\n$type$pod2.html\#".$p->{"items"}->{$key}."\">$key<\/A>\n";
+ }
+ elsif(defined($p->{"headers"}->{$key})){
+ ($pod2,$num)=split(/_/,$p->{"headers"}->{$key},2);
+ $ar[$this] = (($pod eq $pod2) && ($para=~/^\=head/)) ?
+ "\n<A NAME=\"".$p->{"headers"}->{$key}."\">\n$key</A>\n"
+ :
+ "\n$type$pod2.html\#".$p->{"headers"}->{$key}."\">$key<\/A>\n";
+ }
+ else{
+ (warn "No \"=item\" or \"=head\" reference for $ar[$this] in $pod\n") if $debug;
+ if($char =~ /^[BCF]$/){
+ $ar[$this]="<B>$key</B>";
+ }
+ elsif($char eq "L"){
+ $ar[$this]=$key;
+ }
+ elsif($char eq "I"){
+ $ar[$this]="<I>$key</I>";
+ }
+ }
+ }
+ $para=join('',@ar);
+}
+$para;
+}
+sub wait{1;}
diff --git a/pod/pod2man b/pod/pod2man
new file mode 100755
index 0000000000..5b577738e3
--- /dev/null
+++ b/pod/pod2man
@@ -0,0 +1,625 @@
+#!/usr/bin/perl
+
+$/ = "";
+$cutting = 1;
+
+$CFont = 'CW';
+if ($ARGV[0] =~ s/-fc(.*)//) {
+ shift;
+ $CFont = $1 || shift;
+}
+
+if (length($CFont) == 2) {
+ $CFont_embed = "\\f($CFont";
+}
+elsif (length($CFont) == 1) {
+ $CFont_embed = "\\f$CFont";
+}
+else {
+ die "Roff font should be 1 or 2 chars, not `$CFont_embed'";
+}
+
+$name = @ARGV ? $ARGV[0] : "something";
+$name =~ s/\..*//;
+
+print <<"END";
+.rn '' }`
+''' \$RCSfile\$\$Revision\$\$Date\$
+'''
+''' \$Log\$
+'''
+.de Sh
+.br
+.if t .Sp
+.ne 5
+.PP
+\\fB\\\\\$1\\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\\\n(.\$>=3 .ne \\\\\$3
+.el .ne 3
+.IP "\\\\\$1" \\\\\$2
+..
+.de Vb
+.ft $CFont
+.nf
+.ne \\\\\$1
+..
+.de Ve
+.ft R
+
+.fi
+..
+'''
+'''
+''' Set up \\*(-- to give an unbreakable dash;
+''' string Tr holds user defined translation string.
+''' Bell System Logo is used as a dummy character.
+'''
+.tr \\(*W-|\\(bv\\*(Tr
+.ie n \\{\\
+.ds -- \\(*W-
+.if (\\n(.H=4u)&(1m=24u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-12u'-\\" diablo 10 pitch
+.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+.ds L' '
+.ds R' '
+'br\\}
+.el\\{\\
+.ds -- \\(em\\|
+.tr \\*(Tr
+.ds L" ``
+.ds R" ''
+.ds L' `
+.ds R' '
+.if t .ds PI \\(*p
+.if n .ds PI PI
+'br\\}
+.TH \U$name\E 1 "\\*(RP"
+.UC
+END
+
+print <<'END';
+.if n .hy 0
+.if n .na
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.de CQ \" put $1 in typewriter font
+END
+print ".ft $CFont\n";
+print <<'END';
+'if n "\c
+'if t \\\\&\\\\$1\c
+'if n \\\\&\\\\$1\c
+'if n \&"
+\\\\&\\\\$2 \\\\$3 \\\\$4 \\\\$5 \\\\$6 \\\\$7
+'.ft R
+..
+.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+. \" AM - accent mark definitions
+.bd S B 3
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds ? ?
+. ds ! !
+. ds /
+. ds q
+.\}
+.if t \{\
+. ds ' \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\'\h"|\\\\n:u"
+. ds ` \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\`\h'|\\\\n:u'
+. ds ^ \\\\k:\h'-(\\\\n(.wu*10/11-\*(#H)'^\h'|\\\\n:u'
+. ds , \\\\k:\h'-(\\\\n(.wu*8/10)',\h'|\\\\n:u'
+. ds ~ \\\\k:\h'-(\\\\n(.wu-\*(#H-.1m)'~\h'|\\\\n:u'
+. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+. ds / \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\\\n:u'
+. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\\\k:\h'-(\\\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds v \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\\\n:u'\*(#]
+.ds _ \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\\\n:u'
+.ds . \\\\k:\h'-(\\\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\\\n:u'
+.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+.ds o \\\\k:\h'-(\\\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.ds oe o\h'-(\w'o'u*4/10)'e
+.ds Oe O\h'-(\w'O'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\\\k:\h'-(\\\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\\\n:u'
+.if v .ds ^ \\\\k:\h'-(\\\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds v \h'-1'\o'\(aa\(ga'
+. ds _ \h'-1'^
+. ds . \h'-1'.
+. ds 3 3
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+. ds oe oe
+. ds Oe OE
+.\}
+.rm #[ #] #H #V #F C
+END
+
+$indent = 0;
+
+while (<>) {
+ if ($cutting) {
+ next unless /^=/;
+ $cutting = 0;
+ }
+ chomp;
+
+ # Translate verbatim paragraph
+
+ if (/^\s/) {
+ @lines = split(/\n/);
+ for (@lines) {
+ 1 while s
+ {^( [^\t]* ) \t ( \t* ) }
+ { $1 . ' ' x (8 - (length($1)%8) + 8 * (length($2))) }ex;
+ s/\\/\\e/g;
+ s/\A/\\&/s;
+ }
+ $lines = @lines;
+ makespace() unless $verbatim++;
+ print ".Vb $lines\n";
+ print join("\n", @lines), "\n";
+ print ".Ve\n";
+ $needspace = 0;
+ next;
+ }
+
+ $verbatim = 0;
+
+ # check for things that'll hosed our noremap scheme; affects $_
+ init_noremap();
+
+ if (!/^=item/) {
+
+ # trofficate backslashes; must do it before what happens below
+ s/\\/noremap('\\e')/ge;
+
+ # first hide the escapes in case we need to
+ # intuit something and get it wrong due to fmting
+
+ s/([A-Z]<[^<>]*>)/noremap($1)/ge;
+
+ # func() is a reference to a perl function
+ s{
+ \b
+ (
+ [:\w]+ \(\)
+ )
+ } {I<$1>}gx;
+
+ # func(n) is a reference to a man page
+ s{
+ (\w+)
+ (
+ \(
+ [^\s,\051]+
+ \)
+ )
+ } {I<$1>\\|$2}gx;
+
+ # convert simple variable references
+ s/([\$\@%][\w:]+)/C<$1>/g;
+
+ if (m{ (
+ [\-\w]+
+ \(
+ [^\051]*?
+ [\@\$,]
+ [^\051]*?
+ \)
+ )
+ }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
+ {
+ warn "``$1'' should be a [LCI]<$1> ref";
+ }
+
+ while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
+ warn "``$1'' should be [CB]<$1> ref";
+ }
+
+ # put it back so we get the <> processed again;
+ clear_noremap(0); # 0 means leave the E's
+
+ } else {
+ # trofficate backslashes
+ s/\\/noremap('\\e')/ge;
+
+ }
+
+ # need to hide E<> first; they're processed in clear_noremap
+ s/(E<[^<>]+>)/noremap($1)/ge;
+
+
+ $maxnest = 10;
+ while ($maxnest-- && /[A-Z]</) {
+
+ # can't do C font here
+ s/([BI])<([^<>]*)>/font($1) . $2 . font('R')/eg;
+
+ # files and filelike refs in italics
+ s/F<([^<>]*)>/I<$1>/g;
+
+ # no break -- usually we want C<> for this
+ s/S<([^<>]*)>/nobreak($1)/eg;
+
+ # LREF: a manpage(3f)
+ s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;
+
+ # LREF: an =item on another manpage
+ s{
+ L<
+ ([^/]+)
+ /
+ (
+ [:\w]+
+ (\(\))?
+ )
+ >
+ } {the C<$2> entry in the I<$1> manpage}gx;
+
+ # LREF: an =item on this manpage
+ s{
+ ((?:
+ L<
+ /
+ (
+ [:\w]+
+ (\(\))?
+ )
+ >
+ (,?\s+(and\s+)?)?
+ )+)
+ } { internal_lrefs($1) }gex;
+
+ # LREF: a =head2 (head1?), maybe on a manpage, maybe right here
+ # the "func" can disambiguate
+ s{
+ L<
+ (?:
+ ([a-zA-Z]\S+?) /
+ )?
+ "?(.*?)"?
+ >
+ }{
+ do {
+ $1 # if no $1, assume it means on this page.
+ ? "the section on I<$2> in the I<$1> manpage"
+ : "the section on I<$2>"
+ }
+ }gex;
+
+ s/Z<>/\\&/g;
+
+ # comes last because not subject to reprocessing
+ s/C<([^<>]*)>/noremap("${CFont_embed}${1}\\fR")/eg;
+ }
+
+ if (s/^=//) {
+ $needspace = 0; # Assume this.
+
+ s/\n/ /g;
+
+ ($Cmd, $_) = split(' ', $_, 2);
+
+ if (defined $_) {
+ &escapes;
+ s/"/""/g;
+ }
+
+ clear_noremap(1);
+
+ if ($Cmd eq 'cut') {
+ $cutting = 1;
+ }
+ elsif ($Cmd eq 'head1') {
+ print qq{.SH "$_"\n}
+ }
+ elsif ($Cmd eq 'head2') {
+ print qq{.Sh "$_"\n}
+ }
+ elsif ($Cmd eq 'over') {
+ push(@indent,$indent);
+ $indent = $_ + 0;
+ }
+ elsif ($Cmd eq 'back') {
+ $indent = pop(@indent);
+ warn "Unmatched =back\n" unless defined $indent;
+ $needspace = 1;
+ }
+ elsif ($Cmd eq 'item') {
+ s/^\*( |$)/\\(bu$1/g;
+ print STDOUT qq{.Ip "$_" $indent\n};
+ }
+ else {
+ warn "Unrecognized directive: $Cmd\n";
+ }
+ }
+ else {
+ if ($needspace) {
+ &makespace;
+ }
+ &escapes;
+ clear_noremap(1);
+ print $_, "\n";
+ $needspace = 1;
+ }
+}
+
+print <<"END";
+
+.rn }` ''
+END
+
+#########################################################################
+
+sub nobreak {
+ my $string = shift;
+ $string =~ s/ /\\ /g;
+ $string;
+}
+
+sub escapes {
+
+ # translate the minus in foo-bar into foo\-bar for roff
+ s/([^0-9a-z-])-([^-])/$1\\-$2/g;
+
+ # make -- into the string version \*(-- (defined above)
+ s/\b--\b/\\*(--/g;
+ s/"--([^"])/"\\*(--$1/g; # should be a better way
+ s/([^"])--"/$1\\*(--"/g;
+
+ # fix up quotes; this is somewhat tricky
+ if (!/""/) {
+ s/(^|\s)(['"])/noremap("$1\\*(L$2")/ge;
+ s/(['"])($|[\-\s,;\\!?.])/noremap("\\*(R$1$2")/ge;
+ }
+
+ #s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
+ #s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g;
+
+
+ # make sure that func() keeps a bit a space tween the parens
+ ### s/\b\(\)/\\|()/g;
+ ### s/\b\(\)/(\\|)/g;
+
+ # make C++ into \*C+, which is a squinched version (defined above)
+ s/\bC\+\+/\\*(C+/g;
+
+ # make double underbars have a little tiny space between them
+ s/__/_\\|_/g;
+
+ # PI goes to \*(-- (defined above)
+ s/\bPI\b/noremap('\\*(PI')/ge;
+
+ # make all caps a teeny bit smaller, but don't muck with embedded code literals
+ my $hidCFont = font('C');
+ if ($Cmd !~ /^head1/) { # SH already makes smaller
+ # /g isn't enough; 1 while or we'll be off
+
+# 1 while s{
+# (?!$hidCFont)(..|^.|^)
+# \b
+# (
+# [A-Z][\/A-Z+:\-\d_$.]+
+# )
+# (s?)
+# \b
+# } {$1\\s-1$2\\s0}gmox;
+
+ 1 while s{
+ (?!$hidCFont)(..|^.|^)
+ (
+ \b[A-Z]{2,}[\/A-Z+:\-\d_\$]*\b
+ )
+ } {
+ $1 . noremap( '\\s-1' . $2 . '\\s0' )
+ }egmox;
+
+ }
+}
+
+# make troff just be normal, but make small nroff get quoted
+# decided to just put the quotes in the text; sigh;
+sub ccvt {
+ local($_,$prev) = @_;
+ if ( /^\W+$/ && !/^\$./ ) {
+ ($prev && "\n") . noremap(qq{.CQ $_ \n\\&});
+ # what about $" ?
+ } else {
+ noremap(qq{${CFont_embed}$_\\fR});
+ }
+ noremap(qq{.CQ "$_" \n\\&});
+}
+
+sub makespace {
+ if ($indent) {
+ print ".Sp\n";
+ }
+ else {
+ print ".PP\n";
+ }
+}
+
+sub font {
+ local($font) = shift;
+ return '\\f' . noremap($font);
+}
+
+sub noremap {
+ local($thing_to_hide) = shift;
+ $thing_to_hide =~ tr/\000-\177/\200-\377/;
+ return $thing_to_hide;
+}
+
+sub init_noremap {
+ if ( /[\200-\377]/ ) {
+ warn "hit bit char in input stream";
+ }
+}
+
+sub clear_noremap {
+ my $ready_to_print = $_[0];
+
+ tr/\200-\377/\000-\177/;
+
+ # trofficate backslashes
+ # s/(?!\\e)(?:..|^.|^)\\/\\e/g;
+
+ # now for the E<>s, which have been hidden until now
+ # otherwise the interative \w<> processing would have
+ # been hosed by the E<gt>
+ s {
+ E<
+ ( [A-Za-z]+ )
+ >
+ } {
+ do {
+ exists $HTML_Escapes{$1}
+ ? do { $HTML_Escapes{$1} }
+ : do {
+ warn "Unknown escape: $& in $_";
+ "E<$1>";
+ }
+ }
+ }egx if $ready_to_print;
+}
+
+sub internal_lrefs {
+ local($_) = shift;
+
+ s{L</([^>]+)>}{$1}g;
+ my(@items) = split( /(?:,?\s+(?:and\s+)?)/ );
+ my $retstr = "the ";
+ my $i;
+ for ($i = 0; $i <= $#items; $i++) {
+ $retstr .= "C<$items[$i]>";
+ $retstr .= ", " if @items > 2 && $i != $#items;
+ $retstr .= " and " if $i+2 == @items;
+ }
+
+ $retstr .= " entr" . ( @items > 1 ? "ies" : "y" )
+ . " elsewhere in this document";
+
+ return $retstr;
+
+}
+
+BEGIN {
+%HTML_Escapes = (
+ 'amp' => '&', # ampersand
+ 'lt' => '<', # left chevron, less-than
+ 'gt' => '>', # right chevron, greater-than
+ 'quot' => '"', # double quote
+
+ "Aacute" => "A\\*'", # capital A, acute accent
+ "aacute" => "a\\*'", # small a, acute accent
+ "Acirc" => "A\\*^", # capital A, circumflex accent
+ "acirc" => "a\\*^", # small a, circumflex accent
+ "AElig" => '\*(AE', # capital AE diphthong (ligature)
+ "aelig" => '\*(ae', # small ae diphthong (ligature)
+ "Agrave" => "A\\*`", # capital A, grave accent
+ "agrave" => "A\\*`", # small a, grave accent
+ "Aring" => 'A\\*o', # capital A, ring
+ "aring" => 'a\\*o', # small a, ring
+ "Atilde" => 'A\\*~', # capital A, tilde
+ "atilde" => 'a\\*~', # small a, tilde
+ "Auml" => 'A\\*:', # capital A, dieresis or umlaut mark
+ "auml" => 'a\\*:', # small a, dieresis or umlaut mark
+ "Ccedil" => 'C\\*,', # capital C, cedilla
+ "ccedil" => 'c\\*,', # small c, cedilla
+ "Eacute" => "E\\*'", # capital E, acute accent
+ "eacute" => "e\\*'", # small e, acute accent
+ "Ecirc" => "E\\*^", # capital E, circumflex accent
+ "ecirc" => "e\\*^", # small e, circumflex accent
+ "Egrave" => "E\\*`", # capital E, grave accent
+ "egrave" => "e\\*`", # small e, grave accent
+ "ETH" => '\\*(D-', # capital Eth, Icelandic
+ "eth" => '\\*(d-', # small eth, Icelandic
+ "Euml" => "E\\*:", # capital E, dieresis or umlaut mark
+ "euml" => "e\\*:", # small e, dieresis or umlaut mark
+ "Iacute" => "I\\*'", # capital I, acute accent
+ "iacute" => "i\\*'", # small i, acute accent
+ "Icirc" => "I\\*^", # capital I, circumflex accent
+ "icirc" => "i\\*^", # small i, circumflex accent
+ "Igrave" => "I\\*`", # capital I, grave accent
+ "igrave" => "i\\*`", # small i, grave accent
+ "Iuml" => "I\\*:", # capital I, dieresis or umlaut mark
+ "iuml" => "i\\*:", # small i, dieresis or umlaut mark
+ "Ntilde" => 'N\*~', # capital N, tilde
+ "ntilde" => 'n\*~', # small n, tilde
+ "Oacute" => "O\\*'", # capital O, acute accent
+ "oacute" => "o\\*'", # small o, acute accent
+ "Ocirc" => "O\\*^", # capital O, circumflex accent
+ "ocirc" => "o\\*^", # small o, circumflex accent
+ "Ograve" => "O\\*`", # capital O, grave accent
+ "ograve" => "o\\*`", # small o, grave accent
+ "Oslash" => "O\\*/", # capital O, slash
+ "oslash" => "o\\*/", # small o, slash
+ "Otilde" => "O\\*~", # capital O, tilde
+ "otilde" => "o\\*~", # small o, tilde
+ "Ouml" => "O\\*:", # capital O, dieresis or umlaut mark
+ "ouml" => "o\\*:", # small o, dieresis or umlaut mark
+ "szlig" => '\*8', # small sharp s, German (sz ligature)
+ "THORN" => '\\*(Th', # capital THORN, Icelandic
+ "thorn" => '\\*(th',, # small thorn, Icelandic
+ "Uacute" => "U\\*'", # capital U, acute accent
+ "uacute" => "u\\*'", # small u, acute accent
+ "Ucirc" => "U\\*^", # capital U, circumflex accent
+ "ucirc" => "u\\*^", # small u, circumflex accent
+ "Ugrave" => "U\\*`", # capital U, grave accent
+ "ugrave" => "u\\*`", # small u, grave accent
+ "Uuml" => "U\\*:", # capital U, dieresis or umlaut mark
+ "uuml" => "u\\*:", # small u, dieresis or umlaut mark
+ "Yacute" => "Y\\*'", # capital Y, acute accent
+ "yacute" => "y\\*'", # small y, acute accent
+ "yuml" => "y\\*:", # small y, dieresis or umlaut mark
+);
+}
diff --git a/pod/splitman b/pod/splitman
new file mode 100755
index 0000000000..9fe404a061
--- /dev/null
+++ b/pod/splitman
@@ -0,0 +1,46 @@
+#!/usr/bin/perl
+
+while (<>) {
+ if ($seqno = 1 .. /^\.TH/) {
+ unless ($seqno =~ /e/i) {
+ $header .= $_;
+ }
+ next;
+ }
+
+ if ( /^\.Ip\s*"(.*)"\s*\d+$/) {
+ $desking = 0;
+ $desc = $1;
+ if (name($desc) ne $myname) {
+ $myname = name($desc);
+ print $myname, "\n";
+ open(MAN, "> $myname.3pl");
+ print MAN <<EOALL;
+$header
+.TH $myname 3PL "\\*(RP"
+.SH NAME
+$myname
+.SH SYNOPSIS
+.B $desc
+EOALL
+ } else {
+ print MAN <<EOMORE;
+.br
+.ti +3n
+or
+.br
+.B $desc
+EOMORE
+ }
+ next;
+ }
+ unless ($desking) {
+ print MAN ".SH DESCRIPTION\n";
+ $desking = 1;
+ }
+ print MAN;
+}
+
+sub name {
+ ($_[0] =~ /(\w+)/)[0];
+}