This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fix version numbering for dist/PathTools
[perl5.git] / pod / perlport.pod
CommitLineData
e41182b5
GS
1=head1 NAME
2
3perlport - Writing portable Perl
4
e41182b5
GS
5=head1 DESCRIPTION
6
b7df3edc
GS
7Perl runs on numerous operating systems. While most of them share
8much in common, they also have their own unique features.
e41182b5
GS
9
10This document is meant to help you to find out what constitutes portable
b7df3edc 11Perl code. That way once you make a decision to write portably,
e41182b5
GS
12you know where the lines are drawn, and you can stay within them.
13
b7df3edc
GS
14There is a tradeoff between taking full advantage of one particular
15type of computer and taking advantage of a full range of them.
16Naturally, as you broaden your range and become more diverse, the
17common factors drop, and you are left with an increasingly smaller
18area of common ground in which you can operate to accomplish a
19particular task. Thus, when you begin attacking a problem, it is
20important to consider under which part of the tradeoff curve you
21want to operate. Specifically, you must decide whether it is
2c044526 22important that the task that you are coding has the full generality
b7df3edc
GS
23of being portable, or whether to just get the job done right now.
24This is the hardest choice to be made. The rest is easy, because
25Perl provides many choices, whichever way you want to approach your
0a47030a
GS
26problem.
27
28Looking at it another way, writing portable code is usually about
b7df3edc
GS
29willfully limiting your available choices. Naturally, it takes
30discipline and sacrifice to do that. The product of portability
31and convenience may be a constant. You have been warned.
e41182b5
GS
32
33Be aware of two important points:
34
35=over 4
36
37=item Not all Perl programs have to be portable
38
b7df3edc 39There is no reason you should not use Perl as a language to glue Unix
e41182b5
GS
40tools together, or to prototype a Macintosh application, or to manage the
41Windows registry. If it makes no sense to aim for portability for one
42reason or another in a given program, then don't bother.
43
b7df3edc 44=item Nearly all of Perl already I<is> portable
e41182b5
GS
45
46Don't be fooled into thinking that it is hard to create portable Perl
47code. It isn't. Perl tries its level-best to bridge the gaps between
48what's available on different platforms, and all the means available to
49use those features. Thus almost all Perl code runs on any machine
6ab3f9cb 50without modification. But there are some significant issues in
e41182b5
GS
51writing portable code, and this document is entirely about those issues.
52
53=back
54
b7df3edc
GS
55Here's the general rule: When you approach a task commonly done
56using a whole range of platforms, think about writing portable
e41182b5
GS
57code. That way, you don't sacrifice much by way of the implementation
58choices you can avail yourself of, and at the same time you can give
59your users lots of platform choices. On the other hand, when you have to
60take advantage of some unique feature of a particular platform, as is
61often the case with systems programming (whether for Unix, Windows,
204ad8d5 62VMS, etc.), consider writing platform-specific code.
e41182b5 63
b7df3edc
GS
64When the code will run on only two or three operating systems, you
65may need to consider only the differences of those particular systems.
66The important thing is to decide where the code will run and to be
0a47030a
GS
67deliberate in your decision.
68
69The material below is separated into three main sections: main issues of
5a0de581 70portability (L</"ISSUES">), platform-specific issues (L</"PLATFORMS">), and
2c044526 71built-in Perl functions that behave differently on various ports
5a0de581 72(L</"FUNCTION IMPLEMENTATIONS">).
e41182b5
GS
73
74This information should not be considered complete; it includes possibly
b8099c3d 75transient information about idiosyncrasies of some of the ports, almost
b7df3edc 76all of which are in a state of constant evolution. Thus, this material
e41182b5 77should be considered a perpetual work in progress
cc07ed0b 78(C<< <IMG SRC="yellow_sign.gif" ALT="Under Construction"> >>).
e41182b5 79
e41182b5
GS
80=head1 ISSUES
81
82=head2 Newlines
83
638bc118 84In most operating systems, lines in files are terminated by newlines.
e41182b5 85Just what is used as a newline may vary from OS to OS. Unix
b7df3edc 86traditionally uses C<\012>, one type of DOSish I/O uses C<\015\012>,
2c044526 87S<Mac OS> uses C<\015>, and z/OS uses C<\025>.
e41182b5 88
b7df3edc
GS
89Perl uses C<\n> to represent the "logical" newline, where what is
90logical may depend on the platform in use. In MacPerl, C<\n> always
eb9df707
KW
91means C<\015>. On EBCDIC platforms, C<\n> could be C<\025> or C<\045>.
92In DOSish perls, C<\n> usually means C<\012>, but when
51d9476f 93accessing a file in "text" mode, perl uses the C<:crlf> layer that
94translates it to (or from) C<\015\012>, depending on whether you're
95reading or writing. Unix does the same thing on ttys in canonical
96mode. C<\015\012> is commonly referred to as CRLF.
b7df3edc 97
2c044526
KW
98To trim trailing newlines from text lines use C<chomp()>. With default
99settings that function looks for a trailing C<\n> character and thus
31bb23b1 100trims in a portable way.
5b3eff12
MS
101
102When dealing with binary files (or text files in binary mode) be sure
103to explicitly set $/ to the appropriate value for your file format
2c044526 104before using C<chomp()>.
5b3eff12 105
b7df3edc
GS
106Because of the "text" mode translation, DOSish perls have limitations
107in using C<seek> and C<tell> on a file accessed in "text" mode.
108Stick to C<seek>-ing to locations you got from C<tell> (and no
109others), and you are usually free to use C<seek> and C<tell> even
110in "text" mode. Using C<seek> or C<tell> or other file operations
111may be non-portable. If you use C<binmode> on a file, however, you
2c044526 112can usually C<seek> and C<tell> with arbitrary values safely.
e41182b5 113
2c044526 114A common misconception in socket programming is that S<C<\n eq \012>>
0a47030a 115everywhere. When using protocols such as common Internet protocols,
e41182b5
GS
116C<\012> and C<\015> are called for specifically, and the values of
117the logical C<\n> and C<\r> (carriage return) are not reliable.
118
119 print SOCKET "Hi there, client!\r\n"; # WRONG
120 print SOCKET "Hi there, client!\015\012"; # RIGHT
121
0a47030a
GS
122However, using C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious
123and unsightly, as well as confusing to those maintaining the code. As
2c044526 124such, the C<Socket> module supplies the Right Thing for those who want it.
e41182b5
GS
125
126 use Socket qw(:DEFAULT :crlf);
127 print SOCKET "Hi there, client!$CRLF" # RIGHT
128
6ab3f9cb 129When reading from a socket, remember that the default input record
b7df3edc
GS
130separator C<$/> is C<\n>, but robust socket code will recognize as
131either C<\012> or C<\015\012> as end of line:
e41182b5 132
2c044526 133 while (<SOCKET>) { # NOT ADVISABLE!
e41182b5
GS
134 # ...
135 }
136
b7df3edc
GS
137Because both CRLF and LF end in LF, the input record separator can
138be set to LF and any CR stripped later. Better to write:
e41182b5
GS
139
140 use Socket qw(:DEFAULT :crlf);
141 local($/) = LF; # not needed if $/ is already \012
142
143 while (<SOCKET>) {
144 s/$CR?$LF/\n/; # not sure if socket uses LF or CRLF, OK
145 # s/\015?\012/\n/; # same thing
146 }
147
b7df3edc
GS
148This example is preferred over the previous one--even for Unix
149platforms--because now any C<\015>'s (C<\cM>'s) are stripped out
e41182b5
GS
150(and there was much rejoicing).
151
6ab3f9cb 152Similarly, functions that return text data--such as a function that
b7df3edc
GS
153fetches a web page--should sometimes translate newlines before
154returning the data, if they've not yet been translated to the local
155newline representation. A single line of code will often suffice:
2ee0eb3c 156
b7df3edc
GS
157 $data =~ s/\015?\012/\n/g;
158 return $data;
2ee0eb3c 159
6ab3f9cb
GS
160Some of this may be confusing. Here's a handy reference to the ASCII CR
161and LF characters. You can print it out and stick it in your wallet.
162
74555b7a
PP
163 LF eq \012 eq \x0A eq \cJ eq chr(10) eq ASCII 10
164 CR eq \015 eq \x0D eq \cM eq chr(13) eq ASCII 13
6ab3f9cb
GS
165
166 | Unix | DOS | Mac |
167 ---------------------------
168 \n | LF | LF | CR |
169 \r | CR | CR | LF |
170 \n * | LF | CRLF | CR |
171 \r * | CR | CR | LF |
172 ---------------------------
173 * text-mode STDIO
174
b7df3edc
GS
175The Unix column assumes that you are not accessing a serial line
176(like a tty) in canonical mode. If you are, then CR on input becomes
177"\n", and "\n" on output becomes CRLF.
178
6ab3f9cb 179These are just the most common definitions of C<\n> and C<\r> in Perl.
522b859a
JH
180There may well be others. For example, on an EBCDIC implementation
181such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based)
182the above material is similar to "Unix" but the code numbers change:
74555b7a 183
d770bc45
ST
184 LF eq \025 eq \x15 eq \cU eq chr(21) eq CP-1047 21
185 LF eq \045 eq \x25 eq chr(37) eq CP-0037 37
74555b7a
PP
186 CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-1047 13
187 CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-0037 13
188
189 | z/OS | OS/400 |
190 ----------------------
191 \n | LF | LF |
192 \r | CR | CR |
193 \n * | LF | LF |
194 \r * | CR | CR |
195 ----------------------
196 * text-mode STDIO
6ab3f9cb 197
322422de
GS
198=head2 Numbers endianness and Width
199
200Different CPUs store integers and floating point numbers in different
201orders (called I<endianness>) and widths (32-bit and 64-bit being the
b7df3edc
GS
202most common today). This affects your programs when they attempt to transfer
203numbers in binary format from one CPU architecture to another,
204usually either "live" via network connection, or by storing the
205numbers to secondary storage such as a disk file or tape.
322422de 206
2c044526 207Conflicting storage orders make an utter mess out of the numbers. If a
d1e3b762 208little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
b84d4f81
JH
209decimal), a big-endian host (Motorola, Sparc, PA) reads it as
2100x78563412 (2018915346 in decimal). Alpha and MIPS can be either:
211Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
212them in big-endian mode. To avoid this problem in network (socket)
213connections use the C<pack> and C<unpack> formats C<n> and C<N>, the
214"network" orders. These are guaranteed to be portable.
322422de 215
2c044526 216As of Perl 5.10.0, you can also use the C<E<gt>> and C<E<lt>> modifiers
1109a392
MHM
217to force big- or little-endian byte-order. This is useful if you want
218to store signed integers or 64-bit integers, for example.
219
d1e3b762
GS
220You can explore the endianness of your platform by unpacking a
221data structure packed in native format such as:
222
223 print unpack("h*", pack("s2", 1, 2)), "\n";
224 # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
225 # '00100020' on e.g. Motorola 68040
226
227If you need to distinguish between endian architectures you could use
228either of the variables set like so:
229
230 $is_big_endian = unpack("h*", pack("s", 1)) =~ /01/;
4375e838 231 $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
d1e3b762 232
b7df3edc
GS
233Differing widths can cause truncation even between platforms of equal
234endianness. The platform of shorter width loses the upper parts of the
322422de
GS
235number. There is no good solution for this problem except to avoid
236transferring or storing raw binary numbers.
237
b7df3edc 238One can circumnavigate both these problems in two ways. Either
322422de 239transfer and store numbers always in text format, instead of raw
2c044526
KW
240binary, or else consider using modules like C<Data::Dumper> and
241C<Storable>
242(included as of Perl 5.8). Keeping all data as text significantly
1bcbdd38 243simplifies matters.
322422de 244
433acd8a 245=head2 Files and Filesystems
e41182b5
GS
246
247Most platforms these days structure files in a hierarchical fashion.
b7df3edc 248So, it is reasonably safe to assume that all platforms support the
6ab3f9cb 249notion of a "path" to uniquely identify a file on the system. How
b7df3edc 250that path is really written, though, differs considerably.
e41182b5 251
4375e838 252Although similar, file path specifications differ between Unix,
b7df3edc
GS
253Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others.
254Unix, for example, is one of the few OSes that has the elegant idea
255of a single root directory.
322422de 256
6ab3f9cb
GS
257DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with C</>
258as path separator, or in their own idiosyncratic ways (such as having
259several root directories and various "unrooted" device files such NIL:
260and LPT:).
322422de 261
204ad8d5 262S<Mac OS> 9 and earlier used C<:> as a path separator instead of C</>.
322422de 263
6ab3f9cb
GS
264The filesystem may support neither hard links (C<link>) nor
265symbolic links (C<symlink>, C<readlink>, C<lstat>).
433acd8a 266
6ab3f9cb 267The filesystem may support neither access timestamp nor change
433acd8a
JH
268timestamp (meaning that about the only portable timestamp is the
269modification timestamp), or one second granularity of any timestamps
270(e.g. the FAT filesystem limits the time granularity to two seconds).
271
74555b7a 272The "inode change timestamp" (the C<-C> filetest) may really be the
e1020413 273"creation timestamp" (which it is not in Unix).
95a3fe12 274
495c5fdc
GP
275VOS perl can emulate Unix filenames with C</> as path separator. The
276native pathname characters greater-than, less-than, number-sign, and
277percent-sign are always accepted.
278
6ab3f9cb 279S<RISC OS> perl can emulate Unix filenames with C</> as path
322422de 280separator, or go native and use C<.> for path separator and C<:> to
6ab3f9cb 281signal filesystems and disk names.
e41182b5 282
e1020413 283Don't assume Unix filesystem access semantics: that read, write,
a1667ba3 284and execute are all the permissions there are, and even if they exist,
2c044526 285that their semantics (for example what do C<"r">, C<"w">, and C<"x"> mean on
e1020413 286a directory) are the Unix ones. The various Unix/POSIX compatibility
2c044526 287layers usually try to make interfaces like C<chmod()> work, but sometimes
a1667ba3
JH
288there simply is no good mapping.
289
35a328a7
CB
290The C<File::Spec> modules provide methods to manipulate path
291specifications and return the results in native format for each
292platform. This is often unnecessary as Unix-style paths are
293understood by Perl on every supported platform, but if you need to
294produce native paths for a native utility that does not understand
295Unix syntax, or if you are operating on paths or path components
296in unknown (and thus possibly native) syntax, C<File::Spec> is
297your friend. Here are two brief examples:
e41182b5 298
6ab3f9cb
GS
299 use File::Spec::Functions;
300 chdir(updir()); # go up one directory
35a328a7
CB
301
302 # Concatenate a path from its components
303 my $file = catfile(updir(), 'temp', 'file.txt');
304 # on Unix: '../temp/file.txt'
305 # on Win32: '..\temp\file.txt'
306 # on VMS: '[-.temp]file.txt'
e41182b5 307
b7df3edc
GS
308In general, production code should not have file paths hardcoded.
309Making them user-supplied or read from a configuration file is
310better, keeping in mind that file path syntax varies on different
311machines.
e41182b5
GS
312
313This is especially noticeable in scripts like Makefiles and test suites,
314which often assume C</> as a path separator for subdirectories.
315
2c044526 316Also of use is C<File::Basename> from the standard distribution, which
e41182b5
GS
317splits a pathname into pieces (base filename, full path to directory,
318and file suffix).
319
19799a22 320Even when on a single platform (if you can call Unix a single platform),
b7df3edc 321remember not to count on the existence or the contents of particular
3c075c7d 322system-specific files or directories, like F</etc/passwd>,
b7df3edc
GS
323F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>. For
324example, F</etc/passwd> may exist but not contain the encrypted
325passwords, because the system is using some form of enhanced security.
2c044526 326Or it may not contain all the accounts, because the system is using NIS.
3c075c7d 327If code does need to rely on such a file, include a description of the
b7df3edc 328file and its format in the code's documentation, then make it easy for
3c075c7d
CN
329the user to override the default location of the file.
330
b7df3edc
GS
331Don't assume a text file will end with a newline. They should,
332but people forget.
e41182b5 333
ec481373
JH
334Do not have two files or directories of the same name with different
335case, like F<test.pl> and F<Test.pl>, as many platforms have
336case-insensitive (or at least case-forgiving) filenames. Also, try
337not to have non-word characters (except for C<.>) in the names, and
338keep them to the 8.3 convention, for maximum portability, onerous a
339burden though this may appear.
dd9f0070 340
2c044526 341Likewise, when using the C<AutoSplit> module, try to keep your functions to
b7df3edc 3428.3 naming and case-insensitive conventions; or, at the least,
dd9f0070
CN
343make it so the resulting files have a unique (case-insensitively)
344first 8 characters.
345
ec481373
JH
346Whitespace in filenames is tolerated on most systems, but not all,
347and even on systems where it might be tolerated, some utilities
fe829689 348might become confused by such whitespace.
ec481373 349
016930a6
JM
350Many systems (DOS, VMS ODS-2) cannot have more than one C<.> in their
351filenames.
433acd8a 352
c47ff5f1 353Don't assume C<< > >> won't be the first character of a filename.
fe829689 354Always use C<< < >> explicitly to open a file for reading, or even
2c044526 355better, use the three-arg version of C<open>, unless you want the user to
fe829689 356be able to specify a pipe open.
0a47030a 357
ceaffd1d 358 open my $fh, '<', $existing_file) or die $!;
0a47030a 359
6ab3f9cb
GS
360If filenames might use strange characters, it is safest to open it
361with C<sysopen> instead of C<open>. C<open> is magic and can
c47ff5f1 362translate characters like C<< > >>, C<< < >>, and C<|>, which may
b7df3edc 363be the wrong thing to do. (Sometimes, though, it's the right thing.)
fe829689
PN
364Three-arg open can also help protect against this translation in cases
365where it is undesirable.
e41182b5 366
ec481373 367Don't use C<:> as a part of a filename since many systems use that for
8939ba94 368their own semantics (Mac OS Classic for separating pathname components,
ec481373 369many networking schemes and utilities for separating the nodename and
08fef530
JH
370the pathname, and so on). For the same reasons, avoid C<@>, C<;> and
371C<|>.
ec481373 372
e1516da7
JH
373Don't assume that in pathnames you can collapse two leading slashes
374C<//> into one: some networking and clustering filesystems have special
2c044526 375semantics for that. Let the operating system sort it out.
e1516da7 376
ec481373
JH
377The I<portable filename characters> as defined by ANSI C are
378
1802421e
JK
379 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
380 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
ec481373
JH
381 0 1 2 3 4 5 6 7 8 9
382 . _ -
383
2c044526 384and the C<"-"> shouldn't be the first character. If you want to be
e1516da7
JH
385hypercorrect, stay case-insensitive and within the 8.3 naming
386convention (all the files and directories have to be unique within one
387directory if their names are lowercased and truncated to eight
388characters before the C<.>, if any, and to three characters after the
389C<.>, if any). (And do not use C<.>s in directory names.)
ec481373 390
e41182b5
GS
391=head2 System Interaction
392
b7df3edc
GS
393Not all platforms provide a command line. These are usually platforms
394that rely primarily on a Graphical User Interface (GUI) for user
395interaction. A program requiring a command line interface might
396not work everywhere. This is probably for the user of the program
397to deal with, so don't stay up late worrying about it.
e41182b5 398
c87488a3
HS
399Some platforms can't delete or rename files held open by the system,
400this limitation may also apply to changing filesystem metainformation
401like file permissions or owners. Remember to C<close> files when you
402are done with them. Don't C<unlink> or C<rename> an open file. Don't
403C<tie> or C<open> a file already tied or opened; C<untie> or C<close>
404it first.
e41182b5 405
0a47030a
GS
406Don't open the same file more than once at a time for writing, as some
407operating systems put mandatory locks on such files.
408
73e9292c
JH
409Don't assume that write/modify permission on a directory gives the
410right to add or delete files/directories in that directory. That is
411filesystem specific: in some filesystems you need write/modify
412permission also (or even just) in the file/directory itself. In some
413filesystems (AFS, DFS) the permission to add/delete directory entries
414is a completely separate permission.
415
416Don't assume that a single C<unlink> completely gets rid of the file:
417some filesystems (most notably the ones in VMS) have versioned
2c044526 418filesystems, and C<unlink()> removes only the most recent one (it doesn't
73e9292c
JH
419remove all the versions because by default the native tools on those
420platforms remove just the most recent version, too). The portable
421idiom to remove all the versions of a file is
422
94bb614c 423 1 while unlink "file";
73e9292c
JH
424
425This will terminate if the file is undeleteable for some reason
426(protected, not there, and so on).
427
e41182b5 428Don't count on a specific environment variable existing in C<%ENV>.
0a47030a 429Don't count on C<%ENV> entries being case-sensitive, or even
2c044526 430case-preserving. Don't try to clear C<%ENV> by saying C<%ENV = ();>, or,
6be8f7a6 431if you really have to, make it conditional on C<$^O ne 'VMS'> since in
4a0d0822
JH
432VMS the C<%ENV> table is much more than a per-process key-value string
433table.
e41182b5 434
2c044526 435On VMS, some entries in the C<%ENV> hash are dynamically created when
c73b03b7 436their key is used on a read if they did not previously exist. The
9e861032 437values for C<$ENV{HOME}>, C<$ENV{TERM}>, C<$ENV{PATH}>, and C<$ENV{USER}>,
c73b03b7
JM
438are known to be dynamically generated. The specific names that are
439dynamically generated may vary with the version of the C library on VMS,
9e861032 440and more may exist than are documented.
c73b03b7 441
2c044526
KW
442On VMS by default, changes to the %ENV hash persist after perl exits.
443Subsequent invocations of perl in the same process can inadvertently
9e861032 444inherit environment settings that were meant to be temporary.
c73b03b7 445
d1e3b762 446Don't count on signals or C<%SIG> for anything.
e41182b5
GS
447
448Don't count on filename globbing. Use C<opendir>, C<readdir>, and
449C<closedir> instead.
450
b8099c3d 451Don't count on per-program environment variables, or per-program current
dd9f0070 452directories.
b8099c3d 453
c87488a3 454Don't count on specific values of C<$!>, neither numeric nor
2c044526 455especially the string values. Users may switch their locales causing
c87488a3
HS
456error messages to be translated into their languages. If you can
457trust a POSIXish environment, you can portably use the symbols defined
2c044526 458by the C<Errno> module, like C<ENOENT>. And don't trust on the values of C<$!>
c87488a3 459at all except immediately after a failed system call.
3c075c7d 460
a10d74f3
PG
461=head2 Command names versus file pathnames
462
463Don't assume that the name used to invoke a command or program with
464C<system> or C<exec> can also be used to test for the existence of the
465file that holds the executable code for that command or program.
68fb0eb7
PG
466First, many systems have "internal" commands that are built-in to the
467shell or OS and while these commands can be invoked, there is no
468corresponding file. Second, some operating systems (e.g., Cygwin,
469DJGPP, OS/2, and VOS) have required suffixes for executable files;
470these suffixes are generally permitted on the command name but are not
2c044526
KW
471required. Thus, a command like F<"perl"> might exist in a file named
472F<"perl">, F<"perl.exe">, or F<"perl.pm">, depending on the operating system.
473The variable C<"_exe"> in the C<Config> module holds the executable suffix,
474if any. Third, the VMS port carefully sets up C<$^X> and
475C<$Config{perlpath}> so that no further processing is required. This is
68fb0eb7
PG
476just as well, because the matching regular expression used below would
477then have to deal with a possible trailing version number in the VMS
478file name.
a10d74f3 479
2c044526 480To convert C<$^X> to a file pathname, taking account of the requirements
a10d74f3 481of the various operating system possibilities, say:
7ee27b7c 482
a61fc69c
KW
483 use Config;
484 my $thisperl = $^X;
485 if ($^O ne 'VMS')
486 {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
a10d74f3 487
2c044526 488To convert C<$Config{perlpath}> to a file pathname, say:
7ee27b7c 489
a61fc69c
KW
490 use Config;
491 my $thisperl = $Config{perlpath};
492 if ($^O ne 'VMS')
493 {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
a10d74f3 494
7137b697
JH
495=head2 Networking
496
497Don't assume that you can reach the public Internet.
498
499Don't assume that there is only one way to get through firewalls
500to the public Internet.
501
932f293e
JH
502Don't assume that you can reach outside world through any other port
503than 80, or some web proxy. ftp is blocked by many firewalls.
504
dbc6a9ce
JH
505Don't assume that you can send email by connecting to the local SMTP port.
506
7137b697 507Don't assume that you can reach yourself or any node by the name
dbc6a9ce 508'localhost'. The same goes for '127.0.0.1'. You will have to try both.
932f293e 509
86feb2c5
JH
510Don't assume that the host has only one network card, or that it
511can't bind to many virtual IP addresses.
932f293e
JH
512
513Don't assume a particular network device name.
7137b697 514
2c044526 515Don't assume a particular set of C<ioctl()>s will work.
7137b697
JH
516
517Don't assume that you can ping hosts and get replies.
518
dbc6a9ce
JH
519Don't assume that any particular port (service) will respond.
520
2c044526 521Don't assume that C<Sys::Hostname> (or any other API or command) returns
ac036724 522either a fully qualified hostname or a non-qualified hostname: it all
523depends on how the system had been configured. Also remember that for
524things such as DHCP and NAT, the hostname you get back might not be
525very useful.
dbc6a9ce 526
a746ef5c 527All the above I<don't>s may look daunting, and they are, but the key
932f293e
JH
528is to degrade gracefully if one cannot reach the particular network
529service one wants. Croaking or hanging do not look very professional.
530
e41182b5
GS
531=head2 Interprocess Communication (IPC)
532
b7df3edc
GS
533In general, don't directly access the system in code meant to be
534portable. That means, no C<system>, C<exec>, C<fork>, C<pipe>,
535C<``>, C<qx//>, C<open> with a C<|>, nor any of the other things
2c044526 536that makes being a Perl hacker worth being.
e41182b5
GS
537
538Commands that launch external processes are generally supported on
b7df3edc
GS
539most platforms (though many of them do not support any type of
540forking). The problem with using them arises from what you invoke
541them on. External tools are often named differently on different
4375e838 542platforms, may not be available in the same location, might accept
b7df3edc
GS
543different arguments, can behave differently, and often present their
544results in a platform-dependent way. Thus, you should seldom depend
2890cc8c 545on them to produce consistent results. (Then again, if you're calling
b7df3edc 546I<netstat -a>, you probably don't expect it to run on both Unix and CP/M.)
e41182b5 547
b7df3edc 548One especially common bit of Perl code is opening a pipe to B<sendmail>:
e41182b5 549
2890cc8c 550 open(MAIL, '|/usr/lib/sendmail -t')
b7df3edc 551 or die "cannot fork sendmail: $!";
e41182b5
GS
552
553This is fine for systems programming when sendmail is known to be
554available. But it is not fine for many non-Unix systems, and even
555some Unix systems that may not have sendmail installed. If a portable
b7df3edc 556solution is needed, see the various distributions on CPAN that deal
2c044526
KW
557with it. C<Mail::Mailer> and C<Mail::Send> in the C<MailTools> distribution are
558commonly used, and provide several mailing methods, including C<mail>,
559C<sendmail>, and direct SMTP (via C<Net::SMTP>) if a mail transfer agent is
560not available. C<Mail::Sendmail> is a standalone module that provides
b7df3edc
GS
561simple, platform-independent mailing.
562
563The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
564even on all Unix platforms.
e41182b5 565
a81e5e2e
A
566Do not use either the bare result of C<pack("N", 10, 20, 30, 40)> or
567bare v-strings (such as C<v10.20.30.40>) to represent IPv4 addresses:
568both forms just pack the four bytes into network order. That this
569would be equal to the C language C<in_addr> struct (which is what the
570socket code internally uses) is not guaranteed. To be portable use
2c044526 571the routines of the C<Socket> extension, such as C<inet_aton()>,
a81e5e2e 572C<inet_ntoa()>, and C<sockaddr_in()>.
6b2463a0 573
e41182b5 574The rule of thumb for portable code is: Do it all in portable Perl, or
0a47030a 575use a module (that may internally implement it with platform-specific
2c044526 576code, but exposes a common interface).
e41182b5 577
e41182b5
GS
578=head2 External Subroutines (XS)
579
b7df3edc 580XS code can usually be made to work with any platform, but dependent
e41182b5
GS
581libraries, header files, etc., might not be readily available or
582portable, or the XS code itself might be platform-specific, just as Perl
583code might be. If the libraries and headers are portable, then it is
584normally reasonable to make sure the XS code is portable, too.
585
b7df3edc
GS
586A different type of portability issue arises when writing XS code:
587availability of a C compiler on the end-user's system. C brings
588with it its own portability issues, and writing XS code will expose
589you to some of those. Writing purely in Perl is an easier way to
e41182b5
GS
590achieve portability.
591
e41182b5
GS
592=head2 Standard Modules
593
594In general, the standard modules work across platforms. Notable
2c044526 595exceptions are the C<CPAN> module (which currently makes connections to external
e41182b5 596programs that may not be available), platform-specific modules (like
2c044526 597C<ExtUtils::MM_VMS>), and DBM modules.
e41182b5 598
b7df3edc 599There is no one DBM module available on all platforms.
2c044526
KW
600C<SDBM_File> and the others are generally available on all Unix and DOSish
601ports, but not in MacPerl, where only C<NDBM_File> and C<DB_File> are
0a47030a 602available.
e41182b5
GS
603
604The good news is that at least some DBM module should be available, and
2c044526 605C<AnyDBM_File> will use whichever module it can find. Of course, then
b7df3edc
GS
606the code needs to be fairly strict, dropping to the greatest common
607factor (e.g., not exceeding 1K for each record), so that it will
6ab3f9cb 608work with any DBM module. See L<AnyDBM_File> for more details.
e41182b5 609
e41182b5
GS
610=head2 Time and Date
611
0a47030a 612The system's notion of time of day and calendar date is controlled in
b7df3edc 613widely different ways. Don't assume the timezone is stored in C<$ENV{TZ}>,
0a47030a 614and even if it is, don't assume that you can control the timezone through
c87488a3
HS
615that variable. Don't assume anything about the three-letter timezone
616abbreviations (for example that MST would be the Mountain Standard Time,
617it's been known to stand for Moscow Standard Time). If you need to
618use timezones, express them in some unambiguous format like the
619exact number of minutes offset from UTC, or the POSIX timezone
620format.
e41182b5 621
322422de 622Don't assume that the epoch starts at 00:00:00, January 1, 1970,
c87488a3
HS
623because that is OS- and implementation-specific. It is better to
624store a date in an unambiguous representation. The ISO 8601 standard
766af94f 625defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH:MM:SS
c87488a3 626(that's a literal "T" separating the date from the time).
91d20606 627Please do use the ISO 8601 instead of making us guess what
c87488a3
HS
628date 02/03/04 might be. ISO 8601 even sorts nicely as-is.
629A text representation (like "1987-12-18") can be easily converted
2c044526 630into an OS-specific value using a module like C<Date::Parse>.
c87488a3 631An array of values, such as those returned by C<localtime>, can be
2c044526 632converted to an OS-specific representation using C<Time::Local>.
322422de 633
19799a22
GS
634When calculating specific times, such as for tests in time or date modules,
635it may be appropriate to calculate an offset for the epoch.
b7df3edc 636
19799a22 637 require Time::Local;
ceaffd1d 638 my $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);
b7df3edc 639
204ad8d5
JV
640The value for C<$offset> in Unix will be C<0>, but in Mac OS Classic
641will be some large number. C<$offset> can then be added to a Unix time
642value to get what should be the proper value on any system.
322422de
GS
643
644=head2 Character sets and character encoding
645
ec481373
JH
646Assume very little about character sets.
647
648Assume nothing about numerical values (C<ord>, C<chr>) of characters.
eb9df707
KW
649Do not use explicit code point ranges (like C<\xHH-\xHH)>. However,
650starting in Perl v5.22, regular expression pattern bracketed character
f4240379
KW
651class ranges specified like C<qr/[\N{U+HH}-\N{U+HH}]/> are portable,
652and starting in Perl v5.24, the same ranges are portable in C<tr///>.
2c044526 653You can portably use symbolic character classes like C<[:print:]>.
ec481373
JH
654
655Do not assume that the alphabetic characters are encoded contiguously
eb9df707
KW
656(in the numeric sense). There may be gaps. Special coding in Perl,
657however, guarantees that all subsets of C<qr/[A-Z]/>, C<qr/[a-z]/>, and
2c044526
KW
658C<qr/[0-9]/> behave as expected. C<tr///> behaves the same for these
659ranges. In patterns, any ranges specified with end points using the
660C<\N{...}> notations ensures character set portability, but it is a bug
f4240379 661in Perl v5.22, that this isn't true of C<tr///>, fixed in v5.24.
ec481373
JH
662
663Do not assume anything about the ordering of the characters.
664The lowercase letters may come before or after the uppercase letters;
b432a672
AL
665the lowercase and uppercase may be interlaced so that both "a" and "A"
666come before "b"; the accented and other international characters may
667be interlaced so that E<auml> comes before "b".
2c044526 668L<Unicode::Collate> can be used to sort this all out.
322422de
GS
669
670=head2 Internationalisation
671
b7df3edc
GS
672If you may assume POSIX (a rather large assumption), you may read
673more about the POSIX locale system from L<perllocale>. The locale
674system at least attempts to make things a little bit more portable,
675or at least more convenient and native-friendly for non-English
676users. The system affects character sets and encoding, and date
677and time formatting--amongst other things.
e41182b5 678
c87488a3
HS
679If you really want to be international, you should consider Unicode.
680See L<perluniintro> and L<perlunicode> for more information.
681
11264fdb
JH
682If you want to use non-ASCII bytes (outside the bytes 0x00..0x7f) in
683the "source code" of your code, to be portable you have to be explicit
684about what bytes they are. Someone might for example be using your
685code under a UTF-8 locale, in which case random native bytes might be
686illegal ("Malformed UTF-8 ...") This means that for example embedding
687ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
688later. If the bytes are native 8-bit bytes, you can use the C<bytes>
eb9df707
KW
689pragma. If the bytes are in a string (regular expressions being
690curious strings), you can often also use the C<\xHH> or more portably,
691the C<\N{U+HH}> notations instead
1bcbdd38 692of embedding the bytes as-is. If you want to write your code in UTF-8,
eb9df707 693you can use L<utf8>.
11264fdb 694
e41182b5
GS
695=head2 System Resources
696
0a47030a
GS
697If your code is destined for systems with severely constrained (or
698missing!) virtual memory systems then you want to be I<especially> mindful
699of avoiding wasteful constructs such as:
e41182b5 700
ceaffd1d 701 my @lines = <$very_large_file>; # bad
e41182b5 702
ceaffd1d 703 while (<$fh>) {$file .= $_} # sometimes bad
704 my $file = join('', <$fh>); # better
e41182b5 705
b7df3edc
GS
706The last two constructs may appear unintuitive to most people. The
707first repeatedly grows a string, whereas the second allocates a
708large chunk of memory in one go. On some systems, the second is
2c044526 709more efficient than the first.
0a47030a 710
e41182b5
GS
711=head2 Security
712
b7df3edc 713Most multi-user platforms provide basic levels of security, usually
ac036724 714implemented at the filesystem level. Some, however, unfortunately do
715not. Thus the notion of user id, or "home" directory,
b7df3edc
GS
716or even the state of being logged-in, may be unrecognizable on many
717platforms. If you write programs that are security-conscious, it
718is usually best to know what type of system you will be running
719under so that you can write code explicitly for that platform (or
720class of platforms).
0a47030a 721
e1020413 722Don't assume the Unix filesystem access semantics: the operating
a1667ba3 723system or the filesystem may be using some ACL systems, which are
2c044526 724richer languages than the usual C<rwx>. Even if the C<rwx> exist,
a1667ba3
JH
725their semantics might be different.
726
2c044526 727(From the security viewpoint, testing for permissions before attempting to
a1667ba3 728do something is silly anyway: if one tries this, there is potential
ac036724 729for race conditions. Someone or something might change the
a1667ba3
JH
730permissions between the permissions check and the actual operation.
731Just try the operation.)
732
e1020413 733Don't assume the Unix user and group semantics: especially, don't
2c044526 734expect C<< $< >> and C<< $> >> (or C<$(> and C<$)>) to work
a1667ba3
JH
735for switching identities (or memberships).
736
737Don't assume set-uid and set-gid semantics. (And even if you do,
738think twice: set-uid and set-gid are a known can of security worms.)
739
e41182b5
GS
740=head2 Style
741
742For those times when it is necessary to have platform-specific code,
743consider keeping the platform-specific code in one place, making porting
2c044526 744to other platforms easier. Use the C<Config> module and the special
0a47030a 745variable C<$^O> to differentiate platforms, as described in
5a0de581 746L</"PLATFORMS">.
e41182b5 747
d4c800c7
JH
748Beware of the "else syndrome":
749
750 if ($^O eq 'MSWin32') {
751 # code that assumes Windows
752 } else {
753 # code that assumes Linux
754 }
755
756The C<else> branch should be used for the really ultimate fallback,
757not for code specific to some platform.
758
b7df3edc
GS
759Be careful in the tests you supply with your module or programs.
760Module code may be fully portable, but its tests might not be. This
761often happens when tests spawn off other processes or call external
762programs to aid in the testing, or when (as noted above) the tests
c87488a3
HS
763assume certain things about the filesystem and paths. Be careful not
764to depend on a specific output style for errors, such as when checking
765C<$!> after a failed system call. Using C<$!> for anything else than
2c044526 766displaying it as output is doubtful (though see the C<Errno> module for
c87488a3
HS
767testing reasonably portably for error value). Some platforms expect
768a certain output format, and Perl on those platforms may have been
769adjusted accordingly. Most specifically, don't anchor a regex when
770testing an error value.
e41182b5 771
0a47030a 772=head1 CPAN Testers
e41182b5 773
0a47030a
GS
774Modules uploaded to CPAN are tested by a variety of volunteers on
775different platforms. These CPAN testers are notified by mail of each
e41182b5 776new upload, and reply to the list with PASS, FAIL, NA (not applicable to
0a47030a 777this platform), or UNKNOWN (unknown), along with any relevant notations.
e41182b5
GS
778
779The purpose of the testing is twofold: one, to help developers fix any
0a47030a 780problems in their code that crop up because of lack of testing on other
b7df3edc 781platforms; two, to provide users with information about whether
0a47030a 782a given module works on a given platform.
e41182b5 783
2890cc8c 784Also see:
7ee27b7c 785
e41182b5
GS
786=over 4
787
7ee27b7c
AT
788=item *
789
636280bd 790Mailing list: cpan-testers-discuss@perl.org
7ee27b7c
AT
791
792=item *
e41182b5 793
500f1b69 794Testing results: L<http://www.cpantesters.org/>
e41182b5
GS
795
796=back
797
e41182b5
GS
798=head1 PLATFORMS
799
1bcbdd38
BF
800Perl is built with a C<$^O> variable that indicates the operating
801system it was built on. This was implemented
b7df3edc
GS
802to help speed up code that would otherwise have to C<use Config>
803and use the value of C<$Config{osname}>. Of course, to get more
e41182b5
GS
804detailed information about the system, looking into C<%Config> is
805certainly recommended.
806
b7df3edc
GS
807C<%Config> cannot always be trusted, however, because it was built
808at compile time. If perl was built in one place, then transferred
809elsewhere, some values may be wrong. The values may even have been
810edited after the fact.
6ab3f9cb 811
e41182b5
GS
812=head2 Unix
813
814Perl works on a bewildering variety of Unix and Unix-like platforms (see
815e.g. most of the files in the F<hints/> directory in the source code kit).
816On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
d1e3b762
GS
817too) is determined either by lowercasing and stripping punctuation from the
818first field of the string returned by typing C<uname -a> (or a similar command)
819at the shell prompt or by testing the file system for the presence of
820uniquely named files such as a kernel or header file. Here, for example,
821are a few of the more popular Unix flavors:
e41182b5 822
b7df3edc 823 uname $^O $Config{'archname'}
6ab3f9cb 824 --------------------------------------------
b7df3edc 825 AIX aix aix
6ab3f9cb 826 BSD/OS bsdos i386-bsdos
e1516da7 827 Darwin darwin darwin
6ab3f9cb 828 DYNIX/ptx dynixptx i386-dynixptx
2890cc8c 829 FreeBSD freebsd freebsd-i386
df00ff3b 830 Haiku haiku BePC-haiku
d1e3b762 831 Linux linux arm-linux
56b575b9 832 Linux linux armv5tel-linux
b7df3edc 833 Linux linux i386-linux
6ab3f9cb
GS
834 Linux linux i586-linux
835 Linux linux ppc-linux
b7df3edc
GS
836 HP-UX hpux PA-RISC1.1
837 IRIX irix irix
b787fad4 838 Mac OS X darwin darwin
d1e3b762
GS
839 NeXT 3 next next-fat
840 NeXT 4 next OPENSTEP-Mach
6ab3f9cb 841 openbsd openbsd i386-openbsd
b7df3edc 842 OSF1 dec_osf alpha-dec_osf
6ab3f9cb
GS
843 reliantunix-n svr4 RM400-svr4
844 SCO_SV sco_sv i386-sco_sv
845 SINIX-N svr4 RM400-svr4
846 sn4609 unicos CRAY_C90-unicos
847 sn6521 unicosmk t3e-unicosmk
848 sn9617 unicos CRAY_J90-unicos
b7df3edc
GS
849 SunOS solaris sun4-solaris
850 SunOS solaris i86pc-solaris
851 SunOS4 sunos sun4-sunos
e41182b5 852
b7df3edc
GS
853Because the value of C<$Config{archname}> may depend on the
854hardware architecture, it can vary more than the value of C<$^O>.
6ab3f9cb 855
e41182b5
GS
856=head2 DOS and Derivatives
857
b7df3edc 858Perl has long been ported to Intel-style microcomputers running under
e41182b5
GS
859systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
860bring yourself to mention (except for Windows CE, if you count that).
b7df3edc 861Users familiar with I<COMMAND.COM> or I<CMD.EXE> style shells should
e41182b5
GS
862be aware that each of these file specifications may have subtle
863differences:
864
ceaffd1d 865 my $filespec0 = "c:/foo/bar/file.txt";
866 my $filespec1 = "c:\\foo\\bar\\file.txt";
867 my $filespec2 = 'c:\foo\bar\file.txt';
868 my $filespec3 = 'c:\\foo\\bar\\file.txt';
e41182b5 869
b7df3edc
GS
870System calls accept either C</> or C<\> as the path separator.
871However, many command-line utilities of DOS vintage treat C</> as
872the option prefix, so may get confused by filenames containing C</>.
873Aside from calling any external programs, C</> will work just fine,
874and probably better, as it is more consistent with popular usage,
875and avoids the problem of remembering what to backwhack and what
876not to.
e41182b5 877
b7df3edc
GS
878The DOS FAT filesystem can accommodate only "8.3" style filenames. Under
879the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
0a47030a 880filesystems you may have to be careful about case returned with functions
e41182b5
GS
881like C<readdir> or used with functions like C<open> or C<opendir>.
882
b7df3edc
GS
883DOS also treats several filenames as special, such as AUX, PRN,
884NUL, CON, COM1, LPT1, LPT2, etc. Unfortunately, sometimes these
885filenames won't even work if you include an explicit directory
886prefix. It is best to avoid such filenames, if you want your code
887to be portable to DOS and its derivatives. It's hard to know what
888these all are, unfortunately.
e41182b5
GS
889
890Users of these operating systems may also wish to make use of
b7df3edc 891scripts such as I<pl2bat.bat> or I<pl2cmd> to
e41182b5
GS
892put wrappers around your scripts.
893
894Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
5a0de581 895and writing to files (see L</"Newlines">). C<binmode(FILEHANDLE)>
6ab3f9cb
GS
896will keep C<\n> translated as C<\012> for that filehandle. Since it is a
897no-op on other systems, C<binmode> should be used for cross-platform code
b7df3edc
GS
898that deals with binary data. That's assuming you realize in advance
899that your data is in binary. General-purpose programs should
900often assume nothing about their data.
e41182b5 901
b7df3edc 902The C<$^O> variable and the C<$Config{archname}> values for various
e41182b5
GS
903DOSish perls are as follows:
904
67ac489e
MS
905 OS $^O $Config{archname} ID Version
906 --------------------------------------------------------
2890cc8c
CBW
907 MS-DOS dos ?
908 PC-DOS dos ?
67ac489e
MS
909 OS/2 os2 ?
910 Windows 3.1 ? ? 0 3 01
911 Windows 95 MSWin32 MSWin32-x86 1 4 00
912 Windows 98 MSWin32 MSWin32-x86 1 4 10
913 Windows ME MSWin32 MSWin32-x86 1 ?
914 Windows NT MSWin32 MSWin32-x86 2 4 xx
915 Windows NT MSWin32 MSWin32-ALPHA 2 4 xx
916 Windows NT MSWin32 MSWin32-ppc 2 4 xx
7ee27b7c
AT
917 Windows 2000 MSWin32 MSWin32-x86 2 5 00
918 Windows XP MSWin32 MSWin32-x86 2 5 01
919 Windows 2003 MSWin32 MSWin32-x86 2 5 02
bc643a33
CJ
920 Windows Vista MSWin32 MSWin32-x86 2 6 00
921 Windows 7 MSWin32 MSWin32-x86 2 6 01
922 Windows 7 MSWin32 MSWin32-x64 2 6 01
ae525322
CBW
923 Windows 2008 MSWin32 MSWin32-x86 2 6 01
924 Windows 2008 MSWin32 MSWin32-x64 2 6 01
2890cc8c 925 Windows CE MSWin32 ? 3
7ee27b7c 926 Cygwin cygwin cygwin
e41182b5 927
34aaaa84 928The various MSWin32 Perl's can distinguish the OS they are running on
2890cc8c 929via the value of the fifth element of the list returned from
2c044526 930C<Win32::GetOSVersion()>. For example:
34aaaa84
PP
931
932 if ($^O eq 'MSWin32') {
933 my @os_version_info = Win32::GetOSVersion();
934 print +('3.1','95','NT')[$os_version_info[4]],"\n";
935 }
936
2c044526 937There are also C<Win32::IsWinNT()> and C<Win32::IsWin95()>; try C<perldoc Win32>,
7939d86b 938and as of libwin32 0.19 (not part of the core Perl distribution)
2c044526 939C<Win32::GetOSName()>. The very portable C<POSIX::uname()> will work too:
1d65be3a
JH
940
941 c:\> perl -MPOSIX -we "print join '|', uname"
942 Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
d99f392e 943
e41182b5
GS
944Also see:
945
946=over 4
947
c997b287 948=item *
e41182b5 949
500f1b69 950The djgpp environment for DOS, L<http://www.delorie.com/djgpp/>
c997b287 951and L<perldos>.
e41182b5 952
c997b287 953=item *
e41182b5 954
c997b287 955The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
500f1b69 956L<ftp://hobbes.nmsu.edu/pub/os2/dev/emx/> Also L<perlos2>.
e41182b5 957
c997b287 958=item *
d1e3b762 959
c997b287 960Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
2890cc8c 961in L<perlcygwin>.
c997b287
GS
962
963=item *
964
965The C<Win32::*> modules in L<Win32>.
966
967=item *
968
500f1b69 969The ActiveState Pages, L<http://www.activestate.com/>
c997b287
GS
970
971=item *
972
2890cc8c 973The Cygwin environment for Win32; F<README.cygwin> (installed
500f1b69 974as L<perlcygwin>), L<http://www.cygwin.com/>
c997b287
GS
975
976=item *
977
978The U/WIN environment for Win32,
500f1b69 979L<http://www.research.att.com/sw/tools/uwin/>
c997b287 980
cea6626f 981=item *
d1e3b762 982
cea6626f 983Build instructions for OS/2, L<perlos2>
d1e3b762 984
e41182b5
GS
985=back
986
e41182b5
GS
987=head2 VMS
988
2c044526 989Perl on VMS is discussed in L<perlvms> in the Perl distribution.
016930a6
JM
990
991The official name of VMS as of this writing is OpenVMS.
992
e41182b5
GS
993Interacting with Perl from the Digital Command Language (DCL) shell
994often requires a different set of quotation marks than Unix shells do.
995For example:
996
997 $ perl -e "print ""Hello, world.\n"""
998 Hello, world.
999
2c044526 1000There are several ways to wrap your Perl scripts in DCL F<.COM> files, if
e41182b5
GS
1001you are so inclined. For example:
1002
1003 $ write sys$output "Hello from DCL!"
1004 $ if p1 .eqs. ""
1005 $ then perl -x 'f$environment("PROCEDURE")
1006 $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
1007 $ deck/dollars="__END__"
1008 #!/usr/bin/perl
1009
1010 print "Hello from Perl!\n";
1011
1012 __END__
1013 $ endif
1014
1015Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
2c044526 1016Perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
e41182b5 1017
9e861032
CB
1018The VMS operating system has two filesystems, designated by their
1019on-disk structure (ODS) level: ODS-2 and its successor ODS-5. The
1020initial port of Perl to VMS pre-dates ODS-5, but all current testing and
1021development assumes ODS-5 and its capabilities, including case
1022preservation, extended characters in filespecs, and names up to 8192
1023bytes long.
016930a6 1024
9e861032
CB
1025Perl on VMS can accept either VMS- or Unix-style file
1026specifications as in either of the following:
1089a9e3 1027
9e861032
CB
1028 $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
1029 $ perl -ne "print if /perl_setup/i" /sys$login/login.com
1089a9e3 1030
9e861032 1031but not a mixture of both as in:
1089a9e3 1032
9e861032
CB
1033 $ perl -ne "print if /perl_setup/i" sys$login:/login.com
1034 Can't open sys$login:/login.com: file specification syntax error
e41182b5 1035
9e861032
CB
1036In general, the easiest path to portability is always to specify
1037filenames in Unix format unless they will need to be processed by native
1038commands or utilities. Because of this latter consideration, the
1039File::Spec module by default returns native format specifications
1040regardless of input format. This default may be reversed so that
1041filenames are always reported in Unix format by specifying the
1042C<DECC$FILENAME_UNIX_REPORT> feature logical in the environment.
1043
1044The file type, or extension, is always present in a VMS-format file
1045specification even if it's zero-length. This means that, by default,
1046C<readdir> will return a trailing dot on a file with no extension, so
2c044526
KW
1047where you would see C<"a"> on Unix you'll see C<"a."> on VMS. However,
1048the trailing dot may be suppressed by enabling the
9e861032
CB
1049C<DECC$READDIR_DROPDOTNOTYPE> feature in the environment (see the CRTL
1050documentation on feature logical names).
e41182b5 1051
5e12dbfa 1052What C<\n> represents depends on the type of file opened. It usually
2890cc8c
CBW
1053represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>,
1054C<\000>, C<\040>, or nothing depending on the file organization and
2c044526
KW
1055record format. The C<VMS::Stdio> module provides access to the
1056special C<fopen()> requirements of files with unusual attributes on VMS.
e41182b5 1057
e41182b5 1058The value of C<$^O> on OpenVMS is "VMS". To determine the architecture
9e861032 1059that you are running on refer to C<$Config{'archname'}>.
016930a6 1060
b7df3edc
GS
1061On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
1062logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
6ab3f9cb 1063calls to C<localtime> are adjusted to count offsets from
b7df3edc 106401-JAN-1970 00:00:00.00, just like Unix.
6ab3f9cb 1065
e41182b5
GS
1066Also see:
1067
1068=over 4
1069
c997b287
GS
1070=item *
1071
96090e4f 1072F<README.vms> (installed as F<README_vms>), L<perlvms>
c997b287
GS
1073
1074=item *
1075
1089a9e3 1076vmsperl list, vmsperl-subscribe@perl.org
e41182b5 1077
c997b287 1078=item *
e41182b5 1079
500f1b69 1080vmsperl on the web, L<http://www.sidhe.org/vmsperl/index.html>
e41182b5 1081
9e861032
CB
1082=item *
1083
1084VMS Software Inc. web site, L<http://www.vmssoftware.com>
1085
e41182b5
GS
1086=back
1087
495c5fdc
GP
1088=head2 VOS
1089
10fb90aa 1090Perl on VOS (also known as OpenVOS) is discussed in F<README.vos>
2c044526 1091in the Perl distribution (installed as L<perlvos>). Perl on VOS
10fb90aa
PG
1092can accept either VOS- or Unix-style file specifications as in
1093either of the following:
495c5fdc 1094
ea8b8ad2
VP
1095 $ perl -ne "print if /perl_setup/i" >system>notices
1096 $ perl -ne "print if /perl_setup/i" /system/notices
495c5fdc
GP
1097
1098or even a mixture of both as in:
1099
ea8b8ad2 1100 $ perl -ne "print if /perl_setup/i" >system/notices
495c5fdc 1101
b7df3edc 1102Even though VOS allows the slash character to appear in object
495c5fdc 1103names, because the VOS port of Perl interprets it as a pathname
10fb90aa
PG
1104delimiting character, VOS files, directories, or links whose
1105names contain a slash character cannot be processed. Such files
1106must be renamed before they can be processed by Perl.
1107
1108Older releases of VOS (prior to OpenVOS Release 17.0) limit file
1109names to 32 or fewer characters, prohibit file names from
1110starting with a C<-> character, and prohibit file names from
1111containing any character matching C<< tr/ !#%&'()*;<=>?// >>.
1112
1113Newer releases of VOS (OpenVOS Release 17.0 or later) support a
1114feature known as extended names. On these releases, file names
1115can contain up to 255 characters, are prohibited from starting
1116with a C<-> character, and the set of prohibited characters is
1117reduced to any character matching C<< tr/#%*<>?// >>. There are
c69ca1d4 1118restrictions involving spaces and apostrophes: these characters
10fb90aa
PG
1119must not begin or end a name, nor can they immediately precede or
1120follow a period. Additionally, a space must not immediately
1121precede another space or hyphen. Specifically, the following
1122character combinations are prohibited: space-space,
1123space-hyphen, period-space, space-period, period-apostrophe,
1124apostrophe-period, leading or trailing space, and leading or
1125trailing apostrophe. Although an extended file name is limited
1126to 255 characters, a path name is still limited to 256
1127characters.
1128
7d4dfb6d 1129The value of C<$^O> on VOS is "vos". To determine the
10fb90aa 1130architecture that you are running on without resorting to loading
2c044526 1131all of C<%Config> you can examine the content of the C<@INC> array
10fb90aa 1132like so:
495c5fdc 1133
7d4dfb6d 1134 if ($^O =~ /vos/) {
495c5fdc
GP
1135 print "I'm on a Stratus box!\n";
1136 } else {
1137 print "I'm not on a Stratus box!\n";
1138 die;
1139 }
1140
495c5fdc
GP
1141Also see:
1142
1143=over 4
1144
c997b287 1145=item *
495c5fdc 1146
cc07ed0b 1147F<README.vos> (installed as L<perlvos>)
c997b287
GS
1148
1149=item *
1150
1151The VOS mailing list.
495c5fdc 1152
7d4dfb6d
PG
1153There is no specific mailing list for Perl on VOS. You can contact
1154the Stratus Technologies Customer Assistance Center (CAC) for your
1155region, or you can use the contact information located in the
1156distribution files on the Stratus Anonymous FTP site.
495c5fdc 1157
c997b287
GS
1158=item *
1159
7d4dfb6d
PG
1160Stratus Technologies on the web at L<http://www.stratus.com>
1161
1162=item *
1163
1164VOS Open-Source Software on the web at L<http://ftp.stratus.com/pub/vos/vos.html>
495c5fdc
GP
1165
1166=back
1167
e41182b5
GS
1168=head2 EBCDIC Platforms
1169
6eb53dea
KW
1170v5.22 core Perl runs on z/OS (formerly OS/390). Theoretically it could
1171run on the successors of OS/400 on AS/400 minicomputers as well as
1172VM/ESA, and BS2000 for S/390 Mainframes. Such computers use EBCDIC
1173character sets internally (usually
0cc436d0 1174Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
6eb53dea
KW
1175systems).
1176
1177The rest of this section may need updating, but we don't know what it
1178should say. Please email comments to
1179L<perlbug@perl.org|mailto:perlbug@perl.org>.
1180
1181On the mainframe Perl currently works under the "Unix system
0cc436d0 1182services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
2c044526 1183the BS200 POSIX-BC system (BS2000 is supported in Perl 5.6 and greater).
522b859a 1184See L<perlos390> for details. Note that for OS/400 there is also a port of
1bcbdd38 1185Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as opposed to
2890cc8c 1186ILE which is EBCDIC-based), see L<perlos400>.
e41182b5 1187
7c5ffed3
JH
1188As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
1189sub-systems do not support the C<#!> shebang trick for script invocation.
2c044526 1190Hence, on OS/390 and VM/ESA Perl scripts can be executed with a header
7c5ffed3 1191similar to the following simple script:
e41182b5
GS
1192
1193 : # use perl
1194 eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
1195 if 0;
1196 #!/usr/local/bin/perl # just a comment really
1197
1198 print "Hello from perl!\n";
1199
d1e3b762
GS
1200OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
1201Calls to C<system> and backticks can use POSIX shell syntax on all
1202S/390 systems.
1203
b7df3edc 1204On the AS/400, if PERL5 is in your library list, you may need
2c044526 1205to wrap your Perl scripts in a CL procedure to invoke them like so:
6ab3f9cb
GS
1206
1207 BEGIN
1208 CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1209 ENDPGM
1210
2c044526 1211This will invoke the Perl script F<hello.pl> in the root of the
6ab3f9cb
GS
1212QOpenSys file system. On the AS/400 calls to C<system> or backticks
1213must use CL syntax.
1214
e41182b5 1215On these platforms, bear in mind that the EBCDIC character set may have
2c044526 1216an effect on what happens with some Perl functions (such as C<chr>,
0a47030a
GS
1217C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
1218well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
1219and C<|>, not to mention dealing with socket interfaces to ASCII computers
5a0de581 1220(see L</"Newlines">).
e41182b5 1221
b7df3edc
GS
1222Fortunately, most web servers for the mainframe will correctly
1223translate the C<\n> in the following statement to its ASCII equivalent
2c044526 1224(C<\r> is the same under both Unix and z/OS):
e41182b5
GS
1225
1226 print "Content-type: text/html\r\n\r\n";
1227
d1e3b762 1228The values of C<$^O> on some of these platforms includes:
e41182b5 1229
d1e3b762
GS
1230 uname $^O $Config{'archname'}
1231 --------------------------------------------
1232 OS/390 os390 os390
1233 OS400 os400 os400
1234 POSIX-BC posix-bc BS2000-posix-bc
3c075c7d 1235
e41182b5
GS
1236Some simple tricks for determining if you are running on an EBCDIC
1237platform could include any of the following (perhaps all):
1238
ce7b6f06 1239 if ("\t" eq "\005") { print "EBCDIC may be spoken here!\n"; }
e41182b5
GS
1240
1241 if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1242
1243 if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1244
b7df3edc 1245One thing you may not want to rely on is the EBCDIC encoding
0a47030a
GS
1246of punctuation characters since these may differ from code page to code
1247page (and once your module or script is rumoured to work with EBCDIC,
1248folks will want it to work with all EBCDIC character sets).
e41182b5
GS
1249
1250Also see:
1251
1252=over 4
1253
c997b287
GS
1254=item *
1255
6eb53dea 1256L<perlos390>, L<perlos400>, L<perlbs2000>, L<perlebcdic>.
c997b287
GS
1257
1258=item *
e41182b5
GS
1259
1260The perl-mvs@perl.org list is for discussion of porting issues as well as
1261general usage issues for all EBCDIC Perls. Send a message body of
1262"subscribe perl-mvs" to majordomo@perl.org.
1263
7ee27b7c 1264=item *
c997b287
GS
1265
1266AS/400 Perl information at
500f1b69 1267L<http://as400.rochester.ibm.com/>
d1e3b762 1268as well as on CPAN in the F<ports/> directory.
e41182b5
GS
1269
1270=back
1271
b8099c3d
CN
1272=head2 Acorn RISC OS
1273
b7df3edc 1274Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
2890cc8c 1275Unix, and because Unix filename emulation is turned on by default,
b7df3edc 1276most simple scripts will probably work "out of the box". The native
6ab3f9cb 1277filesystem is modular, and individual filesystems are free to be
0a47030a 1278case-sensitive or insensitive, and are usually case-preserving. Some
b7df3edc 1279native filesystems have name length limits, which file and directory
6ab3f9cb
GS
1280names are silently truncated to fit. Scripts should be aware that the
1281standard filesystem currently has a name length limit of B<10>
1282characters, with up to 77 items in a directory, but other filesystems
0a47030a 1283may not impose such limitations.
b8099c3d
CN
1284
1285Native filenames are of the form
1286
6ab3f9cb 1287 Filesystem#Special_Field::DiskName.$.Directory.Directory.File
dd9f0070 1288
b8099c3d
CN
1289where
1290
1291 Special_Field is not usually present, but may contain . and $ .
1292 Filesystem =~ m|[A-Za-z0-9_]|
1293 DsicName =~ m|[A-Za-z0-9_/]|
1294 $ represents the root directory
1295 . is the path separator
1296 @ is the current directory (per filesystem but machine global)
1297 ^ is the parent directory
1298 Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1299
1300The default filename translation is roughly C<tr|/.|./|;>
1301
6ab3f9cb 1302Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
0a47030a
GS
1303the second stage of C<$> interpolation in regular expressions will fall
1304foul of the C<$.> if scripts are not careful.
1305
1306Logical paths specified by system variables containing comma-separated
b7df3edc 1307search lists are also allowed; hence C<System:Modules> is a valid
0a47030a 1308filename, and the filesystem will prefix C<Modules> with each section of
6ab3f9cb 1309C<System$Path> until a name is made that points to an object on disk.
b7df3edc 1310Writing to a new file C<System:Modules> would be allowed only if
0a47030a
GS
1311C<System$Path> contains a single item list. The filesystem will also
1312expand system variables in filenames if enclosed in angle brackets, so
c47ff5f1 1313C<< <System$Dir>.Modules >> would look for the file
0a47030a 1314S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is
c47ff5f1 1315that B<fully qualified filenames can start with C<< <> >>> and should
0a47030a 1316be protected when C<open> is used for input.
b8099c3d
CN
1317
1318Because C<.> was in use as a directory separator and filenames could not
1319be assumed to be unique after 10 characters, Acorn implemented the C
1320compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
1321filenames specified in source code and store the respective files in
b7df3edc 1322subdirectories named after the suffix. Hence files are translated:
b8099c3d
CN
1323
1324 foo.h h.foo
1325 C:foo.h C:h.foo (logical path variable)
1326 sys/os.h sys.h.os (C compiler groks Unix-speak)
1327 10charname.c c.10charname
1328 10charname.o o.10charname
1329 11charname_.c c.11charname (assuming filesystem truncates at 10)
1330
1331The Unix emulation library's translation of filenames to native assumes
b7df3edc
GS
1332that this sort of translation is required, and it allows a user-defined list
1333of known suffixes that it will transpose in this fashion. This may
92863ac5
KW
1334seem transparent, but consider that with these rules F<foo/bar/baz.h>
1335and F<foo/bar/h/baz> both map to F<foo.bar.h.baz>, and that C<readdir> and
0a47030a 1336C<glob> cannot and do not attempt to emulate the reverse mapping. Other
6ab3f9cb 1337C<.>'s in filenames are translated to C</>.
0a47030a 1338
b7df3edc 1339As implied above, the environment accessed through C<%ENV> is global, and
0a47030a 1340the convention is that program specific environment variables are of the
6ab3f9cb
GS
1341form C<Program$Name>. Each filesystem maintains a current directory,
1342and the current filesystem's current directory is the B<global> current
b7df3edc
GS
1343directory. Consequently, sociable programs don't change the current
1344directory but rely on full pathnames, and programs (and Makefiles) cannot
0a47030a
GS
1345assume that they can spawn a child process which can change the current
1346directory without affecting its parent (and everyone else for that
1347matter).
1348
2890cc8c 1349Because native operating system filehandles are global and are currently
b7df3edc 1350allocated down from 255, with 0 being a reserved value, the Unix emulation
0a47030a
GS
1351library emulates Unix filehandles. Consequently, you can't rely on
1352passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
1353
1354The desire of users to express filenames of the form
c47ff5f1 1355C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
0a47030a 1356too: C<``> command output capture has to perform a guessing game. It
c47ff5f1 1357assumes that a string C<< <[^<>]+\$[^<>]> >> is a
0a47030a 1358reference to an environment variable, whereas anything else involving
c47ff5f1 1359C<< < >> or C<< > >> is redirection, and generally manages to be 99%
0a47030a
GS
1360right. Of course, the problem remains that scripts cannot rely on any
1361Unix tools being available, or that any tools found have Unix-like command
1362line arguments.
1363
b7df3edc
GS
1364Extensions and XS are, in theory, buildable by anyone using free
1365tools. In practice, many don't, as users of the Acorn platform are
1366used to binary distributions. MakeMaker does run, but no available
1367make currently copes with MakeMaker's makefiles; even if and when
1368this should be fixed, the lack of a Unix-like shell will cause
1369problems with makefile rules, especially lines of the form C<cd
1370sdbm && make all>, and anything using quoting.
b8099c3d
CN
1371
1372"S<RISC OS>" is the proper name for the operating system, but the value
1373in C<$^O> is "riscos" (because we don't like shouting).
1374
e41182b5
GS
1375=head2 Other perls
1376
b7df3edc 1377Perl has been ported to many platforms that do not fit into any of
b6c36746 1378the categories listed above. Some, such as AmigaOS,
cd86ed9d
JV
1379QNX, Plan 9, and VOS, have been well-integrated into the standard
1380Perl source code kit. You may need to see the F<ports/> directory
1381on CPAN for information, and possibly binaries, for the likes of:
1382aos, Atari ST, lynxos, riscos, Novell Netware, Tandem Guardian,
1383I<etc.> (Yes, we know that some of these OSes may fall under the
1384Unix category, but we are not a standards body.)
e41182b5 1385
d1e3b762
GS
1386Some approximate operating system names and their C<$^O> values
1387in the "OTHER" category include:
1388
1389 OS $^O $Config{'archname'}
1390 ------------------------------------------
1391 Amiga DOS amigaos m68k-amigos
d1e3b762 1392
e41182b5
GS
1393See also:
1394
1395=over 4
1396
c997b287
GS
1397=item *
1398
1399Amiga, F<README.amiga> (installed as L<perlamiga>).
1400
1401=item *
d1e3b762 1402
6ab3f9cb 1403A free perl5-based PERL.NLM for Novell Netware is available in
500f1b69 1404precompiled binary and source code form from L<http://www.novell.com/>
6ab3f9cb 1405as well as from CPAN.
e41182b5 1406
13a2d996 1407=item *
c997b287 1408
e6f03d26 1409S<Plan 9>, F<README.plan9>
d1e3b762 1410
e41182b5
GS
1411=back
1412
e41182b5
GS
1413=head1 FUNCTION IMPLEMENTATIONS
1414
b7df3edc
GS
1415Listed below are functions that are either completely unimplemented
1416or else have been implemented differently on various platforms.
1417Following each description will be, in parentheses, a list of
1418platforms that the description applies to.
e41182b5 1419
b7df3edc
GS
1420The list may well be incomplete, or even wrong in some places. When
1421in doubt, consult the platform-specific README files in the Perl
1422source distribution, and any other documentation resources accompanying
1423a given port.
e41182b5 1424
0a47030a 1425Be aware, moreover, that even among Unix-ish systems there are variations.
e41182b5 1426
b7df3edc 1427For many functions, you can also query C<%Config>, exported by
2c044526 1428default from the C<Config> module. For example, to check whether the
b7df3edc
GS
1429platform has the C<lstat> call, check C<$Config{d_lstat}>. See
1430L<Config> for a full description of available variables.
e41182b5
GS
1431
1432=head2 Alphabetical Listing of Perl Functions
1433
1434=over 8
1435
e41182b5
GS
1436=item -X
1437
038ae9a4
SH
1438C<-w> only inspects the read-only file attribute (FILE_ATTRIBUTE_READONLY),
1439which determines whether the directory can be deleted, not whether it can
1440be written to. Directories always have read and write access unless denied
1441by discretionary access control lists (DACLs). (S<Win32>)
1442
b7df3edc
GS
1443C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
1444which may not reflect UIC-based file protections. (VMS)
e41182b5 1445
b8099c3d
CN
1446C<-s> by name on an open file will return the space reserved on disk,
1447rather than the current extent. C<-s> on an open filehandle returns the
b7df3edc 1448current size. (S<RISC OS>)
b8099c3d 1449
e41182b5 1450C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
204ad8d5 1451C<-x>, C<-o>. (Win32, VMS, S<RISC OS>)
e41182b5 1452
287a962e 1453C<-g>, C<-k>, C<-l>, C<-u>, C<-A> are not particularly meaningful.
b8099c3d 1454(Win32, VMS, S<RISC OS>)
e41182b5 1455
287a962e
JD
1456C<-p> is not particularly meaningful. (VMS, S<RISC OS>)
1457
e41182b5
GS
1458C<-d> is true if passed a device spec without an explicit directory.
1459(VMS)
1460
e41182b5 1461C<-x> (or C<-X>) determine if a file ends in one of the executable
b7df3edc 1462suffixes. C<-S> is meaningless. (Win32)
e41182b5 1463
b8099c3d
CN
1464C<-x> (or C<-X>) determine if a file has an executable file type.
1465(S<RISC OS>)
1466
aca72608
JD
1467=item alarm
1468
1469Emulated using timers that must be explicitly polled whenever Perl
1470wants to dispatch "safe signals" and therefore cannot interrupt
1471blocking system calls. (Win32)
1472
47cd99a4 1473=item atan2
519bc777
RGS
1474
1475Due to issues with various CPUs, math libraries, compilers, and standards,
1476results for C<atan2()> may vary depending on any combination of the above.
1477Perl attempts to conform to the Open Group/IEEE standards for the results
1478returned from C<atan2()>, but cannot force the issue if the system Perl is
2890cc8c 1479run on does not allow it. (Tru64, HP-UX 10.20)
519bc777 1480
2890cc8c 1481The current version of the standards for C<atan2()> is available at
519bc777
RGS
1482L<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
1483
47cd99a4 1484=item binmode
e41182b5 1485
204ad8d5 1486Meaningless. (S<RISC OS>)
e41182b5
GS
1487
1488Reopens file and restores pointer; if function fails, underlying
1489filehandle may be closed, or pointer may be in a different position.
1490(VMS)
1491
1492The value returned by C<tell> may be affected after the call, and
1493the filehandle may be flushed. (Win32)
1494
47cd99a4 1495=item chmod
e41182b5 1496
e41182b5
GS
1497Only good for changing "owner" read-write access, "group", and "other"
1498bits are meaningless. (Win32)
1499
b8099c3d
CN
1500Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1501
495c5fdc
GP
1502Access permissions are mapped onto VOS access-control list changes. (VOS)
1503
4e51f8e4 1504The actual permissions set depend on the value of the C<CYGWIN>
789f0d36 1505in the SYSTEM environment settings. (Cygwin)
4e51f8e4 1506
2c044526 1507Setting the exec bit on some locations (generally F</sdcard>) will return true
43b08d74
BF
1508but not actually set the bit. (Android)
1509
47cd99a4 1510=item chown
e41182b5 1511
204ad8d5 1512Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
e41182b5
GS
1513
1514Does nothing, but won't fail. (Win32)
1515
3fd80bd6
PG
1516A little funky, because VOS's notion of ownership is a little funky (VOS).
1517
e41182b5
GS
1518=item chroot
1519
043fec90 1520Not implemented. (Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
e41182b5 1521
47cd99a4 1522=item crypt
e41182b5
GS
1523
1524May not be available if library or source was not provided when building
b8099c3d 1525perl. (Win32)
e41182b5 1526
43b08d74
BF
1527Not implemented. (Android)
1528
47cd99a4 1529=item dbmclose
e41182b5 1530
e6f03d26 1531Not implemented. (VMS, S<Plan 9>, VOS)
e41182b5 1532
47cd99a4 1533=item dbmopen
e41182b5 1534
e6f03d26 1535Not implemented. (VMS, S<Plan 9>, VOS)
e41182b5 1536
47cd99a4 1537=item dump
e41182b5 1538
204ad8d5 1539Not useful. (S<RISC OS>)
e41182b5 1540
84d78eb7 1541Not supported. (Cygwin, Win32)
e41182b5 1542
b8099c3d 1543Invokes VMS debugger. (VMS)
e41182b5 1544
47cd99a4 1545=item exec
e41182b5 1546
94d4006a 1547C<exec LIST> without the use of indirect object syntax (C<exec PROGRAM LIST>)
2c044526 1548may fall back to trying the shell if the first C<spawn()> fails. (Win32)
94d4006a 1549
0f897271
GS
1550Does not automatically flush output handles on some platforms.
1551(SunOS, Solaris, HP-UX)
1552
af8bb25a
FC
1553Not supported. (Symbian OS)
1554
fe12c0e8
MS
1555=item exit
1556
2c044526
KW
1557Emulates Unix C<exit()> (which considers C<exit 1> to indicate an error) by
1558mapping the C<1> to C<SS$_ABORT> (C<44>). This behavior may be overridden
1559with the pragma C<use vmsish 'exit'>. As with the CRTL's C<exit()>
1560function, C<exit 0> is also mapped to an exit status of C<SS$_NORMAL>
1561(C<1>); this mapping cannot be overridden. Any other argument to
1562C<exit()>
016930a6
JM
1563is used directly as Perl's exit status. On VMS, unless the future
1564POSIX_EXIT mode is enabled, the exit code should always be a valid
1565VMS exit code and not a generic number. When the POSIX_EXIT mode is
1566enabled, a generic number will be encoded in a method compatible with
1567the C library _POSIX_EXIT macro so that it can be decoded by other
1568programs, particularly ones written in C, like the GNV package. (VMS)
fe12c0e8 1569
2890cc8c
CBW
1570C<exit()> resets file pointers, which is a problem when called
1571from a child process (created by C<fork()>) in C<BEGIN>.
bef2c191
RB
1572A workaround is to use C<POSIX::_exit>. (Solaris)
1573
1574 exit unless $Config{archname} =~ /\bsolaris\b/;
1575 require POSIX and POSIX::_exit(0);
1576
47cd99a4 1577=item fcntl
e41182b5 1578
016930a6 1579Not implemented. (Win32)
6a065175 1580
016930a6 1581Some functions available based on the version of VMS. (VMS)
e41182b5 1582
47cd99a4 1583=item flock
e41182b5 1584
204ad8d5 1585Not implemented (VMS, S<RISC OS>, VOS).
e41182b5 1586
e41182b5
GS
1587=item fork
1588
043fec90 1589Not implemented. (AmigaOS, S<RISC OS>, VMS)
0f897271
GS
1590
1591Emulated using multiple interpreters. See L<perlfork>. (Win32)
1592
1593Does not automatically flush output handles on some platforms.
1594(SunOS, Solaris, HP-UX)
e41182b5
GS
1595
1596=item getlogin
1597
204ad8d5 1598Not implemented. (S<RISC OS>)
e41182b5 1599
47cd99a4 1600=item getpgrp
e41182b5 1601
204ad8d5 1602Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1603
1604=item getppid
1605
204ad8d5 1606Not implemented. (Win32, S<RISC OS>)
e41182b5 1607
47cd99a4 1608=item getpriority
e41182b5 1609
043fec90 1610Not implemented. (Win32, VMS, S<RISC OS>, VOS)
e41182b5 1611
47cd99a4 1612=item getpwnam
e41182b5 1613
204ad8d5 1614Not implemented. (Win32)
e41182b5 1615
b8099c3d
CN
1616Not useful. (S<RISC OS>)
1617
47cd99a4 1618=item getgrnam
e41182b5 1619
204ad8d5 1620Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5 1621
47cd99a4 1622=item getnetbyname
e41182b5 1623
43b08d74 1624Not implemented. (Android, Win32, S<Plan 9>)
e41182b5 1625
47cd99a4 1626=item getpwuid
e41182b5 1627
204ad8d5 1628Not implemented. (Win32)
e41182b5 1629
b8099c3d
CN
1630Not useful. (S<RISC OS>)
1631
47cd99a4 1632=item getgrgid
e41182b5 1633
204ad8d5 1634Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5 1635
47cd99a4 1636=item getnetbyaddr
e41182b5 1637
43b08d74 1638Not implemented. (Android, Win32, S<Plan 9>)
e41182b5 1639
47cd99a4 1640=item getprotobynumber
e41182b5 1641
43b08d74
BF
1642Not implemented. (Android)
1643
47cd99a4 1644=item getservbyport
e41182b5 1645
e41182b5
GS
1646=item getpwent
1647
43b08d74 1648Not implemented. (Android, Win32)
e41182b5
GS
1649
1650=item getgrent
1651
43b08d74 1652Not implemented. (Android, Win32, VMS)
e41182b5 1653
ef5a6dd7
JH
1654=item gethostbyname
1655
1656C<gethostbyname('localhost')> does not work everywhere: you may have
204ad8d5 1657to use C<gethostbyname('127.0.0.1')>. (S<Irix 5>)
ef5a6dd7 1658
e41182b5
GS
1659=item gethostent
1660
204ad8d5 1661Not implemented. (Win32)
e41182b5
GS
1662
1663=item getnetent
1664
43b08d74 1665Not implemented. (Android, Win32, S<Plan 9>)
e41182b5
GS
1666
1667=item getprotoent
1668
43b08d74 1669Not implemented. (Android, Win32, S<Plan 9>)
e41182b5
GS
1670
1671=item getservent
1672
e6f03d26 1673Not implemented. (Win32, S<Plan 9>)
e41182b5 1674
43b08d74
BF
1675=item seekdir
1676
1677Not implemented. (Android)
1678
47cd99a4 1679=item sethostent
e41182b5 1680
43b08d74 1681Not implemented. (Android, Win32, S<Plan 9>, S<RISC OS>)
e41182b5 1682
47cd99a4 1683=item setnetent
e41182b5 1684
204ad8d5 1685Not implemented. (Win32, S<Plan 9>, S<RISC OS>)
e41182b5 1686
47cd99a4 1687=item setprotoent
e41182b5 1688
43b08d74 1689Not implemented. (Android, Win32, S<Plan 9>, S<RISC OS>)
e41182b5 1690
47cd99a4 1691=item setservent
e41182b5 1692
e6f03d26 1693Not implemented. (S<Plan 9>, Win32, S<RISC OS>)
e41182b5
GS
1694
1695=item endpwent
1696
b5afd346 1697Not implemented. (Win32)
e41182b5 1698
43b08d74
BF
1699Either not implemented or a no-op. (Android)
1700
e41182b5
GS
1701=item endgrent
1702
43b08d74 1703Not implemented. (Android, S<RISC OS>, VMS, Win32)
e41182b5
GS
1704
1705=item endhostent
1706
43b08d74 1707Not implemented. (Android, Win32)
e41182b5
GS
1708
1709=item endnetent
1710
43b08d74 1711Not implemented. (Android, Win32, S<Plan 9>)
e41182b5
GS
1712
1713=item endprotoent
1714
43b08d74 1715Not implemented. (Android, Win32, S<Plan 9>)
e41182b5
GS
1716
1717=item endservent
1718
e6f03d26 1719Not implemented. (S<Plan 9>, Win32)
e41182b5
GS
1720
1721=item getsockopt SOCKET,LEVEL,OPTNAME
1722
e6f03d26 1723Not implemented. (S<Plan 9>)
e41182b5 1724
e41182b5
GS
1725=item glob
1726
2c044526 1727This operator is implemented via the C<File::Glob> extension on most
63f87e49 1728platforms. See L<File::Glob> for portability information.
b8099c3d 1729
62aa5637
MS
1730=item gmtime
1731
2c044526 1732In theory, C<gmtime()> is reliable from -2**63 to 2**63-1. However,
461d5a49
MS
1733because work arounds in the implementation use floating point numbers,
1734it will become inaccurate as the time gets larger. This is a bug and
1735will be fixed in the future.
62aa5637 1736
10fb90aa
PG
1737On VOS, time values are 32-bit quantities.
1738
e41182b5
GS
1739=item ioctl FILEHANDLE,FUNCTION,SCALAR
1740
1741Not implemented. (VMS)
1742
2c044526 1743Available only for socket handles, and it does what the C<ioctlsocket()> call
e41182b5
GS
1744in the Winsock API does. (Win32)
1745
b8099c3d
CN
1746Available only for socket handles. (S<RISC OS>)
1747
47cd99a4 1748=item kill
e41182b5 1749
862b5365 1750Not implemented, hence not useful for taint checking. (S<RISC OS>)
e41182b5 1751
63f87e49
GS
1752C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
1753a signal to the identified process like it does on Unix platforms.
2c044526 1754Instead C<kill($sig, $pid)> terminates the process identified by C<$pid>,
63f87e49
GS
1755and makes it exit immediately with exit status $sig. As in Unix, if
1756$sig is 0 and the specified process exists, it returns true without
1757actually terminating it. (Win32)
e41182b5 1758
2c044526 1759C<kill(-9, $pid)> will terminate the process specified by C<$pid> and
d0302514
JD
1760recursively all child processes owned by it. This is different from
1761the Unix semantics, where the signal will be delivered to all
1762processes in the same process group as the process specified by
1763$pid. (Win32)
1764
96f902ff
CB
1765A pid of -1 indicating all processes on the system is not currently
1766supported. (VMS)
016930a6 1767
47cd99a4 1768=item link
e41182b5 1769
b5afd346 1770Not implemented. (S<RISC OS>, VOS)
e41182b5 1771
433acd8a
JH
1772Link count not updated because hard links are not quite that hard
1773(They are sort of half-way between hard and soft links). (AmigaOS)
1774
63d6c08b
JD
1775Hard links are implemented on Win32 under NTFS only. They are
1776natively supported on Windows 2000 and later. On Windows NT they
1777are implemented using the Windows POSIX subsystem support and the
1778Perl process will need Administrator or Backup Operator privileges
1779to create hard links.
a3dfe201 1780
016930a6
JM
1781Available on 64 bit OpenVMS 8.2 and later. (VMS)
1782
62aa5637
MS
1783=item localtime
1784
a61fc69c 1785localtime() has the same range as L</gmtime>, but because time zone
dc164757
MS
1786rules change its accuracy for historical and future times may degrade
1787but usually by no more than an hour.
62aa5637 1788
e41182b5
GS
1789=item lstat
1790
016930a6 1791Not implemented. (S<RISC OS>)
e41182b5 1792
63f87e49 1793Return values (especially for device and inode) may be bogus. (Win32)
e41182b5 1794
47cd99a4 1795=item msgctl
e41182b5 1796
47cd99a4 1797=item msgget
e41182b5 1798
47cd99a4 1799=item msgsnd
e41182b5 1800
47cd99a4 1801=item msgrcv
e41182b5 1802
43b08d74 1803Not implemented. (Android, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
e41182b5 1804
47cd99a4 1805=item open
e41182b5 1806
204ad8d5 1807open to C<|-> and C<-|> are unsupported. (Win32, S<RISC OS>)
e41182b5 1808
0f897271
GS
1809Opening a process does not automatically flush output handles on some
1810platforms. (SunOS, Solaris, HP-UX)
1811
e41182b5
GS
1812=item readlink
1813
b8099c3d 1814Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5 1815
47cd99a4 1816=item rename
c9b2b9d4
SS
1817
1818Can't move directories between directories on different logical volumes. (Win32)
1819
3ba4b5c1
JD
1820=item rewinddir
1821
2c044526
KW
1822Will not cause C<readdir()> to re-read the directory stream. The entries
1823already read before the C<rewinddir()> call will just be returned again
3ba4b5c1
JD
1824from a cache buffer. (Win32)
1825
47cd99a4 1826=item select
e41182b5 1827
689c5c24 1828Only implemented on sockets. (Win32, VMS)
e41182b5 1829
b8099c3d
CN
1830Only reliable on sockets. (S<RISC OS>)
1831
76e05f0b 1832Note that the C<select FILEHANDLE> form is generally portable.
63f87e49 1833
47cd99a4 1834=item semctl
e41182b5 1835
47cd99a4 1836=item semget
e41182b5 1837
47cd99a4 1838=item semop
e41182b5 1839
43b08d74 1840Not implemented. (Android, Win32, VMS, S<RISC OS>)
e41182b5 1841
a3dfe201
GS
1842=item setgrent
1843
43b08d74 1844Not implemented. (Android, VMS, Win32, S<RISC OS>)
a3dfe201 1845
47cd99a4 1846=item setpgrp
e41182b5 1847
204ad8d5 1848Not implemented. (Win32, VMS, S<RISC OS>, VOS)
e41182b5 1849
47cd99a4 1850=item setpriority
e41182b5 1851
204ad8d5 1852Not implemented. (Win32, VMS, S<RISC OS>, VOS)
e41182b5 1853
a3dfe201
GS
1854=item setpwent
1855
43b08d74 1856Not implemented. (Android, Win32, S<RISC OS>)
a3dfe201 1857
47cd99a4 1858=item setsockopt
e41182b5 1859
e6f03d26 1860Not implemented. (S<Plan 9>)
e41182b5 1861
47cd99a4 1862=item shmctl
e41182b5 1863
47cd99a4 1864=item shmget
e41182b5 1865
47cd99a4 1866=item shmread
e41182b5 1867
47cd99a4 1868=item shmwrite
e41182b5 1869
43b08d74 1870Not implemented. (Android, Win32, VMS, S<RISC OS>)
e41182b5 1871
001e9f89
DD
1872=item sleep
1873
3cd50447 1874Emulated using synchronization functions such that it can be
2c044526 1875interrupted by C<alarm()>, and limited to a maximum of 4294967 seconds,
3cd50447 1876approximately 49 days. (Win32)
001e9f89 1877
47cd99a4 1878=item sockatmark
80cbd5ad
JH
1879
1880A relatively recent addition to socket functions, may not
e1020413 1881be implemented even in Unix platforms.
80cbd5ad 1882
47cd99a4 1883=item socketpair
e41182b5 1884
043fec90 1885Not implemented. (S<RISC OS>)
10fb90aa 1886
016930a6 1887Available on 64 bit OpenVMS 8.2 and later. (VMS)
e41182b5 1888
e41182b5
GS
1889=item stat
1890
d62e1b7f
JH
1891Platforms that do not have rdev, blksize, or blocks will return these
1892as '', so numeric comparison or manipulation of these fields may cause
1893'not numeric' warnings.
1894
3f1f789b 1895ctime not supported on UFS (S<Mac OS X>).
e41182b5 1896
95a3fe12
MS
1897ctime is creation time instead of inode change time (Win32).
1898
e41182b5
GS
1899device and inode are not meaningful. (Win32)
1900
1901device and inode are not necessarily reliable. (VMS)
1902
b8099c3d
CN
1903mtime, atime and ctime all return the last modification time. Device and
1904inode are not necessarily reliable. (S<RISC OS>)
1905
d62e1b7f
JH
1906dev, rdev, blksize, and blocks are not available. inode is not
1907meaningful and will differ between stat calls on the same file. (os2)
1908
2c044526
KW
1909some versions of cygwin when doing a C<stat("foo")> and if not finding it
1910may then attempt to C<stat("foo.exe")> (Cygwin)
73e9292c 1911
2c044526 1912On Win32 C<stat()> needs to open the file to determine the link count
1fafdf34 1913and update attributes that may have been changed through hard links.
2c044526 1914Setting C<${^WIN32_SLOPPY_STAT}> to a true value speeds up C<stat()> by
1fafdf34
JD
1915not performing this operation. (Win32)
1916
47cd99a4 1917=item symlink
e41182b5 1918
c73b03b7
JM
1919Not implemented. (Win32, S<RISC OS>)
1920
1921Implemented on 64 bit VMS 8.3. VMS requires the symbolic link to be in Unix
1922syntax if it is intended to resolve to a valid path.
e41182b5 1923
47cd99a4 1924=item syscall
e41182b5 1925
043fec90 1926Not implemented. (Win32, VMS, S<RISC OS>, VOS)
e41182b5 1927
47cd99a4 1928=item sysopen
f34d0673 1929
dd9f0070 1930The traditional "0", "1", and "2" MODEs are implemented with different
322422de
GS
1931numeric values on some systems. The flags exported by C<Fcntl>
1932(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
043fec90 1933OS>, OS/390)
f34d0673 1934
47cd99a4 1935=item system
e41182b5 1936
e41182b5 1937As an optimization, may not call the command shell specified in
b7df3edc 1938C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
e41182b5
GS
1939process and immediately returns its process designator, without
1940waiting for it to terminate. Return value may be used subsequently
2c044526
KW
1941in C<wait> or C<waitpid>. Failure to C<spawn()> a subprocess is indicated
1942by setting C<$?> to S<C<"255 << 8">>. C<$?> is set in a way compatible with
1943Unix (i.e. the exitstatus of the subprocess is obtained by S<C<"$? >> 8">>,
63f87e49 1944as described in the documentation). (Win32)
e41182b5 1945
b8099c3d
CN
1946There is no shell to process metacharacters, and the native standard is
1947to pass a command line terminated by "\n" "\r" or "\0" to the spawned
c47ff5f1 1948program. Redirection such as C<< > foo >> is performed (if at all) by
b8099c3d
CN
1949the run time library of the spawned program. C<system> I<list> will call
1950the Unix emulation library's C<exec> emulation, which attempts to provide
1951emulation of the stdin, stdout, stderr in force in the parent, providing
1952the child program uses a compatible version of the emulation library.
1953I<scalar> will call the native command line direct and no such emulation
1954of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
1955
94d4006a 1956C<system LIST> without the use of indirect object syntax (C<system PROGRAM LIST>)
2c044526 1957may fall back to trying the shell if the first C<spawn()> fails. (Win32)
94d4006a 1958
0f897271
GS
1959Does not automatically flush output handles on some platforms.
1960(SunOS, Solaris, HP-UX)
1961
9bc98430
CB
1962The return value is POSIX-like (shifted up by 8 bits), which only allows
1963room for a made-up value derived from the severity bits of the native
2890cc8c 196432-bit condition code (unless overridden by C<use vmsish 'status'>).
016930a6
JM
1965If the native condition code is one that has a POSIX value encoded, the
1966POSIX value will be decoded to extract the expected exit value.
9bc98430
CB
1967For more details see L<perlvms/$?>. (VMS)
1968
43b08d74
BF
1969=item telldir
1970
1971Not implemented. (Android)
1972
e41182b5
GS
1973=item times
1974
63f87e49
GS
1975"cumulative" times will be bogus. On anything other than Windows NT
1976or Windows 2000, "system" time will be bogus, and "user" time is
2c044526 1977actually the time returned by the C<clock()> function in the C runtime
63f87e49 1978library. (Win32)
e41182b5 1979
b8099c3d
CN
1980Not useful. (S<RISC OS>)
1981
47cd99a4 1982=item truncate
e41182b5 1983
6d738113 1984Not implemented. (Older versions of VMS)
e41182b5 1985
3fd80bd6 1986Truncation to same-or-shorter lengths only. (VOS)
495c5fdc 1987
4cfdb94f 1988If a FILEHANDLE is supplied, it must be writable and opened in append
e71a7dc8 1989mode (i.e., use C<<< open(FH, '>>filename') >>>
4cfdb94f
GS
1990or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
1991should not be held open elsewhere. (Win32)
1992
e41182b5
GS
1993=item umask
1994
1bcbdd38 1995Returns undef where unavailable.
e41182b5 1996
b7df3edc
GS
1997C<umask> works but the correct permissions are set only when the file
1998is finally closed. (AmigaOS)
433acd8a 1999
47cd99a4 2000=item utime
e41182b5 2001
b6c36746 2002Only the modification time is updated. (VMS, S<RISC OS>)
e41182b5 2003
322422de 2004May not behave as expected. Behavior depends on the C runtime
2c044526 2005library's implementation of C<utime()>, and the filesystem being
322422de
GS
2006used. The FAT filesystem typically does not support an "access
2007time" field, and it may limit timestamps to a granularity of
2008two seconds. (Win32)
e41182b5
GS
2009
2010=item wait
2011
47cd99a4 2012=item waitpid
e41182b5 2013
e41182b5 2014Can only be applied to process handles returned for processes spawned
a6f858fb 2015using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32)
e41182b5 2016
b8099c3d
CN
2017Not useful. (S<RISC OS>)
2018
e41182b5
GS
2019=back
2020
2021
7c35b6af 2022=head1 Supported Platforms
ba58ab26 2023
7c35b6af
RGS
2024The following platforms are known to build Perl 5.12 (as of April 2010,
2025its release date) from the standard source code distribution available
500f1b69 2026at L<http://www.cpan.org/src>
bb377ba2 2027
bb377ba2
JV
2028=over
2029
2030=item Linux (x86, ARM, IA64)
2031
e0d9a2c8 2032=item HP-UX
bb377ba2
JV
2033
2034=item AIX
2035
2036=item Win32
2037
2038=over
2039
2040=item Windows 2000
2041
2042=item Windows XP
2043
2044=item Windows Server 2003
2045
2046=item Windows Vista
2047
2048=item Windows Server 2008
2049
3b665c47
JD
2050=item Windows 7
2051
bb377ba2
JV
2052=back
2053
2d9ede6e
JH
2054=item Cygwin
2055
67e52905
TC
2056Some tests are known to fail:
2057
2058=over
2059
2060=item *
2061
cb0ee57a 2062F<ext/XS-APItest/t/call_checker.t> - see
67e52905
TC
2063L<https://rt.perl.org/Ticket/Display.html?id=78502>
2064
2065=item *
2066
2067F<dist/I18N-Collate/t/I18N-Collate.t>
2068
2069=item *
2070
2071F<ext/Win32CORE/t/win32core.t> - may fail on recent cygwin installs.
2072
2073=back
2074
bb377ba2
JV
2075=item Solaris (x86, SPARC)
2076
1b0ab010
JV
2077=item OpenVMS
2078
2079=over
2080
2081=item Alpha (7.2 and later)
2082
2083=item I64 (8.2 and later)
2084
2085=back
bb377ba2
JV
2086
2087=item Symbian
2088
2089=item NetBSD
2090
2091=item FreeBSD
2092
2d8e9a35
CBW
2093=item Debian GNU/kFreeBSD
2094
bb377ba2
JV
2095=item Haiku
2096
2097=item Irix (6.5. What else?)
2098
2099=item OpenBSD
2100
2101=item Dragonfly BSD
2102
b60fc215
CBW
2103=item Midnight BSD
2104
a62bfce3
CBW
2105=item QNX Neutrino RTOS (6.5.0)
2106
bb377ba2
JV
2107=item MirOS BSD
2108
7d4dfb6d
PG
2109=item Stratus OpenVOS (17.0 or later)
2110
bb377ba2
JV
2111Caveats:
2112
2113=over
2114
2115=item time_t issues that may or may not be fixed
2116
2117=back
2118
bb377ba2
JV
2119=item Symbian (Series 60 v3, 3.2 and 5 - what else?)
2120
10fb90aa 2121=item Stratus VOS / OpenVOS
bb377ba2
JV
2122
2123=item AIX
2124
25be0a81
BF
2125=item Android
2126
dcfa7505
TC
2127=item FreeMINT
2128
2129Perl now builds with FreeMiNT/Atari. It fails a few tests, that needs
2130some investigation.
2131
2132The FreeMiNT port uses GNU dld for loadable module capabilities. So
2133ensure you have that library installed when building perl.
2134
bb377ba2
JV
2135=back
2136
2890cc8c 2137=head1 EOL Platforms
7b0e9f13
AD
2138
2139=head2 (Perl 5.20)
bb377ba2
JV
2140
2141The following platforms were supported by a previous version of
2142Perl but have been officially removed from Perl's source code
7b0e9f13 2143as of 5.20:
bb377ba2
JV
2144
2145=over
2146
7b0e9f13 2147=item AT&T 3b1
bb377ba2
JV
2148
2149=back
2150
7b0e9f13
AD
2151=head2 (Perl 5.14)
2152
8cbe99e5
JD
2153The following platforms were supported up to 5.10. They may still
2154have worked in 5.12, but supporting code has been removed for 5.14:
bb377ba2
JV
2155
2156=over
2157
2158=item Windows 95
2159
2160=item Windows 98
2161
2162=item Windows ME
2163
2164=item Windows NT4
2165
2166=back
2167
7b0e9f13
AD
2168=head2 (Perl 5.12)
2169
2170The following platforms were supported by a previous version of
2171Perl but have been officially removed from Perl's source code
2172as of 5.12:
2173
2174=over
2175
2176=item Atari MiNT
2177
2178=item Apollo Domain/OS
2179
2180=item Apple Mac OS 8/9
2181
2182=item Tenon Machten
2183
2184=back
2185
2186
bb377ba2
JV
2187=head1 Supported Platforms (Perl 5.8)
2188
2189As of July 2002 (the Perl release 5.8.0), the following platforms were
cec2c193 2190able to build Perl from the standard source code distribution
500f1b69 2191available at L<http://www.cpan.org/src/>
cec2c193
JH
2192
2193 AIX
2194 BeOS
6f683aa2 2195 BSD/OS (BSDi)
cec2c193 2196 Cygwin
ea297d26 2197 DG/UX
811b48f2 2198 DOS DJGPP 1)
cec2c193
JH
2199 DYNIX/ptx
2200 EPOC R5
2201 FreeBSD
6f683aa2 2202 HI-UXMPP (Hitachi) (5.8.0 worked but we didn't know it)
cec2c193
JH
2203 HP-UX
2204 IRIX
2205 Linux
8939ba94 2206 Mac OS Classic
6f683aa2 2207 Mac OS X (Darwin)
cec2c193
JH
2208 MPE/iX
2209 NetBSD
2210 NetWare
2211 NonStop-UX
6f683aa2 2212 ReliantUNIX (formerly SINIX)
cec2c193 2213 OpenBSD
6f683aa2 2214 OpenVMS (formerly VMS)
3ebac25b 2215 Open UNIX (Unixware) (since Perl 5.8.1/5.9.0)
cec2c193 2216 OS/2
522b859a 2217 OS/400 (using the PASE) (since Perl 5.8.1/5.9.0)
70de81db 2218 PowerUX
6f683aa2 2219 POSIX-BC (formerly BS2000)
cec2c193
JH
2220 QNX
2221 Solaris
70de81db 2222 SunOS 4
6f683aa2
JH
2223 SUPER-UX (NEC)
2224 Tru64 UNIX (formerly DEC OSF/1, Digital UNIX)
cec2c193
JH
2225 UNICOS
2226 UNICOS/mk
2227 UTS
7d4dfb6d 2228 VOS / OpenVOS
811b48f2 2229 Win95/98/ME/2K/XP 2)
c40b5d1d 2230 WinCE
6f683aa2 2231 z/OS (formerly OS/390)
cec2c193 2232 VM/ESA
ba58ab26 2233
811b48f2
JH
2234 1) in DOS mode either the DOS or OS/2 ports can be used
2235 2) compilers: Borland, MinGW (GCC), VC6
cec2c193 2236
c40b5d1d 2237The following platforms worked with the previous releases (5.6 and
cec2c193
JH
22385.7), but we did not manage either to fix or to test these in time
2239for the 5.8.0 release. There is a very good chance that many of these
70de81db 2240will work fine with the 5.8.0.
cec2c193 2241
8da2b1be 2242 BSD/OS
cec2c193
JH
2243 DomainOS
2244 Hurd
2245 LynxOS
2246 MachTen
2247 PowerMAX
2248 SCO SV
cec2c193
JH
2249 SVR4
2250 Unixware
2251 Windows 3.1
ba58ab26 2252
70de81db
JH
2253Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
2254
61988e87 2255 AmigaOS 3
70de81db 2256
ba58ab26 2257The following platforms have been known to build Perl from source in
fd46a41b
JH
2258the past (5.005_03 and earlier), but we haven't been able to verify
2259their status for the current release, either because the
2260hardware/software platforms are rare or because we don't have an
2261active champion on these platforms--or both. They used to work,
2262though, so go ahead and try compiling them, and let perlbug@perl.org
2263of any trouble.
ba58ab26 2264
cec2c193
JH
2265 3b1
2266 A/UX
cec2c193
JH
2267 ConvexOS
2268 CX/UX
2269 DC/OSx
2270 DDE SMES
2271 DOS EMX
2272 Dynix
2273 EP/IX
2274 ESIX
2275 FPS
2276 GENIX
2277 Greenhills
2278 ISC
2279 MachTen 68k
cec2c193
JH
2280 MPC
2281 NEWS-OS
2282 NextSTEP
2283 OpenSTEP
2284 Opus
2285 Plan 9
cec2c193 2286 RISC/os
8da2b1be 2287 SCO ODT/OSR
cec2c193
JH
2288 Stellar
2289 SVR2
2290 TI1500
2291 TitanOS
2292 Ultrix
2293 Unisys Dynix
ba58ab26
JH
2294
2295The following platforms have their own source code distributions and
500f1b69 2296binaries available via L<http://www.cpan.org/ports/>
ba58ab26 2297
cec2c193 2298 Perl release
ba58ab26 2299
522b859a 2300 OS/400 (ILE) 5.005_02
cec2c193 2301 Tandem Guardian 5.004
ba58ab26
JH
2302
2303The following platforms have only binaries available via
500f1b69 2304L<http://www.cpan.org/ports/index.html> :
ba58ab26 2305
cec2c193 2306 Perl release
ba58ab26 2307
cec2c193
JH
2308 Acorn RISCOS 5.005_02
2309 AOS 5.002
2310 LynxOS 5.004_02
ba58ab26
JH
2311
2312Although we do suggest that you always build your own Perl from
2313the source code, both for maximal configurability and for security,
2314in case you are in a hurry you can check
500f1b69 2315L<http://www.cpan.org/ports/index.html> for binary distributions.
ba58ab26 2316
c997b287
GS
2317=head1 SEE ALSO
2318
b6c36746 2319L<perlaix>, L<perlamiga>, L<perlbs2000>,
8d87852b 2320L<perlce>, L<perlcygwin>, L<perldos>,
469e7be4 2321L<perlebcdic>, L<perlfreebsd>, L<perlhurd>, L<perlhpux>, L<perlirix>,
b5afd346 2322L<perlmacos>, L<perlmacosx>,
522b859a
JH
2323L<perlnetware>, L<perlos2>, L<perlos390>, L<perlos400>,
2324L<perlplan9>, L<perlqnx>, L<perlsolaris>, L<perltru64>,
043fec90 2325L<perlunicode>, L<perlvms>, L<perlvos>, L<perlwin32>, and L<Win32>.
c997b287 2326
e41182b5
GS
2327=head1 AUTHORS / CONTRIBUTORS
2328
06e9666b 2329Abigail <abigail@foad.org>,
c47ff5f1
GS
2330Charles Bailey <bailey@newman.upenn.edu>,
2331Graham Barr <gbarr@pobox.com>,
2332Tom Christiansen <tchrist@perl.com>,
06e9666b 2333Nicholas Clark <nick@ccl4.org>,
c47ff5f1 2334Thomas Dorner <Thomas.Dorner@start.de>,
06e9666b
A
2335Andy Dougherty <doughera@lafayette.edu>,
2336Dominic Dunlop <domo@computer.org>,
2337Neale Ferguson <neale@vma.tabnsw.com.au>,
c47ff5f1 2338David J. Fiander <davidf@mks.com>,
3fd80bd6 2339Paul Green <Paul.Green@stratus.com>,
06e9666b 2340M.J.T. Guy <mjtg@cam.ac.uk>,
61f30a5e 2341Jarkko Hietaniemi <jhi@iki.fi>,
c47ff5f1 2342Luther Huffman <lutherh@stratcom.com>,
06e9666b
A
2343Nick Ing-Simmons <nick@ing-simmons.net>,
2344Andreas J. KE<ouml>nig <a.koenig@mind.de>,
c47ff5f1
GS
2345Markus Laker <mlaker@contax.co.uk>,
2346Andrew M. Langmead <aml@world.std.com>,
2347Larry Moore <ljmoore@freespace.net>,
2348Paul Moore <Paul.Moore@uk.origin-it.com>,
2349Chris Nandor <pudge@pobox.com>,
1afc07ec 2350Matthias Neeracher <neeracher@mac.com>,
e71a7dc8 2351Philip Newton <pne@cpan.org>,
c47ff5f1
GS
2352Gary Ng <71564.1743@CompuServe.COM>,
2353Tom Phoenix <rootbeer@teleport.com>,
2354AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
2355Peter Prymmer <pvhp@forte.com>,
2356Hugo van der Sanden <hv@crypt0.demon.co.uk>,
2357Gurusamy Sarathy <gsar@activestate.com>,
2358Paul J. Schinder <schinder@pobox.com>,
2359Michael G Schwern <schwern@pobox.com>,
06e9666b 2360Dan Sugalski <dan@sidhe.org>,
bbe548ff 2361Nathan Torkington <gnat@frii.com>,
016930a6 2362John Malmberg <wb8tyw@qsl.net>