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