perl5.005_03

1 files changed, 1613 insertions, 0 deletions

diff --git a/gnu/usr.bin/perl/pod/perlport.pod b/gnu/usr.bin/perl/pod/perlport.pod
new file mode 100644
index 00000000000..c1a5483add6
--- /dev/null
+++ b/gnu/usr.bin/perl/pod/perlport.pod
@@ -0,0 +1,1613 @@
+=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.
+
+The material below is separated into three main sections: main issues of
+portability (L<"ISSUES">, platform-specific issues (L<"PLATFORMS">, and
+builtin perl functions that behave differently on various ports
+(L<"FUNCTION IMPLEMENTATIONS">.
+
+This information should not be considered complete; it includes possibly
+transient information about idiosyncrasies 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 terminated by 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, using 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).
+
+An important thing to remember is that functions that return data
+should translate newlines when appropriate.  Often one line of code
+will suffice:
+
+	$data =~ s/\015?\012/\n/g;
+	return $data;
+
+
+=head2 Numbers endianness and Width
+
+Different CPUs store integers and floating point numbers in different
+orders (called I<endianness>) and widths (32-bit and 64-bit being the
+most common).  This affects your programs if they attempt to transfer
+numbers in binary format from a CPU architecture to another over some
+channel: either 'live' via network connections or storing the numbers
+to secondary storage such as a disk file.
+
+Conflicting storage orders make utter mess out of the numbers: if a
+little-endian host (Intel, Alpha) stores 0x12345678 (305419896 in
+decimal), a big-endian host (Motorola, MIPS, Sparc, PA) reads it as
+0x78563412 (2018915346 in decimal).  To avoid this problem in network
+(socket) connections use the C<pack()> and C<unpack()> formats C<"n">
+and C<"N">, the "network" orders, they are guaranteed to be portable.
+
+Different widths can cause truncation even between platforms of equal
+endianness: the platform of shorter width loses the upper parts of the
+number.  There is no good solution for this problem except to avoid
+transferring or storing raw binary numbers.
+
+One can circumnavigate both these problems in two ways: either
+transfer and store numbers always in text format, instead of raw
+binary, or consider using modules like C<Data::Dumper> (included in
+the standard distribution as of Perl 5.005) and C<Storable>.
+
+=head2 Files and Filesystems
+
+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, VOS, S<RISC OS> and probably others.
+Unix, for example, is one of the few OSes that has the idea of a single
+root directory.
+
+VMS, Windows, and OS/2 can work similarly to Unix with C</> as path
+separator, or in their own idiosyncratic ways (such as having several
+root directories and various "unrooted" device files such NIL: and
+LPT:).
+
+S<Mac OS> uses C<:> as a path separator instead of C</>.
+
+The filesystem may support neither hard links (C<link()>) nor
+symbolic links (C<symlink()>, C<readlink()>, C<lstat()>).
+
+The filesystem may not support neither access timestamp nor change
+timestamp (meaning that about the only portable timestamp is the
+modification timestamp), or one second granularity of any timestamps
+(e.g. the FAT filesystem limits the time granularity to two seconds).
+
+VOS perl can emulate Unix filenames with C</> as path separator.  The
+native pathname characters greater-than, less-than, number-sign, and
+percent-sign are always accepted.
+
+C<RISC OS> perl can emulate Unix filenames with C</> as path
+separator, or go native and use C<.> for path separator and C<:> to
+signal filing systems and disc names.
+
+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).
+
+Even when on a single platform (if you can call UNIX a single platform),
+remember not to count on the existence or the contents of
+system-specific files or directories, like F</etc/passwd>,
+F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>. For
+example, F</etc/passwd> may exist but it may not contain the encrypted
+passwords because the system is using some form of enhanced security --
+or it may not contain all the accounts because the system is using NIS. 
+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.
+
+Don't assume a text file will end with a newline.
+
+Do not have two files of the same name with different case, like
+F<test.pl> and F<Test.pl>, as many platforms have case-insensitive
+filenames.  Also, try not to have non-word characters (except for C<.>)
+in the names, and keep them to the 8.3 convention, for maximum
+portability.
+
+Likewise, if using C<AutoSplit>, try to keep the split functions to
+8.3 naming and case-insensitive conventions; or, at the very least,
+make it so the resulting files have a unique (case-insensitively)
+first 8 characters.
+
+There certainly can be whitespace in filenames.  Many systems (DOS,
+VMS) cannot have more than one C<"."> in their filenames.
+
+Don't assume C<E<gt>> won't be the first character of a filename.
+Always use C<E<lt>> explicitly to open a file for reading.
+
+    open(FILE, "<$existing_file") or die $!;
+
+Actually, though, if filenames might use strange characters, it is
+safest to open it with C<sysopen> instead of C<open>, which is magic.
+
+
+=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 open the same file more than once at a time for writing, as some
+operating systems put mandatory locks on such files.
+
+Don't count on a specific environment variable existing in C<%ENV>.
+Don't count on C<%ENV> entries being case-sensitive, or even
+case-preserving.
+
+Don't count on signals.
+
+Don't count on filename globbing.  Use C<opendir>, C<readdir>, and
+C<closedir> instead.
+
+Don't count on per-program environment variables, or per-program current
+directories.
+
+Don't count on specific values of C<$!>.
+
+
+=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<|>, nor 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).
+
+The UNIX System V IPC (C<msg*(), sem*(), shm*()>) is not available
+even in all UNIX platforms.
+
+
+=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 only 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 00:00:00, January 1, 1970,
+because that is OS-specific.  Better to store a date in an unambiguous
+representation.  The ISO 8601 standard defines YYYY-MM-DD as the date
+format.  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 Character sets and character encoding
+
+Assume very little about character sets.  Do not assume anything about
+the numerical values (C<ord()>, C<chr()>) of characters.  Do not
+assume that the alphabetic characters are encoded contiguously (in
+numerical sense).  Do not assume anything about the ordering of the
+characters.  The lowercase letters may come before or after the
+uppercase letters, the lowercase and uppercase may be interlaced so
+that both 'a' and 'A' come before the 'b', the accented and other
+international characters may be interlaced so that E<auml> comes
+before the 'b'.
+
+
+=head2 Internationalisation
+
+If you may assume POSIX (a rather large assumption, that in practice
+means UNIX), you may read more about the POSIX locale system from
+L<perllocale>.  The locale system at least attempts to make things a
+little bit more portable, or at least more convenient and
+native-friendly for non-English users.  The system affects character
+sets and encoding, and date and time formatting, among other things.
+
+
+=head2 System Resources
+
+If your code is destined for systems with severely constrained (or
+missing!) virtual memory systems then you want to be I<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 multi-user 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 many 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
+
+Modules uploaded to CPAN are tested by a variety of volunteers on
+different platforms.  These CPAN testers are notified by mail of each
+new upload, and reply to the list with PASS, FAIL, NA (not applicable to
+this platform), or UNKNOWN (unknown), along with any relevant notations.
+
+The purpose of the testing is twofold: one, to help developers fix any
+problems in their code that crop up because of lack of testing on other
+platforms; 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 C<uname -a> (or a similar command)
+at the shell prompt.  Here, for example, are a few of the more popular
+Unix flavors:
+
+    uname        $^O        $Config{'archname'}
+    -------------------------------------------
+    AIX          aix        aix
+    FreeBSD      freebsd    freebsd-i386    
+    Linux        linux      i386-linux
+    HP-UX        hpux       PA-RISC1.1
+    IRIX         irix       irix
+    OSF1         dec_osf    alpha-dec_osf
+    SunOS        solaris    sun4-solaris
+    SunOS        solaris    i86pc-solaris
+    SunOS4       sunos      sun4-sunos
+
+Note that because the C<$Config{'archname'}> may depend on the hardware
+architecture it may vary quite a lot, much more than the C<$^O>.
+
+=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 filesystem can only accommodate "8.3" style filenames.  Under
+the "case insensitive, but case preserving" HPFS (OS/2) and NTFS (NT)
+filesystems 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.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html> or
+C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>
+
+=item Build instructions for Win32, L<perlwin32>.
+
+=item The ActiveState Pages, C<http://www.activestate.com/>
+
+=back
+
+
+=head2 S<Mac OS>
+
+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> and L<"CPAN Testers">
+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 the
+C<Mac::Files> module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>.
+
+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 programs 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';
+
+S<Mac OS X>, to be based on NeXT's OpenStep OS, will (in theory) be able
+to run MacPerl natively, but Unix perl will also run natively under the
+built-in Unix environment.
+
+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 had an eight level limit on directory depths from any rooted logical
+(allowing 16 levels overall) prior to VMS 7.2.  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 VOS
+
+Perl on VOS is discussed in F<README.vos> in the perl distribution.
+Note that perl on VOS can accept either VOS- or Unix-style file
+specifications as in either of the following:
+
+    $ perl -ne "print if /perl_setup/i" >system>notices
+    $ perl -ne "print if /perl_setup/i" /system/notices
+
+or even a mixture of both as in:
+
+    $ perl -ne "print if /perl_setup/i" >system/notices
+
+Note that even though VOS allows the slash character to appear in object
+names, because the VOS port of Perl interprets it as a pathname
+delimiting character, VOS files, directories, or links whose names
+contain a slash character cannot be processed.  Such files must be
+renamed before they can be processed by Perl.
+
+The following C functions are unimplemented on VOS, and any attempt by
+Perl to use them will result in a fatal error message and an immediate
+exit from Perl:  dup, do_aspawn, do_spawn, fork, waitpid.  Once these
+functions become available in the VOS POSIX.1 implementation, you can
+either recompile and rebind Perl, or you can download a newer port from
+ftp.stratus.com.
+
+The value of C<$^O> on VOS is "VOS".  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(/VOS/, @INC)) {
+        print "I'm on a Stratus box!\n";
+    } else {
+        print "I'm not on a Stratus box!\n";
+        die;
+    }
+
+    if (grep(/860/, @INC)) {
+        print "This box is a Stratus XA/R!\n";
+    } elsif (grep(/7100/, @INC)) {
+        print "This box is a Stratus HP 7100 or 8000!\n";
+    } elsif (grep(/8000/, @INC)) {
+        print "This box is a Stratus HP 8000!\n";
+    } else {
+        print "This box is a Stratus 68K...\n";
+    }
+
+Also see:
+
+=over 4
+
+=item L<README.vos>
+
+=item VOS mailing list
+
+There is no specific mailing list for Perl on VOS.  You can post
+comments to the comp.sys.stratus newsgroup, or subscribe to the general
+Stratus mailing list.  Send a letter with "Subscribe Info-Stratus" in
+the message body to majordomo@list.stratagy.com.
+
+=item VOS Perl on the web at C<http://ftp.stratus.com/pub/vos/vos.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 & VM/ESA 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 & VM/ESA).  Note that on
+the mainframe perl currently works under the "Unix system services
+for OS/390" (formerly known as OpenEdition) and VM/ESA OpenEdition.
+
+As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
+sub-systems do not support the C<#!> shebang trick for script invocation.
+Hence, on OS/390 and VM/ESA perl scripts can be 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 some 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 Unix and OS/390 & VM/ESA):
+
+    print "Content-type: text/html\r\n\r\n";
+
+The value of C<$^O> on OS/390 is "os390".
+
+The value of C<$^O> on VM/ESA is "vmesa".
+
+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 Acorn RISC OS
+
+As Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
+Unix and Unix filename emulation is turned on by default, it is quite
+likely that most simple scripts will work "out of the box".  The native
+filing system is modular, and individual filing systems are free to be
+case-sensitive or insensitive, and are usually case-preserving.  Some
+native filing systems have name length limits which file and directory
+names are silently truncated to fit - scripts should be aware that the
+standard disc filing system currently has a name length limit of B<10>
+characters, with up to 77 items in a directory, but other filing systems
+may not impose such limitations.
+
+Native filenames are of the form
+
+    Filesystem#Special_Field::DiscName.$.Directory.Directory.File
+
+where
+
+    Special_Field is not usually present, but may contain . and $ .
+    Filesystem =~ m|[A-Za-z0-9_]|
+    DsicName   =~ m|[A-Za-z0-9_/]|
+    $ represents the root directory
+    . is the path separator
+    @ is the current directory (per filesystem but machine global)
+    ^ is the parent directory
+    Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
+
+The default filename translation is roughly C<tr|/.|./|;>
+
+Note that C<"ADFS::HardDisc.$.File" ne 'ADFS::HardDisc.$.File'> and that
+the second stage of C<$> interpolation in regular expressions will fall
+foul of the C<$.> if scripts are not careful.
+
+Logical paths specified by system variables containing comma-separated
+search lists are also allowed, hence C<System:Modules> is a valid
+filename, and the filesystem will prefix C<Modules> with each section of
+C<System$Path> until a name is made that points to an object on disc.
+Writing to a new file C<System:Modules> would only be allowed if
+C<System$Path> contains a single item list.  The filesystem will also
+expand system variables in filenames if enclosed in angle brackets, so
+C<E<lt>System$DirE<gt>.Modules> would look for the file
+S<C<$ENV{'System$Dir'} . 'Modules'>>.  The obvious implication of this is
+that B<fully qualified filenames can start with C<E<lt>E<gt>>> and should
+be protected when C<open> is used for input.
+
+Because C<.> was in use as a directory separator and filenames could not
+be assumed to be unique after 10 characters, Acorn implemented the C
+compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
+filenames specified in source code and store the respective files in
+subdirectories named after the suffix. Hence files are translated:
+
+    foo.h           h.foo
+    C:foo.h         C:h.foo        (logical path variable)
+    sys/os.h        sys.h.os       (C compiler groks Unix-speak)
+    10charname.c    c.10charname
+    10charname.o    o.10charname
+    11charname_.c   c.11charname   (assuming filesystem truncates at 10)
+
+The Unix emulation library's translation of filenames to native assumes
+that this sort of translation is required, and allows a user defined list
+of known suffixes which it will transpose in this fashion.  This may
+appear transparent, but consider that with these rules C<foo/bar/baz.h>
+and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
+C<glob> cannot and do not attempt to emulate the reverse mapping.  Other
+C<.>s in filenames are translated to C</>.
+
+As implied above the environment accessed through C<%ENV> is global, and
+the convention is that program specific environment variables are of the
+form C<Program$Name>.  Each filing system maintains a current directory,
+and the current filing system's current directory is the B<global> current
+directory.  Consequently, sociable scripts don't change the current
+directory but rely on full pathnames, and scripts (and Makefiles) cannot
+assume that they can spawn a child process which can change the current
+directory without affecting its parent (and everyone else for that
+matter).
+
+As native operating system filehandles are global and currently are
+allocated down from 255, with 0 being a reserved value the Unix emulation
+library emulates Unix filehandles.  Consequently, you can't rely on
+passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
+
+The desire of users to express filenames of the form
+C<E<lt>Foo$DirE<gt>.Bar> on the command line unquoted causes problems,
+too: C<``> command output capture has to perform a guessing game.  It
+assumes that a string C<E<lt>[^E<lt>E<gt>]+\$[^E<lt>E<gt>]E<gt>> is a
+reference to an environment variable, whereas anything else involving
+C<E<lt>> or C<E<gt>> is redirection, and generally manages to be 99%
+right.  Of course, the problem remains that scripts cannot rely on any
+Unix tools being available, or that any tools found have Unix-like command
+line arguments.
+
+Extensions and XS are, in theory, buildable by anyone using free tools.
+In practice, many don't, as users of the Acorn platform are used to binary
+distribution.  MakeMaker does run, but no available make currently copes
+with MakeMaker's makefiles; even if/when this is fixed, the lack of a
+Unix-like shell can cause problems with makefile rules, especially lines
+of the form C<cd sdbm && make all>, and anything using quoting.
+
+"S<RISC OS>" is the proper name for the operating system, but the value
+in C<$^O> is "riscos" (because we don't like shouting).
+
+Also see:
+
+=over 4
+
+=item perl list
+
+=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: aos, atari, lynxos, 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 perl5-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.
+
+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.pm> 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<-s> returns the size of the data fork, not the total size of data fork
+plus resource fork.  (S<Mac OS>).
+
+C<-s> by name on an open file will return the space reserved on disk,
+rather than the current extent.  C<-s> on an open filehandle returns the
+current size. (S<RISC OS>)
+
+C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
+C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+
+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, S<RISC OS>)
+
+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 may
+affect S<Mac OS> often. (S<Mac OS>)
+
+C<-x> (or C<-X>) determine if a file ends in one of the executable
+suffixes. C<-S> is meaningless. (Win32)
+
+C<-x> (or C<-X>) determine if a file has an executable file type.
+(S<RISC OS>)
+
+=item binmode FILEHANDLE
+
+Meaningless. (S<Mac OS>, S<RISC 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)
+
+Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
+
+Access permissions are mapped onto VOS access-control list changes. (VOS)
+
+=item chown LIST
+
+Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS)
+
+Does nothing, but won't fail. (Win32)
+
+=item chroot FILENAME
+
+=item chroot
+
+Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA)
+
+=item crypt PLAINTEXT,SALT
+
+May not be available if library or source was not provided when building
+perl. (Win32)
+
+Not implemented. (VOS)
+
+=item dbmclose HASH
+
+Not implemented. (VMS, Plan9, VOS)
+
+=item dbmopen HASH,DBNAME,MODE
+
+Not implemented. (VMS, Plan9, VOS)
+
+=item dump LABEL
+
+Not useful. (S<Mac OS>, S<RISC OS>)
+
+Not implemented. (Win32)
+
+Invokes VMS debugger. (VMS)
+
+=item exec LIST
+
+Not implemented. (S<Mac OS>)
+
+Implemented via Spawn. (VM/ESA)
+
+=item fcntl FILEHANDLE,FUNCTION,SCALAR
+
+Not implemented. (Win32, VMS)
+
+=item flock FILEHANDLE,OPERATION
+
+Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
+
+Available only on Windows NT (not on Windows 95). (Win32)
+
+=item fork
+
+Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>, VOS, VM/ESA)
+
+=item getlogin
+
+Not implemented. (S<Mac OS>, S<RISC OS>)
+
+=item getpgrp PID
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
+
+=item getppid
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+
+=item getpriority WHICH,WHO
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
+
+=item getpwnam NAME
+
+Not implemented. (S<Mac OS>, Win32)
+
+Not useful. (S<RISC OS>)
+
+=item getgrnam NAME
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+
+=item getnetbyname NAME
+
+Not implemented. (S<Mac OS>, Win32, Plan9)
+
+=item getpwuid UID
+
+Not implemented. (S<Mac OS>, Win32)
+
+Not useful. (S<RISC OS>)
+
+=item getgrgid GID
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+
+=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, VM/ESA)
+
+=item getgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
+
+=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, S<RISC OS>)
+
+=item setgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+
+=item sethostent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
+
+=item setnetent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
+
+=item setprotoent STAYOPEN
+
+Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
+
+=item setservent STAYOPEN
+
+Not implemented. (Plan9, Win32, S<RISC OS>)
+
+=item endpwent
+
+Not implemented. (S<Mac OS>, Win32, VM/ESA)
+
+=item endgrent
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VM/ESA)
+
+=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)
+
+Globbing built-in, but only C<*> and C<?> metacharacters are supported.
+Globbing relies on operating system calls, which may return filenames
+in any order.  As most filesystems are case-insensitive, even "sorted"
+filenames will not be in case-sensitive order. (S<RISC OS>)
+
+=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)
+
+Available only for socket handles. (S<RISC OS>)
+
+=item kill LIST
+
+Not implemented, hence not useful for taint checking. (S<Mac OS>,
+S<RISC 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, S<RISC OS>)
+
+Link count not updated because hard links are not quite that hard
+(They are sort of half-way between hard and soft links). (AmigaOS)
+
+=item lstat FILEHANDLE
+
+=item lstat EXPR
+
+=item lstat
+
+Not implemented. (VMS, S<RISC OS>)
+
+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, S<RISC OS>, VOS)
+
+=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, S<RISC OS>)
+
+=item pipe READHANDLE,WRITEHANDLE
+
+Not implemented. (S<Mac OS>)
+
+Very limited functionality. (MiNT)
+
+=item readlink EXPR
+
+=item readlink
+
+Not implemented. (Win32, VMS, S<RISC OS>)
+
+=item select RBITS,WBITS,EBITS,TIMEOUT
+
+Only implemented on sockets. (Win32)
+
+Only reliable on sockets. (S<RISC OS>)
+
+=item semctl ID,SEMNUM,CMD,ARG
+
+=item semget KEY,NSEMS,FLAGS
+
+=item semop KEY,OPSTRING
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
+
+=item setpgrp PID,PGRP
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
+
+=item setpriority WHICH,WHO,PRIORITY
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
+
+=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, S<RISC OS>, VOS)
+
+=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
+
+=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)
+
+mtime, atime and ctime all return the last modification time.  Device and
+inode are not necessarily reliable.  (S<RISC OS>)
+
+=item symlink OLDFILE,NEWFILE
+
+Not implemented. (Win32, VMS, S<RISC OS>)
+
+=item syscall LIST
+
+Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
+
+=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
+
+The traditional "0", "1", and "2" MODEs are implemented with different
+numeric values on some systems.  The flags exported by C<Fcntl>
+(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though.  (S<Mac
+OS>, OS/390, VM/ESA)
+
+=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)
+
+There is no shell to process metacharacters, and the native standard is
+to pass a command line terminated by "\n" "\r" or "\0" to the spawned
+program.  Redirection such as C<E<gt> foo> is performed (if at all) by
+the run time library of the spawned program.  C<system> I<list> will call
+the Unix emulation library's C<exec> emulation, which attempts to provide
+emulation of the stdin, stdout, stderr in force in the parent, providing
+the child program uses a compatible version of the emulation library.
+I<scalar> will call the native command line direct and no such emulation
+of a child Unix program will exists.  Mileage B<will> vary.  (S<RISC OS>)
+
+Far from being POSIX compliant.  Because there may be no underlying
+/bin/sh tries to work around the problem by forking and execing the
+first token in its argument string.  Handles basic redirection
+("E<lt>" or "E<gt>") on its own behalf. (MiNT)
+
+=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)
+
+Not useful. (S<RISC OS>)
+
+=item truncate FILEHANDLE,LENGTH
+
+=item truncate EXPR,LENGTH
+
+Not implemented. (VMS)
+
+Truncation to zero-length only. (VOS)
+
+If a FILEHANDLE is supplied, it must be writable and opened in append
+mode (i.e., use C<open(FH, '>>filename')>
+or C<sysopen(FH,...,O_APPEND|O_RDWR)>.  If a filename is supplied, it
+should not be held open elsewhere. (Win32)
+
+=item umask EXPR
+
+=item umask
+
+Returns undef where unavailable, as of version 5.005.
+
+C<umask()> works but the correct permissions are only set when the file
+is finally close()d. (AmigaOS)
+
+=item utime LIST
+
+Only the modification time is updated. (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
+used.  The FAT filesystem typically does not support an "access
+time" field, and it may limit timestamps to a granularity of
+two seconds. (Win32)
+
+=item wait
+
+=item waitpid PID,FLAGS
+
+Not implemented. (S<Mac OS>, VOS)
+
+Can only be applied to process handles returned for processes spawned
+using C<system(1, ...)>. (Win32)
+
+Not useful. (S<RISC OS>)
+
+=back
+
+=head1 CHANGES
+
+=over 4
+
+=item v1.39, 11 February, 1999
+
+Changes from Jarkko and EMX URL fixes Michael Schwern.  Additional
+note about newlines added.
+
+=item v1.38, 31 December 1998
+
+More changes from Jarkko.
+
+=item v1.37, 19 December 1998
+
+More minor changes.  Merge two separate version 1.35 documents.
+
+=item v1.36, 9 September 1998
+
+Updated for Stratus VOS.  Also known as version 1.35.
+
+=item v1.35, 13 August 1998
+
+Integrate more minor changes, plus addition of new sections under
+L<"ISSUES">: L<"Numbers endianness and Width">,
+L<"Character sets and character encoding">,
+L<"Internationalisation">.
+
+=item v1.33, 06 August 1998
+
+Integrate more minor changes.
+
+=item v1.32, 05 August 1998
+
+Integrate more minor changes.
+
+=item v1.30, 03 August 1998
+
+Major update for RISC OS, other minor changes.
+
+=item v1.23, 10 July 1998
+
+First public release with perl5.005.
+
+=back
+
+=head1 AUTHORS / CONTRIBUTORS
+
+Abigail E<lt>abigail@fnx.comE<gt>,
+Charles Bailey E<lt>bailey@newman.upenn.eduE<gt>,
+Graham Barr E<lt>gbarr@pobox.comE<gt>,
+Tom Christiansen E<lt>tchrist@perl.comE<gt>,
+Nicholas Clark E<lt>Nicholas.Clark@liverpool.ac.ukE<gt>,
+Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>,
+Dominic Dunlop E<lt>domo@vo.luE<gt>,
+Neale Ferguson E<lt>neale@mailbox.tabnsw.com.auE<gt>
+Paul Green E<lt>Paul_Green@stratus.comE<gt>,
+M.J.T. Guy E<lt>mjtg@cus.cam.ac.ukE<gt>,
+Jarkko Hietaniemi E<lt>jhi@iki.fi<gt>,
+Luther Huffman E<lt>lutherh@stratcom.comE<gt>,
+Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>,
+Andreas J. KE<ouml>nig E<lt>koenig@kulturbox.deE<gt>,
+Markus Laker E<lt>mlaker@contax.co.ukE<gt>,
+Andrew M. Langmead E<lt>aml@world.std.comE<gt>,
+Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>,
+Chris Nandor E<lt>pudge@pobox.comE<gt>,
+Matthias Neeracher E<lt>neeri@iis.ee.ethz.chE<gt>,
+Gary Ng E<lt>71564.1743@CompuServe.COME<gt>,
+Tom Phoenix E<lt>rootbeer@teleport.comE<gt>,
+Peter Prymmer E<lt>pvhp@forte.comE<gt>,
+Hugo van der Sanden E<lt>hv@crypt0.demon.co.ukE<gt>,
+Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>,
+Paul J. Schinder E<lt>schinder@pobox.comE<gt>,
+Michael G Schwern E<lt>schwern@pobox.comE<gt>,
+Dan Sugalski E<lt>sugalskd@ous.eduE<gt>,
+Nathan Torkington E<lt>gnat@frii.comE<gt>.
+
+This document is maintained by Chris Nandor
+E<lt>pudge@pobox.comE<gt>.
+
+=head1 VERSION
+
+Version 1.39, last modified 11 February 1999