X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlport.pod;h=87b2b27406cd87c27adabb1196bd15949b2f5246;hb=e706c0cd31a70bd2c97d4510f261613278a7e1f5;hp=3f9e918d4176e5ae254e634a8e1cbed47320c7f1;hpb=e0d9a2c811410c7aae3b9b9a69f60cc5395e8fdb;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlport.pod b/pod/perlport.pod index 3f9e918..87b2b27 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -271,7 +271,7 @@ modification timestamp), or one second granularity of any timestamps (e.g. the FAT filesystem limits the time granularity to two seconds). The "inode change timestamp" (the C<-C> filetest) may really be the -"creation timestamp" (which it is not in UNIX). +"creation timestamp" (which it is not in Unix). VOS perl can emulate Unix filenames with C as path separator. The native pathname characters greater-than, less-than, number-sign, and @@ -281,10 +281,10 @@ S perl can emulate Unix filenames with C as path 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, +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 +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. @@ -295,7 +295,7 @@ to be running the program. use File::Spec::Functions; chdir(updir()); # go up one directory - $file = catfile(curdir(), 'temp', 'file.txt'); + my $file = catfile(curdir(), 'temp', 'file.txt'); # on Unix and Win32, './temp/file.txt' # on Mac OS Classic, ':temp:file.txt' # on VMS, '[.temp]file.txt' @@ -356,7 +356,7 @@ Always use C<< < >> explicitly to open a file for reading, or even better, use the three-arg version of open, unless you want the user to be able to specify a pipe open. - open(FILE, '<', $existing_file) or die $!; + open my $fh, '<', $existing_file) or die $!; If filenames might use strange characters, it is safest to open it with C instead of C. C is magic and can @@ -452,7 +452,7 @@ Don't count on per-program environment variables, or per-program current directories. Don't count on specific values of C<$!>, neither numeric nor -especially the strings values-- users may switch their locales causing +especially the strings values. Users may switch their locales causing error messages to be translated into their languages. If you can trust a POSIXish environment, you can portably use the symbols defined by the Errno module, like ENOENT. And don't trust on the values of C<$!> @@ -481,14 +481,14 @@ To convert $^X to a file pathname, taking account of the requirements of the various operating system possibilities, say: use Config; - $thisperl = $^X; + my $thisperl = $^X; if ($^O ne 'VMS') {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} To convert $Config{perlpath} to a file pathname, say: use Config; - $thisperl = $Config{perlpath}; + my $thisperl = $Config{perlpath}; if ($^O ne 'VMS') {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;} @@ -518,13 +518,13 @@ Don't assume that you can ping hosts and get replies. Don't assume that any particular port (service) will respond. -Don't assume that Sys::Hostname (or any other API or command) -returns either a fully qualified hostname or a non-qualified hostname: -it all depends on how the system had been configured. Also remember -things like DHCP and NAT-- the hostname you get back might not be very -useful. +Don't assume that Sys::Hostname (or any other API or command) returns +either a fully qualified hostname or a non-qualified hostname: it all +depends on how the system had been configured. Also remember that for +things such as DHCP and NAT, the hostname you get back might not be +very useful. -All the above "don't":s may look daunting, and they are -- but the key +All the above "don't":s may look daunting, and they are, but the key is to degrade gracefully if one cannot reach the particular network service one wants. Croaking or hanging do not look very professional. @@ -635,7 +635,7 @@ When calculating specific times, such as for tests in time or date modules, it may be appropriate to calculate an offset for the epoch. require Time::Local; - $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70); + my $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70); The value for C<$offset> in Unix will be C<0>, but in Mac OS Classic will be some large number. C<$offset> can then be added to a Unix time @@ -693,10 +693,10 @@ of avoiding wasteful constructs such as: for (0..10000000) {} # bad for (my $x = 0; $x <= 10000000; ++$x) {} # good - @lines = ; # bad + my @lines = <$very_large_file>; # bad - while () {$file .= $_} # sometimes bad - $file = join('', ); # better + while (<$fh>) {$file .= $_} # sometimes bad + my $file = join('', <$fh>); # better The last two constructs may appear unintuitive to most people. The first repeatedly grows a string, whereas the second allocates a @@ -706,26 +706,26 @@ more efficient that the first. =head2 Security 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, +implemented at the filesystem level. Some, however, unfortunately do +not. 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 +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 +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 +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). @@ -846,10 +846,10 @@ Users familiar with I or I style shells should be aware that each of these file specifications may have subtle differences: - $filespec0 = "c:/foo/bar/file.txt"; - $filespec1 = "c:\\foo\\bar\\file.txt"; - $filespec2 = 'c:\foo\bar\file.txt'; - $filespec3 = 'c:\\foo\\bar\\file.txt'; + my $filespec0 = "c:/foo/bar/file.txt"; + my $filespec1 = "c:\\foo\\bar\\file.txt"; + my $filespec2 = 'c:\foo\bar\file.txt'; + my $filespec3 = 'c:\\foo\\bar\\file.txt'; System calls accept either C or C<\> as the path separator. However, many command-line utilities of DOS vintage treat C as @@ -1020,7 +1020,7 @@ Unicode characters. Characters that could be misinterpreted by the DCL shell or file parsing utilities need to be prefixed with the C<^> character, or replaced with hexadecimal characters prefixed with the C<^> character. Such prefixing is only needed with the pathnames are -in VMS format in applications. Programs that can accept the UNIX format +in VMS format in applications. Programs that can accept the Unix format of pathnames do not need the escape characters. The maximum length for filenames is 255 characters. The ODS-5 file system can handle both a case preserved and a case sensitive mode. @@ -1031,34 +1031,34 @@ Support for the extended file specifications is being done as optional settings to preserve backward compatibility with Perl scripts that assume the previous VMS limitations. -In general routines on VMS that get a UNIX format file specification -should return it in a UNIX format, and when they get a VMS format +In general routines on VMS that get a Unix format file specification +should return it in a Unix format, and when they get a VMS format specification they should return a VMS format unless they are documented to do a conversion. For routines that generate return a file specification, VMS allows setting if the C library which Perl is built on if it will be returned in VMS -format or in UNIX format. +format or in Unix format. With the ODS-2 file system, there is not much difference in syntax of -filenames without paths for VMS or UNIX. With the extended character +filenames without paths for VMS or Unix. With the extended character set available with ODS-5 there can be a significant difference. Because of this, existing Perl scripts written for VMS were sometimes -treating VMS and UNIX filenames interchangeably. Without the extended +treating VMS and Unix filenames interchangeably. Without the extended character set enabled, this behavior will mostly be maintained for backwards compatibility. When extended characters are enabled with ODS-5, the handling of -UNIX formatted file specifications is to that of a UNIX system. +Unix formatted file specifications is to that of a Unix system. VMS file specifications without extensions have a trailing dot. An -equivalent UNIX file specification should not show the trailing dot. +equivalent Unix file specification should not show the trailing dot. The result of all of this, is that for VMS, for portable scripts, you can not depend on Perl to present the filenames in lowercase, to be case sensitive, and that the filenames could be returned in either -UNIX or VMS format. +Unix or VMS format. And if a routine returns a file specification, unless it is intended to convert it, it should return it in the same format as it found it. @@ -1073,7 +1073,7 @@ return F when VMS is (though that file could be opened with C). With support for extended file specifications and if C was -given a UNIX format directory, a file named F will return F +given a Unix format directory, a file named F will return F and optionally in the exact case on the disk. When C is given a VMS format directory, then C should return F, and again with the optionally the exact case. @@ -1590,7 +1590,7 @@ Does not automatically flush output handles on some platforms. =item exit -Emulates UNIX exit() (which considers C to indicate an error) by +Emulates Unix exit() (which considers C to indicate an error) by mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden with the pragma C. As with the CRTL's exit() function, C is also mapped to an exit status of SS$_NORMAL @@ -1885,7 +1885,7 @@ Not implemented. (Win32, VMS, S, VOS) =item sockatmark A relatively recent addition to socket functions, may not -be implemented even in UNIX platforms. +be implemented even in Unix platforms. =item socketpair @@ -2049,11 +2049,23 @@ at http://www.cpan.org/src =item Windows Server 2008 +=item Windows 7 + =back +=item Cygwin + =item Solaris (x86, SPARC) -=item OpenVMS (which versions?) +=item OpenVMS + +=over + +=item Alpha (7.2 and later) + +=item I64 (8.2 and later) + +=back =item Symbian