Change 14086 by gsar@rake on 2002/01/05 00:19:01
integrate changes from maint-5.6/macperl branch
Affected files ...
.... //depot/maint-5.6/perl/ext/IO/IO.xs#4 integrate
.... //depot/maint-5.6/perl/lib/File/Find.pm#11 integrate
.... //depot/maint-5.6/perl/lib/File/Spec/Mac.pm#7 integrate
.... //depot/maint-5.6/perl/lib/Pod/Html.pm#4 integrate
.... //depot/maint-5.6/perl/pod/perlmodinstall.pod#4 integrate
.... //depot/maint-5.6/perl/pod/perlport.pod#25 integrate
Differences ...
==== //depot/maint-5.6/perl/ext/IO/IO.xs#4 (text) ====
Index: perl/ext/IO/IO.xs
--- perl/ext/IO/IO.xs.~1~ Fri Jan 4 17:30:05 2002
+++ perl/ext/IO/IO.xs Fri Jan 4 17:30:05 2002
@@ -18,6 +18,13 @@
#endif
#ifdef PerlIO
+#ifdef MACOS_TRADITIONAL
+#define PERLIO_IS_STDIO 1
+#undef setbuf
+#undef setvbuf
+#define setvbuf _stdsetvbuf
+#define setbuf(f,b) ( __sf_setbuf(f,b) )
+#endif
typedef int SysRet;
typedef PerlIO * InputStream;
typedef PerlIO * OutputStream;
==== //depot/maint-5.6/perl/lib/File/Find.pm#11 (text) ====
Index: perl/lib/File/Find.pm
--- perl/lib/File/Find.pm.~1~ Fri Jan 4 17:30:05 2002
+++ perl/lib/File/Find.pm Fri Jan 4 17:30:05 2002
@@ -2,7 +2,8 @@
use 5.006;
use strict;
use warnings;
-our $VERSION = '1.03';
+use warnings::register;
+our $VERSION = '1.04';
require Exporter;
require Cwd;
@@ -43,7 +44,7 @@
Reports the name of a directory only AFTER all its entries
have been reported. Entry point finddepth() is a shortcut for
-specifying C<{ bydepth => 1 }> in the first argument of find().
+specifying C<{ bydepth =E<gt> 1 }> in the first argument of find().
=item C<preprocess>
@@ -149,7 +150,22 @@
current filename within that directory. C<$File::Find::name> contains
the complete pathname to the file. You are chdir()'d to
C<$File::Find::dir> when the function is called, unless C<no_chdir>
-was specified. When C<follow> or C<follow_fast> are in effect, there is
+was specified. Note that when changing to directories is in effect
+the root directory (F</>) is a somewhat special case inasmuch as the
+concatenation of C<$File::Find::dir>, C<'/'> and C<$_> is not literally
+equal to C<$File::Find::name>. The table below summarizes all variants:
+
+ $File::Find::name $File::Find::dir $_
+ default / / .
+ no_chdir=>0 /etc / etc
+ /etc/x /etc x
+
+ no_chdir=>1 / / /
+ /etc / /etc
+ /etc/x /etc /etc/x
+
+
+When <follow> or <follow_fast> are in effect, there is
also a C<$File::Find::fullname>. The function may set
C<$File::Find::prune> to prune the tree unless C<bydepth> was
specified. Unless C<follow> or C<follow_fast> is specified, for
@@ -190,6 +206,17 @@
See also the script C<pfind> on CPAN for a nice application of this
module.
+=head1 WARNINGS
+
+If you run your program with the C<-w> switch, or if you use the
+C<warnings> pragma, File::Find will report warnings for several weird
+situations. You can disable these warnings by putting the statement
+
+ no warnings 'File::Find';
+
+in the appropriate scope. See L<perllexwarn> for more info about lexical
+warnings.
+
=head1 CAVEAT
=over 2
@@ -197,15 +224,16 @@
=item $dont_use_nlink
You can set the variable C<$File::Find::dont_use_nlink> to 1, if you want to
-force File::Find to always stat directories. This was used for systems
-that do not have the correct C<nlink> count for directories. Examples are
-ISO-9660 (CD-R), AFS, and operating systems like OS/2, DOS and a couple of
-others.
+force File::Find to always stat directories. This was used for file systems
+that do not have an C<nlink> count matching the number of sub-directories.
+Examples are ISO-9660 (CD-ROM), AFS, HPFS (OS/2 file system), FAT (DOS file
+system) and a couple of others.
-Since now File::Find should now detect such things on-the-fly and switch it
-self to using stat, this will probably not a problem to you.
+You shouldn't need to set this variable, since File::Find should now detect
+such file systems on-the-fly and switch itself to using stat. This works even
+for parts of your file system, like a mounted CD-ROM.
-If you do set $dont_use_nlink to 1, you will notice slow-downs.
+If you do set C<$File::Find::dont_use_nlink> to 1, you will notice slow-downs.
=item symlinks
@@ -452,7 +480,7 @@
return undef unless defined $DEV; # dangling symbolic link
}
- if ($full_check && $SLnkSeen{$DEV, $INO}++) {
+ if ($full_check && defined $DEV && $SLnkSeen{$DEV, $INO}++) {
if ( ($follow_skip < 1) || ((-d _) && ($follow_skip < 2)) ) {
die "$AbsName encountered a second time";
}
@@ -542,7 +570,7 @@
else {
$abs_dir = contract_name_Mac($cwd, $top_item);
unless (defined $abs_dir) {
- warn "Can't determine absolute path for $top_item (No such
file or directory)\n" if $^W;
+ warnings::warnif "Can't determine absolute path for $top_item
+(No such file or directory)\n";
next Proc_Top_Item;
}
}
@@ -565,7 +593,7 @@
if (ref $dangling_symlinks eq 'CODE') {
$dangling_symlinks->($top_item, $cwd);
} else {
- warn "$top_item is a dangling symbolic link\n" if $^W;
+ warnings::warnif "$top_item is a dangling symbolic link\n";
}
}
next Proc_Top_Item;
@@ -579,7 +607,7 @@
else { # no follow
$topdir = $top_item;
unless (defined $topnlink) {
- warn "Can't stat $top_item: $!\n" if $^W;
+ warnings::warnif "Can't stat $top_item: $!\n";
next Proc_Top_Item;
}
if (-d _) {
@@ -616,7 +644,7 @@
}
unless ($no_chdir || chdir $abs_dir) {
- warn "Couldn't chdir $abs_dir: $!\n" if $^W;
+ warnings::warnif "Couldn't chdir $abs_dir: $!\n";
next Proc_Top_Item;
}
@@ -684,7 +712,7 @@
}
}
unless (chdir $udir) {
- warn "Can't cd to $udir: $!\n" if $^W;
+ warnings::warnif "Can't cd to $udir: $!\n";
return;
}
}
@@ -727,10 +755,11 @@
}
unless (chdir $udir) {
if ($Is_MacOS) {
- warn "Can't cd to ($p_dir) $udir: $!\n" if $^W;
+ warnings::warnif "Can't cd to ($p_dir) $udir: $!\n";
}
else {
- warn "Can't cd to (" . ($p_dir ne '/' ? $p_dir : '') . "/) $udir:
$!\n" if $^W;
+ warnings::warnif "Can't cd to (" .
+ ($p_dir ne '/' ? $p_dir : '') . "/) $udir: $!\n";
}
next;
}
@@ -745,7 +774,7 @@
# Get the list of files in the current directory.
unless (opendir DIR, ($no_chdir ? $dir_name : $File::Find::current_dir)) {
- warn "Can't opendir($dir_name): $!\n" if $^W;
+ warnings::warnif "Can't opendir($dir_name): $!\n";
next;
}
@filenames = readdir DIR;
@@ -845,12 +874,12 @@
}
else {
if ( substr($name,-2) eq '/.' ) {
- $name =~ s|/\.$||;
+ substr($name, length($name) == 2 ? -1 : -2) = '';
}
$dir = $p_dir;
$_ = ($no_chdir ? $dir_name : $dir_rel );
if ( substr($_,-2) eq '/.' ) {
- s|/\.$||;
+ substr($_, length($_) == 2 ? -1 : -2) = '';
}
}
{ &$wanted_callback }; # protect against wild "next"
@@ -914,7 +943,7 @@
}
$ok = chdir($updir_loc) unless ($p_dir eq $File::Find::current_dir);
unless ($ok) {
- warn "Can't cd to $updir_loc: $!\n" if $^W;
+ warnings::warnif "Can't cd to $updir_loc: $!\n";
return;
}
}
@@ -931,7 +960,7 @@
# change (back) to parent directory (always untainted)
unless ($no_chdir) {
unless (chdir $updir_loc) {
- warn "Can't cd to $updir_loc: $!\n" if $^W;
+ warnings::warnif "Can't cd to $updir_loc: $!\n";
next;
}
}
@@ -962,7 +991,7 @@
}
}
unless (chdir $updir_loc) {
- warn "Can't cd to $updir_loc: $!\n" if $^W;
+ warnings::warnif "Can't cd to $updir_loc: $!\n";
next;
}
}
@@ -975,7 +1004,7 @@
# Get the list of files in the current directory.
unless (opendir DIR, ($no_chdir ? $dir_loc : $File::Find::current_dir)) {
- warn "Can't opendir($dir_loc): $!\n" if $^W;
+ warnings::warnif "Can't opendir($dir_loc): $!\n";
next;
}
@filenames = readdir DIR;
@@ -1020,7 +1049,7 @@
if ( $byd_flag < 0 ) { # must be finddepth, report dirname now
unless ($no_chdir || ($dir_rel eq $File::Find::current_dir)) {
unless (chdir $updir_loc) { # $updir_loc (parent dir) is always
untainted
- warn "Can't cd to $updir_loc: $!\n" if $^W;
+ warnings::warnif "Can't cd to $updir_loc: $!\n";
next;
}
}
@@ -1036,12 +1065,12 @@
}
else {
if ( substr($name,-2) eq '/.' ) {
- $name =~ s|/\.$||; # $File::Find::name
+ substr($name, length($name) == 2 ? -1 : -2) = ''; #
+$File::Find::name
}
$dir = $p_dir; # $File::Find::dir
$_ = ($no_chdir ? $dir_name : $dir_rel); # $_
if ( substr($_,-2) eq '/.' ) {
- s|/\.$||;
+ substr($_, length($_) == 2 ? -1 : -2) = '';
}
}
@@ -1108,7 +1137,7 @@
$File::Find::dont_use_nlink = 1
if $^O eq 'os2' || $^O eq 'dos' || $^O eq 'amigaos' || $^O eq 'MSWin32' ||
- $^O eq 'cygwin' || $^O eq 'epoc' || $^O eq 'NetWare';
+ $^O eq 'cygwin' || $^O eq 'epoc';
# Set dont_use_nlink in your hint file if your system's stat doesn't
# report the number of links in a directory as an indication
==== //depot/maint-5.6/perl/lib/File/Spec/Mac.pm#7 (text) ====
Index: perl/lib/File/Spec/Mac.pm
--- perl/lib/File/Spec/Mac.pm.~1~ Fri Jan 4 17:30:05 2002
+++ perl/lib/File/Spec/Mac.pm Fri Jan 4 17:30:05 2002
@@ -667,8 +667,8 @@
my $base_dirs = ($self->splitpath( $base ))[1] ;
# Now, remove all leading components that are the same
- my @pathchunks = $self->splitdir( $path_dirs ); # expected: ('')
- my @basechunks = $self->splitdir( $base_dirs ); # expected: (d1, d2)
+ my @pathchunks = $self->splitdir( $path_dirs );
+ my @basechunks = $self->splitdir( $base_dirs );
while ( @pathchunks &&
@basechunks &&
==== //depot/maint-5.6/perl/lib/Pod/Html.pm#4 (text) ====
Index: perl/lib/Pod/Html.pm
--- perl/lib/Pod/Html.pm.~1~ Fri Jan 4 17:30:05 2002
+++ perl/lib/Pod/Html.pm Fri Jan 4 17:30:05 2002
@@ -10,6 +10,7 @@
use Carp;
use Config;
use Cwd;
+use File::Spec;
use File::Spec::Unix;
use Getopt::Long;
use Pod::Functions;
@@ -213,7 +214,7 @@
# other files.
my $podfile = ""; # read from stdin by default
my @podpath = (); # list of directories containing library pods.
-my $podroot = "."; # filesystem base directory from which all
+my $podroot = File::Spec->curdir; # filesystem base directory from which
+all
# relative paths in $podpath stem.
my $css = ''; # Cascading style sheet
my $recurse = 1; # recurse on subdirectories in $podpath.
@@ -260,7 +261,7 @@
$htmlfile = ""; # write to stdout by default
$podfile = ""; # read from stdin by default
@podpath = (); # list of directories containing library pods.
-$podroot = "."; # filesystem base directory from which all
+$podroot = File::Spec->curdir; # filesystem base directory from which all
# relative paths in $podpath stem.
$css = ''; # Cascading style sheet
$recurse = 1; # recurse on subdirectories in $podpath.
==== //depot/maint-5.6/perl/pod/perlmodinstall.pod#4 (text) ====
Index: perl/pod/perlmodinstall.pod
--- perl/pod/perlmodinstall.pod.~1~ Fri Jan 4 17:30:05 2002
+++ perl/pod/perlmodinstall.pod Fri Jan 4 17:30:05 2002
@@ -5,23 +5,32 @@
=head1 DESCRIPTION
You can think of a module as the fundamental unit of reusable Perl
-code; See L<perlmod> for details. Whenever anyone creates a chunk
-of Perl code that they think will be useful to the world, they
-register as a Perl developer at
-http://www.perl.com/CPAN/modules/04pause.html so that they can then
-upload their code to CPAN. CPAN is the Comprehensive Perl Archive
-Network and can be accessed at http://www.perl.com/CPAN/, or searched
-via http://cpan.perl.com/ and
-http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
+code; see L<perlmod> for details. Whenever anyone creates a chunk of
+Perl code that they think will be useful to the world, they register
+as a Perl developer at http://www.cpan.org/modules/04pause.html
+so that they can then upload their code to the CPAN. The CPAN is the
+Comprehensive Perl Archive Network and can be accessed at
+http://www.cpan.org/ , and searched at http://search.cpan.org/ .
This documentation is for people who want to download CPAN modules
and install them on their own computer.
=head2 PREAMBLE
-You have a file ending in F<.tar.gz> (or, less often, F<.zip>).
-You know there's a tasty module inside. You must now take four
-steps:
+First, are you sure that the module isn't already on your system? Try
+C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
+instance, C<perl -MCGI::Carp -e 1>.
+
+If you don't see an error message, you have the module. (If you do
+see an error message, it's still possible you have the module, but
+that it's not in your path, which you can display with C<perl -e
+"print qq(@INC)">.) For the remainder of this document, we'll assume
+that you really honestly truly lack an installed module, but have
+found it on the CPAN.
+
+So now you have a file ending in .tar.gz (or, less often, .zip). You
+know there's a tasty module inside. There are four steps you must now
+take:
=over 5
@@ -36,28 +45,30 @@
=back
Here's how to perform each step for each operating system. This is
-I<not> a substitute for reading the README and INSTALL files that
+<not> a substitute for reading the README and INSTALL files that
might have come with your module!
Also note that these instructions are tailored for installing the
-module into your system's repository of Perl modules. But you can
+module into your system's repository of Perl modules -- but you can
install modules into any directory you wish. For instance, where I
-say C<perl Makefile.PL>, you can substitute C<perl
-Makefile.PL PREFIX=/my/perl_directory> to install the modules
-into C</my/perl_directory>. Then you can use the modules
-from your Perl programs with C<use lib
-"/my/perl_directory/lib/site_perl"> or sometimes just C<use
-"/my/perl_directory">.
+say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL
+PREFIX=/my/perl_directory> to install the modules into
+C</my/perl_directory>. Then you can use the modules from your Perl
+programs with C<use lib "/my/perl_directory/lib/site_perl";> or
+sometimes just C<use "/my/perl_directory";>. If you're on a system
+that requires superuser/root access to install modules into the
+directories you see when you type C<perl -e "print qq(@INC)">, you'll
+want to install them into a local directory (such as your home
+directory) and use this approach.
=over 4
=item *
-B<If you're on Unix,>
+B<If you're on a Unix or Linux system,>
You can use Andreas Koenig's CPAN module
-(which comes standard with Perl, or can itself be downloaded
-from http://www.perl.com/CPAN/modules/by-module/CPAN)
+( http://www.cpan.org/modules/by-module/CPAN )
to automate the following steps, from DECOMPRESS through INSTALL.
A. DECOMPRESS
@@ -82,33 +93,43 @@
make
make test
+or
+
+ perl Makefile.PL PREFIX=/my/perl_directory
+
+to install it locally. (Remember that if you do this, you'll have to
+put C<use lib "/my/perl_directory";> near the top of the program that
+is to use this module.
+
D. INSTALL
While still in that directory, type:
make install
-Make sure you have appropriate permissions to install the module
+Make sure you have the appropriate permissions to install the module
in your Perl 5 library directory. Often, you'll need to be root.
-Perl maintains a record of all module installations. To look at
-this list, simply type:
-
- perldoc perllocal
-
That's all you need to do on Unix systems with dynamic linking.
-Most Unix systems have dynamic linking--if yours doesn't, or if for
-another reason you have a statically-linked perl, I<and> the
+Most Unix systems have dynamic linking -- if yours doesn't, or if for
+another reason you have a statically-linked perl, B<and> the
module requires compilation, you'll need to build a new Perl binary
that includes the module. Again, you'll probably need to be root.
=item *
-B<If you're running Windows 95 or NT with the ActiveState port of Perl>
+B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
+
+First, type C<ppm> from a shell and see whether ActiveState's PPM
+repository has your module. If so, you can install it with C<ppm> and
+you won't have to bother with any of the other steps here. You might
+be able to use the CPAN instructions from the "Unix or Linux" section
+above as well; give it a try. Otherwise, you'll have to follow the
+steps below.
A. DECOMPRESS
-You can use the shareware B<Winzip> program ( http://www.winzip.com ) to
+You can use the shareware Winzip ( http://www.winzip.com ) to
decompress and unpack modules.
B. UNPACK
@@ -117,11 +138,12 @@
C. BUILD
-Does the module require compilation (i.e. does it have files
-that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, you're on
-your own. You can try compiling it yourself if you have a C compiler.
-If you're successful, consider uploading the resulting binary to
-CPAN for others to use. If it doesn't, go to INSTALL.
+Does the module require compilation (i.e. does it have files that end
+in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it doesn't, go to INSTALL.
+If it does, life is now officially tough for you, because you have to
+compile the module yourself -- no easy feat on Windows. You'll need
+the C<nmake> utility, available at
+ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe.
D. INSTALL
@@ -132,65 +154,16 @@
=item *
-B<If you're running Windows 95 or NT with the core Windows distribution of
-Perl,>
+B<If you're using a Macintosh,>
- A. DECOMPRESS
-When you download the module, make sure it ends in either
-F<.tar.gz> or F<.zip>. Windows browsers sometimes
-download C<.tar.gz> files as C<_tar.tar>, because
-early versions of Windows prohibited more than one dot in a filename.
-
-You can use the shareware B<WinZip> program ( http://www.winzip.com ) to
-decompress and unpack modules.
-
-Or, you can use InfoZip's C<unzip> utility (
-http://www.cdrom.com/pub/infozip/ ) to uncompress C<.zip> files; type
-C<unzip yourmodule.zip> in your shell.
-
-Or, if you have a working C<tar> and C<gzip>, you can
-type
-
- gzip -cd yourmodule.tar.gz | tar xvf -
-
-in the shell to decompress C<yourmodule.tar.gz>. This will
-UNPACK your module as well.
-
- B. UNPACK
-
-The methods in DECOMPRESS will have done this for you.
-
- C. BUILD
-
-Go into the newly-created directory and type:
-
- perl Makefile.PL
- dmake
- dmake test
-
-Depending on your perl configuration, C<dmake> might not be
-available. You might have to substitute whatever C<perl
--V:make> says. (Usually, that will be C<nmake> or
-C<make>.)
-
- D. INSTALL
-
-While still in that directory, type:
-
- dmake install
-
-=item *
-
-B<If you're using a Macintosh,>
-
A. DECOMPRESS
-First thing you should do is make sure you have the latest B<cpan-mac>
-distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has
-utilities for doing all of the steps. Read the cpan-mac directions
-carefully and install it. If you choose not to use cpan-mac
-for some reason, there are alternatives listed here.
+First, make sure you have the latest B<cpan-mac> distribution (
+http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
+doing all of the steps. Read the cpan-mac directions carefully and
+install it. If you choose not to use cpan-mac for some reason, there
+are alternatives listed here.
After installing cpan-mac, drop the module archive on the
B<untarzipme> droplet, which will decompress and unpack for you.
@@ -290,7 +263,7 @@
While still in that directory, type:
- make install
+ make install
You will need the packages mentioned in F<README.dos> in the Perl distribution.
@@ -306,8 +279,8 @@
B<If you're on VMS,>
-When downloading from CPAN, save your file with a F<.tgz>
-extension instead of F<.tar.gz>. All other periods in the
+When downloading from CPAN, save your file with a C<.tgz>
+extension instead of C<.tar.gz>. All other periods in the
filename should be replaced with underscores. For example,
C<Your-Module-1.33.tar.gz> should be downloaded as
C<Your-Module-1_33.tgz>.
@@ -322,12 +295,14 @@
unzip Your-Module.zip
-Executables for gzip, zip, and VMStar ( Alphas:
-http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen:
-http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ).
+Executables for gzip, zip, and VMStar:
+
+ http://www.openvms.digital.com/freeware/
+ http://www.crinoid.com/utils/
+
+and their source code:
-gzip and tar
-are also available at ftp://ftp.digital.com/pub/VMS.
+ http://www.fsf.org/order/ftp.html
Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
package. The former is a simple compression tool; the latter permits
@@ -345,9 +320,9 @@
C. BUILD
-Make sure you have MMS (from Digital) or the freeware MMK ( available from
-MadGoat at http://www.madgoat.com ). Then type this to create the
-DESCRIP.MMS for the module:
+Make sure you have MMS (from Digital) or the freeware MMK ( available
+from MadGoat at http://www.madgoat.com ). Then type this to create
+the DESCRIP.MMS for the module:
perl Makefile.PL
@@ -375,10 +350,10 @@
A. DECOMPRESS
- Decompress the file with C<gzip -d yourmodule.tar.gz>
+Decompress the file with C<gzip -d yourmodule.tar.gz>
- You can get gzip from
- http://www.s390.ibm.com/products/oe/bpxqp1.html.
+You can get gzip from
+http://www.s390.ibm.com/products/oe/bpxqp1.html
B. UNPACK
@@ -392,7 +367,6 @@
=back
-
=head1 PORTABILITY
Note that not all modules will work with on all platforms.
@@ -455,19 +429,17 @@
The Perl Journal, http://tpj.com
-with invaluable help from Brandon Allbery, Charles Bailey, Graham
-Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
-Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
-Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
-Sugalski, Larry Virden, and Ilya Zakharevich.
+with invaluable help from Chris Nandor, and valuable help from Brandon
+Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
+Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
+J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
+Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
-First version July 22, 1998
-
-Last Modified August 22, 2000
+First version July 22, 1998; last revised November 21, 2001.
=head1 COPYRIGHT
-Copyright (C) 1998, 2000 Jon Orwant. All Rights Reserved.
+Copyright (C) 1998, 2001 Jon Orwant. All Rights Reserved.
Permission is granted to make and distribute verbatim copies of this
documentation provided the copyright notice and this permission notice are
@@ -484,3 +456,4 @@
Permission is granted to copy and distribute translations of this
documentation into another language, under the above conditions for
modified versions.
+
==== //depot/maint-5.6/perl/pod/perlport.pod#25 (text) ====
Index: perl/pod/perlport.pod
--- perl/pod/perlport.pod.~1~ Fri Jan 4 17:30:05 2002
+++ perl/pod/perlport.pod Fri Jan 4 17:30:05 2002
@@ -267,6 +267,13 @@
separator, or go native and use C<.> for path separator and C<:> to
signal filesystems and disk names.
+Don't assume UNIX filesystem access semantics: that read, write,
+and execute are all the permissions there are, and even if they exist,
+that their semantics (for example what do r, w, and x mean on
+a directory) are the UNIX ones. The various UNIX/POSIX compatibility
+layers usually try to make interfaces like chmod() work, but sometimes
+there simply is no good mapping.
+
If all this is intimidating, have no (well, maybe only a little)
fear. There are modules that can help. The File::Spec modules
provide methods to do the Right Thing on whatever platform happens
@@ -423,13 +430,13 @@
The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
even on all Unix platforms.
-Do not use either the bare result of C<pack("N", 10, 20, 30, 40)>
-or bare v-strings (such as C<v10.20.30.40>) or to represent
-IPv4 addresses: both forms just pack the four bytes into network order.
-That this would be equal to the C language C<in_addr> struct (which is
-what the socket code internally uses) is not guaranteed. To be
-portable use the routines of the Socket extension, such as
-C<inet_aton()>, C<inet_ntoa()>, and C<sockaddr_in()>.
+Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
+bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
+both forms just pack the four bytes into network order. That this
+would be equal to the C language C<in_addr> struct (which is what the
+socket code internally uses) is not guaranteed. To be portable use
+the routines of the Socket extension, such as C<inet_aton()>,
+C<inet_ntoa()>, and C<sockaddr_in()>.
The rule of thumb for portable code is: Do it all in portable Perl, or
use a module (that may internally implement it with platform-specific
@@ -538,13 +545,31 @@
Most multi-user platforms provide basic levels of security, usually
implemented at the filesystem level. Some, however, do
-not--unfortunately. Thus the notion of user id, or "home" directory,
+not-- unfortunately. Thus the notion of user id, or "home" directory,
or even the state of being logged-in, may be unrecognizable on many
platforms. If you write programs that are security-conscious, it
is usually best to know what type of system you will be running
under so that you can write code explicitly for that platform (or
class of platforms).
+Don't assume the UNIX filesystem access semantics: the operating
+system or the filesystem may be using some ACL systems, which are
+richer languages than the usual rwx. Even if the rwx exist,
+their semantics might be different.
+
+(From security viewpoint testing for permissions before attempting to
+do something is silly anyway: if one tries this, there is potential
+for race conditions-- someone or something might change the
+permissions between the permissions check and the actual operation.
+Just try the operation.)
+
+Don't assume the UNIX user and group semantics: especially, don't
+expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
+for switching identities (or memberships).
+
+Don't assume set-uid and set-gid semantics. (And even if you do,
+think twice: set-uid and set-gid are a known can of security worms.)
+
=head2 Style
For those times when it is necessary to have platform-specific code,
@@ -559,7 +584,7 @@
programs to aid in the testing, or when (as noted above) the tests
assume certain things about the filesystem and paths. Be careful
not to depend on a specific output style for errors, such as when
-checking C<$!> after an system call. Some platforms expect a certain
+checking C<$!> after a system call. Some platforms expect a certain
output format, and perl on those platforms may have been adjusted
accordingly. Most specifically, don't anchor a regex when testing
an error value.
@@ -1416,6 +1441,17 @@
Does not automatically flush output handles on some platforms.
(SunOS, Solaris, HP-UX)
+=item exit EXPR
+
+=item exit
+
+Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
+mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
+with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
+function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
+(C<1>); this mapping cannot be overridden. Any other argument to exit()
+is used directly as Perl's exit status. (VMS)
+
=item fcntl FILEHANDLE,FUNCTION,SCALAR
Not implemented. (Win32, VMS)
@@ -1559,17 +1595,6 @@
Not implemented. (Plan9, Win32)
-=item exit EXPR
-
-=item exit
-
-Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
-mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
-with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
-function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
-(C<1>); this mapping cannot be overridden. Any other argument to exit()
-is used directly as Perl's exit status. (VMS)
-
=item getsockopt SOCKET,LEVEL,OPTNAME
Not implemented. (Plan9)
@@ -1658,11 +1683,11 @@
=item select RBITS,WBITS,EBITS,TIMEOUT
-Only implemented on sockets. (Win32)
+Only implemented on sockets. (Win32, VMS)
Only reliable on sockets. (S<RISC OS>)
-Note that the C<socket FILEHANDLE> form is generally portable.
+Note that the C<select FILEHANDLE> form is generally portable.
=item semctl ID,SEMNUM,CMD,ARG
@@ -1823,7 +1848,7 @@
=item utime LIST
-Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
+Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
May not behave as expected. Behavior depends on the C runtime
library's implementation of utime(), and the filesystem being
@@ -1937,7 +1962,7 @@
As of early 2001 (the Perl releases 5.6.1 and 5.7.1), the following
platforms are able to build Perl from the standard source code
-distribution available at http://www.perl.com/CPAN/src/index.html
+distribution available at http://www.cpan.org/src/index.html
AIX
AmigaOS
@@ -2063,7 +2088,7 @@
Netware
The following platforms have their own source code distributions and
-binaries available via http://www.perl.com/CPAN/ports/index.html:
+binaries available via http://www.cpan.org/ports/index.html:
Perl release
@@ -2072,7 +2097,7 @@
Tandem Guardian 5.004
The following platforms have only binaries available via
-http://www.perl.com/CPAN/ports/index.html :
+http://www.cpan.org/ports/index.html :
Perl release
@@ -2083,7 +2108,7 @@
Although we do suggest that you always build your own Perl from
the source code, both for maximal configurability and for security,
in case you are in a hurry you can check
-http://www.perl.com/CPAN/ports/index.html for binary distributions.
+http://www.cpan.org/ports/index.html for binary distributions.
=head1 SEE ALSO
End of Patch.
