1PERLPORT(1)            Perl Programmers Reference Guide            PERLPORT(1)
2
3
4

NAME

6       perlport - Writing portable Perl
7

DESCRIPTION

9       Perl runs on numerous operating systems.  While most of them share much
10       in common, they also have their own unique features.
11
12       This document is meant to help you to find out what constitutes
13       portable Perl code.  That way once you make a decision to write
14       portably, you know where the lines are drawn, and you can stay within
15       them.
16
17       There is a tradeoff between taking full advantage of one particular
18       type of computer and taking advantage of a full range of them.
19       Naturally, as you broaden your range and become more diverse, the
20       common factors drop, and you are left with an increasingly smaller area
21       of common ground in which you can operate to accomplish a particular
22       task.  Thus, when you begin attacking a problem, it is important to
23       consider under which part of the tradeoff curve you want to operate.
24       Specifically, you must decide whether it is important that the task
25       that you are coding has the full generality of being portable, or
26       whether to just get the job done right now.  This is the hardest choice
27       to be made.  The rest is easy, because Perl provides many choices,
28       whichever way you want to approach your problem.
29
30       Looking at it another way, writing portable code is usually about
31       willfully limiting your available choices.  Naturally, it takes
32       discipline and sacrifice to do that.  The product of portability and
33       convenience may be a constant.  You have been warned.
34
35       Be aware of two important points:
36
37       Not all Perl programs have to be portable
38           There is no reason you should not use Perl as a language to glue
39           Unix tools together, or to prototype a Macintosh application, or to
40           manage the Windows registry.  If it makes no sense to aim for
41           portability for one reason or another in a given program, then
42           don't bother.
43
44       Nearly all of Perl already is portable
45           Don't be fooled into thinking that it is hard to create portable
46           Perl code.  It isn't.  Perl tries its level-best to bridge the gaps
47           between what's available on different platforms, and all the means
48           available to use those features.  Thus almost all Perl code runs on
49           any machine without modification.  But there are some significant
50           issues in writing portable code, and this document is entirely
51           about those issues.
52
53       Here's the general rule: When you approach a task commonly done using a
54       whole range of platforms, think about writing portable code.  That way,
55       you don't sacrifice much by way of the implementation choices you can
56       avail yourself of, and at the same time you can give your users lots of
57       platform choices.  On the other hand, when you have to take advantage
58       of some unique feature of a particular platform, as is often the case
59       with systems programming (whether for Unix, Windows, VMS, etc.),
60       consider writing platform-specific code.
61
62       When the code will run on only two or three operating systems, you may
63       need to consider only the differences of those particular systems.  The
64       important thing is to decide where the code will run and to be
65       deliberate in your decision.
66
67       The material below is separated into three main sections: main issues
68       of portability ("ISSUES"), platform-specific issues ("PLATFORMS"), and
69       built-in Perl functions that behave differently on various ports
70       ("FUNCTION IMPLEMENTATIONS").
71
72       This information should not be considered complete; it includes
73       possibly transient information about idiosyncrasies of some of the
74       ports, almost all of which are in a state of constant evolution.  Thus,
75       this material should be considered a perpetual work in progress ("<IMG
76       SRC="yellow_sign.gif" ALT="Under Construction">").
77

ISSUES

79   Newlines
80       In most operating systems, lines in files are terminated by newlines.
81       Just what is used as a newline may vary from OS to OS.  Unix
82       traditionally uses "\012", one type of DOSish I/O uses "\015\012",
83       Mac OS uses "\015", and z/OS uses "\025".
84
85       Perl uses "\n" to represent the "logical" newline, where what is
86       logical may depend on the platform in use.  In MacPerl, "\n" always
87       means "\015".  On EBCDIC platforms, "\n" could be "\025" or "\045".  In
88       DOSish perls, "\n" usually means "\012", but when accessing a file in
89       "text" mode, perl uses the ":crlf" layer that translates it to (or
90       from) "\015\012", depending on whether you're reading or writing. Unix
91       does the same thing on ttys in canonical mode.  "\015\012" is commonly
92       referred to as CRLF.
93
94       To trim trailing newlines from text lines use "chomp".  With default
95       settings that function looks for a trailing "\n" character and thus
96       trims in a portable way.
97
98       When dealing with binary files (or text files in binary mode) be sure
99       to explicitly set $/ to the appropriate value for your file format
100       before using "chomp".
101
102       Because of the "text" mode translation, DOSish perls have limitations
103       in using "seek" and "tell" on a file accessed in "text" mode.  Stick to
104       "seek"-ing to locations you got from "tell" (and no others), and you
105       are usually free to use "seek" and "tell" even in "text" mode.  Using
106       "seek" or "tell" or other file operations may be non-portable.  If you
107       use "binmode" on a file, however, you can usually "seek" and "tell"
108       with arbitrary values safely.
109
110       A common misconception in socket programming is that "\n eq \012"
111       everywhere.  When using protocols such as common Internet protocols,
112       "\012" and "\015" are called for specifically, and the values of the
113       logical "\n" and "\r" (carriage return) are not reliable.
114
115           print $socket "Hi there, client!\r\n";      # WRONG
116           print $socket "Hi there, client!\015\012";  # RIGHT
117
118       However, using "\015\012" (or "\cM\cJ", or "\x0D\x0A") can be tedious
119       and unsightly, as well as confusing to those maintaining the code.  As
120       such, the "Socket" module supplies the Right Thing for those who want
121       it.
122
123           use Socket qw(:DEFAULT :crlf);
124           print $socket "Hi there, client!$CRLF"      # RIGHT
125
126       When reading from a socket, remember that the default input record
127       separator $/ is "\n", but robust socket code will recognize as either
128       "\012" or "\015\012" as end of line:
129
130           while (<$socket>) {  # NOT ADVISABLE!
131               # ...
132           }
133
134       Because both CRLF and LF end in LF, the input record separator can be
135       set to LF and any CR stripped later.  Better to write:
136
137           use Socket qw(:DEFAULT :crlf);
138           local($/) = LF;      # not needed if $/ is already \012
139
140           while (<$socket>) {
141               s/$CR?$LF/\n/;   # not sure if socket uses LF or CRLF, OK
142           #   s/\015?\012/\n/; # same thing
143           }
144
145       This example is preferred over the previous one--even for Unix
146       platforms--because now any "\015"'s ("\cM"'s) are stripped out (and
147       there was much rejoicing).
148
149       Similarly, functions that return text data--such as a function that
150       fetches a web page--should sometimes translate newlines before
151       returning the data, if they've not yet been translated to the local
152       newline representation.  A single line of code will often suffice:
153
154           $data =~ s/\015?\012/\n/g;
155           return $data;
156
157       Some of this may be confusing.  Here's a handy reference to the ASCII
158       CR and LF characters.  You can print it out and stick it in your
159       wallet.
160
161           LF  eq  \012  eq  \x0A  eq  \cJ  eq  chr(10)  eq  ASCII 10
162           CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  ASCII 13
163
164                    | Unix | DOS  | Mac  |
165               ---------------------------
166               \n   |  LF  |  LF  |  CR  |
167               \r   |  CR  |  CR  |  LF  |
168               \n * |  LF  | CRLF |  CR  |
169               \r * |  CR  |  CR  |  LF  |
170               ---------------------------
171               * text-mode STDIO
172
173       The Unix column assumes that you are not accessing a serial line (like
174       a tty) in canonical mode.  If you are, then CR on input becomes "\n",
175       and "\n" on output becomes CRLF.
176
177       These are just the most common definitions of "\n" and "\r" in Perl.
178       There may well be others.  For example, on an EBCDIC implementation
179       such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-
180       based) the above material is similar to "Unix" but the code numbers
181       change:
182
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
187
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
196
197   Numbers endianness and Width
198       Different CPUs store integers and floating point numbers in different
199       orders (called endianness) and widths (32-bit and 64-bit being the most
200       common today).  This affects your programs when they attempt to
201       transfer numbers in binary format from one CPU architecture to another,
202       usually either "live" via network connection, or by storing the numbers
203       to secondary storage such as a disk file or tape.
204
205       Conflicting storage orders make an utter mess out of the numbers.  If a
206       little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
207       decimal), a big-endian host (Motorola, Sparc, PA) reads it as
208       0x78563412 (2018915346 in decimal).  Alpha and MIPS can be either:
209       Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses them
210       in big-endian mode.  To avoid this problem in network (socket)
211       connections use the "pack" and "unpack" formats "n" and "N", the
212       "network" orders.  These are guaranteed to be portable.
213
214       As of Perl 5.10.0, you can also use the ">" and "<" modifiers to force
215       big- or little-endian byte-order.  This is useful if you want to store
216       signed integers or 64-bit integers, for example.
217
218       You can explore the endianness of your platform by unpacking a data
219       structure packed in native format such as:
220
221           print unpack("h*", pack("s2", 1, 2)), "\n";
222           # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
223           # '00100020' on e.g. Motorola 68040
224
225       If you need to distinguish between endian architectures you could use
226       either of the variables set like so:
227
228           $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
229           $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
230
231       Differing widths can cause truncation even between platforms of equal
232       endianness.  The platform of shorter width loses the upper parts of the
233       number.  There is no good solution for this problem except to avoid
234       transferring or storing raw binary numbers.
235
236       One can circumnavigate both these problems in two ways.  Either
237       transfer and store numbers always in text format, instead of raw
238       binary, or else consider using modules like "Data::Dumper" and
239       "Storable" (included as of Perl 5.8).  Keeping all data as text
240       significantly simplifies matters.
241
242   Files and Filesystems
243       Most platforms these days structure files in a hierarchical fashion.
244       So, it is reasonably safe to assume that all platforms support the
245       notion of a "path" to uniquely identify a file on the system.  How that
246       path is really written, though, differs considerably.
247
248       Although similar, file path specifications differ between Unix,
249       Windows, Mac OS, OS/2, VMS, VOS, RISC OS, and probably others.  Unix,
250       for example, is one of the few OSes that has the elegant idea of a
251       single root directory.
252
253       DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with "/" as
254       path separator, or in their own idiosyncratic ways (such as having
255       several root directories and various "unrooted" device files such NIL:
256       and LPT:).
257
258       Mac OS 9 and earlier used ":" as a path separator instead of "/".
259
260       The filesystem may support neither hard links ("link") nor symbolic
261       links ("symlink", "readlink", "lstat").
262
263       The filesystem may support neither access timestamp nor change
264       timestamp (meaning that about the only portable timestamp is the
265       modification timestamp), or one second granularity of any timestamps
266       (e.g. the FAT filesystem limits the time granularity to two seconds).
267
268       The "inode change timestamp" (the "-C" filetest) may really be the
269       "creation timestamp" (which it is not in Unix).
270
271       VOS perl can emulate Unix filenames with "/" as path separator.  The
272       native pathname characters greater-than, less-than, number-sign, and
273       percent-sign are always accepted.
274
275       RISC OS perl can emulate Unix filenames with "/" as path separator, or
276       go native and use "." for path separator and ":" to signal filesystems
277       and disk names.
278
279       Don't assume Unix filesystem access semantics: that read, write, and
280       execute are all the permissions there are, and even if they exist, that
281       their semantics (for example what do "r", "w", and "x" mean on a
282       directory) are the Unix ones.  The various Unix/POSIX compatibility
283       layers usually try to make interfaces like "chmod" work, but sometimes
284       there simply is no good mapping.
285
286       The "File::Spec" modules provide methods to manipulate path
287       specifications and return the results in native format for each
288       platform.  This is often unnecessary as Unix-style paths are understood
289       by Perl on every supported platform, but if you need to produce native
290       paths for a native utility that does not understand Unix syntax, or if
291       you are operating on paths or path components in unknown (and thus
292       possibly native) syntax, "File::Spec" is your friend.  Here are two
293       brief examples:
294
295           use File::Spec::Functions;
296           chdir(updir());        # go up one directory
297
298           # Concatenate a path from its components
299           my $file = catfile(updir(), 'temp', 'file.txt');
300           # on Unix:    '../temp/file.txt'
301           # on Win32:   '..\temp\file.txt'
302           # on VMS:     '[-.temp]file.txt'
303
304       In general, production code should not have file paths hardcoded.
305       Making them user-supplied or read from a configuration file is better,
306       keeping in mind that file path syntax varies on different machines.
307
308       This is especially noticeable in scripts like Makefiles and test
309       suites, which often assume "/" as a path separator for subdirectories.
310
311       Also of use is "File::Basename" from the standard distribution, which
312       splits a pathname into pieces (base filename, full path to directory,
313       and file suffix).
314
315       Even when on a single platform (if you can call Unix a single
316       platform), remember not to count on the existence or the contents of
317       particular system-specific files or directories, like /etc/passwd,
318       /etc/sendmail.conf, /etc/resolv.conf, or even /tmp/.  For example,
319       /etc/passwd may exist but not contain the encrypted passwords, because
320       the system is using some form of enhanced security.  Or it may not
321       contain all the accounts, because the system is using NIS.  If code
322       does need to rely on such a file, include a description of the file and
323       its format in the code's documentation, then make it easy for the user
324       to override the default location of the file.
325
326       Don't assume a text file will end with a newline.  They should, but
327       people forget.
328
329       Do not have two files or directories of the same name with different
330       case, like test.pl and Test.pl, as many platforms have case-insensitive
331       (or at least case-forgiving) filenames.  Also, try not to have non-word
332       characters (except for ".") in the names, and keep them to the 8.3
333       convention, for maximum portability, onerous a burden though this may
334       appear.
335
336       Likewise, when using the "AutoSplit" module, try to keep your functions
337       to 8.3 naming and case-insensitive conventions; or, at the least, make
338       it so the resulting files have a unique (case-insensitively) first 8
339       characters.
340
341       Whitespace in filenames is tolerated on most systems, but not all, and
342       even on systems where it might be tolerated, some utilities might
343       become confused by such whitespace.
344
345       Many systems (DOS, VMS ODS-2) cannot have more than one "." in their
346       filenames.
347
348       Don't assume ">" won't be the first character of a filename.  Always
349       use the three-arg version of "open":
350
351           open my $fh, '<', $existing_file) or die $!;
352
353       Two-arg "open" is magic and can translate characters like ">", "<", and
354       "|" in filenames, which is usually the wrong thing to do.  "sysopen"
355       and three-arg "open" don't have this problem.
356
357       Don't use ":" as a part of a filename since many systems use that for
358       their own semantics (Mac OS Classic for separating pathname components,
359       many networking schemes and utilities for separating the nodename and
360       the pathname, and so on).  For the same reasons, avoid "@", ";" and
361       "|".
362
363       Don't assume that in pathnames you can collapse two leading slashes
364       "//" into one: some networking and clustering filesystems have special
365       semantics for that.  Let the operating system sort it out.
366
367       The portable filename characters as defined by ANSI C are
368
369        a b c d e f g h i j k l m n o p q r s t u v w x y z
370        A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
371        0 1 2 3 4 5 6 7 8 9
372        . _ -
373
374       and "-" shouldn't be the first character.  If you want to be
375       hypercorrect, stay case-insensitive and within the 8.3 naming
376       convention (all the files and directories have to be unique within one
377       directory if their names are lowercased and truncated to eight
378       characters before the ".", if any, and to three characters after the
379       ".", if any).  (And do not use "."s in directory names.)
380
381   System Interaction
382       Not all platforms provide a command line.  These are usually platforms
383       that rely primarily on a Graphical User Interface (GUI) for user
384       interaction.  A program requiring a command line interface might not
385       work everywhere.  This is probably for the user of the program to deal
386       with, so don't stay up late worrying about it.
387
388       Some platforms can't delete or rename files held open by the system,
389       this limitation may also apply to changing filesystem metainformation
390       like file permissions or owners.  Remember to "close" files when you
391       are done with them.  Don't "unlink" or "rename" an open file.  Don't
392       "tie" or "open" a file already tied or opened; "untie" or "close" it
393       first.
394
395       Don't open the same file more than once at a time for writing, as some
396       operating systems put mandatory locks on such files.
397
398       Don't assume that write/modify permission on a directory gives the
399       right to add or delete files/directories in that directory.  That is
400       filesystem specific: in some filesystems you need write/modify
401       permission also (or even just) in the file/directory itself.  In some
402       filesystems (AFS, DFS) the permission to add/delete directory entries
403       is a completely separate permission.
404
405       Don't assume that a single "unlink" completely gets rid of the file:
406       some filesystems (most notably the ones in VMS) have versioned
407       filesystems, and "unlink" removes only the most recent one (it doesn't
408       remove all the versions because by default the native tools on those
409       platforms remove just the most recent version, too).  The portable
410       idiom to remove all the versions of a file is
411
412           1 while unlink "file";
413
414       This will terminate if the file is undeletable for some reason
415       (protected, not there, and so on).
416
417       Don't count on a specific environment variable existing in %ENV.  Don't
418       count on %ENV entries being case-sensitive, or even case-preserving.
419       Don't try to clear %ENV by saying "%ENV = ();", or, if you really have
420       to, make it conditional on "$^O ne 'VMS'" since in VMS the %ENV table
421       is much more than a per-process key-value string table.
422
423       On VMS, some entries in the %ENV hash are dynamically created when
424       their key is used on a read if they did not previously exist.  The
425       values for $ENV{HOME}, $ENV{TERM}, $ENV{PATH}, and $ENV{USER}, are
426       known to be dynamically generated.  The specific names that are
427       dynamically generated may vary with the version of the C library on
428       VMS, and more may exist than are documented.
429
430       On VMS by default, changes to the %ENV hash persist after perl exits.
431       Subsequent invocations of perl in the same process can inadvertently
432       inherit environment settings that were meant to be temporary.
433
434       Don't count on signals or %SIG for anything.
435
436       Don't count on filename globbing.  Use "opendir", "readdir", and
437       "closedir" instead.
438
439       Don't count on per-program environment variables, or per-program
440       current directories.
441
442       Don't count on specific values of $!, neither numeric nor especially
443       the string values. Users may switch their locales causing error
444       messages to be translated into their languages.  If you can trust a
445       POSIXish environment, you can portably use the symbols defined by the
446       "Errno" module, like "ENOENT".  And don't trust on the values of $! at
447       all except immediately after a failed system call.
448
449   Command names versus file pathnames
450       Don't assume that the name used to invoke a command or program with
451       "system" or "exec" can also be used to test for the existence of the
452       file that holds the executable code for that command or program.
453       First, many systems have "internal" commands that are built-in to the
454       shell or OS and while these commands can be invoked, there is no
455       corresponding file.  Second, some operating systems (e.g., Cygwin,
456       OS/2, and VOS) have required suffixes for executable files; these
457       suffixes are generally permitted on the command name but are not
458       required.  Thus, a command like "perl" might exist in a file named
459       perl, perl.exe, or perl.pm, depending on the operating system.  The
460       variable $Config{_exe} in the "Config" module holds the executable
461       suffix, if any.  Third, the VMS port carefully sets up $^X and
462       $Config{perlpath} so that no further processing is required.  This is
463       just as well, because the matching regular expression used below would
464       then have to deal with a possible trailing version number in the VMS
465       file name.
466
467       To convert $^X to a file pathname, taking account of the requirements
468       of the various operating system possibilities, say:
469
470        use Config;
471        my $thisperl = $^X;
472        if ($^O ne 'VMS') {
473            $thisperl .= $Config{_exe}
474                unless $thisperl =~ m/\Q$Config{_exe}\E$/i;
475        }
476
477       To convert $Config{perlpath} to a file pathname, say:
478
479        use Config;
480        my $thisperl = $Config{perlpath};
481        if ($^O ne 'VMS') {
482            $thisperl .= $Config{_exe}
483                unless $thisperl =~ m/\Q$Config{_exe}\E$/i;
484        }
485
486   Networking
487       Don't assume that you can reach the public Internet.
488
489       Don't assume that there is only one way to get through firewalls to the
490       public Internet.
491
492       Don't assume that you can reach outside world through any other port
493       than 80, or some web proxy.  ftp is blocked by many firewalls.
494
495       Don't assume that you can send email by connecting to the local SMTP
496       port.
497
498       Don't assume that you can reach yourself or any node by the name
499       'localhost'.  The same goes for '127.0.0.1'.  You will have to try
500       both.
501
502       Don't assume that the host has only one network card, or that it can't
503       bind to many virtual IP addresses.
504
505       Don't assume a particular network device name.
506
507       Don't assume a particular set of "ioctl"s will work.
508
509       Don't assume that you can ping hosts and get replies.
510
511       Don't assume that any particular port (service) will respond.
512
513       Don't assume that "Sys::Hostname" (or any other API or command) returns
514       either a fully qualified hostname or a non-qualified hostname: it all
515       depends on how the system had been configured.  Also remember that for
516       things such as DHCP and NAT, the hostname you get back might not be
517       very useful.
518
519       All the above don'ts may look daunting, and they are, but the key is to
520       degrade gracefully if one cannot reach the particular network service
521       one wants.  Croaking or hanging do not look very professional.
522
523   Interprocess Communication (IPC)
524       In general, don't directly access the system in code meant to be
525       portable.  That means, no "system", "exec", "fork", "pipe", `` or
526       "qx//", "open" with a "|", nor any of the other things that makes being
527       a Perl hacker worth being.
528
529       Commands that launch external processes are generally supported on most
530       platforms (though many of them do not support any type of forking).
531       The problem with using them arises from what you invoke them on.
532       External tools are often named differently on different platforms, may
533       not be available in the same location, might accept different
534       arguments, can behave differently, and often present their results in a
535       platform-dependent way.  Thus, you should seldom depend on them to
536       produce consistent results.  (Then again, if you're calling "netstat
537       -a", you probably don't expect it to run on both Unix and CP/M.)
538
539       One especially common bit of Perl code is opening a pipe to sendmail:
540
541           open(my $mail, '|-', '/usr/lib/sendmail -t')
542               or die "cannot fork sendmail: $!";
543
544       This is fine for systems programming when sendmail is known to be
545       available.  But it is not fine for many non-Unix systems, and even some
546       Unix systems that may not have sendmail installed.  If a portable
547       solution is needed, see the various distributions on CPAN that deal
548       with it.  "Mail::Mailer" and "Mail::Send" in the "MailTools"
549       distribution are commonly used, and provide several mailing methods,
550       including "mail", "sendmail", and direct SMTP (via "Net::SMTP") if a
551       mail transfer agent is not available.  "Mail::Sendmail" is a standalone
552       module that provides simple, platform-independent mailing.
553
554       The Unix System V IPC ("msg*(), sem*(), shm*()") is not available even
555       on all Unix platforms.
556
557       Do not use either the bare result of "pack("N", 10, 20, 30, 40)" or
558       bare v-strings (such as "v10.20.30.40") to represent IPv4 addresses:
559       both forms just pack the four bytes into network order.  That this
560       would be equal to the C language "in_addr" struct (which is what the
561       socket code internally uses) is not guaranteed.  To be portable use the
562       routines of the "Socket" module, such as "inet_aton", "inet_ntoa", and
563       "sockaddr_in".
564
565       The rule of thumb for portable code is: Do it all in portable Perl, or
566       use a module (that may internally implement it with platform-specific
567       code, but exposes a common interface).
568
569   External Subroutines (XS)
570       XS code can usually be made to work with any platform, but dependent
571       libraries, header files, etc., might not be readily available or
572       portable, or the XS code itself might be platform-specific, just as
573       Perl code might be.  If the libraries and headers are portable, then it
574       is normally reasonable to make sure the XS code is portable, too.
575
576       A different type of portability issue arises when writing XS code:
577       availability of a C compiler on the end-user's system.  C brings with
578       it its own portability issues, and writing XS code will expose you to
579       some of those.  Writing purely in Perl is an easier way to achieve
580       portability.
581
582   Standard Modules
583       In general, the standard modules work across platforms.  Notable
584       exceptions are the "CPAN" module (which currently makes connections to
585       external programs that may not be available), platform-specific modules
586       (like "ExtUtils::MM_VMS"), and DBM modules.
587
588       There is no one DBM module available on all platforms.  "SDBM_File" and
589       the others are generally available on all Unix and DOSish ports, but
590       not in MacPerl, where only "NDBM_File" and "DB_File" are available.
591
592       The good news is that at least some DBM module should be available, and
593       "AnyDBM_File" will use whichever module it can find.  Of course, then
594       the code needs to be fairly strict, dropping to the greatest common
595       factor (e.g., not exceeding 1K for each record), so that it will work
596       with any DBM module.  See AnyDBM_File for more details.
597
598   Time and Date
599       The system's notion of time of day and calendar date is controlled in
600       widely different ways.  Don't assume the timezone is stored in
601       $ENV{TZ}, and even if it is, don't assume that you can control the
602       timezone through that variable.  Don't assume anything about the three-
603       letter timezone abbreviations (for example that MST would be the
604       Mountain Standard Time, it's been known to stand for Moscow Standard
605       Time).  If you need to use timezones, express them in some unambiguous
606       format like the exact number of minutes offset from UTC, or the POSIX
607       timezone format.
608
609       Don't assume that the epoch starts at 00:00:00, January 1, 1970,
610       because that is OS- and implementation-specific.  It is better to store
611       a date in an unambiguous representation.  The ISO 8601 standard defines
612       YYYY-MM-DD as the date format, or YYYY-MM-DDTHH:MM:SS (that's a literal
613       "T" separating the date from the time).  Please do use the ISO 8601
614       instead of making us guess what date 02/03/04 might be.  ISO 8601 even
615       sorts nicely as-is.  A text representation (like "1987-12-18") can be
616       easily converted into an OS-specific value using a module like
617       "Time::Piece" (see "Date Parsing" in Time::Piece) or "Date::Parse".  An
618       array of values, such as those returned by "localtime", can be
619       converted to an OS-specific representation using "Time::Local".
620
621       When calculating specific times, such as for tests in time or date
622       modules, it may be appropriate to calculate an offset for the epoch.
623
624           use Time::Local qw(timegm);
625           my $offset = timegm(0, 0, 0, 1, 0, 1970);
626
627       The value for $offset in Unix will be 0, but in Mac OS Classic will be
628       some large number.  $offset can then be added to a Unix time value to
629       get what should be the proper value on any system.
630
631   Character sets and character encoding
632       Assume very little about character sets.
633
634       Assume nothing about numerical values ("ord", "chr") of characters.  Do
635       not use explicit code point ranges (like "\xHH-\xHH)".  However,
636       starting in Perl v5.22, regular expression pattern bracketed character
637       class ranges specified like "qr/[\N{U+HH}-\N{U+HH}]/" are portable, and
638       starting in Perl v5.24, the same ranges are portable in "tr///".  You
639       can portably use symbolic character classes like "[:print:]".
640
641       Do not assume that the alphabetic characters are encoded contiguously
642       (in the numeric sense).  There may be gaps.  Special coding in Perl,
643       however, guarantees that all subsets of "qr/[A-Z]/", "qr/[a-z]/", and
644       "qr/[0-9]/" behave as expected.  "tr///" behaves the same for these
645       ranges.  In patterns, any ranges specified with end points using the
646       "\N{...}" notations ensures character set portability, but it is a bug
647       in Perl v5.22 that this isn't true of "tr///", fixed in v5.24.
648
649       Do not assume anything about the ordering of the characters.  The
650       lowercase letters may come before or after the uppercase letters; the
651       lowercase and uppercase may be interlaced so that both "a" and "A" come
652       before "b"; the accented and other international characters may be
653       interlaced so that ä comes before "b".  Unicode::Collate can be used to
654       sort this all out.
655
656   Internationalisation
657       If you may assume POSIX (a rather large assumption), you may read more
658       about the POSIX locale system from perllocale.  The locale system at
659       least attempts to make things a little bit more portable, or at least
660       more convenient and native-friendly for non-English users.  The system
661       affects character sets and encoding, and date and time
662       formatting--amongst other things.
663
664       If you really want to be international, you should consider Unicode.
665       See perluniintro and perlunicode for more information.
666
667       By default Perl assumes your source code is written in an 8-bit ASCII
668       superset. To embed Unicode characters in your strings and regexes, you
669       can use the "\x{HH}" or (more portably) "\N{U+HH}" notations. You can
670       also use the "utf8" pragma and write your code in UTF-8, which lets you
671       use Unicode characters directly (not just in quoted constructs but also
672       in identifiers).
673
674   System Resources
675       If your code is destined for systems with severely constrained (or
676       missing!) virtual memory systems then you want to be especially mindful
677       of avoiding wasteful constructs such as:
678
679           my @lines = <$very_large_file>;            # bad
680
681           while (<$fh>) {$file .= $_}                # sometimes bad
682           my $file = join('', <$fh>);                # better
683
684       The last two constructs may appear unintuitive to most people.  The
685       first repeatedly grows a string, whereas the second allocates a large
686       chunk of memory in one go.  On some systems, the second is more
687       efficient than the first.
688
689   Security
690       Most multi-user platforms provide basic levels of security, usually
691       implemented at the filesystem level.  Some, however, unfortunately do
692       not.  Thus the notion of user id, or "home" directory, or even the
693       state of being logged-in, may be unrecognizable on many platforms.  If
694       you write programs that are security-conscious, it is usually best to
695       know what type of system you will be running under so that you can
696       write code explicitly for that platform (or class of platforms).
697
698       Don't assume the Unix filesystem access semantics: the operating system
699       or the filesystem may be using some ACL systems, which are richer
700       languages than the usual "rwx".  Even if the "rwx" exist, their
701       semantics might be different.
702
703       (From the security viewpoint, testing for permissions before attempting
704       to do something is silly anyway: if one tries this, there is potential
705       for race conditions. Someone or something might change the permissions
706       between the permissions check and the actual operation.  Just try the
707       operation.)
708
709       Don't assume the Unix user and group semantics: especially, don't
710       expect $< and $> (or $( and $)) to work for switching identities (or
711       memberships).
712
713       Don't assume set-uid and set-gid semantics.  (And even if you do, think
714       twice: set-uid and set-gid are a known can of security worms.)
715
716   Style
717       For those times when it is necessary to have platform-specific code,
718       consider keeping the platform-specific code in one place, making
719       porting to other platforms easier.  Use the "Config" module and the
720       special variable $^O to differentiate platforms, as described in
721       "PLATFORMS".
722
723       Beware of the "else syndrome":
724
725         if ($^O eq 'MSWin32') {
726           # code that assumes Windows
727         } else {
728           # code that assumes Linux
729         }
730
731       The "else" branch should be used for the really ultimate fallback, not
732       for code specific to some platform.
733
734       Be careful in the tests you supply with your module or programs.
735       Module code may be fully portable, but its tests might not be.  This
736       often happens when tests spawn off other processes or call external
737       programs to aid in the testing, or when (as noted above) the tests
738       assume certain things about the filesystem and paths.  Be careful not
739       to depend on a specific output style for errors, such as when checking
740       $! after a failed system call.  Using $! for anything else than
741       displaying it as output is doubtful (though see the "Errno" module for
742       testing reasonably portably for error value). Some platforms expect a
743       certain output format, and Perl on those platforms may have been
744       adjusted accordingly.  Most specifically, don't anchor a regex when
745       testing an error value.
746

CPAN Testers

748       Modules uploaded to CPAN are tested by a variety of volunteers on
749       different platforms.  These CPAN testers are notified by mail of each
750       new upload, and reply to the list with PASS, FAIL, NA (not applicable
751       to this platform), or UNKNOWN (unknown), along with any relevant
752       notations.
753
754       The purpose of the testing is twofold: one, to help developers fix any
755       problems in their code that crop up because of lack of testing on other
756       platforms; two, to provide users with information about whether a given
757       module works on a given platform.
758
759       Also see:
760
761       •   Mailing list: cpan-testers-discuss@perl.org
762
763       •   Testing results: <https://www.cpantesters.org/>
764

PLATFORMS

766       Perl is built with a $^O variable that indicates the operating system
767       it was built on.  This was implemented to help speed up code that would
768       otherwise have to "use Config" and use the value of $Config{osname}.
769       Of course, to get more detailed information about the system, looking
770       into %Config is certainly recommended.
771
772       %Config cannot always be trusted, however, because it was built at
773       compile time.  If perl was built in one place, then transferred
774       elsewhere, some values may be wrong.  The values may even have been
775       edited after the fact.
776
777   Unix
778       Perl works on a bewildering variety of Unix and Unix-like platforms
779       (see e.g. most of the files in the hints/ directory in the source code
780       kit).  On most of these systems, the value of $^O (hence
781       $Config{osname}, too) is determined either by lowercasing and stripping
782       punctuation from the first field of the string returned by typing
783       "uname -a" (or a similar command) at the shell prompt or by testing the
784       file system for the presence of uniquely named files such as a kernel
785       or header file.  Here, for example, are a few of the more popular Unix
786       flavors:
787
788           uname         $^O        $Config{archname}
789           --------------------------------------------
790           AIX           aix        aix
791           BSD/OS        bsdos      i386-bsdos
792           Darwin        darwin     darwin
793           DYNIX/ptx     dynixptx   i386-dynixptx
794           FreeBSD       freebsd    freebsd-i386
795           Haiku         haiku      BePC-haiku
796           Linux         linux      arm-linux
797           Linux         linux      armv5tel-linux
798           Linux         linux      i386-linux
799           Linux         linux      i586-linux
800           Linux         linux      ppc-linux
801           HP-UX         hpux       PA-RISC1.1
802           IRIX          irix       irix
803           Mac OS X      darwin     darwin
804           NeXT 3        next       next-fat
805           NeXT 4        next       OPENSTEP-Mach
806           openbsd       openbsd    i386-openbsd
807           OSF1          dec_osf    alpha-dec_osf
808           reliantunix-n svr4       RM400-svr4
809           SCO_SV        sco_sv     i386-sco_sv
810           SINIX-N       svr4       RM400-svr4
811           sn4609        unicos     CRAY_C90-unicos
812           sn6521        unicosmk   t3e-unicosmk
813           sn9617        unicos     CRAY_J90-unicos
814           SunOS         solaris    sun4-solaris
815           SunOS         solaris    i86pc-solaris
816           SunOS4        sunos      sun4-sunos
817
818       Because the value of $Config{archname} may depend on the hardware
819       architecture, it can vary more than the value of $^O.
820
821   DOS and Derivatives
822       Perl has long been ported to Intel-style microcomputers running under
823       systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
824       bring yourself to mention (except for Windows CE, if you count that).
825       Users familiar with COMMAND.COM or CMD.EXE style shells should be aware
826       that each of these file specifications may have subtle differences:
827
828           my $filespec0 = "c:/foo/bar/file.txt";
829           my $filespec1 = "c:\\foo\\bar\\file.txt";
830           my $filespec2 = 'c:\foo\bar\file.txt';
831           my $filespec3 = 'c:\\foo\\bar\\file.txt';
832
833       System calls accept either "/" or "\" as the path separator.  However,
834       many command-line utilities of DOS vintage treat "/" as the option
835       prefix, so may get confused by filenames containing "/".  Aside from
836       calling any external programs, "/" will work just fine, and probably
837       better, as it is more consistent with popular usage, and avoids the
838       problem of remembering what to backwhack and what not to.
839
840       The DOS FAT filesystem can accommodate only "8.3" style filenames.
841       Under the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS
842       (NT) filesystems you may have to be careful about case returned with
843       functions like "readdir" or used with functions like "open" or
844       "opendir".
845
846       DOS also treats several filenames as special, such as AUX, PRN, NUL,
847       CON, COM1, LPT1, LPT2, etc.  Unfortunately, sometimes these filenames
848       won't even work if you include an explicit directory prefix.  It is
849       best to avoid such filenames, if you want your code to be portable to
850       DOS and its derivatives.  It's hard to know what these all are,
851       unfortunately.
852
853       Users of these operating systems may also wish to make use of scripts
854       such as pl2bat.bat to put wrappers around your scripts.
855
856       Newline ("\n") is translated as "\015\012" by the I/O system when
857       reading from and writing to files (see "Newlines").
858       binmode($filehandle) will keep "\n" translated as "\012" for that
859       filehandle.  "binmode" should always be used for code that deals with
860       binary data.  That's assuming you realize in advance that your data is
861       in binary.  General-purpose programs should often assume nothing about
862       their data.
863
864       The $^O variable and the $Config{archname} values for various DOSish
865       perls are as follows:
866
867           OS             $^O       $Config{archname}  ID    Version
868           ---------------------------------------------------------
869           MS-DOS         dos       ?
870           PC-DOS         dos       ?
871           OS/2           os2       ?
872           Windows 3.1    ?         ?                  0     3 01
873           Windows 95     MSWin32   MSWin32-x86        1     4 00
874           Windows 98     MSWin32   MSWin32-x86        1     4 10
875           Windows ME     MSWin32   MSWin32-x86        1     ?
876           Windows NT     MSWin32   MSWin32-x86        2     4 xx
877           Windows NT     MSWin32   MSWin32-ALPHA      2     4 xx
878           Windows NT     MSWin32   MSWin32-ppc        2     4 xx
879           Windows 2000   MSWin32   MSWin32-x86        2     5 00
880           Windows XP     MSWin32   MSWin32-x86        2     5 01
881           Windows 2003   MSWin32   MSWin32-x86        2     5 02
882           Windows Vista  MSWin32   MSWin32-x86        2     6 00
883           Windows 7      MSWin32   MSWin32-x86        2     6 01
884           Windows 7      MSWin32   MSWin32-x64        2     6 01
885           Windows 2008   MSWin32   MSWin32-x86        2     6 01
886           Windows 2008   MSWin32   MSWin32-x64        2     6 01
887           Windows CE     MSWin32   ?                  3
888           Cygwin         cygwin    cygwin
889
890       The various MSWin32 Perl's can distinguish the OS they are running on
891       via the value of the fifth element of the list returned from
892       Win32::GetOSVersion().  For example:
893
894           if ($^O eq 'MSWin32') {
895               my @os_version_info = Win32::GetOSVersion();
896               print +('3.1','95','NT')[$os_version_info[4]],"\n";
897           }
898
899       There are also "Win32::IsWinNT()|Win32/Win32::IsWinNT()",
900       "Win32::IsWin95()|Win32/Win32::IsWin95()", and Win32::GetOSName(); try
901       "perldoc Win32".  The very portable POSIX::uname() will work too:
902
903           c:\> perl -MPOSIX -we "print join '|', uname"
904           Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
905
906       Errors set by Winsock functions are now put directly into $^E, and the
907       relevant "WSAE*" error codes are now exported from the Errno and POSIX
908       modules for testing this against.
909
910       The previous behavior of putting the errors (converted to POSIX-style
911       "E*" error codes since Perl 5.20.0) into $! was buggy due to the non-
912       equivalence of like-named Winsock and POSIX error constants, a
913       relationship between which has unfortunately been established in one
914       way or another since Perl 5.8.0.
915
916       The new behavior provides a much more robust solution for checking
917       Winsock errors in portable software without accidentally matching POSIX
918       tests that were intended for other OSes and may have different meanings
919       for Winsock.
920
921       The old behavior is currently retained, warts and all, for backwards
922       compatibility, but users are encouraged to change any code that tests
923       $! against "E*" constants for Winsock errors to instead test $^E
924       against "WSAE*" constants.  After a suitable deprecation period, which
925       started with Perl 5.24, the old behavior may be removed, leaving $!
926       unchanged after Winsock function calls, to avoid any possible confusion
927       over which error variable to check.
928
929       Also see:
930
931       •   The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
932           <ftp://hobbes.nmsu.edu/pub/os2/dev/emx/>  Also perlos2.
933
934       •   Build instructions for Win32 in perlwin32, or under the Cygnus
935           environment in perlcygwin.
936
937       •   The "Win32::*" modules in Win32.
938
939       •   The ActiveState Pages, <https://www.activestate.com/>
940
941       •   The Cygwin environment for Win32; README.cygwin (installed as
942           perlcygwin), <https://www.cygwin.com/>
943
944       •   Build instructions for OS/2, perlos2
945
946   VMS
947       Perl on VMS is discussed in perlvms in the Perl distribution.
948
949       The official name of VMS as of this writing is OpenVMS.
950
951       Interacting with Perl from the Digital Command Language (DCL) shell
952       often requires a different set of quotation marks than Unix shells do.
953       For example:
954
955           $ perl -e "print ""Hello, world.\n"""
956           Hello, world.
957
958       There are several ways to wrap your Perl scripts in DCL .COM files, if
959       you are so inclined.  For example:
960
961           $ write sys$output "Hello from DCL!"
962           $ if p1 .eqs. ""
963           $ then perl -x 'f$environment("PROCEDURE")
964           $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
965           $ deck/dollars="__END__"
966           #!/usr/bin/perl
967
968           print "Hello from Perl!\n";
969
970           __END__
971           $ endif
972
973       Do take care with "$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT" if your
974       Perl-in-DCL script expects to do things like "$read = <STDIN>;".
975
976       The VMS operating system has two filesystems, designated by their on-
977       disk structure (ODS) level: ODS-2 and its successor ODS-5.  The initial
978       port of Perl to VMS pre-dates ODS-5, but all current testing and
979       development assumes ODS-5 and its capabilities, including case
980       preservation, extended characters in filespecs, and names up to 8192
981       bytes long.
982
983       Perl on VMS can accept either VMS- or Unix-style file specifications as
984       in either of the following:
985
986           $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
987           $ perl -ne "print if /perl_setup/i" /sys$login/login.com
988
989       but not a mixture of both as in:
990
991           $ perl -ne "print if /perl_setup/i" sys$login:/login.com
992           Can't open sys$login:/login.com: file specification syntax error
993
994       In general, the easiest path to portability is always to specify
995       filenames in Unix format unless they will need to be processed by
996       native commands or utilities.  Because of this latter consideration,
997       the File::Spec module by default returns native format specifications
998       regardless of input format.  This default may be reversed so that
999       filenames are always reported in Unix format by specifying the
1000       "DECC$FILENAME_UNIX_REPORT" feature logical in the environment.
1001
1002       The file type, or extension, is always present in a VMS-format file
1003       specification even if it's zero-length.  This means that, by default,
1004       "readdir" will return a trailing dot on a file with no extension, so
1005       where you would see "a" on Unix you'll see "a." on VMS.  However, the
1006       trailing dot may be suppressed by enabling the
1007       "DECC$READDIR_DROPDOTNOTYPE" feature in the environment (see the CRTL
1008       documentation on feature logical names).
1009
1010       What "\n" represents depends on the type of file opened.  It usually
1011       represents "\012" but it could also be "\015", "\012", "\015\012",
1012       "\000", "\040", or nothing depending on the file organization and
1013       record format.  The "VMS::Stdio" module provides access to the special
1014       fopen() requirements of files with unusual attributes on VMS.
1015
1016       The value of $^O on OpenVMS is "VMS".  To determine the architecture
1017       that you are running on refer to $Config{archname}.
1018
1019       On VMS, perl determines the UTC offset from the
1020       "SYS$TIMEZONE_DIFFERENTIAL" logical name.  Although the VMS epoch began
1021       at 17-NOV-1858 00:00:00.00, calls to "localtime" are adjusted to count
1022       offsets from 01-JAN-1970 00:00:00.00, just like Unix.
1023
1024       Also see:
1025
1026README.vms (installed as README_vms), perlvms
1027
1028       •   vmsperl list, vmsperl-subscribe@perl.org
1029
1030       •   vmsperl on the web, <http://www.sidhe.org/vmsperl/index.html>
1031
1032       •   VMS Software Inc. web site, <http://www.vmssoftware.com>
1033
1034   VOS
1035       Perl on VOS (also known as OpenVOS) is discussed in README.vos in the
1036       Perl distribution (installed as perlvos).  Perl on VOS can accept
1037       either VOS- or Unix-style file specifications as in either of the
1038       following:
1039
1040           $ perl -ne "print if /perl_setup/i" >system>notices
1041           $ perl -ne "print if /perl_setup/i" /system/notices
1042
1043       or even a mixture of both as in:
1044
1045           $ perl -ne "print if /perl_setup/i" >system/notices
1046
1047       Even though VOS allows the slash character to appear in object names,
1048       because the VOS port of Perl interprets it as a pathname delimiting
1049       character, VOS files, directories, or links whose names contain a slash
1050       character cannot be processed.  Such files must be renamed before they
1051       can be processed by Perl.
1052
1053       Older releases of VOS (prior to OpenVOS Release 17.0) limit file names
1054       to 32 or fewer characters, prohibit file names from starting with a "-"
1055       character, and prohibit file names from containing " " (space) or any
1056       character from the set "!#%&'()*;<=>?".
1057
1058       Newer releases of VOS (OpenVOS Release 17.0 or later) support a feature
1059       known as extended names.  On these releases, file names can contain up
1060       to 255 characters, are prohibited from starting with a "-" character,
1061       and the set of prohibited characters is reduced to "#%*<>?".  There are
1062       restrictions involving spaces and apostrophes:  these characters must
1063       not begin or end a name, nor can they immediately precede or follow a
1064       period.  Additionally, a space must not immediately precede another
1065       space or hyphen.  Specifically, the following character combinations
1066       are prohibited:  space-space, space-hyphen, period-space, space-period,
1067       period-apostrophe, apostrophe-period, leading or trailing space, and
1068       leading or trailing apostrophe.  Although an extended file name is
1069       limited to 255 characters, a path name is still limited to 256
1070       characters.
1071
1072       The value of $^O on VOS is "vos".  To determine the architecture that
1073       you are running on refer to $Config{archname}.
1074
1075       Also see:
1076
1077README.vos (installed as perlvos)
1078
1079       •   The VOS mailing list.
1080
1081           There is no specific mailing list for Perl on VOS.  You can contact
1082           the Stratus Technologies Customer Assistance Center (CAC) for your
1083           region, or you can use the contact information located in the
1084           distribution files on the Stratus Anonymous FTP site.
1085
1086       •   Stratus Technologies on the web at <http://www.stratus.com>
1087
1088       •   VOS Open-Source Software on the web at
1089           <http://ftp.stratus.com/pub/vos/vos.html>
1090
1091   EBCDIC Platforms
1092       v5.22 core Perl runs on z/OS (formerly OS/390).  Theoretically it could
1093       run on the successors of OS/400 on AS/400 minicomputers as well as
1094       VM/ESA, and BS2000 for S/390 Mainframes.  Such computers use EBCDIC
1095       character sets internally (usually Character Code Set ID 0037 for
1096       OS/400 and either 1047 or POSIX-BC for S/390 systems).
1097
1098       The rest of this section may need updating, but we don't know what it
1099       should say.  Please submit comments to
1100       <https://github.com/Perl/perl5/issues>.
1101
1102       On the mainframe Perl currently works under the "Unix system services
1103       for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or the
1104       BS200 POSIX-BC system (BS2000 is supported in Perl 5.6 and greater).
1105       See perlos390 for details.  Note that for OS/400 there is also a port
1106       of Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as
1107       opposed to ILE which is EBCDIC-based), see perlos400.
1108
1109       As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix sub-
1110       systems do not support the "#!" shebang trick for script invocation.
1111       Hence, on OS/390 and VM/ESA Perl scripts can be executed with a header
1112       similar to the following simple script:
1113
1114           : # use perl
1115               eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
1116                   if 0;
1117           #!/usr/local/bin/perl     # just a comment really
1118
1119           print "Hello from perl!\n";
1120
1121       OS/390 will support the "#!" shebang trick in release 2.8 and beyond.
1122       Calls to "system" and backticks can use POSIX shell syntax on all S/390
1123       systems.
1124
1125       On the AS/400, if PERL5 is in your library list, you may need to wrap
1126       your Perl scripts in a CL procedure to invoke them like so:
1127
1128           BEGIN
1129             CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1130           ENDPGM
1131
1132       This will invoke the Perl script hello.pl in the root of the QOpenSys
1133       file system.  On the AS/400 calls to "system" or backticks must use CL
1134       syntax.
1135
1136       On these platforms, bear in mind that the EBCDIC character set may have
1137       an effect on what happens with some Perl functions (such as "chr",
1138       "pack", "print", "printf", "ord", "sort", "sprintf", "unpack"), as well
1139       as bit-fiddling with ASCII constants using operators like "^", "&" and
1140       "|", not to mention dealing with socket interfaces to ASCII computers
1141       (see "Newlines").
1142
1143       Fortunately, most web servers for the mainframe will correctly
1144       translate the "\n" in the following statement to its ASCII equivalent
1145       ("\r" is the same under both Unix and z/OS):
1146
1147           print "Content-type: text/html\r\n\r\n";
1148
1149       The values of $^O on some of these platforms include:
1150
1151           uname         $^O        $Config{archname}
1152           --------------------------------------------
1153           OS/390        os390      os390
1154           OS400         os400      os400
1155           POSIX-BC      posix-bc   BS2000-posix-bc
1156
1157       Some simple tricks for determining if you are running on an EBCDIC
1158       platform could include any of the following (perhaps all):
1159
1160           if ("\t" eq "\005")  { print "EBCDIC may be spoken here!\n"; }
1161
1162           if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1163
1164           if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1165
1166       One thing you may not want to rely on is the EBCDIC encoding of
1167       punctuation characters since these may differ from code page to code
1168       page (and once your module or script is rumoured to work with EBCDIC,
1169       folks will want it to work with all EBCDIC character sets).
1170
1171       Also see:
1172
1173       •   perlos390, perlos400, perlbs2000, perlebcdic.
1174
1175       •   The perl-mvs@perl.org list is for discussion of porting issues as
1176           well as general usage issues for all EBCDIC Perls.  Send a message
1177           body of "subscribe perl-mvs" to majordomo@perl.org.
1178
1179       •   AS/400 Perl information at <http://as400.rochester.ibm.com/> as
1180           well as on CPAN in the ports/ directory.
1181
1182   Acorn RISC OS
1183       Because Acorns use ASCII with newlines ("\n") in text files as "\012"
1184       like Unix, and because Unix filename emulation is turned on by default,
1185       most simple scripts will probably work "out of the box".  The native
1186       filesystem is modular, and individual filesystems are free to be case-
1187       sensitive or insensitive, and are usually case-preserving.  Some native
1188       filesystems have name length limits, which file and directory names are
1189       silently truncated to fit.  Scripts should be aware that the standard
1190       filesystem currently has a name length limit of 10 characters, with up
1191       to 77 items in a directory, but other filesystems may not impose such
1192       limitations.
1193
1194       Native filenames are of the form
1195
1196           Filesystem#Special_Field::DiskName.$.Directory.Directory.File
1197
1198       where
1199
1200           Special_Field is not usually present, but may contain . and $ .
1201           Filesystem =~ m|[A-Za-z0-9_]|
1202           DsicName   =~ m|[A-Za-z0-9_/]|
1203           $ represents the root directory
1204           . is the path separator
1205           @ is the current directory (per filesystem but machine global)
1206           ^ is the parent directory
1207           Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1208
1209       The default filename translation is roughly "tr|/.|./|", swapping dots
1210       and slashes.
1211
1212       Note that ""ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'" and that
1213       the second stage of "$" interpolation in regular expressions will fall
1214       foul of the $. variable if scripts are not careful.
1215
1216       Logical paths specified by system variables containing comma-separated
1217       search lists are also allowed; hence "System:Modules" is a valid
1218       filename, and the filesystem will prefix "Modules" with each section of
1219       "System$Path" until a name is made that points to an object on disk.
1220       Writing to a new file "System:Modules" would be allowed only if
1221       "System$Path" contains a single item list.  The filesystem will also
1222       expand system variables in filenames if enclosed in angle brackets, so
1223       "<System$Dir>.Modules" would look for the file
1224       "$ENV{'System$Dir'} . 'Modules'".  The obvious implication of this is
1225       that fully qualified filenames can start with "<>" and the three-
1226       argument form of "open" should always be used.
1227
1228       Because "." was in use as a directory separator and filenames could not
1229       be assumed to be unique after 10 characters, Acorn implemented the C
1230       compiler to strip the trailing ".c" ".h" ".s" and ".o" suffix from
1231       filenames specified in source code and store the respective files in
1232       subdirectories named after the suffix.  Hence files are translated:
1233
1234           foo.h           h.foo
1235           C:foo.h         C:h.foo        (logical path variable)
1236           sys/os.h        sys.h.os       (C compiler groks Unix-speak)
1237           10charname.c    c.10charname
1238           10charname.o    o.10charname
1239           11charname_.c   c.11charname   (assuming filesystem truncates at 10)
1240
1241       The Unix emulation library's translation of filenames to native assumes
1242       that this sort of translation is required, and it allows a user-defined
1243       list of known suffixes that it will transpose in this fashion.  This
1244       may seem transparent, but consider that with these rules foo/bar/baz.h
1245       and foo/bar/h/baz both map to foo.bar.h.baz, and that "readdir" and
1246       "glob" cannot and do not attempt to emulate the reverse mapping.  Other
1247       "."'s in filenames are translated to "/".
1248
1249       As implied above, the environment accessed through %ENV is global, and
1250       the convention is that program specific environment variables are of
1251       the form "Program$Name".  Each filesystem maintains a current
1252       directory, and the current filesystem's current directory is the global
1253       current directory.  Consequently, sociable programs don't change the
1254       current directory but rely on full pathnames, and programs (and
1255       Makefiles) cannot assume that they can spawn a child process which can
1256       change the current directory without affecting its parent (and everyone
1257       else for that matter).
1258
1259       Because native operating system filehandles are global and are
1260       currently allocated down from 255, with 0 being a reserved value, the
1261       Unix emulation library emulates Unix filehandles.  Consequently, you
1262       can't rely on passing "STDIN", "STDOUT", or "STDERR" to your children.
1263
1264       The desire of users to express filenames of the form "<Foo$Dir>.Bar" on
1265       the command line unquoted causes problems, too: `` command output
1266       capture has to perform a guessing game.  It assumes that a string
1267       "<[^<>]+\$[^<>]>" is a reference to an environment variable, whereas
1268       anything else involving "<" or ">" is redirection, and generally
1269       manages to be 99% right.  Of course, the problem remains that scripts
1270       cannot rely on any Unix tools being available, or that any tools found
1271       have Unix-like command line arguments.
1272
1273       Extensions and XS are, in theory, buildable by anyone using free tools.
1274       In practice, many don't, as users of the Acorn platform are used to
1275       binary distributions.  MakeMaker does run, but no available make
1276       currently copes with MakeMaker's makefiles; even if and when this
1277       should be fixed, the lack of a Unix-like shell will cause problems with
1278       makefile rules, especially lines of the form "cd sdbm && make all", and
1279       anything using quoting.
1280
1281       "RISC OS" is the proper name for the operating system, but the value in
1282       $^O is "riscos" (because we don't like shouting).
1283
1284   Other perls
1285       Perl has been ported to many platforms that do not fit into any of the
1286       categories listed above.  Some, such as AmigaOS, QNX, Plan 9, and VOS,
1287       have been well-integrated into the standard Perl source code kit.  You
1288       may need to see the ports/ directory on CPAN for information, and
1289       possibly binaries, for the likes of: aos, Atari ST, lynxos, riscos,
1290       Novell Netware, Tandem Guardian, etc.  (Yes, we know that some of these
1291       OSes may fall under the Unix category, but we are not a standards
1292       body.)
1293
1294       Some approximate operating system names and their $^O values in the
1295       "OTHER" category include:
1296
1297           OS            $^O        $Config{archname}
1298           ------------------------------------------
1299           Amiga DOS     amigaos    m68k-amigos
1300
1301       See also:
1302
1303       •   Amiga, README.amiga (installed as perlamiga).
1304
1305       •   Plan 9, README.plan9
1306

FUNCTION IMPLEMENTATIONS

1308       Listed below are functions that are either completely unimplemented or
1309       else have been implemented differently on various platforms.  Preceding
1310       each description will be, in parentheses, a list of platforms that the
1311       description applies to.
1312
1313       The list may well be incomplete, or even wrong in some places.  When in
1314       doubt, consult the platform-specific README files in the Perl source
1315       distribution, and any other documentation resources accompanying a
1316       given port.
1317
1318       Be aware, moreover, that even among Unix-ish systems there are
1319       variations.
1320
1321       For many functions, you can also query %Config, exported by default
1322       from the "Config" module.  For example, to check whether the platform
1323       has the "lstat" call, check $Config{d_lstat}.  See Config for a full
1324       description of available variables.
1325
1326   Alphabetical Listing of Perl Functions
1327       -X      (Win32) "-w" only inspects the read-only file attribute
1328               (FILE_ATTRIBUTE_READONLY), which determines whether the
1329               directory can be deleted, not whether it can be written to.
1330               Directories always have read and write access unless denied by
1331               discretionary access control lists (DACLs).
1332
1333               (VMS) "-r", "-w", "-x", and "-o" tell whether the file is
1334               accessible, which may not reflect UIC-based file protections.
1335
1336               (RISC OS) "-s" by name on an open file will return the space
1337               reserved on disk, rather than the current extent.  "-s" on an
1338               open filehandle returns the current size.
1339
1340               (Win32, VMS, RISC OS) "-R", "-W", "-X", "-O" are
1341               indistinguishable from "-r", "-w", "-x", "-o".
1342
1343               (Win32, VMS, RISC OS) "-g", "-k", "-l", "-u", "-A" are not
1344               particularly meaningful.
1345
1346               (Win32) "-l" returns true for both symlinks and directory
1347               junctions.
1348
1349               (VMS, RISC OS) "-p" is not particularly meaningful.
1350
1351               (VMS) "-d" is true if passed a device spec without an explicit
1352               directory.
1353
1354               (Win32) "-x" (or "-X") determine if a file ends in one of the
1355               executable suffixes.  "-S" is meaningless.
1356
1357               (RISC OS) "-x" (or "-X") determine if a file has an executable
1358               file type.
1359
1360       alarm   (Win32) Emulated using timers that must be explicitly polled
1361               whenever Perl wants to dispatch "safe signals" and therefore
1362               cannot interrupt blocking system calls.
1363
1364       atan2   (Tru64, HP-UX 10.20) Due to issues with various CPUs, math
1365               libraries, compilers, and standards, results for "atan2" may
1366               vary depending on any combination of the above.  Perl attempts
1367               to conform to the Open Group/IEEE standards for the results
1368               returned from "atan2", but cannot force the issue if the system
1369               Perl is run on does not allow it.
1370
1371               The current version of the standards for "atan2" is available
1372               at
1373               <http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
1374
1375       binmode (RISC OS) Meaningless.
1376
1377               (VMS) Reopens file and restores pointer; if function fails,
1378               underlying filehandle may be closed, or pointer may be in a
1379               different position.
1380
1381               (Win32) The value returned by "tell" may be affected after the
1382               call, and the filehandle may be flushed.
1383
1384       chdir   (Win32) The current directory reported by the system may
1385               include any symbolic links specified to chdir().
1386
1387       chmod   (Win32) Only good for changing "owner" read-write access;
1388               "group" and "other" bits are meaningless.
1389
1390               (RISC OS) Only good for changing "owner" and "other" read-write
1391               access.
1392
1393               (VOS) Access permissions are mapped onto VOS access-control
1394               list changes.
1395
1396               (Cygwin) The actual permissions set depend on the value of the
1397               "CYGWIN" variable in the SYSTEM environment settings.
1398
1399               (Android) Setting the exec bit on some locations (generally
1400               /sdcard) will return true but not actually set the bit.
1401
1402               (VMS) A mode argument of zero sets permissions to the user's
1403               default permission mask rather than disabling all permissions.
1404
1405       chown   (Plan 9, RISC OS) Not implemented.
1406
1407               (Win32) Does nothing, but won't fail.
1408
1409               (VOS) A little funky, because VOS's notion of ownership is a
1410               little funky.
1411
1412       chroot  (Win32, VMS, Plan 9, RISC OS, VOS) Not implemented.
1413
1414       crypt   (Win32) May not be available if library or source was not
1415               provided when building perl.
1416
1417               (Android) Not implemented.
1418
1419       dbmclose
1420               (VMS, Plan 9, VOS) Not implemented.
1421
1422       dbmopen (VMS, Plan 9, VOS) Not implemented.
1423
1424       dump    (RISC OS) Not useful.
1425
1426               (Cygwin, Win32) Not supported.
1427
1428               (VMS) Invokes VMS debugger.
1429
1430       exec    (Win32) "exec LIST" without the use of indirect object syntax
1431               ("exec PROGRAM LIST") may fall back to trying the shell if the
1432               first spawn() fails.
1433
1434               Note that the list form of exec() is emulated since the Win32
1435               API CreateProcess() accepts a simple string rather than an
1436               array of command-line arguments.  This may have security
1437               implications for your code.
1438
1439               (SunOS, Solaris, HP-UX) Does not automatically flush output
1440               handles on some platforms.
1441
1442       exit    (VMS) Emulates Unix "exit" (which considers "exit 1" to
1443               indicate an error) by mapping the 1 to "SS$_ABORT" (44).  This
1444               behavior may be overridden with the pragma "use vmsish 'exit'".
1445               As with the CRTL's exit() function, "exit 0" is also mapped to
1446               an exit status of "SS$_NORMAL" (1); this mapping cannot be
1447               overridden.  Any other argument to "exit" is used directly as
1448               Perl's exit status.  On VMS, unless the future POSIX_EXIT mode
1449               is enabled, the exit code should always be a valid VMS exit
1450               code and not a generic number.  When the POSIX_EXIT mode is
1451               enabled, a generic number will be encoded in a method
1452               compatible with the C library _POSIX_EXIT macro so that it can
1453               be decoded by other programs, particularly ones written in C,
1454               like the GNV package.
1455
1456               (Solaris) "exit" resets file pointers, which is a problem when
1457               called from a child process (created by "fork") in "BEGIN".  A
1458               workaround is to use "POSIX::_exit".
1459
1460                   exit unless $Config{archname} =~ /\bsolaris\b/;
1461                   require POSIX;
1462                   POSIX::_exit(0);
1463
1464       fcntl   (Win32) Not implemented.
1465
1466               (VMS) Some functions available based on the version of VMS.
1467
1468       flock   (VMS, RISC OS, VOS) Not implemented.
1469
1470       fork    (AmigaOS, RISC OS, VMS) Not implemented.
1471
1472               (Win32) Emulated using multiple interpreters.  See perlfork.
1473
1474               (SunOS, Solaris, HP-UX) Does not automatically flush output
1475               handles on some platforms.
1476
1477       getlogin
1478               (RISC OS) Not implemented.
1479
1480       getpgrp (Win32, VMS, RISC OS) Not implemented.
1481
1482       getppid (Win32, RISC OS) Not implemented.
1483
1484       getpriority
1485               (Win32, VMS, RISC OS, VOS) Not implemented.
1486
1487       getpwnam
1488               (Win32) Not implemented.
1489
1490               (RISC OS) Not useful.
1491
1492       getgrnam
1493               (Win32, VMS, RISC OS) Not implemented.
1494
1495       getnetbyname
1496               (Android, Win32, Plan 9) Not implemented.
1497
1498       getpwuid
1499               (Win32) Not implemented.
1500
1501               (RISC OS) Not useful.
1502
1503       getgrgid
1504               (Win32, VMS, RISC OS) Not implemented.
1505
1506       getnetbyaddr
1507               (Android, Win32, Plan 9) Not implemented.
1508
1509       getprotobynumber
1510               (Android) Not implemented.
1511
1512       getpwent
1513               (Android, Win32) Not implemented.
1514
1515       getgrent
1516               (Android, Win32, VMS) Not implemented.
1517
1518       gethostbyname
1519               (Irix 5) gethostbyname('localhost') does not work everywhere:
1520               you may have to use gethostbyname('127.0.0.1').
1521
1522       gethostent
1523               (Win32) Not implemented.
1524
1525       getnetent
1526               (Android, Win32, Plan 9) Not implemented.
1527
1528       getprotoent
1529               (Android, Win32, Plan 9) Not implemented.
1530
1531       getservent
1532               (Win32, Plan 9) Not implemented.
1533
1534       seekdir (Android) Not implemented.
1535
1536       sethostent
1537               (Android, Win32, Plan 9, RISC OS) Not implemented.
1538
1539       setnetent
1540               (Win32, Plan 9, RISC OS) Not implemented.
1541
1542       setprotoent
1543               (Android, Win32, Plan 9, RISC OS) Not implemented.
1544
1545       setservent
1546               (Plan 9, Win32, RISC OS) Not implemented.
1547
1548       endpwent
1549               (Win32) Not implemented.
1550
1551               (Android) Either not implemented or a no-op.
1552
1553       endgrent
1554               (Android, RISC OS, VMS, Win32) Not implemented.
1555
1556       endhostent
1557               (Android, Win32) Not implemented.
1558
1559       endnetent
1560               (Android, Win32, Plan 9) Not implemented.
1561
1562       endprotoent
1563               (Android, Win32, Plan 9) Not implemented.
1564
1565       endservent
1566               (Plan 9, Win32) Not implemented.
1567
1568       getsockopt
1569               (Plan 9) Not implemented.
1570
1571       glob    This operator is implemented via the "File::Glob" extension on
1572               most platforms.  See File::Glob for portability information.
1573
1574       gmtime  In theory, "gmtime" is reliable from -2**63 to 2**63-1.
1575               However, because work-arounds in the implementation use
1576               floating point numbers, it will become inaccurate as the time
1577               gets larger.  This is a bug and will be fixed in the future.
1578
1579               (VOS) Time values are 32-bit quantities.
1580
1581       ioctl   (VMS) Not implemented.
1582
1583               (Win32) Available only for socket handles, and it does what the
1584               ioctlsocket() call in the Winsock API does.
1585
1586               (RISC OS) Available only for socket handles.
1587
1588       kill    (RISC OS) Not implemented, hence not useful for taint checking.
1589
1590               (Win32) "kill" doesn't send a signal to the identified process
1591               like it does on Unix platforms.  Instead "kill($sig, $pid)"
1592               terminates the process identified by $pid, and makes it exit
1593               immediately with exit status $sig.  As in Unix, if $sig is 0
1594               and the specified process exists, it returns true without
1595               actually terminating it.
1596
1597               (Win32) "kill(-9, $pid)" will terminate the process specified
1598               by $pid and recursively all child processes owned by it.  This
1599               is different from the Unix semantics, where the signal will be
1600               delivered to all processes in the same process group as the
1601               process specified by $pid.
1602
1603               (VMS) A pid of -1 indicating all processes on the system is not
1604               currently supported.
1605
1606       link    (RISC OS, VOS) Not implemented.
1607
1608               (AmigaOS) Link count not updated because hard links are not
1609               quite that hard (They are sort of half-way between hard and
1610               soft links).
1611
1612               (Win32) Hard links are implemented on Win32 under NTFS only.
1613               They are natively supported on Windows 2000 and later.  On
1614               Windows NT they are implemented using the Windows POSIX
1615               subsystem support and the Perl process will need Administrator
1616               or Backup Operator privileges to create hard links.
1617
1618               (VMS) Available on 64 bit OpenVMS 8.2 and later.
1619
1620       localtime
1621               "localtime" has the same range as "gmtime", but because time
1622               zone rules change, its accuracy for historical and future times
1623               may degrade but usually by no more than an hour.
1624
1625       lstat   (RISC OS) Not implemented.
1626
1627               (Win32) Treats directory junctions as symlinks.
1628
1629       msgctl
1630       msgget
1631       msgsnd
1632       msgrcv  (Android, Win32, VMS, Plan 9, RISC OS, VOS) Not implemented.
1633
1634       open    (RISC OS) Open modes "|-" and "-|" are unsupported.
1635
1636               (SunOS, Solaris, HP-UX) Opening a process does not
1637               automatically flush output handles on some platforms.
1638
1639               (Win32) Both of modes "|-" and "-|" are supported, but the list
1640               form is emulated since the Win32 API CreateProcess() accepts a
1641               simple string rather than an array of arguments.  This may have
1642               security implications for your code.
1643
1644       readlink
1645               (VMS, RISC OS) Not implemented.
1646
1647               (Win32) readlink() on a directory junction returns the object
1648               name, not a simple path.
1649
1650       rename  (Win32) Can't move directories between directories on different
1651               logical volumes.
1652
1653       rewinddir
1654               (Win32) Will not cause "readdir" to re-read the directory
1655               stream.  The entries already read before the "rewinddir" call
1656               will just be returned again from a cache buffer.
1657
1658       select  (Win32, VMS) Only implemented on sockets.
1659
1660               (RISC OS) Only reliable on sockets.
1661
1662               Note that the "select FILEHANDLE" form is generally portable.
1663
1664       semctl
1665       semget
1666       semop   (Android, Win32, VMS, RISC OS) Not implemented.
1667
1668       setgrent
1669               (Android, VMS, Win32, RISC OS) Not implemented.
1670
1671       setpgrp (Win32, VMS, RISC OS, VOS) Not implemented.
1672
1673       setpriority
1674               (Win32, VMS, RISC OS, VOS) Not implemented.
1675
1676       setpwent
1677               (Android, Win32, RISC OS) Not implemented.
1678
1679       setsockopt
1680               (Plan 9) Not implemented.
1681
1682       shmctl
1683       shmget
1684       shmread
1685       shmwrite
1686               (Android, Win32, VMS, RISC OS) Not implemented.
1687
1688       sleep   (Win32) Emulated using synchronization functions such that it
1689               can be interrupted by "alarm", and limited to a maximum of
1690               4294967 seconds, approximately 49 days.
1691
1692       socketpair
1693               (RISC OS) Not implemented.
1694
1695               (VMS) Available on 64 bit OpenVMS 8.2 and later.
1696
1697       stat    Platforms that do not have "rdev", "blksize", or "blocks" will
1698               return these as '', so numeric comparison or manipulation of
1699               these fields may cause 'not numeric' warnings.
1700
1701               (Mac OS X) "ctime" not supported on UFS.
1702
1703               (Win32) "ctime" is creation time instead of inode change time.
1704
1705               (VMS) "dev" and "ino" are not necessarily reliable.
1706
1707               (RISC OS) "mtime", "atime" and "ctime" all return the last
1708               modification time.  "dev" and "ino" are not necessarily
1709               reliable.
1710
1711               (OS/2) "dev", "rdev", "blksize", and "blocks" are not
1712               available.  "ino" is not meaningful and will differ between
1713               stat calls on the same file.
1714
1715               (Cygwin) Some versions of cygwin when doing a stat("foo") and
1716               not finding it may then attempt to stat("foo.exe").
1717
1718       symlink (RISC OS) Not implemented.
1719
1720               (Win32) Requires either elevated permissions or developer mode
1721               and a sufficiently recent version of Windows 10. You can check
1722               whether the current process has the required privileges using
1723               the Win32::IsSymlinkCreationAllowed() function.
1724
1725               Since Windows needs to know whether the target is a directory
1726               or not when creating the link the target Perl will only create
1727               the link as a directory link when the target exists and is a
1728               directory.
1729
1730               Windows does not recognize forward slashes as path separators
1731               in symbolic links.  Hence on Windows, any "/" in the OLDFILE
1732               parameter to symlink() are converted to "\".  This is reflected
1733               in the result returned by readlink(), the "\" in the result are
1734               not converted back to "/".
1735
1736               (VMS) Implemented on 64 bit VMS 8.3.  VMS requires the symbolic
1737               link to be in Unix syntax if it is intended to resolve to a
1738               valid path.
1739
1740       syscall (Win32, VMS, RISC OS, VOS) Not implemented.
1741
1742       sysopen (Mac OS, OS/390) The traditional 0, 1, and 2 MODEs are
1743               implemented with different numeric values on some systems.  The
1744               flags exported by "Fcntl" ("O_RDONLY", "O_WRONLY", "O_RDWR")
1745               should work everywhere though.
1746
1747       system  (Win32) As an optimization, may not call the command shell
1748               specified in $ENV{PERL5SHELL}.  "system(1, @args)" spawns an
1749               external process and immediately returns its process
1750               designator, without waiting for it to terminate.  Return value
1751               may be used subsequently in "wait" or "waitpid".  Failure to
1752               spawn() a subprocess is indicated by setting $? to "255 << 8".
1753               $? is set in a way compatible with Unix (i.e. the exit status
1754               of the subprocess is obtained by "$? >> 8", as described in the
1755               documentation).
1756
1757               Note that the list form of system() is emulated since the Win32
1758               API CreateProcess() accepts a simple string rather than an
1759               array of command-line arguments.  This may have security
1760               implications for your code.
1761
1762               (RISC OS) There is no shell to process metacharacters, and the
1763               native standard is to pass a command line terminated by "\n"
1764               "\r" or "\0" to the spawned program.  Redirection such as ">
1765               foo" is performed (if at all) by the run time library of the
1766               spawned program.  "system LIST" will call the Unix emulation
1767               library's "exec" emulation, which attempts to provide emulation
1768               of the stdin, stdout, stderr in force in the parent, provided
1769               the child program uses a compatible version of the emulation
1770               library.  "system SCALAR" will call the native command line
1771               directly and no such emulation of a child Unix program will
1772               occur.  Mileage will vary.
1773
1774               (Win32) "system LIST" without the use of indirect object syntax
1775               ("system PROGRAM LIST") may fall back to trying the shell if
1776               the first spawn() fails.
1777
1778               (SunOS, Solaris, HP-UX) Does not automatically flush output
1779               handles on some platforms.
1780
1781               (VMS) As with Win32, "system(1, @args)" spawns an external
1782               process and immediately returns its process designator without
1783               waiting for the process to terminate.  In this case the return
1784               value may be used subsequently in "wait" or "waitpid".
1785               Otherwise the return value is POSIX-like (shifted up by 8
1786               bits), which only allows room for a made-up value derived from
1787               the severity bits of the native 32-bit condition code (unless
1788               overridden by "use vmsish 'status'").  If the native condition
1789               code is one that has a POSIX value encoded, the POSIX value
1790               will be decoded to extract the expected exit value.  For more
1791               details see "$?" in perlvms.
1792
1793       telldir (Android) Not implemented.
1794
1795       times   (Win32) "Cumulative" times will be bogus.  On anything other
1796               than Windows NT or Windows 2000, "system" time will be bogus,
1797               and "user" time is actually the time returned by the clock()
1798               function in the C runtime library.
1799
1800               (RISC OS) Not useful.
1801
1802       truncate
1803               (Older versions of VMS) Not implemented.
1804
1805               (VOS) Truncation to same-or-shorter lengths only.
1806
1807               (Win32) If a FILEHANDLE is supplied, it must be writable and
1808               opened in append mode (i.e., use "open(my $fh, '>>',
1809               'filename')" or "sysopen(my $fh, ..., O_APPEND|O_RDWR)".  If a
1810               filename is supplied, it should not be held open elsewhere.
1811
1812       umask   Returns "undef" where unavailable.
1813
1814               (AmigaOS) "umask" works but the correct permissions are set
1815               only when the file is finally closed.
1816
1817       utime   (VMS, RISC OS) Only the modification time is updated.
1818
1819               (Win32) May not behave as expected.  Behavior depends on the C
1820               runtime library's implementation of utime(), and the filesystem
1821               being used.  The FAT filesystem typically does not support an
1822               "access time" field, and it may limit timestamps to a
1823               granularity of two seconds.
1824
1825       wait
1826       waitpid (Win32) Can only be applied to process handles returned for
1827               processes spawned using "system(1, ...)" or pseudo processes
1828               created with "fork".
1829
1830               (RISC OS) Not useful.
1831

Supported Platforms

1833       The following platforms are known to build Perl 5.12 (as of April 2010,
1834       its release date) from the standard source code distribution available
1835       at <http://www.cpan.org/src>
1836
1837       Linux (x86, ARM, IA64)
1838       HP-UX
1839       AIX
1840       Win32
1841           Windows 2000
1842           Windows XP
1843           Windows Server 2003
1844           Windows Vista
1845           Windows Server 2008
1846           Windows 7
1847       Cygwin
1848           Some tests are known to fail:
1849
1850ext/XS-APItest/t/call_checker.t - see
1851               <https://github.com/Perl/perl5/issues/10750>
1852
1853dist/I18N-Collate/t/I18N-Collate.t
1854
1855ext/Win32CORE/t/win32core.t - may fail on recent cygwin
1856               installs.
1857
1858       Solaris (x86, SPARC)
1859       OpenVMS
1860           Alpha (7.2 and later)
1861           I64 (8.2 and later)
1862       NetBSD
1863       FreeBSD
1864       Debian GNU/kFreeBSD
1865       Haiku
1866       Irix (6.5. What else?)
1867       OpenBSD
1868       Dragonfly BSD
1869       Midnight BSD
1870       QNX Neutrino RTOS (6.5.0)
1871       MirOS BSD
1872       Stratus OpenVOS (17.0 or later)
1873           Caveats:
1874
1875           time_t issues that may or may not be fixed
1876       Stratus VOS / OpenVOS
1877       AIX
1878       Android
1879       FreeMINT
1880           Perl now builds with FreeMiNT/Atari. It fails a few tests, that
1881           needs some investigation.
1882
1883           The FreeMiNT port uses GNU dld for loadable module capabilities. So
1884           ensure you have that library installed when building perl.
1885

EOL Platforms

1887   (Perl 5.37.1)
1888       The following platforms were supported by a previous version of Perl
1889       but have been officially removed from Perl's source code as of 5.37.1:
1890
1891       Ultrix
1892
1893   (Perl 5.36)
1894       The following platforms were supported by a previous version of Perl
1895       but have been officially removed from Perl's source code as of 5.36:
1896
1897       NetWare
1898       DOS/DJGPP
1899       AT&T UWIN
1900
1901   (Perl 5.20)
1902       The following platforms were supported by a previous version of Perl
1903       but have been officially removed from Perl's source code as of 5.20:
1904
1905       AT&T 3b1
1906
1907   (Perl 5.14)
1908       The following platforms were supported up to 5.10.  They may still have
1909       worked in 5.12, but supporting code has been removed for 5.14:
1910
1911       Windows 95
1912       Windows 98
1913       Windows ME
1914       Windows NT4
1915
1916   (Perl 5.12)
1917       The following platforms were supported by a previous version of Perl
1918       but have been officially removed from Perl's source code as of 5.12:
1919
1920       Atari MiNT
1921       Apollo Domain/OS
1922       Apple Mac OS 8/9
1923       Tenon Machten
1924

Supported Platforms (Perl 5.8)

1926       As of July 2002 (the Perl release 5.8.0), the following platforms were
1927       able to build Perl from the standard source code distribution available
1928       at <http://www.cpan.org/src/>
1929
1930               AIX
1931               BeOS
1932               BSD/OS          (BSDi)
1933               Cygwin
1934               DG/UX
1935               DOS DJGPP       1)
1936               DYNIX/ptx
1937               EPOC R5
1938               FreeBSD
1939               HI-UXMPP        (Hitachi) (5.8.0 worked but we didn't know it)
1940               HP-UX
1941               IRIX
1942               Linux
1943               Mac OS Classic
1944               Mac OS X        (Darwin)
1945               MPE/iX
1946               NetBSD
1947               NetWare
1948               NonStop-UX
1949               ReliantUNIX     (formerly SINIX)
1950               OpenBSD
1951               OpenVMS         (formerly VMS)
1952               Open UNIX       (Unixware) (since Perl 5.8.1/5.9.0)
1953               OS/2
1954               OS/400          (using the PASE) (since Perl 5.8.1/5.9.0)
1955               POSIX-BC        (formerly BS2000)
1956               QNX
1957               Solaris
1958               SunOS 4
1959               SUPER-UX        (NEC)
1960               Tru64 UNIX      (formerly DEC OSF/1, Digital UNIX)
1961               UNICOS
1962               UNICOS/mk
1963               UTS
1964               VOS / OpenVOS
1965               Win95/98/ME/2K/XP 2)
1966               WinCE
1967               z/OS            (formerly OS/390)
1968               VM/ESA
1969
1970               1) in DOS mode either the DOS or OS/2 ports can be used
1971               2) compilers: Borland, MinGW (GCC), VC6
1972
1973       The following platforms worked with the previous releases (5.6 and
1974       5.7), but we did not manage either to fix or to test these in time for
1975       the 5.8.0 release.  There is a very good chance that many of these will
1976       work fine with the 5.8.0.
1977
1978               BSD/OS
1979               DomainOS
1980               Hurd
1981               LynxOS
1982               MachTen
1983               PowerMAX
1984               SCO SV
1985               SVR4
1986               Unixware
1987               Windows 3.1
1988
1989       Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
1990
1991               AmigaOS 3
1992
1993       The following platforms have been known to build Perl from source in
1994       the past (5.005_03 and earlier), but we haven't been able to verify
1995       their status for the current release, either because the
1996       hardware/software platforms are rare or because we don't have an active
1997       champion on these platforms--or both.  They used to work, though, so go
1998       ahead and try compiling them, and let
1999       <https://github.com/Perl/perl5/issues> know of any trouble.
2000
2001               3b1
2002               A/UX
2003               ConvexOS
2004               CX/UX
2005               DC/OSx
2006               DDE SMES
2007               DOS EMX
2008               Dynix
2009               EP/IX
2010               ESIX
2011               FPS
2012               GENIX
2013               Greenhills
2014               ISC
2015               MachTen 68k
2016               MPC
2017               NEWS-OS
2018               NextSTEP
2019               OpenSTEP
2020               Opus
2021               Plan 9
2022               RISC/os
2023               SCO ODT/OSR
2024               Stellar
2025               SVR2
2026               TI1500
2027               TitanOS
2028               Unisys Dynix
2029
2030       The following platforms have their own source code distributions and
2031       binaries available via <http://www.cpan.org/ports/>
2032
2033                                       Perl release
2034
2035               OS/400 (ILE)            5.005_02
2036               Tandem Guardian         5.004
2037
2038       The following platforms have only binaries available via
2039       <http://www.cpan.org/ports/index.html> :
2040
2041                                       Perl release
2042
2043               Acorn RISCOS            5.005_02
2044               AOS                     5.002
2045               LynxOS                  5.004_02
2046
2047       Although we do suggest that you always build your own Perl from the
2048       source code, both for maximal configurability and for security, in case
2049       you are in a hurry you can check <http://www.cpan.org/ports/index.html>
2050       for binary distributions.
2051

SEE ALSO

2053       perlaix, perlamiga, perlbs2000, perlcygwin, perlebcdic, perlfreebsd,
2054       perlhurd, perlhpux, perlirix, perlmacosx, perlos2, perlos390,
2055       perlos400, perlplan9, perlqnx, perlsolaris, perltru64, perlunicode,
2056       perlvms, perlvos, perlwin32, and Win32.
2057

AUTHORS / CONTRIBUTORS

2059       Abigail <abigail@abigail.be>, Charles Bailey <bailey@newman.upenn.edu>,
2060       Graham Barr <gbarr@pobox.com>, Tom Christiansen <tchrist@perl.com>,
2061       Nicholas Clark <nick@ccl4.org>, Thomas Dorner <Thomas.Dorner@start.de>,
2062       Andy Dougherty <doughera@lafayette.edu>, Dominic Dunlop
2063       <domo@computer.org>, Neale Ferguson <neale@vma.tabnsw.com.au>, David J.
2064       Fiander <davidf@mks.com>, Paul Green <Paul.Green@stratus.com>, M.J.T.
2065       Guy <mjtg@cam.ac.uk>, Jarkko Hietaniemi <jhi@iki.fi>, Luther Huffman
2066       <lutherh@stratcom.com>, Nick Ing-Simmons <nick@ing-simmons.net>,
2067       Andreas J. König <a.koenig@mind.de>, Markus Laker
2068       <mlaker@contax.co.uk>, Andrew M. Langmead <aml@world.std.com>, Lukas
2069       Mai <l.mai@web.de>, Larry Moore <ljmoore@freespace.net>, Paul Moore
2070       <Paul.Moore@uk.origin-it.com>, Chris Nandor <pudge@pobox.com>, Matthias
2071       Neeracher <neeracher@mac.com>, Philip Newton <pne@cpan.org>, Gary Ng
2072       <71564.1743@CompuServe.COM>, Tom Phoenix <rootbeer@teleport.com>, André
2073       Pirard <A.Pirard@ulg.ac.be>, Peter Prymmer <pvhp@forte.com>, Hugo van
2074       der Sanden <hv@crypt0.demon.co.uk>, Gurusamy Sarathy
2075       <gsar@activestate.com>, Paul J. Schinder <schinder@pobox.com>, Michael
2076       G Schwern <schwern@pobox.com>, Dan Sugalski <dan@sidhe.org>, Nathan
2077       Torkington <gnat@frii.com>, John Malmberg <wb8tyw@qsl.net>
2078
2079
2080
2081perl v5.38.2                      2023-11-30                       PERLPORT(1)
Impressum