This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
https://perl5.git.perl.org / perl5.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
AW: question on "len item/string item" with unpack()
[perl5.git] / pod / perlfunc.pod
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 2d6c40c..73cde05 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1,4 +1,5 @@
 =head1 NAME
 =head1 NAME
+X<function>
 
 perlfunc - Perl builtin functions
 
 
 perlfunc - Perl builtin functions
 
@@ -68,6 +69,7 @@ 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.
 last value in the list.  Some operators return a count of successful
 operations.  In general, they do what you want, unless you want
 consistency.
+X<context>
 
 A named array in scalar context is quite different from what would at
 first glance appear to be a list in scalar context.  You can't get a list
 
 A named array in scalar context is quite different from what would at
 first glance appear to be a list in scalar context.  You can't get a list
@@ -85,6 +87,7 @@ C<waitpid>, and C<syscall>.  System calls also set the special C<$!>
 variable on failure.  Other functions do not, except accidentally.
 
 =head2 Perl Functions by Category
 variable on failure.  Other functions do not, except accidentally.
 
 =head2 Perl Functions by Category
+X<function>
 
 Here are Perl's functions (including things that look like
 functions, like some keywords and named operators)
 
 Here are Perl's functions (including things that look like
 functions, like some keywords and named operators)
@@ -94,37 +97,44 @@ than one place.
 =over 4
 
 =item Functions for SCALARs or strings
 =over 4
 
 =item Functions for SCALARs or strings
+X<scalar> X<string> X<character>
 
 C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
 C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
 C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
 
 =item Regular expressions and pattern matching
 
 C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
 C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
 C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
 
 =item Regular expressions and pattern matching
+X<regular expression> X<regex> X<regexp>
 
 C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
 
 =item Numeric functions
 
 C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
 
 =item Numeric functions
+X<numeric> X<number> X<trigonometric> X<trigonometry>
 
 C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
 C<sin>, C<sqrt>, C<srand>
 
 =item Functions for real @ARRAYs
 
 C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
 C<sin>, C<sqrt>, C<srand>
 
 =item Functions for real @ARRAYs
+X<array>
 
 C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
 
 =item Functions for list data
 
 C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
 
 =item Functions for list data
+X<list>
 
 C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
 
 =item Functions for real %HASHes
 
 C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
 
 =item Functions for real %HASHes
+X<hash>
 
 C<delete>, C<each>, C<exists>, C<keys>, C<values>
 
 =item Input and output functions
 
 C<delete>, C<each>, C<exists>, C<keys>, C<values>
 
 =item Input and output functions
+X<I/O> X<input> X<output> X<dbm>
 
 C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
 C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
 
 C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
 C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
-C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
+C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
 C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
 C<warn>, C<write>
 
 C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
 C<warn>, C<write>
 
@@ -133,6 +143,7 @@ C<warn>, C<write>
 C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 =item Functions for filehandles, files, or directories
 C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 =item Functions for filehandles, files, or directories
+X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
@@ -140,10 +151,18 @@ C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
 C<umask>, C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your Perl program
 C<umask>, C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your Perl program
+X<control flow>
 
 C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
 C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
 
 C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
 C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
+=item Keywords related to switch
+
+C<break>, C<continue>
+
+(These are only available if you enable the "switch" feature.
+See L<feature> and L<perlsyn/"Switch statements">.)
+
 =item Keywords related to scoping
 
 C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
 =item Keywords related to scoping
 
 C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
@@ -154,38 +173,45 @@ C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
 C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
 C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
+X<process> X<pid> X<process id>
 
 C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
 C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
 C<times>, C<wait>, C<waitpid>
 
 =item Keywords related to perl modules
 
 C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
 C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
 C<times>, C<wait>, C<waitpid>
 
 =item Keywords related to perl modules
+X<module>
 
 C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
 
 =item Keywords related to classes and object-orientedness
 
 C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
 
 =item Keywords related to classes and object-orientedness
+X<object> X<class> X<package>
 
 C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
 C<untie>, C<use>
 
 =item Low-level socket functions
 
 C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
 C<untie>, C<use>
 
 =item Low-level socket functions
+X<socket> X<sock>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
 C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
 C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
+X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
 
 C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
 C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
 
 =item Fetching user and group info
 
 C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
 C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
 
 =item Fetching user and group info
+X<user> X<group> X<password> X<uid> X<gid>  X<passwd> X</etc/passwd>
 
 C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
 C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
 C<getpwuid>, C<setgrent>, C<setpwent>
 
 =item Fetching network info
 
 C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
 C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
 C<getpwuid>, C<setgrent>, C<setpwent>
 
 =item Fetching network info
+X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
 
 C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
 C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
 
 C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
 C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
@@ -194,15 +220,17 @@ C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
 C<setnetent>, C<setprotoent>, C<setservent>
 
 =item Time-related functions
 C<setnetent>, C<setprotoent>, C<setservent>
 
 =item Time-related functions
+X<time> X<date>
 
 C<gmtime>, C<localtime>, C<time>, C<times>
 
 =item Functions new in perl5
 
 C<gmtime>, C<localtime>, C<time>, C<times>
 
 =item Functions new in perl5
+X<perl5>
 
 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
 
 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
-C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
-C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
-C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
+C<import>, C<lc>, C<lcfirst>, C<lock>, C<map>, C<my>, C<no>, C<our>,
+C<prototype>, C<qr>, C<qw>, C<qx>, C<readline>, C<readpipe>, C<ref>,
+C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
 operator, which can be used in expressions.
 
 * - C<sub> was a keyword in perl4, but in perl5 it is an
 operator, which can be used in expressions.
@@ -214,6 +242,7 @@ C<dbmclose>, C<dbmopen>
 =back
 
 =head2 Portability
 =back
 
 =head2 Portability
+X<portability> X<Unix> X<portable>
 
 Perl was born in Unix and can therefore access all common Unix
 system calls.  In non-Unix environments, the functionality of some
 
 Perl was born in Unix and can therefore access all common Unix
 system calls.  In non-Unix environments, the functionality of some
@@ -247,6 +276,8 @@ L<perlport> and other available platform-specific documentation.
 =over 8
 
 =item -X FILEHANDLE
 =over 8
 
 =item -X FILEHANDLE
+X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
+X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
 =item -X EXPR
 
 
 =item -X EXPR
 
@@ -261,8 +292,6 @@ 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:
 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:
-X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
-X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
     -r File is readable by effective uid/gid.
     -w File is writable by effective uid/gid.
 
     -r File is readable by effective uid/gid.
     -w File is writable by effective uid/gid.
@@ -373,6 +402,7 @@ the return value of C<-f $file> as an argument to another filetest
 operator, no special magic will happen.)
 
 =item abs VALUE
 operator, no special magic will happen.)
 
 =item abs VALUE
+X<abs> X<absolute>
 
 =item abs
 
 
 =item abs
 
@@ -380,6 +410,7 @@ Returns the absolute value of its argument.
 If VALUE is omitted, uses C<$_>.
 
 =item accept NEWSOCKET,GENERICSOCKET
 If VALUE is omitted, uses C<$_>.
 
 =item accept NEWSOCKET,GENERICSOCKET
+X<accept>
 
 Accepts an incoming socket connect, just as the accept(2) system call
 does.  Returns the packed address if it succeeded, false otherwise.
 
 Accepts an incoming socket connect, just as the accept(2) system call
 does.  Returns the packed address if it succeeded, false otherwise.
@@ -390,6 +421,9 @@ be set for the newly opened file descriptor, as determined by the
 value of $^F.  See L<perlvar/$^F>.
 
 =item alarm SECONDS
 value of $^F.  See L<perlvar/$^F>.
 
 =item alarm SECONDS
+X<alarm>
+X<SIGALRM>
+X<timer>
 
 =item alarm
 
 
 =item alarm
 
@@ -438,6 +472,7 @@ modulo the caveats given in L<perlipc/"Signals">.
 For more information see L<perlipc>.
 
 =item atan2 Y,X
 For more information see L<perlipc>.
 
 =item atan2 Y,X
+X<atan2> X<arctangent> X<tan> X<tangent>
 
 Returns the arctangent of Y/X in the range -PI to PI.
 
 
 Returns the arctangent of Y/X in the range -PI to PI.
 
@@ -449,6 +484,7 @@ function, or use the familiar relation:
 Note that atan2(0, 0) is not well-defined.
 
 =item bind SOCKET,NAME
 Note that atan2(0, 0) is not well-defined.
 
 =item bind SOCKET,NAME
+X<bind>
 
 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
 
 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
@@ -456,6 +492,7 @@ packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE, LAYER
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE, LAYER
+X<binmode> X<binary> X<text> X<DOS> X<Windows>
 
 =item binmode FILEHANDLE
 
 
 =item binmode FILEHANDLE
 
@@ -542,6 +579,7 @@ in L<perlvar> for how to manually set your input and output
 line-termination sequences.
 
 =item bless REF,CLASSNAME
 line-termination sequences.
 
 =item bless REF,CLASSNAME
+X<bless>
 
 =item bless REF
 
 
 =item bless REF
 
@@ -561,7 +599,15 @@ that CLASSNAME is a true value.
 
 See L<perlmod/"Perl Modules">.
 
 
 See L<perlmod/"Perl Modules">.
 
+=item break
+
+Break out of a C<given()> block.
+
+This keyword is enabled by the "switch" feature: see L<feature>
+for more information.
+
 =item caller EXPR
 =item caller EXPR
+X<caller> X<call stack> X<stack> X<stack trace>
 
 =item caller
 
 
 =item caller
 
@@ -577,7 +623,8 @@ print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
     ($package, $filename, $line, $subroutine, $hasargs,
 to go back before the current one.
 
     ($package, $filename, $line, $subroutine, $hasargs,
-    $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
+    $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
+        = caller($i);
 
 Here $subroutine may be C<(eval)> if the frame is not a subroutine
 call, but an C<eval>.  In such a case additional elements $evaltext and
 
 Here $subroutine may be C<(eval)> if the frame is not a subroutine
 call, but an C<eval>.  In such a case additional elements $evaltext and
@@ -593,6 +640,10 @@ C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
 compiled with.  The C<$hints> and C<$bitmask> values are subject to change
 between versions of Perl, and are not meant for external use.
 
 compiled with.  The C<$hints> and C<$bitmask> values are subject to change
 between versions of Perl, and are not meant for external use.
 
+C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
+caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
+of this hash, as they are the actual values stored in the optree.
+
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
 arguments with which the subroutine was invoked.
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable C<@DB::args> to be the
 arguments with which the subroutine was invoked.
@@ -604,6 +655,8 @@ C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 previous time C<caller> was called.
 
 =item chdir EXPR
 previous time C<caller> was called.
 
 =item chdir EXPR
+X<chdir>
+X<cd>
 
 =item chdir FILEHANDLE
 
 
 =item chdir FILEHANDLE
 
@@ -623,6 +676,7 @@ directory handle as argument.  On systems that don't support fchdir,
 passing handles produces a fatal error at run time.
 
 =item chmod LIST
 passing handles produces a fatal error at run time.
 
 =item chmod LIST
+X<chmod> X<permission> X<mode>
 
 Changes the permissions of a list of files.  The first element of the
 list must be the numerical mode, which should probably be an octal
 
 Changes the permissions of a list of files.  The first element of the
 list must be the numerical mode, which should probably be an octal
@@ -639,7 +693,9 @@ successfully changed.  See also L</oct>, if all you have is a string.
 
 On systems that support fchmod, you might pass file handles among the
 files.  On systems that don't support fchmod, passing file handles
 
 On systems that support fchmod, you might pass file handles among the
 files.  On systems that don't support fchmod, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time.   The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
 
     open(my $fh, "<", "foo");
     my $perm = (stat $fh)[2] & 07777;
 
     open(my $fh, "<", "foo");
     my $perm = (stat $fh)[2] & 07777;
@@ -654,6 +710,7 @@ module:
     # This is identical to the chmod 0755 of the above example.
 
 =item chomp VARIABLE
     # This is identical to the chmod 0755 of the above example.
 
 =item chomp VARIABLE
+X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
 
 =item chomp( LIST )
 
 
 =item chomp( LIST )
 
@@ -699,6 +756,7 @@ C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
 as C<chomp($a, $b)>.
 
 =item chop VARIABLE
 as C<chomp($a, $b)>.
 
 =item chop VARIABLE
+X<chop>
 
 =item chop( LIST )
 
 
 =item chop( LIST )
 
@@ -720,6 +778,7 @@ character, use C<substr($string, 0, -1)>.
 See also L</chomp>.
 
 =item chown LIST
 See also L</chomp>.
 
 =item chown LIST
+X<chown> X<owner> X<user> X<group>
 
 Changes the owner (and group) of a list of files.  The first two
 elements of the list must be the I<numeric> uid and gid, in that
 
 Changes the owner (and group) of a list of files.  The first two
 elements of the list must be the I<numeric> uid and gid, in that
@@ -732,7 +791,9 @@ successfully changed.
 
 On systems that support fchown, you might pass file handles among the
 files.  On systems that don't support fchown, passing file handles
 
 On systems that support fchown, you might pass file handles among the
 files.  On systems that don't support fchown, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time.  The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
 
 Here's an example that looks up nonnumeric uids in the passwd file:
 
 
 Here's an example that looks up nonnumeric uids in the passwd file:
 
@@ -757,6 +818,7 @@ On POSIX systems, you can detect this condition this way:
     $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
 
 =item chr NUMBER
     $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
 
 =item chr NUMBER
+X<chr> X<character> X<ASCII> X<Unicode>
 
 =item chr
 
 
 =item chr
 
@@ -767,7 +829,7 @@ to 255 (inclusive) are by default not encoded in UTF-8 Unicode for
 backward compatibility reasons (but see L<encoding>).
 
 Negative values give the Unicode replacement character (chr(0xfffd)),
 backward compatibility reasons (but see L<encoding>).
 
 Negative values give the Unicode replacement character (chr(0xfffd)),
-except under the L</bytes> pragma, where low eight bits of the value
+except under the L<bytes> pragma, where low eight bits of the value
 (truncated to an integer) are used.
 
 If NUMBER is omitted, uses C<$_>.
 (truncated to an integer) are used.
 
 If NUMBER is omitted, uses C<$_>.
@@ -780,6 +842,7 @@ the low eight bits.
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item chroot FILENAME
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item chroot FILENAME
+X<chroot> X<root>
 
 =item chroot
 
 
 =item chroot
 
@@ -791,6 +854,7 @@ reasons, this call is restricted to the superuser.  If FILENAME is
 omitted, does a C<chroot> to C<$_>.
 
 =item close FILEHANDLE
 omitted, does a C<chroot> to C<$_>.
 
 =item close FILEHANDLE
+X<close>
 
 =item close
 
 
 =item close
 
@@ -833,11 +897,13 @@ FILEHANDLE may be an expression whose value can be used as an indirect
 filehandle, usually the real filehandle name.
 
 =item closedir DIRHANDLE
 filehandle, usually the real filehandle name.
 
 =item closedir DIRHANDLE
+X<closedir>
 
 Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
 =item connect SOCKET,NAME
 
 Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
 =item connect SOCKET,NAME
+X<connect>
 
 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
 
 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
@@ -845,6 +911,9 @@ packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item continue BLOCK
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item continue BLOCK
+X<continue>
+
+=item continue
 
 C<continue> is actually a flow control statement rather than a function.  If
 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
 
 C<continue> is actually a flow control statement rather than a function.  If
 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
@@ -873,7 +942,14 @@ Omitting the C<continue> section is semantically equivalent to using an
 empty one, logically enough.  In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
 empty one, logically enough.  In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
+If the "switch" feature is enabled, C<continue> is also a
+function that will break out of the current C<when> or C<default>
+block, and fall through to the next case. See L<feature> and
+L<perlsyn/"Switch statements"> for more information.
+
+
 =item cos EXPR
 =item cos EXPR
+X<cos> X<cosine> X<acos> X<arccosine>
 
 =item cos
 
 
 =item cos
 
@@ -886,6 +962,8 @@ function, or use this relation:
     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
 
 =item crypt PLAINTEXT,SALT
     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
 
 =item crypt PLAINTEXT,SALT
+X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
+X<decrypt> X<cryptography> X<passwd>
 
 Creates a digest string exactly like the crypt(3) function in the C
 library (assuming that you actually have a version there that has not
 
 Creates a digest string exactly like the crypt(3) function in the C
 library (assuming that you actually have a version there that has not
@@ -963,12 +1041,14 @@ the string back to an eight-bit byte string before calling crypt()
 C<Wide character in crypt>.
 
 =item dbmclose HASH
 C<Wide character in crypt>.
 
 =item dbmclose HASH
+X<dbmclose>
 
 [This function has been largely superseded by the C<untie> function.]
 
 Breaks the binding between a DBM file and a hash.
 
 =item dbmopen HASH,DBNAME,MASK
 
 [This function has been largely superseded by the C<untie> function.]
 
 Breaks the binding between a DBM file and a hash.
 
 =item dbmopen HASH,DBNAME,MASK
+X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
 
 [This function has been largely superseded by the C<tie> function.]
 
 
 [This function has been largely superseded by the C<tie> function.]
 
@@ -1011,6 +1091,7 @@ before you call dbmopen():
        or die "Can't open netscape history file: $!";
 
 =item defined EXPR
        or die "Can't open netscape history file: $!";
 
 =item defined EXPR
+X<defined> X<undef> X<undefined>
 
 =item defined
 
 
 =item defined
 
@@ -1074,6 +1155,7 @@ what you want.
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
+X<delete>
 
 Given an expression that specifies a hash element, array element, hash slice,
 or array slice, deletes the specified element(s) from the hash or array.
 
 Given an expression that specifies a hash element, array element, hash slice,
 or array slice, deletes the specified element(s) from the hash or array.
@@ -1138,6 +1220,7 @@ lookup:
     delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
 
 =item die LIST
     delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
 
 =item die LIST
+X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
 
 Outside an C<eval>, prints the value of LIST to C<STDERR> and
 exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
 
 Outside an C<eval>, prints the value of LIST to C<STDERR> and
 exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
@@ -1229,6 +1312,7 @@ this promotes strange action at a distance, this counterintuitive
 behavior may be fixed in a future release.
 
 =item do BLOCK
 behavior may be fixed in a future release.
 
 =item do BLOCK
+X<do> X<block>
 
 Not really a function.  Returns the value of the last command in the
 sequence of commands indicated by BLOCK.  When modified by the C<while> or
 
 Not really a function.  Returns the value of the last command in the
 sequence of commands indicated by BLOCK.  When modified by the C<while> or
@@ -1241,10 +1325,12 @@ C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
 See L<perlsyn> for alternative strategies.
 
 =item do SUBROUTINE(LIST)
 See L<perlsyn> for alternative strategies.
 
 =item do SUBROUTINE(LIST)
+X<do>
 
 This form of subroutine call is deprecated.  See L<perlsub>.
 
 =item do EXPR
 
 This form of subroutine call is deprecated.  See L<perlsub>.
 
 =item do EXPR
+X<do>
 
 Uses the value of EXPR as a filename and executes the contents of the
 file as a Perl script.
 
 Uses the value of EXPR as a filename and executes the contents of the
 file as a Perl script.
@@ -1288,6 +1374,7 @@ file.  Manual error checking can be done this way:
     }
 
 =item dump LABEL
     }
 
 =item dump LABEL
+X<dump> X<core> X<undump>
 
 =item dump
 
 
 =item dump
 
@@ -1320,6 +1407,7 @@ You might also consider autoloading or selfloading, which at least
 make your program I<appear> to run faster.
 
 =item each HASH
 make your program I<appear> to run faster.
 
 =item each HASH
+X<each> X<hash, iterator>
 
 When called in list context, returns a 2-element list consisting of the
 key and value for the next element of a hash, so that you can iterate over
 
 When called in list context, returns a 2-element list consisting of the
 key and value for the next element of a hash, so that you can iterate over
@@ -1359,6 +1447,9 @@ only in a different order:
 See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE
 See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE
+X<eof>
+X<end of file>
+X<end-of-file>
 
 =item eof ()
 
 
 =item eof ()
 
@@ -1409,6 +1500,7 @@ input operators typically return C<undef> when they run out of data, or if
 there was an error.
 
 =item eval EXPR
 there was an error.
 
 =item eval EXPR
+X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
 
 =item eval BLOCK
 
 
 =item eval BLOCK
 
@@ -1527,6 +1619,7 @@ scope of the first non-DB piece of code that called it. You don't normally
 need to worry about this unless you are writing a Perl debugger.
 
 =item exec LIST
 need to worry about this unless you are writing a Perl debugger.
 
 =item exec LIST
+X<exec> X<execute>
 
 =item exec PROGRAM LIST
 
 
 =item exec PROGRAM LIST
 
@@ -1602,6 +1695,7 @@ Note that C<exec> will not call your C<END> blocks, nor will it call
 any C<DESTROY> methods in your objects.
 
 =item exists EXPR
 any C<DESTROY> methods in your objects.
 
 =item exists EXPR
+X<exists> X<autovivification>
 
 Given an expression that specifies a hash element or array element,
 returns true if the specified element in the hash or array has ever
 
 Given an expression that specifies a hash element or array element,
 returns true if the specified element in the hash or array has ever
@@ -1662,6 +1756,7 @@ to exists() is an error.
     exists &sub();     # Error
 
 =item exit EXPR
     exists &sub();     # Error
 
 =item exit EXPR
+X<exit> X<terminate> X<abort>
 
 =item exit
 
 
 =item exit
 
@@ -1689,6 +1784,7 @@ can call C<POSIX:_exit($status)> to avoid END and destructor processing.
 See L<perlmod> for details.
 
 =item exp EXPR
 See L<perlmod> for details.
 
 =item exp EXPR
+X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
 
 =item exp
 
 
 =item exp
 
@@ -1696,6 +1792,7 @@ Returns I<e> (the natural logarithm base) to the power of EXPR.
 If EXPR is omitted, gives C<exp($_)>.
 
 =item fcntl FILEHANDLE,FUNCTION,SCALAR
 If EXPR is omitted, gives C<exp($_)>.
 
 =item fcntl FILEHANDLE,FUNCTION,SCALAR
+X<fcntl>
 
 Implements the fcntl(2) function.  You'll probably have to say
 
 
 Implements the fcntl(2) function.  You'll probably have to say
 
@@ -1732,6 +1829,7 @@ on your own, though.
                 or die "Can't set flags for the socket: $!\n";
 
 =item fileno FILEHANDLE
                 or die "Can't set flags for the socket: $!\n";
 
 =item fileno FILEHANDLE
+X<fileno>
 
 Returns the file descriptor for a filehandle, or undefined if the
 filehandle is not open.  This is mainly useful for constructing
 
 Returns the file descriptor for a filehandle, or undefined if the
 filehandle is not open.  This is mainly useful for constructing
@@ -1751,6 +1849,7 @@ return undefined even though they are open.)
 
 
 =item flock FILEHANDLE,OPERATION
 
 
 =item flock FILEHANDLE,OPERATION
+X<flock> X<lock> X<locking>
 
 Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
 for success, false on failure.  Produces a fatal error if used on a
 
 Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
 for success, false on failure.  Produces a fatal error if used on a
@@ -1828,6 +1927,7 @@ function lose the locks, making it harder to write servers.
 See also L<DB_File> for other flock() examples.
 
 =item fork
 See also L<DB_File> for other flock() examples.
 
 =item fork
+X<fork> X<child> X<parent>
 
 Does a fork(2) system call to create a new process running the
 same program at the same point.  It returns the child pid to the
 
 Does a fork(2) system call to create a new process running the
 same program at the same point.  It returns the child pid to the
@@ -1856,6 +1956,7 @@ backgrounded job launched from a remote shell) won't think you're done.
 You should reopen those to F</dev/null> if it's any issue.
 
 =item format
 You should reopen those to F</dev/null> if it's any issue.
 
 =item format
+X<format>
 
 Declare a picture format for use by the C<write> function.  For
 example:
 
 Declare a picture format for use by the C<write> function.  For
 example:
@@ -1873,6 +1974,7 @@ example:
 See L<perlform> for many details and examples.
 
 =item formline PICTURE,LIST
 See L<perlform> for many details and examples.
 
 =item formline PICTURE,LIST
+X<formline>
 
 This is an internal function used by C<format>s, though you may call it,
 too.  It formats (see L<perlform>) a list of values according to the
 
 This is an internal function used by C<format>s, though you may call it,
 too.  It formats (see L<perlform>) a list of values according to the
@@ -1892,6 +1994,7 @@ character may be taken to mean the beginning of an array name.
 C<formline> always returns true.  See L<perlform> for other examples.
 
 =item getc FILEHANDLE
 C<formline> always returns true.  See L<perlform> for other examples.
 
 =item getc FILEHANDLE
+X<getc> X<getchar>
 
 =item getc
 
 
 =item getc
 
@@ -1928,6 +2031,7 @@ module from your nearest CPAN site; details on CPAN can be found on
 L<perlmodlib/CPAN>.
 
 =item getlogin
 L<perlmodlib/CPAN>.
 
 =item getlogin
+X<getlogin> X<login>
 
 This implements the C library function of the same name, which on most
 systems returns the current login from F</etc/utmp>, if any.  If null,
 
 This implements the C library function of the same name, which on most
 systems returns the current login from F</etc/utmp>, if any.  If null,
@@ -1939,6 +2043,7 @@ Do not consider C<getlogin> for authentication: it is not as
 secure as C<getpwuid>.
 
 =item getpeername SOCKET
 secure as C<getpwuid>.
 
 =item getpeername SOCKET
+X<getpeername> X<peer>
 
 Returns the packed sockaddr address of other end of the SOCKET connection.
 
 
 Returns the packed sockaddr address of other end of the SOCKET connection.
 
@@ -1949,6 +2054,7 @@ Returns the packed sockaddr address of other end of the SOCKET connection.
     $herstraddr     = inet_ntoa($iaddr);
 
 =item getpgrp PID
     $herstraddr     = inet_ntoa($iaddr);
 
 =item getpgrp PID
+X<getpgrp> X<group>
 
 Returns the current process group for the specified PID.  Use
 a PID of C<0> to get the current process group for the
 
 Returns the current process group for the specified PID.  Use
 a PID of C<0> to get the current process group for the
@@ -1958,6 +2064,7 @@ group of current process.  Note that the POSIX version of C<getpgrp>
 does not accept a PID argument, so only C<PID==0> is truly portable.
 
 =item getppid
 does not accept a PID argument, so only C<PID==0> is truly portable.
 
 =item getppid
+X<getppid> X<parent> X<pid>
 
 Returns the process id of the parent process.
 
 
 Returns the process id of the parent process.
 
@@ -1969,12 +2076,19 @@ to call the underlying C<getppid()>, you may use the CPAN module
 C<Linux::Pid>.
 
 =item getpriority WHICH,WHO
 C<Linux::Pid>.
 
 =item getpriority WHICH,WHO
+X<getpriority> X<priority> X<nice>
 
 Returns the current priority for a process, a process group, or a user.
 (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
 machine that doesn't implement getpriority(2).
 
 =item getpwnam NAME
 
 Returns the current priority for a process, a process group, or a user.
 (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
 machine that doesn't implement getpriority(2).
 
 =item getpwnam NAME
+X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
+X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
+X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
+X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
+X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
+X<endnetent> X<endprotoent> X<endservent> 
 
 =item getgrnam NAME
 
 
 =item getgrnam NAME
 
@@ -2128,6 +2242,7 @@ they aren't, because a C<File::stat> object is different from
 a C<User::pwent> object.
 
 =item getsockname SOCKET
 a C<User::pwent> object.
 
 =item getsockname SOCKET
+X<getsockname>
 
 Returns the packed sockaddr address of this end of the SOCKET connection,
 in case you don't know the address because you have several different
 
 Returns the packed sockaddr address of this end of the SOCKET connection,
 in case you don't know the address because you have several different
@@ -2141,6 +2256,7 @@ IPs that the connection might have come in on.
        inet_ntoa($myaddr);
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
        inet_ntoa($myaddr);
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
+X<getsockopt>
 
 Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
 Options may exist at multiple protocol levels depending on the socket
 
 Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
 Options may exist at multiple protocol levels depending on the socket
@@ -2172,6 +2288,7 @@ An example testing if Nagle's algorithm is turned on on a socket:
 
 
 =item glob EXPR
 
 
 =item glob EXPR
+X<glob> X<wildcard> X<filename, expansion> X<expand>
 
 =item glob
 
 
 =item glob
 
@@ -2187,15 +2304,16 @@ Beginning with v5.6.0, this operator is implemented using the standard
 C<File::Glob> extension.  See L<File::Glob> for details.
 
 =item gmtime EXPR
 C<File::Glob> extension.  See L<File::Glob> for details.
 
 =item gmtime EXPR
+X<gmtime> X<UTC> X<Greenwich>
 
 =item gmtime
 
 
 =item gmtime
 
-Converts a time as returned by the time function to an 8-element list
+Converts a time as returned by the time function to an 9-element list
 with the time localized for the standard Greenwich time zone.
 Typically used as follows:
 
 with the time localized for the standard Greenwich time zone.
 Typically used as follows:
 
-    #  0    1    2     3     4    5     6     7
-    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
+    #  0    1    2     3     4    5     6     7     8
+    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                            gmtime(time);
 
 All list elements are numeric, and come straight out of the C `struct
                                            gmtime(time);
 
 All list elements are numeric, and come straight out of the C `struct
@@ -2205,7 +2323,8 @@ itself, in the range C<0..11> with 0 indicating January and 11
 indicating December.  $year is the number of years since 1900.  That
 is, $year is C<123> in year 2023.  $wday is the day of the week, with
 0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
 indicating December.  $year is the number of years since 1900.  That
 is, $year is C<123> in year 2023.  $wday is the day of the week, with
 0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
-the year, in the range C<0..364> (or C<0..365> in leap years.)
+the year, in the range C<0..364> (or C<0..365> in leap years).  $isdst
+is always C<0>.
 
 Note that the $year element is I<not> simply the last two digits of
 the year.  If you assume it is then you create non-Y2K-compliant
 
 Note that the $year element is I<not> simply the last two digits of
 the year.  If you assume it is then you create non-Y2K-compliant
@@ -2236,6 +2355,7 @@ strings, see the example in L</localtime>.
 See L<perlport/gmtime> for portability concerns.
 
 =item goto LABEL
 See L<perlport/gmtime> for portability concerns.
 
 =item goto LABEL
+X<goto> X<jump> X<jmp>
 
 =item goto EXPR
 
 
 =item goto EXPR
 
@@ -2277,6 +2397,7 @@ containing a code reference, or a block that evaluates to a code
 reference.
 
 =item grep BLOCK LIST
 reference.
 
 =item grep BLOCK LIST
+X<grep>
 
 =item grep EXPR,LIST
 
 
 =item grep EXPR,LIST
 
@@ -2311,6 +2432,7 @@ can't be seen from the outside, avoiding any potential side-effects.
 See also L</map> for a list composed of the results of the BLOCK or EXPR.
 
 =item hex EXPR
 See also L</map> for a list composed of the results of the BLOCK or EXPR.
 
 =item hex EXPR
+X<hex> X<hexadecimal>
 
 =item hex
 
 
 =item hex
 
@@ -2327,6 +2449,7 @@ unlike oct(). To present something as hex, look into L</printf>,
 L</sprintf>, or L</unpack>.
 
 =item import LIST
 L</sprintf>, or L</unpack>.
 
 =item import LIST
+X<import>
 
 There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
 
 There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
@@ -2334,6 +2457,7 @@ names to another module.  The C<use> function calls the C<import> method
 for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
 for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
+X<index> X<indexOf> X<InStr>
 
 =item index STR,SUBSTR
 
 
 =item index STR,SUBSTR
 
@@ -2348,6 +2472,7 @@ you've set the C<$[> variable to--but don't do that).  If the substring
 is not found, C<index> returns one less than the base, ordinarily C<-1>.
 
 =item int EXPR
 is not found, C<index> returns one less than the base, ordinarily C<-1>.
 
 =item int EXPR
+X<int> X<integer> X<truncate> X<trunc>
 
 =item int
 
 
 =item int
 
@@ -2361,10 +2486,11 @@ the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
 functions will serve you better than will int().
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
 functions will serve you better than will int().
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
+X<ioctl>
 
 Implements the ioctl(2) function.  You'll probably first have to say
 
 
 Implements the ioctl(2) function.  You'll probably first have to say
 
-    require "sys/ioctl.ph";    # probably in $Config{archlib}/ioctl.ph
+    require "sys/ioctl.ph";    # probably in $Config{archlib}/sys/ioctl.ph
 
 to get the correct function definitions.  If F<sys/ioctl.ph> doesn't
 exist or doesn't have the correct definitions you'll have to roll your
 
 to get the correct function definitions.  If F<sys/ioctl.ph> doesn't
 exist or doesn't have the correct definitions you'll have to roll your
@@ -2397,6 +2523,7 @@ The special string C<"0 but true"> is exempt from B<-w> complaints
 about improper numeric conversions.
 
 =item join EXPR,LIST
 about improper numeric conversions.
 
 =item join EXPR,LIST
+X<join>
 
 Joins the separate strings of LIST into a single string with fields
 separated by the value of EXPR, and returns that new string.  Example:
 
 Joins the separate strings of LIST into a single string with fields
 separated by the value of EXPR, and returns that new string.  Example:
@@ -2407,6 +2534,7 @@ Beware that unlike C<split>, C<join> doesn't take a pattern as its
 first argument.  Compare L</split>.
 
 =item keys HASH
 first argument.  Compare L</split>.
 
 =item keys HASH
+X<keys> X<key>
 
 Returns a list consisting of all the keys of the named hash.
 (In scalar context, returns the number of keys.)
 
 Returns a list consisting of all the keys of the named hash.
 (In scalar context, returns the number of keys.)
@@ -2465,6 +2593,7 @@ as trying has no effect).
 See also C<each>, C<values> and C<sort>.
 
 =item kill SIGNAL, LIST
 See also C<each>, C<values> and C<sort>.
 
 =item kill SIGNAL, LIST
+X<kill> X<signal>
 
 Sends a signal to a list of processes.  Returns the number of
 processes successfully signaled (which is not necessarily the
 
 Sends a signal to a list of processes.  Returns the number of
 processes successfully signaled (which is not necessarily the
@@ -2473,10 +2602,12 @@ same as the number actually killed).
     $cnt = kill 1, $child1, $child2;
     kill 9, @goners;
 
     $cnt = kill 1, $child1, $child2;
     kill 9, @goners;
 
-If SIGNAL is zero, no signal is sent to the process.  This is a
-useful way to check that a child process is alive and hasn't changed
-its UID.  See L<perlport> for notes on the portability of this
-construct.
+If SIGNAL is zero, no signal is sent to the process, but the kill(2)
+system call will check whether it's possible to send a signal to it (that
+means, to be brief, that the process is owned by the same user, or we are
+the super-user).  This is a useful way to check that a child process is
+alive and hasn't changed its UID.  See L<perlport> for notes on the
+portability of this construct.
 
 Unlike in the shell, if SIGNAL is negative, it kills
 process groups instead of processes.  (On System V, a negative I<PROCESS>
 
 Unlike in the shell, if SIGNAL is negative, it kills
 process groups instead of processes.  (On System V, a negative I<PROCESS>
@@ -2487,6 +2618,7 @@ use a signal name in quotes.
 See L<perlipc/"Signals"> for more details.
 
 =item last LABEL
 See L<perlipc/"Signals"> for more details.
 
 =item last LABEL
+X<last> X<break>
 
 =item last
 
 
 =item last
 
@@ -2512,6 +2644,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item lc EXPR
 C<redo> work.
 
 =item lc EXPR
+X<lc> X<lowercase>
 
 =item lc
 
 
 =item lc
 
@@ -2523,6 +2656,7 @@ and L<perlunicode> for more details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item lcfirst EXPR
 If EXPR is omitted, uses C<$_>.
 
 =item lcfirst EXPR
+X<lcfirst> X<lowercase>
 
 =item lcfirst
 
 
 =item lcfirst
 
@@ -2535,6 +2669,7 @@ details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item length EXPR
 If EXPR is omitted, uses C<$_>.
 
 =item length EXPR
+X<length> X<size>
 
 =item length
 
 
 =item length
 
@@ -2548,17 +2683,20 @@ number of characters, not the number of bytes.  To get the length
 in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
 
 =item link OLDFILE,NEWFILE
 in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
 
 =item link OLDFILE,NEWFILE
+X<link>
 
 Creates a new filename linked to the old filename.  Returns true for
 success, false otherwise.
 
 =item listen SOCKET,QUEUESIZE
 
 Creates a new filename linked to the old filename.  Returns true for
 success, false otherwise.
 
 =item listen SOCKET,QUEUESIZE
+X<listen>
 
 Does the same thing that the listen system call does.  Returns true if
 it succeeded, false otherwise.  See the example in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item local EXPR
 
 Does the same thing that the listen system call does.  Returns true if
 it succeeded, false otherwise.  See the example in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item local EXPR
+X<local>
 
 You really probably want to be using C<my> instead, because C<local> isn't
 what most people think of as "local".  See
 
 You really probably want to be using C<my> instead, because C<local> isn't
 what most people think of as "local".  See
@@ -2570,6 +2708,7 @@ be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
 for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
 for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
+X<localtime>
 
 =item localtime
 
 
 =item localtime
 
@@ -2637,6 +2776,7 @@ and the month of the year, may not necessarily be three characters wide.
 See L<perlport/localtime> for portability concerns.
 
 =item lock THING
 See L<perlport/localtime> for portability concerns.
 
 =item lock THING
+X<lock>
 
 This function places an advisory lock on a shared variable, or referenced
 object contained in I<THING> until the lock goes out of scope.
 
 This function places an advisory lock on a shared variable, or referenced
 object contained in I<THING> until the lock goes out of scope.
@@ -2647,6 +2787,7 @@ instead. (However, if you've said C<use threads>, lock() is always a
 keyword.) See L<threads>.
 
 =item log EXPR
 keyword.) See L<threads>.
 
 =item log EXPR
+X<log> X<logarithm> X<e> X<ln> X<base>
 
 =item log
 
 
 =item log
 
@@ -2663,6 +2804,7 @@ divided by the natural log of N.  For example:
 See also L</exp> for the inverse operation.
 
 =item lstat EXPR
 See also L</exp> for the inverse operation.
 
 =item lstat EXPR
+X<lstat>
 
 =item lstat
 
 
 =item lstat
 
@@ -2679,6 +2821,7 @@ If EXPR is omitted, stats C<$_>.
 The match operator.  See L<perlop>.
 
 =item map BLOCK LIST
 The match operator.  See L<perlop>.
 
 =item map BLOCK LIST
+X<map>
 
 =item map EXPR,LIST
 
 
 =item map EXPR,LIST
 
@@ -2738,6 +2881,7 @@ or to force an anon hash constructor use C<+{>
 and you get list of anonymous hashes each with only 1 entry.
 
 =item mkdir FILENAME,MASK
 and you get list of anonymous hashes each with only 1 entry.
 
 =item mkdir FILENAME,MASK
+X<mkdir> X<md> X<directory, create>
 
 =item mkdir FILENAME
 
 
 =item mkdir FILENAME
 
@@ -2762,6 +2906,7 @@ this right, so Perl automatically removes all trailing slashes to keep
 everyone happy.
 
 =item msgctl ID,CMD,ARG
 everyone happy.
 
 =item msgctl ID,CMD,ARG
+X<msgctl>
 
 Calls the System V IPC function msgctl(2).  You'll probably have to say
 
 
 Calls the System V IPC function msgctl(2).  You'll probably have to say
 
@@ -2774,12 +2919,14 @@ C<"0 but true"> for zero, or the actual return value otherwise.  See also
 L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
 
 =item msgget KEY,FLAGS
 L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
 
 =item msgget KEY,FLAGS
+X<msgget>
 
 Calls the System V IPC function msgget(2).  Returns the message queue
 id, or the undefined value if there is an error.  See also
 L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
 
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
 
 Calls the System V IPC function msgget(2).  Returns the message queue
 id, or the undefined value if there is an error.  See also
 L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
 
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+X<msgrcv>
 
 Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
 
 Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
@@ -2791,6 +2938,7 @@ an error.  See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and
 C<IPC::SysV::Msg> documentation.
 
 =item msgsnd ID,MSG,FLAGS
 C<IPC::SysV::Msg> documentation.
 
 =item msgsnd ID,MSG,FLAGS
+X<msgsnd>
 
 Calls the System V IPC function msgsnd to send the message MSG to the
 message queue ID.  MSG must begin with the native long integer message
 
 Calls the System V IPC function msgsnd to send the message MSG to the
 message queue ID.  MSG must begin with the native long integer message
@@ -2801,6 +2949,7 @@ or false if there is an error.  See also C<IPC::SysV>
 and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
+X<my>
 
 =item my TYPE EXPR
 
 
 =item my TYPE EXPR
 
@@ -2820,6 +2969,7 @@ L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
 =item next LABEL
 L<attributes>, and L<Attribute::Handlers>.
 
 =item next LABEL
+X<next> X<continue>
 
 =item next
 
 
 =item next
 
@@ -2846,6 +2996,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item no Module VERSION LIST
 C<redo> work.
 
 =item no Module VERSION LIST
+X<no>
 
 =item no Module VERSION
 
 
 =item no Module VERSION
 
@@ -2856,6 +3007,7 @@ C<redo> work.
 See the C<use> function, of which C<no> is the opposite.
 
 =item oct EXPR
 See the C<use> function, of which C<no> is the opposite.
 
 =item oct EXPR
+X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
 
 =item oct
 
 
 =item oct
 
@@ -2880,6 +3032,7 @@ automatically convert strings into numbers as needed, this automatic
 conversion assumes base 10.)
 
 =item open FILEHANDLE,EXPR
 conversion assumes base 10.)
 
 =item open FILEHANDLE,EXPR
+X<open> X<pipe> X<file, open> X<fopen>
 
 =item open FILEHANDLE,MODE,EXPR
 
 
 =item open FILEHANDLE,MODE,EXPR
 
@@ -2966,9 +3119,9 @@ L<PerlIO> for more details). For example
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
   open(FH, "<:utf8", "file")
 
 will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>. (Note that if layers are specified in the
-three-arg form then default layers set by the C<open> pragma are
-ignored.)
+see L<perluniintro>. Note that if layers are specified in the
+three-arg form then default layers stored in ${^OPEN} (see L<perlvar>;
+usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
 
 Open returns nonzero upon success, the undefined value otherwise.  If
 the C<open> involved a pipe, the return value happens to be the pid of
 
 Open returns nonzero upon success, the undefined value otherwise.  If
 the C<open> involved a pipe, the return value happens to be the pid of
@@ -3249,6 +3402,7 @@ them, and automatically close whenever and however you leave that scope:
 See L</seek> for some details about mixing reading and writing.
 
 =item opendir DIRHANDLE,EXPR
 See L</seek> for some details about mixing reading and writing.
 
 =item opendir DIRHANDLE,EXPR
+X<opendir>
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
@@ -3259,6 +3413,7 @@ reference to a new anonymous dirhandle.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord EXPR
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord EXPR
+X<ord> X<encoding>
 
 =item ord
 
 
 =item ord
 
@@ -3270,6 +3425,7 @@ For the reverse, see L</chr>.
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
+X<our> X<global>
 
 =item our EXPR TYPE
 
 
 =item our EXPR TYPE
 
@@ -3339,31 +3495,8 @@ from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
-The only currently recognized C<our()> attribute is C<unique> which
-indicates that a single copy of the global is to be used by all
-interpreters should the program happen to be running in a
-multi-interpreter environment. (The default behaviour would be for
-each interpreter to have its own copy of the global.)  Examples:
-
-    our @EXPORT : unique = qw(foo);
-    our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
-    our $VERSION : unique = "1.00";
-
-Note that this attribute also has the effect of making the global
-readonly when the first new interpreter is cloned (for example,
-when the first new thread is created).
-
-Multi-interpreter environments can come to being either through the
-fork() emulation on Windows platforms, or by embedding perl in a
-multi-threaded application.  The C<unique> attribute does nothing in
-all other environments.
-
-Warning: the current implementation of this attribute operates on the
-typeglob associated with the variable; this means that C<our $x : unique>
-also has the effect of C<our @x : unique; our %x : unique>. This may be
-subject to change.
-
 =item pack TEMPLATE,LIST
 =item pack TEMPLATE,LIST
+X<pack>
 
 Takes a LIST of values and converts it into a string using the rules
 given by the TEMPLATE.  The resulting string is the concatenation of
 
 Takes a LIST of values and converts it into a string using the rules
 given by the TEMPLATE.  The resulting string is the concatenation of
@@ -3405,7 +3538,7 @@ of values, as follows:
     I  A unsigned integer value.
          (This 'integer' is _at_least_ 32 bits wide.  Its exact
            size depends on what a local C compiler calls 'int'.)
     I  A unsigned integer value.
          (This 'integer' is _at_least_ 32 bits wide.  Its exact
            size depends on what a local C compiler calls 'int'.)
- 
+
     n  An unsigned short (16-bit) in "network" (big-endian) order.
     N  An unsigned long (32-bit) in "network" (big-endian) order.
     v  An unsigned short (16-bit) in "VAX" (little-endian) order.
     n  An unsigned short (16-bit) in "network" (big-endian) order.
     N  An unsigned long (32-bit) in "network" (big-endian) order.
     v  An unsigned short (16-bit) in "VAX" (little-endian) order.
@@ -3594,29 +3727,32 @@ so will result in a fatal error.
 The C</> template character allows packing and unpacking of a sequence of
 items where the packed structure contains a packed item count followed by 
 the packed items themselves.
 The C</> template character allows packing and unpacking of a sequence of
 items where the packed structure contains a packed item count followed by 
 the packed items themselves.
-You write I<length-item>C</>I<sequence-item>.
 
 
-The I<length-item> can be any C<pack> template letter, and describes
-how the length value is packed.  The ones likely to be of most use are
-integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
-SNMP) and C<N> (for Sun XDR).
+For C<pack> you write I<length-item>C</>I<sequence-item> and the
+I<length-item> describes how the length value is packed. The ones likely
+to be of most use are integer-packing ones like C<n> (for Java strings),
+C<w> (for ASN.1 or SNMP) and C<N> (for Sun XDR).
 
 For C<pack>, the I<sequence-item> may have a repeat count, in which case
 the minimum of that and the number of available items is used as argument
 for the I<length-item>. If it has no repeat count or uses a '*', the number
 
 For C<pack>, the I<sequence-item> may have a repeat count, in which case
 the minimum of that and the number of available items is used as argument
 for the I<length-item>. If it has no repeat count or uses a '*', the number
-of available items is used. For C<unpack> the repeat count is always obtained
-by decoding the packed item count, and the I<sequence-item> must not have a
-repeat count.
+of available items is used.
+
+For C<unpack> an internal stack of integer arguments unpacked so far is
+used. You write C</>I<sequence-item> and the repeat count is obtained by
+popping off the last element from the stack. The I<sequence-item> must not
+have a repeat count.
 
 If the I<sequence-item> refers to a string type (C<"A">, C<"a"> or C<"Z">),
 the I<length-item> is a string length, not a number of strings. If there is
 an explicit repeat count for pack, the packed string will be adjusted to that
 given length.
 
 
 If the I<sequence-item> refers to a string type (C<"A">, C<"a"> or C<"Z">),
 the I<length-item> is a string length, not a number of strings. If there is
 an explicit repeat count for pack, the packed string will be adjusted to that
 given length.
 
-    unpack 'W/a', "\04Gurusamy";        gives ('Guru')
-    unpack 'a3/A* A*', '007 Bond  J ';  gives (' Bond', 'J')
-    pack 'n/a* w/a','hello,','world';   gives "\000\006hello,\005world"
-    pack 'a/W2', ord('a') .. ord('z');  gives '2ab'
+    unpack 'W/a', "\04Gurusamy";            gives ('Guru')
+    unpack 'a3/A A*', '007 Bond  J ';       gives (' Bond', 'J')
+    unpack 'a3 x2 /A A*', '007: Bond, J.';  gives ('Bond, J', '.')
+    pack 'n/a* w/a','hello,','world';       gives "\000\006hello,\005world"
+    pack 'a/W2', ord('a') .. ord('z');      gives '2ab'
 
 The I<length-item> is not returned explicitly from C<unpack>.
 
 
 The I<length-item> is not returned explicitly from C<unpack>.
 
@@ -3883,6 +4019,7 @@ Examples:
 The same template may generally also be used in unpack().
 
 =item package NAMESPACE
 The same template may generally also be used in unpack().
 
 =item package NAMESPACE
+X<package> X<module> X<namespace>
 
 =item package
 
 
 =item package
 
@@ -3912,6 +4049,7 @@ See L<perlmod/"Packages"> for more information about packages, modules,
 and classes.  See L<perlsub> for other scoping issues.
 
 =item pipe READHANDLE,WRITEHANDLE
 and classes.  See L<perlsub> for other scoping issues.
 
 =item pipe READHANDLE,WRITEHANDLE
+X<pipe>
 
 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
 
 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
@@ -3927,6 +4065,7 @@ for the newly opened file descriptors as determined by the value of $^F.
 See L<perlvar/$^F>.
 
 =item pop ARRAY
 See L<perlvar/$^F>.
 
 =item pop ARRAY
+X<pop> X<stack>
 
 =item pop
 
 
 =item pop
 
@@ -3941,6 +4080,7 @@ omitted, pops the C<@ARGV> array in the main program, and the C<@_>
 array in subroutines, just like C<shift>.
 
 =item pos SCALAR
 array in subroutines, just like C<shift>.
 
 =item pos SCALAR
+X<pos> X<match, position>
 
 =item pos
 
 
 =item pos
 
@@ -3956,6 +4096,7 @@ the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST
 L<perlop>.
 
 =item print FILEHANDLE LIST
+X<print>
 
 =item print LIST
 
 
 =item print LIST
 
@@ -3990,6 +4131,7 @@ you will have to use a block returning the filehandle value instead:
     print { $OK ? STDOUT : STDERR } "stuff\n";
 
 =item printf FILEHANDLE FORMAT, LIST
     print { $OK ? STDOUT : STDERR } "stuff\n";
 
 =item printf FILEHANDLE FORMAT, LIST
+X<printf>
 
 =item printf FORMAT, LIST
 
 
 =item printf FORMAT, LIST
 
@@ -4005,6 +4147,7 @@ C<print> would do.  The C<print> is more efficient and less
 error prone.
 
 =item prototype FUNCTION
 error prone.
 
 =item prototype FUNCTION
+X<prototype>
 
 Returns the prototype of a function as a string (or C<undef> if the
 function has no prototype).  FUNCTION is a reference to, or the name of,
 
 Returns the prototype of a function as a string (or C<undef> if the
 function has no prototype).  FUNCTION is a reference to, or the name of,
@@ -4018,6 +4161,7 @@ like a Perl function.  Otherwise, the string describing the equivalent
 prototype is returned.
 
 =item push ARRAY,LIST
 prototype is returned.
 
 =item push ARRAY,LIST
+X<push>, X<stack>
 
 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
 
 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
@@ -4027,7 +4171,8 @@ LIST.  Has the same effect as
        $ARRAY[++$#ARRAY] = $value;
     }
 
        $ARRAY[++$#ARRAY] = $value;
     }
 
-but is more efficient.  Returns the new number of elements in the array.
+but is more efficient.  Returns the number of elements in the array following
+the completed C<push>.
 
 =item q/STRING/
 
 
 =item q/STRING/
 
@@ -4042,6 +4187,7 @@ but is more efficient.  Returns the new number of elements in the array.
 Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
 Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
+X<quotemeta> X<metacharacter>
 
 =item quotemeta
 
 
 =item quotemeta
 
@@ -4055,6 +4201,7 @@ the C<\Q> escape in double-quoted strings.
 If EXPR is omitted, uses C<$_>.
 
 =item rand EXPR
 If EXPR is omitted, uses C<$_>.
 
 =item rand EXPR
+X<rand> X<random>
 
 =item rand
 
 
 =item rand
 
@@ -4077,6 +4224,7 @@ large or too small, then your version of Perl was probably compiled
 with the wrong number of RANDBITS.)
 
 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
 with the wrong number of RANDBITS.)
 
 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<read>
 
 =item read FILEHANDLE,SCALAR,LENGTH
 
 
 =item read FILEHANDLE,SCALAR,LENGTH
 
@@ -4106,6 +4254,7 @@ characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be read.
 
 =item readdir DIRHANDLE
 in that case pretty much any characters can be read.
 
 =item readdir DIRHANDLE
+X<readdir>
 
 Returns the next directory entry for a directory opened by C<opendir>.
 If used in list context, returns all the rest of the entries in the
 
 Returns the next directory entry for a directory opened by C<opendir>.
 If used in list context, returns all the rest of the entries in the
@@ -4121,6 +4270,7 @@ C<chdir> there, it would have been testing the wrong file.
     closedir DIR;
 
 =item readline EXPR
     closedir DIR;
 
 =item readline EXPR
+X<readline> X<gets> X<fgets>
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
 context, each call reads and returns the next line, until end-of-file is
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
 context, each call reads and returns the next line, until end-of-file is
@@ -4156,6 +4306,7 @@ steps to ensure that C<readline> was successful.
     }
 
 =item readlink EXPR
     }
 
 =item readlink EXPR
+X<readlink>
 
 =item readlink
 
 
 =item readlink
 
@@ -4165,6 +4316,7 @@ error, returns the undefined value and sets C<$!> (errno).  If EXPR is
 omitted, uses C<$_>.
 
 =item readpipe EXPR
 omitted, uses C<$_>.
 
 =item readpipe EXPR
+X<readpipe>
 
 EXPR is executed as a system command.
 The collected standard output of the command is returned.
 
 EXPR is executed as a system command.
 The collected standard output of the command is returned.
@@ -4176,6 +4328,7 @@ operator, but you can use it directly.  The C<qx/EXPR/>
 operator is discussed in more detail in L<perlop/"I/O Operators">.
 
 =item recv SOCKET,SCALAR,LENGTH,FLAGS
 operator is discussed in more detail in L<perlop/"I/O Operators">.
 
 =item recv SOCKET,SCALAR,LENGTH,FLAGS
+X<recv>
 
 Receives a message on a socket.  Attempts to receive LENGTH characters
 of data into variable SCALAR from the specified SOCKET filehandle.
 
 Receives a message on a socket.  Attempts to receive LENGTH characters
 of data into variable SCALAR from the specified SOCKET filehandle.
@@ -4195,6 +4348,7 @@ characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be read.
 
 =item redo LABEL
 in that case pretty much any characters can be read.
 
 =item redo LABEL
+X<redo>
 
 =item redo
 
 
 =item redo
 
@@ -4233,6 +4387,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item ref EXPR
 C<redo> work.
 
 =item ref EXPR
+X<ref> X<reference>
 
 =item ref
 
 
 =item ref
 
@@ -4263,6 +4418,7 @@ name is returned instead.  You can think of C<ref> as a C<typeof> operator.
 See also L<perlref>.
 
 =item rename OLDNAME,NEWNAME
 See also L<perlref>.
 
 =item rename OLDNAME,NEWNAME
+X<rename> X<move> X<mv> X<ren>
 
 Changes the name of a file; an existing file NEWNAME will be
 clobbered.  Returns true for success, false otherwise.
 
 Changes the name of a file; an existing file NEWNAME will be
 clobbered.  Returns true for success, false otherwise.
@@ -4275,6 +4431,7 @@ open files, or pre-existing files.  Check L<perlport> and either the
 rename(2) manpage or equivalent system documentation for details.
 
 =item require VERSION
 rename(2) manpage or equivalent system documentation for details.
 
 =item require VERSION
+X<require>
 
 =item require EXPR
 
 
 =item require EXPR
 
@@ -4298,10 +4455,10 @@ version should be used instead.
     require 5.6.1;     # ditto
     require 5.006_001; # ditto; preferred for backwards compatibility
 
     require 5.6.1;     # ditto
     require 5.006_001; # ditto; preferred for backwards compatibility
 
-Otherwise, C<ref> 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 C<eval>.  Has semantics similar to the
-following subroutine:
+Otherwise, C<require> 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 C<eval>.  Has
+semantics similar to the following subroutine:
 
     sub require {
        my ($filename) = @_;
 
     sub require {
        my ($filename) = @_;
@@ -4365,14 +4522,12 @@ will complain about not finding "F<Foo::Bar>" there.  In this case you can do:
 
         eval "require $class";
 
 
         eval "require $class";
 
-Now that you understand how C<require> looks for files in the case of
-a bareword argument, there is a little extra functionality going on
-behind the scenes.  Before C<require> looks for a "F<.pm>" extension,
-it will first look for a filename with a "F<.pmc>" extension.  A file
-with this extension is assumed to be Perl bytecode generated by
-L<B::Bytecode|B::Bytecode>.  If this file is found, and its modification
-time is newer than a coinciding "F<.pm>" non-compiled file, it will be
-loaded in place of that non-compiled file ending in a "F<.pm>" extension.
+Now that you understand how C<require> looks for files in the case of a
+bareword argument, there is a little extra functionality going on behind
+the scenes.  Before C<require> looks for a "F<.pm>" extension, it will
+first look for a similar filename with a "F<.pmc>" extension. If this file
+is found, it will be loaded in place of any file ending in a "F<.pm>"
+extension.
 
 You can also insert hooks into the import facility, by putting directly
 Perl code into the @INC array.  There are three forms of hooks: subroutine
 
 You can also insert hooks into the import facility, by putting directly
 Perl code into the @INC array.  There are three forms of hooks: subroutine
@@ -4382,9 +4537,42 @@ Subroutine references are the simplest case.  When the inclusion system
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first being a reference to itself, and the
 second the name of the file to be included (e.g. "F<Foo/Bar.pm>").  The
 walks through @INC and encounters a subroutine, this subroutine gets
 called with two parameters, the first being a reference to itself, and the
 second the name of the file to be included (e.g. "F<Foo/Bar.pm>").  The
-subroutine should return C<undef> or a filehandle, from which the file to
-include will be read.  If C<undef> is returned, C<require> will look at
-the remaining elements of @INC.
+subroutine should return nothing, or a list of up to 4 values in the
+following order:
+
+=over
+
+=item 1
+
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
+
+
+=item 2
+
+A filehandle, from which the file will be read.  
+
+=item 3
+
+A reference to a subroutine. If there is no file handle, then this subroutine
+is expected to generate one line of source code per call, writing the line
+into C<$_> and returning 1, then returning 0 at "end of FILE" If there is a
+file handle then the subroutine will be called to act a simple source filter,
+with the line as read in C<$_>. Again, return 1 for each valid line, and 0
+after all lines have been returned.
+
+=item 4
+
+Optional state for the subroutine. The state is passed in as C<$_[1]>. A
+reference to the subroutine itself is passed in as C<$_[0]>.
+
+=back
+
+If an empty list, C<undef>, or nothing that matches the first 3 values above
+is returned then C<require> will look at the remaining elements of @INC.
+Note that this file handle must be a real file handle (strictly a typeglob,
+or reference to a typeglob, blessed or unblessed) - tied file handles will be
+ignored and return value processing will stop there.
 
 If the hook is an array reference, its first element must be a subroutine
 reference.  This subroutine is called as above, but the first parameter is
 
 If the hook is an array reference, its first element must be a subroutine
 reference.  This subroutine is called as above, but the first parameter is
@@ -4411,8 +4599,8 @@ or:
 
 If the hook is an object, it must provide an INC method that will be
 called as above, the first parameter being the object itself.  (Note that
 
 If the hook is an object, it must provide an INC method that will be
 called as above, the first parameter being the object itself.  (Note that
-you must fully qualify the sub's name, as it is always forced into package
-C<main>.)  Here is a typical code layout:
+you must fully qualify the sub's name, as unqualified C<INC> is always forced
+into package C<main>.)  Here is a typical code layout:
 
     # In Foo.pm
     package Foo;
 
     # In Foo.pm
     package Foo;
@@ -4431,6 +4619,7 @@ corresponding to the files they have loaded. See L<perlvar/%INC>.
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
+X<reset>
 
 =item reset
 
 
 =item reset
 
@@ -4454,6 +4643,7 @@ up on scope exit anyway, so you'll probably want to use them instead.
 See L</my>.
 
 =item return EXPR
 See L</my>.
 
 =item return EXPR
+X<return>
 
 =item return
 
 
 =item return
 
@@ -4469,6 +4659,7 @@ or do FILE will automatically return the value of the last expression
 evaluated.)
 
 =item reverse LIST
 evaluated.)
 
 =item reverse LIST
+X<reverse> X<rev> X<invert>
 
 In list context, returns a list value consisting of the elements
 of LIST in the opposite order.  In scalar context, concatenates the
 
 In list context, returns a list value consisting of the elements
 of LIST in the opposite order.  In scalar context, concatenates the
@@ -4491,19 +4682,22 @@ on a large hash, such as from a DBM file.
     %by_name = reverse %by_address;    # Invert the hash
 
 =item rewinddir DIRHANDLE
     %by_name = reverse %by_address;    # Invert the hash
 
 =item rewinddir DIRHANDLE
+X<rewinddir>
 
 Sets the current position to the beginning of the directory for the
 C<readdir> routine on DIRHANDLE.
 
 =item rindex STR,SUBSTR,POSITION
 
 Sets the current position to the beginning of the directory for the
 C<readdir> routine on DIRHANDLE.
 
 =item rindex STR,SUBSTR,POSITION
+X<rindex>
 
 =item rindex STR,SUBSTR
 
 
 =item rindex STR,SUBSTR
 
-Works just like index() except that it returns the position of the LAST
+Works just like index() except that it returns the position of the I<last>
 occurrence of SUBSTR in STR.  If POSITION is specified, returns the
 occurrence of SUBSTR in STR.  If POSITION is specified, returns the
-last occurrence at or before that position.
+last occurrence beginning at or before that position.
 
 =item rmdir FILENAME
 
 =item rmdir FILENAME
+X<rmdir> X<rd> X<directory, remove>
 
 =item rmdir
 
 
 =item rmdir
 
@@ -4515,7 +4709,25 @@ sets C<$!> (errno).  If FILENAME is omitted, uses C<$_>.
 
 The substitution operator.  See L<perlop>.
 
 
 The substitution operator.  See L<perlop>.
 
+=item say FILEHANDLE LIST
+X<say>
+
+=item say LIST
+
+=item say
+
+Just like C<print>, but implicitly appends a newline.
+C<say LIST> is simply an abbreviation for C<print LIST, "\n">,
+and C<say()> works just like C<print($_, "\n")>.
+
+That means that a call to say() appends any output record separator
+I<after> the added newline.
+
+This keyword is only available when the "say" feature is
+enabled: see L<feature>.
+
 =item scalar EXPR
 =item scalar EXPR
+X<scalar> X<context>
 
 Forces EXPR to be interpreted in scalar context and returns the value
 of EXPR.
 
 Forces EXPR to be interpreted in scalar context and returns the value
 of EXPR.
@@ -4545,6 +4757,7 @@ is the moral equivalent of these two:
 See L<perlop> for more details on unary operators and the comma operator.
 
 =item seek FILEHANDLE,POSITION,WHENCE
 See L<perlop> for more details on unary operators and the comma operator.
 
 =item seek FILEHANDLE,POSITION,WHENCE
+X<seek> X<fseek> X<filehandle, position>
 
 Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
 FILEHANDLE may be an expression whose value gives the name of the
 
 Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
 FILEHANDLE may be an expression whose value gives the name of the
@@ -4591,6 +4804,7 @@ cantankerous), then you may need something more like this:
     }
 
 =item seekdir DIRHANDLE,POS
     }
 
 =item seekdir DIRHANDLE,POS
+X<seekdir>
 
 Sets the current position for the C<readdir> routine on DIRHANDLE.  POS
 must be a value returned by C<telldir>.  C<seekdir> also has the same caveats
 
 Sets the current position for the C<readdir> routine on DIRHANDLE.  POS
 must be a value returned by C<telldir>.  C<seekdir> also has the same caveats
@@ -4598,6 +4812,7 @@ about possible directory compaction as the corresponding system library
 routine.
 
 =item select FILEHANDLE
 routine.
 
 =item select FILEHANDLE
+X<select> X<filehandle, default>
 
 =item select
 
 
 =item select
 
@@ -4626,6 +4841,7 @@ methods, preferring to write the last example as:
     STDERR->autoflush(1);
 
 =item select RBITS,WBITS,EBITS,TIMEOUT
     STDERR->autoflush(1);
 
 =item select RBITS,WBITS,EBITS,TIMEOUT
+X<select>
 
 This calls the select(2) system call with the bit masks specified, which
 can be constructed using C<fileno> and C<vec>, along these lines:
 
 This calls the select(2) system call with the bit masks specified, which
 can be constructed using C<fileno> and C<vec>, along these lines:
@@ -4673,7 +4889,8 @@ Note that whether C<select> gets restarted after signals (say, SIGALRM)
 is implementation-dependent.  See also L<perlport> for notes on the
 portability of C<select>.
 
 is implementation-dependent.  See also L<perlport> for notes on the
 portability of C<select>.
 
-On error, C<select> returns C<undef> and sets C<$!>.
+On error, C<select> behaves like the select(2) system call : it returns
+-1 and sets C<$!>.
 
 Note: on some Unixes, the select(2) system call may report a socket file
 descriptor as "ready for reading", when actually no data is available,
 
 Note: on some Unixes, the select(2) system call may report a socket file
 descriptor as "ready for reading", when actually no data is available,
@@ -4686,6 +4903,7 @@ or <FH>) with C<select>, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C<sysread> instead.
 
 =item semctl ID,SEMNUM,CMD,ARG
 then only on POSIX systems.  You have to use C<sysread> instead.
 
 =item semctl ID,SEMNUM,CMD,ARG
+X<semctl>
 
 Calls the System V IPC function C<semctl>.  You'll probably have to say
 
 
 Calls the System V IPC function C<semctl>.  You'll probably have to say
 
@@ -4701,6 +4919,7 @@ See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
 documentation.
 
 =item semget KEY,NSEMS,FLAGS
 documentation.
 
 =item semget KEY,NSEMS,FLAGS
+X<semget>
 
 Calls the System V IPC function semget.  Returns the semaphore id, or
 the undefined value if there is an error.  See also
 
 Calls the System V IPC function semget.  Returns the semaphore id, or
 the undefined value if there is an error.  See also
@@ -4708,6 +4927,7 @@ L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
 documentation.
 
 =item semop KEY,OPSTRING
 documentation.
 
 =item semop KEY,OPSTRING
+X<semop>
 
 Calls the System V IPC function semop to perform semaphore operations
 such as signalling and waiting.  OPSTRING must be a packed array of
 
 Calls the System V IPC function semop to perform semaphore operations
 such as signalling and waiting.  OPSTRING must be a packed array of
@@ -4725,6 +4945,7 @@ L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
 documentation.
 
 =item send SOCKET,MSG,FLAGS,TO
 documentation.
 
 =item send SOCKET,MSG,FLAGS,TO
+X<send>
 
 =item send SOCKET,MSG,FLAGS
 
 
 =item send SOCKET,MSG,FLAGS
 
@@ -4745,6 +4966,7 @@ Unicode characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be sent.
 
 =item setpgrp PID,PGRP
 in that case pretty much any characters can be sent.
 
 =item setpgrp PID,PGRP
+X<setpgrp> X<group>
 
 Sets the current process group for the specified PID, C<0> for the current
 process.  Will produce a fatal error if used on a machine that doesn't
 
 Sets the current process group for the specified PID, C<0> for the current
 process.  Will produce a fatal error if used on a machine that doesn't
@@ -4754,18 +4976,28 @@ accept any arguments, so only C<setpgrp(0,0)> is portable.  See also
 C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
 C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
+X<setpriority> X<priority> X<nice> X<renice>
 
 Sets the current priority for a process, a process group, or a user.
 (See setpriority(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 current priority for a process, a process group, or a user.
 (See setpriority(2).)  Will produce a fatal error if used on a machine
 that doesn't implement setpriority(2).
 
 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+X<setsockopt>
 
 Sets the socket option requested.  Returns undefined if there is an
 
 Sets the socket option requested.  Returns undefined if there is an
-error.  OPTVAL may be specified as C<undef> if you don't want to pass an
-argument.
+error.  Use integer constants provided by the C<Socket> module for
+LEVEL and OPNAME.  Values for LEVEL can also be obtained from
+getprotobyname.  OPTVAL might either be a packed string or an integer.
+An integer OPTVAL is shorthand for pack("i", OPTVAL).
+
+An example disabling the Nagle's algorithm for a socket:
+
+    use Socket qw(IPPROTO_TCP TCP_NODELAY);
+    setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
 
 =item shift ARRAY
 
 =item shift ARRAY
+X<shift>
 
 =item shift
 
 
 =item shift
 
@@ -4782,6 +5014,7 @@ same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
 
 =item shmctl ID,CMD,ARG
 right end.
 
 =item shmctl ID,CMD,ARG
+X<shmctl>
 
 Calls the System V IPC function shmctl.  You'll probably have to say
 
 
 Calls the System V IPC function shmctl.  You'll probably have to say
 
@@ -4794,12 +5027,15 @@ true" for zero, or the actual return value otherwise.
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmget KEY,SIZE,FLAGS
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmget KEY,SIZE,FLAGS
+X<shmget>
 
 Calls the System V IPC function shmget.  Returns the shared memory
 segment id, or the undefined value if there is an error.
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmread ID,VAR,POS,SIZE
 
 Calls the System V IPC function shmget.  Returns the shared memory
 segment id, or the undefined value if there is an error.
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmread ID,VAR,POS,SIZE
+X<shmread>
+X<shmwrite>
 
 =item shmwrite ID,STRING,POS,SIZE
 
 
 =item shmwrite ID,STRING,POS,SIZE
 
@@ -4813,6 +5049,7 @@ shmread() taints the variable. See also L<perlipc/"SysV IPC">,
 C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
 
 =item shutdown SOCKET,HOW
 C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
 
 =item shutdown SOCKET,HOW
+X<shutdown>
 
 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.
 
 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.
@@ -4828,6 +5065,7 @@ disables the file descriptor in any forked copies in other
 processes.
 
 =item sin EXPR
 processes.
 
 =item sin EXPR
+X<sin> X<sine> X<asin> X<arcsine>
 
 =item sin
 
 
 =item sin
 
@@ -4840,6 +5078,7 @@ function, or use this relation:
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
 
 =item sleep EXPR
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
 
 =item sleep EXPR
+X<sleep> X<pause>
 
 =item sleep
 
 
 =item sleep
 
@@ -4864,6 +5103,7 @@ help.
 See also the POSIX module's C<pause> function.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
 See also the POSIX module's C<pause> function.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
+X<socket>
 
 Opens a socket of the specified kind and attaches it to filehandle
 SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
 
 Opens a socket of the specified kind and attaches it to filehandle
 SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
@@ -4876,6 +5116,7 @@ be set for the newly opened file descriptor, as determined by the
 value of $^F.  See L<perlvar/$^F>.
 
 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
 value of $^F.  See L<perlvar/$^F>.
 
 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+X<socketpair>
 
 Creates an unnamed pair of sockets in the specified domain, of the
 specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
 
 Creates an unnamed pair of sockets in the specified domain, of the
 specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
@@ -4899,6 +5140,7 @@ emulate socketpair using IP sockets to localhost if your system implements
 sockets but not socketpair.
 
 =item sort SUBNAME LIST
 sockets but not socketpair.
 
 =item sort SUBNAME LIST
+X<sort> X<qsort> X<quicksort> X<mergesort>
 
 =item sort BLOCK LIST
 
 
 =item sort BLOCK LIST
 
@@ -4925,8 +5167,8 @@ as the package global variables $a and $b (see example below).  Note that
 in the latter case, it is usually counter-productive to declare $a and
 $b as lexicals.
 
 in the latter case, it is usually counter-productive to declare $a and
 $b as lexicals.
 
-In either case, the subroutine may not be recursive.  The values to be
-compared are always passed by reference and should not be modified.
+The values to be compared are always passed by reference and should not
+be modified.
 
 You also cannot exit out of the sort block or subroutine using any of the
 loop control operators described in L<perlsyn> or with C<goto>.
 
 You also cannot exit out of the sort block or subroutine using any of the
 loop control operators described in L<perlsyn> or with C<goto>.
@@ -5069,6 +5311,7 @@ eliminate any C<NaN>s from the input.
     @result = sort { $a <=> $b } grep { $_ == $_ } @input;
 
 =item splice ARRAY,OFFSET,LENGTH,LIST
     @result = sort { $a <=> $b } grep { $_ == $_ } @input;
 
 =item splice ARRAY,OFFSET,LENGTH,LIST
+X<splice>
 
 =item splice ARRAY,OFFSET,LENGTH
 
 
 =item splice ARRAY,OFFSET,LENGTH
 
@@ -5111,6 +5354,7 @@ Example, assuming array lengths are passed before arrays:
     if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
 
 =item split /PATTERN/,EXPR,LIMIT
     if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
 
 =item split /PATTERN/,EXPR,LIMIT
+X<split>
 
 =item split /PATTERN/,EXPR
 
 
 =item split /PATTERN/,EXPR
 
@@ -5225,6 +5469,7 @@ matched in a C<split()> will be set to C<undef> when returned:
     # @fields is (1, 'A', 2, undef, 3)
 
 =item sprintf FORMAT, LIST
     # @fields is (1, 'A', 2, undef, 3)
 
 =item sprintf FORMAT, LIST
+X<sprintf>
 
 Returns a string formatted by the usual C<printf> conventions of the C
 library function C<sprintf>.  See below for more details
 
 Returns a string formatted by the usual C<printf> conventions of the C
 library function C<sprintf>.  See below for more details
@@ -5325,12 +5570,13 @@ For example:
 
 =item vector flag
 
 
 =item vector flag
 
-The vector flag C<v>, optionally specifying the join string to use.
-This flag tells perl to interpret the supplied string as a vector
-of integers, one for each character in the string, separated by
-a given string (a dot C<.> by default). This can be useful for
-displaying ordinal values of characters in arbitrary strings:
+This flag tells perl to interpret the supplied string as a vector of
+integers, one for each character in the string. Perl applies the format to
+each integer in turn, then joins the resulting strings with a separator (a
+dot C<.> by default). This can be useful for displaying ordinal values of
+characters in arbitrary strings:
 
 
+  printf "%vd", "AB\x{100}";           # prints "65.66.256"
   printf "version is v%vd\n", $^V;     # Perl's version
 
 Put an asterisk C<*> before the C<v> to override the string to
   printf "version is v%vd\n", $^V;     # Perl's version
 
 Put an asterisk C<*> before the C<v> to override the string to
@@ -5361,6 +5607,7 @@ If a field width obtained through C<*> is negative, it has the same
 effect as the C<-> flag: left-justification.
 
 =item precision, or maximum width
 effect as the C<-> flag: left-justification.
 
 =item precision, or maximum width
+X<precision>
 
 You can specify a precision (for numeric conversions) or a maximum
 width (for string conversions) by specifying a C<.> followed by a number.
 
 You can specify a precision (for numeric conversions) or a maximum
 width (for string conversions) by specifying a C<.> followed by a number.
@@ -5498,6 +5745,7 @@ point in formatted real numbers is affected by the LC_NUMERIC locale.
 See L<perllocale>.
 
 =item sqrt EXPR
 See L<perllocale>.
 
 =item sqrt EXPR
+X<sqrt> X<root> X<square root>
 
 =item sqrt
 
 
 =item sqrt
 
@@ -5509,6 +5757,7 @@ loaded the standard Math::Complex module.
     print sqrt(-2);    # prints 1.4142135623731i
 
 =item srand EXPR
     print sqrt(-2);    # prints 1.4142135623731i
 
 =item srand EXPR
+X<srand> X<seed> X<randseed>
 
 =item srand
 
 
 =item srand
 
@@ -5570,6 +5819,7 @@ for a seed can fall prey to the mathematical property that
 one-third of the time.  So don't do that.
 
 =item stat FILEHANDLE
 one-third of the time.  So don't do that.
 
 =item stat FILEHANDLE
+X<stat> X<file, status>
 
 =item stat EXPR
 
 
 =item stat EXPR
 
@@ -5669,7 +5919,7 @@ The commonly available C<S_IF*> constants are
 
     # File types.  Not necessarily all are available on your system.
 
 
     # File types.  Not necessarily all are available on your system.
 
-    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
 
     # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
 
 
     # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
 
@@ -5700,6 +5950,7 @@ about the C<S_*> constants.  To get status info for a symbolic link
 instead of the target file behind the link, use the C<lstat> function.
 
 =item study SCALAR
 instead of the target file behind the link, use the C<lstat> function.
 
 =item study SCALAR
+X<study>
 
 =item study
 
 
 =item study
 
@@ -5759,6 +6010,7 @@ out the names of those files that contain a match:
     }
 
 =item sub NAME BLOCK
     }
 
 =item sub NAME BLOCK
+X<sub>
 
 =item sub NAME (PROTO) BLOCK
 
 
 =item sub NAME (PROTO) BLOCK
 
@@ -5776,6 +6028,7 @@ references, and L<attributes> and L<Attribute::Handlers> for more
 information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
+X<substr> X<substring> X<mid> X<left> X<right>
 
 =item substr EXPR,OFFSET,LENGTH
 
 
 =item substr EXPR,OFFSET,LENGTH
 
@@ -5829,6 +6082,7 @@ Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
 unspecified.
 
 =item symlink OLDFILE,NEWFILE
 unspecified.
 
 =item symlink OLDFILE,NEWFILE
+X<symlink> X<link> X<symbolic link> X<link, symbolic>
 
 Creates a new filename symbolically linked to the old filename.
 Returns C<1> for success, C<0> otherwise.  On systems that don't support
 
 Creates a new filename symbolically linked to the old filename.
 Returns C<1> for success, C<0> otherwise.  On systems that don't support
@@ -5838,6 +6092,7 @@ use eval:
     $symlink_exists = eval { symlink("",""); 1 };
 
 =item syscall NUMBER, LIST
     $symlink_exists = eval { symlink("",""); 1 };
 
 =item syscall NUMBER, LIST
+X<syscall> X<system call>
 
 Calls the system call specified as the first element of the list,
 passing the remaining elements as arguments to the system call.  If
 
 Calls the system call specified as the first element of the list,
 passing the remaining elements as arguments to the system call.  If
@@ -5872,6 +6127,7 @@ to retrieve the file number of the other end.  You can avoid this
 problem by using C<pipe> instead.
 
 =item sysopen FILEHANDLE,FILENAME,MODE
 problem by using C<pipe> instead.
 
 =item sysopen FILEHANDLE,FILENAME,MODE
+X<sysopen>
 
 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
 
 
 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
 
@@ -5890,6 +6146,7 @@ using the C<|>-operator.
 Some of the most common values are C<O_RDONLY> for opening the file in
 read-only mode, C<O_WRONLY> for opening the file in write-only mode,
 and C<O_RDWR> for opening the file in read-write mode.
 Some of the most common values are C<O_RDONLY> for opening the file in
 read-only mode, C<O_WRONLY> for opening the file in write-only mode,
 and C<O_RDWR> for opening the file in read-write mode.
+X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
 
 For historical reasons, some values work on almost every system
 supported by perl: zero means read-only, one means write-only, and two
 
 For historical reasons, some values work on almost every system
 supported by perl: zero means read-only, one means write-only, and two
@@ -5903,6 +6160,7 @@ PERMS specifies the permissions of the newly created file.  If you omit
 the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
 These permission values need to be in octal, and are modified by your
 process's current C<umask>.
 the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
 These permission values need to be in octal, and are modified by your
 process's current C<umask>.
+X<O_CREAT>
 
 In many systems the C<O_EXCL> flag is available for opening files in
 exclusive mode.  This is B<not> locking: exclusiveness means here that
 
 In many systems the C<O_EXCL> flag is available for opening files in
 exclusive mode.  This is B<not> locking: exclusiveness means here that
@@ -5911,10 +6169,12 @@ on network filesystems, and has no effect unless the C<O_CREAT> flag
 is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
 being opened if it is a symbolic link.  It does not protect against
 symbolic links in the file's path.
 is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
 being opened if it is a symbolic link.  It does not protect against
 symbolic links in the file's path.
+X<O_EXCL>
 
 Sometimes you may want to truncate an already-existing file.  This
 can be done using the C<O_TRUNC> flag.  The behavior of
 C<O_TRUNC> with C<O_RDONLY> is undefined.
 
 Sometimes you may want to truncate an already-existing file.  This
 can be done using the C<O_TRUNC> flag.  The behavior of
 C<O_TRUNC> with C<O_RDONLY> is undefined.
+X<O_TRUNC>
 
 You should seldom if ever use C<0644> as argument to C<sysopen>, because
 that takes away the user's option to have a more permissive umask.
 
 You should seldom if ever use C<0644> as argument to C<sysopen>, because
 that takes away the user's option to have a more permissive umask.
@@ -5930,6 +6190,7 @@ library, or perhaps using the POSIX::open() function.
 See L<perlopentut> for a kinder, gentler explanation of opening files.
 
 =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
 See L<perlopentut> for a kinder, gentler explanation of opening files.
 
 =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<sysread>
 
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
 
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
@@ -5961,6 +6222,7 @@ The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item sysseek FILEHANDLE,POSITION,WHENCE
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item sysseek FILEHANDLE,POSITION,WHENCE
+X<sysseek> X<lseek>
 
 Sets FILEHANDLE's system position in bytes using the system call
 lseek(2).  FILEHANDLE may be an expression whose value gives the name
 
 Sets FILEHANDLE's system position in bytes using the system call
 lseek(2).  FILEHANDLE may be an expression whose value gives the name
@@ -5992,6 +6254,7 @@ true on success and false on failure, yet you can still easily determine
 the new position.
 
 =item system LIST
 the new position.
 
 =item system LIST
+X<system> X<shell>
 
 =item system PROGRAM LIST
 
 
 =item system PROGRAM LIST
 
@@ -6057,6 +6320,7 @@ and return codes will be subject to its quirks and capabilities.
 See L<perlop/"`STRING`"> and L</exec> for details.
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
 See L<perlop/"`STRING`"> and L</exec> for details.
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<syswrite>
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
 
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
 
@@ -6085,6 +6349,7 @@ The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item tell FILEHANDLE
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item tell FILEHANDLE
+X<tell>
 
 =item tell
 
 
 =item tell
 
@@ -6109,6 +6374,7 @@ that has been manipulated by sysread(), syswrite() or sysseek().
 Those functions ignore the buffering, while tell() does not.
 
 =item telldir DIRHANDLE
 Those functions ignore the buffering, while tell() does not.
 
 =item telldir DIRHANDLE
+X<telldir>
 
 Returns the current position of the C<readdir> routines on DIRHANDLE.
 Value may be given to C<seekdir> to access a particular location in a
 
 Returns the current position of the C<readdir> routines on DIRHANDLE.
 Value may be given to C<seekdir> to access a particular location in a
@@ -6116,6 +6382,7 @@ directory.  C<telldir> has the same caveats about possible directory
 compaction as the corresponding system library routine.
 
 =item tie VARIABLE,CLASSNAME,LIST
 compaction as the corresponding system library routine.
 
 =item tie VARIABLE,CLASSNAME,LIST
+X<tie>
 
 This function binds a variable to a package class that will provide the
 implementation for the variable.  VARIABLE is the name of the variable
 
 This function binds a variable to a package class that will provide the
 implementation for the variable.  VARIABLE is the name of the variable
@@ -6207,6 +6474,7 @@ or the F<Config> module for interesting C<tie> implementations.
 For further details see L<perltie>, L<"tied VARIABLE">.
 
 =item tied VARIABLE
 For further details see L<perltie>, L<"tied VARIABLE">.
 
 =item tied VARIABLE
+X<tied>
 
 Returns a reference to the object underlying VARIABLE (the same value
 that was originally returned by the C<tie> call that bound the variable
 
 Returns a reference to the object underlying VARIABLE (the same value
 that was originally returned by the C<tie> call that bound the variable
@@ -6214,6 +6482,7 @@ to a package.)  Returns the undefined value if VARIABLE isn't tied to a
 package.
 
 =item time
 package.
 
 =item time
+X<time> X<epoch>
 
 Returns the number of non-leap seconds since whatever time the system
 considers to be the epoch, suitable for feeding to C<gmtime> and
 
 Returns the number of non-leap seconds since whatever time the system
 considers to be the epoch, suitable for feeding to C<gmtime> and
@@ -6228,6 +6497,7 @@ gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
 See L<perlfaq8> for details.
 
 =item times
 See L<perlfaq8> for details.
 
 =item times
+X<times>
 
 Returns a four-element list giving the user and system times, in
 seconds, for this process and the children of this process.
 
 Returns a four-element list giving the user and system times, in
 seconds, for this process and the children of this process.
@@ -6236,11 +6506,14 @@ seconds, for this process and the children of this process.
 
 In scalar context, C<times> returns C<$user>.
 
 
 In scalar context, C<times> returns C<$user>.
 
+Note that times for children are included only after they terminate.
+
 =item tr///
 
 The transliteration operator.  Same as C<y///>.  See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
 =item tr///
 
 The transliteration operator.  Same as C<y///>.  See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
+X<truncate>
 
 =item truncate EXPR,LENGTH
 
 
 =item truncate EXPR,LENGTH
 
@@ -6252,7 +6525,11 @@ otherwise.
 The behavior is undefined if LENGTH is greater than the length of the
 file.
 
 The behavior is undefined if LENGTH is greater than the length of the
 file.
 
+The position in the file of FILEHANDLE is left unchanged.  You may want to
+call L<seek> before writing to the file.
+
 =item uc EXPR
 =item uc EXPR
+X<uc> X<uppercase> X<toupper>
 
 =item uc
 
 
 =item uc
 
@@ -6266,6 +6543,7 @@ C<ucfirst> for that.
 If EXPR is omitted, uses C<$_>.
 
 =item ucfirst EXPR
 If EXPR is omitted, uses C<$_>.
 
 =item ucfirst EXPR
+X<ucfirst> X<uppercase>
 
 =item ucfirst
 
 
 =item ucfirst
 
@@ -6278,6 +6556,7 @@ for more details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item umask EXPR
 If EXPR is omitted, uses C<$_>.
 
 =item umask EXPR
+X<umask>
 
 =item umask
 
 
 =item umask
 
@@ -6315,6 +6594,7 @@ Remember that a umask is a number, usually given in octal; it is I<not> a
 string of octal digits.  See also L</oct>, if all you have is a string.
 
 =item undef EXPR
 string of octal digits.  See also L</oct>, if all you have is a string.
 
 =item undef EXPR
+X<undef> X<undefine>
 
 =item undef
 
 
 =item undef
 
@@ -6341,6 +6621,7 @@ parameter.  Examples:
 Note that this is a unary operator, not a list operator.
 
 =item unlink LIST
 Note that this is a unary operator, not a list operator.
 
 =item unlink LIST
+X<unlink> X<delete> X<remove> X<rm>
 
 =item unlink
 
 
 =item unlink
 
@@ -6351,14 +6632,16 @@ deleted.
     unlink @goners;
     unlink <*.bak>;
 
     unlink @goners;
     unlink <*.bak>;
 
-Note: C<unlink> will not delete directories unless you are superuser and
-the B<-U> flag is supplied to Perl.  Even if these conditions are
+Note: C<unlink> will not attempt to 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
 met, be warned that unlinking a directory can inflict damage on your
-filesystem.  Use C<rmdir> instead.
+filesystem.  Finally, using C<unlink> on directories is not supported on 
+many operating systems.  Use C<rmdir> instead.
 
 If LIST is omitted, uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
 
 If LIST is omitted, uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
+X<unpack>
 
 =item unpack TEMPLATE
 
 
 =item unpack TEMPLATE
 
@@ -6419,11 +6702,13 @@ the rest is ignored.
 See L</pack> for more examples and notes.
 
 =item untie VARIABLE
 See L</pack> for more examples and notes.
 
 =item untie VARIABLE
+X<untie>
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
 Has no effect if the variable is not tied.
 
 =item unshift ARRAY,LIST
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
 Has no effect if the variable is not tied.
 
 =item unshift ARRAY,LIST
+X<unshift>
 
 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
 
 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
@@ -6436,6 +6721,7 @@ prepended elements stay in the same order.  Use C<reverse> to do the
 reverse.
 
 =item use Module VERSION LIST
 reverse.
 
 =item use Module VERSION LIST
+X<use> X<module> X<import>
 
 =item use Module VERSION
 
 
 =item use Module VERSION
 
@@ -6534,6 +6820,7 @@ for the C<-M> and C<-m> command-line options to perl that give C<use>
 functionality from the command-line.
 
 =item utime LIST
 functionality from the command-line.
 
 =item utime LIST
+X<utime>
 
 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
 
 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
@@ -6567,7 +6854,14 @@ be equivalent of passing it as 0 and will not have the same effect as
 described when they are both C<undef>.  This case will also trigger an
 uninitialized warning.
 
 described when they are both C<undef>.  This case will also trigger an
 uninitialized warning.
 
+On systems that support futimes, you might pass file handles among the
+files.  On systems that don't support futimes, passing file handles
+produces a fatal error at run time.  The file handles must be passed
+as globs or references to be recognized.  Barewords are considered
+file names.
+
 =item values HASH
 =item values HASH
+X<values>
 
 Returns a list consisting of all the values of the named hash.
 (In a scalar context, returns the number of values.)
 
 Returns a list consisting of all the values of the named hash.
 (In a scalar context, returns the number of values.)
@@ -6592,6 +6886,7 @@ modify the contents of the hash:
 See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
 See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
+X<vec> X<bit> X<bit vector>
 
 Treats the string in EXPR as a bit vector made up of elements of
 width BITS, and returns the value of the element specified by OFFSET
 
 Treats the string in EXPR as a bit vector made up of elements of
 width BITS, and returns the value of the element specified by OFFSET
@@ -6832,6 +7127,7 @@ example should print the following table:
     vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
 
 =item wait
     vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
 
 =item wait
+X<wait>
 
 Behaves like the wait(2) system call on your system: it waits for a child
 process to terminate and returns the pid of the deceased process, or
 
 Behaves like the wait(2) system call on your system: it waits for a child
 process to terminate and returns the pid of the deceased process, or
@@ -6841,6 +7137,7 @@ Note that a return value of C<-1> could mean that child processes are
 being automatically reaped, as described in L<perlipc>.
 
 =item waitpid PID,FLAGS
 being automatically reaped, as described in L<perlipc>.
 
 =item waitpid PID,FLAGS
+X<waitpid>
 
 Waits for a particular child process to terminate and returns the pid of
 the deceased process, or C<-1> if there is no such child process.  On some
 
 Waits for a particular child process to terminate and returns the pid of
 the deceased process, or C<-1> if there is no such child process.  On some
@@ -6865,6 +7162,7 @@ processes are being automatically reaped.  See L<perlipc> for details,
 and for other examples.
 
 =item wantarray
 and for other examples.
 
 =item wantarray
+X<wantarray> X<context>
 
 Returns true if the context of the currently executing subroutine or
 C<eval> is looking for a list value.  Returns false if the context is
 
 Returns true if the context of the currently executing subroutine or
 C<eval> is looking for a list value.  Returns false if the context is
@@ -6882,6 +7180,7 @@ method.
 This function should have been named wantlist() instead.
 
 =item warn LIST
 This function should have been named wantlist() instead.
 
 =item warn LIST
+X<warn> X<warning> X<STDERR>
 
 Produces a message on STDERR just like C<die>, but doesn't exit or throw
 an exception.
 
 Produces a message on STDERR just like C<die>, but doesn't exit or throw
 an exception.
@@ -6925,6 +7224,7 @@ examples.  See the Carp module for other kinds of warnings using its
 carp() and cluck() functions.
 
 =item write FILEHANDLE
 carp() and cluck() functions.
 
 =item write FILEHANDLE
+X<write>
 
 =item write EXPR
 
 
 =item write EXPR
 
Unnamed repository; edit this file 'description' to name the repository.