[ Index ]

PHP Cross Reference of Unnamed Project




/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/pod/ -> perlport.pod (source)

   1  =head1 NAME
   3  perlport - Writing portable Perl
   5  =head1 DESCRIPTION
   7  Perl runs on numerous operating systems.  While most of them share
   8  much in common, they also have their own unique features.
  10  This document is meant to help you to find out what constitutes portable
  11  Perl code.  That way once you make a decision to write portably,
  12  you know where the lines are drawn, and you can stay within them.
  14  There is a tradeoff between taking full advantage of one particular
  15  type of computer and taking advantage of a full range of them.
  16  Naturally, as you broaden your range and become more diverse, the
  17  common factors drop, and you are left with an increasingly smaller
  18  area of common ground in which you can operate to accomplish a
  19  particular task.  Thus, when you begin attacking a problem, it is
  20  important to consider under which part of the tradeoff curve you
  21  want to operate.  Specifically, you must decide whether it is
  22  important that the task that you are coding have the full generality
  23  of being portable, or whether to just get the job done right now.
  24  This is the hardest choice to be made.  The rest is easy, because
  25  Perl provides many choices, whichever way you want to approach your
  26  problem.
  28  Looking at it another way, writing portable code is usually about
  29  willfully limiting your available choices.  Naturally, it takes
  30  discipline and sacrifice to do that.  The product of portability
  31  and convenience may be a constant.  You have been warned.
  33  Be aware of two important points:
  35  =over 4
  37  =item Not all Perl programs have to be portable
  39  There is no reason you should not use Perl as a language to glue Unix
  40  tools together, or to prototype a Macintosh application, or to manage the
  41  Windows registry.  If it makes no sense to aim for portability for one
  42  reason or another in a given program, then don't bother.
  44  =item Nearly all of Perl already I<is> portable
  46  Don't be fooled into thinking that it is hard to create portable Perl
  47  code.  It isn't.  Perl tries its level-best to bridge the gaps between
  48  what's available on different platforms, and all the means available to
  49  use those features.  Thus almost all Perl code runs on any machine
  50  without modification.  But there are some significant issues in
  51  writing portable code, and this document is entirely about those issues.
  53  =back
  55  Here's the general rule: When you approach a task commonly done
  56  using a whole range of platforms, think about writing portable
  57  code.  That way, you don't sacrifice much by way of the implementation
  58  choices you can avail yourself of, and at the same time you can give
  59  your users lots of platform choices.  On the other hand, when you have to
  60  take advantage of some unique feature of a particular platform, as is
  61  often the case with systems programming (whether for Unix, Windows,
  62  S<Mac OS>, VMS, etc.), consider writing platform-specific code.
  64  When the code will run on only two or three operating systems, you
  65  may need to consider only the differences of those particular systems.
  66  The important thing is to decide where the code will run and to be
  67  deliberate in your decision.
  69  The material below is separated into three main sections: main issues of
  70  portability (L<"ISSUES">), platform-specific issues (L<"PLATFORMS">), and
  71  built-in perl functions that behave differently on various ports
  74  This information should not be considered complete; it includes possibly
  75  transient information about idiosyncrasies of some of the ports, almost
  76  all of which are in a state of constant evolution.  Thus, this material
  77  should be considered a perpetual work in progress
  78  (C<< <IMG SRC="yellow_sign.gif" ALT="Under Construction"> >>).
  80  =head1 ISSUES
  82  =head2 Newlines
  84  In most operating systems, lines in files are terminated by newlines.
  85  Just what is used as a newline may vary from OS to OS.  Unix
  86  traditionally uses C<\012>, one type of DOSish I/O uses C<\015\012>,
  87  and S<Mac OS> uses C<\015>.
  89  Perl uses C<\n> to represent the "logical" newline, where what is
  90  logical may depend on the platform in use.  In MacPerl, C<\n> always
  91  means C<\015>.  In DOSish perls, C<\n> usually means C<\012>, but
  92  when accessing a file in "text" mode, STDIO translates it to (or
  93  from) C<\015\012>, depending on whether you're reading or writing.
  94  Unix does the same thing on ttys in canonical mode.  C<\015\012>
  95  is commonly referred to as CRLF.
  97  To trim trailing newlines from text lines use chomp().  With default 
  98  settings that function looks for a trailing C<\n> character and thus 
  99  trims in a portable way.
 101  When dealing with binary files (or text files in binary mode) be sure
 102  to explicitly set $/ to the appropriate value for your file format
 103  before using chomp().
 105  Because of the "text" mode translation, DOSish perls have limitations
 106  in using C<seek> and C<tell> on a file accessed in "text" mode.
 107  Stick to C<seek>-ing to locations you got from C<tell> (and no
 108  others), and you are usually free to use C<seek> and C<tell> even
 109  in "text" mode.  Using C<seek> or C<tell> or other file operations
 110  may be non-portable.  If you use C<binmode> on a file, however, you
 111  can usually C<seek> and C<tell> with arbitrary values in safety.
 113  A common misconception in socket programming is that C<\n> eq C<\012>
 114  everywhere.  When using protocols such as common Internet protocols,
 115  C<\012> and C<\015> are called for specifically, and the values of
 116  the logical C<\n> and C<\r> (carriage return) are not reliable.
 118      print SOCKET "Hi there, client!\r\n";      # WRONG
 119      print SOCKET "Hi there, client!\015\012";  # RIGHT
 121  However, using C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious
 122  and unsightly, as well as confusing to those maintaining the code.  As
 123  such, the Socket module supplies the Right Thing for those who want it.
 125      use Socket qw(:DEFAULT :crlf);
 126      print SOCKET "Hi there, client!$CRLF"      # RIGHT
 128  When reading from a socket, remember that the default input record
 129  separator C<$/> is C<\n>, but robust socket code will recognize as
 130  either C<\012> or C<\015\012> as end of line:
 132      while (<SOCKET>) {
 133          # ...
 134      }
 136  Because both CRLF and LF end in LF, the input record separator can
 137  be set to LF and any CR stripped later.  Better to write:
 139      use Socket qw(:DEFAULT :crlf);
 140      local($/) = LF;      # not needed if $/ is already \012
 142      while (<SOCKET>) {
 143          s/$CR?$LF/\n/;   # not sure if socket uses LF or CRLF, OK
 144      #   s/\015?\012/\n/; # same thing
 145      }
 147  This example is preferred over the previous one--even for Unix
 148  platforms--because now any C<\015>'s (C<\cM>'s) are stripped out
 149  (and there was much rejoicing).
 151  Similarly, functions that return text data--such as a function that
 152  fetches a web page--should sometimes translate newlines before
 153  returning the data, if they've not yet been translated to the local
 154  newline representation.  A single line of code will often suffice:
 156      $data =~ s/\015?\012/\n/g;
 157      return $data;
 159  Some of this may be confusing.  Here's a handy reference to the ASCII CR
 160  and LF characters.  You can print it out and stick it in your wallet.
 162      LF  eq  \012  eq  \x0A  eq  \cJ  eq  chr(10)  eq  ASCII 10
 163      CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  ASCII 13
 165               | Unix | DOS  | Mac  |
 166          ---------------------------
 167          \n   |  LF  |  LF  |  CR  |
 168          \r   |  CR  |  CR  |  LF  |
 169          \n * |  LF  | CRLF |  CR  |
 170          \r * |  CR  |  CR  |  LF  |
 171          ---------------------------
 172          * text-mode STDIO
 174  The Unix column assumes that you are not accessing a serial line
 175  (like a tty) in canonical mode.  If you are, then CR on input becomes
 176  "\n", and "\n" on output becomes CRLF.
 178  These are just the most common definitions of C<\n> and C<\r> in Perl.
 179  There may well be others.  For example, on an EBCDIC implementation
 180  such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based)
 181  the above material is similar to "Unix" but the code numbers change:
 183      LF  eq  \025  eq  \x15  eq  \cU  eq  chr(21)  eq  CP-1047 21
 184      LF  eq  \045  eq  \x25  eq           chr(37)  eq  CP-0037 37
 185      CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-1047 13
 186      CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-0037 13
 188               | z/OS | OS/400 |
 189          ----------------------
 190          \n   |  LF  |  LF    |
 191          \r   |  CR  |  CR    |
 192          \n * |  LF  |  LF    |
 193          \r * |  CR  |  CR    |
 194          ----------------------
 195          * text-mode STDIO
 197  =head2 Numbers endianness and Width
 199  Different CPUs store integers and floating point numbers in different
 200  orders (called I<endianness>) and widths (32-bit and 64-bit being the
 201  most common today).  This affects your programs when they attempt to transfer
 202  numbers in binary format from one CPU architecture to another,
 203  usually either "live" via network connection, or by storing the
 204  numbers to secondary storage such as a disk file or tape.
 206  Conflicting storage orders make utter mess out of the numbers.  If a
 207  little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
 208  decimal), a big-endian host (Motorola, Sparc, PA) reads it as
 209  0x78563412 (2018915346 in decimal).  Alpha and MIPS can be either:
 210  Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
 211  them in big-endian mode.  To avoid this problem in network (socket)
 212  connections use the C<pack> and C<unpack> formats C<n> and C<N>, the
 213  "network" orders.  These are guaranteed to be portable.
 215  As of perl 5.9.2, you can also use the C<E<gt>> and C<E<lt>> modifiers
 216  to force big- or little-endian byte-order.  This is useful if you want
 217  to store signed integers or 64-bit integers, for example.
 219  You can explore the endianness of your platform by unpacking a
 220  data structure packed in native format such as:
 222      print unpack("h*", pack("s2", 1, 2)), "\n";
 223      # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
 224      # '00100020' on e.g. Motorola 68040
 226  If you need to distinguish between endian architectures you could use
 227  either of the variables set like so:
 229      $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
 230      $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
 232  Differing widths can cause truncation even between platforms of equal
 233  endianness.  The platform of shorter width loses the upper parts of the
 234  number.  There is no good solution for this problem except to avoid
 235  transferring or storing raw binary numbers.
 237  One can circumnavigate both these problems in two ways.  Either
 238  transfer and store numbers always in text format, instead of raw
 239  binary, or else consider using modules like Data::Dumper (included in
 240  the standard distribution as of Perl 5.005) and Storable (included as
 241  of perl 5.8).  Keeping all data as text significantly simplifies matters.
 243  The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's
 244  how far EBCDIC, or more precisely UTF-EBCDIC will go.
 246  =head2 Files and Filesystems
 248  Most platforms these days structure files in a hierarchical fashion.
 249  So, it is reasonably safe to assume that all platforms support the
 250  notion of a "path" to uniquely identify a file on the system.  How
 251  that path is really written, though, differs considerably.
 253  Although similar, file path specifications differ between Unix,
 254  Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others.
 255  Unix, for example, is one of the few OSes that has the elegant idea
 256  of a single root directory.
 258  DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with C</>
 259  as path separator, or in their own idiosyncratic ways (such as having
 260  several root directories and various "unrooted" device files such NIL:
 261  and LPT:).
 263  S<Mac OS> uses C<:> as a path separator instead of C</>.
 265  The filesystem may support neither hard links (C<link>) nor
 266  symbolic links (C<symlink>, C<readlink>, C<lstat>).
 268  The filesystem may support neither access timestamp nor change
 269  timestamp (meaning that about the only portable timestamp is the
 270  modification timestamp), or one second granularity of any timestamps
 271  (e.g. the FAT filesystem limits the time granularity to two seconds).
 273  The "inode change timestamp" (the C<-C> filetest) may really be the
 274  "creation timestamp" (which it is not in UNIX).
 276  VOS perl can emulate Unix filenames with C</> as path separator.  The
 277  native pathname characters greater-than, less-than, number-sign, and
 278  percent-sign are always accepted.
 280  S<RISC OS> perl can emulate Unix filenames with C</> as path
 281  separator, or go native and use C<.> for path separator and C<:> to
 282  signal filesystems and disk names.
 284  Don't assume UNIX filesystem access semantics: that read, write,
 285  and execute are all the permissions there are, and even if they exist,
 286  that their semantics (for example what do r, w, and x mean on
 287  a directory) are the UNIX ones.  The various UNIX/POSIX compatibility
 288  layers usually try to make interfaces like chmod() work, but sometimes
 289  there simply is no good mapping.
 291  If all this is intimidating, have no (well, maybe only a little)
 292  fear.  There are modules that can help.  The File::Spec modules
 293  provide methods to do the Right Thing on whatever platform happens
 294  to be running the program.
 296      use File::Spec::Functions;
 297      chdir(updir());        # go up one directory
 298      $file = catfile(curdir(), 'temp', 'file.txt');
 299      # on Unix and Win32, './temp/file.txt'
 300      # on Mac OS, ':temp:file.txt'
 301      # on VMS, '[.temp]file.txt'
 303  File::Spec is available in the standard distribution as of version
 304  5.004_05.  File::Spec::Functions is only in File::Spec 0.7 and later,
 305  and some versions of perl come with version 0.6.  If File::Spec
 306  is not updated to 0.7 or later, you must use the object-oriented
 307  interface from File::Spec (or upgrade File::Spec).
 309  In general, production code should not have file paths hardcoded.
 310  Making them user-supplied or read from a configuration file is
 311  better, keeping in mind that file path syntax varies on different
 312  machines.
 314  This is especially noticeable in scripts like Makefiles and test suites,
 315  which often assume C</> as a path separator for subdirectories.
 317  Also of use is File::Basename from the standard distribution, which
 318  splits a pathname into pieces (base filename, full path to directory,
 319  and file suffix).
 321  Even when on a single platform (if you can call Unix a single platform),
 322  remember not to count on the existence or the contents of particular
 323  system-specific files or directories, like F</etc/passwd>,
 324  F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>.  For
 325  example, F</etc/passwd> may exist but not contain the encrypted
 326  passwords, because the system is using some form of enhanced security.
 327  Or it may not contain all the accounts, because the system is using NIS. 
 328  If code does need to rely on such a file, include a description of the
 329  file and its format in the code's documentation, then make it easy for
 330  the user to override the default location of the file.
 332  Don't assume a text file will end with a newline.  They should,
 333  but people forget.
 335  Do not have two files or directories of the same name with different
 336  case, like F<test.pl> and F<Test.pl>, as many platforms have
 337  case-insensitive (or at least case-forgiving) filenames.  Also, try
 338  not to have non-word characters (except for C<.>) in the names, and
 339  keep them to the 8.3 convention, for maximum portability, onerous a
 340  burden though this may appear.
 342  Likewise, when using the AutoSplit module, try to keep your functions to
 343  8.3 naming and case-insensitive conventions; or, at the least,
 344  make it so the resulting files have a unique (case-insensitively)
 345  first 8 characters.
 347  Whitespace in filenames is tolerated on most systems, but not all,
 348  and even on systems where it might be tolerated, some utilities
 349  might become confused by such whitespace.
 351  Many systems (DOS, VMS ODS-2) cannot have more than one C<.> in their
 352  filenames.
 354  Don't assume C<< > >> won't be the first character of a filename.
 355  Always use C<< < >> explicitly to open a file for reading, or even
 356  better, use the three-arg version of open, unless you want the user to
 357  be able to specify a pipe open.
 359      open(FILE, '<', $existing_file) or die $!;
 361  If filenames might use strange characters, it is safest to open it
 362  with C<sysopen> instead of C<open>.  C<open> is magic and can
 363  translate characters like C<< > >>, C<< < >>, and C<|>, which may
 364  be the wrong thing to do.  (Sometimes, though, it's the right thing.)
 365  Three-arg open can also help protect against this translation in cases
 366  where it is undesirable.
 368  Don't use C<:> as a part of a filename since many systems use that for
 369  their own semantics (Mac OS Classic for separating pathname components,
 370  many networking schemes and utilities for separating the nodename and
 371  the pathname, and so on).  For the same reasons, avoid C<@>, C<;> and
 372  C<|>.
 374  Don't assume that in pathnames you can collapse two leading slashes
 375  C<//> into one: some networking and clustering filesystems have special
 376  semantics for that.  Let the operating system to sort it out.
 378  The I<portable filename characters> as defined by ANSI C are
 380   a b c d e f g h i j k l m n o p q r t u v w x y z
 381   A B C D E F G H I J K L M N O P Q R T U V W X Y Z
 382   0 1 2 3 4 5 6 7 8 9
 383   . _ -
 385  and the "-" shouldn't be the first character.  If you want to be
 386  hypercorrect, stay case-insensitive and within the 8.3 naming
 387  convention (all the files and directories have to be unique within one
 388  directory if their names are lowercased and truncated to eight
 389  characters before the C<.>, if any, and to three characters after the
 390  C<.>, if any).  (And do not use C<.>s in directory names.)
 392  =head2 System Interaction
 394  Not all platforms provide a command line.  These are usually platforms
 395  that rely primarily on a Graphical User Interface (GUI) for user
 396  interaction.  A program requiring a command line interface might
 397  not work everywhere.  This is probably for the user of the program
 398  to deal with, so don't stay up late worrying about it.
 400  Some platforms can't delete or rename files held open by the system,
 401  this limitation may also apply to changing filesystem metainformation
 402  like file permissions or owners.  Remember to C<close> files when you
 403  are done with them.  Don't C<unlink> or C<rename> an open file.  Don't
 404  C<tie> or C<open> a file already tied or opened; C<untie> or C<close>
 405  it first.
 407  Don't open the same file more than once at a time for writing, as some
 408  operating systems put mandatory locks on such files.
 410  Don't assume that write/modify permission on a directory gives the
 411  right to add or delete files/directories in that directory.  That is
 412  filesystem specific: in some filesystems you need write/modify
 413  permission also (or even just) in the file/directory itself.  In some
 414  filesystems (AFS, DFS) the permission to add/delete directory entries
 415  is a completely separate permission.
 417  Don't assume that a single C<unlink> completely gets rid of the file:
 418  some filesystems (most notably the ones in VMS) have versioned
 419  filesystems, and unlink() removes only the most recent one (it doesn't
 420  remove all the versions because by default the native tools on those
 421  platforms remove just the most recent version, too).  The portable
 422  idiom to remove all the versions of a file is
 424      1 while unlink "file";
 426  This will terminate if the file is undeleteable for some reason
 427  (protected, not there, and so on).
 429  Don't count on a specific environment variable existing in C<%ENV>.
 430  Don't count on C<%ENV> entries being case-sensitive, or even
 431  case-preserving.  Don't try to clear %ENV by saying C<%ENV = ();>, or,
 432  if you really have to, make it conditional on C<$^O ne 'VMS'> since in
 433  VMS the C<%ENV> table is much more than a per-process key-value string
 434  table.
 436  On VMS, some entries in the %ENV hash are dynamically created when
 437  their key is used on a read if they did not previously exist.  The
 438  values for C<$ENV{HOME}>, C<$ENV{TERM}>, C<$ENV{HOME}>, and C<$ENV{USER}>,
 439  are known to be dynamically generated.  The specific names that are
 440  dynamically generated may vary with the version of the C library on VMS,
 441  and more may exist than is documented.
 443  On VMS by default, changes to the %ENV hash are persistent after the process
 444  exits.  This can cause unintended issues.
 446  Don't count on signals or C<%SIG> for anything.
 448  Don't count on filename globbing.  Use C<opendir>, C<readdir>, and
 449  C<closedir> instead.
 451  Don't count on per-program environment variables, or per-program current
 452  directories.
 454  Don't count on specific values of C<$!>, neither numeric nor
 455  especially the strings values-- users may switch their locales causing
 456  error messages to be translated into their languages.  If you can
 457  trust a POSIXish environment, you can portably use the symbols defined
 458  by the Errno module, like ENOENT.  And don't trust on the values of C<$!>
 459  at all except immediately after a failed system call.
 461  =head2 Command names versus file pathnames
 463  Don't assume that the name used to invoke a command or program with
 464  C<system> or C<exec> can also be used to test for the existence of the
 465  file that holds the executable code for that command or program.
 466  First, many systems have "internal" commands that are built-in to the
 467  shell or OS and while these commands can be invoked, there is no
 468  corresponding file.  Second, some operating systems (e.g., Cygwin,
 469  DJGPP, OS/2, and VOS) have required suffixes for executable files;
 470  these suffixes are generally permitted on the command name but are not
 471  required.  Thus, a command like "perl" might exist in a file named
 472  "perl", "perl.exe", or "perl.pm", depending on the operating system.
 473  The variable "_exe" in the Config module holds the executable suffix,
 474  if any.  Third, the VMS port carefully sets up $^X and
 475  $Config{perlpath} so that no further processing is required.  This is
 476  just as well, because the matching regular expression used below would
 477  then have to deal with a possible trailing version number in the VMS
 478  file name.
 480  To convert $^X to a file pathname, taking account of the requirements
 481  of the various operating system possibilities, say:
 483    use Config;
 484    $thisperl = $^X;
 485    if ($^O ne 'VMS')
 486       {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
 488  To convert $Config{perlpath} to a file pathname, say:
 490    use Config;
 491    $thisperl = $Config{perlpath};
 492    if ($^O ne 'VMS')
 493       {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
 495  =head2 Networking
 497  Don't assume that you can reach the public Internet.
 499  Don't assume that there is only one way to get through firewalls
 500  to the public Internet.
 502  Don't assume that you can reach outside world through any other port
 503  than 80, or some web proxy.  ftp is blocked by many firewalls.
 505  Don't assume that you can send email by connecting to the local SMTP port.
 507  Don't assume that you can reach yourself or any node by the name
 508  'localhost'.  The same goes for ''.  You will have to try both.
 510  Don't assume that the host has only one network card, or that it
 511  can't bind to many virtual IP addresses.
 513  Don't assume a particular network device name.
 515  Don't assume a particular set of ioctl()s will work.
 517  Don't assume that you can ping hosts and get replies.
 519  Don't assume that any particular port (service) will respond.
 521  Don't assume that Sys::Hostname (or any other API or command)
 522  returns either a fully qualified hostname or a non-qualified hostname:
 523  it all depends on how the system had been configured.  Also remember
 524  things like DHCP and NAT-- the hostname you get back might not be very
 525  useful.
 527  All the above "don't":s may look daunting, and they are -- but the key
 528  is to degrade gracefully if one cannot reach the particular network
 529  service one wants.  Croaking or hanging do not look very professional.
 531  =head2 Interprocess Communication (IPC)
 533  In general, don't directly access the system in code meant to be
 534  portable.  That means, no C<system>, C<exec>, C<fork>, C<pipe>,
 535  C<``>, C<qx//>, C<open> with a C<|>, nor any of the other things
 536  that makes being a perl hacker worth being.
 538  Commands that launch external processes are generally supported on
 539  most platforms (though many of them do not support any type of
 540  forking).  The problem with using them arises from what you invoke
 541  them on.  External tools are often named differently on different
 542  platforms, may not be available in the same location, might accept
 543  different arguments, can behave differently, and often present their
 544  results in a platform-dependent way.  Thus, you should seldom depend
 545  on them to produce consistent results. (Then again, if you're calling 
 546  I<netstat -a>, you probably don't expect it to run on both Unix and CP/M.)
 548  One especially common bit of Perl code is opening a pipe to B<sendmail>:
 550      open(MAIL, '|/usr/lib/sendmail -t') 
 551      or die "cannot fork sendmail: $!";
 553  This is fine for systems programming when sendmail is known to be
 554  available.  But it is not fine for many non-Unix systems, and even
 555  some Unix systems that may not have sendmail installed.  If a portable
 556  solution is needed, see the various distributions on CPAN that deal
 557  with it.  Mail::Mailer and Mail::Send in the MailTools distribution are
 558  commonly used, and provide several mailing methods, including mail,
 559  sendmail, and direct SMTP (via Net::SMTP) if a mail transfer agent is
 560  not available.  Mail::Sendmail is a standalone module that provides
 561  simple, platform-independent mailing.
 563  The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
 564  even on all Unix platforms.
 566  Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
 567  bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
 568  both forms just pack the four bytes into network order.  That this
 569  would be equal to the C language C<in_addr> struct (which is what the
 570  socket code internally uses) is not guaranteed.  To be portable use
 571  the routines of the Socket extension, such as C<inet_aton()>,
 572  C<inet_ntoa()>, and C<sockaddr_in()>.
 574  The rule of thumb for portable code is: Do it all in portable Perl, or
 575  use a module (that may internally implement it with platform-specific
 576  code, but expose a common interface).
 578  =head2 External Subroutines (XS)
 580  XS code can usually be made to work with any platform, but dependent
 581  libraries, header files, etc., might not be readily available or
 582  portable, or the XS code itself might be platform-specific, just as Perl
 583  code might be.  If the libraries and headers are portable, then it is
 584  normally reasonable to make sure the XS code is portable, too.
 586  A different type of portability issue arises when writing XS code:
 587  availability of a C compiler on the end-user's system.  C brings
 588  with it its own portability issues, and writing XS code will expose
 589  you to some of those.  Writing purely in Perl is an easier way to
 590  achieve portability.
 592  =head2 Standard Modules
 594  In general, the standard modules work across platforms.  Notable
 595  exceptions are the CPAN module (which currently makes connections to external
 596  programs that may not be available), platform-specific modules (like
 597  ExtUtils::MM_VMS), and DBM modules.
 599  There is no one DBM module available on all platforms.
 600  SDBM_File and the others are generally available on all Unix and DOSish
 601  ports, but not in MacPerl, where only NBDM_File and DB_File are
 602  available.
 604  The good news is that at least some DBM module should be available, and
 605  AnyDBM_File will use whichever module it can find.  Of course, then
 606  the code needs to be fairly strict, dropping to the greatest common
 607  factor (e.g., not exceeding 1K for each record), so that it will
 608  work with any DBM module.  See L<AnyDBM_File> for more details.
 610  =head2 Time and Date
 612  The system's notion of time of day and calendar date is controlled in
 613  widely different ways.  Don't assume the timezone is stored in C<$ENV{TZ}>,
 614  and even if it is, don't assume that you can control the timezone through
 615  that variable.  Don't assume anything about the three-letter timezone
 616  abbreviations (for example that MST would be the Mountain Standard Time,
 617  it's been known to stand for Moscow Standard Time).  If you need to
 618  use timezones, express them in some unambiguous format like the
 619  exact number of minutes offset from UTC, or the POSIX timezone
 620  format.
 622  Don't assume that the epoch starts at 00:00:00, January 1, 1970,
 623  because that is OS- and implementation-specific.  It is better to
 624  store a date in an unambiguous representation.  The ISO 8601 standard
 625  defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH-MM-SS
 626  (that's a literal "T" separating the date from the time).
 627  Please do use the ISO 8601 instead of making us to guess what
 628  date 02/03/04 might be.  ISO 8601 even sorts nicely as-is.
 629  A text representation (like "1987-12-18") can be easily converted
 630  into an OS-specific value using a module like Date::Parse.
 631  An array of values, such as those returned by C<localtime>, can be
 632  converted to an OS-specific representation using Time::Local.
 634  When calculating specific times, such as for tests in time or date modules,
 635  it may be appropriate to calculate an offset for the epoch.
 637      require Time::Local;
 638      $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);
 640  The value for C<$offset> in Unix will be C<0>, but in Mac OS will be
 641  some large number.  C<$offset> can then be added to a Unix time value
 642  to get what should be the proper value on any system.
 644  On Windows (at least), you shouldn't pass a negative value to C<gmtime> or
 645  C<localtime>.
 647  =head2 Character sets and character encoding
 649  Assume very little about character sets.
 651  Assume nothing about numerical values (C<ord>, C<chr>) of characters.
 652  Do not use explicit code point ranges (like \xHH-\xHH); use for
 653  example symbolic character classes like C<[:print:]>.
 655  Do not assume that the alphabetic characters are encoded contiguously
 656  (in the numeric sense).  There may be gaps.
 658  Do not assume anything about the ordering of the characters.
 659  The lowercase letters may come before or after the uppercase letters;
 660  the lowercase and uppercase may be interlaced so that both "a" and "A"
 661  come before "b"; the accented and other international characters may
 662  be interlaced so that E<auml> comes before "b".
 664  =head2 Internationalisation
 666  If you may assume POSIX (a rather large assumption), you may read
 667  more about the POSIX locale system from L<perllocale>.  The locale
 668  system at least attempts to make things a little bit more portable,
 669  or at least more convenient and native-friendly for non-English
 670  users.  The system affects character sets and encoding, and date
 671  and time formatting--amongst other things.
 673  If you really want to be international, you should consider Unicode.
 674  See L<perluniintro> and L<perlunicode> for more information.
 676  If you want to use non-ASCII bytes (outside the bytes 0x00..0x7f) in
 677  the "source code" of your code, to be portable you have to be explicit
 678  about what bytes they are.  Someone might for example be using your
 679  code under a UTF-8 locale, in which case random native bytes might be
 680  illegal ("Malformed UTF-8 ...")  This means that for example embedding
 681  ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
 682  later.  If the bytes are native 8-bit bytes, you can use the C<bytes>
 683  pragma.  If the bytes are in a string (regular expression being a
 684  curious string), you can often also use the C<\xHH> notation instead
 685  of embedding the bytes as-is.  (If you want to write your code in UTF-8,
 686  you can use the C<utf8>.) The C<bytes> and C<utf8> pragmata are
 687  available since Perl 5.6.0.
 689  =head2 System Resources
 691  If your code is destined for systems with severely constrained (or
 692  missing!) virtual memory systems then you want to be I<especially> mindful
 693  of avoiding wasteful constructs such as:
 695      # NOTE: this is no longer "bad" in perl5.005
 696      for (0..10000000) {}                       # bad
 697      for (my $x = 0; $x <= 10000000; ++$x) {}   # good
 699      @lines = <VERY_LARGE_FILE>;                # bad
 701      while (<FILE>) {$file .= $_}               # sometimes bad
 702      $file = join('', <FILE>);                  # better
 704  The last two constructs may appear unintuitive to most people.  The
 705  first repeatedly grows a string, whereas the second allocates a
 706  large chunk of memory in one go.  On some systems, the second is
 707  more efficient that the first.
 709  =head2 Security
 711  Most multi-user platforms provide basic levels of security, usually
 712  implemented at the filesystem level.  Some, however, do
 713  not-- unfortunately.  Thus the notion of user id, or "home" directory,
 714  or even the state of being logged-in, may be unrecognizable on many
 715  platforms.  If you write programs that are security-conscious, it
 716  is usually best to know what type of system you will be running
 717  under so that you can write code explicitly for that platform (or
 718  class of platforms).
 720  Don't assume the UNIX filesystem access semantics: the operating
 721  system or the filesystem may be using some ACL systems, which are
 722  richer languages than the usual rwx.  Even if the rwx exist,
 723  their semantics might be different.
 725  (From security viewpoint testing for permissions before attempting to
 726  do something is silly anyway: if one tries this, there is potential
 727  for race conditions-- someone or something might change the
 728  permissions between the permissions check and the actual operation.
 729  Just try the operation.)
 731  Don't assume the UNIX user and group semantics: especially, don't
 732  expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
 733  for switching identities (or memberships).
 735  Don't assume set-uid and set-gid semantics. (And even if you do,
 736  think twice: set-uid and set-gid are a known can of security worms.)
 738  =head2 Style
 740  For those times when it is necessary to have platform-specific code,
 741  consider keeping the platform-specific code in one place, making porting
 742  to other platforms easier.  Use the Config module and the special
 743  variable C<$^O> to differentiate platforms, as described in
 744  L<"PLATFORMS">.
 746  Be careful in the tests you supply with your module or programs.
 747  Module code may be fully portable, but its tests might not be.  This
 748  often happens when tests spawn off other processes or call external
 749  programs to aid in the testing, or when (as noted above) the tests
 750  assume certain things about the filesystem and paths.  Be careful not
 751  to depend on a specific output style for errors, such as when checking
 752  C<$!> after a failed system call.  Using C<$!> for anything else than
 753  displaying it as output is doubtful (though see the Errno module for
 754  testing reasonably portably for error value). Some platforms expect
 755  a certain output format, and Perl on those platforms may have been
 756  adjusted accordingly.  Most specifically, don't anchor a regex when
 757  testing an error value.
 759  =head1 CPAN Testers
 761  Modules uploaded to CPAN are tested by a variety of volunteers on
 762  different platforms.  These CPAN testers are notified by mail of each
 763  new upload, and reply to the list with PASS, FAIL, NA (not applicable to
 764  this platform), or UNKNOWN (unknown), along with any relevant notations.
 766  The purpose of the testing is twofold: one, to help developers fix any
 767  problems in their code that crop up because of lack of testing on other
 768  platforms; two, to provide users with information about whether
 769  a given module works on a given platform.
 771  Also see: 
 773  =over 4
 775  =item *
 777  Mailing list: cpan-testers@perl.org
 779  =item *
 781  Testing results: http://testers.cpan.org/
 783  =back
 785  =head1 PLATFORMS
 787  As of version 5.002, Perl is built with a C<$^O> variable that
 788  indicates the operating system it was built on.  This was implemented
 789  to help speed up code that would otherwise have to C<use Config>
 790  and use the value of C<$Config{osname}>.  Of course, to get more
 791  detailed information about the system, looking into C<%Config> is
 792  certainly recommended.
 794  C<%Config> cannot always be trusted, however, because it was built
 795  at compile time.  If perl was built in one place, then transferred
 796  elsewhere, some values may be wrong.  The values may even have been
 797  edited after the fact.
 799  =head2 Unix
 801  Perl works on a bewildering variety of Unix and Unix-like platforms (see
 802  e.g. most of the files in the F<hints/> directory in the source code kit).
 803  On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
 804  too) is determined either by lowercasing and stripping punctuation from the
 805  first field of the string returned by typing C<uname -a> (or a similar command)
 806  at the shell prompt or by testing the file system for the presence of
 807  uniquely named files such as a kernel or header file.  Here, for example,
 808  are a few of the more popular Unix flavors:
 810      uname         $^O        $Config{'archname'}
 811      --------------------------------------------
 812      AIX           aix        aix
 813      BSD/OS        bsdos      i386-bsdos
 814      Darwin        darwin     darwin
 815      dgux          dgux       AViiON-dgux
 816      DYNIX/ptx     dynixptx   i386-dynixptx
 817      FreeBSD       freebsd    freebsd-i386    
 818      Linux         linux      arm-linux
 819      Linux         linux      i386-linux
 820      Linux         linux      i586-linux
 821      Linux         linux      ppc-linux
 822      HP-UX         hpux       PA-RISC1.1
 823      IRIX          irix       irix
 824      Mac OS X      darwin     darwin
 825      MachTen PPC   machten    powerpc-machten
 826      NeXT 3        next       next-fat
 827      NeXT 4        next       OPENSTEP-Mach
 828      openbsd       openbsd    i386-openbsd
 829      OSF1          dec_osf    alpha-dec_osf
 830      reliantunix-n svr4       RM400-svr4
 831      SCO_SV        sco_sv     i386-sco_sv
 832      SINIX-N       svr4       RM400-svr4
 833      sn4609        unicos     CRAY_C90-unicos
 834      sn6521        unicosmk   t3e-unicosmk
 835      sn9617        unicos     CRAY_J90-unicos
 836      SunOS         solaris    sun4-solaris
 837      SunOS         solaris    i86pc-solaris
 838      SunOS4        sunos      sun4-sunos
 840  Because the value of C<$Config{archname}> may depend on the
 841  hardware architecture, it can vary more than the value of C<$^O>.
 843  =head2 DOS and Derivatives
 845  Perl has long been ported to Intel-style microcomputers running under
 846  systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
 847  bring yourself to mention (except for Windows CE, if you count that).
 848  Users familiar with I<COMMAND.COM> or I<CMD.EXE> style shells should
 849  be aware that each of these file specifications may have subtle
 850  differences:
 852      $filespec0 = "c:/foo/bar/file.txt";
 853      $filespec1 = "c:\\foo\\bar\\file.txt";
 854      $filespec2 = 'c:\foo\bar\file.txt';
 855      $filespec3 = 'c:\\foo\\bar\\file.txt';
 857  System calls accept either C</> or C<\> as the path separator.
 858  However, many command-line utilities of DOS vintage treat C</> as
 859  the option prefix, so may get confused by filenames containing C</>.
 860  Aside from calling any external programs, C</> will work just fine,
 861  and probably better, as it is more consistent with popular usage,
 862  and avoids the problem of remembering what to backwhack and what
 863  not to.
 865  The DOS FAT filesystem can accommodate only "8.3" style filenames.  Under
 866  the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
 867  filesystems you may have to be careful about case returned with functions
 868  like C<readdir> or used with functions like C<open> or C<opendir>.
 870  DOS also treats several filenames as special, such as AUX, PRN,
 871  NUL, CON, COM1, LPT1, LPT2, etc.  Unfortunately, sometimes these
 872  filenames won't even work if you include an explicit directory
 873  prefix.  It is best to avoid such filenames, if you want your code
 874  to be portable to DOS and its derivatives.  It's hard to know what
 875  these all are, unfortunately.
 877  Users of these operating systems may also wish to make use of
 878  scripts such as I<pl2bat.bat> or I<pl2cmd> to
 879  put wrappers around your scripts.
 881  Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
 882  and writing to files (see L<"Newlines">).  C<binmode(FILEHANDLE)>
 883  will keep C<\n> translated as C<\012> for that filehandle.  Since it is a
 884  no-op on other systems, C<binmode> should be used for cross-platform code
 885  that deals with binary data.  That's assuming you realize in advance
 886  that your data is in binary.  General-purpose programs should
 887  often assume nothing about their data.
 889  The C<$^O> variable and the C<$Config{archname}> values for various
 890  DOSish perls are as follows:
 892       OS            $^O      $Config{archname}   ID    Version
 893       --------------------------------------------------------
 894       MS-DOS        dos        ?                 
 895       PC-DOS        dos        ?                 
 896       OS/2          os2        ?
 897       Windows 3.1   ?          ?                 0      3 01
 898       Windows 95    MSWin32    MSWin32-x86       1      4 00
 899       Windows 98    MSWin32    MSWin32-x86       1      4 10
 900       Windows ME    MSWin32    MSWin32-x86       1      ?
 901       Windows NT    MSWin32    MSWin32-x86       2      4 xx
 902       Windows NT    MSWin32    MSWin32-ALPHA     2      4 xx
 903       Windows NT    MSWin32    MSWin32-ppc       2      4 xx
 904       Windows 2000  MSWin32    MSWin32-x86       2      5 00
 905       Windows XP    MSWin32    MSWin32-x86       2      5 01
 906       Windows 2003  MSWin32    MSWin32-x86       2      5 02
 907       Windows CE    MSWin32    ?                 3           
 908       Cygwin        cygwin     cygwin
 910  The various MSWin32 Perl's can distinguish the OS they are running on
 911  via the value of the fifth element of the list returned from 
 912  Win32::GetOSVersion().  For example:
 914      if ($^O eq 'MSWin32') {
 915          my @os_version_info = Win32::GetOSVersion();
 916          print +('3.1','95','NT')[$os_version_info[4]],"\n";
 917      }
 919  There are also Win32::IsWinNT() and Win32::IsWin95(), try C<perldoc Win32>,
 920  and as of libwin32 0.19 (not part of the core Perl distribution)
 921  Win32::GetOSName().  The very portable POSIX::uname() will work too:
 923      c:\> perl -MPOSIX -we "print join '|', uname"
 924      Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
 926  Also see:
 928  =over 4
 930  =item *
 932  The djgpp environment for DOS, http://www.delorie.com/djgpp/
 933  and L<perldos>.
 935  =item *
 937  The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
 938  http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or
 939  ftp://hobbes.nmsu.edu/pub/os2/dev/emx/  Also L<perlos2>.
 941  =item *
 943  Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
 944  in L<perlcygwin>.  
 946  =item *
 948  The C<Win32::*> modules in L<Win32>.
 950  =item *
 952  The ActiveState Pages, http://www.activestate.com/
 954  =item *
 956  The Cygwin environment for Win32; F<README.cygwin> (installed 
 957  as L<perlcygwin>), http://www.cygwin.com/
 959  =item *
 961  The U/WIN environment for Win32,
 962  http://www.research.att.com/sw/tools/uwin/
 964  =item *
 966  Build instructions for OS/2, L<perlos2>
 968  =back
 970  =head2 S<Mac OS>
 972  Any module requiring XS compilation is right out for most people, because
 973  MacPerl is built using non-free (and non-cheap!) compilers.  Some XS
 974  modules that can work with MacPerl are built and distributed in binary
 975  form on CPAN.
 977  Directories are specified as:
 979      volume:folder:file              for absolute pathnames
 980      volume:folder:                  for absolute pathnames
 981      :folder:file                    for relative pathnames
 982      :folder:                        for relative pathnames
 983      :file                           for relative pathnames
 984      file                            for relative pathnames
 986  Files are stored in the directory in alphabetical order.  Filenames are
 987  limited to 31 characters, and may include any character except for
 988  null and C<:>, which is reserved as the path separator.
 990  Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the
 991  Mac::Files module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>.
 993  In the MacPerl application, you can't run a program from the command line;
 994  programs that expect C<@ARGV> to be populated can be edited with something
 995  like the following, which brings up a dialog box asking for the command
 996  line arguments.
 998      if (!@ARGV) {
 999          @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
1000      }
1002  A MacPerl script saved as a "droplet" will populate C<@ARGV> with the full
1003  pathnames of the files dropped onto the script.
1005  Mac users can run programs under a type of command line interface
1006  under MPW (Macintosh Programmer's Workshop, a free development
1007  environment from Apple).  MacPerl was first introduced as an MPW
1008  tool, and MPW can be used like a shell:
1010      perl myscript.plx some arguments
1012  ToolServer is another app from Apple that provides access to MPW tools
1013  from MPW and the MacPerl app, which allows MacPerl programs to use
1014  C<system>, backticks, and piped C<open>.
1016  "S<Mac OS>" is the proper name for the operating system, but the value
1017  in C<$^O> is "MacOS".  To determine architecture, version, or whether
1018  the application or MPW tool version is running, check:
1020      $is_app    = $MacPerl::Version =~ /App/;
1021      $is_tool   = $MacPerl::Version =~ /MPW/;
1022      ($version) = $MacPerl::Version =~ /^(\S+)/;
1023      $is_ppc    = $MacPerl::Architecture eq 'MacPPC';
1024      $is_68k    = $MacPerl::Architecture eq 'Mac68K';
1026  S<Mac OS X>, based on NeXT's OpenStep OS, runs MacPerl natively, under the
1027  "Classic" environment.  There is no "Carbon" version of MacPerl to run
1028  under the primary Mac OS X environment.  S<Mac OS X> and its Open Source
1029  version, Darwin, both run Unix perl natively.
1031  Also see:
1033  =over 4
1035  =item *
1037  MacPerl Development, http://dev.macperl.org/ .
1039  =item *
1041  The MacPerl Pages, http://www.macperl.com/ .
1043  =item *
1045  The MacPerl mailing lists, http://lists.perl.org/ .
1047  =item *
1049  MPW, ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/
1051  =back
1053  =head2 VMS
1055  Perl on VMS is discussed in L<perlvms> in the perl distribution.
1057  The official name of VMS as of this writing is OpenVMS.
1059  Perl on VMS can accept either VMS- or Unix-style file
1060  specifications as in either of the following:
1062      $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
1063      $ perl -ne "print if /perl_setup/i" /sys$login/login.com
1065  but not a mixture of both as in:
1067      $ perl -ne "print if /perl_setup/i" sys$login:/login.com
1068      Can't open sys$login:/login.com: file specification syntax error
1070  Interacting with Perl from the Digital Command Language (DCL) shell
1071  often requires a different set of quotation marks than Unix shells do.
1072  For example:
1074      $ perl -e "print ""Hello, world.\n"""
1075      Hello, world.
1077  There are several ways to wrap your perl scripts in DCL F<.COM> files, if
1078  you are so inclined.  For example:
1080      $ write sys$output "Hello from DCL!"
1081      $ if p1 .eqs. ""
1082      $ then perl -x 'f$environment("PROCEDURE")
1083      $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
1084      $ deck/dollars="__END__"
1085      #!/usr/bin/perl
1087      print "Hello from Perl!\n";
1089      __END__
1090      $ endif
1092  Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
1093  perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
1095  The VMS operating system has two filesystems, known as ODS-2 and ODS-5.
1097  For ODS-2, filenames are in the format "name.extension;version".  The
1098  maximum length for filenames is 39 characters, and the maximum length for
1099  extensions is also 39 characters.  Version is a number from 1 to
1100  32767.  Valid characters are C</[A-Z0-9$_-]/>.
1102  The ODS-2 filesystem is case-insensitive and does not preserve case.
1103  Perl simulates this by converting all filenames to lowercase internally.
1105  For ODS-5, filenames may have almost any character in them and can include
1106  Unicode characters.  Characters that could be misinterpreted by the DCL
1107  shell or file parsing utilities need to be prefixed with the C<^>
1108  character, or replaced with hexadecimal characters prefixed with the
1109  C<^> character.  Such prefixing is only needed with the pathnames are
1110  in VMS format in applications.  Programs that can accept the UNIX format
1111  of pathnames do not need the escape characters.  The maximum length for
1112  filenames is 255 characters.  The ODS-5 file system can handle both
1113  a case preserved and a case sensitive mode.
1115  ODS-5 is only available on the OpenVMS for 64 bit platforms.
1117  Support for the extended file specifications is being done as optional
1118  settings to preserve backward compatibility with Perl scripts that
1119  assume the previous VMS limitations.
1121  In general routines on VMS that get a UNIX format file specification
1122  should return it in a UNIX format, and when they get a VMS format
1123  specification they should return a VMS format unless they are documented
1124  to do a conversion.
1126  For routines that generate return a file specification, VMS allows setting
1127  if the C library which Perl is built on if it will be returned in VMS
1128  format or in UNIX format.
1130  With the ODS-2 file system, there is not much difference in syntax of
1131  filenames without paths for VMS or UNIX.  With the extended character
1132  set available with ODS-5 there can be a significant difference.
1134  Because of this, existing Perl scripts written for VMS were sometimes
1135  treating VMS and UNIX filenames interchangeably.  Without the extended
1136  character set enabled, this behavior will mostly be maintained for
1137  backwards compatibility.
1139  When extended characters are enabled with ODS-5, the handling of
1140  UNIX formatted file specifications is to that of a UNIX system.
1142  VMS file specifications without extensions have a trailing dot.  An
1143  equivalent UNIX file specification should not show the trailing dot.
1145  The result of all of this, is that for VMS, for portable scripts, you
1146  can not depend on Perl to present the filenames in lowercase, to be
1147  case sensitive, and that the filenames could be returned in either
1148  UNIX or VMS format.
1150  And if a routine returns a file specification, unless it is intended to
1151  convert it, it should return it in the same format as it found it.
1153  C<readdir> by default has traditionally returned lowercased filenames.
1154  When the ODS-5 support is enabled, it will return the exact case of the
1155  filename on the disk.
1157  Files without extensions have a trailing period on them, so doing a
1158  C<readdir> in the default mode with a file named F<A.;5> will
1159  return F<a.> when VMS is (though that file could be opened with
1160  C<open(FH, 'A')>).
1162  With support for extended file specifications and if C<opendir> was
1163  given a UNIX format directory, a file named F<A.;5> will return F<a>
1164  and optionally in the exact case on the disk.  When C<opendir> is given
1165  a VMS format directory, then C<readdir> should return F<a.>, and
1166  again with the optionally the exact case.
1168  RMS had an eight level limit on directory depths from any rooted logical
1169  (allowing 16 levels overall) prior to VMS 7.2, and even with versions of
1170  VMS on VAX up through 7.3.  Hence C<PERL_ROOT:[LIB.]> is a
1171  valid directory specification but C<PERL_ROOT:[LIB.]> is
1172  not.  F<Makefile.PL> authors might have to take this into account, but at
1173  least they can refer to the former as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
1175  Pumpkings and module integrators can easily see whether files with too many
1176  directory levels have snuck into the core by running the following in the
1177  top-level source directory:
1179     $ perl -ne "$_=~s/\s+.*//; print if scalar(split /\//) > 8;" < MANIFEST
1182  The VMS::Filespec module, which gets installed as part of the build
1183  process on VMS, is a pure Perl module that can easily be installed on
1184  non-VMS platforms and can be helpful for conversions to and from RMS
1185  native formats.  It is also now the only way that you should check to
1186  see if VMS is in a case sensitive mode.
1188  What C<\n> represents depends on the type of file opened.  It usually
1189  represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>, 
1190  C<\000>, C<\040>, or nothing depending on the file organization and 
1191  record format.  The VMS::Stdio module provides access to the 
1192  special fopen() requirements of files with unusual attributes on VMS.
1194  TCP/IP stacks are optional on VMS, so socket routines might not be
1195  implemented.  UDP sockets may not be supported.
1197  The TCP/IP library support for all current versions of VMS is dynamically
1198  loaded if present, so even if the routines are configured, they may
1199  return a status indicating that they are not implemented.
1201  The value of C<$^O> on OpenVMS is "VMS".  To determine the architecture
1202  that you are running on without resorting to loading all of C<%Config>
1203  you can examine the content of the C<@INC> array like so:
1205      if (grep(/VMS_AXP/, @INC)) {
1206          print "I'm on Alpha!\n";
1208      } elsif (grep(/VMS_VAX/, @INC)) {
1209          print "I'm on VAX!\n";
1211      } elsif (grep(/VMS_IA64/, @INC)) {
1212          print "I'm on IA64!\n";
1214      } else {
1215          print "I'm not so sure about where $^O is...\n";
1216      }
1218  In general, the significant differences should only be if Perl is running
1219  on VMS_VAX or one of the 64 bit OpenVMS platforms.
1221  On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
1222  logical name.  Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
1223  calls to C<localtime> are adjusted to count offsets from
1224  01-JAN-1970 00:00:00.00, just like Unix.
1226  Also see:
1228  =over 4
1230  =item *
1232  F<README.vms> (installed as L<README_vms>), L<perlvms>
1234  =item *
1236  vmsperl list, vmsperl-subscribe@perl.org
1238  =item *
1240  vmsperl on the web, http://www.sidhe.org/vmsperl/index.html
1242  =back
1244  =head2 VOS
1246  Perl on VOS is discussed in F<README.vos> in the perl distribution
1247  (installed as L<perlvos>).  Perl on VOS can accept either VOS- or
1248  Unix-style file specifications as in either of the following:
1250      C<< $ perl -ne "print if /perl_setup/i" >system>notices >>
1251      C<< $ perl -ne "print if /perl_setup/i" /system/notices >>
1253  or even a mixture of both as in:
1255      C<< $ perl -ne "print if /perl_setup/i" >system/notices >>
1257  Even though VOS allows the slash character to appear in object
1258  names, because the VOS port of Perl interprets it as a pathname
1259  delimiting character, VOS files, directories, or links whose names
1260  contain a slash character cannot be processed.  Such files must be
1261  renamed before they can be processed by Perl.  Note that VOS limits
1262  file names to 32 or fewer characters.
1264  The value of C<$^O> on VOS is "VOS".  To determine the architecture that
1265  you are running on without resorting to loading all of C<%Config> you
1266  can examine the content of the @INC array like so:
1268      if ($^O =~ /VOS/) {
1269          print "I'm on a Stratus box!\n";
1270      } else {
1271          print "I'm not on a Stratus box!\n";
1272          die;
1273      }
1275  Also see:
1277  =over 4
1279  =item *
1281  F<README.vos> (installed as L<perlvos>)
1283  =item *
1285  The VOS mailing list.
1287  There is no specific mailing list for Perl on VOS.  You can post
1288  comments to the comp.sys.stratus newsgroup, or subscribe to the general
1289  Stratus mailing list.  Send a letter with "subscribe Info-Stratus" in
1290  the message body to majordomo@list.stratagy.com.
1292  =item *
1294  VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html
1296  =back
1298  =head2 EBCDIC Platforms
1300  Recent versions of Perl have been ported to platforms such as OS/400 on
1301  AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
1302  Mainframes.  Such computers use EBCDIC character sets internally (usually
1303  Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
1304  systems).  On the mainframe perl currently works under the "Unix system
1305  services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
1306  the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
1307  See L<perlos390> for details.  Note that for OS/400 there is also a port of
1308  Perl 5.8.1/5.9.0 or later to the PASE which is ASCII-based (as opposed to
1309  ILE which is EBCDIC-based), see L<perlos400>. 
1311  As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
1312  sub-systems do not support the C<#!> shebang trick for script invocation.
1313  Hence, on OS/390 and VM/ESA perl scripts can be executed with a header
1314  similar to the following simple script:
1316      : # use perl
1317          eval 'exec /usr/local/bin/perl -S $0 $1+"$@"}'
1318              if 0;
1319      #!/usr/local/bin/perl     # just a comment really
1321      print "Hello from perl!\n";
1323  OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
1324  Calls to C<system> and backticks can use POSIX shell syntax on all
1325  S/390 systems.
1327  On the AS/400, if PERL5 is in your library list, you may need
1328  to wrap your perl scripts in a CL procedure to invoke them like so:
1330      BEGIN
1331        CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1332      ENDPGM
1334  This will invoke the perl script F<hello.pl> in the root of the
1335  QOpenSys file system.  On the AS/400 calls to C<system> or backticks
1336  must use CL syntax.
1338  On these platforms, bear in mind that the EBCDIC character set may have
1339  an effect on what happens with some perl functions (such as C<chr>,
1340  C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
1341  well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
1342  and C<|>, not to mention dealing with socket interfaces to ASCII computers
1343  (see L<"Newlines">).
1345  Fortunately, most web servers for the mainframe will correctly
1346  translate the C<\n> in the following statement to its ASCII equivalent
1347  (C<\r> is the same under both Unix and OS/390 & VM/ESA):
1349      print "Content-type: text/html\r\n\r\n";
1351  The values of C<$^O> on some of these platforms includes:
1353      uname         $^O        $Config{'archname'}
1354      --------------------------------------------
1355      OS/390        os390      os390
1356      OS400         os400      os400
1357      POSIX-BC      posix-bc   BS2000-posix-bc
1358      VM/ESA        vmesa      vmesa
1360  Some simple tricks for determining if you are running on an EBCDIC
1361  platform could include any of the following (perhaps all):
1363      if ("\t" eq "\05")   { print "EBCDIC may be spoken here!\n"; }
1365      if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1367      if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1369  One thing you may not want to rely on is the EBCDIC encoding
1370  of punctuation characters since these may differ from code page to code
1371  page (and once your module or script is rumoured to work with EBCDIC,
1372  folks will want it to work with all EBCDIC character sets).
1374  Also see:
1376  =over 4
1378  =item *
1380  L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
1381  L<perlebcdic>.
1383  =item *
1385  The perl-mvs@perl.org list is for discussion of porting issues as well as
1386  general usage issues for all EBCDIC Perls.  Send a message body of
1387  "subscribe perl-mvs" to majordomo@perl.org.
1389  =item *
1391  AS/400 Perl information at
1392  http://as400.rochester.ibm.com/
1393  as well as on CPAN in the F<ports/> directory.
1395  =back
1397  =head2 Acorn RISC OS
1399  Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
1400  Unix, and because Unix filename emulation is turned on by default, 
1401  most simple scripts will probably work "out of the box".  The native
1402  filesystem is modular, and individual filesystems are free to be
1403  case-sensitive or insensitive, and are usually case-preserving.  Some
1404  native filesystems have name length limits, which file and directory
1405  names are silently truncated to fit.  Scripts should be aware that the
1406  standard filesystem currently has a name length limit of B<10>
1407  characters, with up to 77 items in a directory, but other filesystems
1408  may not impose such limitations.
1410  Native filenames are of the form
1412      Filesystem#Special_Field::DiskName.$.Directory.Directory.File
1414  where
1416      Special_Field is not usually present, but may contain . and $ .
1417      Filesystem =~ m|[A-Za-z0-9_]|
1418      DsicName   =~ m|[A-Za-z0-9_/]|
1419      $ represents the root directory
1420      . is the path separator
1421      @ is the current directory (per filesystem but machine global)
1422      ^ is the parent directory
1423      Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1425  The default filename translation is roughly C<tr|/.|./|;>
1427  Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
1428  the second stage of C<$> interpolation in regular expressions will fall
1429  foul of the C<$.> if scripts are not careful.
1431  Logical paths specified by system variables containing comma-separated
1432  search lists are also allowed; hence C<System:Modules> is a valid
1433  filename, and the filesystem will prefix C<Modules> with each section of
1434  C<System$Path> until a name is made that points to an object on disk.
1435  Writing to a new file C<System:Modules> would be allowed only if
1436  C<System$Path> contains a single item list.  The filesystem will also
1437  expand system variables in filenames if enclosed in angle brackets, so
1438  C<< <System$Dir>.Modules >> would look for the file
1439  S<C<$ENV{'System$Dir'} . 'Modules'>>.  The obvious implication of this is
1440  that B<fully qualified filenames can start with C<< <> >>> and should
1441  be protected when C<open> is used for input.
1443  Because C<.> was in use as a directory separator and filenames could not
1444  be assumed to be unique after 10 characters, Acorn implemented the C
1445  compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
1446  filenames specified in source code and store the respective files in
1447  subdirectories named after the suffix.  Hence files are translated:
1449      foo.h           h.foo
1450      C:foo.h         C:h.foo        (logical path variable)
1451      sys/os.h        sys.h.os       (C compiler groks Unix-speak)
1452      10charname.c    c.10charname
1453      10charname.o    o.10charname
1454      11charname_.c   c.11charname   (assuming filesystem truncates at 10)
1456  The Unix emulation library's translation of filenames to native assumes
1457  that this sort of translation is required, and it allows a user-defined list
1458  of known suffixes that it will transpose in this fashion.  This may
1459  seem transparent, but consider that with these rules C<foo/bar/baz.h>
1460  and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
1461  C<glob> cannot and do not attempt to emulate the reverse mapping.  Other
1462  C<.>'s in filenames are translated to C</>.
1464  As implied above, the environment accessed through C<%ENV> is global, and
1465  the convention is that program specific environment variables are of the
1466  form C<Program$Name>.  Each filesystem maintains a current directory,
1467  and the current filesystem's current directory is the B<global> current
1468  directory.  Consequently, sociable programs don't change the current
1469  directory but rely on full pathnames, and programs (and Makefiles) cannot
1470  assume that they can spawn a child process which can change the current
1471  directory without affecting its parent (and everyone else for that
1472  matter).
1474  Because native operating system filehandles are global and are currently 
1475  allocated down from 255, with 0 being a reserved value, the Unix emulation
1476  library emulates Unix filehandles.  Consequently, you can't rely on
1477  passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
1479  The desire of users to express filenames of the form
1480  C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
1481  too: C<``> command output capture has to perform a guessing game.  It
1482  assumes that a string C<< <[^<>]+\$[^<>]> >> is a
1483  reference to an environment variable, whereas anything else involving
1484  C<< < >> or C<< > >> is redirection, and generally manages to be 99%
1485  right.  Of course, the problem remains that scripts cannot rely on any
1486  Unix tools being available, or that any tools found have Unix-like command
1487  line arguments.
1489  Extensions and XS are, in theory, buildable by anyone using free
1490  tools.  In practice, many don't, as users of the Acorn platform are
1491  used to binary distributions.  MakeMaker does run, but no available
1492  make currently copes with MakeMaker's makefiles; even if and when
1493  this should be fixed, the lack of a Unix-like shell will cause
1494  problems with makefile rules, especially lines of the form C<cd
1495  sdbm && make all>, and anything using quoting.
1497  "S<RISC OS>" is the proper name for the operating system, but the value
1498  in C<$^O> is "riscos" (because we don't like shouting).
1500  =head2 Other perls
1502  Perl has been ported to many platforms that do not fit into any of
1503  the categories listed above.  Some, such as AmigaOS, Atari MiNT,
1504  BeOS, HP MPE/iX, QNX, Plan 9, and VOS, have been well-integrated
1505  into the standard Perl source code kit.  You may need to see the
1506  F<ports/> directory on CPAN for information, and possibly binaries,
1507  for the likes of: aos, Atari ST, lynxos, riscos, Novell Netware,
1508  Tandem Guardian, I<etc.>  (Yes, we know that some of these OSes may
1509  fall under the Unix category, but we are not a standards body.)
1511  Some approximate operating system names and their C<$^O> values
1512  in the "OTHER" category include:
1514      OS            $^O        $Config{'archname'}
1515      ------------------------------------------
1516      Amiga DOS     amigaos    m68k-amigos
1517      BeOS          beos
1518      MPE/iX        mpeix      PA-RISC1.1
1520  See also:
1522  =over 4
1524  =item *
1526  Amiga, F<README.amiga> (installed as L<perlamiga>).
1528  =item *
1530  Atari, F<README.mint> and Guido Flohr's web page
1531  http://stud.uni-sb.de/~gufl0000/
1533  =item *
1535  Be OS, F<README.beos>
1537  =item *
1539  HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
1540  http://www.bixby.org/mark/perlix.html
1542  =item *
1544  A free perl5-based PERL.NLM for Novell Netware is available in
1545  precompiled binary and source code form from http://www.novell.com/
1546  as well as from CPAN.
1548  =item  *
1550  S<Plan 9>, F<README.plan9>
1552  =back
1556  Listed below are functions that are either completely unimplemented
1557  or else have been implemented differently on various platforms.
1558  Following each description will be, in parentheses, a list of
1559  platforms that the description applies to.
1561  The list may well be incomplete, or even wrong in some places.  When
1562  in doubt, consult the platform-specific README files in the Perl
1563  source distribution, and any other documentation resources accompanying
1564  a given port.
1566  Be aware, moreover, that even among Unix-ish systems there are variations.
1568  For many functions, you can also query C<%Config>, exported by
1569  default from the Config module.  For example, to check whether the
1570  platform has the C<lstat> call, check C<$Config{d_lstat}>.  See
1571  L<Config> for a full description of available variables.
1573  =head2 Alphabetical Listing of Perl Functions
1575  =over 8
1577  =item -X
1579  C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
1580  and applications are executable, and there are no uid/gid
1581  considerations.  C<-o> is not supported.  (S<Mac OS>)
1583  C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
1584  which may not reflect UIC-based file protections.  (VMS)
1586  C<-s> returns the size of the data fork, not the total size of data fork
1587  plus resource fork.  (S<Mac OS>).
1589  C<-s> by name on an open file will return the space reserved on disk,
1590  rather than the current extent.  C<-s> on an open filehandle returns the
1591  current size.  (S<RISC OS>)
1593  C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
1594  C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1596  C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
1597  (S<Mac OS>)
1599  C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
1600  (Win32, VMS, S<RISC OS>)
1602  C<-d> is true if passed a device spec without an explicit directory.
1603  (VMS)
1605  C<-T> and C<-B> are implemented, but might misclassify Mac text files
1606  with foreign characters; this is the case will all platforms, but may
1607  affect S<Mac OS> often.  (S<Mac OS>)
1609  C<-x> (or C<-X>) determine if a file ends in one of the executable
1610  suffixes.  C<-S> is meaningless.  (Win32)
1612  C<-x> (or C<-X>) determine if a file has an executable file type.
1613  (S<RISC OS>)
1615  =item atan2
1617  Due to issues with various CPUs, math libraries, compilers, and standards,
1618  results for C<atan2()> may vary depending on any combination of the above.
1619  Perl attempts to conform to the Open Group/IEEE standards for the results
1620  returned from C<atan2()>, but cannot force the issue if the system Perl is
1621  run on does not allow it.  (Tru64, HP-UX 10.20) 
1623  The current version of the standards for C<atan2()> is available at 
1624  L<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
1626  =item binmode
1628  Meaningless.  (S<Mac OS>, S<RISC OS>)
1630  Reopens file and restores pointer; if function fails, underlying
1631  filehandle may be closed, or pointer may be in a different position.
1632  (VMS)
1634  The value returned by C<tell> may be affected after the call, and
1635  the filehandle may be flushed. (Win32)
1637  =item chmod
1639  Only limited meaning.  Disabling/enabling write permission is mapped to
1640  locking/unlocking the file. (S<Mac OS>)
1642  Only good for changing "owner" read-write access, "group", and "other"
1643  bits are meaningless. (Win32)
1645  Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1647  Access permissions are mapped onto VOS access-control list changes. (VOS)
1649  The actual permissions set depend on the value of the C<CYGWIN>
1650  in the SYSTEM environment settings.  (Cygwin)
1652  =item chown
1654  Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
1656  Does nothing, but won't fail. (Win32)
1658  A little funky, because VOS's notion of ownership is a little funky (VOS).
1660  =item chroot
1662  Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS, VM/ESA)
1664  =item crypt
1666  May not be available if library or source was not provided when building
1667  perl. (Win32)
1669  =item dbmclose
1671  Not implemented. (VMS, S<Plan 9>, VOS)
1673  =item dbmopen
1675  Not implemented. (VMS, S<Plan 9>, VOS)
1677  =item dump
1679  Not useful. (S<Mac OS>, S<RISC OS>)
1681  Not supported. (Cygwin, Win32)
1683  Invokes VMS debugger. (VMS)
1685  =item exec
1687  Not implemented. (S<Mac OS>)
1689  Implemented via Spawn. (VM/ESA)
1691  Does not automatically flush output handles on some platforms.
1692  (SunOS, Solaris, HP-UX)
1694  =item exit
1696  Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
1697  mapping the C<1> to SS$_ABORT (C<44>).  This behavior may be overridden
1698  with the pragma C<use vmsish 'exit'>.  As with the CRTL's exit()
1699  function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
1700  (C<1>); this mapping cannot be overridden.  Any other argument to exit()
1701  is used directly as Perl's exit status.  On VMS, unless the future
1702  POSIX_EXIT mode is enabled, the exit code should always be a valid
1703  VMS exit code and not a generic number.  When the POSIX_EXIT mode is
1704  enabled, a generic number will be encoded in a method compatible with
1705  the C library _POSIX_EXIT macro so that it can be decoded by other
1706  programs, particularly ones written in C, like the GNV package.  (VMS)
1708  =item fcntl
1710  Not implemented. (Win32)
1711  Some functions available based on the version of VMS. (VMS)
1713  =item flock
1715  Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
1717  Available only on Windows NT (not on Windows 95). (Win32)
1719  =item fork
1721  Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VM/ESA, VMS)
1723  Emulated using multiple interpreters.  See L<perlfork>.  (Win32)
1725  Does not automatically flush output handles on some platforms.
1726  (SunOS, Solaris, HP-UX)
1728  =item getlogin
1730  Not implemented. (S<Mac OS>, S<RISC OS>)
1732  =item getpgrp
1734  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1736  =item getppid
1738  Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
1740  =item getpriority
1742  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
1744  =item getpwnam
1746  Not implemented. (S<Mac OS>, Win32)
1748  Not useful. (S<RISC OS>)
1750  =item getgrnam
1752  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1754  =item getnetbyname
1756  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1758  =item getpwuid
1760  Not implemented. (S<Mac OS>, Win32)
1762  Not useful. (S<RISC OS>)
1764  =item getgrgid
1766  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1768  =item getnetbyaddr
1770  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1772  =item getprotobynumber
1774  Not implemented. (S<Mac OS>)
1776  =item getservbyport
1778  Not implemented. (S<Mac OS>)
1780  =item getpwent
1782  Not implemented. (S<Mac OS>, Win32, VM/ESA)
1784  =item getgrent
1786  Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
1788  =item gethostbyname
1790  C<gethostbyname('localhost')> does not work everywhere: you may have
1791  to use C<gethostbyname('')>. (S<Mac OS>, S<Irix 5>)
1793  =item gethostent
1795  Not implemented. (S<Mac OS>, Win32)
1797  =item getnetent
1799  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1801  =item getprotoent
1803  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1805  =item getservent
1807  Not implemented. (Win32, S<Plan 9>)
1809  =item sethostent
1811  Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
1813  =item setnetent
1815  Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
1817  =item setprotoent
1819  Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
1821  =item setservent
1823  Not implemented. (S<Plan 9>, Win32, S<RISC OS>)
1825  =item endpwent
1827  Not implemented. (S<Mac OS>, MPE/iX, VM/ESA, Win32)
1829  =item endgrent
1831  Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
1833  =item endhostent
1835  Not implemented. (S<Mac OS>, Win32)
1837  =item endnetent
1839  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1841  =item endprotoent
1843  Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
1845  =item endservent
1847  Not implemented. (S<Plan 9>, Win32)
1849  =item getsockopt SOCKET,LEVEL,OPTNAME
1851  Not implemented. (S<Plan 9>)
1853  =item glob
1855  This operator is implemented via the File::Glob extension on most
1856  platforms.  See L<File::Glob> for portability information.
1858  =item gmtime
1860  Same portability caveats as L<localtime>.
1864  Not implemented. (VMS)
1866  Available only for socket handles, and it does what the ioctlsocket() call
1867  in the Winsock API does. (Win32)
1869  Available only for socket handles. (S<RISC OS>)
1871  =item kill
1873  C<kill(0, LIST)> is implemented for the sake of taint checking;
1874  use with other signals is unimplemented. (S<Mac OS>)
1876  Not implemented, hence not useful for taint checking. (S<RISC OS>)
1878  C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
1879  a signal to the identified process like it does on Unix platforms.
1880  Instead C<kill($sig, $pid)> terminates the process identified by $pid,
1881  and makes it exit immediately with exit status $sig.  As in Unix, if
1882  $sig is 0 and the specified process exists, it returns true without
1883  actually terminating it. (Win32)
1885  C<kill(-9, $pid)> will terminate the process specified by $pid and
1886  recursively all child processes owned by it.  This is different from
1887  the Unix semantics, where the signal will be delivered to all
1888  processes in the same process group as the process specified by
1889  $pid. (Win32)
1891  Is not supported for process identification number of 0 or negative
1892  numbers. (VMS)
1894  =item link
1896  Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>)
1898  Link count not updated because hard links are not quite that hard
1899  (They are sort of half-way between hard and soft links). (AmigaOS)
1901  Hard links are implemented on Win32 under NTFS only. They are
1902  natively supported on Windows 2000 and later.  On Windows NT they
1903  are implemented using the Windows POSIX subsystem support and the
1904  Perl process will need Administrator or Backup Operator privileges
1905  to create hard links.
1907  Available on 64 bit OpenVMS 8.2 and later.  (VMS)
1909  =item localtime
1911  Because Perl currently relies on the native standard C localtime()
1912  function, it is only safe to use times between 0 and (2**31)-1.  Times
1913  outside this range may result in unexpected behavior depending on your
1914  operating system's implementation of localtime().
1916  =item lstat
1918  Not implemented. (S<RISC OS>)
1920  Return values (especially for device and inode) may be bogus. (Win32)
1922  =item msgctl
1924  =item msgget
1926  =item msgsnd
1928  =item msgrcv
1930  Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
1932  =item open
1934  The C<|> variants are supported only if ToolServer is installed.
1935  (S<Mac OS>)
1937  open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
1939  Opening a process does not automatically flush output handles on some
1940  platforms.  (SunOS, Solaris, HP-UX)
1942  =item pipe
1944  Very limited functionality. (MiNT)
1946  =item readlink
1948  Not implemented. (Win32, VMS, S<RISC OS>)
1950  =item rename
1952  Can't move directories between directories on different logical volumes. (Win32)
1954  =item select
1956  Only implemented on sockets. (Win32, VMS)
1958  Only reliable on sockets. (S<RISC OS>)
1960  Note that the C<select FILEHANDLE> form is generally portable.
1962  =item semctl
1964  =item semget
1966  =item semop
1968  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1970  =item setgrent
1972  Not implemented. (S<Mac OS>, MPE/iX, VMS, Win32, S<RISC OS>, VOS)
1974  =item setpgrp
1976  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1978  =item setpriority
1980  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1982  =item setpwent
1984  Not implemented. (S<Mac OS>, MPE/iX, Win32, S<RISC OS>, VOS)
1986  =item setsockopt
1988  Not implemented. (S<Plan 9>)
1990  =item shmctl
1992  =item shmget
1994  =item shmread
1996  =item shmwrite
1998  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
2000  =item sockatmark
2002  A relatively recent addition to socket functions, may not
2003  be implemented even in UNIX platforms.
2005  =item socketpair
2007  Not implemented. (Win32, S<RISC OS>, VOS, VM/ESA)
2009  Available on 64 bit OpenVMS 8.2 and later.  (VMS)
2011  =item stat
2013  Platforms that do not have rdev, blksize, or blocks will return these
2014  as '', so numeric comparison or manipulation of these fields may cause
2015  'not numeric' warnings.
2017  mtime and atime are the same thing, and ctime is creation time instead of
2018  inode change time. (S<Mac OS>).
2020  ctime not supported on UFS (S<Mac OS X>).
2022  ctime is creation time instead of inode change time  (Win32).
2024  device and inode are not meaningful.  (Win32)
2026  device and inode are not necessarily reliable.  (VMS)
2028  mtime, atime and ctime all return the last modification time.  Device and
2029  inode are not necessarily reliable.  (S<RISC OS>)
2031  dev, rdev, blksize, and blocks are not available.  inode is not
2032  meaningful and will differ between stat calls on the same file.  (os2)
2034  some versions of cygwin when doing a stat("foo") and if not finding it
2035  may then attempt to stat("foo.exe") (Cygwin)
2037  On Win32 stat() needs to open the file to determine the link count
2038  and update attributes that may have been changed through hard links.
2039  Setting ${^WIN32_SLOPPY_STAT} to a true value speeds up stat() by
2040  not performing this operation. (Win32)
2042  =item symlink
2044  Not implemented. (Win32, S<RISC OS>)
2046  Implemented on 64 bit VMS 8.3.  VMS requires the symbolic link to be in Unix
2047  syntax if it is intended to resolve to a valid path.
2049  =item syscall
2051  Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
2053  =item sysopen
2055  The traditional "0", "1", and "2" MODEs are implemented with different
2056  numeric values on some systems.  The flags exported by C<Fcntl>
2057  (O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though.  (S<Mac
2058  OS>, OS/390, VM/ESA)
2060  =item system
2062  Only implemented if ToolServer is installed. (S<Mac OS>)
2064  As an optimization, may not call the command shell specified in
2065  C<$ENV{PERL5SHELL}>.  C<system(1, @args)> spawns an external
2066  process and immediately returns its process designator, without
2067  waiting for it to terminate.  Return value may be used subsequently
2068  in C<wait> or C<waitpid>.  Failure to spawn() a subprocess is indicated
2069  by setting $? to "255 << 8".  C<$?> is set in a way compatible with
2070  Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8",
2071  as described in the documentation).  (Win32)
2073  There is no shell to process metacharacters, and the native standard is
2074  to pass a command line terminated by "\n" "\r" or "\0" to the spawned
2075  program.  Redirection such as C<< > foo >> is performed (if at all) by
2076  the run time library of the spawned program.  C<system> I<list> will call
2077  the Unix emulation library's C<exec> emulation, which attempts to provide
2078  emulation of the stdin, stdout, stderr in force in the parent, providing
2079  the child program uses a compatible version of the emulation library.
2080  I<scalar> will call the native command line direct and no such emulation
2081  of a child Unix program will exists.  Mileage B<will> vary.  (S<RISC OS>)
2083  Far from being POSIX compliant.  Because there may be no underlying
2084  /bin/sh tries to work around the problem by forking and execing the
2085  first token in its argument string.  Handles basic redirection
2086  ("<" or ">") on its own behalf. (MiNT)
2088  Does not automatically flush output handles on some platforms.
2089  (SunOS, Solaris, HP-UX)
2091  The return value is POSIX-like (shifted up by 8 bits), which only allows
2092  room for a made-up value derived from the severity bits of the native
2093  32-bit condition code (unless overridden by C<use vmsish 'status'>). 
2094  If the native condition code is one that has a POSIX value encoded, the
2095  POSIX value will be decoded to extract the expected exit value.
2096  For more details see L<perlvms/$?>. (VMS)
2098  =item times
2100  Only the first entry returned is nonzero. (S<Mac OS>)
2102  "cumulative" times will be bogus.  On anything other than Windows NT
2103  or Windows 2000, "system" time will be bogus, and "user" time is
2104  actually the time returned by the clock() function in the C runtime
2105  library. (Win32)
2107  Not useful. (S<RISC OS>)
2109  =item truncate
2111  Not implemented. (Older versions of VMS)
2113  Truncation to same-or-shorter lengths only. (VOS)
2115  If a FILEHANDLE is supplied, it must be writable and opened in append
2116  mode (i.e., use C<<< open(FH, '>>filename') >>>
2117  or C<sysopen(FH,...,O_APPEND|O_RDWR)>.  If a filename is supplied, it
2118  should not be held open elsewhere. (Win32)
2120  =item umask
2122  Returns undef where unavailable, as of version 5.005.
2124  C<umask> works but the correct permissions are set only when the file
2125  is finally closed. (AmigaOS)
2127  =item utime
2129  Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
2131  May not behave as expected.  Behavior depends on the C runtime
2132  library's implementation of utime(), and the filesystem being
2133  used.  The FAT filesystem typically does not support an "access
2134  time" field, and it may limit timestamps to a granularity of
2135  two seconds. (Win32)
2137  =item wait
2139  =item waitpid
2141  Not implemented. (S<Mac OS>)
2143  Can only be applied to process handles returned for processes spawned
2144  using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32)
2146  Not useful. (S<RISC OS>)
2148  =back
2151  =head1 Supported Platforms
2153  As of July 2002 (the Perl release 5.8.0), the following platforms are
2154  able to build Perl from the standard source code distribution
2155  available at http://www.cpan.org/src/index.html
2157          AIX
2158          BeOS
2159          BSD/OS          (BSDi)
2160          Cygwin
2161          DG/UX
2162          DOS DJGPP       1)
2163          DYNIX/ptx
2164          EPOC R5
2165          FreeBSD
2166          HI-UXMPP        (Hitachi) (5.8.0 worked but we didn't know it)
2167          HP-UX
2168          IRIX
2169          Linux
2170          Mac OS Classic
2171          Mac OS X        (Darwin)
2172          MPE/iX
2173          NetBSD
2174          NetWare
2175          NonStop-UX
2176          ReliantUNIX     (formerly SINIX)
2177          OpenBSD
2178          OpenVMS         (formerly VMS)
2179          Open UNIX       (Unixware) (since Perl 5.8.1/5.9.0)
2180          OS/2
2181          OS/400          (using the PASE) (since Perl 5.8.1/5.9.0)
2182          PowerUX
2183          POSIX-BC        (formerly BS2000)
2184          QNX
2185          Solaris
2186          SunOS 4
2187          SUPER-UX        (NEC)
2188          Tru64 UNIX      (formerly DEC OSF/1, Digital UNIX)
2189          UNICOS
2190          UNICOS/mk
2191          UTS
2192          VOS
2193          Win95/98/ME/2K/XP 2)
2194          WinCE
2195          z/OS            (formerly OS/390)
2196          VM/ESA
2198          1) in DOS mode either the DOS or OS/2 ports can be used
2199          2) compilers: Borland, MinGW (GCC), VC6
2201  The following platforms worked with the previous releases (5.6 and
2202  5.7), but we did not manage either to fix or to test these in time
2203  for the 5.8.0 release.  There is a very good chance that many of these
2204  will work fine with the 5.8.0.
2206          BSD/OS
2207          DomainOS
2208          Hurd
2209          LynxOS
2210          MachTen
2211          PowerMAX
2212          SCO SV
2213          SVR4
2214          Unixware
2215          Windows 3.1
2217  Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
2219      AmigaOS
2221  The following platforms have been known to build Perl from source in
2222  the past (5.005_03 and earlier), but we haven't been able to verify
2223  their status for the current release, either because the
2224  hardware/software platforms are rare or because we don't have an
2225  active champion on these platforms--or both.  They used to work,
2226  though, so go ahead and try compiling them, and let perlbug@perl.org
2227  of any trouble.
2229          3b1
2230          A/UX
2231          ConvexOS
2232          CX/UX
2233          DC/OSx
2234          DDE SMES
2235          DOS EMX
2236          Dynix
2237          EP/IX
2238          ESIX
2239          FPS
2240          GENIX
2241          Greenhills
2242          ISC
2243          MachTen 68k
2244          MiNT
2245          MPC
2246          NEWS-OS
2247          NextSTEP
2248          OpenSTEP
2249          Opus
2250          Plan 9
2251          RISC/os
2252          SCO ODT/OSR
2253          Stellar
2254          SVR2
2255          TI1500
2256          TitanOS
2257          Ultrix
2258          Unisys Dynix
2260  The following platforms have their own source code distributions and
2261  binaries available via http://www.cpan.org/ports/
2263                                  Perl release
2265          OS/400 (ILE)            5.005_02
2266          Tandem Guardian         5.004
2268  The following platforms have only binaries available via
2269  http://www.cpan.org/ports/index.html :
2271                                  Perl release
2273          Acorn RISCOS            5.005_02
2274          AOS                     5.002
2275          LynxOS                  5.004_02
2277  Although we do suggest that you always build your own Perl from
2278  the source code, both for maximal configurability and for security,
2279  in case you are in a hurry you can check
2280  http://www.cpan.org/ports/index.html for binary distributions.
2282  =head1 SEE ALSO
2284  L<perlaix>, L<perlamiga>, L<perlapollo>, L<perlbeos>, L<perlbs2000>,
2285  L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>, L<perlepoc>,
2286  L<perlebcdic>, L<perlfreebsd>, L<perlhurd>, L<perlhpux>, L<perlirix>,
2287  L<perlmachten>, L<perlmacos>, L<perlmacosx>, L<perlmint>, L<perlmpeix>,
2288  L<perlnetware>, L<perlos2>, L<perlos390>, L<perlos400>,
2289  L<perlplan9>, L<perlqnx>, L<perlsolaris>, L<perltru64>,
2290  L<perlunicode>, L<perlvmesa>, L<perlvms>, L<perlvos>,
2291  L<perlwin32>, and L<Win32>.
2295  Abigail <abigail@foad.org>,
2296  Charles Bailey <bailey@newman.upenn.edu>,
2297  Graham Barr <gbarr@pobox.com>,
2298  Tom Christiansen <tchrist@perl.com>,
2299  Nicholas Clark <nick@ccl4.org>,
2300  Thomas Dorner <Thomas.Dorner@start.de>,
2301  Andy Dougherty <doughera@lafayette.edu>,
2302  Dominic Dunlop <domo@computer.org>,
2303  Neale Ferguson <neale@vma.tabnsw.com.au>,
2304  David J. Fiander <davidf@mks.com>,
2305  Paul Green <Paul.Green@stratus.com>,
2306  M.J.T. Guy <mjtg@cam.ac.uk>,
2307  Jarkko Hietaniemi <jhi@iki.fi>,
2308  Luther Huffman <lutherh@stratcom.com>,
2309  Nick Ing-Simmons <nick@ing-simmons.net>,
2310  Andreas J. KE<ouml>nig <a.koenig@mind.de>,
2311  Markus Laker <mlaker@contax.co.uk>,
2312  Andrew M. Langmead <aml@world.std.com>,
2313  Larry Moore <ljmoore@freespace.net>,
2314  Paul Moore <Paul.Moore@uk.origin-it.com>,
2315  Chris Nandor <pudge@pobox.com>,
2316  Matthias Neeracher <neeracher@mac.com>,
2317  Philip Newton <pne@cpan.org>,
2318  Gary Ng <71564.1743@CompuServe.COM>,
2319  Tom Phoenix <rootbeer@teleport.com>,
2320  AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
2321  Peter Prymmer <pvhp@forte.com>,
2322  Hugo van der Sanden <hv@crypt0.demon.co.uk>,
2323  Gurusamy Sarathy <gsar@activestate.com>,
2324  Paul J. Schinder <schinder@pobox.com>,
2325  Michael G Schwern <schwern@pobox.com>,
2326  Dan Sugalski <dan@sidhe.org>,
2327  Nathan Torkington <gnat@frii.com>.
2328  John Malmberg <wb8tyw@qsl.net>

Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1