This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
tweak sort() notes (from Nathan Torkington)
[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
e41182b5
GS
1226=item binmode FILEHANDLE
1227
b7df3edc 1228Meaningless. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1229
1230Reopens file and restores pointer; if function fails, underlying
1231filehandle may be closed, or pointer may be in a different position.
1232(VMS)
1233
1234The value returned by C<tell> may be affected after the call, and
1235the filehandle may be flushed. (Win32)
1236
1237=item chmod LIST
1238
b7df3edc 1239Only limited meaning. Disabling/enabling write permission is mapped to
e41182b5
GS
1240locking/unlocking the file. (S<Mac OS>)
1241
1242Only good for changing "owner" read-write access, "group", and "other"
1243bits are meaningless. (Win32)
1244
b8099c3d
CN
1245Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1246
495c5fdc
GP
1247Access permissions are mapped onto VOS access-control list changes. (VOS)
1248
e41182b5
GS
1249=item chown LIST
1250
495c5fdc 1251Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1252
1253Does nothing, but won't fail. (Win32)
1254
1255=item chroot FILENAME
1256
1257=item chroot
1258
7c5ffed3 1259Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1260
1261=item crypt PLAINTEXT,SALT
1262
1263May not be available if library or source was not provided when building
b8099c3d 1264perl. (Win32)
e41182b5 1265
495c5fdc
GP
1266Not implemented. (VOS)
1267
e41182b5
GS
1268=item dbmclose HASH
1269
495c5fdc 1270Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1271
1272=item dbmopen HASH,DBNAME,MODE
1273
495c5fdc 1274Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1275
1276=item dump LABEL
1277
b8099c3d 1278Not useful. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1279
1280Not implemented. (Win32)
1281
b8099c3d 1282Invokes VMS debugger. (VMS)
e41182b5
GS
1283
1284=item exec LIST
1285
1286Not implemented. (S<Mac OS>)
1287
7c5ffed3 1288Implemented via Spawn. (VM/ESA)
3c075c7d 1289
0f897271
GS
1290Does not automatically flush output handles on some platforms.
1291(SunOS, Solaris, HP-UX)
1292
e41182b5
GS
1293=item fcntl FILEHANDLE,FUNCTION,SCALAR
1294
1295Not implemented. (Win32, VMS)
1296
1297=item flock FILEHANDLE,OPERATION
1298
495c5fdc 1299Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
e41182b5
GS
1300
1301Available only on Windows NT (not on Windows 95). (Win32)
1302
1303=item fork
1304
0f897271
GS
1305Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VOS, VM/ESA)
1306
1307Emulated using multiple interpreters. See L<perlfork>. (Win32)
1308
1309Does not automatically flush output handles on some platforms.
1310(SunOS, Solaris, HP-UX)
e41182b5
GS
1311
1312=item getlogin
1313
b8099c3d 1314Not implemented. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1315
1316=item getpgrp PID
1317
495c5fdc 1318Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1319
1320=item getppid
1321
b8099c3d 1322Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1323
1324=item getpriority WHICH,WHO
1325
7c5ffed3 1326Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1327
1328=item getpwnam NAME
1329
1330Not implemented. (S<Mac OS>, Win32)
1331
b8099c3d
CN
1332Not useful. (S<RISC OS>)
1333
e41182b5
GS
1334=item getgrnam NAME
1335
b8099c3d 1336Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1337
1338=item getnetbyname NAME
1339
1340Not implemented. (S<Mac OS>, Win32, Plan9)
1341
1342=item getpwuid UID
1343
1344Not implemented. (S<Mac OS>, Win32)
1345
b8099c3d
CN
1346Not useful. (S<RISC OS>)
1347
e41182b5
GS
1348=item getgrgid GID
1349
b8099c3d 1350Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1351
1352=item getnetbyaddr ADDR,ADDRTYPE
1353
1354Not implemented. (S<Mac OS>, Win32, Plan9)
1355
1356=item getprotobynumber NUMBER
1357
1358Not implemented. (S<Mac OS>)
1359
1360=item getservbyport PORT,PROTO
1361
1362Not implemented. (S<Mac OS>)
1363
1364=item getpwent
1365
7c5ffed3 1366Not implemented. (S<Mac OS>, Win32, VM/ESA)
e41182b5
GS
1367
1368=item getgrent
1369
7c5ffed3 1370Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
e41182b5
GS
1371
1372=item gethostent
1373
1374Not implemented. (S<Mac OS>, Win32)
1375
1376=item getnetent
1377
1378Not implemented. (S<Mac OS>, Win32, Plan9)
1379
1380=item getprotoent
1381
1382Not implemented. (S<Mac OS>, Win32, Plan9)
1383
1384=item getservent
1385
1386Not implemented. (Win32, Plan9)
1387
1388=item setpwent
1389
b8099c3d 1390Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1391
1392=item setgrent
1393
b8099c3d 1394Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1395
1396=item sethostent STAYOPEN
1397
b8099c3d 1398Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1399
1400=item setnetent STAYOPEN
1401
b8099c3d 1402Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1403
1404=item setprotoent STAYOPEN
1405
b8099c3d 1406Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1407
1408=item setservent STAYOPEN
1409
b8099c3d 1410Not implemented. (Plan9, Win32, S<RISC OS>)
e41182b5
GS
1411
1412=item endpwent
1413
a3dfe201 1414Not implemented. (S<Mac OS>, MPE/iX, VM/ESA, Win32)
e41182b5
GS
1415
1416=item endgrent
1417
a3dfe201 1418Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
e41182b5
GS
1419
1420=item endhostent
1421
1422Not implemented. (S<Mac OS>, Win32)
1423
1424=item endnetent
1425
1426Not implemented. (S<Mac OS>, Win32, Plan9)
1427
1428=item endprotoent
1429
1430Not implemented. (S<Mac OS>, Win32, Plan9)
1431
1432=item endservent
1433
1434Not implemented. (Plan9, Win32)
1435
1436=item getsockopt SOCKET,LEVEL,OPTNAME
1437
1438Not implemented. (S<Mac OS>, Plan9)
1439
1440=item glob EXPR
1441
1442=item glob
1443
1444Globbing built-in, but only C<*> and C<?> metacharacters are supported.
1445(S<Mac OS>)
1446
b7df3edc 1447Features depend on external perlglob.exe or perlglob.bat. May be
0a47030a
GS
1448overridden with something like File::DosGlob, which is recommended.
1449(Win32)
e41182b5 1450
b8099c3d 1451Globbing built-in, but only C<*> and C<?> metacharacters are supported.
0a47030a
GS
1452Globbing relies on operating system calls, which may return filenames
1453in any order. As most filesystems are case-insensitive, even "sorted"
1454filenames will not be in case-sensitive order. (S<RISC OS>)
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
42b8b86c
GS
1470C<kill($sig, $pid)> makes the process exit immediately with exit
1471status $sig. As in Unix, if $sig is 0 and the specified process exists,
1472it returns true without actually terminating it. (Win32)
e41182b5
GS
1473
1474=item link OLDFILE,NEWFILE
1475
a3dfe201 1476Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
e41182b5 1477
433acd8a
JH
1478Link count not updated because hard links are not quite that hard
1479(They are sort of half-way between hard and soft links). (AmigaOS)
1480
a3dfe201
GS
1481Hard links are implemented on Win32 (Windows NT and Windows 2000)
1482under NTFS only.
1483
e41182b5
GS
1484=item lstat FILEHANDLE
1485
1486=item lstat EXPR
1487
1488=item lstat
1489
b8099c3d 1490Not implemented. (VMS, S<RISC OS>)
e41182b5 1491
b8099c3d 1492Return values may be bogus. (Win32)
e41182b5
GS
1493
1494=item msgctl ID,CMD,ARG
1495
1496=item msgget KEY,FLAGS
1497
1498=item msgsnd ID,MSG,FLAGS
1499
1500=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1501
495c5fdc 1502Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1503
1504=item open FILEHANDLE,EXPR
1505
1506=item open FILEHANDLE
1507
b7df3edc 1508The C<|> variants are supported only if ToolServer is installed.
e41182b5
GS
1509(S<Mac OS>)
1510
c47ff5f1 1511open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5 1512
0f897271
GS
1513Opening a process does not automatically flush output handles on some
1514platforms. (SunOS, Solaris, HP-UX)
1515
e41182b5
GS
1516=item pipe READHANDLE,WRITEHANDLE
1517
1518Not implemented. (S<Mac OS>)
1519
433acd8a
JH
1520Very limited functionality. (MiNT)
1521
e41182b5
GS
1522=item readlink EXPR
1523
1524=item readlink
1525
b8099c3d 1526Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1527
1528=item select RBITS,WBITS,EBITS,TIMEOUT
1529
1530Only implemented on sockets. (Win32)
1531
b8099c3d
CN
1532Only reliable on sockets. (S<RISC OS>)
1533
e41182b5
GS
1534=item semctl ID,SEMNUM,CMD,ARG
1535
1536=item semget KEY,NSEMS,FLAGS
1537
1538=item semop KEY,OPSTRING
1539
495c5fdc 1540Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5 1541
a3dfe201
GS
1542=item setgrent
1543
1544Not implemented. (MPE/iX, Win32)
1545
e41182b5
GS
1546=item setpgrp PID,PGRP
1547
495c5fdc 1548Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1549
1550=item setpriority WHICH,WHO,PRIORITY
1551
495c5fdc 1552Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5 1553
a3dfe201
GS
1554=item setpwent
1555
1556Not implemented. (MPE/iX, Win32)
1557
e41182b5
GS
1558=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1559
1560Not implemented. (S<Mac OS>, Plan9)
1561
1562=item shmctl ID,CMD,ARG
1563
1564=item shmget KEY,SIZE,FLAGS
1565
1566=item shmread ID,VAR,POS,SIZE
1567
1568=item shmwrite ID,STRING,POS,SIZE
1569
495c5fdc 1570Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1571
1572=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1573
7c5ffed3 1574Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1575
1576=item stat FILEHANDLE
1577
1578=item stat EXPR
1579
1580=item stat
1581
1582mtime and atime are the same thing, and ctime is creation time instead of
1583inode change time. (S<Mac OS>)
1584
1585device and inode are not meaningful. (Win32)
1586
1587device and inode are not necessarily reliable. (VMS)
1588
b8099c3d
CN
1589mtime, atime and ctime all return the last modification time. Device and
1590inode are not necessarily reliable. (S<RISC OS>)
1591
e41182b5
GS
1592=item symlink OLDFILE,NEWFILE
1593
b8099c3d 1594Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1595
1596=item syscall LIST
1597
7c5ffed3 1598Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5 1599
f34d0673
GS
1600=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1601
dd9f0070 1602The traditional "0", "1", and "2" MODEs are implemented with different
322422de
GS
1603numeric values on some systems. The flags exported by C<Fcntl>
1604(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
7c5ffed3 1605OS>, OS/390, VM/ESA)
f34d0673 1606
e41182b5
GS
1607=item system LIST
1608
1609Only implemented if ToolServer is installed. (S<Mac OS>)
1610
1611As an optimization, may not call the command shell specified in
b7df3edc 1612C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
e41182b5
GS
1613process and immediately returns its process designator, without
1614waiting for it to terminate. Return value may be used subsequently
1615in C<wait> or C<waitpid>. (Win32)
1616
b8099c3d
CN
1617There is no shell to process metacharacters, and the native standard is
1618to pass a command line terminated by "\n" "\r" or "\0" to the spawned
c47ff5f1 1619program. Redirection such as C<< > foo >> is performed (if at all) by
b8099c3d
CN
1620the run time library of the spawned program. C<system> I<list> will call
1621the Unix emulation library's C<exec> emulation, which attempts to provide
1622emulation of the stdin, stdout, stderr in force in the parent, providing
1623the child program uses a compatible version of the emulation library.
1624I<scalar> will call the native command line direct and no such emulation
1625of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
1626
433acd8a
JH
1627Far from being POSIX compliant. Because there may be no underlying
1628/bin/sh tries to work around the problem by forking and execing the
9b63e9ec 1629first token in its argument string. Handles basic redirection
c47ff5f1 1630("<" or ">") on its own behalf. (MiNT)
433acd8a 1631
0f897271
GS
1632Does not automatically flush output handles on some platforms.
1633(SunOS, Solaris, HP-UX)
1634
e41182b5
GS
1635=item times
1636
1637Only the first entry returned is nonzero. (S<Mac OS>)
1638
1639"cumulative" times will be bogus. On anything other than Windows NT,
1640"system" time will be bogus, and "user" time is actually the time
1641returned by the clock() function in the C runtime library. (Win32)
1642
b8099c3d
CN
1643Not useful. (S<RISC OS>)
1644
e41182b5
GS
1645=item truncate FILEHANDLE,LENGTH
1646
1647=item truncate EXPR,LENGTH
1648
1649Not implemented. (VMS)
1650
495c5fdc
GP
1651Truncation to zero-length only. (VOS)
1652
4cfdb94f
GS
1653If a FILEHANDLE is supplied, it must be writable and opened in append
1654mode (i.e., use C<open(FH, '>>filename')>
1655or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
1656should not be held open elsewhere. (Win32)
1657
e41182b5
GS
1658=item umask EXPR
1659
1660=item umask
1661
1662Returns undef where unavailable, as of version 5.005.
1663
b7df3edc
GS
1664C<umask> works but the correct permissions are set only when the file
1665is finally closed. (AmigaOS)
433acd8a 1666
e41182b5
GS
1667=item utime LIST
1668
b8099c3d 1669Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
e41182b5 1670
322422de
GS
1671May not behave as expected. Behavior depends on the C runtime
1672library's implementation of utime(), and the filesystem being
1673used. The FAT filesystem typically does not support an "access
1674time" field, and it may limit timestamps to a granularity of
1675two seconds. (Win32)
e41182b5
GS
1676
1677=item wait
1678
1679=item waitpid PID,FLAGS
1680
495c5fdc 1681Not implemented. (S<Mac OS>, VOS)
e41182b5
GS
1682
1683Can only be applied to process handles returned for processes spawned
1684using C<system(1, ...)>. (Win32)
1685
b8099c3d
CN
1686Not useful. (S<RISC OS>)
1687
e41182b5
GS
1688=back
1689
b8099c3d
CN
1690=head1 CHANGES
1691
1692=over 4
1693
56d7751a
GS
1694=item v1.46, 12 February 2000
1695
1696Updates for VOS and MPE/iX. (Peter Prymmer) Other small changes.
1697
0cc436d0
GS
1698=item v1.45, 20 December 1999
1699
1700Small changes from 5.005_63 distribution, more changes to EBCDIC info.
1701
d1e3b762
GS
1702=item v1.44, 19 July 1999
1703
1704A bunch of updates from Peter Prymmer for C<$^O> values,
1705endianness, File::Spec, VMS, BS2000, OS/400.
1706
b7df3edc
GS
1707=item v1.43, 24 May 1999
1708
1709Added a lot of cleaning up from Tom Christiansen.
1710
19799a22 1711=item v1.42, 22 May 1999
b7df3edc 1712
19799a22 1713Added notes about tests, sprintf/printf, and epoch offsets.
b7df3edc 1714
6ab3f9cb
GS
1715=item v1.41, 19 May 1999
1716
1717Lots more little changes to formatting and content.
1718
d1e3b762 1719Added a bunch of C<$^O> and related values
6ab3f9cb
GS
1720for various platforms; fixed mail and web addresses, and added
1721and changed miscellaneous notes. (Peter Prymmer)
1722
1723=item v1.40, 11 April 1999
1724
1725Miscellaneous changes.
1726
1727=item v1.39, 11 February 1999
2ee0eb3c
CN
1728
1729Changes from Jarkko and EMX URL fixes Michael Schwern. Additional
1730note about newlines added.
1731
9b63e9ec
CN
1732=item v1.38, 31 December 1998
1733
1734More changes from Jarkko.
1735
3c075c7d
CN
1736=item v1.37, 19 December 1998
1737
1738More minor changes. Merge two separate version 1.35 documents.
1739
1740=item v1.36, 9 September 1998
1741
1742Updated for Stratus VOS. Also known as version 1.35.
1743
1744=item v1.35, 13 August 1998
495c5fdc 1745
3c075c7d
CN
1746Integrate more minor changes, plus addition of new sections under
1747L<"ISSUES">: L<"Numbers endianness and Width">,
1748L<"Character sets and character encoding">,
1749L<"Internationalisation">.
495c5fdc 1750
3c075c7d 1751=item v1.33, 06 August 1998
0a47030a
GS
1752
1753Integrate more minor changes.
1754
3c075c7d 1755=item v1.32, 05 August 1998
dd9f0070
CN
1756
1757Integrate more minor changes.
1758
3c075c7d 1759=item v1.30, 03 August 1998
b8099c3d
CN
1760
1761Major update for RISC OS, other minor changes.
1762
3c075c7d 1763=item v1.23, 10 July 1998
b8099c3d
CN
1764
1765First public release with perl5.005.
1766
1767=back
e41182b5 1768
ba58ab26
JH
1769=head1 Supported Platforms
1770
1771As of early March 2000 (the Perl release 5.6.0), the following
1772platforms are able to build Perl from the standard source code
1773distribution available at http://www.perl.com/CPAN/src/index.html
1774
1775 AIX
1776 DOS DJGPP 1)
1777 FreeBSD
1778 HP-UX
1779 IRIX
1780 Linux
1781 LynxOS
1782 MachTen
1783 MPE/iX
1784 NetBSD
1785 OpenBSD
1786 OS/2
1787 QNX
1788 Rhapsody/Darwin 2)
1789 Solaris
1790 SVR4
1791 Tru64 UNIX 3)
1792 UNICOS
1793 UNICOS/mk
1794 Unixware
1795 VMS
1796 VOS
1797 Windows 3.1 1)
1798 Windows 95 1) 4)
1799 Windows 98 1) 4)
1800 Windows NT 1) 4)
1801
1802 1) in DOS mode either the DOS or OS/2 ports can be used
1803 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X
1804 3) formerly known as Digital UNIX and before that DEC OSF/1
1805 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
1806
1807The following platforms worked for the previous major release
1808(5.005_03 being the latest maintenance release of that, as of early
1809March 2000), but be did not manage to test these in time for the 5.6.0
1810release of Perl. There is a very good chance that these will work
1811just fine with 5.6.0.
1812
1813 A/UX
1814 BeOS
1815 BSD/OS
1816 DG/UX
1817 DYNIX/ptx
1818 DomainOS
1819 Hurd
1820 NextSTEP
1821 OpenSTEP
1822 PowerMAX
1823 SCO ODT/OSR
1824 SunOS
1825 Ultrix
1826
1827The following platform worked for the previous major release (5.005_03
1828being the latest maintenance release of that, as of early March 2000).
1829However, standardization on UTF-8 as the internal string representation
1830in 5.6.0 has introduced incompatibilities in this EBCDIC platform.
1831Support for this platform may be enabled in a future release:
1832
1833 OS390 1)
1834
1835 1) Previously known as MVS, or OpenEdition MVS.
1836
1837Strongly related to the OS390 platform by also being EBCDIC-based
1838mainframe platforms are the following platforms:
1839
1840 BS2000
1841 VM/ESA
1842
1843These are also not expected to work under 5.6.0 for the same reasons
1844as OS390. Contact the mailing list perl-mvs@perl.org for more details.
1845
1846MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source
1847does work with 5.6.0, but additional MacOS specific source code is needed
1848for a complete port. Contact the mailing list macperl-porters@macperl.org
1849for more information.
1850
1851The following platforms have been known to build Perl from source in
1852the past, but we haven't been able to verify their status for the
1853current release, either because the hardware/software platforms are
1854rare or because we don't have an active champion on these
1855platforms--or both:
1856
1857 3b1
1858 AmigaOS
1859 ConvexOS
1860 CX/UX
1861 DC/OSx
1862 DDE SMES
1863 DOS EMX
1864 Dynix
1865 EP/IX
1866 ESIX
1867 FPS
1868 GENIX
1869 Greenhills
1870 ISC
1871 MachTen 68k
1872 MiNT
1873 MPC
1874 NEWS-OS
1875 Opus
1876 Plan 9
1877 PowerUX
1878 RISC/os
1879 Stellar
1880 SVR2
1881 TI1500
1882 TitanOS
1883 Unisys Dynix
1884 Unixware
1885
1886Support for the following platform is planned for a future Perl release:
1887
1888 Netware
1889
1890The following platforms have their own source code distributions and
1891binaries available via http://www.perl.com/CPAN/ports/index.html:
1892
1893 Perl release
1894
1895 AS/400 5.003
1896 Netware 5.003_07
1897 Tandem Guardian 5.004
1898
1899The following platforms have only binaries available via
1900http://www.perl.com/CPAN/ports/index.html:
1901
1902 Perl release
1903
1904 Acorn RISCOS 5.005_02
1905 AOS 5.002
1906 LynxOS 5.004_02
1907
1908Although we do suggest that you always build your own Perl from
1909the source code, both for maximal configurability and for security,
1910in case you are in a hurry you can check
1911http://www.perl.com/CPAN/ports/index.html for binary distributions.
1912
e41182b5
GS
1913=head1 AUTHORS / CONTRIBUTORS
1914
c47ff5f1
GS
1915Abigail <abigail@fnx.com>,
1916Charles Bailey <bailey@newman.upenn.edu>,
1917Graham Barr <gbarr@pobox.com>,
1918Tom Christiansen <tchrist@perl.com>,
1919Nicholas Clark <Nicholas.Clark@liverpool.ac.uk>,
1920Thomas Dorner <Thomas.Dorner@start.de>,
1921Andy Dougherty <doughera@lafcol.lafayette.edu>,
1922Dominic Dunlop <domo@vo.lu>,
1923Neale Ferguson <neale@mailbox.tabnsw.com.au>,
1924David J. Fiander <davidf@mks.com>,
1925Paul Green <Paul_Green@stratus.com>,
1926M.J.T. Guy <mjtg@cus.cam.ac.uk>,
1927Jarkko Hietaniemi <jhi@iki.fi<gt>,
1928Luther Huffman <lutherh@stratcom.com>,
1929Nick Ing-Simmons <nick@ni-s.u-net.com>,
1930Andreas J. KE<ouml>nig <koenig@kulturbox.de>,
1931Markus Laker <mlaker@contax.co.uk>,
1932Andrew M. Langmead <aml@world.std.com>,
1933Larry Moore <ljmoore@freespace.net>,
1934Paul Moore <Paul.Moore@uk.origin-it.com>,
1935Chris Nandor <pudge@pobox.com>,
1936Matthias Neeracher <neeri@iis.ee.ethz.ch>,
1937Gary Ng <71564.1743@CompuServe.COM>,
1938Tom Phoenix <rootbeer@teleport.com>,
1939AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
1940Peter Prymmer <pvhp@forte.com>,
1941Hugo van der Sanden <hv@crypt0.demon.co.uk>,
1942Gurusamy Sarathy <gsar@activestate.com>,
1943Paul J. Schinder <schinder@pobox.com>,
1944Michael G Schwern <schwern@pobox.com>,
1945Dan Sugalski <sugalskd@ous.edu>,
1946Nathan Torkington <gnat@frii.com>.
e41182b5 1947
3c075c7d 1948This document is maintained by Chris Nandor
c47ff5f1 1949<pudge@pobox.com>.
e41182b5
GS
1950
1951=head1 VERSION
1952
56d7751a 1953Version 1.46, last modified 12 February 2000