integrate cfgperl contents into mainline

p4raw-id: //depot/perl@5822

6 files changed, 204 insertions, 69 deletions

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index c13dcde6ff..32e77d6f07 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -897,6 +897,13 @@ Creates a new SV which is an exact duplicate of the original SV.
 
 	SV*	newSVsv(SV* old)
 
+=item newSVuv
+
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
+
+	SV*	newSVuv(UV u)
+
 =item newXS
 
 Used by C<xsubpp> to hook up XSUBs as Perl subs.
@@ -1590,17 +1597,17 @@ false, defined or undefined.  Does not handle 'get' magic.
 
 	bool	SvTRUE(SV* sv)
 
+=item svtype
+
+An enum of flags for Perl types.  These are found in the file B<sv.h> 
+in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
+
 =item SvTYPE
 
 Returns the type of the SV.  See C<svtype>.
 
 	svtype	SvTYPE(SV* sv)
 
-=item svtype
-
-An enum of flags for Perl types.  These are found in the file B<sv.h> 
-in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
-
 =item SVt_IV
 
 Integer type flag for scalars.  See C<svtype>.
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index e7eab2b3a9..147bbc1edb 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -206,6 +206,19 @@ will produce different results on platforms that have different
 $Config{ivsize}.  For portability, be sure to mask off the excess bits
 in the result of unary C<~>, e.g., C<~$x & 0xffffffff>.
 
+=head2 The passwd and shell returned by the getpwxxx() are now tainted
+
+Because the user can affect her own encrypted password and login shell
+the password and shell returned by the getpwent(), getpwnam(), and
+getpwuid() functions are tainted.
+
+=head2 The msgrcv() and shmread() now taint
+
+Because other (untrusted) processes can modify messages and shared
+memory segments for their own nefarious purposes, the messages
+returned by msgrcv() (and its object-oriented interface,
+IPC::SysV::Msg::rcv) and the variable modified by shmread() are tainted.
+
 =back
 
 =head2 C Source Incompatibilities
@@ -535,7 +548,7 @@ See L<perldata/"Scalar value constructors"> for additional information.
 
 =head2 Weak references
 
-    WARNING: This is an experimental feature.
+    WARNING: This is an experimental feature.  Details are subject to change.  
 
 In previous versions of Perl, you couldn't cache objects so as
 to allow them to be deleted if the last reference from outside 
@@ -2632,6 +2645,70 @@ warning.  And in Perl 5.005, this special treatment will cease.
 
 =back
 
+=head1 Known Problems
+
+=head2 Thread tests failing
+
+The subtests 19 and 20 of the lib/thread test are known to fail in
+many platforms.
+
+=head2 EBCDIC platforms not supported
+
+In earlier releases of Perl the EBCDIC environments like OS390 (also
+known as Open Edition MVS) and VM-ESA were supported.  Due to the
+changes required by the UTF-8 (Unicode) support in Perl 5.6 the EBCDIC
+platforms are not supported in Perl 5.6.0.
+
+=head2 NEXTSTEP 3.3 POSIX test failure
+
+In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the
+operating system libraries is buggy: the %j format numbers the days of
+a month starting from zero, which, while being logical to programmers,
+will cause the subtests 19 to 27 of the lib/posix test may fail.
+
+=head2 UNICOS/mk CC failures during Configure run
+
+In UNICOS/mk the following errors may appear during the Configure run:
+
+	Guessing which symbols your C compiler and preprocessor define...
+	CC-20 cc: ERROR File = try.c, Line = 3
+	...
+	  bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
+	...
+	4 errors detected in the compilation of "try.c".
+
+The culprit is the broken awk of UNICOS/mk.  The effect is fortunately
+rather mild: Perl itself is not adversely affected by the error, only
+the h2ph utility coming with Perl, and that is rather rarely needed
+these days.
+
+=head2 Many features still experimental
+
+As discussed above, many features are still experimental, to a greater
+or lesser degree.  Interfaces and implementation are subject to
+change, in extreme cases even subject to removal in some future
+release of Perl.  These features include the following:
+
+=over 4
+
+=item Threads
+
+=item Unicode
+
+=item Lvalue subroutines
+
+=item Weak references
+
+=item File globbing now implemented internally
+
+=item The Compiler suite
+
+=item the DB module
+
+=item the regular expression constructs C<(?{ code })> and C<(??{ code })>
+
+=back
+
 =head1 BUGS
 
 If you find what you think is a bug, you might check the
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index f14b8bb04b..2c96d1d310 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1859,6 +1859,14 @@ various get routines are as follows:
 
 (If the entry doesn't exist you get a null list.)
 
+The exact meaning of the $gcos field varies but it usually contains
+the real name of the user (as opposed to the login name) and other
+information pertaining to the user.  Beware, however, that in many
+system users are able to change this information and therefore it
+cannot be trusted and therefore the $gcos is is tainted (see
+L<perlsec>).  The $passwd and $shell, user's encrypted password and
+login shell, are also tainted, because of the same reason.
+
 In scalar context, you get the name, unless the function was a
 lookup by name, in which case you get the other thing, whatever it is.
 (If the entry doesn't exist you get the undefined value.)  For example:
@@ -1871,26 +1879,25 @@ lookup by name, in which case you get the other thing, whatever it is.
     $name  = getgrent();
     #etc.
 
-In I<getpw*()> the fields $quota, $comment, and $expire are
-special cases in the sense that in many systems they are unsupported.
-If the $quota is unsupported, it is an empty scalar.  If it is
-supported, it usually encodes the disk quota.  If the $comment
-field is unsupported, it is an empty scalar.  If it is supported it
-usually encodes some administrative comment about the user.  In some
-systems the $quota field may be $change or $age, fields that have
-to do with password aging.  In some systems the $comment field may
-be $class.  The $expire field, if present, encodes the expiration
-period of the account or the password.  For the availability and the
-exact meaning of these fields in your system, please consult your
-getpwnam(3) documentation and your F<pwd.h> file.  You can also find
-out from within Perl what your $quota and $comment fields mean
-and whether you have the $expire field by using the C<Config> module
-and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>,
-and C<d_pwexpire>.  Shadow password files are only supported if your
-vendor has implemented them in the intuitive fashion that calling the
-regular C library routines gets the shadow versions if you're running
-under privilege.  Those that incorrectly implement a separate library
-call are not supported.
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported.  If the
+$quota is unsupported, it is an empty scalar.  If it is supported, it
+usually encodes the disk quota.  If the $comment field is unsupported,
+it is an empty scalar.  If it is supported it usually encodes some
+administrative comment about the user.  In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging.  In some systems the $comment field may be $class.  The $expire
+field, if present, encodes the expiration period of the account or the
+password.  For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+F<pwd.h> file.  You can also find out from within Perl what your
+$quota and $comment fields mean and whether you have the $expire field
+by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
+C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
+files are only supported if your vendor has implemented them in the
+intuitive fashion that calling the regular C library routines gets the
+shadow versions if you're running under privilege.  Those that
+incorrectly implement a separate library call are not supported.
 
 The $members value returned by I<getgr*()> is a space separated list of
 the login names of the members of the group.
@@ -2490,22 +2497,25 @@ Calls the System V IPC function msgget(2).  Returns the message queue
 id, or the undefined value if there is an error.  See also C<IPC::SysV>
 and C<IPC::Msg> documentation.
 
-=item msgsnd ID,MSG,FLAGS
-
-Calls the System V IPC function msgsnd to send the message MSG to the
-message queue ID.  MSG must begin with the native long integer message
-type, which may be created with C<pack("l!", $type)>.  Returns true if
-successful, or false if there is an error.  See also C<IPC::SysV> and
-C<IPC::SysV::Msg> documentation.
-
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
 
 Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
-SIZE.  Note that if a message is received, the message type will be
-the first thing in VAR, and the maximum length of VAR is SIZE plus the
-size of the message type.  Returns true if successful, or false if
-there is an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
+SIZE.  Note that when a message is received, the message type as a
+native long integer will be the first thing in VAR, followed by the
+actual message.  This packing may be opened with C<unpack("l! a*")>.
+Taints the variable.  Returns true if successful, or false if there is
+an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
+
+=item msgsnd ID,MSG,FLAGS
+
+Calls the System V IPC function msgsnd to send the message MSG to the
+message queue ID.  MSG must begin with the native long integer message
+type, and be followed by the length of the actual message, and finally
+the message itself.  This kind of packing can be achieved with
+C<pack("l! a*", $type, $message)>.  Returns true if successful,
+or false if there is an error.  See also C<IPC::SysV>
+and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
@@ -4015,8 +4025,8 @@ detaching from it.  When reading, VAR must be a variable that will
 hold the data read.  When writing, if STRING is too long, only SIZE
 bytes are used; if STRING is too short, nulls are written to fill out
 SIZE bytes.  Return true if successful, or false if there is an error.
-See also C<IPC::SysV> documentation and the C<IPC::Shareable> module
-from CPAN.
+shmread() taints the variable. See also C<IPC::SysV> documentation and
+the C<IPC::Shareable> module from CPAN.
 
 =item shutdown SOCKET,HOW
 
diff --git a/pod/perlipc.pod b/pod/perlipc.pod
index a9c7e48106..8760257821 100644
--- a/pod/perlipc.pod
+++ b/pod/perlipc.pod
@@ -1305,16 +1305,16 @@ you weren't wanting it to.
 
 Here's a small example showing shared memory usage.
 
-    use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU S_IRWXG S_IRWXO);
+    use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU);
 
     $size = 2000;
-    $key = shmget(IPC_PRIVATE, $size, S_IRWXU|S_IRWXG|S_IRWXO) || die "$!";
-    print "shm key $key\n";
+    $id = shmget(IPC_PRIVATE, $size, S_IRWXU) || die "$!";
+    print "shm key $id\n";
 
     $message = "Message #1";
-    shmwrite($key, $message, 0, 60) || die "$!";
+    shmwrite($id, $message, 0, 60) || die "$!";
     print "wrote: '$message'\n";
-    shmread($key, $buff, 0, 60) || die "$!";
+    shmread($id, $buff, 0, 60) || die "$!";
     print "read : '$buff'\n";
 
     # the buffer of shmread is zero-character end-padded.
@@ -1322,16 +1322,16 @@ Here's a small example showing shared memory usage.
     print "un" unless $buff eq $message;
     print "swell\n";
 
-    print "deleting shm $key\n";
-    shmctl($key, IPC_RMID, 0) || die "$!";
+    print "deleting shm $id\n";
+    shmctl($id, IPC_RMID, 0) || die "$!";
 
 Here's an example of a semaphore:
 
     use IPC::SysV qw(IPC_CREAT);
 
     $IPC_KEY = 1234;
-    $key = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!";
-    print "shm key $key\n";
+    $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!";
+    print "shm key $id\n";
 
 Put this code in a separate file to be run in more than one process.
 Call the file F<take>:
@@ -1339,8 +1339,8 @@ Call the file F<take>:
     # create a semaphore
 
     $IPC_KEY = 1234;
-    $key = semget($IPC_KEY,  0 , 0 );
-    die if !defined($key);
+    $id = semget($IPC_KEY,  0 , 0 );
+    die if !defined($id);
 
     $semnum = 0;
     $semflag = 0;
@@ -1348,14 +1348,14 @@ Call the file F<take>:
     # 'take' semaphore
     # wait for semaphore to be zero
     $semop = 0;
-    $opstring1 = pack("sss", $semnum, $semop, $semflag);
+    $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
 
     # Increment the semaphore count
     $semop = 1;
-    $opstring2 = pack("sss", $semnum, $semop,  $semflag);
+    $opstring2 = pack("s!s!s!", $semnum, $semop,  $semflag);
     $opstring = $opstring1 . $opstring2;
 
-    semop($key,$opstring) || die "$!";
+    semop($id,$opstring) || die "$!";
 
 Put this code in a separate file to be run in more than one process.
 Call this file F<give>:
@@ -1365,22 +1365,53 @@ Call this file F<give>:
     # that the second process continues
 
     $IPC_KEY = 1234;
-    $key = semget($IPC_KEY, 0, 0);
-    die if !defined($key);
+    $id = semget($IPC_KEY, 0, 0);
+    die if !defined($id);
 
     $semnum = 0;
     $semflag = 0;
 
     # Decrement the semaphore count
     $semop = -1;
-    $opstring = pack("sss", $semnum, $semop, $semflag);
+    $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
 
-    semop($key,$opstring) || die "$!";
+    semop($id,$opstring) || die "$!";
 
 The SysV IPC code above was written long ago, and it's definitely
 clunky looking.  For a more modern look, see the IPC::SysV module
 which is included with Perl starting from Perl 5.005.
 
+A small example demonstrating SysV message queues:
+
+    use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU);
+
+    my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRWXU);
+
+    my $sent = "message";
+    my $type = 1234;
+    my $rcvd;
+    my $type_rcvd;
+
+    if (defined $id) {
+        if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) {
+            if (msgrcv($id, $rcvd, 60, 0, 0)) {
+                ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd);
+                if ($rcvd eq $sent) {
+                    print "okay\n";
+                } else {
+                    print "not okay\n";
+                }
+            } else {
+                die "# msgrcv failed\n";
+            }
+        } else {
+            die "# msgsnd failed\n";
+        }
+        msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n";
+    } else {
+        die "# msgget failed\n";
+    }
+
 =head1 NOTES
 
 Most of these routines quietly but politely return C<undef> when they
diff --git a/pod/perlsec.pod b/pod/perlsec.pod
index 40374870a1..4185e84803 100644
--- a/pod/perlsec.pod
+++ b/pod/perlsec.pod
@@ -32,17 +32,19 @@ program more secure than the corresponding C program.
 You may not use data derived from outside your program to affect
 something else outside your program--at least, not by accident.  All
 command line arguments, environment variables, locale information (see
-L<perllocale>), results of certain system calls (readdir, readlink,
-the gecos field of getpw* calls), and all file input are marked as
-"tainted".  Tainted data may not be used directly or indirectly in any
-command that invokes a sub-shell, nor in any command that modifies
-files, directories, or processes. (B<Important exception>: If you pass
-a list of arguments to either C<system> or C<exec>, the elements of
-that list are B<NOT> checked for taintedness.) Any variable set
-to a value derived from tainted data will itself be tainted,
-even if it is logically impossible for the tainted data
-to alter the variable.  Because taintedness is associated with each
-scalar value, some elements of an array can be tainted and others not.
+L<perllocale>), results of certain system calls (readdir(),
+readlink(), the variable of shmread(), the messages returned by
+msgrcv(), the password, gcos and shell fields returned by the
+getpwxxx() calls), and all file input are marked as "tainted".
+Tainted data may not be used directly or indirectly in any command
+that invokes a sub-shell, nor in any command that modifies files,
+directories, or processes. (B<Important exception>: If you pass a list
+of arguments to either C<system> or C<exec>, the elements of that list
+are B<NOT> checked for taintedness.) Any variable set to a value
+derived from tainted data will itself be tainted, even if it is
+logically impossible for the tainted data to alter the variable.
+Because taintedness is associated with each scalar value, some
+elements of an array can be tainted and others not.
 
 For example:
 
diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod
index 88849dd662..0314d9da6c 100644
--- a/pod/perlthrtut.pod
+++ b/pod/perlthrtut.pod
@@ -4,6 +4,14 @@ perlthrtut - tutorial on threads in Perl
 
 =head1 DESCRIPTION
 
+    WARNING: Threading is an experimental feature.  Both the interface
+    and implementation are subject to change drastically.  In fact, this
+    documentation describes the flavor of threads that was in version
+    5.005.  Perl 5.6.0 and later have the beginnings of support for
+    interpreter threads, which (when finished) is expected to be
+    significantly different from what is described here.  The information
+    contained here may therefore soon be obsolete.  Use at your own risk!
+
 One of the most prominent new features of Perl 5.005 is the inclusion
 of threads.  Threads make a number of things a lot easier, and are a
 very useful addition to your bag of programming tricks.