pod/perlport.pod

   1 =head1 NAME
   2
   3 perlport - Writing portable Perl
   4
   5 =head1 DESCRIPTION
   6
   7 Perl runs on numerous operating systems.  While most of them share
   8 much in common, they also have their own unique features.
   9
  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.
  13
  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.
  27
  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.
  32
  33 Be aware of two important points:
  34
  35 =over 4
  36
  37 =item Not all Perl programs have to be portable
  38
  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.
  43
  44 =item Nearly all of Perl already I<is> portable
  45
  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.
  52
  53 =back
  54
  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.
  63
  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.
  68
  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
  72 (L<"FUNCTION IMPLEMENTATIONS">.
  73
  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"> >>).
  79
  80 =head1 ISSUES
  81
  82 =head2 Newlines
  83
  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>.
  88
  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.
  96
  97 A common cause of unportable programs is the misuse of chop() to trim
  98 newlines:
  99
 100     # XXX UNPORTABLE!
 101     while(<FILE>) {
 102         chop;
 103         @array = split(/:/);
 104         #...
 105     }
 106
 107 You can get away with this on Unix and MacOS (they have a single
 108 character end-of-line), but the same program will break under DOSish
 109 perls because you're only chop()ing half the end-of-line.  Instead,
 110 chomp() should be used to trim newlines.  The Dunce::Files module can
 111 help audit your code for misuses of chop().
 112
 113 When dealing with binary files (or text files in binary mode) be sure
 114 to explicitly set $/ to the appropriate value for your file format
 115 before using chomp().
 116
 117 Because of the "text" mode translation, DOSish perls have limitations
 118 in using C<seek> and C<tell> on a file accessed in "text" mode.
 119 Stick to C<seek>-ing to locations you got from C<tell> (and no
 120 others), and you are usually free to use C<seek> and C<tell> even
 121 in "text" mode.  Using C<seek> or C<tell> or other file operations
 122 may be non-portable.  If you use C<binmode> on a file, however, you
 123 can usually C<seek> and C<tell> with arbitrary values in safety.
 124
 125 A common misconception in socket programming is that C<\n> eq C<\012>
 126 everywhere.  When using protocols such as common Internet protocols,
 127 C<\012> and C<\015> are called for specifically, and the values of
 128 the logical C<\n> and C<\r> (carriage return) are not reliable.
 129
 130     print SOCKET "Hi there, client!\r\n";      # WRONG
 131     print SOCKET "Hi there, client!\015\012";  # RIGHT
 132
 133 However, using C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious
 134 and unsightly, as well as confusing to those maintaining the code.  As
 135 such, the Socket module supplies the Right Thing for those who want it.
 136
 137     use Socket qw(:DEFAULT :crlf);
 138     print SOCKET "Hi there, client!$CRLF"      # RIGHT
 139
 140 When reading from a socket, remember that the default input record
 141 separator C<$/> is C<\n>, but robust socket code will recognize as
 142 either C<\012> or C<\015\012> as end of line:
 143
 144     while (<SOCKET>) {
 145         # ...
 146     }
 147
 148 Because both CRLF and LF end in LF, the input record separator can
 149 be set to LF and any CR stripped later.  Better to write:
 150
 151     use Socket qw(:DEFAULT :crlf);
 152     local($/) = LF;      # not needed if $/ is already \012
 153
 154     while (<SOCKET>) {
 155         s/$CR?$LF/\n/;   # not sure if socket uses LF or CRLF, OK
 156     #   s/\015?\012/\n/; # same thing
 157     }
 158
 159 This example is preferred over the previous one--even for Unix
 160 platforms--because now any C<\015>'s (C<\cM>'s) are stripped out
 161 (and there was much rejoicing).
 162
 163 Similarly, functions that return text data--such as a function that
 164 fetches a web page--should sometimes translate newlines before
 165 returning the data, if they've not yet been translated to the local
 166 newline representation.  A single line of code will often suffice:
 167
 168     $data =~ s/\015?\012/\n/g;
 169     return $data;
 170
 171 Some of this may be confusing.  Here's a handy reference to the ASCII CR
 172 and LF characters.  You can print it out and stick it in your wallet.
 173
 174     LF  eq  \012  eq  \x0A  eq  \cJ  eq  chr(10)  eq  ASCII 10
 175     CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  ASCII 13
 176
 177              | Unix | DOS  | Mac  |
 178         ---------------------------
 179         \n   |  LF  |  LF  |  CR  |
 180         \r   |  CR  |  CR  |  LF  |
 181         \n * |  LF  | CRLF |  CR  |
 182         \r * |  CR  |  CR  |  LF  |
 183         ---------------------------
 184         * text-mode STDIO
 185
 186 The Unix column assumes that you are not accessing a serial line
 187 (like a tty) in canonical mode.  If you are, then CR on input becomes
 188 "\n", and "\n" on output becomes CRLF.
 189
 190 These are just the most common definitions of C<\n> and C<\r> in Perl.
 191 There may well be others.  For example, on an EBCDIC implementation such
 192 as z/OS or OS/400 the above material is similar to "Unix" but the code
 193 numbers change:
 194
 195     LF  eq  \025  eq  \x15  eq           chr(21)  eq  CP-1047 21
 196     LF  eq  \045  eq  \x25  eq  \cU  eq  chr(37)  eq  CP-0037 37
 197     CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-1047 13
 198     CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-0037 13
 199
 200              | z/OS | OS/400 |
 201         ----------------------
 202         \n   |  LF  |  LF    |
 203         \r   |  CR  |  CR    |
 204         \n * |  LF  |  LF    |
 205         \r * |  CR  |  CR    |
 206         ----------------------
 207         * text-mode STDIO
 208
 209 =head2 Numbers endianness and Width
 210
 211 Different CPUs store integers and floating point numbers in different
 212 orders (called I<endianness>) and widths (32-bit and 64-bit being the
 213 most common today).  This affects your programs when they attempt to transfer
 214 numbers in binary format from one CPU architecture to another,
 215 usually either "live" via network connection, or by storing the
 216 numbers to secondary storage such as a disk file or tape.
 217
 218 Conflicting storage orders make utter mess out of the numbers.  If a
 219 little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
 220 decimal), a big-endian host (Motorola, Sparc, PA) reads it as
 221 0x78563412 (2018915346 in decimal).  Alpha and MIPS can be either:
 222 Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
 223 them in big-endian mode.  To avoid this problem in network (socket)
 224 connections use the C<pack> and C<unpack> formats C<n> and C<N>, the
 225 "network" orders.  These are guaranteed to be portable.
 226
 227 You can explore the endianness of your platform by unpacking a
 228 data structure packed in native format such as:
 229
 230     print unpack("h*", pack("s2", 1, 2)), "\n";
 231     # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
 232     # '00100020' on e.g. Motorola 68040
 233
 234 If you need to distinguish between endian architectures you could use
 235 either of the variables set like so:
 236
 237     $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
 238     $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
 239
 240 Differing widths can cause truncation even between platforms of equal
 241 endianness.  The platform of shorter width loses the upper parts of the
 242 number.  There is no good solution for this problem except to avoid
 243 transferring or storing raw binary numbers.
 244
 245 One can circumnavigate both these problems in two ways.  Either
 246 transfer and store numbers always in text format, instead of raw
 247 binary, or else consider using modules like Data::Dumper (included in
 248 the standard distribution as of Perl 5.005) and Storable (included as
 249 of perl 5.8).  Keeping all data as text significantly simplifies matters.
 250
 251 The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's
 252 how far EBCDIC, or more precisely UTF-EBCDIC will go.
 253
 254 =head2 Files and Filesystems
 255
 256 Most platforms these days structure files in a hierarchical fashion.
 257 So, it is reasonably safe to assume that all platforms support the
 258 notion of a "path" to uniquely identify a file on the system.  How
 259 that path is really written, though, differs considerably.
 260
 261 Although similar, file path specifications differ between Unix,
 262 Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others.
 263 Unix, for example, is one of the few OSes that has the elegant idea
 264 of a single root directory.
 265
 266 DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with C</>
 267 as path separator, or in their own idiosyncratic ways (such as having
 268 several root directories and various "unrooted" device files such NIL:
 269 and LPT:).
 270
 271 S<Mac OS> uses C<:> as a path separator instead of C</>.
 272
 273 The filesystem may support neither hard links (C<link>) nor
 274 symbolic links (C<symlink>, C<readlink>, C<lstat>).
 275
 276 The filesystem may support neither access timestamp nor change
 277 timestamp (meaning that about the only portable timestamp is the
 278 modification timestamp), or one second granularity of any timestamps
 279 (e.g. the FAT filesystem limits the time granularity to two seconds).
 280
 281 The "inode change timestamp" (the C<-C> filetest) may really be the
 282 "creation timestamp" (which it is not in UNIX).
 283
 284 VOS perl can emulate Unix filenames with C</> as path separator.  The
 285 native pathname characters greater-than, less-than, number-sign, and
 286 percent-sign are always accepted.
 287
 288 S<RISC OS> perl can emulate Unix filenames with C</> as path
 289 separator, or go native and use C<.> for path separator and C<:> to
 290 signal filesystems and disk names.
 291
 292 Don't assume UNIX filesystem access semantics: that read, write,
 293 and execute are all the permissions there are, and even if they exist,
 294 that their semantics (for example what do r, w, and x mean on
 295 a directory) are the UNIX ones.  The various UNIX/POSIX compatibility
 296 layers usually try to make interfaces like chmod() work, but sometimes
 297 there simply is no good mapping.
 298
 299 If all this is intimidating, have no (well, maybe only a little)
 300 fear.  There are modules that can help.  The File::Spec modules
 301 provide methods to do the Right Thing on whatever platform happens
 302 to be running the program.
 303
 304     use File::Spec::Functions;
 305     chdir(updir());        # go up one directory
 306     $file = catfile(curdir(), 'temp', 'file.txt');
 307     # on Unix and Win32, './temp/file.txt'
 308     # on Mac OS, ':temp:file.txt'
 309     # on VMS, '[.temp]file.txt'
 310
 311 File::Spec is available in the standard distribution as of version
 312 5.004_05.  File::Spec::Functions is only in File::Spec 0.7 and later,
 313 and some versions of perl come with version 0.6.  If File::Spec
 314 is not updated to 0.7 or later, you must use the object-oriented
 315 interface from File::Spec (or upgrade File::Spec).
 316
 317 In general, production code should not have file paths hardcoded.
 318 Making them user-supplied or read from a configuration file is
 319 better, keeping in mind that file path syntax varies on different
 320 machines.
 321
 322 This is especially noticeable in scripts like Makefiles and test suites,
 323 which often assume C</> as a path separator for subdirectories.
 324
 325 Also of use is File::Basename from the standard distribution, which
 326 splits a pathname into pieces (base filename, full path to directory,
 327 and file suffix).
 328
 329 Even when on a single platform (if you can call Unix a single platform),
 330 remember not to count on the existence or the contents of particular
 331 system-specific files or directories, like F</etc/passwd>,
 332 F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>.  For
 333 example, F</etc/passwd> may exist but not contain the encrypted
 334 passwords, because the system is using some form of enhanced security.
 335 Or it may not contain all the accounts, because the system is using NIS.
 336 If code does need to rely on such a file, include a description of the
 337 file and its format in the code's documentation, then make it easy for
 338 the user to override the default location of the file.
 339
 340 Don't assume a text file will end with a newline.  They should,
 341 but people forget.
 342
 343 Do not have two files or directories of the same name with different
 344 case, like F<test.pl> and F<Test.pl>, as many platforms have
 345 case-insensitive (or at least case-forgiving) filenames.  Also, try
 346 not to have non-word characters (except for C<.>) in the names, and
 347 keep them to the 8.3 convention, for maximum portability, onerous a
 348 burden though this may appear.
 349
 350 Likewise, when using the AutoSplit module, try to keep your functions to
 351 8.3 naming and case-insensitive conventions; or, at the least,
 352 make it so the resulting files have a unique (case-insensitively)
 353 first 8 characters.
 354
 355 Whitespace in filenames is tolerated on most systems, but not all,
 356 and even on systems where it might be tolerated, some utilities
 357 might become confused by such whitespace.
 358
 359 Many systems (DOS, VMS) cannot have more than one C<.> in their filenames.
 360
 361 Don't assume C<< > >> won't be the first character of a filename.
 362 Always use C<< < >> explicitly to open a file for reading, or even
 363 better, use the three-arg version of open, unless you want the user to
 364 be able to specify a pipe open.
 365
 366     open(FILE, '<', $existing_file) or die $!;
 367
 368 If filenames might use strange characters, it is safest to open it
 369 with C<sysopen> instead of C<open>.  C<open> is magic and can
 370 translate characters like C<< > >>, C<< < >>, and C<|>, which may
 371 be the wrong thing to do.  (Sometimes, though, it's the right thing.)
 372 Three-arg open can also help protect against this translation in cases
 373 where it is undesirable.
 374
 375 Don't use C<:> as a part of a filename since many systems use that for
 376 their own semantics (MacOS Classic for separating pathname components,
 377 many networking schemes and utilities for separating the nodename and
 378 the pathname, and so on).  For the same reasons, avoid C<@>, C<;> and
 379 C<|>.
 380
 381 Don't assume that in pathnames you can collapse two leading slashes
 382 C<//> into one: some networking and clustering filesystems have special
 383 semantics for that.  Let the operating system to sort it out.
 384
 385 The I<portable filename characters> as defined by ANSI C are
 386
 387  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
 388  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
 389  0 1 2 3 4 5 6 7 8 9
 390  . _ -
 391
 392 and the "-" shouldn't be the first character.  If you want to be
 393 hypercorrect, stay case-insensitive and within the 8.3 naming
 394 convention (all the files and directories have to be unique within one
 395 directory if their names are lowercased and truncated to eight
 396 characters before the C<.>, if any, and to three characters after the
 397 C<.>, if any).  (And do not use C<.>s in directory names.)
 398
 399 =head2 System Interaction
 400
 401 Not all platforms provide a command line.  These are usually platforms
 402 that rely primarily on a Graphical User Interface (GUI) for user
 403 interaction.  A program requiring a command line interface might
 404 not work everywhere.  This is probably for the user of the program
 405 to deal with, so don't stay up late worrying about it.
 406
 407 Some platforms can't delete or rename files held open by the system.
 408 Remember to C<close> files when you are done with them.  Don't
 409 C<unlink> or C<rename> an open file.  Don't C<tie> or C<open> a
 410 file already tied or opened; C<untie> or C<close> it first.
 411
 412 Don't open the same file more than once at a time for writing, as some
 413 operating systems put mandatory locks on such files.
 414
 415 Don't assume that write/modify permission on a directory gives the
 416 right to add or delete files/directories in that directory.  That is
 417 filesystem specific: in some filesystems you need write/modify
 418 permission also (or even just) in the file/directory itself.  In some
 419 filesystems (AFS, DFS) the permission to add/delete directory entries
 420 is a completely separate permission.
 421
 422 Don't assume that a single C<unlink> completely gets rid of the file:
 423 some filesystems (most notably the ones in VMS) have versioned
 424 filesystems, and unlink() removes only the most recent one (it doesn't
 425 remove all the versions because by default the native tools on those
 426 platforms remove just the most recent version, too).  The portable
 427 idiom to remove all the versions of a file is
 428
 429     1 while unlink "file";
 430
 431 This will terminate if the file is undeleteable for some reason
 432 (protected, not there, and so on).
 433
 434 Don't count on a specific environment variable existing in C<%ENV>.
 435 Don't count on C<%ENV> entries being case-sensitive, or even
 436 case-preserving.  Don't try to clear %ENV by saying C<%ENV = ();>, or,
 437 if you really have to, make it conditional on C<$^O ne 'VMS'> since in
 438 VMS the C<%ENV> table is much more than a per-process key-value string
 439 table.
 440
 441 Don't count on signals or C<%SIG> for anything.
 442
 443 Don't count on filename globbing.  Use C<opendir>, C<readdir>, and
 444 C<closedir> instead.
 445
 446 Don't count on per-program environment variables, or per-program current
 447 directories.
 448
 449 Don't count on specific values of C<$!>.
 450
 451 =head2 Command names versus file pathnames
 452
 453 Don't assume that the name used to invoke a command or program with
 454 C<system> or C<exec> can also be used to test for the existence of the
 455 file that holds the executable code for that command or program.
 456 First, many operating systems have "internal" commands that are
 457 built-in to the OS and while these commands can be invoked, there is
 458 no corresponding file.  Second, some operating systems (Cygwin, DJGPP,
 459 OS/2, and VOS) have required suffixes for executable files; these
 460 suffixes are generally permitted on the command name but are not
 461 required.  Thus, a command like "perl" might exist in a file named
 462 "perl", "perl.exe", or "perl.pm", depending on the operating system.
 463 The variable "_exe" in the Config module holds the executable suffix,
 464 if any.  Third, VMS files always end in a version number, which comes
 465 after the executable suffix.
 466
 467 To convert $^X to a file pathname, taking account of the requirements
 468 of the various operating system possibilities, say:
 469   use Config;
 470   use File::Spec;
 471   $thisperl = $^X;
 472   $thisperl .= $Config{_exe} unless $thisperl ~= m/$Config{_exe}([;\d]*)$/i;
 473
 474 To convert $Config{perlpath} to a file pathname, say:
 475
 476   use Config;
 477   use File::Spec;
 478   $thisperl = File::Spec->canonpath($Config{perlpath});
 479   $thisperl .= $Config{_exe} unless $thisperl ~= m/$Config{_exe}([;\d]*)$/i;
 480
 481 =head2 Interprocess Communication (IPC)
 482
 483 In general, don't directly access the system in code meant to be
 484 portable.  That means, no C<system>, C<exec>, C<fork>, C<pipe>,
 485 C<``>, C<qx//>, C<open> with a C<|>, nor any of the other things
 486 that makes being a perl hacker worth being.
 487
 488 Commands that launch external processes are generally supported on
 489 most platforms (though many of them do not support any type of
 490 forking).  The problem with using them arises from what you invoke
 491 them on.  External tools are often named differently on different
 492 platforms, may not be available in the same location, might accept
 493 different arguments, can behave differently, and often present their
 494 results in a platform-dependent way.  Thus, you should seldom depend
 495 on them to produce consistent results. (Then again, if you're calling
 496 I<netstat -a>, you probably don't expect it to run on both Unix and CP/M.)
 497
 498 One especially common bit of Perl code is opening a pipe to B<sendmail>:
 499
 500     open(MAIL, '|/usr/lib/sendmail -t')
 501         or die "cannot fork sendmail: $!";
 502
 503 This is fine for systems programming when sendmail is known to be
 504 available.  But it is not fine for many non-Unix systems, and even
 505 some Unix systems that may not have sendmail installed.  If a portable
 506 solution is needed, see the various distributions on CPAN that deal
 507 with it.  Mail::Mailer and Mail::Send in the MailTools distribution are
 508 commonly used, and provide several mailing methods, including mail,
 509 sendmail, and direct SMTP (via Net::SMTP) if a mail transfer agent is
 510 not available.  Mail::Sendmail is a standalone module that provides
 511 simple, platform-independent mailing.
 512
 513 The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
 514 even on all Unix platforms.
 515
 516 Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
 517 bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
 518 both forms just pack the four bytes into network order.  That this
 519 would be equal to the C language C<in_addr> struct (which is what the
 520 socket code internally uses) is not guaranteed.  To be portable use
 521 the routines of the Socket extension, such as C<inet_aton()>,
 522 C<inet_ntoa()>, and C<sockaddr_in()>.
 523
 524 The rule of thumb for portable code is: Do it all in portable Perl, or
 525 use a module (that may internally implement it with platform-specific
 526 code, but expose a common interface).
 527
 528 =head2 External Subroutines (XS)
 529
 530 XS code can usually be made to work with any platform, but dependent
 531 libraries, header files, etc., might not be readily available or
 532 portable, or the XS code itself might be platform-specific, just as Perl
 533 code might be.  If the libraries and headers are portable, then it is
 534 normally reasonable to make sure the XS code is portable, too.
 535
 536 A different type of portability issue arises when writing XS code:
 537 availability of a C compiler on the end-user's system.  C brings
 538 with it its own portability issues, and writing XS code will expose
 539 you to some of those.  Writing purely in Perl is an easier way to
 540 achieve portability.
 541
 542 =head2 Standard Modules
 543
 544 In general, the standard modules work across platforms.  Notable
 545 exceptions are the CPAN module (which currently makes connections to external
 546 programs that may not be available), platform-specific modules (like
 547 ExtUtils::MM_VMS), and DBM modules.
 548
 549 There is no one DBM module available on all platforms.
 550 SDBM_File and the others are generally available on all Unix and DOSish
 551 ports, but not in MacPerl, where only NBDM_File and DB_File are
 552 available.
 553
 554 The good news is that at least some DBM module should be available, and
 555 AnyDBM_File will use whichever module it can find.  Of course, then
 556 the code needs to be fairly strict, dropping to the greatest common
 557 factor (e.g., not exceeding 1K for each record), so that it will
 558 work with any DBM module.  See L<AnyDBM_File> for more details.
 559
 560 =head2 Time and Date
 561
 562 The system's notion of time of day and calendar date is controlled in
 563 widely different ways.  Don't assume the timezone is stored in C<$ENV{TZ}>,
 564 and even if it is, don't assume that you can control the timezone through
 565 that variable.
 566
 567 Don't assume that the epoch starts at 00:00:00, January 1, 1970,
 568 because that is OS- and implementation-specific.  It is better to store a date
 569 in an unambiguous representation.  The ISO-8601 standard defines
 570 "YYYY-MM-DD" as the date format.  A text representation (like "1987-12-18")
 571 can be easily converted into an OS-specific value using a module like
 572 Date::Parse.  An array of values, such as those returned by
 573 C<localtime>, can be converted to an OS-specific representation using
 574 Time::Local.
 575
 576 When calculating specific times, such as for tests in time or date modules,
 577 it may be appropriate to calculate an offset for the epoch.
 578
 579     require Time::Local;
 580     $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);
 581
 582 The value for C<$offset> in Unix will be C<0>, but in Mac OS will be
 583 some large number.  C<$offset> can then be added to a Unix time value
 584 to get what should be the proper value on any system.
 585
 586 =head2 Character sets and character encoding
 587
 588 Assume very little about character sets.
 589
 590 Assume nothing about numerical values (C<ord>, C<chr>) of characters.
 591 Do not use explicit code point ranges (like \xHH-\xHH); use for
 592 example symbolic character classes like C<[:print:]>.
 593
 594 Do not assume that the alphabetic characters are encoded contiguously
 595 (in the numeric sense).  There may be gaps.
 596
 597 Do not assume anything about the ordering of the characters.
 598 The lowercase letters may come before or after the uppercase letters;
 599 the lowercase and uppercase may be interlaced so that both `a' and `A'
 600 come before `b'; the accented and other international characters may
 601 be interlaced so that E<auml> comes before `b'.
 602
 603 =head2 Internationalisation
 604
 605 If you may assume POSIX (a rather large assumption), you may read
 606 more about the POSIX locale system from L<perllocale>.  The locale
 607 system at least attempts to make things a little bit more portable,
 608 or at least more convenient and native-friendly for non-English
 609 users.  The system affects character sets and encoding, and date
 610 and time formatting--amongst other things.
 611
 612 =head2 System Resources
 613
 614 If your code is destined for systems with severely constrained (or
 615 missing!) virtual memory systems then you want to be I<especially> mindful
 616 of avoiding wasteful constructs such as:
 617
 618     # NOTE: this is no longer "bad" in perl5.005
 619     for (0..10000000) {}                       # bad
 620     for (my $x = 0; $x <= 10000000; ++$x) {}   # good
 621
 622     @lines = <VERY_LARGE_FILE>;                # bad
 623
 624     while (<FILE>) {$file .= $_}               # sometimes bad
 625     $file = join('', <FILE>);                  # better
 626
 627 The last two constructs may appear unintuitive to most people.  The
 628 first repeatedly grows a string, whereas the second allocates a
 629 large chunk of memory in one go.  On some systems, the second is
 630 more efficient that the first.
 631
 632 =head2 Security
 633
 634 Most multi-user platforms provide basic levels of security, usually
 635 implemented at the filesystem level.  Some, however, do
 636 not-- unfortunately.  Thus the notion of user id, or "home" directory,
 637 or even the state of being logged-in, may be unrecognizable on many
 638 platforms.  If you write programs that are security-conscious, it
 639 is usually best to know what type of system you will be running
 640 under so that you can write code explicitly for that platform (or
 641 class of platforms).
 642
 643 Don't assume the UNIX filesystem access semantics: the operating
 644 system or the filesystem may be using some ACL systems, which are
 645 richer languages than the usual rwx.  Even if the rwx exist,
 646 their semantics might be different.
 647
 648 (From security viewpoint testing for permissions before attempting to
 649 do something is silly anyway: if one tries this, there is potential
 650 for race conditions-- someone or something might change the
 651 permissions between the permissions check and the actual operation.
 652 Just try the operation.)
 653
 654 Don't assume the UNIX user and group semantics: especially, don't
 655 expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
 656 for switching identities (or memberships).
 657
 658 Don't assume set-uid and set-gid semantics. (And even if you do,
 659 think twice: set-uid and set-gid are a known can of security worms.)
 660
 661 =head2 Style
 662
 663 For those times when it is necessary to have platform-specific code,
 664 consider keeping the platform-specific code in one place, making porting
 665 to other platforms easier.  Use the Config module and the special
 666 variable C<$^O> to differentiate platforms, as described in
 667 L<"PLATFORMS">.
 668
 669 Be careful in the tests you supply with your module or programs.
 670 Module code may be fully portable, but its tests might not be.  This
 671 often happens when tests spawn off other processes or call external
 672 programs to aid in the testing, or when (as noted above) the tests
 673 assume certain things about the filesystem and paths.  Be careful
 674 not to depend on a specific output style for errors, such as when
 675 checking C<$!> after a system call.  Some platforms expect a certain
 676 output format, and perl on those platforms may have been adjusted
 677 accordingly.  Most specifically, don't anchor a regex when testing
 678 an error value.
 679
 680 =head1 CPAN Testers
 681
 682 Modules uploaded to CPAN are tested by a variety of volunteers on
 683 different platforms.  These CPAN testers are notified by mail of each
 684 new upload, and reply to the list with PASS, FAIL, NA (not applicable to
 685 this platform), or UNKNOWN (unknown), along with any relevant notations.
 686
 687 The purpose of the testing is twofold: one, to help developers fix any
 688 problems in their code that crop up because of lack of testing on other
 689 platforms; two, to provide users with information about whether
 690 a given module works on a given platform.
 691
 692 =over 4
 693
 694 =item Mailing list: cpan-testers@perl.org
 695
 696 =item Testing results: http://testers.cpan.org/
 697
 698 =back
 699
 700 =head1 PLATFORMS
 701
 702 As of version 5.002, Perl is built with a C<$^O> variable that
 703 indicates the operating system it was built on.  This was implemented
 704 to help speed up code that would otherwise have to C<use Config>
 705 and use the value of C<$Config{osname}>.  Of course, to get more
 706 detailed information about the system, looking into C<%Config> is
 707 certainly recommended.
 708
 709 C<%Config> cannot always be trusted, however, because it was built
 710 at compile time.  If perl was built in one place, then transferred
 711 elsewhere, some values may be wrong.  The values may even have been
 712 edited after the fact.
 713
 714 =head2 Unix
 715
 716 Perl works on a bewildering variety of Unix and Unix-like platforms (see
 717 e.g. most of the files in the F<hints/> directory in the source code kit).
 718 On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
 719 too) is determined either by lowercasing and stripping punctuation from the
 720 first field of the string returned by typing C<uname -a> (or a similar command)
 721 at the shell prompt or by testing the file system for the presence of
 722 uniquely named files such as a kernel or header file.  Here, for example,
 723 are a few of the more popular Unix flavors:
 724
 725     uname         $^O        $Config{'archname'}
 726     --------------------------------------------
 727     AIX           aix        aix
 728     BSD/OS        bsdos      i386-bsdos
 729     Darwin        darwin     darwin
 730     dgux          dgux       AViiON-dgux
 731     DYNIX/ptx     dynixptx   i386-dynixptx
 732     FreeBSD       freebsd    freebsd-i386
 733     Linux         linux      arm-linux
 734     Linux         linux      i386-linux
 735     Linux         linux      i586-linux
 736     Linux         linux      ppc-linux
 737     HP-UX         hpux       PA-RISC1.1
 738     IRIX          irix       irix
 739     Mac OS X      darwin     darwin
 740     MachTen PPC   machten    powerpc-machten
 741     NeXT 3        next       next-fat
 742     NeXT 4        next       OPENSTEP-Mach
 743     openbsd       openbsd    i386-openbsd
 744     OSF1          dec_osf    alpha-dec_osf
 745     reliantunix-n svr4       RM400-svr4
 746     SCO_SV        sco_sv     i386-sco_sv
 747     SINIX-N       svr4       RM400-svr4
 748     sn4609        unicos     CRAY_C90-unicos
 749     sn6521        unicosmk   t3e-unicosmk
 750     sn9617        unicos     CRAY_J90-unicos
 751     SunOS         solaris    sun4-solaris
 752     SunOS         solaris    i86pc-solaris
 753     SunOS4        sunos      sun4-sunos
 754
 755 Because the value of C<$Config{archname}> may depend on the
 756 hardware architecture, it can vary more than the value of C<$^O>.
 757
 758 =head2 DOS and Derivatives
 759
 760 Perl has long been ported to Intel-style microcomputers running under
 761 systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
 762 bring yourself to mention (except for Windows CE, if you count that).
 763 Users familiar with I<COMMAND.COM> or I<CMD.EXE> style shells should
 764 be aware that each of these file specifications may have subtle
 765 differences:
 766
 767     $filespec0 = "c:/foo/bar/file.txt";
 768     $filespec1 = "c:\\foo\\bar\\file.txt";
 769     $filespec2 = 'c:\foo\bar\file.txt';
 770     $filespec3 = 'c:\\foo\\bar\\file.txt';
 771
 772 System calls accept either C</> or C<\> as the path separator.
 773 However, many command-line utilities of DOS vintage treat C</> as
 774 the option prefix, so may get confused by filenames containing C</>.
 775 Aside from calling any external programs, C</> will work just fine,
 776 and probably better, as it is more consistent with popular usage,
 777 and avoids the problem of remembering what to backwhack and what
 778 not to.
 779
 780 The DOS FAT filesystem can accommodate only "8.3" style filenames.  Under
 781 the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
 782 filesystems you may have to be careful about case returned with functions
 783 like C<readdir> or used with functions like C<open> or C<opendir>.
 784
 785 DOS also treats several filenames as special, such as AUX, PRN,
 786 NUL, CON, COM1, LPT1, LPT2, etc.  Unfortunately, sometimes these
 787 filenames won't even work if you include an explicit directory
 788 prefix.  It is best to avoid such filenames, if you want your code
 789 to be portable to DOS and its derivatives.  It's hard to know what
 790 these all are, unfortunately.
 791
 792 Users of these operating systems may also wish to make use of
 793 scripts such as I<pl2bat.bat> or I<pl2cmd> to
 794 put wrappers around your scripts.
 795
 796 Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
 797 and writing to files (see L<"Newlines">).  C<binmode(FILEHANDLE)>
 798 will keep C<\n> translated as C<\012> for that filehandle.  Since it is a
 799 no-op on other systems, C<binmode> should be used for cross-platform code
 800 that deals with binary data.  That's assuming you realize in advance
 801 that your data is in binary.  General-purpose programs should
 802 often assume nothing about their data.
 803
 804 The C<$^O> variable and the C<$Config{archname}> values for various
 805 DOSish perls are as follows:
 806
 807      OS            $^O      $Config{archname}   ID    Version
 808      --------------------------------------------------------
 809      MS-DOS        dos        ?
 810      PC-DOS        dos        ?
 811      OS/2          os2        ?
 812      Windows 3.1   ?          ?                 0      3 01
 813      Windows 95    MSWin32    MSWin32-x86       1      4 00
 814      Windows 98    MSWin32    MSWin32-x86       1      4 10
 815      Windows ME    MSWin32    MSWin32-x86       1      ?
 816      Windows NT    MSWin32    MSWin32-x86       2      4 xx
 817      Windows NT    MSWin32    MSWin32-ALPHA     2      4 xx
 818      Windows NT    MSWin32    MSWin32-ppc       2      4 xx
 819      Windows 2000  MSWin32    MSWin32-x86       2      5 xx
 820      Windows XP    MSWin32    MSWin32-x86       2      ?
 821      Windows CE    MSWin32    ?                 3
 822      Cygwin        cygwin     ?
 823
 824 The various MSWin32 Perl's can distinguish the OS they are running on
 825 via the value of the fifth element of the list returned from
 826 Win32::GetOSVersion().  For example:
 827
 828     if ($^O eq 'MSWin32') {
 829         my @os_version_info = Win32::GetOSVersion();
 830         print +('3.1','95','NT')[$os_version_info[4]],"\n";
 831     }
 832
 833 Also see:
 834
 835 =over 4
 836
 837 =item *
 838
 839 The djgpp environment for DOS, http://www.delorie.com/djgpp/
 840 and L<perldos>.
 841
 842 =item *
 843
 844 The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
 845 http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or
 846 ftp://hobbes.nmsu.edu/pub/os2/dev/emx/  Also L<perlos2>.
 847
 848 =item *
 849
 850 Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
 851 in L<perlcygwin>.
 852
 853 =item *
 854
 855 The C<Win32::*> modules in L<Win32>.
 856
 857 =item *
 858
 859 The ActiveState Pages, http://www.activestate.com/
 860
 861 =item *
 862
 863 The Cygwin environment for Win32; F<README.cygwin> (installed
 864 as L<perlcygwin>), http://www.cygwin.com/
 865
 866 =item *
 867
 868 The U/WIN environment for Win32,
 869 http://www.research.att.com/sw/tools/uwin/
 870
 871 =item *
 872
 873 Build instructions for OS/2, L<perlos2>
 874
 875 =back
 876
 877 =head2 S<Mac OS>
 878
 879 Any module requiring XS compilation is right out for most people, because
 880 MacPerl is built using non-free (and non-cheap!) compilers.  Some XS
 881 modules that can work with MacPerl are built and distributed in binary
 882 form on CPAN.
 883
 884 Directories are specified as:
 885
 886     volume:folder:file              for absolute pathnames
 887     volume:folder:                  for absolute pathnames
 888     :folder:file                    for relative pathnames
 889     :folder:                        for relative pathnames
 890     :file                           for relative pathnames
 891     file                            for relative pathnames
 892
 893 Files are stored in the directory in alphabetical order.  Filenames are
 894 limited to 31 characters, and may include any character except for
 895 null and C<:>, which is reserved as the path separator.
 896
 897 Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the
 898 Mac::Files module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>.
 899
 900 In the MacPerl application, you can't run a program from the command line;
 901 programs that expect C<@ARGV> to be populated can be edited with something
 902 like the following, which brings up a dialog box asking for the command
 903 line arguments.
 904
 905     if (!@ARGV) {
 906         @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
 907     }
 908
 909 A MacPerl script saved as a "droplet" will populate C<@ARGV> with the full
 910 pathnames of the files dropped onto the script.
 911
 912 Mac users can run programs under a type of command line interface
 913 under MPW (Macintosh Programmer's Workshop, a free development
 914 environment from Apple).  MacPerl was first introduced as an MPW
 915 tool, and MPW can be used like a shell:
 916
 917     perl myscript.plx some arguments
 918
 919 ToolServer is another app from Apple that provides access to MPW tools
 920 from MPW and the MacPerl app, which allows MacPerl programs to use
 921 C<system>, backticks, and piped C<open>.
 922
 923 "S<Mac OS>" is the proper name for the operating system, but the value
 924 in C<$^O> is "MacOS".  To determine architecture, version, or whether
 925 the application or MPW tool version is running, check:
 926
 927     $is_app    = $MacPerl::Version =~ /App/;
 928     $is_tool   = $MacPerl::Version =~ /MPW/;
 929     ($version) = $MacPerl::Version =~ /^(\S+)/;
 930     $is_ppc    = $MacPerl::Architecture eq 'MacPPC';
 931     $is_68k    = $MacPerl::Architecture eq 'Mac68K';
 932
 933 S<Mac OS X>, based on NeXT's OpenStep OS, runs MacPerl natively, under the
 934 "Classic" environment.  There is no "Carbon" version of MacPerl to run
 935 under the primary Mac OS X environment.  S<Mac OS X> and its Open Source
 936 version, Darwin, both run Unix perl natively.
 937
 938 Also see:
 939
 940 =over 4
 941
 942 =item *
 943
 944 MacPerl Development, http://dev.macperl.org/ .
 945
 946 =item *
 947
 948 The MacPerl Pages, http://www.macperl.com/ .
 949
 950 =item *
 951
 952 The MacPerl mailing lists, http://lists.perl.org/ .
 953
 954 =back
 955
 956 =head2 VMS
 957
 958 Perl on VMS is discussed in L<perlvms> in the perl distribution.
 959 Perl on VMS can accept either VMS- or Unix-style file
 960 specifications as in either of the following:
 961
 962     $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
 963     $ perl -ne "print if /perl_setup/i" /sys$login/login.com
 964
 965 but not a mixture of both as in:
 966
 967     $ perl -ne "print if /perl_setup/i" sys$login:/login.com
 968     Can't open sys$login:/login.com: file specification syntax error
 969
 970 Interacting with Perl from the Digital Command Language (DCL) shell
 971 often requires a different set of quotation marks than Unix shells do.
 972 For example:
 973
 974     $ perl -e "print ""Hello, world.\n"""
 975     Hello, world.
 976
 977 There are several ways to wrap your perl scripts in DCL F<.COM> files, if
 978 you are so inclined.  For example:
 979
 980     $ write sys$output "Hello from DCL!"
 981     $ if p1 .eqs. ""
 982     $ then perl -x 'f$environment("PROCEDURE")
 983     $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
 984     $ deck/dollars="__END__"
 985     #!/usr/bin/perl
 986
 987     print "Hello from Perl!\n";
 988
 989     __END__
 990     $ endif
 991
 992 Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
 993 perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
 994
 995 Filenames are in the format "name.extension;version".  The maximum
 996 length for filenames is 39 characters, and the maximum length for
 997 extensions is also 39 characters.  Version is a number from 1 to
 998 32767.  Valid characters are C</[A-Z0-9$_-]/>.
 999
1000 VMS's RMS filesystem is case-insensitive and does not preserve case.
1001 C<readdir> returns lowercased filenames, but specifying a file for
1002 opening remains case-insensitive.  Files without extensions have a
1003 trailing period on them, so doing a C<readdir> with a file named F<A.;5>
1004 will return F<a.> (though that file could be opened with
1005 C<open(FH, 'A')>).
1006
1007 RMS had an eight level limit on directory depths from any rooted logical
1008 (allowing 16 levels overall) prior to VMS 7.2.  Hence
1009 C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a valid directory specification but
1010 C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is not.  F<Makefile.PL> authors might
1011 have to take this into account, but at least they can refer to the former
1012 as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
1013
1014 The VMS::Filespec module, which gets installed as part of the build
1015 process on VMS, is a pure Perl module that can easily be installed on
1016 non-VMS platforms and can be helpful for conversions to and from RMS
1017 native formats.
1018
1019 What C<\n> represents depends on the type of file opened.  It usually
1020 represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>,
1021 C<\000>, C<\040>, or nothing depending on the file organiztion and
1022 record format.  The VMS::Stdio module provides access to the
1023 special fopen() requirements of files with unusual attributes on VMS.
1024
1025 TCP/IP stacks are optional on VMS, so socket routines might not be
1026 implemented.  UDP sockets may not be supported.
1027
1028 The value of C<$^O> on OpenVMS is "VMS".  To determine the architecture
1029 that you are running on without resorting to loading all of C<%Config>
1030 you can examine the content of the C<@INC> array like so:
1031
1032     if (grep(/VMS_AXP/, @INC)) {
1033         print "I'm on Alpha!\n";
1034
1035     } elsif (grep(/VMS_VAX/, @INC)) {
1036         print "I'm on VAX!\n";
1037
1038     } else {
1039         print "I'm not so sure about where $^O is...\n";
1040     }
1041
1042 On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
1043 logical name.  Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
1044 calls to C<localtime> are adjusted to count offsets from
1045 01-JAN-1970 00:00:00.00, just like Unix.
1046
1047 Also see:
1048
1049 =over 4
1050
1051 =item *
1052
1053 F<README.vms> (installed as L<README_vms>), L<perlvms>
1054
1055 =item *
1056
1057 vmsperl list, majordomo@perl.org
1058
1059 (Put the words C<subscribe vmsperl> in message body.)
1060
1061 =item *
1062
1063 vmsperl on the web, http://www.sidhe.org/vmsperl/index.html
1064
1065 =back
1066
1067 =head2 VOS
1068
1069 Perl on VOS is discussed in F<README.vos> in the perl distribution
1070 (installed as L<perlvos>).  Perl on VOS can accept either VOS- or
1071 Unix-style file specifications as in either of the following:
1072
1073     C<< $ perl -ne "print if /perl_setup/i" >system>notices >>
1074     C<< $ perl -ne "print if /perl_setup/i" /system/notices >>
1075
1076 or even a mixture of both as in:
1077
1078     C<< $ perl -ne "print if /perl_setup/i" >system/notices >>
1079
1080 Even though VOS allows the slash character to appear in object
1081 names, because the VOS port of Perl interprets it as a pathname
1082 delimiting character, VOS files, directories, or links whose names
1083 contain a slash character cannot be processed.  Such files must be
1084 renamed before they can be processed by Perl.  Note that VOS limits
1085 file names to 32 or fewer characters.
1086
1087 Perl on VOS can be built using two different compilers and two different
1088 versions of the POSIX runtime.  The recommended method for building full
1089 Perl is with the GNU C compiler and the generally-available version of
1090 VOS POSIX support.  See F<README.vos> (installed as L<perlvos>) for
1091 restrictions that apply when Perl is built using the VOS Standard C
1092 compiler or the alpha version of VOS POSIX support.
1093
1094 The value of C<$^O> on VOS is "VOS".  To determine the architecture that
1095 you are running on without resorting to loading all of C<%Config> you
1096 can examine the content of the @INC array like so:
1097
1098     if ($^O =~ /VOS/) {
1099         print "I'm on a Stratus box!\n";
1100     } else {
1101         print "I'm not on a Stratus box!\n";
1102         die;
1103     }
1104
1105     if (grep(/860/, @INC)) {
1106         print "This box is a Stratus XA/R!\n";
1107
1108     } elsif (grep(/7100/, @INC)) {
1109         print "This box is a Stratus HP 7100 or 8xxx!\n";
1110
1111     } elsif (grep(/8000/, @INC)) {
1112         print "This box is a Stratus HP 8xxx!\n";
1113
1114     } else {
1115         print "This box is a Stratus 68K!\n";
1116     }
1117
1118 Also see:
1119
1120 =over 4
1121
1122 =item *
1123
1124 F<README.vos> (installed as L<perlvos>)
1125
1126 =item *
1127
1128 The VOS mailing list.
1129
1130 There is no specific mailing list for Perl on VOS.  You can post
1131 comments to the comp.sys.stratus newsgroup, or subscribe to the general
1132 Stratus mailing list.  Send a letter with "subscribe Info-Stratus" in
1133 the message body to majordomo@list.stratagy.com.
1134
1135 =item *
1136
1137 VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html
1138
1139 =back
1140
1141 =head2 EBCDIC Platforms
1142
1143 Recent versions of Perl have been ported to platforms such as OS/400 on
1144 AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
1145 Mainframes.  Such computers use EBCDIC character sets internally (usually
1146 Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
1147 systems).  On the mainframe perl currently works under the "Unix system
1148 services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
1149 the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
1150 See L<perlos390> for details.
1151
1152 As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
1153 sub-systems do not support the C<#!> shebang trick for script invocation.
1154 Hence, on OS/390 and VM/ESA perl scripts can be executed with a header
1155 similar to the following simple script:
1156
1157     : # use perl
1158         eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
1159             if 0;
1160     #!/usr/local/bin/perl     # just a comment really
1161
1162     print "Hello from perl!\n";
1163
1164 OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
1165 Calls to C<system> and backticks can use POSIX shell syntax on all
1166 S/390 systems.
1167
1168 On the AS/400, if PERL5 is in your library list, you may need
1169 to wrap your perl scripts in a CL procedure to invoke them like so:
1170
1171     BEGIN
1172       CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1173     ENDPGM
1174
1175 This will invoke the perl script F<hello.pl> in the root of the
1176 QOpenSys file system.  On the AS/400 calls to C<system> or backticks
1177 must use CL syntax.
1178
1179 On these platforms, bear in mind that the EBCDIC character set may have
1180 an effect on what happens with some perl functions (such as C<chr>,
1181 C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
1182 well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
1183 and C<|>, not to mention dealing with socket interfaces to ASCII computers
1184 (see L<"Newlines">).
1185
1186 Fortunately, most web servers for the mainframe will correctly
1187 translate the C<\n> in the following statement to its ASCII equivalent
1188 (C<\r> is the same under both Unix and OS/390 & VM/ESA):
1189
1190     print "Content-type: text/html\r\n\r\n";
1191
1192 The values of C<$^O> on some of these platforms includes:
1193
1194     uname         $^O        $Config{'archname'}
1195     --------------------------------------------
1196     OS/390        os390      os390
1197     OS400         os400      os400
1198     POSIX-BC      posix-bc   BS2000-posix-bc
1199     VM/ESA        vmesa      vmesa
1200
1201 Some simple tricks for determining if you are running on an EBCDIC
1202 platform could include any of the following (perhaps all):
1203
1204     if ("\t" eq "\05")   { print "EBCDIC may be spoken here!\n"; }
1205
1206     if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1207
1208     if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1209
1210 One thing you may not want to rely on is the EBCDIC encoding
1211 of punctuation characters since these may differ from code page to code
1212 page (and once your module or script is rumoured to work with EBCDIC,
1213 folks will want it to work with all EBCDIC character sets).
1214
1215 Also see:
1216
1217 =over 4
1218
1219 =item *
1220
1221 *
1222
1223 L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
1224 L<perlebcdic>.
1225
1226 =item *
1227
1228 The perl-mvs@perl.org list is for discussion of porting issues as well as
1229 general usage issues for all EBCDIC Perls.  Send a message body of
1230 "subscribe perl-mvs" to majordomo@perl.org.
1231
1232 =item  *
1233
1234 AS/400 Perl information at
1235 http://as400.rochester.ibm.com/
1236 as well as on CPAN in the F<ports/> directory.
1237
1238 =back
1239
1240 =head2 Acorn RISC OS
1241
1242 Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
1243 Unix, and because Unix filename emulation is turned on by default,
1244 most simple scripts will probably work "out of the box".  The native
1245 filesystem is modular, and individual filesystems are free to be
1246 case-sensitive or insensitive, and are usually case-preserving.  Some
1247 native filesystems have name length limits, which file and directory
1248 names are silently truncated to fit.  Scripts should be aware that the
1249 standard filesystem currently has a name length limit of B<10>
1250 characters, with up to 77 items in a directory, but other filesystems
1251 may not impose such limitations.
1252
1253 Native filenames are of the form
1254
1255     Filesystem#Special_Field::DiskName.$.Directory.Directory.File
1256
1257 where
1258
1259     Special_Field is not usually present, but may contain . and $ .
1260     Filesystem =~ m|[A-Za-z0-9_]|
1261     DsicName   =~ m|[A-Za-z0-9_/]|
1262     $ represents the root directory
1263     . is the path separator
1264     @ is the current directory (per filesystem but machine global)
1265     ^ is the parent directory
1266     Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1267
1268 The default filename translation is roughly C<tr|/.|./|;>
1269
1270 Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
1271 the second stage of C<$> interpolation in regular expressions will fall
1272 foul of the C<$.> if scripts are not careful.
1273
1274 Logical paths specified by system variables containing comma-separated
1275 search lists are also allowed; hence C<System:Modules> is a valid
1276 filename, and the filesystem will prefix C<Modules> with each section of
1277 C<System$Path> until a name is made that points to an object on disk.
1278 Writing to a new file C<System:Modules> would be allowed only if
1279 C<System$Path> contains a single item list.  The filesystem will also
1280 expand system variables in filenames if enclosed in angle brackets, so
1281 C<< <System$Dir>.Modules >> would look for the file
1282 S<C<$ENV{'System$Dir'} . 'Modules'>>.  The obvious implication of this is
1283 that B<fully qualified filenames can start with C<< <> >>> and should
1284 be protected when C<open> is used for input.
1285
1286 Because C<.> was in use as a directory separator and filenames could not
1287 be assumed to be unique after 10 characters, Acorn implemented the C
1288 compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
1289 filenames specified in source code and store the respective files in
1290 subdirectories named after the suffix.  Hence files are translated:
1291
1292     foo.h           h.foo
1293     C:foo.h         C:h.foo        (logical path variable)
1294     sys/os.h        sys.h.os       (C compiler groks Unix-speak)
1295     10charname.c    c.10charname
1296     10charname.o    o.10charname
1297     11charname_.c   c.11charname   (assuming filesystem truncates at 10)
1298
1299 The Unix emulation library's translation of filenames to native assumes
1300 that this sort of translation is required, and it allows a user-defined list
1301 of known suffixes that it will transpose in this fashion.  This may
1302 seem transparent, but consider that with these rules C<foo/bar/baz.h>
1303 and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
1304 C<glob> cannot and do not attempt to emulate the reverse mapping.  Other
1305 C<.>'s in filenames are translated to C</>.
1306
1307 As implied above, the environment accessed through C<%ENV> is global, and
1308 the convention is that program specific environment variables are of the
1309 form C<Program$Name>.  Each filesystem maintains a current directory,
1310 and the current filesystem's current directory is the B<global> current
1311 directory.  Consequently, sociable programs don't change the current
1312 directory but rely on full pathnames, and programs (and Makefiles) cannot
1313 assume that they can spawn a child process which can change the current
1314 directory without affecting its parent (and everyone else for that
1315 matter).
1316
1317 Because native operating system filehandles are global and are currently
1318 allocated down from 255, with 0 being a reserved value, the Unix emulation
1319 library emulates Unix filehandles.  Consequently, you can't rely on
1320 passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
1321
1322 The desire of users to express filenames of the form
1323 C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
1324 too: C<``> command output capture has to perform a guessing game.  It
1325 assumes that a string C<< <[^<>]+\$[^<>]> >> is a
1326 reference to an environment variable, whereas anything else involving
1327 C<< < >> or C<< > >> is redirection, and generally manages to be 99%
1328 right.  Of course, the problem remains that scripts cannot rely on any
1329 Unix tools being available, or that any tools found have Unix-like command
1330 line arguments.
1331
1332 Extensions and XS are, in theory, buildable by anyone using free
1333 tools.  In practice, many don't, as users of the Acorn platform are
1334 used to binary distributions.  MakeMaker does run, but no available
1335 make currently copes with MakeMaker's makefiles; even if and when
1336 this should be fixed, the lack of a Unix-like shell will cause
1337 problems with makefile rules, especially lines of the form C<cd
1338 sdbm && make all>, and anything using quoting.
1339
1340 "S<RISC OS>" is the proper name for the operating system, but the value
1341 in C<$^O> is "riscos" (because we don't like shouting).
1342
1343 =head2 Other perls
1344
1345 Perl has been ported to many platforms that do not fit into any of
1346 the categories listed above.  Some, such as AmigaOS, Atari MiNT,
1347 BeOS, HP MPE/iX, QNX, Plan 9, and VOS, have been well-integrated
1348 into the standard Perl source code kit.  You may need to see the
1349 F<ports/> directory on CPAN for information, and possibly binaries,
1350 for the likes of: aos, Atari ST, lynxos, riscos, Novell Netware,
1351 Tandem Guardian, I<etc.>  (Yes, we know that some of these OSes may
1352 fall under the Unix category, but we are not a standards body.)
1353
1354 Some approximate operating system names and their C<$^O> values
1355 in the "OTHER" category include:
1356
1357     OS            $^O        $Config{'archname'}
1358     ------------------------------------------
1359     Amiga DOS     amigaos    m68k-amigos
1360     MPE/iX        mpeix      PA-RISC1.1
1361
1362 See also:
1363
1364 =over 4
1365
1366 =item *
1367
1368 Amiga, F<README.amiga> (installed as L<perlamiga>).
1369
1370 =item *
1371
1372 Atari, F<README.mint> and Guido Flohr's web page
1373 http://stud.uni-sb.de/~gufl0000/
1374
1375 =item *
1376
1377 Be OS, F<README.beos>
1378
1379 =item *
1380
1381 HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
1382 http://www.bixby.org/mark/perlix.html
1383
1384 =item *
1385
1386 A free perl5-based PERL.NLM for Novell Netware is available in
1387 precompiled binary and source code form from http://www.novell.com/
1388 as well as from CPAN.
1389
1390 =item  *
1391
1392 Plan 9, F<README.plan9>
1393
1394 =back
1395
1396 =head1 FUNCTION IMPLEMENTATIONS
1397
1398 Listed below are functions that are either completely unimplemented
1399 or else have been implemented differently on various platforms.
1400 Following each description will be, in parentheses, a list of
1401 platforms that the description applies to.
1402
1403 The list may well be incomplete, or even wrong in some places.  When
1404 in doubt, consult the platform-specific README files in the Perl
1405 source distribution, and any other documentation resources accompanying
1406 a given port.
1407
1408 Be aware, moreover, that even among Unix-ish systems there are variations.
1409
1410 For many functions, you can also query C<%Config>, exported by
1411 default from the Config module.  For example, to check whether the
1412 platform has the C<lstat> call, check C<$Config{d_lstat}>.  See
1413 L<Config> for a full description of available variables.
1414
1415 =head2 Alphabetical Listing of Perl Functions
1416
1417 =over 8
1418
1419 =item -X FILEHANDLE
1420
1421 =item -X EXPR
1422
1423 =item -X
1424
1425 C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
1426 and applications are executable, and there are no uid/gid
1427 considerations.  C<-o> is not supported.  (S<Mac OS>)
1428
1429 C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
1430 which may not reflect UIC-based file protections.  (VMS)
1431
1432 C<-s> returns the size of the data fork, not the total size of data fork
1433 plus resource fork.  (S<Mac OS>).
1434
1435 C<-s> by name on an open file will return the space reserved on disk,
1436 rather than the current extent.  C<-s> on an open filehandle returns the
1437 current size.  (S<RISC OS>)
1438
1439 C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
1440 C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1441
1442 C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
1443 (S<Mac OS>)
1444
1445 C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
1446 (Win32, VMS, S<RISC OS>)
1447
1448 C<-d> is true if passed a device spec without an explicit directory.
1449 (VMS)
1450
1451 C<-T> and C<-B> are implemented, but might misclassify Mac text files
1452 with foreign characters; this is the case will all platforms, but may
1453 affect S<Mac OS> often.  (S<Mac OS>)
1454
1455 C<-x> (or C<-X>) determine if a file ends in one of the executable
1456 suffixes.  C<-S> is meaningless.  (Win32)
1457
1458 C<-x> (or C<-X>) determine if a file has an executable file type.
1459 (S<RISC OS>)
1460
1461 =item alarm SECONDS
1462
1463 =item alarm
1464
1465 Not implemented. (Win32)
1466
1467 =item binmode FILEHANDLE
1468
1469 Meaningless.  (S<Mac OS>, S<RISC OS>)
1470
1471 Reopens file and restores pointer; if function fails, underlying
1472 filehandle may be closed, or pointer may be in a different position.
1473 (VMS)
1474
1475 The value returned by C<tell> may be affected after the call, and
1476 the filehandle may be flushed. (Win32)
1477
1478 =item chmod LIST
1479
1480 Only limited meaning.  Disabling/enabling write permission is mapped to
1481 locking/unlocking the file. (S<Mac OS>)
1482
1483 Only good for changing "owner" read-write access, "group", and "other"
1484 bits are meaningless. (Win32)
1485
1486 Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1487
1488 Access permissions are mapped onto VOS access-control list changes. (VOS)
1489
1490 The actual permissions set depend on the value of the C<CYGWIN>
1491 in the SYSTEM environment settings.  (Cygwin)
1492
1493 =item chown LIST
1494
1495 Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS)
1496
1497 Does nothing, but won't fail. (Win32)
1498
1499 =item chroot FILENAME
1500
1501 =item chroot
1502
1503 Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA)
1504
1505 =item crypt PLAINTEXT,SALT
1506
1507 May not be available if library or source was not provided when building
1508 perl. (Win32)
1509
1510 Not implemented. (VOS)
1511
1512 =item dbmclose HASH
1513
1514 Not implemented. (VMS, Plan9, VOS)
1515
1516 =item dbmopen HASH,DBNAME,MODE
1517
1518 Not implemented. (VMS, Plan9, VOS)
1519
1520 =item dump LABEL
1521
1522 Not useful. (S<Mac OS>, S<RISC OS>)
1523
1524 Not implemented. (Win32)
1525
1526 Invokes VMS debugger. (VMS)
1527
1528 =item exec LIST
1529
1530 Not implemented. (S<Mac OS>)
1531
1532 Implemented via Spawn. (VM/ESA)
1533
1534 Does not automatically flush output handles on some platforms.
1535 (SunOS, Solaris, HP-UX)
1536
1537 =item exit EXPR
1538
1539 =item exit
1540
1541 Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
1542 mapping the C<1> to SS$_ABORT (C<44>).  This behavior may be overridden
1543 with the pragma C<use vmsish 'exit'>.  As with the CRTL's exit()
1544 function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
1545 (C<1>); this mapping cannot be overridden.  Any other argument to exit()
1546 is used directly as Perl's exit status. (VMS)
1547
1548 =item fcntl FILEHANDLE,FUNCTION,SCALAR
1549
1550 Not implemented. (Win32, VMS)
1551
1552 =item flock FILEHANDLE,OPERATION
1553
1554 Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
1555
1556 Available only on Windows NT (not on Windows 95). (Win32)
1557
1558 =item fork
1559
1560 Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VOS, VM/ESA)
1561
1562 Emulated using multiple interpreters.  See L<perlfork>.  (Win32)
1563
1564 Does not automatically flush output handles on some platforms.
1565 (SunOS, Solaris, HP-UX)
1566
1567 =item getlogin
1568
1569 Not implemented. (S<Mac OS>, S<RISC OS>)
1570
1571 =item getpgrp PID
1572
1573 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1574
1575 =item getppid
1576
1577 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1578
1579 =item getpriority WHICH,WHO
1580
1581 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
1582
1583 =item getpwnam NAME
1584
1585 Not implemented. (S<Mac OS>, Win32)
1586
1587 Not useful. (S<RISC OS>)
1588
1589 =item getgrnam NAME
1590
1591 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1592
1593 =item getnetbyname NAME
1594
1595 Not implemented. (S<Mac OS>, Win32, Plan9)
1596
1597 =item getpwuid UID
1598
1599 Not implemented. (S<Mac OS>, Win32)
1600
1601 Not useful. (S<RISC OS>)
1602
1603 =item getgrgid GID
1604
1605 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
1606
1607 =item getnetbyaddr ADDR,ADDRTYPE
1608
1609 Not implemented. (S<Mac OS>, Win32, Plan9)
1610
1611 =item getprotobynumber NUMBER
1612
1613 Not implemented. (S<Mac OS>)
1614
1615 =item getservbyport PORT,PROTO
1616
1617 Not implemented. (S<Mac OS>)
1618
1619 =item getpwent
1620
1621 Not implemented. (S<Mac OS>, Win32, VM/ESA)
1622
1623 =item getgrent
1624
1625 Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
1626
1627 =item gethostent
1628
1629 Not implemented. (S<Mac OS>, Win32)
1630
1631 =item getnetent
1632
1633 Not implemented. (S<Mac OS>, Win32, Plan9)
1634
1635 =item getprotoent
1636
1637 Not implemented. (S<Mac OS>, Win32, Plan9)
1638
1639 =item getservent
1640
1641 Not implemented. (Win32, Plan9)
1642
1643 =item sethostent STAYOPEN
1644
1645 Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
1646
1647 =item setnetent STAYOPEN
1648
1649 Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
1650
1651 =item setprotoent STAYOPEN
1652
1653 Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
1654
1655 =item setservent STAYOPEN
1656
1657 Not implemented. (Plan9, Win32, S<RISC OS>)
1658
1659 =item endpwent
1660
1661 Not implemented. (S<Mac OS>, MPE/iX, VM/ESA, Win32)
1662
1663 =item endgrent
1664
1665 Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
1666
1667 =item endhostent
1668
1669 Not implemented. (S<Mac OS>, Win32)
1670
1671 =item endnetent
1672
1673 Not implemented. (S<Mac OS>, Win32, Plan9)
1674
1675 =item endprotoent
1676
1677 Not implemented. (S<Mac OS>, Win32, Plan9)
1678
1679 =item endservent
1680
1681 Not implemented. (Plan9, Win32)
1682
1683 =item getsockopt SOCKET,LEVEL,OPTNAME
1684
1685 Not implemented. (Plan9)
1686
1687 =item glob EXPR
1688
1689 =item glob
1690
1691 This operator is implemented via the File::Glob extension on most
1692 platforms.  See L<File::Glob> for portability information.
1693
1694 =item ioctl FILEHANDLE,FUNCTION,SCALAR
1695
1696 Not implemented. (VMS)
1697
1698 Available only for socket handles, and it does what the ioctlsocket() call
1699 in the Winsock API does. (Win32)
1700
1701 Available only for socket handles. (S<RISC OS>)
1702
1703 =item kill SIGNAL, LIST
1704
1705 C<kill(0, LIST)> is implemented for the sake of taint checking;
1706 use with other signals is unimplemented. (S<Mac OS>)
1707
1708 Not implemented, hence not useful for taint checking. (S<RISC OS>)
1709
1710 C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
1711 a signal to the identified process like it does on Unix platforms.
1712 Instead C<kill($sig, $pid)> terminates the process identified by $pid,
1713 and makes it exit immediately with exit status $sig.  As in Unix, if
1714 $sig is 0 and the specified process exists, it returns true without
1715 actually terminating it. (Win32)
1716
1717 =item link OLDFILE,NEWFILE
1718
1719 Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
1720
1721 Link count not updated because hard links are not quite that hard
1722 (They are sort of half-way between hard and soft links). (AmigaOS)
1723
1724 Hard links are implemented on Win32 (Windows NT and Windows 2000)
1725 under NTFS only.
1726
1727 =item lstat FILEHANDLE
1728
1729 =item lstat EXPR
1730
1731 =item lstat
1732
1733 Not implemented. (VMS, S<RISC OS>)
1734
1735 Return values (especially for device and inode) may be bogus. (Win32)
1736
1737 =item msgctl ID,CMD,ARG
1738
1739 =item msgget KEY,FLAGS
1740
1741 =item msgsnd ID,MSG,FLAGS
1742
1743 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1744
1745 Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS)
1746
1747 =item open FILEHANDLE,EXPR
1748
1749 =item open FILEHANDLE
1750
1751 The C<|> variants are supported only if ToolServer is installed.
1752 (S<Mac OS>)
1753
1754 open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
1755
1756 Opening a process does not automatically flush output handles on some
1757 platforms.  (SunOS, Solaris, HP-UX)
1758
1759 =item pipe READHANDLE,WRITEHANDLE
1760
1761 Very limited functionality. (MiNT)
1762
1763 =item readlink EXPR
1764
1765 =item readlink
1766
1767 Not implemented. (Win32, VMS, S<RISC OS>)
1768
1769 =item select RBITS,WBITS,EBITS,TIMEOUT
1770
1771 Only implemented on sockets. (Win32, VMS)
1772
1773 Only reliable on sockets. (S<RISC OS>)
1774
1775 Note that the C<select FILEHANDLE> form is generally portable.
1776
1777 =item semctl ID,SEMNUM,CMD,ARG
1778
1779 =item semget KEY,NSEMS,FLAGS
1780
1781 =item semop KEY,OPSTRING
1782
1783 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1784
1785 =item setgrent
1786
1787 Not implemented. (S<Mac OS>, MPE/iX, VMS, Win32, VMS, S<RISC OS>)
1788
1789 =item setpgrp PID,PGRP
1790
1791 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1792
1793 =item setpriority WHICH,WHO,PRIORITY
1794
1795 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1796
1797 =item setpwent
1798
1799 Not implemented. (S<Mac OS>, MPE/iX, Win32, S<RISC OS>)
1800
1801 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1802
1803 Not implemented. (Plan9)
1804
1805 =item shmctl ID,CMD,ARG
1806
1807 =item shmget KEY,SIZE,FLAGS
1808
1809 =item shmread ID,VAR,POS,SIZE
1810
1811 =item shmwrite ID,STRING,POS,SIZE
1812
1813 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
1814
1815 =item sockatmark SOCKET
1816
1817 A relatively recent addition to socket functions, may not
1818 be implemented even in UNIX platforms.
1819
1820 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1821
1822 Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
1823
1824 =item stat FILEHANDLE
1825
1826 =item stat EXPR
1827
1828 =item stat
1829
1830 Platforms that do not have rdev, blksize, or blocks will return these
1831 as '', so numeric comparison or manipulation of these fields may cause
1832 'not numeric' warnings.
1833
1834 mtime and atime are the same thing, and ctime is creation time instead of
1835 inode change time. (S<Mac OS>).
1836
1837 ctime not supported on UFS (S<Mac OS X>).
1838
1839 ctime is creation time instead of inode change time  (Win32).
1840
1841 device and inode are not meaningful.  (Win32)
1842
1843 device and inode are not necessarily reliable.  (VMS)
1844
1845 mtime, atime and ctime all return the last modification time.  Device and
1846 inode are not necessarily reliable.  (S<RISC OS>)
1847
1848 dev, rdev, blksize, and blocks are not available.  inode is not
1849 meaningful and will differ between stat calls on the same file.  (os2)
1850
1851 some versions of cygwin when doing a stat("foo") and if not finding it
1852 may then attempt to stat("foo.exe") (Cygwin)
1853
1854 =item symlink OLDFILE,NEWFILE
1855
1856 Not implemented. (Win32, VMS, S<RISC OS>)
1857
1858 =item syscall LIST
1859
1860 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
1861
1862 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1863
1864 The traditional "0", "1", and "2" MODEs are implemented with different
1865 numeric values on some systems.  The flags exported by C<Fcntl>
1866 (O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though.  (S<Mac
1867 OS>, OS/390, VM/ESA)
1868
1869 =item system LIST
1870
1871 In general, do not assume the UNIX/POSIX semantics that you can shift
1872 C<$?> right by eight to get the exit value, or that C<$? & 127>
1873 would give you the number of the signal that terminated the program,
1874 or that C<$? & 128> would test true if the program was terminated by a
1875 coredump.  Instead, use the POSIX W*() interfaces: for example, use
1876 WIFEXITED($?) and WEXITVALUE($?) to test for a normal exit and the exit
1877 value, WIFSIGNALED($?) and WTERMSIG($?) for a signal exit and the
1878 signal.  Core dumping is not a portable concept, so there's no portable
1879 way to test for that.
1880
1881 Only implemented if ToolServer is installed. (S<Mac OS>)
1882
1883 As an optimization, may not call the command shell specified in
1884 C<$ENV{PERL5SHELL}>.  C<system(1, @args)> spawns an external
1885 process and immediately returns its process designator, without
1886 waiting for it to terminate.  Return value may be used subsequently
1887 in C<wait> or C<waitpid>.  Failure to spawn() a subprocess is indicated
1888 by setting $? to "255 << 8".  C<$?> is set in a way compatible with
1889 Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8",
1890 as described in the documentation).  (Win32)
1891
1892 There is no shell to process metacharacters, and the native standard is
1893 to pass a command line terminated by "\n" "\r" or "\0" to the spawned
1894 program.  Redirection such as C<< > foo >> is performed (if at all) by
1895 the run time library of the spawned program.  C<system> I<list> will call
1896 the Unix emulation library's C<exec> emulation, which attempts to provide
1897 emulation of the stdin, stdout, stderr in force in the parent, providing
1898 the child program uses a compatible version of the emulation library.
1899 I<scalar> will call the native command line direct and no such emulation
1900 of a child Unix program will exists.  Mileage B<will> vary.  (S<RISC OS>)
1901
1902 Far from being POSIX compliant.  Because there may be no underlying
1903 /bin/sh tries to work around the problem by forking and execing the
1904 first token in its argument string.  Handles basic redirection
1905 ("<" or ">") on its own behalf. (MiNT)
1906
1907 Does not automatically flush output handles on some platforms.
1908 (SunOS, Solaris, HP-UX)
1909
1910 The return value is POSIX-like (shifted up by 8 bits), which only allows
1911 room for a made-up value derived from the severity bits of the native
1912 32-bit condition code (unless overridden by C<use vmsish 'status'>).
1913 For more details see L<perlvms/$?>. (VMS)
1914
1915 =item times
1916
1917 Only the first entry returned is nonzero. (S<Mac OS>)
1918
1919 "cumulative" times will be bogus.  On anything other than Windows NT
1920 or Windows 2000, "system" time will be bogus, and "user" time is
1921 actually the time returned by the clock() function in the C runtime
1922 library. (Win32)
1923
1924 Not useful. (S<RISC OS>)
1925
1926 =item truncate FILEHANDLE,LENGTH
1927
1928 =item truncate EXPR,LENGTH
1929
1930 Not implemented. (Older versions of VMS)
1931
1932 Truncation to zero-length only. (VOS)
1933
1934 If a FILEHANDLE is supplied, it must be writable and opened in append
1935 mode (i.e., use C<<< open(FH, '>>filename') >>>
1936 or C<sysopen(FH,...,O_APPEND|O_RDWR)>.  If a filename is supplied, it
1937 should not be held open elsewhere. (Win32)
1938
1939 =item umask EXPR
1940
1941 =item umask
1942
1943 Returns undef where unavailable, as of version 5.005.
1944
1945 C<umask> works but the correct permissions are set only when the file
1946 is finally closed. (AmigaOS)
1947
1948 =item utime LIST
1949
1950 Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
1951
1952 May not behave as expected.  Behavior depends on the C runtime
1953 library's implementation of utime(), and the filesystem being
1954 used.  The FAT filesystem typically does not support an "access
1955 time" field, and it may limit timestamps to a granularity of
1956 two seconds. (Win32)
1957
1958 =item wait
1959
1960 =item waitpid PID,FLAGS
1961
1962 Not implemented. (S<Mac OS>, VOS)
1963
1964 Can only be applied to process handles returned for processes spawned
1965 using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32)
1966
1967 Not useful. (S<RISC OS>)
1968
1969 =back
1970
1971 =head1 CHANGES
1972
1973 =over 4
1974
1975 =item v1.48, 02 February 2001
1976
1977 Various updates from perl5-porters over the past year, supported
1978 platforms update from Jarkko Hietaniemi.
1979
1980 =item v1.47, 22 March 2000
1981
1982 Various cleanups from Tom Christiansen, including migration of
1983 long platform listings from L<perl>.
1984
1985 =item v1.46, 12 February 2000
1986
1987 Updates for VOS and MPE/iX. (Peter Prymmer)  Other small changes.
1988
1989 =item v1.45, 20 December 1999
1990
1991 Small changes from 5.005_63 distribution, more changes to EBCDIC info.
1992
1993 =item v1.44, 19 July 1999
1994
1995 A bunch of updates from Peter Prymmer for C<$^O> values,
1996 endianness, File::Spec, VMS, BS2000, OS/400.
1997
1998 =item v1.43, 24 May 1999
1999
2000 Added a lot of cleaning up from Tom Christiansen.
2001
2002 =item v1.42, 22 May 1999
2003
2004 Added notes about tests, sprintf/printf, and epoch offsets.
2005
2006 =item v1.41, 19 May 1999
2007
2008 Lots more little changes to formatting and content.
2009
2010 Added a bunch of C<$^O> and related values
2011 for various platforms; fixed mail and web addresses, and added
2012 and changed miscellaneous notes.  (Peter Prymmer)
2013
2014 =item v1.40, 11 April 1999
2015
2016 Miscellaneous changes.
2017
2018 =item v1.39, 11 February 1999
2019
2020 Changes from Jarkko and EMX URL fixes Michael Schwern.  Additional
2021 note about newlines added.
2022
2023 =item v1.38, 31 December 1998
2024
2025 More changes from Jarkko.
2026
2027 =item v1.37, 19 December 1998
2028
2029 More minor changes.  Merge two separate version 1.35 documents.
2030
2031 =item v1.36, 9 September 1998
2032
2033 Updated for Stratus VOS.  Also known as version 1.35.
2034
2035 =item v1.35, 13 August 1998
2036
2037 Integrate more minor changes, plus addition of new sections under
2038 L<"ISSUES">: L<"Numbers endianness and Width">,
2039 L<"Character sets and character encoding">,
2040 L<"Internationalisation">.
2041
2042 =item v1.33, 06 August 1998
2043
2044 Integrate more minor changes.
2045
2046 =item v1.32, 05 August 1998
2047
2048 Integrate more minor changes.
2049
2050 =item v1.30, 03 August 1998
2051
2052 Major update for RISC OS, other minor changes.
2053
2054 =item v1.23, 10 July 1998
2055
2056 First public release with perl5.005.
2057
2058 =back
2059
2060 =head1 Supported Platforms
2061
2062 As of early 2001 (the Perl releases 5.6.1 and 5.7.1), the following
2063 platforms are able to build Perl from the standard source code
2064 distribution available at http://www.cpan.org/src/index.html
2065
2066         AIX
2067         AmigaOS
2068         Darwin          (Mac OS X)
2069         DG/UX
2070         DOS DJGPP       1)
2071         DYNIX/ptx
2072         EPOC R5
2073         FreeBSD
2074         HP-UX
2075         IRIX
2076         Linux
2077         MachTen
2078         MacOS Classic   2)
2079         NonStop-UX
2080         ReliantUNIX     (SINIX)
2081         OpenBSD
2082         OpenVMS         (VMS)
2083         OS/2
2084         OS X
2085         QNX
2086         Solaris
2087         Tru64 UNIX      (DEC OSF/1, Digital UNIX)
2088         UNICOS
2089         UNICOS/mk
2090         VOS
2091         Win32/NT/2K     3)
2092
2093         1) in DOS mode either the DOS or OS/2 ports can be used
2094         2) Mac OS Classic (pre-X) is almost 5.6.1-ready; building from
2095            the source does work with 5.6.1, but additional MacOS specific
2096            source code is needed for a complete build.  See the web
2097            site http://dev.macperl.org/ for more information.
2098         3) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
2099
2100 The following platforms worked for the previous releases (5.6.0 and 5.7.0),
2101 but we did not manage to test these in time for the 5.7.1 release.
2102 There is a very good chance that these will work fine with the 5.7.1.
2103
2104         DomainOS
2105         Hurd
2106         LynxOS
2107         MinGW
2108         MPE/iX
2109         NetBSD
2110         PowerMAX
2111         SCO SV
2112         SunOS
2113         SVR4
2114         Unixware
2115         Windows 3.1
2116         Windows 95
2117         Windows 98
2118         Windows Me
2119
2120 The following platform worked for the 5.005_03 major release but not
2121 for 5.6.0.  Standardization on UTF-8 as the internal string
2122 representation in 5.6.0 and 5.6.1 introduced incompatibilities in this
2123 EBCDIC platform.  While Perl 5.7.1 will build on this platform some
2124 regression tests may fail and the C<use utf8;> pragma typically
2125 introduces text handling errors.
2126
2127         OS/390  1)
2128
2129         1) previously known as MVS, about to become z/OS.
2130
2131 Strongly related to the OS/390 platform by also being EBCDIC-based
2132 mainframe platforms are the following platforms:
2133
2134         POSIX-BC        (BS2000)
2135         VM/ESA
2136
2137 These are also expected to work, albeit with no UTF-8 support, under 5.6.1
2138 for the same reasons as OS/390.  Contact the mailing list perl-mvs@perl.org
2139 for more details.
2140
2141 The following platforms have been known to build Perl from source in
2142 the past (5.005_03 and earlier), but we haven't been able to verify
2143 their status for the current release, either because the
2144 hardware/software platforms are rare or because we don't have an
2145 active champion on these platforms--or both.  They used to work,
2146 though, so go ahead and try compiling them, and let perlbug@perl.org
2147 of any trouble.
2148
2149         3b1
2150         A/UX
2151         BeOS
2152         BSD/OS
2153         ConvexOS
2154         CX/UX
2155         DC/OSx
2156         DDE SMES
2157         DOS EMX
2158         Dynix
2159         EP/IX
2160         ESIX
2161         FPS
2162         GENIX
2163         Greenhills
2164         ISC
2165         MachTen 68k
2166         MiNT
2167         MPC
2168         NEWS-OS
2169         NextSTEP
2170         OpenSTEP
2171         Opus
2172         Plan 9
2173         PowerUX
2174         RISC/os
2175         SCO ODT/OSR
2176         Stellar
2177         SVR2
2178         TI1500
2179         TitanOS
2180         Ultrix
2181         Unisys Dynix
2182         Unixware
2183         UTS
2184
2185 Support for the following platform is planned for a future Perl release:
2186
2187         Netware
2188
2189 The following platforms have their own source code distributions and
2190 binaries available via http://www.cpan.org/ports/
2191
2192                                 Perl release
2193
2194         Netware                 5.003_07
2195         OS/400                  5.005_02
2196         Tandem Guardian         5.004
2197
2198 The following platforms have only binaries available via
2199 http://www.cpan.org/ports/index.html :
2200
2201                                 Perl release
2202
2203         Acorn RISCOS            5.005_02
2204         AOS                     5.002
2205         LynxOS                  5.004_02
2206
2207 Although we do suggest that you always build your own Perl from
2208 the source code, both for maximal configurability and for security,
2209 in case you are in a hurry you can check
2210 http://www.cpan.org/ports/index.html for binary distributions.
2211
2212 =head1 SEE ALSO
2213
2214 L<perlaix>, L<perlapollo>, L<perlamiga>, L<perlbeos>, L<perlbs200>,
2215 L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>, L<perlepoc>, L<perlebcdic>,
2216 L<perlhurd>, L<perlhpux>, L<perlmachten>, L<perlmacos>, L<perlmint>,
2217 L<perlmpeix>, L<perlnetware>, L<perlos2>, L<perlos390>, L<perlplan9>,
2218 L<perlqnx>, L<perlsolaris>, L<perltru64>, L<perlunicode>,
2219 L<perlvmesa>, L<perlvms>, L<perlvos>, L<perlwin32>, and L<Win32>.
2220
2221 =head1 AUTHORS / CONTRIBUTORS
2222
2223 Abigail <abigail@foad.org>,
2224 Charles Bailey <bailey@newman.upenn.edu>,
2225 Graham Barr <gbarr@pobox.com>,
2226 Tom Christiansen <tchrist@perl.com>,
2227 Nicholas Clark <nick@ccl4.org>,
2228 Thomas Dorner <Thomas.Dorner@start.de>,
2229 Andy Dougherty <doughera@lafayette.edu>,
2230 Dominic Dunlop <domo@computer.org>,
2231 Neale Ferguson <neale@vma.tabnsw.com.au>,
2232 David J. Fiander <davidf@mks.com>,
2233 Paul Green <Paul_Green@stratus.com>,
2234 M.J.T. Guy <mjtg@cam.ac.uk>,
2235 Jarkko Hietaniemi <jhi@iki.fi>,
2236 Luther Huffman <lutherh@stratcom.com>,
2237 Nick Ing-Simmons <nick@ing-simmons.net>,
2238 Andreas J. KE<ouml>nig <a.koenig@mind.de>,
2239 Markus Laker <mlaker@contax.co.uk>,
2240 Andrew M. Langmead <aml@world.std.com>,
2241 Larry Moore <ljmoore@freespace.net>,
2242 Paul Moore <Paul.Moore@uk.origin-it.com>,
2243 Chris Nandor <pudge@pobox.com>,
2244 Matthias Neeracher <neeracher@mac.com>,
2245 Philip Newton <pne@cpan.org>,
2246 Gary Ng <71564.1743@CompuServe.COM>,
2247 Tom Phoenix <rootbeer@teleport.com>,
2248 AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
2249 Peter Prymmer <pvhp@forte.com>,
2250 Hugo van der Sanden <hv@crypt0.demon.co.uk>,
2251 Gurusamy Sarathy <gsar@activestate.com>,
2252 Paul J. Schinder <schinder@pobox.com>,
2253 Michael G Schwern <schwern@pobox.com>,
2254 Dan Sugalski <dan@sidhe.org>,
2255 Nathan Torkington <gnat@frii.com>.
2256