add perlport.pod v1.23 from Chris Nandor <pudge@pobox.com>

p4raw-id: //depot/perl@1412

2 files changed, 1161 insertions, 0 deletions

diff --git a/pod/perl.pod b/pod/perl.pod
index 4c9808feae..1924d46d8b 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -49,6 +49,7 @@ of sections:
     perldiag	Perl diagnostic messages
     perlsec	Perl security
     perltrap	Perl traps for the unwary
+    perlport	Perl portability guide
     perlstyle	Perl style guide
 
     perlpod	Perl plain old documentation
diff --git a/pod/perlport.pod b/pod/perlport.pod
new file mode 100644
index 0000000000..83654689a6
--- /dev/null
+++ b/pod/perlport.pod
@@ -0,0 +1,1160 @@
+=head1 NAME
+
+perlport - Writing portable Perl
+
+
+=head1 DESCRIPTION
+
+Perl runs on a variety of operating systems.  While most of them share
+a lot in common, they also have their own very particular and unique
+features.
+
+This document is meant to help you to find out what constitutes portable
+perl code, so that once you have made your decision to write portably,
+you know where the lines are drawn, and you can stay within them.
+
+There is a tradeoff between taking full advantage of B<a> particular type
+of computer,  and taking advantage of a full B<range> of them.  Naturally,
+as you make your range bigger (and thus more diverse), the common denominators
+drop, and you are left with fewer areas of common ground in which
+you can operate to accomplish a particular task.  Thus, when you begin
+attacking a problem, it is important to consider which part of the tradeoff
+curve you want to operate under. Specifically, whether it is important to
+you that the task that you are coding needs the full generality of being
+portable, or if it is sufficient to just get the job done.  This is the
+hardest choice to be made.  The rest is easy, because Perl provides lots
+of choices, whichever way you want to approach your problem.
+
+Looking at it another way, writing portable code is usually about willfully
+limiting your available choices.  Naturally, it takes discipline to do that.
+
+Be aware of two important points:
+
+=over 4
+
+=item Not all Perl programs have to be portable
+
+There is no reason why you should not use Perl as a language to glue Unix
+tools together, or to prototype a Macintosh application, or to manage the
+Windows registry.  If it makes no sense to aim for portability for one
+reason or another in a given program, then don't bother.
+
+=item The vast majority of Perl B<is> portable
+
+Don't be fooled into thinking that it is hard to create portable Perl
+code.  It isn't.  Perl tries its level-best to bridge the gaps between
+what's available on different platforms, and all the means available to
+use those features.  Thus almost all Perl code runs on any machine
+without modification.  But there I<are> some significant issues in
+writing portable code, and this document is entirely about those issues.
+
+=back
+
+Here's the general rule: When you approach a task that is commonly done
+using a whole range of platforms, think in terms of writing portable
+code.  That way, you don't sacrifice much by way of the implementation
+choices you can avail yourself of, and at the same time you can give
+your users lots of platform choices.  On the other hand, when you have to
+take advantage of some unique feature of a particular platform, as is
+often the case with systems programming (whether for Unix, Windows,
+S<Mac OS>, VMS, etc.), consider writing platform-specific code.
+
+When the code will run on only two or three operating systems, then you may
+only need to consider the differences of those particular systems.  The
+important thing is to decide where the code will run, and to be deliberate
+in your decision.
+
+This information should not be considered complete; it includes possibly
+transient information about idiosyncracies of some of the ports, almost
+all of which are in a state of constant evolution.  Thus this material
+should be considered a perpetual work in progress
+(E<lt>IMG SRC="yellow_sign.gif" ALT="Under Construction"E<gt>).
+
+
+=head1 ISSUES
+
+=head2 Newlines
+
+In most operating systems, lines in files are separated with newlines.
+Just what is used as a newline may vary from OS to OS.  Unix
+traditionally uses C<\012>, one kind of Windows I/O uses C<\015\012>,
+and S<Mac OS> uses C<\015>.
+
+Perl uses C<\n> to represent the "logical" newline, where what
+is logical may depend on the platform in use.  In MacPerl, C<\n>
+always means C<\015>.  In DOSish perls, C<\n> usually means C<\012>, but
+when accessing a file in "text" mode, STDIO translates it to (or from)
+C<\015\012>.
+
+Due to the "text" mode translation, DOSish perls have limitations
+of using C<seek> and C<tell> when a file is being accessed in "text"
+mode.  Specifically, if you stick to C<seek>-ing to locations you got
+from C<tell> (and no others), you are usually free to use C<seek> and
+C<tell> even in "text" mode.  In general, using C<seek> or C<tell> or
+other file operations that count bytes instead of characters, without
+considering the length of C<\n>, may be non-portable.  If you use
+C<binmode> on a file, however, you can usually use C<seek> and C<tell>
+with arbitrary values quite safely.
+
+A common misconception in socket programming is that C<\n> eq C<\012>
+everywhere.  When using protocols, such as common Internet protocols,
+C<\012> and C<\015> are called for specifically, and the values of
+the logical C<\n> and C<\r> (carriage return) are not reliable.
+
+    print SOCKET "Hi there, client!\r\n";      # WRONG
+    print SOCKET "Hi there, client!\015\012";  # RIGHT
+
+[NOTE: this does not necessarily apply to communications that are
+filtered by another program or module before sending to the socket; the
+the most popular EBCDIC webserver, for instance, accepts C<\r\n>,
+which translates those characters, along with all other
+characters in text streams, from EBCDIC to ASCII.]
+
+However, C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious and
+unsightly, as well as confusing to those maintaining the code.  As such,
+the C<Socket> module supplies the Right Thing for those who want it.
+
+    use Socket qw(:DEFAULT :crlf);
+    print SOCKET "Hi there, client!$CRLF"      # RIGHT
+
+When reading I<from> a socket, remember that the default input record
+separator (C<$/>) is C<\n>, but code like this should recognize C<$/> as
+C<\012> or C<\015\012>:
+
+    while (<SOCKET>) {
+        # ...
+    }
+
+Better:
+
+    use Socket qw(:DEFAULT :crlf);
+    local($/) = LF;      # not needed if $/ is already \012
+
+    while (<SOCKET>) {
+        s/$CR?$LF/\n/;   # not sure if socket uses LF or CRLF, OK
+    #   s/\015?\012/\n/; # same thing
+    }
+
+And this example is actually better than the previous one even for Unix
+platforms, because now any C<\015>'s (C<\cM>'s) are stripped out
+(and there was much rejoicing).
+
+
+=head2 File Paths
+
+Most platforms these days structure files in a hierarchical fashion.
+So, it is reasonably safe to assume that any platform supports the
+notion of a "path" to uniquely identify a file on the system.  Just
+how that path is actually written, differs.
+
+While they are similar, file path specifications differ between Unix,
+Windows, S<Mac OS>, OS/2, VMS and probably others.  Unix, for example, is
+one of the few OSes that has the idea of a root directory.  S<Mac OS>
+uses C<:> as a path separator instead of C</>.  VMS, Windows, and OS/2
+can work similarly to Unix with C</> as path separator, or in their own
+idiosyncratic ways.
+
+As with the newline problem above, there are modules that can help.  The
+C<File::Spec> modules provide methods to do the Right Thing on whatever
+platform happens to be running the program.
+
+    use File::Spec;
+    chdir(File::Spec->updir());        # go up one directory
+    $file = File::Spec->catfile(
+        File::Spec->curdir(), 'temp', 'file.txt'
+    );
+    # on Unix and Win32, './temp/file.txt'
+    # on Mac OS, ':temp:file.txt'
+
+File::Spec is available in the standard distribution, as of version
+5.004_05.
+
+In general, production code should not have file paths hardcoded; making
+them user supplied or from a configuration file is better, keeping in mind
+that file path syntax varies on different machines.
+
+This is especially noticeable in scripts like Makefiles and test suites,
+which often assume C</> as a path separator for subdirectories.
+
+Also of use is C<File::Basename>, from the standard distribution, which
+splits a pathname into pieces (base filename, full path to directory,
+and file suffix).
+
+Remember not to count on the existence of system-specific files, like
+F</etc/resolv.conf>.  If code does need to rely on such a file, include a
+description of the file and its format in the code's documentation, and
+make it easy for the user to override the default location of the file.
+
+
+=head2 System Interaction
+
+Not all platforms provide for the notion of a command line, necessarily.
+These are usually platforms that rely on a Graphical User Interface (GUI)
+for user interaction.  So a program requiring command lines might not work
+everywhere.  But this is probably for the user of the program to deal
+with.
+
+Some platforms can't delete or rename files that are being held open by
+the system.  Remember to C<close> files when you are done with them.
+Don't C<unlink> or C<rename> an open file.  Don't C<tie> to or C<open> a
+file that is already tied to or opened; C<untie> or C<close> first.
+
+Don't count on a specific environment variable existing in C<%ENV>.
+Don't even count on C<%ENV> entries being case-sensitive, or even
+case-preserving.
+
+Don't count on signals in portable programs.
+
+Don't count on filename globbing.  Use C<opendir>, C<readdir>, and
+C<closedir> instead.
+
+
+=head2 Interprocess Communication (IPC)
+
+In general, don't directly access the system in code that is meant to be
+portable.  That means, no: C<system>, C<exec>, C<fork>, C<pipe>, C<``>,
+C<qx//>, C<open> with a C<|>, or any of the other things that makes being
+a Unix perl hacker worth being.
+
+Commands that launch external processes are generally supported on
+most platforms (though many of them do not support any type of forking),
+but the problem with using them arises from what you invoke with them.
+External tools are often named differently on different platforms, often
+not available in the same location, often accept different arguments,
+often behave differently, and often represent their results in a
+platform-dependent way.  Thus you should seldom depend on them to produce
+consistent results.
+
+One especially common bit of Perl code is opening a pipe to sendmail:
+
+    open(MAIL, '|/usr/lib/sendmail -t') or die $!;
+
+This is fine for systems programming when sendmail is known to be
+available.  But it is not fine for many non-Unix systems, and even
+some Unix systems that may not have sendmail installed.  If a portable
+solution is needed, see the C<Mail::Send> and C<Mail::Mailer> modules
+in the C<MailTools> distribution.  C<Mail::Mailer> provides several
+mailing methods, including mail, sendmail, and direct SMTP
+(via C<Net::SMTP>) if a mail transfer agent is not available.
+
+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 code,
+but expose a common interface.  By portable Perl, we mean code that
+avoids the constructs described in this document as being non-portable.
+
+
+=head2 External Subroutines (XS)
+
+XS code, in general, can be made to work with any platform; but dependent
+libraries, header files, etc., might not be readily available or
+portable, or the XS code itself might be platform-specific, just as Perl
+code might be.  If the libraries and headers are portable, then it is
+normally reasonable to make sure the XS code is portable, too.
+
+There is a different kind of portability issue with writing XS
+code: availability of a C compiler on the end-user's system.  C brings with
+it its own portability issues, and writing XS code will expose you to
+some of those.  Writing purely in perl is a comparatively easier way to
+achieve portability.
+
+
+=head2 Standard Modules
+
+In general, the standard modules work across platforms.  Notable
+exceptions are C<CPAN.pm> (which currently makes connections to external
+programs that may not be available), platform-specific modules (like
+C<ExtUtils::MM_VMS>), and DBM modules.
+
+There is no one DBM module that is available on all platforms.
+C<SDBM_File> and the others are generally available on all Unix and DOSish
+ports, but not in MacPerl, where C<NBDM_File> and C<DB_File> are available.
+
+The good news is that at least some DBM module should be available, and
+C<AnyDBM_File> will use whichever module it can find.  Of course, then
+the code needs to be fairly strict, dropping to the lowest common
+denominator (e.g., not exceeding 1K for each record).
+
+
+=head2 Time and Date
+
+The system's notion of time of day and calendar date is controlled in widely
+different ways. Don't assume the timezone is stored in C<$ENV{TZ}>, and even
+if it is, don't assume that you can control the timezone through that
+variable.
+
+Don't assume that the epoch starts at January 1, 1970, because that is
+OS-specific.  Better to store a date in an unambiguous representation.
+A text representation (like C<1 Jan 1970>) can be easily converted into an
+OS-specific value using a module like C<Date::Parse>.  An array of values,
+such as those returned by C<localtime>, can be converted to an OS-specific
+representation using C<Time::Local>.
+
+
+=head2 System Resources
+
+If your code is destined for systems with severely constrained (or missing!)
+virtual memory systems then you want to be especially mindful of avoiding
+wasteful constructs such as:
+
+    # NOTE: this is no longer "bad" in perl5.005
+    for (0..10000000) {}                       # bad
+    for (my $x = 0; $x <= 10000000; ++$x) {}   # good
+
+    @lines = <VERY_LARGE_FILE>;                # bad
+
+    while (<FILE>) {$file .= $_}               # sometimes bad
+    $file = join '', <FILE>;                   # better
+
+The last two may appear unintuitive to most people.  The first of those
+two constructs repeatedly grows a string, while the second allocates a
+large chunk of memory in one go.  On some systems, the latter is more
+efficient that the former.
+
+=head2 Security
+
+Most Unix platforms provide basic levels of security that is usually felt
+at the file-system level.  Other platforms usually don't (unfortunately).
+Thus the notion of User-ID, or "home" directory, or even the state of
+being logged-in may be unrecognizable on may platforms.  If you write
+programs that are security conscious, it is usually best to know what
+type of system you will be operating under, and write code explicitly
+for that platform (or class of platforms).
+
+=head2 Style
+
+For those times when it is necessary to have platform-specific code,
+consider keeping the platform-specific code in one place, making porting
+to other platforms easier.  Use the C<Config> module and the special
+variable C<$^O> to differentiate platforms, as described in L<"PLATFORMS">.
+
+
+=head1 CPAN TESTERS
+
+Module uploaded to CPAN are tested by a variety of volunteers on
+different platforms.  These CPAN testers are notified by e-mail of each
+new upload, and reply to the list with PASS, FAIL, NA (not applicable to
+this platform), or ???? (unknown), along with any relevant notations.
+
+The purpose of the testing is twofold: one, to help developers fix any
+problems in their code; two, to provide users with information about
+whether or not a given module works on a given platform.
+
+=over 4
+
+=item Mailing list: cpan-testers@perl.org
+
+=item Testing results: C<http://www.connect.net/gbarr/cpan-test/>
+
+=back
+
+
+=head1 PLATFORMS
+
+As of version 5.002, Perl is built with a C<$^O> variable that
+indicates the operating system it was built on.  This was implemented
+to help speed up code that would otherwise have to C<use Config;> and
+use the value of C<$Config{'osname'}>.  Of course, to get
+detailed information about the system, looking into C<%Config> is
+certainly recommended.
+
+=head2 Unix
+
+Perl works on a bewildering variety of Unix and Unix-like platforms (see
+e.g. most of the files in the F<hints/> directory in the source code kit).
+On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
+too) is determined by lowercasing and stripping punctuation from the first
+field of the string returned by typing
+
+    % uname -a
+
+(or a similar command) at the shell prompt.  Here, for example, are a few
+of the more popular Unix flavors:
+
+    uname        $^O
+    --------------------
+    AIX          aix
+    FreeBSD      freebsd
+    Linux        linux
+    HP-UX        hpux
+    OSF1         dec_osf
+    SunOS        solaris
+    SunOS4       sunos
+
+
+=head2 DOS and Derivatives
+
+Perl has long been ported to PC style microcomputers running under
+systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
+bring yourself to mention (except for Windows CE, if you count that).
+Users familiar with I<COMMAND.COM> and/or I<CMD.EXE> 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';
+
+System calls accept either C</> or C<\> as the path separator.  However,
+many command-line utilities of DOS vintage treat C</> as the option
+prefix, so they may get confused by filenames containing C</>.  Aside
+from calling any external programs, C</> will work just fine, and
+probably better, as it is more consistent with popular usage, and avoids
+the problem of remembering what to backwhack and what not to.
+
+The DOS FAT file system can only accomodate "8.3" style filenames.  Under
+the "case insensitive, but case preserving" HPFS (OS/2) and NTFS (NT)
+file systems you may have to be careful about case returned with functions
+like C<readdir> or used with functions like C<open> or C<opendir>.
+
+DOS also treats several filenames as special, such as AUX, PRN, NUL, CON,
+COM1, LPT1, LPT2 etc.  Unfortunately these filenames won't even work
+if you include an explicit directory prefix, in some cases.  It is best
+to avoid such filenames, if you want your code to be portable to DOS
+and its derivatives.
+
+Users of these operating systems may also wish to make use of
+scripts such as I<pl2bat.bat> or I<pl2cmd> as appropriate to
+put wrappers around your scripts.
+
+Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
+and writing to files.  C<binmode(FILEHANDLE)> will keep C<\n> translated
+as C<\012> for that filehandle.  Since it is a noop on other systems,
+C<binmode> should be used for cross-platform code that deals with binary
+data.
+
+The C<$^O> variable and the C<$Config{'archname'}> values for various
+DOSish perls are as follows:
+
+    OS            $^O        $Config{'archname'}
+    --------------------------------------------
+    MS-DOS        dos
+    PC-DOS        dos
+    OS/2          os2
+    Windows 95    MSWin32    MSWin32-x86
+    Windows NT    MSWin32    MSWin32-x86
+    Windows NT    MSWin32    MSWin32-alpha
+    Windows NT    MSWin32    MSWin32-ppc
+
+Also see:
+
+=over 4
+
+=item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>
+
+=item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>,
+C<http://www.juge.com/bbs/Hobb.19.html>
+
+=item Build instructions for Win32, L<perlwin32>.
+
+=item The ActiveState Pages, C<http://www.activestate.com/>
+
+=back
+
+
+=head2 MacPerl
+
+Any module requiring XS compilation is right out for most people, because
+MacPerl is built using non-free (and non-cheap!) compilers.  Some XS
+modules that can work with MacPerl are built and distributed in binary
+form on CPAN.  See I<MacPerl: Power and Ease> for more details.
+
+Directories are specified as:
+
+    volume:folder:file              for absolute pathnames
+    volume:folder:                  for absolute pathnames
+    :folder:file                    for relative pathnames
+    :folder:                        for relative pathnames
+    :file                           for relative pathnames
+    file                            for relative pathnames
+
+Files in a directory are stored in alphabetical order.  Filenames are
+limited to 31 characters, and may include any character except C<:>,
+which is reserved as a path separator.
+
+Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in
+C<Mac::Files>.
+
+In the MacPerl application, you can't run a program from the command line;
+programs that expect C<@ARGV> to be populated can be edited with something
+like the following, which brings up a dialog box asking for the command
+line arguments.
+
+    if (!@ARGV) {
+        @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
+    }
+
+A MacPerl script saved as a droplet will populate C<@ARGV> with the full
+pathnames of the files dropped onto the script.
+
+Mac users can use programs on a kind of command line under MPW (Macintosh
+Programmer's Workshop, a free development environment from Apple).
+MacPerl was first introduced as an MPW tool, and MPW can be used like a
+shell:
+
+    perl myscript.plx some arguments
+
+ToolServer is another app from Apple that provides access to MPW tools
+from MPW and the MacPerl app, which allows MacPerl program to use
+C<system>, backticks, and piped C<open>.
+
+"S<Mac OS>" is the proper name for the operating system, but the value
+in C<$^O> is "MacOS".  To determine architecture, version, or whether
+the application or MPW tool version is running, check:
+
+    $is_app    = $MacPerl::Version =~ /App/;
+    $is_tool   = $MacPerl::Version =~ /MPW/;
+    ($version) = $MacPerl::Version =~ /^(\S+)/;
+    $is_ppc    = $MacPerl::Architecture eq 'MacPPC';
+    $is_68k    = $MacPerl::Architecture eq 'Mac68K';
+
+
+Also see:
+
+=over 4
+
+=item The MacPerl Pages, C<http://www.ptf.com/macperl/>.
+
+=item The MacPerl mailing list, C<mac-perl-request@iis.ee.ethz.ch>.
+
+=back
+
+
+=head2 VMS
+
+Perl on VMS is discussed in F<vms/perlvms.pod> in the perl distribution.
+Note that perl on VMS can accept either VMS or Unix style file
+specifications as in either of the following:
+
+    $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
+    $ perl -ne "print if /perl_setup/i" /sys$login/login.com
+
+but not a mixture of both as in:
+
+    $ perl -ne "print if /perl_setup/i" sys$login:/login.com
+    Can't open sys$login:/login.com: file specification syntax error
+
+Interacting with Perl from the Digital Command Language (DCL) shell
+often requires a different set of quotation marks than Unix shells do.
+For example:
+
+    $ perl -e "print ""Hello, world.\n"""
+    Hello, world.
+
+There are a number of ways to wrap your perl scripts in DCL .COM files if
+you are so inclined.  For example:
+
+    $ write sys$output "Hello from DCL!"
+    $ if p1 .eqs. ""
+    $ then perl -x 'f$environment("PROCEDURE")
+    $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
+    $ deck/dollars="__END__"
+    #!/usr/bin/perl
+
+    print "Hello from Perl!\n";
+
+    __END__
+    $ endif
+
+Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
+perl-in-DCL script expects to do things like C<$read = E<lt>STDINE<gt>;>.
+
+Filenames are in the format "name.extension;version".  The maximum
+length for filenames is 39 characters, and the maximum length for
+extensions is also 39 characters.  Version is a number from 1 to
+32767.  Valid characters are C</[A-Z0-9$_-]/>.
+
+VMS' RMS filesystem is case insensitive and does not preserve case.
+C<readdir> returns lowercased filenames, but specifying a file for
+opening remains case insensitive. Files without extensions have a
+trailing period on them, so doing a C<readdir> with a file named F<A.;5>
+will return F<a.> (though that file could be opened with C<open(FH, 'A')>.
+
+RMS has an eight level limit on directory depths from any rooted logical
+(allowing 16 levels overall).  Hence C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]>
+is a valid directory specification but C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]>
+is not.  F<Makefile.PL> authors might have to take this into account, but
+at least they can refer to the former as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
+
+The C<VMS::Filespec> module, which gets installed as part
+of the build process on VMS, is a pure Perl module that can easily be
+installed on non-VMS platforms and can be helpful for conversions to
+and from RMS native formats.
+
+What C<\n> represents depends on the type of file that is open.  It could
+be C<\015>, C<\012>, C<\015\012>, or nothing.  Reading from a file
+translates newlines to C<\012>, unless C<binmode> was executed on that
+handle, just like DOSish perls.
+
+TCP/IP stacks are optional on VMS, so socket routines might not be
+implemented.  UDP sockets may not be supported.
+
+The value of C<$^O> on OpenVMS is "VMS".  To determine the architecture
+that you are running on without resorting to loading all of C<%Config>
+you can examine the content of the C<@INC> array like so:
+
+    if (grep(/VMS_AXP/, @INC)) {
+        print "I'm on Alpha!\n";
+    } elsif (grep(/VMS_VAX/, @INC)) {
+        print "I'm on VAX!\n";
+    } else {
+        print "I'm not so sure about where $^O is...\n";
+    }
+
+Also see:
+
+=over 4
+
+=item L<perlvms.pod>
+
+=item vmsperl list, C<vmsperl-request@newman.upenn.edu>
+
+Put words C<SUBSCRIBE VMSPERL> in message body.
+
+=item vmsperl on the web, C<http://www.sidhe.org/vmsperl/index.html>
+
+=back
+
+
+=head2 EBCDIC Platforms
+
+Recent versions of Perl have been ported to platforms such as OS/400 on
+AS/400 minicomputers as well as OS/390 for IBM Mainframes.  Such computers
+use EBCDIC character sets internally (usually Character Code Set ID 00819
+for OS/400 and IBM-1047 for OS/390).  Note that on the mainframe perl
+currently works under the "Unix system services for OS/390" (formerly
+known as OpenEdition).
+
+As of R2.5 of USS for OS/390 that Unix sub-system did not support the
+C<#!> shebang trick for script invocation.  Hence, on OS/390 perl scripts
+can executed with a header similar to the following simple script:
+
+    : # use perl
+        eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
+            if 0;
+    #!/usr/local/bin/perl     # just a comment really
+
+    print "Hello from perl!\n";
+
+On these platforms, bear in mind that the EBCDIC character set may have
+an effect on what happens with perl functions such as C<chr>, C<pack>,
+C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>; as well as
+bit-fiddling with ASCII constants using operators like C<^>, C<&> and
+C<|>; not to mention dealing with socket interfaces to ASCII computers
+(see L<"NEWLINES">).
+
+Fortunately, most web servers for the mainframe will correctly translate
+the C<\n> in the following statement to its ASCII equivalent (note that
+C<\r> is the same under both ASCII and EBCDIC):
+
+    print "Content-type: text/html\r\n\r\n";
+
+The value of C<$^O> on OS/390 is "os390".
+
+Some simple tricks for determining if you are running on an EBCDIC
+platform could include any of the following (perhaps all):
+
+    if ("\t" eq "\05")   { print "EBCDIC may be spoken here!\n"; }
+
+    if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
+
+    if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
+
+Note that one thing you may not want to rely on is the EBCDIC encoding
+of punctuation characters since these may differ from code page to code page
+(and once your module or script is rumoured to work with EBCDIC, folks will
+want it to work with all EBCDIC character sets).
+
+Also see:
+
+=over 4
+
+=item perl-mvs list
+
+The perl-mvs@perl.org list is for discussion of porting issues as well as
+general usage issues for all EBCDIC Perls.  Send a message body of
+"subscribe perl-mvs" to majordomo@perl.org.
+
+=item AS/400 Perl information at C<http://as400.rochester.ibm.com>
+
+=back
+
+=head2 Other perls
+
+Perl has been ported to a variety of platforms that do not fit into any of
+the above categories.  Some, such as AmigaOS, BeOS, QNX, and Plan 9, have
+been well integrated into the standard Perl source code kit.  You may need
+to see the F<ports/> directory on CPAN for information, and possibly
+binaries, for the likes of: acorn, aos, atari, lynxos, HP-MPE/iX, riscos,
+Tandem Guardian, vos, I<etc.> (yes we know that some of these OSes may fall
+under the Unix category but we are not a standards body.)
+
+See also:
+
+=over 4
+
+=item Atari, Guido Flohr's page C<http://stud.uni-sb.de/~gufl0000/>
+
+=item HP 300 MPE/iX  C<http://www.cccd.edu/~markb/perlix.html>
+
+=item Novell Netware
+
+A free Perl 5 based PERL.NLM for Novell Netware is available from
+C<http://www.novell.com/>
+
+=back
+
+
+=head1 FUNCTION IMPLEMENTATIONS
+
+Listed below are functions unimplemented or implemented differently on
+various platforms.  Following each description will be, in parentheses, a
+list of platforms that the description applies to.
+
+The list may very well be incomplete, or wrong in some places.  When in
+doubt, consult the platform-specific README files in the Perl source
+distribution, and other documentation resources for a given port.
+
+Be aware, moreover, that even among Unix-ish systems there are variations,
+and not all functions listed here are necessarily available, though
+most usually are.
+
+For many functions, you can also query C<%Config>, exported by default
+from C<Config.pm>.  For example, to check if the platform has the C<lstat>
+call, check C<$Config{'d_lstat'}>.  See L<Config> for a full description
+of available variables.
+
+
+=head2 Alphabetical Listing of Perl Functions
+
+=over 8
+
+=item -X FILEHANDLE
+
+=item -X EXPR
+
+=item -X
+
+C<-r>, C<-w>, and C<-x> have only a very limited meaning; directories
+and applications are executable, and there are no uid/gid
+considerations. C<-o> is not supported. (S<Mac OS>)
+
+C<-r>, C<-w>, C<-x>, and C<-o> tell whether or not file is accessible,
+which may not reflect UIC-based file protections. (VMS)
+
+C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
+C<-x>, C<-o>. (S<Mac OS>, Win32, VMS)
+
+C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
+(S<Mac OS>)
+
+C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
+(Win32, VMS)
+
+C<-d> is true if passed a device spec without an explicit directory.
+(VMS)
+
+C<-T> and C<-B> are implemented, but might misclassify Mac text files
+with foreign characters; this is the case will all platforms, but
+affects S<Mac OS> a lot. (S<Mac OS>)
+
+C<-x> (or C<-X>) determine if a file ends in one of the executable
+suffixes. C<-S> is meaningless. (Win32)
+
+=item binmode FILEHANDLE
+
+Meaningless. (S<Mac OS>)
+
+Reopens file and restores pointer; if function fails, underlying
+filehandle may be closed, or pointer may be in a different position.
+(VMS)
+
+The value returned by C<tell> may be affected after the call, and
+the filehandle may be flushed. (Win32)
+
+=item chmod LIST
+
+Only limited meaning. Disabling/enabling write permission is mapped to
+locking/unlocking the file. (S<Mac OS>)
+
+Only good for changing "owner" read-write access, "group", and "other"
+bits are meaningless. (Win32)
+
+=item chown LIST
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+Does nothing, but won't fail. (Win32)
+
+=item chroot FILENAME
+
+=item chroot
+
+Not implemented. (S<Mac OS>, Win32, VMS, Plan9)
+
+=item crypt PLAINTEXT,SALT
+
+May not be available if library or source was not provided when building
+perl.  (Win32)
+
+=item dbmclose HASH
+
+Not implemented. (VMS, Plan9)
+
+=item dbmopen HASH,DBNAME,MODE
+
+Not implemented. (VMS, Plan9)
+
+=item dump LABEL
+
+Not useful. (S<Mac OS>)
+
+Not implemented. (Win32)
+
+Invokes VMS debugger.  (VMS)
+
+=item exec LIST
+
+Not implemented. (S<Mac OS>)
+
+=item fcntl FILEHANDLE,FUNCTION,SCALAR
+
+Not implemented. (Win32, VMS)
+
+=item flock FILEHANDLE,OPERATION
+
+Not implemented (S<Mac OS>, VMS).
+
+Available only on Windows NT (not on Windows 95). (Win32)
+
+=item fork
+
+Not implemented. (S<Mac OS>, Win32, AmigaOS)
+
+=item getlogin
+
+Not implemented. (S<Mac OS>)
+
+=item getpgrp PID
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item getppid
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item getpriority WHICH,WHO
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item getpwnam NAME
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item getgrnam NAME
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item getnetbyname NAME
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item getpwuid UID
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item getgrgid GID
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item getnetbyaddr ADDR,ADDRTYPE
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item getprotobynumber NUMBER
+
+Not implemented. (S<Mac OS>)
+
+=item getservbyport PORT,PROTO
+
+Not implemented. (S<Mac OS>)
+
+=item getpwent
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item getgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item gethostent
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item getnetent
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item getprotoent
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item getservent
+
+Not implemented. (Win32, Plan9)
+
+=item setpwent
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item setgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item sethostent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item setnetent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item setprotoent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item setservent STAYOPEN
+
+Not implemented. (Plan9, Win32)
+
+=item endpwent
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item endgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item endhostent
+
+Not implemented. (S<Mac OS>, Win32)
+
+=item endnetent
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item endprotoent
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item endservent
+
+Not implemented. (Plan9, Win32)
+
+=item getsockopt SOCKET,LEVEL,OPTNAME
+
+Not implemented. (S<Mac OS>, Plan9)
+
+=item glob EXPR
+
+=item glob
+
+Globbing built-in, but only C<*> and C<?> metacharacters are supported.
+(S<Mac OS>)
+
+Features depend on external perlglob.exe or perlglob.bat. May be overridden
+with something like File::DosGlob, which is recommended. (Win32)
+
+=item ioctl FILEHANDLE,FUNCTION,SCALAR
+
+Not implemented. (VMS)
+
+Available only for socket handles, and it does what the ioctlsocket() call
+in the Winsock API does. (Win32)
+
+=item kill LIST
+
+Not implemented. (S<Mac OS>)
+
+Available only for process handles returned by the C<system(1, ...)> method of
+spawning a process.  (Win32)
+
+=item link OLDFILE,NEWFILE
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item lstat FILEHANDLE
+
+=item lstat EXPR
+
+=item lstat
+
+Not implemented. (VMS)
+
+Return values may be bogus.  (Win32)
+
+=item msgctl ID,CMD,ARG
+
+=item msgget KEY,FLAGS
+
+=item msgsnd ID,MSG,FLAGS
+
+=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+
+Not implemented. (S<Mac OS>, Win32, VMS, Plan9)
+
+=item open FILEHANDLE,EXPR
+
+=item open FILEHANDLE
+
+The C<|> variants are only supported if ToolServer is installed.
+(S<Mac OS>)
+
+open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32)
+
+=item pipe READHANDLE,WRITEHANDLE
+
+Not implemented. (S<Mac OS>)
+
+=item readlink EXPR
+
+=item readlink
+
+Not implemented. (Win32, VMS)
+
+=item select RBITS,WBITS,EBITS,TIMEOUT
+
+Only implemented on sockets. (Win32)
+
+=item semctl ID,SEMNUM,CMD,ARG
+
+=item semget KEY,NSEMS,FLAGS
+
+=item semop KEY,OPSTRING
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item setpgrp PID,PGRP
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item setpriority WHICH,WHO,PRIORITY
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+
+Not implemented. (S<Mac OS>, Plan9)
+
+=item shmctl ID,CMD,ARG
+
+=item shmget KEY,SIZE,FLAGS
+
+=item shmread ID,VAR,POS,SIZE
+
+=item shmwrite ID,STRING,POS,SIZE
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item stat FILEHANDLE
+
+=item stat EXPR
+
+=item stat
+
+mtime and atime are the same thing, and ctime is creation time instead of
+inode change time. (S<Mac OS>)
+
+device and inode are not meaningful.  (Win32)
+
+device and inode are not necessarily reliable.  (VMS)
+
+=item symlink OLDFILE,NEWFILE
+
+Not implemented. (Win32, VMS)
+
+=item syscall LIST
+
+Not implemented. (S<Mac OS>, Win32, VMS)
+
+=item system LIST
+
+Only implemented if ToolServer is installed. (S<Mac OS>)
+
+As an optimization, may not call the command shell specified in
+C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
+process and immediately returns its process designator, without
+waiting for it to terminate.  Return value may be used subsequently
+in C<wait> or C<waitpid>.  (Win32)
+
+=item times
+
+Only the first entry returned is nonzero. (S<Mac OS>)
+
+"cumulative" times will be bogus.  On anything other than Windows NT,
+"system" time will be bogus, and "user" time is actually the time
+returned by the clock() function in the C runtime library. (Win32)
+
+=item truncate FILEHANDLE,LENGTH
+
+=item truncate EXPR,LENGTH
+
+Not implemented. (VMS)
+
+=item umask EXPR
+
+=item umask
+
+Returns undef where unavailable, as of version 5.005.
+
+=item utime LIST
+
+Only the modification time is updated. (S<Mac OS>, VMS)
+
+May not behave as expected. (Win32)
+
+=item wait
+
+=item waitpid PID,FLAGS
+
+Not implemented. (S<Mac OS>)
+
+Can only be applied to process handles returned for processes spawned
+using C<system(1, ...)>. (Win32)
+
+=back
+
+
+=head1 AUTHORS / CONTRIBUTORS
+
+Chris Nandor E<lt>pudge@pobox.comE<gt>,
+Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>,
+Peter Prymmer E<lt>pvhp@forte.comE<gt>,
+Tom Christiansen E<lt>tchrist@perl.comE<gt>,
+Nathan Torkington E<lt>gnat@frii.comE<gt>,
+Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>,
+Matthias Neercher E<lt>neeri@iis.ee.ethz.chE<gt>,
+Charles Bailey E<lt>bailey@genetics.upenn.eduE<gt>,
+Luther Huffman E<lt>lutherh@stratcom.comE<gt>,
+Gary Ng E<lt>71564.1743@CompuServe.COME<gt>,
+Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>,
+Paul J. Schinder E<lt>schinder@pobox.comE<gt>,
+Tom Phoenix E<lt>rootbeer@teleport.comE<gt>,
+Hugo van der Sanden E<lt>h.sanden@elsevier.nlE<gt>,
+Dominic Dunlop E<lt>domo@vo.luE<gt>,
+Dan Sugalski E<lt>sugalskd@ous.eduE<gt>,
+Andreas J. Koenig E<lt>koenig@kulturbox.deE<gt>,
+Andrew M. Langmead E<lt>aml@world.std.comE<gt>,
+Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>,
+Abigail E<lt>abigail@fnx.comE<gt>.
+
+This document is maintained by Chris Nandor.
+
+=head1 VERSION
+
+Version 1.23, last modified 10 July 1998.
+