perlport - Writing portable Perl


DESCRIPTION

       Perl runs on numerous operating systems.  While most of
       them share much in common, they also have their own unique
       features.

       This document is meant to help you to find out what con­
       stitutes portable Perl code.  That way once you make a
       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 one
       particular type of computer and taking advantage of a full
       range of them.  Naturally, as you broaden your range and
       become more diverse, the common factors drop, and you are
       left with an increasingly smaller area 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 under which part of the tradeoff curve you
       want to operate.  Specifically, you must decide whether it
       is important that the task that you are coding have the
       full generality of being portable, or whether to just get
       the job done right now.  This is the hardest choice to be
       made.  The rest is easy, because Perl provides many
       choices, whichever way you want to approach your problem.

       Looking at it another way, writing portable code is usu­
       ally about willfully limiting your available choices.
       Naturally, it takes discipline and sacrifice to do that.
       The product of portability and convenience may be a con­
       stant.  You have been warned.

       Be aware of two important points:

       Not all Perl programs have to be portable
           There is no reason you should not use Perl as a lan­
           guage to glue Unix tools together, or to prototype a
           Macintosh application, or to manage the Windows reg­
           istry.  If it makes no sense to aim for portability
           for one reason or another in a given program, then
           don't bother.

       Nearly all of Perl already is portable
           Don't be fooled into thinking that it is hard to cre­
           ate 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 are some
           significant issues in writing portable code, and this
           document is entirely about those issues.

       done using a whole range of platforms, think about 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 plat­
       form 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, Mac OS, VMS, etc.), consider writing plat­
       form-specific code.

       When the code will run on only two or three operating sys­
       tems, you may need to consider only 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 (the section on "ISSUES", plat­
       form-specific issues (the section on "PLATFORMS", and
       built-in perl functions that behave differently on various
       ports (the section on "FUNCTION IMPLEMENTATIONS".

       This information should not be considered complete; it
       includes possibly transient information about idiosyn­
       crasies 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 (<IMG SRC="yel­
       low_sign.gif" ALT="Under Construction">).


ISSUES

       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 `\012', one type of
       DOSish I/O uses `\015\012', and Mac OS uses `\015'.

       Perl uses `\n' to represent the "logical" newline, where
       what is logical may depend on the platform in use.  In
       MacPerl, `\n' always means `\015'.  In DOSish perls, `\n'
       usually means `\012', but when accessing a file in "text"
       mode, STDIO translates it to (or from) `\015\012', depend­
       ing on whether you're reading or writing.  Unix does the
       same thing on ttys in canonical mode.  `\015\012' is com­
       monly referred to as CRLF.

       Because of the "text" mode translation, DOSish perls have
       limitations in using `seek' and `tell' on a file accessed
       in "text" mode.  Stick to `seek'-ing to locations you got
       from `tell' (and no others), and you are usually free to
       use `seek' and `tell' even in "text" mode.  Using `seek'
       or `tell' or other file operations may be non-portable.
       If you use `binmode' on a file, however, you can usually


       A common misconception in socket programming is that `\n'
       eq `\012' everywhere.  When using protocols such as common
       Internet protocols, `\012' and `\015' are called for
       specifically, and the values of the logical `\n' and `\r'
       (carriage return) are not reliable.

           print SOCKET "Hi there, client!\r\n";      # WRONG
           print SOCKET "Hi there, client!\015\012";  # RIGHT

       However, using `\015\012' (or `\cM\cJ', or `\x0D\x0A') can
       be tedious and unsightly, as well as confusing to those
       maintaining the code.  As such, the 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 from a socket, remember that the default
       input record separator `$/' is `\n', but robust socket
       code will recognize as either `\012' or `\015\012' as end
       of line:

           while (<SOCKET>) {
               # ...
           }

       Because both CRLF and LF end in LF, the input record sepa­
       rator can be set to LF and any CR stripped later.  Better
       to write:

           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
           }

       This example is preferred over the previous one--even for
       Unix platforms--because now any `\015''s (`\cM''s) are
       stripped out (and there was much rejoicing).

       Similarly, functions that return text data--such as a
       function that fetches a web page--should sometimes trans­
       late newlines before returning the data, if they've not
       yet been translated to the local newline representation.
       A single line of code will often suffice:

           $data =~ s/\015?\012/\n/g;
           return $data;

       Some of this may be confusing.  Here's a handy reference

       and stick it in your wallet.

           LF  ==  \012  ==  \x0A  ==  \cJ  ==  ASCII 10
           CR  ==  \015  ==  \x0D  ==  \cM  ==  ASCII 13

                    | Unix | DOS  | Mac  |
               ---------------------------
               \n   |  LF  |  LF  |  CR  |
               \r   |  CR  |  CR  |  LF  |
               \n * |  LF  | CRLF |  CR  |
               \r * |  CR  |  CR  |  LF  |
               ---------------------------
               * text-mode STDIO

       The Unix column assumes that you are not accessing a
       serial line (like a tty) in canonical mode.  If you are,
       then CR on input becomes "\n", and "\n" on output becomes
       CRLF.

       These are just the most common definitions of `\n' and
       `\r' in Perl.  There may well be others.

       Numbers endianness and Width

       Different CPUs store integers and floating point numbers
       in different orders (called endianness) and widths (32-bit
       and 64-bit being the most common today).  This affects
       your programs when they attempt to transfer numbers in
       binary format from one CPU architecture to another, usu­
       ally either "live" via network connection, or by storing
       the numbers to secondary storage such as a disk file or
       tape.

       Conflicting storage orders make utter mess out of the num­
       bers.  If a little-endian host (Intel, VAX) 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 `pack' and `unpack' formats
       `n' and `N', the "network" orders.  These are guaranteed
       to be portable.

       You can explore the endianness of your platform by unpack­
       ing a data structure packed in native format such as:

           print unpack("h*", pack("s2", 1, 2)), "\n";
           # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
           # '00100020' on e.g. Motorola 68040

       If you need to distinguish between endian architectures
       you could use either of the variables set like so:

           $is_litte_endian = unpack("h*", pack("s", 1)) =~ /^1/;

       Differing widths can cause truncation even between plat­
       forms 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 else consider using modules like
       Data::Dumper (included in the standard distribution as of
       Perl 5.005) and Storable.  Keeping all data as text sig­
       nificantly simplifies matters.

       Files and Filesystems

       Most platforms these days structure files in a hierarchi­
       cal fashion.  So, it is reasonably safe to assume that all
       platforms support the notion of a "path" to uniquely iden­
       tify a file on the system.  How that path is really writ­
       ten, though, differs considerably.

       Atlhough similar, file path specifications differ between
       Unix, Windows, Mac OS, OS/2, VMS, VOS, RISC OS, and proba­
       bly others.  Unix, for example, is one of the few OSes
       that has the elegant idea of a single root directory.

       DOS, OS/2, VMS, VOS, and Windows can work similarly to
       Unix with `/' as path separator, or in their own idiosyn­
       cratic ways (such as having several root directories and
       various "unrooted" device files such NIL: and LPT:).

       Mac OS uses `:' as a path separator instead of `/'.

       The filesystem may support neither hard links (`link') nor
       symbolic links (`symlink', `readlink', `lstat').

       The filesystem may 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 `/' as path sepa­
       rator.  The native pathname characters greater-than, less-
       than, number-sign, and percent-sign are always accepted.

       RISC OS perl can emulate Unix filenames with `/' as path
       separator, or go native and use `.' for path separator and
       `:' to signal filesystems and disk names.

       If all this is intimidating, have no (well, maybe only a

       File::Spec modules provide methods to do the Right Thing
       on whatever platform happens to be running the program.

           use File::Spec::Functions;
           chdir(updir());        # go up one directory
           $file = catfile(curdir(), 'temp', 'file.txt');
           # on Unix and Win32, './temp/file.txt'
           # on Mac OS, ':temp:file.txt'
           # on VMS, '[.temp]file.txt'

       File::Spec is available in the standard distribution as of
       version 5.004_05.  File::Spec::Functions is only in
       File::Spec 0.7 and later, and some versions of perl come
       with version 0.6.  If File::Spec is not updated to 0.7 or
       later, you must use the object-oriented interface from
       File::Spec (or upgrade File::Spec).

       In general, production code should not have file paths
       hardcoded.  Making them user-supplied or read from a con­
       figuration 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 `/' as a path separa­
       tor for subdirectories.

       Also of use is File::Basename from the standard distribu­
       tion, 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 particular system-specific files or
       directories, like /etc/passwd, /etc/sendmail.conf,
       /etc/resolv.conf, or even /tmp/.  For example, /etc/passwd
       may exist but 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, then 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.  They
       should, but people forget.

       Do not have two files of the same name with different
       case, like test.pl and Test.pl, as many platforms have
       case-insensitive filenames.  Also, try not to have non-
       word characters (except for `.')  in the names, and keep
       them to the 8.3 convention, for maximum portability, oner­
       ous a burden though this may appear.

       your functions to 8.3 naming and case-insensitive conven­
       tions; or, at the least, make it so the resulting files
       have a unique (case-insensitively) first 8 characters.

       Whitespace in filenames is tolerated on most systems, but
       not all.  Many systems (DOS, VMS) cannot have more than
       one `.' in their filenames.

       Don't assume `>' won't be the first character of a file­
       name.  Always use `<' explicitly to open a file for read­
       ing, unless you want the user to be able to specify a pipe
       open.

           open(FILE, "< $existing_file") or die $!;

       If filenames might use strange characters, it is safest to
       open it with `sysopen' instead of `open'.  `open' is magic
       and can translate characters like `>', `<', and `|', which
       may be the wrong thing to do.  (Sometimes, though, it's
       the right thing.)

       System Interaction

       Not all platforms provide a command line.  These are usu­
       ally platforms that rely primarily on a Graphical User
       Interface (GUI) for user interaction.  A program requiring
       a command line interface might not work everywhere.  This
       is probably for the user of the program to deal with, so
       don't stay up late worrying about it.

       Some platforms can't delete or rename files held open by
       the system.  Remember to `close' files when you are done
       with them.  Don't `unlink' or `rename' an open file.
       Don't `tie' or `open' a file already tied or opened;
       `untie' or `close' it 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
       `%ENV'.  Don't count on `%ENV' entries being case-sensi­
       tive, or even case-preserving.

       Don't count on signals or `%SIG' for anything.

       Don't count on filename globbing.  Use `opendir', `read­
       dir', and `closedir' instead.

       Don't count on per-program environment variables, or per-
       program current directories.

       Don't count on specific values of `$!'.


       In general, don't directly access the system in code meant
       to be portable.  That means, no `system', `exec', `fork',
       `pipe', ```', `qx//', `open' with a `|', nor any of the
       other things that makes being a perl hacker worth being.

       Commands that launch external processes are generally sup­
       ported on most platforms (though many of them do not sup­
       port any type of forking).  The problem with using them
       arises from what you invoke them on.  External tools are
       often named differently on different platforms, may not be
       available in the same location, migth accept different
       arguments, can behave differently, and often present their
       results in a platform-dependent way.  Thus, you should
       seldom depend on them to produce consistent results. (Then
       again, if you're calling netstat -a, you probably don't
       expect it to run on both Unix and CP/M.)

       One especially common bit of Perl code is opening a pipe
       to sendmail:

           open(MAIL, '|/usr/lib/sendmail -t')
               or die "cannot fork sendmail: $!";

       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 various distributions on CPAN that deal with it.
       Mail::Mailer and Mail::Send in the MailTools distribution
       are commonly used, and provide several mailing methods,
       including mail, sendmail, and direct SMTP (via Net::SMTP)
       if a mail transfer agent is not available.  Mail::Sendmail
       is a standalone module that provides simple, platform-
       independent mailing.

       The Unix System V IPC (`msg*(), sem*(), shm*()') is not
       available even on all Unix platforms.

       The rule of thumb for portable code is: Do it all in
       portable Perl, or use a module (that may internally imple­
       ment it with platform-specific code, but expose a common
       interface).

       External Subroutines (XS)

       XS code can usually 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.

       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 an easier way to achieve portability.

       Standard Modules

       In general, the standard modules work across platforms.
       Notable exceptions are the CPAN module (which currently
       makes connections to external programs that may not be
       available), platform-specific modules (like ExtU­
       tils::MM_VMS), and DBM modules.

       There is no one DBM module available on all platforms.
       SDBM_File and the others are generally available on all
       Unix and DOSish ports, but not in MacPerl, where only
       NBDM_File and DB_File are available.

       The good news is that at least some DBM module should be
       available, and AnyDBM_File will use whichever module it
       can find.  Of course, then the code needs to be fairly
       strict, dropping to the greatest common factor (e.g., not
       exceeding 1K for each record), so that it will work with
       any DBM module.  See the AnyDBM_File manpage for more
       details.

       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 `$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- and implementation-specific.  It
       is better to store a date in an unambiguous representa­
       tion.  The ISO-8601 standard defines "YYYY-MM-DD" as the
       date format.  A text representation (like "1987-12-18")
       can be easily converted into an OS-specific value using a
       module like Date::Parse.  An array of values, such as
       those returned by `localtime', can be converted to an OS-
       specific representation using Time::Local.

       When calculating specific times, such as for tests in time
       or date modules, it may be appropriate to calculate an
       offset for the epoch.

           require Time::Local;
           $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);

       The value for `$offset' in Unix will be `0', but in Mac OS
       will be some large number.  `$offset' can then be added to

       on any system.

       Character sets and character encoding

       Assume little about character sets.  Assume nothing about
       numerical values (`ord', `chr') of characters.  Do not
       assume that the alphabetic characters are encoded contigu­
       ously (in the numeric sense).  Do not assume anything
       about the ordering of the characters.  The lowercase let­
       ters may come before or after the uppercase letters; the
       lowercase and uppercase may be interlaced so that both `a'
       and `A' come before `b'; the accented and other interna­
       tional characters may be interlaced so that ae comes
       before `b'.

       Internationalisation

       If you may assume POSIX (a rather large assumption), you
       may read more about the POSIX locale system from the perl­
       locale manpage.  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--amongst other things.

       System Resources

       If your code is destined for systems with severely con­
       strained (or missing!) virtual memory systems then you
       want to be especially mindful of avoiding wasteful con­
       structs 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 constructs may appear unintuitive to most
       people.  The first repeatedly grows a string, whereas the
       second allocates a large chunk of memory in one go.  On
       some systems, the second is more efficient that the first.

       Security

       Most multi-user platforms provide basic levels of secu­
       rity, usually implemented at the filesystem level.  Some,
       however, do not--unfortunately.  Thus the notion of user
       id, or "home" directory, or even the state of being
       logged-in, may be unrecognizable on many platforms.  If

       ally best to know what type of system you will be running
       under so that you can write code explicitly for that plat­
       form (or class of platforms).

       Style

       For those times when it is necessary to have platform-spe­
       cific code, consider keeping the platform-specific code in
       one place, making porting to other platforms easier.  Use
       the Config module and the special variable `$^O' to dif­
       ferentiate platforms, as described in the section on
       "PLATFORMS".

       Be careful in the tests you supply with your module or
       programs.  Module code may be fully portable, but its
       tests might not be.  This often happens when tests spawn
       off other processes or call external programs to aid in
       the testing, or when (as noted above) the tests assume
       certain things about the filesystem and paths.  Be careful
       not to depend on a specific output style for errors, such
       as when checking `$!' after an system call.  Some plat­
       forms expect a certain output format, and perl on those
       platforms may have been adjusted accordingly.  Most
       specifically, don't anchor a regex when testing an error
       value.


CPAN Testers

       Modules uploaded to CPAN are tested by a variety of volun­
       teers 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 devel­
       opers 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 a given module works
       on a given platform.

       Mailing list: cpan-testers@perl.org

       Testing results: http://testers.cpan.org/


PLATFORMS

       As of version 5.002, Perl is built with a `$^O' variable
       that indicates the operating system it was built on.  This
       was implemented to help speed up code that would otherwise
       have to `use Config' and use the value of `$Con­
       fig{osname}'.  Of course, to get more detailed information
       about the system, looking into `%Config' is certainly rec­
       ommended.

       `%Config' cannot always be trusted, however, because it

       place, then transferred elsewhere, some values may be
       wrong.  The values may even have been edited after the
       fact.

       Unix

       Perl works on a bewildering variety of Unix and Unix-like
       platforms (see e.g. most of the files in the hints/ direc­
       tory in the source code kit).  On most of these systems,
       the value of `$^O' (hence `$Config{'osname'}', too) is
       determined either 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 or
       by testing the file system for the presence of uniquely
       named files such as a kernel or header file.  Here, for
       example, are a few of the more popular Unix flavors:

           uname         $^O        $Config{'archname'}
           --------------------------------------------
           AIX           aix        aix
           BSD/OS        bsdos      i386-bsdos
           dgux          dgux       AViiON-dgux
           DYNIX/ptx     dynixptx   i386-dynixptx
           FreeBSD       freebsd    freebsd-i386
           Linux         linux      arm-linux
           Linux         linux      i386-linux
           Linux         linux      i586-linux
           Linux         linux      ppc-linux
           HP-UX         hpux       PA-RISC1.1
           IRIX          irix       irix
           Mac OS X      rhapsody   rhapsody
           MachTen PPC   machten    powerpc-machten
           NeXT 3        next       next-fat
           NeXT 4        next       OPENSTEP-Mach
           openbsd       openbsd    i386-openbsd
           OSF1          dec_osf    alpha-dec_osf
           reliantunix-n svr4       RM400-svr4
           SCO_SV        sco_sv     i386-sco_sv
           SINIX-N       svr4       RM400-svr4
           sn4609        unicos     CRAY_C90-unicos
           sn6521        unicosmk   t3e-unicosmk
           sn9617        unicos     CRAY_J90-unicos
           SunOS         solaris    sun4-solaris
           SunOS         solaris    i86pc-solaris
           SunOS4        sunos      sun4-sunos

       Because the value of `$Config{archname}' may depend on the
       hardware architecture, it can vary more than the value of
       `$^O'.


       Perl has long been ported to Intel-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 famil­
       iar with COMMAND.COM or CMD.EXE style shells should be
       aware that each of these file specifications may have sub­
       tle 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 `/' or `\' as the path separa­
       tor.  However, many command-line utilities of DOS vintage
       treat `/' as the option prefix, so may get confused by
       filenames containing `/'.  Aside from calling any external
       programs, `/' 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 accommodate only "8.3" style
       filenames.  Under the "case-insensitive, but case-preserv­
       ing" HPFS (OS/2) and NTFS (NT) filesystems you may have to
       be careful about case returned with functions like `read­
       dir' or used with functions like `open' or `opendir'.

       DOS also treats several filenames as special, such as AUX,
       PRN, NUL, CON, COM1, LPT1, LPT2, etc.  Unfortunately,
       sometimes these filenames won't even work if you include
       an explicit directory prefix.  It is best to avoid such
       filenames, if you want your code to be portable to DOS and
       its derivatives.  It's hard to know what these all are,
       unfortunately.

       Users of these operating systems may also wish to make use
       of scripts such as pl2bat.bat or pl2cmd to put wrappers
       around your scripts.

       Newline (`\n') is translated as `\015\012' by STDIO when
       reading from and writing to files (see the section on
       "Newlines").  `binmode(FILEHANDLE)' will keep `\n' trans­
       lated as `\012' for that filehandle.  Since it is a no-op
       on other systems, `binmode' should be used for cross-plat­
       form code that deals with binary data.  That's assuming
       you realize in advance that your data is in binary.  Gen­
       eral-purpose programs should often assume nothing about
       their data.

       The `$^O' variable and the `$Config{archname}' values for
       various DOSish perls are as follows:

           --------------------------------------------
           MS-DOS        dos
           PC-DOS        dos
           OS/2          os2
           Windows 95    MSWin32    MSWin32-x86
           Windows 98    MSWin32    MSWin32-x86
           Windows NT    MSWin32    MSWin32-x86
           Windows NT    MSWin32    MSWin32-ALPHA
           Windows NT    MSWin32    MSWin32-ppc
           Cygwin        cygwin

       Also see:

       ·   The djgpp environment for DOS, http://www.delo­
           rie.com/djgpp/ and the perldos manpage.

       ·   The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
           http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html
           or ftp://hobbes.nmsu.edu/pub/os2/dev/emx.  Also the
           perlos2 manpage.

       ·   Build instructions for Win32 in the perlwin32 manpage,
           or under the Cygnus environment in the perlcygwin man­
           page.

       ·   The `Win32::*' modules in the Win32 manpage.

       ·   The ActiveState Pages, http://www.activestate.com/

       ·   The Cygwin environment for Win32; README.cygwin
           (installed as the perlcygwin manpage), http://source­
           ware.cygnus.com/cygwin/

       ·   The U/WIN environment for Win32,
           <http://www.research.att.com/sw/tools/uwin/

       Build instructions for OS/2, the perlos2 manpage

       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.

       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

       Filenames are limited to 31 characters, and may include
       any character except for null and `:', which is reserved
       as the path separator.

       Instead of `flock', see `FSpSetFLock' and `FSpRstFLock' in
       the Mac::Files module, or `chmod(0444, ...)' and
       `chmod(0666, ...)'.

       In the MacPerl application, you can't run a program from
       the command line; programs that expect `@ARGV' to be popu­
       lated 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
       `@ARGV' with the full pathnames of the files dropped onto
       the script.

       Mac users can run programs under a type of command line
       interface 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 `system', backticks, and piped
       `open'.

       "Mac OS" is the proper name for the operating system, but
       the value in `$^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';

       Mac OS X and Mac OS X Server, based on NeXT's OpenStep OS,
       will (in theory) be able to run MacPerl natively, under
       the "Classic" environment.  The new "Cocoa" environment
       (formerly called the "Yellow Box") may run a slightly mod­
       ified version of MacPerl, using the Carbon interfaces.

       Mac OS X Server and its Open Source version, Darwin, both

       for these is slated for perl 5.6.

       Also see:

       ·   The MacPerl Pages, http://www.macperl.com/ .

       ·   The MacPerl mailing lists, http://www.macperl.org/ .

       ·   MacPerl Module Porters, http://pudge.net/mmp/ .

       VMS

       Perl on VMS is discussed in the perlvms manpage in the
       perl distribution.  Perl on VMS can accept either VMS- or
       Unix-style file specifications as in either of the follow­
       ing:

           $ 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 several 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 `$ ASSIGN/nolog/user SYS$COMMAND:
       SYS$INPUT' if your perl-in-DCL script expects to do things
       like `$read = <STDIN>;'.

       Filenames are in the format "name.extension;version".  The
       maximum length for filenames is 39 characters, and the

       sion is a number from 1 to 32767.  Valid characters are
       `/[A-Z0-9$_-]/'.

       VMS's RMS filesystem is case-insensitive and does not pre­
       serve case.  `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 `readdir' with a file named A.;5 will return a.
       (though that file could be opened with `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 `PERL_ROOT:[LIB.2.3.4.5.6.7.8]' is a valid
       directory specification but
       `PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]' is not.  Makefile.PL
       authors might have to take this into account, but at least
       they can refer to the former as
       `/PERL_ROOT/lib/2/3/4/5/6/7/8/'.

       The 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 help­
       ful for conversions to and from RMS native formats.

       What `\n' represents depends on the type of file opened.
       It could be `\015', `\012', `\015\012', or nothing.  The
       VMS::Stdio module provides access to the special fopen()
       requirements of files with unusual attributes on VMS.

       TCP/IP stacks are optional on VMS, so socket routines
       might not be implemented.  UDP sockets may not be sup­
       ported.

       The value of `$^O' on OpenVMS is "VMS".  To determine the
       architecture that you are running on without resorting to
       loading all of `%Config' you can examine the content of
       the `@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";
           }

       On VMS, perl determines the UTC offset from the `SYS$TIME­
       ZONE_DIFFERENTIAL' logical name.  Although the VMS epoch
       began at 17-NOV-1858 00:00:00.00, calls to `localtime' are
       adjusted to count offsets from 01-JAN-1970 00:00:00.00,
       just like Unix.


       ·   README.vms (installed as the README_vms manpage), the
           perlvms manpage

       ·   vmsperl list, majordomo@perl.org

           (Put the words `subscribe vmsperl' in message body.)

       ·   vmsperl on the web,
           http://www.sidhe.org/vmsperl/index.html

       VOS

       Perl on VOS is discussed in README.vos in the perl distri­
       bution.  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

       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, directo­
       ries, or links whose names contain a slash character can­
       not be processed.  Such files must be renamed before they
       can be processed by Perl.  Note that VOS limits file names
       to 32 or fewer characters.

       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 `$^O' on VOS is "VOS".  To determine the
       architecture that you are running on without resorting to
       loading all of `%Config' you can examine the content of
       the @INC array like so:

           if ($^O =~ /VOS/) {
               print "I'm on a Stratus box!\n";
           } else {
               print "I'm not on a Stratus box!\n";
               die;
           }

               print "This box is a Stratus XA/R!\n";

           } elsif (grep(/7100/, @INC)) {
               print "This box is a Stratus HP 7100 or 8xxx!\n";

           } elsif (grep(/8000/, @INC)) {
               print "This box is a Stratus HP 8xxx!\n";

           } else {
               print "This box is a Stratus 68K!\n";
           }

       Also see:

       ·   README.vos

       ·   The VOS mailing list.

           There is no specific mailing list for Perl on VOS.
           You can post comments to the comp.sys.stratus news­
           group, or subscribe to the general Stratus mailing
           list.  Send a letter with "Subscribe Info-Stratus" in
           the message body to majordomo@list.stratagy.com.

       ·   VOS Perl on the web at http://ftp.stra­
           tus.com/pub/vos/vos.html

       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, and BS2000 for S/390 Mainframes.  Such computers
       use EBCDIC character sets internally (usually Character
       Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC
       for S/390 systems).  On the mainframe perl currently works
       under the "Unix system services for OS/390" (formerly
       known as OpenEdition), VM/ESA OpenEdition, or the BS200
       POSIX-BC system (BS2000 is supported in perl 5.6 and
       greater).  See the perlos390 manpage for details.

       As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA
       these Unix sub-systems do not support the `#!' 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";

       and beyond.  Calls to `system' and backticks can use POSIX
       shell syntax on all S/390 systems.

       On the AS/400, if PERL5 is in your library list, you may
       need to wrap your perl scripts in a CL procedure to invoke
       them like so:

           BEGIN
             CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
           ENDPGM

       This will invoke the perl script hello.pl in the root of
       the QOpenSys file system.  On the AS/400 calls to `system'
       or backticks must use CL syntax.

       On these platforms, bear in mind that the EBCDIC character
       set may have an effect on what happens with some perl
       functions (such as `chr', `pack', `print', `printf',
       `ord', `sort', `sprintf', `unpack'), as well as bit-fid­
       dling with ASCII constants using operators like `^', `&'
       and `|', not to mention dealing with socket interfaces to
       ASCII computers (see the section on "Newlines").

       Fortunately, most web servers for the mainframe will cor­
       rectly translate the `\n' in the following statement to
       its ASCII equivalent (`\r' is the same under both Unix and
       OS/390 & VM/ESA):

           print "Content-type: text/html\r\n\r\n";

       The values of `$^O' on some of these platforms includes:

           uname         $^O        $Config{'archname'}
           --------------------------------------------
           OS/390        os390      os390
           OS400         os400      os400
           POSIX-BC      posix-bc   BS2000-posix-bc
           VM/ESA        vmesa      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"; }

       One thing you may not want to rely on is the EBCDIC encod­
       ing 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


       Also see:

       ·   *

           the perlos390 manpage, README.os390, README.posix-bc,
           README.vmesa

       ·   The perl-mvs@perl.org list is for discussion of port­
           ing issues as well as general usage issues for all
           EBCDIC Perls.  Send a message body of "subscribe perl-
           mvs" to majordomo@perl.org.

       ·   AS/400 Perl information at
           ttp://as400.rochester.ibm.com/ as well as on CPAN in
           the ports/ directory.

       Acorn RISC OS

       Because Acorns use ASCII with newlines (`\n') in text
       files as `\012' like Unix, and because Unix filename emu­
       lation is turned on by default, most simple scripts will
       probably work "out of the box".  The native filesystem is
       modular, and individual filesystems are free to be case-
       sensitive or insensitive, and are usually case-preserving.
       Some native filesystems have name length limits, which
       file and directory names are silently truncated to fit.
       Scripts should be aware that the standard filesystem cur­
       rently has a name length limit of 10 characters, with up
       to 77 items in a directory, but other filesystems may not
       impose such limitations.

       Native filenames are of the form

           Filesystem#Special_Field::DiskName.$.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 `tr|/.|./|;'

       Note that `"ADFS::HardDisk.$.File" ne 'ADFS::Hard­
       Disk.$.File'' and that the second stage of `$' interpola­
       tion in regular expressions will fall foul of the `$.' if
       scripts are not careful.

       comma-separated search lists are also allowed; hence `Sys­
       tem:Modules' is a valid filename, and the filesystem will
       prefix `Modules' with each section of `System$Path' until
       a name is made that points to an object on disk.  Writing
       to a new file `System:Modules' would be allowed only if
       `System$Path' contains a single item list.  The filesystem
       will also expand system variables in filenames if enclosed
       in angle brackets, so `<System$Dir>.Modules' would look
       for the file `$ENV{'System$Dir'} . 'Modules''.  The obvi­
       ous implication of this is that fully qualified filenames
       can start with `<>' and should be protected when `open' is
       used for input.

       Because `.' was in use as a directory separator and file­
       names could not be assumed to be unique after 10 charac­
       ters, Acorn implemented the C compiler to strip the trail­
       ing `.c' `.h' `.s' and `.o' suffix from filenames speci­
       fied in source code and store the respective files in sub­
       directories 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 it allows a user-defined list of known suffixes that
       it will transpose in this fashion.  This may seem trans­
       parent, but consider that with these rules `foo/bar/baz.h'
       and `foo/bar/h/baz' both map to `foo.bar.h.baz', and that
       `readdir' and `glob' cannot and do not attempt to emulate
       the reverse mapping.  Other `.''s in filenames are trans­
       lated to `/'.

       As implied above, the environment accessed through `%ENV'
       is global, and the convention is that program specific
       environment variables are of the form `Program$Name'.
       Each filesystem maintains a current directory, and the
       current filesystem's current directory is the global cur­
       rent directory.  Consequently, sociable programs don't
       change the current directory but rely on full pathnames,
       and programs (and Makefiles) cannot assume that they can
       spawn a child process which can change the current direc­
       tory without affecting its parent (and everyone else for
       that matter).

       Because native operating system filehandles are global and
       are currently allocated down from 255, with 0 being a
       reserved value, the Unix emulation library emulates Unix

       `STDIN', `STDOUT', or `STDERR' to your children.

       The desire of users to express filenames of the form
       `<Foo$Dir>.Bar' on the command line unquoted causes prob­
       lems, too: ```' command output capture has to perform a
       guessing game.  It assumes that a string `<[^<>]+\$[^<>]>'
       is a reference to an environment variable, whereas any­
       thing else involving `<' or `>' is redirection, and gener­
       ally 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 distributions.
       MakeMaker does run, but no available make currently copes
       with MakeMaker's makefiles; even if and when this should
       be fixed, the lack of a Unix-like shell will cause prob­
       lems with makefile rules, especially lines of the form `cd
       sdbm && make all', and anything using quoting.

       "RISC OS" is the proper name for the operating system, but
       the value in `$^O' is "riscos" (because we don't like
       shouting).

       Other perls

       Perl has been ported to many platforms that do not fit
       into any of the categories listed above.  Some, such as
       AmigaOS, Atari MiNT, BeOS, HP MPE/iX, QNX, Plan 9, and
       VOS, have been well-integrated into the standard Perl
       source code kit.  You may need to see the ports/ directory
       on CPAN for information, and possibly binaries, for the
       likes of: aos, Atari ST, lynxos, riscos, Novell Netware,
       Tandem Guardian, etc.  (Yes, we know that some of these
       OSes may fall under the Unix category, but we are not a
       standards body.)

       Some approximate operating system names and their `$^O'
       values in the "OTHER" category include:

           OS            $^O        $Config{'archname'}
           ------------------------------------------
           Amiga DOS     amigaos    m68k-amigos
           MPE/iX        mpeix      PA-RISC1.1

       See also:

       ·   Amiga, README.amiga (installed as the perlamiga man­
           page).

           http://stud.uni-sb.de/~gufl0000/

       ·   Be OS, README.beos

       ·   HP 300 MPE/iX, README.mpeix and Mark Bixby's web page
           http://www.cccd.edu/~markb/perlix.html

       ·   A free perl5-based PERL.NLM for Novell Netware is
           available in precompiled binary and source code form
           from http://www.novell.com/ as well as from CPAN.

           Plan 9, README.plan9


FUNCTION IMPLEMENTATIONS

       Listed below are functions that are either completely
       unimplemented or else have been implemented differently on
       various platforms.  Following each description will be, in
       parentheses, a list of platforms that the description
       applies to.

       The list may well be incomplete, or even wrong in some
       places.  When in doubt, consult the platform-specific
       README files in the Perl source distribution, and any
       other documentation resources accompanying a given port.

       Be aware, moreover, that even among Unix-ish systems there
       are variations.

       For many functions, you can also query `%Config', exported
       by default from the Config module.  For example, to check
       whether the platform has the `lstat' call, check `$Con­
       fig{d_lstat}'.  See the Config manpage for a full descrip­
       tion of available variables.

       Alphabetical Listing of Perl Functions

       -X FILEHANDLE

       -X EXPR

       -X      `-r', `-w', and `-x' have a limited meaning only;
               directories and applications are executable, and
               there are no uid/gid considerations.  `-o' is not
               supported.  (Mac OS)

               `-r', `-w', `-x', and `-o' tell whether the file
               is accessible, which may not reflect UIC-based
               file protections.  (VMS)

               `-s' returns the size of the data fork, not the
               total size of data fork plus resource fork.
               (Mac OS).

               reserved on disk, rather than the current extent.
               `-s' on an open filehandle returns the current
               size.  (RISC OS)

               `-R', `-W', `-X', `-O' are indistinguishable from
               `-r', `-w', `-x', `-o'. (Mac OS, Win32, VMS,
               RISC OS)

               `-b', `-c', `-k', `-g', `-p', `-u', `-A' are not
               implemented.  (Mac OS)

               `-g', `-k', `-l', `-p', `-u', `-A' are not partic­
               ularly meaningful.  (Win32, VMS, RISC OS)

               `-d' is true if passed a device spec without an
               explicit directory.  (VMS)

               `-T' and `-B' are implemented, but might misclas­
               sify Mac text files with foreign characters; this
               is the case will all platforms, but may affect
               Mac OS often.  (Mac OS)

               `-x' (or `-X') determine if a file ends in one of
               the executable suffixes.  `-S' is meaningless.
               (Win32)

               `-x' (or `-X') determine if a file has an exe­
               cutable file type.  (RISC OS)

       alarm SECONDS

       alarm   Not implemented. (Win32)

       binmode FILEHANDLE
               Meaningless.  (Mac OS, 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 `tell' may be affected after
               the call, and the filehandle may be flushed.
               (Win32)

       chmod LIST
               Only limited meaning.  Disabling/enabling write
               permission is mapped to locking/unlocking the
               file. (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-


               Access permissions are mapped onto VOS access-con­
               trol list changes. (VOS)

       chown LIST
               Not implemented. (Mac OS, Win32, Plan9, RISC OS,
               VOS)

               Does nothing, but won't fail. (Win32)

       chroot FILENAME

       chroot  Not implemented. (Mac OS, Win32, VMS, Plan9,
               RISC OS, VOS, VM/ESA)

       crypt PLAINTEXT,SALT
               May not be available if library or source was not
               provided when building perl. (Win32)

               Not implemented. (VOS)

       dbmclose HASH
               Not implemented. (VMS, Plan9, VOS)

       dbmopen HASH,DBNAME,MODE
               Not implemented. (VMS, Plan9, VOS)

       dump LABEL
               Not useful. (Mac OS, RISC OS)

               Not implemented. (Win32)

               Invokes VMS debugger. (VMS)

       exec LIST
               Not implemented. (Mac OS)

               Implemented via Spawn. (VM/ESA)

               Does not automatically flush output handles on
               some platforms.  (SunOS, Solaris, HP-UX)

       fcntl FILEHANDLE,FUNCTION,SCALAR
               Not implemented. (Win32, VMS)

       flock FILEHANDLE,OPERATION
               Not implemented (Mac OS, VMS, RISC OS, VOS).

               Available only on Windows NT (not on Windows 95).
               (Win32)

       fork    Not implemented. (Mac OS, AmigaOS, RISC OS, VOS,
               VM/ESA)

               perlfork manpage.  (Win32)

               Does not automatically flush output handles on
               some platforms.  (SunOS, Solaris, HP-UX)

       getlogin
               Not implemented. (Mac OS, RISC OS)

       getpgrp PID
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS)

       getppid Not implemented. (Mac OS, Win32, VMS, RISC OS)

       getpriority WHICH,WHO
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS, VM/ESA)

       getpwnam NAME
               Not implemented. (Mac OS, Win32)

               Not useful. (RISC OS)

       getgrnam NAME
               Not implemented. (Mac OS, Win32, VMS, RISC OS)

       getnetbyname NAME
               Not implemented. (Mac OS, Win32, Plan9)

       getpwuid UID
               Not implemented. (Mac OS, Win32)

               Not useful. (RISC OS)

       getgrgid GID
               Not implemented. (Mac OS, Win32, VMS, RISC OS)

       getnetbyaddr ADDR,ADDRTYPE
               Not implemented. (Mac OS, Win32, Plan9)

       getprotobynumber NUMBER
               Not implemented. (Mac OS)

       getservbyport PORT,PROTO
               Not implemented. (Mac OS)

       getpwent
               Not implemented. (Mac OS, Win32, VM/ESA)

       getgrent
               Not implemented. (Mac OS, Win32, VMS, VM/ESA)

               Not implemented. (Mac OS, Win32)

       getnetent
               Not implemented. (Mac OS, Win32, Plan9)

       getprotoent
               Not implemented. (Mac OS, Win32, Plan9)

       getservent
               Not implemented. (Win32, Plan9)

       setpwent
               Not implemented. (Mac OS, Win32, RISC OS)

       setgrent
               Not implemented. (Mac OS, Win32, VMS, RISC OS)

       sethostent STAYOPEN
               Not implemented. (Mac OS, Win32, Plan9, RISC OS)

       setnetent STAYOPEN
               Not implemented. (Mac OS, Win32, Plan9, RISC OS)

       setprotoent STAYOPEN
               Not implemented. (Mac OS, Win32, Plan9, RISC OS)

       setservent STAYOPEN
               Not implemented. (Plan9, Win32, RISC OS)

       endpwent
               Not implemented. (Mac OS, MPE/iX, VM/ESA, Win32)

       endgrent
               Not implemented. (Mac OS, MPE/iX, RISC OS, VM/ESA,
               VMS, Win32)

       endhostent
               Not implemented. (Mac OS, Win32)

       endnetent
               Not implemented. (Mac OS, Win32, Plan9)

       endprotoent
               Not implemented. (Mac OS, Win32, Plan9)

       endservent
               Not implemented. (Plan9, Win32)

       getsockopt SOCKET,LEVEL,OPTNAME
               Not implemented. (Mac OS, Plan9)

       glob EXPR

               acters are supported.  (Mac OS)

               This operator is implemented via the File::Glob
               extension on most platforms.  See the File::Glob
               manpage for portability information.

       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. (RISC OS)

       kill SIGNAL, LIST
               Not implemented, hence not useful for taint check­
               ing. (Mac OS, RISC OS)

               `kill()' doesn't have the semantics of `raise()',
               i.e. it doesn't send a signal to the identified
               process like it does on Unix platforms.  Instead
               `kill($sig, $pid)' terminates the process identi­
               fied by $pid, and makes it exit immediately with
               exit status $sig.  As in Unix, if $sig is 0 and
               the specified process exists, it returns true
               without actually terminating it. (Win32)

       link OLDFILE,NEWFILE
               Not implemented. (Mac OS, MPE/iX, VMS, 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)

               Hard links are implemented on Win32 (Windows NT
               and Windows 2000) under NTFS only.

       lstat FILEHANDLE

       lstat EXPR

       lstat   Not implemented. (VMS, RISC OS)

               Return values (especially for device and inode)
               may be bogus. (Win32)

       msgctl ID,CMD,ARG

       msgget KEY,FLAGS

       msgsnd ID,MSG,FLAGS

               Not implemented. (Mac OS, Win32, VMS, Plan9,
               RISC OS, VOS)

       open FILEHANDLE,EXPR

       open FILEHANDLE
               The `|' variants are supported only if ToolServer
               is installed.  (Mac OS)

               open to `|-' and `-|' are unsupported. (Mac OS,
               Win32, RISC OS)

               Opening a process does not automatically flush
               output handles on some platforms.  (SunOS,
               Solaris, HP-UX)

       pipe READHANDLE,WRITEHANDLE
               Not implemented. (Mac OS)

               Very limited functionality. (MiNT)

       readlink EXPR

       readlink
               Not implemented. (Win32, VMS, RISC OS)

       select RBITS,WBITS,EBITS,TIMEOUT
               Only implemented on sockets. (Win32)

               Only reliable on sockets. (RISC OS)

               Note that the `socket FILEHANDLE' form is gener­
               ally portable.

       semctl ID,SEMNUM,CMD,ARG

       semget KEY,NSEMS,FLAGS

       semop KEY,OPSTRING
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS)

       setgrent
               Not implemented. (MPE/iX, Win32)

       setpgrp PID,PGRP
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS)

       setpriority WHICH,WHO,PRIORITY
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS)

               Not implemented. (MPE/iX, Win32)

       setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
               Not implemented. (Mac OS, Plan9)

       shmctl ID,CMD,ARG

       shmget KEY,SIZE,FLAGS

       shmread ID,VAR,POS,SIZE

       shmwrite ID,STRING,POS,SIZE
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS)

       socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS, VM/ESA)

       stat FILEHANDLE

       stat EXPR

       stat    mtime and atime are the same thing, and ctime is
               creation time instead of inode change time.
               (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 modifi­
               cation time.  Device and inode are not necessarily
               reliable.  (RISC OS)

       symlink OLDFILE,NEWFILE
               Not implemented. (Win32, VMS, RISC OS)

       syscall LIST
               Not implemented. (Mac OS, Win32, VMS, RISC OS,
               VOS, VM/ESA)

       sysopen FILEHANDLE,FILENAME,MODE,PERMS
               The traditional "0", "1", and "2" MODEs are imple­
               mented with different numeric values on some sys­
               tems.  The flags exported by `Fcntl' (O_RDONLY,
               O_WRONLY, O_RDWR) should work everywhere though.
               (Mac OS, OS/390, VM/ESA)

       system LIST
               Only implemented if ToolServer is installed.
               (Mac OS)

               specified in `$ENV{PERL5SHELL}'.  `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 `wait' or `waitpid'.  Failure to
               spawn() a subprocess is indicated by setting $? to
               "255 << 8".  `$?' is set in a way compatible with
               Unix (i.e. the exitstatus of the subprocess is
               obtained by "$? >> 8", as described in the docu­
               mentation).  (Win32)

               There is no shell to process metacharacters, and
               the native standard is to pass a command line ter­
               minated by "\n" "\r" or "\0" to the spawned pro­
               gram.  Redirection such as `> foo' is performed
               (if at all) by the run time library of the spawned
               program.  `system' list will call the Unix emula­
               tion library's `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.  scalar will call the native command line
               direct and no such emulation of a child Unix pro­
               gram will exists.  Mileage will vary.  (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
               ("<" or ">") on its own behalf. (MiNT)

               Does not automatically flush output handles on
               some platforms.  (SunOS, Solaris, HP-UX)

       times   Only the first entry returned is nonzero. (Mac OS)

               "cumulative" times will be bogus.  On anything
               other than Windows NT or Windows 2000, "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. (RISC OS)

       truncate FILEHANDLE,LENGTH

       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 `open(FH,

               `sysopen(FH,...,O_APPEND|O_RDWR)'.  If a filename
               is supplied, it should not be held open elsewhere.
               (Win32)

       umask EXPR

       umask   Returns undef where unavailable, as of version
               5.005.

               `umask' works but the correct permissions are set
               only when the file is finally closed. (AmigaOS)

       utime LIST
               Only the modification time is updated. (Mac OS,
               VMS, 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)

       wait

       waitpid PID,FLAGS
               Not implemented. (Mac OS, VOS)

               Can only be applied to process handles returned
               for processes spawned using `system(1, ...)'.
               (Win32)

               Not useful. (RISC OS)


CHANGES

       v1.47, 22 March 2000
           Various cleanups from Tom Christiansen, including
           migration of long platform listings from the perl man­
           page.

       v1.46, 12 February 2000
           Updates for VOS and MPE/iX. (Peter Prymmer)  Other
           small changes.

       v1.45, 20 December 1999
           Small changes from 5.005_63 distribution, more changes
           to EBCDIC info.

       v1.44, 19 July 1999
           A bunch of updates from Peter Prymmer for `$^O' val­
           ues, endianness, File::Spec, VMS, BS2000, OS/400.

           Added a lot of cleaning up from Tom Christiansen.

       v1.42, 22 May 1999
           Added notes about tests, sprintf/printf, and epoch
           offsets.

       v1.41, 19 May 1999
           Lots more little changes to formatting and content.

           Added a bunch of `$^O' and related values for various
           platforms; fixed mail and web addresses, and added and
           changed miscellaneous notes.  (Peter Prymmer)

       v1.40, 11 April 1999
           Miscellaneous changes.

       v1.39, 11 February 1999
           Changes from Jarkko and EMX URL fixes Michael Schwern.
           Additional note about newlines added.

       v1.38, 31 December 1998
           More changes from Jarkko.

       v1.37, 19 December 1998
           More minor changes.  Merge two separate version 1.35
           documents.

       v1.36, 9 September 1998
           Updated for Stratus VOS.  Also known as version 1.35.

       v1.35, 13 August 1998
           Integrate more minor changes, plus addition of new
           sections under the section on "ISSUES": the section on
           "Numbers endianness and Width", the section on "Char­
           acter sets and character encoding", the section on
           "Internationalisation".

       v1.33, 06 August 1998
           Integrate more minor changes.

       v1.32, 05 August 1998
           Integrate more minor changes.

       v1.30, 03 August 1998
           Major update for RISC OS, other minor changes.

       v1.23, 10 July 1998
           First public release with perl5.005.


Supported Platforms

       As of early March 2000 (the Perl release 5.6.0), the fol­
       lowing platforms are able to build Perl from the standard
       source code distribution available at


               AIX
               DOS DJGPP       1)
               FreeBSD
               HP-UX
               IRIX
               Linux
               LynxOS
               MachTen
               MPE/iX
               NetBSD
               OpenBSD
               OS/2
               QNX
               Rhapsody/Darwin 2)
               SCO SV
               SINIX
               Solaris
               SVR4
               Tru64 UNIX      3)
               UNICOS
               UNICOS/mk
               Unixware
               VMS
               VOS
               Windows 3.1     1)
               Windows 95      1) 4)
               Windows 98      1) 4)
               Windows NT      1) 4)

               1) in DOS mode either the DOS or OS/2 ports can be used
               2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X
               3) formerly known as Digital UNIX and before that DEC OSF/1
               4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++

       The following platforms worked for the previous major
       release (5.005_03 being the latest maintenance release of
       that, as of early March 2000), but be did not manage to
       test these in time for the 5.6.0 release of Perl.  There
       is a very good chance that these will work just fine with
       5.6.0.

               BeOS
               BSD/OS
               DG/UX
               DYNIX/ptx
               DomainOS
               Hurd
               NextSTEP
               OpenSTEP
               PowerMAX
               SCO ODT/OSR
               SunOS
               Ultrix

       The following platform worked for the previous major
       release (5.005_03 being the latest maintenance release of
       that, as of early March 2000).  However, standardization
       on UTF-8 as the internal string representation in 5.6.0
       has introduced incompatibilities in this EBCDIC platform.
       Support for this platform may be enabled in a future
       release:

               OS390   1)

               1) Previously known as MVS, or OpenEdition MVS.

       Strongly related to the OS390 platform by also being
       EBCDIC-based mainframe platforms are the following plat­
       forms:

               BS2000
               VM/ESA

       These are also not expected to work under 5.6.0 for the
       same reasons as OS390.  Contact the mailing list perl-
       mvs@perl.org for more details.

       MacOS (Classic, pre-X) is almost 5.6.0-ready; building
       from the source does work with 5.6.0, but additional MacOS
       specific source code is needed for a complete port.  Con­
       tact the mailing list macperl-porters@macperl.org for more
       information.

       The following platforms have been known to build Perl from
       source in the past, but we haven't been able to verify
       their status for the current release, either because the
       hardware/software platforms are rare or because we don't
       have an active champion on these platforms--or both:

               AmigaOS
               ConvexOS
               CX/UX
               DC/OSx
               DDE SMES
               DOS EMX
               Dynix
               EP/IX
               ESIX
               FPS
               GENIX
               Greenhills
               ISC
               MachTen 68k
               MiNT
               MPC
               NEWS-OS
               Opus
               Plan 9
               PowerUX
               RISC/os
               Stellar
               SVR2
               TI1500
               TitanOS
               Unisys Dynix
               Unixware

       Support for the following platform is planned for a future
       Perl release:

               Netware

       The following platforms have their own source code distri­
       butions and binaries available via
       http://www.perl.com/CPAN/ports/index.html:

                                       Perl release

               AS/400                  5.003
               Netware                 5.003_07
               Tandem Guardian         5.004

       The following platforms have only binaries available via
       http://www.perl.com/CPAN/ports/index.html :

                                       Perl release

               Acorn RISCOS            5.005_02
               AOS                     5.002
               LynxOS                  5.004_02

       Although we do suggest that you always build your own Perl

       for security, in case you are in a hurry you can check
       http://www.perl.com/CPAN/ports/index.html for binary dis­
       tributions.


SEE ALSO

       the perlamiga manpage, the perlcygwin manpage, the perldos
       manpage, the perlhpux manpage, the perlos2 manpage, the
       perlos390 manpage, the perlwin32 manpage, the perlvms man­
       page, and the Win32 manpage.


AUTHORS / CONTRIBUTORS

       Abigail <abigail@fnx.com>, Charles Bailey <bailey@new­
       man.upenn.edu>, Graham Barr <gbarr@pobox.com>, Tom Chris­
       tiansen <tchrist@perl.com>, Nicholas Clark
       <Nicholas.Clark@liverpool.ac.uk>, Thomas Dorner
       <Thomas.Dorner@start.de>, Andy Dougherty <doughera@laf­
       col.lafayette.edu>, Dominic Dunlop <domo@vo.lu>, Neale
       Ferguson <neale@mailbox.tabnsw.com.au>, David J. Fiander
       <davidf@mks.com>, Paul Green <Paul_Green@stratus.com>,
       M.J.T. Guy <mjtg@cus.cam.ac.uk>, Jarkko Hietaniemi
       <jhi@iki.fi<gt>, Luther Huffman <lutherh@stratcom.com>,
       Nick Ing-Simmons <nick@ni-s.u-net.com>, Andreas J. Koenig
       <koenig@kulturbox.de>, Markus Laker <mlaker@contax.co.uk>,
       Andrew M. Langmead <aml@world.std.com>, Larry Moore
       <ljmoore@freespace.net>, Paul Moore <Paul.Moore@uk.origin-
       it.com>, Chris Nandor <pudge@pobox.com>, Matthias Neer­
       acher <neeri@iis.ee.ethz.ch>, Gary Ng <71564.1743@Com­
       puServe.COM>, Tom Phoenix <rootbeer@teleport.com>, Andre
       Pirard <A.Pirard@ulg.ac.be>, Peter Prymmer
       <pvhp@forte.com>, Hugo van der Sanden
       <hv@crypt0.demon.co.uk>, Gurusamy Sarathy <gsar@actives­
       tate.com>, Paul J. Schinder <schinder@pobox.com>, Michael
       G Schwern <schwern@pobox.com>, Dan Sugalski <sugal­
       skd@ous.edu>, Nathan Torkington <gnat@frii.com>.

       This document is maintained by Chris Nandor
       <pudge@pobox.com>.


VERSION

       Version 1.47, last modified 22 March 2000


Man(1) output converted with man2html