X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/d8ff3e95e0f2357b6f26f5a94c52c46231fb1a74..758600332df6396bd902fa4a761230f89664ecb8:/pod/perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 9394e22..af47dc2 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -522,6 +522,10 @@ argument is omitted, tests L<C<$_>|perlvar/$_>, except for C<-t>, which
 tests STDIN.  Unless otherwise documented, it returns C<1> for true and
 C<''> for false.  If the file doesn't exist or can't be examined, it
 returns L<C<undef>|/undef EXPR> and sets L<C<$!>|perlvar/$!> (errno).
+With the exception of the C<-l> test they all follow symbolic links
+because they use C<stat()> and not C<lstat()> (so dangling symlinks can't
+be examined and will therefore report failure).
+
 Despite the funny names, precedence is the same as any other named unary
 operator.  The operator may be any of:
 
@@ -814,8 +818,8 @@ translation and marking it as bytes (as opposed to Unicode characters).
 Note that, despite what may be implied in I<"Programming Perl"> (the
 Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
 Other layers that would affect the binary nature of the stream are
-I<also> disabled.  See L<PerlIO>, L<perlrun>, and the discussion about the
-PERLIO environment variable.
+I<also> disabled.  See L<PerlIO>, and the discussion about the PERLIO
+environment variable in L<perlrun|perlrun/PERLIO>.
 
 The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
 form C<:...>, are called I/O I<layers>.  The L<open> pragma can be used to
@@ -943,6 +947,10 @@ list context, caller returns
        # 0         1          2
     my ($package, $filename, $line) = caller;
 
+Like L<C<__FILE__>|/__FILE__> and L<C<__LINE__>|/__LINE__>, the filename and
+line number returned here may be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
+
 With EXPR, it returns some extra information that the debugger uses to
 print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
@@ -1224,9 +1232,10 @@ change your current working directory, which is unaffected.)  For security
 reasons, this call is restricted to the superuser.  If FILENAME is
 omitted, does a L<C<chroot>|/chroot FILENAME> to L<C<$_>|perlvar/$_>.
 
-B<NOTE:>  It is good security practice to do C<chdir("/")>
+B<NOTE:>  It is mandatory for security to C<chdir("/")>
 (L<C<chdir>|/chdir EXPR> to the root directory) immediately after a
-L<C<chroot>|/chroot FILENAME>.
+L<C<chroot>|/chroot FILENAME>, otherwise the current working directory
+may be outside of the new root.
 
 Portability issues: L<perlport/chroot>.
 
@@ -1904,7 +1913,7 @@ X<dump> X<core> X<undump>
 =for Pod::Functions create an immediate core dump
 
 This function causes an immediate core dump.  See also the B<-u>
-command-line switch in L<perlrun>, which does the same thing.
+command-line switch in L<perlrun|perlrun/-u>, which does the same thing.
 Primarily this is so that you can use the B<undump> program (not
 supplied) to turn your core dump into an executable binary after
 having initialized all your variables at the beginning of the
@@ -2302,7 +2311,7 @@ Examples:
 If you want to trap errors when loading an XS module, some problems with
 the binary interface (such as Perl version skew) may be fatal even with
 C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set.  See
-L<perlrun>.
+L<perlrun|perlrun/PERL_DL_NONLAZY>.
 
 Using the C<eval {}> form as an exception trap in libraries does have some
 issues.  Due to the current arguably broken state of C<__DIE__> hooks, you
@@ -2616,8 +2625,8 @@ L<Unicode::UCD/B<prop_invmap()>>.
 For further information on casefolding, refer to
 the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
 4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
-available at L<http://www.unicode.org/versions/latest/>, as well as the
-Case Charts available at L<http://www.unicode.org/charts/case/>.
+available at L<https://www.unicode.org/versions/latest/>, as well as the
+Case Charts available at L<https://www.unicode.org/charts/case/>.
 
 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
 
@@ -2696,6 +2705,8 @@ X<__FILE__>
 =for Pod::Functions the name of the current source file
 
 A special token that returns the name of the file in which it occurs.
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
 
 =item fileno FILEHANDLE
 X<fileno>
@@ -3950,6 +3961,8 @@ X<__LINE__>
 =for Pod::Functions the current source line number
 
 A special token that compiles to the current line number.
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
 
 =item link OLDFILE,NEWFILE
 X<link>
@@ -4481,9 +4494,10 @@ indicate that you want both read and write access to the file; thus
 C<< +< >> is almost always preferred for read/write updates--the
 C<< +> >> mode would clobber the file first.  You can't usually use
 either read-write mode for updating textfiles, since they have
-variable-length records.  See the B<-i> switch in L<perlrun> for a
-better approach.  The file is created with permissions of C<0666>
-modified by the process's L<C<umask>|/umask EXPR> value.
+variable-length records.  See the B<-i> switch in
+L<perlrun|perlrun/-i[extension]> for a better approach.  The file is
+created with permissions of C<0666> modified by the process's
+L<C<umask>|/umask EXPR> value.
 
 These various prefixes correspond to the L<fopen(3)> modes of C<r>,
 C<r+>, C<w>, C<w+>, C<a>, and C<a+>.
@@ -6032,7 +6046,7 @@ This protects against those locales where characters such as C<"|"> are
 considered to be word characters.
 
 Otherwise, Perl quotes non-ASCII characters using an adaptation from
-Unicode (see L<http://www.unicode.org/reports/tr31/>).
+Unicode (see L<https://www.unicode.org/reports/tr31/>).
 The only code points that are quoted are those that have any of the
 Unicode properties:  Pattern_Syntax, Pattern_White_Space, White_Space,
 Default_Ignorable_Code_Point, or General_Category=Control.
@@ -6266,7 +6280,7 @@ multi-line) string.  In list context, returns a list of lines
 C<$INPUT_RECORD_SEPARATOR> in L<English>)).
 This is the internal function implementing the C<qx/EXPR/>
 operator, but you can use it directly.  The C<qx/EXPR/>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
+operator is discussed in more detail in L<perlop/"C<qx/I<STRING>/>">.
 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
 
 =item recv SOCKET,SCALAR,LENGTH,FLAGS
@@ -6375,7 +6389,9 @@ C<HASH>, C<CODE>, C<FORMAT>, or C<IO>, indicating only which kind of
 object it is.  If the unblessed referent is a scalar, then the return
 value will be one of the strings C<SCALAR>, C<VSTRING>, C<REF>, C<GLOB>,
 C<LVALUE>, or C<REGEXP>, depending on the kind of value the scalar
-currently has.  Beware that these built-in type names can also be used as
+currently has.   But note that C<qr//> scalars are created already
+blessed, so C<ref qr/.../> will likely return C<Regexp>.  Beware that
+these built-in type names can also be used as
 class names, so C<ref> returning one of these names doesn't unambiguously
 indicate that the referent is of the kind to which the name refers.
 
@@ -6648,7 +6664,8 @@ Generally used in a L<C<continue>|/continue BLOCK> block at the end of a
 loop to clear variables and reset C<m?pattern?> searches so that they
 work again.  The
 expression is interpreted as a list of single characters (hyphens
-allowed for ranges).  All variables and arrays beginning with one of
+allowed for ranges).  All variables (scalars, arrays, and hashes)
+in the current package beginning with one of
 those letters are reset to their pristine state.  If the expression is
 omitted, one-match searches (C<m?pattern?>) are reset to match again.
 Only resets variables or searches in the current package.  Always returns
@@ -6661,6 +6678,7 @@ Only resets variables or searches in the current package.  Always returns
 Resetting C<"A-Z"> is not recommended because you'll wipe out your
 L<C<@ARGV>|perlvar/@ARGV> and L<C<@INC>|perlvar/@INC> arrays and your
 L<C<%ENV>|perlvar/%ENV> hash.
+
 Resets only package variables; lexical variables are unaffected, but
 they clean themselves up on scope exit anyway, so you'll probably want
 to use them instead.  See L<C<my>|/my VARLIST>.
@@ -6674,8 +6692,8 @@ X<return>
 
 Returns from a subroutine, L<C<eval>|/eval EXPR>,
 L<C<do FILE>|/do EXPR>, L<C<sort>|/sort SUBNAME LIST> block or regex
-eval block (but not a L<C<grep>|/grep BLOCK LIST> or
-L<C<map>|/map BLOCK LIST> block) with the value
+eval block (but not a L<C<grep>|/grep BLOCK LIST>,
+L<C<map>|/map BLOCK LIST>, or L<C<do BLOCK>|/do BLOCK> block) with the value
 given in EXPR.  Evaluation of EXPR may be in list, scalar, or void
 context, depending on how the return value will be used, and the context
 may vary from one execution to the next (see
@@ -6781,8 +6799,8 @@ X<say>
 =for Pod::Functions +say output a list to a filehandle, appending a newline
 
 Just like L<C<print>|/print FILEHANDLE LIST>, but implicitly appends a
-newline.  C<say LIST> is simply an abbreviation for
-C<{ local $\ = "\n"; print LIST }>.  To use FILEHANDLE without a LIST to
+newline at the end of the LIST instead of any value L<C<$\>|perlvar/$\>
+might have.  To use FILEHANDLE without a LIST to
 print the contents of L<C<$_>|perlvar/$_> to it, you must use a bareword
 filehandle like C<FH>, not an indirect one like C<$fh>.
 
@@ -8057,8 +8075,8 @@ as supported by the compiler used to build Perl:
    h           interpret integer as C type "short" or
                "unsigned short"
    j           interpret integer as C type "intmax_t" on Perl
-               5.14 or later; and only with a C99 compiler
-               prior to Perl 5.30 (unportable)
+               5.14 or later; and prior to Perl 5.30, only with
+               a C99 compiler (unportable)
    l           interpret integer as C type "long" or
                "unsigned long"
    q, L, or ll interpret integer as C type "long long",
@@ -8725,7 +8743,7 @@ X<sysseek> X<lseek>
 
 Sets FILEHANDLE's system position I<in bytes> using L<lseek(2)>.  FILEHANDLE may
 be an expression whose value gives the name of the filehandle.  The values
-for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it
+for WHENCE are C<0> to set the new position to POSITION; C<1> to set it
 to the current position plus POSITION; and C<2> to set it to EOF plus
 POSITION, typically negative.
 
@@ -9507,9 +9525,10 @@ I<only> meant to be used to assert that the running Perl is of a earlier
 version than its argument and I<not> to undo the feature-enabling side effects
 of C<use VERSION>.
 
-See L<perlmodlib> for a list of standard modules and pragmas.  See L<perlrun>
-for the C<-M> and C<-m> command-line options to Perl that give
-L<C<use>|/use Module VERSION LIST> functionality from the command-line.
+See L<perlmodlib> for a list of standard modules and pragmas.  See
+L<perlrun|perlrun/-m[-]module> for the C<-M> and C<-m> command-line
+options to Perl that give L<C<use>|/use Module VERSION LIST>
+functionality from the command-line.
 
 =item utime LIST
 X<utime>
@@ -9661,10 +9680,8 @@ to try to write off the beginning of the string (i.e., negative OFFSET).
 If the string happens to be encoded as UTF-8 internally (and thus has
 the UTF8 flag set), L<C<vec>|/vec EXPR,OFFSET,BITS> tries to convert it
 to use a one-byte-per-character internal representation. However, if the
-string contains characters with values of 256 or higher, that conversion
-will fail, and a deprecation message will be raised.  In that situation,
-C<vec> will operate on the underlying buffer regardless, in its internal
-UTF-8 representation.  In Perl 5.32, this will be a fatal error.
+string contains characters with values of 256 or higher, a fatal error
+will occur.
 
 Strings created with L<C<vec>|/vec EXPR,OFFSET,BITS> can also be
 manipulated with the logical