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