Integrate from maint-5.8 : changes 18290-1, 18293-5, 18297

p4raw-id: //depot/perl@18299
p4raw-integrated: from //depot/maint-5.8/perl@18298 'copy in'
	pod/perlretut.pod (@17645..) pod/perlre.pod (@18080..)
	ext/POSIX/t/is.t (@18189..) t/op/subst.t (@18214..)
	ext/POSIX/t/posix.t (@18271..) t/op/pat.t (@18276..)
	ext/POSIX/POSIX.pod (@18294..) 'merge in' regexec.c (@18095..)

3 files changed, 82 insertions, 63 deletions

diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod
index a4550855a0..4d1ded6d56 100644
--- a/ext/POSIX/POSIX.pod
+++ b/ext/POSIX/POSIX.pod
@@ -580,15 +580,20 @@ see L<perlfunc/gmtime>.
 
 =item isalnum
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:alnum:]]/> construct instead, or possibly the C</\w/> construct.
+This is identical to the C function, except that it can apply to a
+single character or to a whole string.  Note that locale settings may
+affect what characters are considered C<isalnum>.  Does not work on
+Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:alnum:]]/> construct instead, or possibly
+the C</\w/> construct.
 
 =item isalpha
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:alpha:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isalpha>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:alpha:]]/> construct instead.
 
 =item isatty
 
@@ -597,60 +602,82 @@ to a tty.  Similar to the C<-t> operator, see L<perlfunc/-X>.
 
 =item iscntrl
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:cntrl:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<iscntrl>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:cntrl:]]/> construct instead.
 
 =item isdigit
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:digit:]]/> construct instead, or the C</\d/> construct.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isdigit> (unlikely, but
+still possible). Does not work on Unicode characters code point 256
+or higher.  Consider using regular expressions and the C</[[:digit:]]/>
+construct instead, or the C</\d/> construct.
 
 =item isgraph
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:graph:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isgraph>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:graph:]]/> construct instead.
 
 =item islower
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:lower:]]/> construct instead.  Do B<not> use C</[a-z]/>.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<islower>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:lower:]]/> construct instead.  Do B<not> use
+C</[a-z]/>.
 
 =item isprint
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:print:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isprint>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:print:]]/> construct instead.
 
 =item ispunct
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:punct:]]/> construct instead.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<ispunct>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:punct:]]/> construct instead.
 
 =item isspace
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:space:]]/> construct instead, or the C</\s/> construct.
-(Note that C</\s/> and C</[[:space:]]/> are slightly different in that
-C</[[:space:]]/> can normally match a vertical tab, while C</\s/> does
-not.)
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isspace>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:space:]]/> construct instead, or the C</\s/>
+construct.  (Note that C</\s/> and C</[[:space:]]/> are slightly
+different in that C</[[:space:]]/> can normally match a vertical tab,
+while C</\s/> does not.)
 
 =item isupper
 
-This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:upper:]]/> construct instead.  Do B<not> use C</[A-Z]/>.
+This is identical to the C function, except that it can apply to
+a single character or to a whole string.  Note that locale settings
+may affect what characters are considered C<isupper>.  Does not work
+on Unicode characters code point 256 or higher.  Consider using regular
+expressions and the C</[[:upper:]]/> construct instead.  Do B<not> use
+C</[A-Z]/>.
 
 =item isxdigit
 
 This is identical to the C function, except that it can apply to a single
-character or to a whole string.  Consider using regular expressions and the
-C</[[:xdigit:]]/> construct instead, or simply C</[0-9a-f]/i>.
+character or to a whole string.  Note that locale settings may affect what
+characters are considered C<isxdigit> (unlikely, but still possible).
+Does not work on Unicode characters code point 256 or higher.
+Consider using regular expressions and the C</[[:xdigit:]]/>
+construct instead, or simply C</[0-9a-f]/i>.
 
 =item kill
 
@@ -1224,12 +1251,23 @@ I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1.  The
 year (C<year>) is given in years since 1900.  I.e., the year 1995 is 95; the
 year 2001 is 101.  Consult your system's C<strftime()> manpage for details
 about these and the other arguments.
+
 If you want your code to be portable, your format (C<fmt>) argument
 should use only the conversion specifiers defined by the ANSI C
-standard.  These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
-The given arguments are made consistent
-as though by calling C<mktime()> before calling your system's
-C<strftime()> function, except that the C<isdst> value is not affected.
+standard (C89, to play safe).  These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
+But even then, the B<results> of some of the conversion specifiers are
+non-portable.  For example, the specifiers C<aAbBcpZ> change according
+to the locale settings of the user, and both how to set locales (the
+locale names) and what output to expect are non-standard.
+The specifier C<c> changes according to the timezone settings of the
+user and the timezone computation rules of the operating system.
+The C<Z> specifier is notoriously unportable since the names of
+timezones are non-standard. Sticking to the numeric specifiers is the
+safest route.
+
+The given arguments are made consistent as though by calling
+C<mktime()> before calling your system's C<strftime()> function,
+except that the C<isdst> value is not affected.
 
 The string for Tuesday, December 12, 1995.
 
diff --git a/ext/POSIX/t/is.t b/ext/POSIX/t/is.t
index 6aa96f0b7c..9ab851cd4e 100644
--- a/ext/POSIX/t/is.t
+++ b/ext/POSIX/t/is.t
@@ -10,12 +10,14 @@ BEGIN {
     }
 }
 
-
 use POSIX;
 use strict ;
 
-$| = 1;
+# E.g. \t might or might not be isprint() depending on the locale,
+# so let's reset to the default.
+setlocale(LC_ALL, 'C') if $Config{d_setlocale};
 
+$| = 1;
 
 # List of characters (and strings) to feed to the is<xxx> functions.
 #
diff --git a/ext/POSIX/t/posix.t b/ext/POSIX/t/posix.t
index 9b0a751064..6ce418cccb 100644
--- a/ext/POSIX/t/posix.t
+++ b/ext/POSIX/t/posix.t
@@ -11,8 +11,7 @@ BEGIN {
 }
 
 require "./test.pl";
-plan(tests => 66);
-
+plan(tests => 61);
 
 use POSIX qw(fcntl_h signal_h limits_h _exit getcwd open read strftime write
 	     errno);
@@ -183,26 +182,6 @@ try_strftime("Wed Mar 01 00:00:00 2000 061", 0,0,0, 1,2,100);
 try_strftime("Fri Mar 31 00:00:00 2000 091", 0,0,0, 31,2,100);
 &POSIX::setlocale(&POSIX::LC_TIME, $lc) if $Config{d_setlocale};
 
-SKIP: {
-    # XXX wait for smokers to see which OSs else to skip
-    skip("No mktime and/or tm_gmtoff", 5)
-	if !$Config{d_mktime} || !$Config{d_tm_tm_gmtoff} || !$Config{d_tm_tm_zone};
-    local $ENV{TZ} = "Europe/Berlin";
-
-    # May fail for ancient FreeBSD versions.
-    # %z is not included in POSIX, but valid on Linux and FreeBSD.
-    foreach $def ([1000,'Sun Sep  9 03:46:40 2001 +0200 CEST'],
-		  [900, 'Thu Jul  9 18:00:00 1998 +0200 CEST'],
-		  [800, 'Tue May  9 08:13:20 1995 +0200 CEST'],
-		  [700, 'Sat Mar  7 21:26:40 1992 +0100 CET'],
-		  [600, 'Thu Jan  5 11:40:00 1989 +0100 CET'],
-		 ) {
-	my($t, $expected) = @$def;
-        my @tm = localtime($t*1000000);
-	is(strftime("%c %z %Z",@tm), $expected, "validating zone setting: $expected");
-    }
-}
-
 {
     for my $test (0, 1) {
 	$! = 0;