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       DJGPP, OS/2, and VOS) have required suffixes for executable files;
457       these 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 ae comes before "b".  Unicode::Collate can be used
654       to 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()";
901       try "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 djgpp environment for DOS, <http://www.delorie.com/djgpp/> and
932           perldos.
933
934       •   The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
935           <ftp://hobbes.nmsu.edu/pub/os2/dev/emx/>  Also perlos2.
936
937       •   Build instructions for Win32 in perlwin32, or under the Cygnus
938           environment in perlcygwin.
939
940       •   The "Win32::*" modules in Win32.
941
942       •   The ActiveState Pages, <https://www.activestate.com/>
943
944       •   The Cygwin environment for Win32; README.cygwin (installed as
945           perlcygwin), <https://www.cygwin.com/>
946
947       •   The U/WIN environment for Win32,
948           <http://www.research.att.com/sw/tools/uwin/>
949
950       •   Build instructions for OS/2, perlos2
951
952   VMS
953       Perl on VMS is discussed in perlvms in the Perl distribution.
954
955       The official name of VMS as of this writing is OpenVMS.
956
957       Interacting with Perl from the Digital Command Language (DCL) shell
958       often requires a different set of quotation marks than Unix shells do.
959       For example:
960
961           $ perl -e "print ""Hello, world.\n"""
962           Hello, world.
963
964       There are several ways to wrap your Perl scripts in DCL .COM files, if
965       you are so inclined.  For example:
966
967           $ write sys$output "Hello from DCL!"
968           $ if p1 .eqs. ""
969           $ then perl -x 'f$environment("PROCEDURE")
970           $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
971           $ deck/dollars="__END__"
972           #!/usr/bin/perl
973
974           print "Hello from Perl!\n";
975
976           __END__
977           $ endif
978
979       Do take care with "$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT" if your
980       Perl-in-DCL script expects to do things like "$read = <STDIN>;".
981
982       The VMS operating system has two filesystems, designated by their on-
983       disk structure (ODS) level: ODS-2 and its successor ODS-5.  The initial
984       port of Perl to VMS pre-dates ODS-5, but all current testing and
985       development assumes ODS-5 and its capabilities, including case
986       preservation, extended characters in filespecs, and names up to 8192
987       bytes long.
988
989       Perl on VMS can accept either VMS- or Unix-style file specifications as
990       in either of the following:
991
992           $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
993           $ perl -ne "print if /perl_setup/i" /sys$login/login.com
994
995       but not a mixture of both as in:
996
997           $ perl -ne "print if /perl_setup/i" sys$login:/login.com
998           Can't open sys$login:/login.com: file specification syntax error
999
1000       In general, the easiest path to portability is always to specify
1001       filenames in Unix format unless they will need to be processed by
1002       native commands or utilities.  Because of this latter consideration,
1003       the File::Spec module by default returns native format specifications
1004       regardless of input format.  This default may be reversed so that
1005       filenames are always reported in Unix format by specifying the
1006       "DECC$FILENAME_UNIX_REPORT" feature logical in the environment.
1007
1008       The file type, or extension, is always present in a VMS-format file
1009       specification even if it's zero-length.  This means that, by default,
1010       "readdir" will return a trailing dot on a file with no extension, so
1011       where you would see "a" on Unix you'll see "a." on VMS.  However, the
1012       trailing dot may be suppressed by enabling the
1013       "DECC$READDIR_DROPDOTNOTYPE" feature in the environment (see the CRTL
1014       documentation on feature logical names).
1015
1016       What "\n" represents depends on the type of file opened.  It usually
1017       represents "\012" but it could also be "\015", "\012", "\015\012",
1018       "\000", "\040", or nothing depending on the file organization and
1019       record format.  The "VMS::Stdio" module provides access to the special
1020       "fopen()" requirements of files with unusual attributes on VMS.
1021
1022       The value of $^O on OpenVMS is "VMS".  To determine the architecture
1023       that you are running on refer to $Config{archname}.
1024
1025       On VMS, perl determines the UTC offset from the
1026       "SYS$TIMEZONE_DIFFERENTIAL" logical name.  Although the VMS epoch began
1027       at 17-NOV-1858 00:00:00.00, calls to "localtime" are adjusted to count
1028       offsets from 01-JAN-1970 00:00:00.00, just like Unix.
1029
1030       Also see:
1031
1032README.vms (installed as README_vms), perlvms
1033
1034       •   vmsperl list, vmsperl-subscribe@perl.org
1035
1036       •   vmsperl on the web, <http://www.sidhe.org/vmsperl/index.html>
1037
1038       •   VMS Software Inc. web site, <http://www.vmssoftware.com>
1039
1040   VOS
1041       Perl on VOS (also known as OpenVOS) is discussed in README.vos in the
1042       Perl distribution (installed as perlvos).  Perl on VOS can accept
1043       either VOS- or Unix-style file specifications as in either of the
1044       following:
1045
1046           $ perl -ne "print if /perl_setup/i" >system>notices
1047           $ perl -ne "print if /perl_setup/i" /system/notices
1048
1049       or even a mixture of both as in:
1050
1051           $ perl -ne "print if /perl_setup/i" >system/notices
1052
1053       Even though VOS allows the slash character to appear in object names,
1054       because the VOS port of Perl interprets it as a pathname delimiting
1055       character, VOS files, directories, or links whose names contain a slash
1056       character cannot be processed.  Such files must be renamed before they
1057       can be processed by Perl.
1058
1059       Older releases of VOS (prior to OpenVOS Release 17.0) limit file names
1060       to 32 or fewer characters, prohibit file names from starting with a "-"
1061       character, and prohibit file names from containing " " (space) or any
1062       character from the set "!#%&'()*;<=>?".
1063
1064       Newer releases of VOS (OpenVOS Release 17.0 or later) support a feature
1065       known as extended names.  On these releases, file names can contain up
1066       to 255 characters, are prohibited from starting with a "-" character,
1067       and the set of prohibited characters is reduced to "#%*<>?".  There are
1068       restrictions involving spaces and apostrophes:  these characters must
1069       not begin or end a name, nor can they immediately precede or follow a
1070       period.  Additionally, a space must not immediately precede another
1071       space or hyphen.  Specifically, the following character combinations
1072       are prohibited:  space-space, space-hyphen, period-space, space-period,
1073       period-apostrophe, apostrophe-period, leading or trailing space, and
1074       leading or trailing apostrophe.  Although an extended file name is
1075       limited to 255 characters, a path name is still limited to 256
1076       characters.
1077
1078       The value of $^O on VOS is "vos".  To determine the architecture that
1079       you are running on refer to $Config{archname}.
1080
1081       Also see:
1082
1083README.vos (installed as perlvos)
1084
1085       •   The VOS mailing list.
1086
1087           There is no specific mailing list for Perl on VOS.  You can contact
1088           the Stratus Technologies Customer Assistance Center (CAC) for your
1089           region, or you can use the contact information located in the
1090           distribution files on the Stratus Anonymous FTP site.
1091
1092       •   Stratus Technologies on the web at <http://www.stratus.com>
1093
1094       •   VOS Open-Source Software on the web at
1095           <http://ftp.stratus.com/pub/vos/vos.html>
1096
1097   EBCDIC Platforms
1098       v5.22 core Perl runs on z/OS (formerly OS/390).  Theoretically it could
1099       run on the successors of OS/400 on AS/400 minicomputers as well as
1100       VM/ESA, and BS2000 for S/390 Mainframes.  Such computers use EBCDIC
1101       character sets internally (usually Character Code Set ID 0037 for
1102       OS/400 and either 1047 or POSIX-BC for S/390 systems).
1103
1104       The rest of this section may need updating, but we don't know what it
1105       should say.  Please submit comments to
1106       <https://github.com/Perl/perl5/issues>.
1107
1108       On the mainframe Perl currently works under the "Unix system services
1109       for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or the
1110       BS200 POSIX-BC system (BS2000 is supported in Perl 5.6 and greater).
1111       See perlos390 for details.  Note that for OS/400 there is also a port
1112       of Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as
1113       opposed to ILE which is EBCDIC-based), see perlos400.
1114
1115       As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix sub-
1116       systems do not support the "#!" shebang trick for script invocation.
1117       Hence, on OS/390 and VM/ESA Perl scripts can be executed with a header
1118       similar to the following simple script:
1119
1120           : # use perl
1121               eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
1122                   if 0;
1123           #!/usr/local/bin/perl     # just a comment really
1124
1125           print "Hello from perl!\n";
1126
1127       OS/390 will support the "#!" shebang trick in release 2.8 and beyond.
1128       Calls to "system" and backticks can use POSIX shell syntax on all S/390
1129       systems.
1130
1131       On the AS/400, if PERL5 is in your library list, you may need to wrap
1132       your Perl scripts in a CL procedure to invoke them like so:
1133
1134           BEGIN
1135             CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1136           ENDPGM
1137
1138       This will invoke the Perl script hello.pl in the root of the QOpenSys
1139       file system.  On the AS/400 calls to "system" or backticks must use CL
1140       syntax.
1141
1142       On these platforms, bear in mind that the EBCDIC character set may have
1143       an effect on what happens with some Perl functions (such as "chr",
1144       "pack", "print", "printf", "ord", "sort", "sprintf", "unpack"), as well
1145       as bit-fiddling with ASCII constants using operators like "^", "&" and
1146       "|", not to mention dealing with socket interfaces to ASCII computers
1147       (see "Newlines").
1148
1149       Fortunately, most web servers for the mainframe will correctly
1150       translate the "\n" in the following statement to its ASCII equivalent
1151       ("\r" is the same under both Unix and z/OS):
1152
1153           print "Content-type: text/html\r\n\r\n";
1154
1155       The values of $^O on some of these platforms include:
1156
1157           uname         $^O        $Config{archname}
1158           --------------------------------------------
1159           OS/390        os390      os390
1160           OS400         os400      os400
1161           POSIX-BC      posix-bc   BS2000-posix-bc
1162
1163       Some simple tricks for determining if you are running on an EBCDIC
1164       platform could include any of the following (perhaps all):
1165
1166           if ("\t" eq "\005")  { print "EBCDIC may be spoken here!\n"; }
1167
1168           if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1169
1170           if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1171
1172       One thing you may not want to rely on is the EBCDIC encoding of
1173       punctuation characters since these may differ from code page to code
1174       page (and once your module or script is rumoured to work with EBCDIC,
1175       folks will want it to work with all EBCDIC character sets).
1176
1177       Also see:
1178
1179       •   perlos390, perlos400, perlbs2000, perlebcdic.
1180
1181       •   The perl-mvs@perl.org list is for discussion of porting issues as
1182           well as general usage issues for all EBCDIC Perls.  Send a message
1183           body of "subscribe perl-mvs" to majordomo@perl.org.
1184
1185       •   AS/400 Perl information at <http://as400.rochester.ibm.com/> as
1186           well as on CPAN in the ports/ directory.
1187
1188   Acorn RISC OS
1189       Because Acorns use ASCII with newlines ("\n") in text files as "\012"
1190       like Unix, and because Unix filename emulation is turned on by default,
1191       most simple scripts will probably work "out of the box".  The native
1192       filesystem is modular, and individual filesystems are free to be case-
1193       sensitive or insensitive, and are usually case-preserving.  Some native
1194       filesystems have name length limits, which file and directory names are
1195       silently truncated to fit.  Scripts should be aware that the standard
1196       filesystem currently has a name length limit of 10 characters, with up
1197       to 77 items in a directory, but other filesystems may not impose such
1198       limitations.
1199
1200       Native filenames are of the form
1201
1202           Filesystem#Special_Field::DiskName.$.Directory.Directory.File
1203
1204       where
1205
1206           Special_Field is not usually present, but may contain . and $ .
1207           Filesystem =~ m|[A-Za-z0-9_]|
1208           DsicName   =~ m|[A-Za-z0-9_/]|
1209           $ represents the root directory
1210           . is the path separator
1211           @ is the current directory (per filesystem but machine global)
1212           ^ is the parent directory
1213           Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1214
1215       The default filename translation is roughly "tr|/.|./|", swapping dots
1216       and slashes.
1217
1218       Note that ""ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'" and that
1219       the second stage of "$" interpolation in regular expressions will fall
1220       foul of the $. variable if scripts are not careful.
1221
1222       Logical paths specified by system variables containing comma-separated
1223       search lists are also allowed; hence "System:Modules" is a valid
1224       filename, and the filesystem will prefix "Modules" with each section of
1225       "System$Path" until a name is made that points to an object on disk.
1226       Writing to a new file "System:Modules" would be allowed only if
1227       "System$Path" contains a single item list.  The filesystem will also
1228       expand system variables in filenames if enclosed in angle brackets, so
1229       "<System$Dir>.Modules" would look for the file
1230       "$ENV{'System$Dir'} . 'Modules'".  The obvious implication of this is
1231       that fully qualified filenames can start with "<>" and the three-
1232       argument form of "open" should always be used.
1233
1234       Because "." was in use as a directory separator and filenames could not
1235       be assumed to be unique after 10 characters, Acorn implemented the C
1236       compiler to strip the trailing ".c" ".h" ".s" and ".o" suffix from
1237       filenames specified in source code and store the respective files in
1238       subdirectories named after the suffix.  Hence files are translated:
1239
1240           foo.h           h.foo
1241           C:foo.h         C:h.foo        (logical path variable)
1242           sys/os.h        sys.h.os       (C compiler groks Unix-speak)
1243           10charname.c    c.10charname
1244           10charname.o    o.10charname
1245           11charname_.c   c.11charname   (assuming filesystem truncates at 10)
1246
1247       The Unix emulation library's translation of filenames to native assumes
1248       that this sort of translation is required, and it allows a user-defined
1249       list of known suffixes that it will transpose in this fashion.  This
1250       may seem transparent, but consider that with these rules foo/bar/baz.h
1251       and foo/bar/h/baz both map to foo.bar.h.baz, and that "readdir" and
1252       "glob" cannot and do not attempt to emulate the reverse mapping.  Other
1253       "."'s in filenames are translated to "/".
1254
1255       As implied above, the environment accessed through %ENV is global, and
1256       the convention is that program specific environment variables are of
1257       the form "Program$Name".  Each filesystem maintains a current
1258       directory, and the current filesystem's current directory is the global
1259       current directory.  Consequently, sociable programs don't change the
1260       current directory but rely on full pathnames, and programs (and
1261       Makefiles) cannot assume that they can spawn a child process which can
1262       change the current directory without affecting its parent (and everyone
1263       else for that matter).
1264
1265       Because native operating system filehandles are global and are
1266       currently allocated down from 255, with 0 being a reserved value, the
1267       Unix emulation library emulates Unix filehandles.  Consequently, you
1268       can't rely on passing "STDIN", "STDOUT", or "STDERR" to your children.
1269
1270       The desire of users to express filenames of the form "<Foo$Dir>.Bar" on
1271       the command line unquoted causes problems, too: "``" command output
1272       capture has to perform a guessing game.  It assumes that a string
1273       "<[^<>]+\$[^<>]>" is a reference to an environment variable, whereas
1274       anything else involving "<" or ">" is redirection, and generally
1275       manages to be 99% right.  Of course, the problem remains that scripts
1276       cannot rely on any Unix tools being available, or that any tools found
1277       have Unix-like command line arguments.
1278
1279       Extensions and XS are, in theory, buildable by anyone using free tools.
1280       In practice, many don't, as users of the Acorn platform are used to
1281       binary distributions.  MakeMaker does run, but no available make
1282       currently copes with MakeMaker's makefiles; even if and when this
1283       should be fixed, the lack of a Unix-like shell will cause problems with
1284       makefile rules, especially lines of the form "cd sdbm && make all", and
1285       anything using quoting.
1286
1287       "RISC OS" is the proper name for the operating system, but the value in
1288       $^O is "riscos" (because we don't like shouting).
1289
1290   Other perls
1291       Perl has been ported to many platforms that do not fit into any of the
1292       categories listed above.  Some, such as AmigaOS, QNX, Plan 9, and VOS,
1293       have been well-integrated into the standard Perl source code kit.  You
1294       may need to see the ports/ directory on CPAN for information, and
1295       possibly binaries, for the likes of: aos, Atari ST, lynxos, riscos,
1296       Novell Netware, Tandem Guardian, etc.  (Yes, we know that some of these
1297       OSes may fall under the Unix category, but we are not a standards
1298       body.)
1299
1300       Some approximate operating system names and their $^O values in the
1301       "OTHER" category include:
1302
1303           OS            $^O        $Config{archname}
1304           ------------------------------------------
1305           Amiga DOS     amigaos    m68k-amigos
1306
1307       See also:
1308
1309       •   Amiga, README.amiga (installed as perlamiga).
1310
1311       •   A free perl5-based PERL.NLM for Novell Netware is available in
1312           precompiled binary and source code form from
1313           <http://www.novell.com/> as well as from CPAN.
1314
1315       •   Plan 9, README.plan9
1316

FUNCTION IMPLEMENTATIONS

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

Supported Platforms

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

EOL Platforms

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

Supported Platforms (Perl 5.8)

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

SEE ALSO

2044       perlaix, perlamiga, perlbs2000, perlcygwin, perldos, perlebcdic,
2045       perlfreebsd, perlhurd, perlhpux, perlirix, perlmacos, perlmacosx,
2046       perlnetware, perlos2, perlos390, perlos400, perlplan9, perlqnx,
2047       perlsolaris, perltru64, perlunicode, perlvms, perlvos, perlwin32, and
2048       Win32.
2049

AUTHORS / CONTRIBUTORS

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