This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
various pod tweaks (from M.J.T. Guy <mjtg@cus.cam.ac.uk>)
[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
GS
77should be considered a perpetual work in progress
78(E<lt>IMG SRC="yellow_sign.gif" ALT="Under Construction"E<gt>).
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
93from) C<\015\012>, depending on whether your reading or writing.
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
JH
305
306Don't assume C<E<gt>> won't be the first character of a filename.
b7df3edc
GS
307Always use C<E<lt>> explicitly to open a file for reading,
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
314translate characters like C<E<gt>>, C<E<lt>>, 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
6ab3f9cb 531=item Testing results: C<http://www.perl.org/cpan-testers/>
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
GS
650 Windows NT MSWin32 MSWin32-ppc
651
652Also see:
653
654=over 4
655
656=item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>
657
658=item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>,
2ee0eb3c
CN
659C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html> or
660C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>
e41182b5
GS
661
662=item Build instructions for Win32, L<perlwin32>.
663
664=item The ActiveState Pages, C<http://www.activestate.com/>
665
873b149f
GS
666=item The Cygwin environment for Win32; L<README.cygwin>,
667C<http://sourceware.cygnus.com/cygwin/>
d1e3b762
GS
668
669=item The U/WIN environment for Win32,
670C<http://www.research.att.com/sw/tools/uwin/>
671
672
e41182b5
GS
673=back
674
dd9f0070 675=head2 S<Mac OS>
e41182b5
GS
676
677Any module requiring XS compilation is right out for most people, because
678MacPerl is built using non-free (and non-cheap!) compilers. Some XS
679modules that can work with MacPerl are built and distributed in binary
6ab3f9cb 680form on CPAN.
e41182b5
GS
681
682Directories are specified as:
683
684 volume:folder:file for absolute pathnames
685 volume:folder: for absolute pathnames
686 :folder:file for relative pathnames
687 :folder: for relative pathnames
688 :file for relative pathnames
689 file for relative pathnames
690
b7df3edc 691Files are stored in the directory in alphabetical order. Filenames are
6ab3f9cb 692limited to 31 characters, and may include any character except for
b7df3edc 693null and C<:>, which is reserved as the path separator.
e41182b5 694
0a47030a 695Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the
6ab3f9cb 696Mac::Files module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>.
e41182b5
GS
697
698In the MacPerl application, you can't run a program from the command line;
699programs that expect C<@ARGV> to be populated can be edited with something
700like the following, which brings up a dialog box asking for the command
701line arguments.
702
703 if (!@ARGV) {
704 @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
705 }
706
b7df3edc 707A MacPerl script saved as a "droplet" will populate C<@ARGV> with the full
e41182b5
GS
708pathnames of the files dropped onto the script.
709
b7df3edc
GS
710Mac users can run programs under a type of command line interface
711under MPW (Macintosh Programmer's Workshop, a free development
712environment from Apple). MacPerl was first introduced as an MPW
713tool, and MPW can be used like a shell:
e41182b5
GS
714
715 perl myscript.plx some arguments
716
717ToolServer is another app from Apple that provides access to MPW tools
0a47030a 718from MPW and the MacPerl app, which allows MacPerl programs to use
e41182b5
GS
719C<system>, backticks, and piped C<open>.
720
721"S<Mac OS>" is the proper name for the operating system, but the value
722in C<$^O> is "MacOS". To determine architecture, version, or whether
723the application or MPW tool version is running, check:
724
725 $is_app = $MacPerl::Version =~ /App/;
726 $is_tool = $MacPerl::Version =~ /MPW/;
727 ($version) = $MacPerl::Version =~ /^(\S+)/;
728 $is_ppc = $MacPerl::Architecture eq 'MacPPC';
729 $is_68k = $MacPerl::Architecture eq 'Mac68K';
730
6ab3f9cb
GS
731S<Mac OS X> and S<Mac OS X Server>, based on NeXT's OpenStep OS, will
732(in theory) be able to run MacPerl natively, under the "Classic"
733environment. The new "Cocoa" environment (formerly called the "Yellow Box")
734may run a slightly modified version of MacPerl, using the Carbon interfaces.
735
736S<Mac OS X Server> and its Open Source version, Darwin, both run Unix
b7df3edc 737perl natively (with a few patches). Full support for these
87275199 738is slated for perl 5.6.
6ab3f9cb 739
e41182b5
GS
740Also see:
741
742=over 4
743
6ab3f9cb 744=item The MacPerl Pages, C<http://www.macperl.com/>.
e41182b5 745
6ab3f9cb
GS
746=item The MacPerl mailing lists, C<http://www.macperl.org/>.
747
748=item MacPerl Module Porters, C<http://pudge.net/mmp/>.
e41182b5
GS
749
750=back
751
e41182b5
GS
752=head2 VMS
753
754Perl on VMS is discussed in F<vms/perlvms.pod> in the perl distribution.
b7df3edc 755Perl on VMS can accept either VMS- or Unix-style file
e41182b5
GS
756specifications as in either of the following:
757
758 $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
759 $ perl -ne "print if /perl_setup/i" /sys$login/login.com
760
761but not a mixture of both as in:
762
763 $ perl -ne "print if /perl_setup/i" sys$login:/login.com
764 Can't open sys$login:/login.com: file specification syntax error
765
766Interacting with Perl from the Digital Command Language (DCL) shell
767often requires a different set of quotation marks than Unix shells do.
768For example:
769
770 $ perl -e "print ""Hello, world.\n"""
771 Hello, world.
772
b7df3edc 773There are several ways to wrap your perl scripts in DCL F<.COM> files, if
e41182b5
GS
774you are so inclined. For example:
775
776 $ write sys$output "Hello from DCL!"
777 $ if p1 .eqs. ""
778 $ then perl -x 'f$environment("PROCEDURE")
779 $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
780 $ deck/dollars="__END__"
781 #!/usr/bin/perl
782
783 print "Hello from Perl!\n";
784
785 __END__
786 $ endif
787
788Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
789perl-in-DCL script expects to do things like C<$read = E<lt>STDINE<gt>;>.
790
791Filenames are in the format "name.extension;version". The maximum
792length for filenames is 39 characters, and the maximum length for
793extensions is also 39 characters. Version is a number from 1 to
79432767. Valid characters are C</[A-Z0-9$_-]/>.
795
b7df3edc 796VMS's RMS filesystem is case-insensitive and does not preserve case.
e41182b5 797C<readdir> returns lowercased filenames, but specifying a file for
b7df3edc 798opening remains case-insensitive. Files without extensions have a
e41182b5 799trailing period on them, so doing a C<readdir> with a file named F<A.;5>
0a47030a
GS
800will return F<a.> (though that file could be opened with
801C<open(FH, 'A')>).
e41182b5 802
f34d0673 803RMS had an eight level limit on directory depths from any rooted logical
dd9f0070
CN
804(allowing 16 levels overall) prior to VMS 7.2. Hence
805C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a valid directory specification but
806C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is not. F<Makefile.PL> authors might
807have to take this into account, but at least they can refer to the former
f34d0673 808as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
e41182b5 809
6ab3f9cb 810The VMS::Filespec module, which gets installed as part of the build
0a47030a
GS
811process on VMS, is a pure Perl module that can easily be installed on
812non-VMS platforms and can be helpful for conversions to and from RMS
813native formats.
e41182b5 814
b7df3edc 815What C<\n> represents depends on the type of file opened. It could
d1e3b762
GS
816be C<\015>, C<\012>, C<\015\012>, or nothing. The VMS::Stdio module
817provides access to the special fopen() requirements of files with unusual
818attributes on VMS.
e41182b5
GS
819
820TCP/IP stacks are optional on VMS, so socket routines might not be
821implemented. UDP sockets may not be supported.
822
823The value of C<$^O> on OpenVMS is "VMS". To determine the architecture
824that you are running on without resorting to loading all of C<%Config>
825you can examine the content of the C<@INC> array like so:
826
827 if (grep(/VMS_AXP/, @INC)) {
828 print "I'm on Alpha!\n";
6ab3f9cb 829
e41182b5
GS
830 } elsif (grep(/VMS_VAX/, @INC)) {
831 print "I'm on VAX!\n";
6ab3f9cb 832
e41182b5
GS
833 } else {
834 print "I'm not so sure about where $^O is...\n";
835 }
836
b7df3edc
GS
837On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
838logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
6ab3f9cb 839calls to C<localtime> are adjusted to count offsets from
b7df3edc 84001-JAN-1970 00:00:00.00, just like Unix.
6ab3f9cb 841
e41182b5
GS
842Also see:
843
844=over 4
845
d1e3b762 846=item L<README.vms>, L<perlvms.pod>
e41182b5 847
6ab3f9cb 848=item vmsperl list, C<majordomo@perl.org>
e41182b5 849
6ab3f9cb 850Put the words C<subscribe vmsperl> in message body.
e41182b5
GS
851
852=item vmsperl on the web, C<http://www.sidhe.org/vmsperl/index.html>
853
854=back
855
495c5fdc
GP
856=head2 VOS
857
858Perl on VOS is discussed in F<README.vos> in the perl distribution.
b7df3edc 859Perl on VOS can accept either VOS- or Unix-style file
495c5fdc
GP
860specifications as in either of the following:
861
862 $ perl -ne "print if /perl_setup/i" >system>notices
863 $ perl -ne "print if /perl_setup/i" /system/notices
864
865or even a mixture of both as in:
866
867 $ perl -ne "print if /perl_setup/i" >system/notices
868
b7df3edc 869Even though VOS allows the slash character to appear in object
495c5fdc
GP
870names, because the VOS port of Perl interprets it as a pathname
871delimiting character, VOS files, directories, or links whose names
872contain a slash character cannot be processed. Such files must be
873renamed before they can be processed by Perl.
874
2ee0eb3c 875The following C functions are unimplemented on VOS, and any attempt by
495c5fdc 876Perl to use them will result in a fatal error message and an immediate
2ee0eb3c
CN
877exit from Perl: dup, do_aspawn, do_spawn, fork, waitpid. Once these
878functions become available in the VOS POSIX.1 implementation, you can
879either recompile and rebind Perl, or you can download a newer port from
880ftp.stratus.com.
495c5fdc
GP
881
882The value of C<$^O> on VOS is "VOS". To determine the architecture that
883you are running on without resorting to loading all of C<%Config> you
884can examine the content of the C<@INC> array like so:
885
886 if (grep(/VOS/, @INC)) {
887 print "I'm on a Stratus box!\n";
888 } else {
889 print "I'm not on a Stratus box!\n";
890 die;
891 }
892
893 if (grep(/860/, @INC)) {
894 print "This box is a Stratus XA/R!\n";
6ab3f9cb 895
495c5fdc
GP
896 } elsif (grep(/7100/, @INC)) {
897 print "This box is a Stratus HP 7100 or 8000!\n";
6ab3f9cb 898
495c5fdc
GP
899 } elsif (grep(/8000/, @INC)) {
900 print "This box is a Stratus HP 8000!\n";
6ab3f9cb 901
495c5fdc
GP
902 } else {
903 print "This box is a Stratus 68K...\n";
904 }
905
906Also see:
907
908=over 4
909
910=item L<README.vos>
911
912=item VOS mailing list
913
914There is no specific mailing list for Perl on VOS. You can post
915comments to the comp.sys.stratus newsgroup, or subscribe to the general
916Stratus mailing list. Send a letter with "Subscribe Info-Stratus" in
917the message body to majordomo@list.stratagy.com.
918
919=item VOS Perl on the web at C<http://ftp.stratus.com/pub/vos/vos.html>
920
921=back
922
e41182b5
GS
923=head2 EBCDIC Platforms
924
925Recent versions of Perl have been ported to platforms such as OS/400 on
d1e3b762
GS
926AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
927Mainframes. Such computers use EBCDIC character sets internally (usually
928Character Code Set ID 00819 for OS/400 and 1047 for S/390 systems).
929On the mainframe perl currently works under the "Unix system services
930for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
931the BS200 POSIX system (BS2000 is supported in perl 5.006 and greater).
e41182b5 932
7c5ffed3
JH
933As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
934sub-systems do not support the C<#!> shebang trick for script invocation.
935Hence, on OS/390 and VM/ESA perl scripts can be executed with a header
936similar to the following simple script:
e41182b5
GS
937
938 : # use perl
939 eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
940 if 0;
941 #!/usr/local/bin/perl # just a comment really
942
943 print "Hello from perl!\n";
944
d1e3b762
GS
945OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
946Calls to C<system> and backticks can use POSIX shell syntax on all
947S/390 systems.
948
b7df3edc 949On the AS/400, if PERL5 is in your library list, you may need
6ab3f9cb
GS
950to wrap your perl scripts in a CL procedure to invoke them like so:
951
952 BEGIN
953 CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
954 ENDPGM
955
956This will invoke the perl script F<hello.pl> in the root of the
957QOpenSys file system. On the AS/400 calls to C<system> or backticks
958must use CL syntax.
959
e41182b5 960On these platforms, bear in mind that the EBCDIC character set may have
0a47030a
GS
961an effect on what happens with some perl functions (such as C<chr>,
962C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
963well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
964and C<|>, not to mention dealing with socket interfaces to ASCII computers
6ab3f9cb 965(see L<"Newlines">).
e41182b5 966
b7df3edc
GS
967Fortunately, most web servers for the mainframe will correctly
968translate the C<\n> in the following statement to its ASCII equivalent
969(C<\r> is the same under both Unix and OS/390 & VM/ESA):
e41182b5
GS
970
971 print "Content-type: text/html\r\n\r\n";
972
d1e3b762 973The values of C<$^O> on some of these platforms includes:
e41182b5 974
d1e3b762
GS
975 uname $^O $Config{'archname'}
976 --------------------------------------------
977 OS/390 os390 os390
978 OS400 os400 os400
979 POSIX-BC posix-bc BS2000-posix-bc
980 VM/ESA vmesa vmesa
3c075c7d 981
e41182b5
GS
982Some simple tricks for determining if you are running on an EBCDIC
983platform could include any of the following (perhaps all):
984
985 if ("\t" eq "\05") { print "EBCDIC may be spoken here!\n"; }
986
987 if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
988
989 if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
990
b7df3edc 991One thing you may not want to rely on is the EBCDIC encoding
0a47030a
GS
992of punctuation characters since these may differ from code page to code
993page (and once your module or script is rumoured to work with EBCDIC,
994folks will want it to work with all EBCDIC character sets).
e41182b5
GS
995
996Also see:
997
998=over 4
999
d1e3b762
GS
1000=item L<README.os390>, L<README.posix-bc>, L<README.vmesa>
1001
e41182b5
GS
1002=item perl-mvs list
1003
1004The perl-mvs@perl.org list is for discussion of porting issues as well as
1005general usage issues for all EBCDIC Perls. Send a message body of
1006"subscribe perl-mvs" to majordomo@perl.org.
1007
0a47030a 1008=item AS/400 Perl information at C<http://as400.rochester.ibm.com/>
d1e3b762 1009as well as on CPAN in the F<ports/> directory.
e41182b5
GS
1010
1011=back
1012
b8099c3d
CN
1013=head2 Acorn RISC OS
1014
b7df3edc
GS
1015Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
1016Unix, and because Unix filename emulation is turned on by default,
1017most simple scripts will probably work "out of the box". The native
6ab3f9cb 1018filesystem is modular, and individual filesystems are free to be
0a47030a 1019case-sensitive or insensitive, and are usually case-preserving. Some
b7df3edc 1020native filesystems have name length limits, which file and directory
6ab3f9cb
GS
1021names are silently truncated to fit. Scripts should be aware that the
1022standard filesystem currently has a name length limit of B<10>
1023characters, with up to 77 items in a directory, but other filesystems
0a47030a 1024may not impose such limitations.
b8099c3d
CN
1025
1026Native filenames are of the form
1027
6ab3f9cb 1028 Filesystem#Special_Field::DiskName.$.Directory.Directory.File
dd9f0070 1029
b8099c3d
CN
1030where
1031
1032 Special_Field is not usually present, but may contain . and $ .
1033 Filesystem =~ m|[A-Za-z0-9_]|
1034 DsicName =~ m|[A-Za-z0-9_/]|
1035 $ represents the root directory
1036 . is the path separator
1037 @ is the current directory (per filesystem but machine global)
1038 ^ is the parent directory
1039 Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1040
1041The default filename translation is roughly C<tr|/.|./|;>
1042
6ab3f9cb 1043Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
0a47030a
GS
1044the second stage of C<$> interpolation in regular expressions will fall
1045foul of the C<$.> if scripts are not careful.
1046
1047Logical paths specified by system variables containing comma-separated
b7df3edc 1048search lists are also allowed; hence C<System:Modules> is a valid
0a47030a 1049filename, and the filesystem will prefix C<Modules> with each section of
6ab3f9cb 1050C<System$Path> until a name is made that points to an object on disk.
b7df3edc 1051Writing to a new file C<System:Modules> would be allowed only if
0a47030a
GS
1052C<System$Path> contains a single item list. The filesystem will also
1053expand system variables in filenames if enclosed in angle brackets, so
1054C<E<lt>System$DirE<gt>.Modules> would look for the file
1055S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is
3c075c7d 1056that B<fully qualified filenames can start with C<E<lt>E<gt>>> and should
0a47030a 1057be protected when C<open> is used for input.
b8099c3d
CN
1058
1059Because C<.> was in use as a directory separator and filenames could not
1060be assumed to be unique after 10 characters, Acorn implemented the C
1061compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
1062filenames specified in source code and store the respective files in
b7df3edc 1063subdirectories named after the suffix. Hence files are translated:
b8099c3d
CN
1064
1065 foo.h h.foo
1066 C:foo.h C:h.foo (logical path variable)
1067 sys/os.h sys.h.os (C compiler groks Unix-speak)
1068 10charname.c c.10charname
1069 10charname.o o.10charname
1070 11charname_.c c.11charname (assuming filesystem truncates at 10)
1071
1072The Unix emulation library's translation of filenames to native assumes
b7df3edc
GS
1073that this sort of translation is required, and it allows a user-defined list
1074of known suffixes that it will transpose in this fashion. This may
1075seem transparent, but consider that with these rules C<foo/bar/baz.h>
0a47030a
GS
1076and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
1077C<glob> cannot and do not attempt to emulate the reverse mapping. Other
6ab3f9cb 1078C<.>'s in filenames are translated to C</>.
0a47030a 1079
b7df3edc 1080As implied above, the environment accessed through C<%ENV> is global, and
0a47030a 1081the convention is that program specific environment variables are of the
6ab3f9cb
GS
1082form C<Program$Name>. Each filesystem maintains a current directory,
1083and the current filesystem's current directory is the B<global> current
b7df3edc
GS
1084directory. Consequently, sociable programs don't change the current
1085directory but rely on full pathnames, and programs (and Makefiles) cannot
0a47030a
GS
1086assume that they can spawn a child process which can change the current
1087directory without affecting its parent (and everyone else for that
1088matter).
1089
b7df3edc
GS
1090Because native operating system filehandles are global and are currently
1091allocated down from 255, with 0 being a reserved value, the Unix emulation
0a47030a
GS
1092library emulates Unix filehandles. Consequently, you can't rely on
1093passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
1094
1095The desire of users to express filenames of the form
1096C<E<lt>Foo$DirE<gt>.Bar> on the command line unquoted causes problems,
1097too: C<``> command output capture has to perform a guessing game. It
1098assumes that a string C<E<lt>[^E<lt>E<gt>]+\$[^E<lt>E<gt>]E<gt>> is a
1099reference to an environment variable, whereas anything else involving
1100C<E<lt>> or C<E<gt>> is redirection, and generally manages to be 99%
1101right. Of course, the problem remains that scripts cannot rely on any
1102Unix tools being available, or that any tools found have Unix-like command
1103line arguments.
1104
b7df3edc
GS
1105Extensions and XS are, in theory, buildable by anyone using free
1106tools. In practice, many don't, as users of the Acorn platform are
1107used to binary distributions. MakeMaker does run, but no available
1108make currently copes with MakeMaker's makefiles; even if and when
1109this should be fixed, the lack of a Unix-like shell will cause
1110problems with makefile rules, especially lines of the form C<cd
1111sdbm && make all>, and anything using quoting.
b8099c3d
CN
1112
1113"S<RISC OS>" is the proper name for the operating system, but the value
1114in C<$^O> is "riscos" (because we don't like shouting).
1115
e41182b5
GS
1116=head2 Other perls
1117
b7df3edc
GS
1118Perl has been ported to many platforms that do not fit into any of
1119the categories listed above. Some, such as AmigaOS, Atari MiNT,
1120BeOS, HP MPE/iX, QNX, Plan 9, and VOS, have been well-integrated
1121into the standard Perl source code kit. You may need to see the
1122F<ports/> directory on CPAN for information, and possibly binaries,
1123for the likes of: aos, Atari ST, lynxos, riscos, Novell Netware,
1124Tandem Guardian, I<etc.> (Yes, we know that some of these OSes may
1125fall under the Unix category, but we are not a standards body.)
e41182b5 1126
d1e3b762
GS
1127Some approximate operating system names and their C<$^O> values
1128in the "OTHER" category include:
1129
1130 OS $^O $Config{'archname'}
1131 ------------------------------------------
1132 Amiga DOS amigaos m68k-amigos
1133 MPE/iX mpeix PA-RISC1.1
1134
e41182b5
GS
1135See also:
1136
1137=over 4
1138
d1e3b762
GS
1139=item Amiga, L<README.amiga>
1140
1141=item Atari, L<README.mint> and Guido Flohr's web page
1142C<http://stud.uni-sb.de/~gufl0000/>
e41182b5 1143
d1e3b762
GS
1144=item Be OS, L<README.beos>
1145
1146=item HP 300 MPE/iX, L<README.mpeix> and Mark Bixby's web page
1147C<http://www.cccd.edu/~markb/perlix.html>
e41182b5
GS
1148
1149=item Novell Netware
1150
6ab3f9cb
GS
1151A free perl5-based PERL.NLM for Novell Netware is available in
1152precompiled binary and source code form from C<http://www.novell.com/>
1153as well as from CPAN.
e41182b5 1154
d1e3b762
GS
1155=item Plan 9, L<README.plan9>
1156
e41182b5
GS
1157=back
1158
e41182b5
GS
1159=head1 FUNCTION IMPLEMENTATIONS
1160
b7df3edc
GS
1161Listed below are functions that are either completely unimplemented
1162or else have been implemented differently on various platforms.
1163Following each description will be, in parentheses, a list of
1164platforms that the description applies to.
e41182b5 1165
b7df3edc
GS
1166The list may well be incomplete, or even wrong in some places. When
1167in doubt, consult the platform-specific README files in the Perl
1168source distribution, and any other documentation resources accompanying
1169a given port.
e41182b5 1170
0a47030a 1171Be aware, moreover, that even among Unix-ish systems there are variations.
e41182b5 1172
b7df3edc
GS
1173For many functions, you can also query C<%Config>, exported by
1174default from the Config module. For example, to check whether the
1175platform has the C<lstat> call, check C<$Config{d_lstat}>. See
1176L<Config> for a full description of available variables.
e41182b5
GS
1177
1178=head2 Alphabetical Listing of Perl Functions
1179
1180=over 8
1181
1182=item -X FILEHANDLE
1183
1184=item -X EXPR
1185
1186=item -X
1187
b7df3edc 1188C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
e41182b5 1189and applications are executable, and there are no uid/gid
b7df3edc 1190considerations. C<-o> is not supported. (S<Mac OS>)
e41182b5 1191
b7df3edc
GS
1192C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
1193which may not reflect UIC-based file protections. (VMS)
e41182b5 1194
b8099c3d
CN
1195C<-s> returns the size of the data fork, not the total size of data fork
1196plus resource fork. (S<Mac OS>).
1197
1198C<-s> by name on an open file will return the space reserved on disk,
1199rather than the current extent. C<-s> on an open filehandle returns the
b7df3edc 1200current size. (S<RISC OS>)
b8099c3d 1201
e41182b5 1202C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
b8099c3d 1203C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1204
1205C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
1206(S<Mac OS>)
1207
1208C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
b8099c3d 1209(Win32, VMS, S<RISC OS>)
e41182b5
GS
1210
1211C<-d> is true if passed a device spec without an explicit directory.
1212(VMS)
1213
1214C<-T> and C<-B> are implemented, but might misclassify Mac text files
0a47030a 1215with foreign characters; this is the case will all platforms, but may
b7df3edc 1216affect S<Mac OS> often. (S<Mac OS>)
e41182b5
GS
1217
1218C<-x> (or C<-X>) determine if a file ends in one of the executable
b7df3edc 1219suffixes. C<-S> is meaningless. (Win32)
e41182b5 1220
b8099c3d
CN
1221C<-x> (or C<-X>) determine if a file has an executable file type.
1222(S<RISC OS>)
1223
e41182b5
GS
1224=item binmode FILEHANDLE
1225
b7df3edc 1226Meaningless. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1227
1228Reopens file and restores pointer; if function fails, underlying
1229filehandle may be closed, or pointer may be in a different position.
1230(VMS)
1231
1232The value returned by C<tell> may be affected after the call, and
1233the filehandle may be flushed. (Win32)
1234
1235=item chmod LIST
1236
b7df3edc 1237Only limited meaning. Disabling/enabling write permission is mapped to
e41182b5
GS
1238locking/unlocking the file. (S<Mac OS>)
1239
1240Only good for changing "owner" read-write access, "group", and "other"
1241bits are meaningless. (Win32)
1242
b8099c3d
CN
1243Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1244
495c5fdc
GP
1245Access permissions are mapped onto VOS access-control list changes. (VOS)
1246
e41182b5
GS
1247=item chown LIST
1248
495c5fdc 1249Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1250
1251Does nothing, but won't fail. (Win32)
1252
1253=item chroot FILENAME
1254
1255=item chroot
1256
7c5ffed3 1257Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1258
1259=item crypt PLAINTEXT,SALT
1260
1261May not be available if library or source was not provided when building
b8099c3d 1262perl. (Win32)
e41182b5 1263
495c5fdc
GP
1264Not implemented. (VOS)
1265
e41182b5
GS
1266=item dbmclose HASH
1267
495c5fdc 1268Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1269
1270=item dbmopen HASH,DBNAME,MODE
1271
495c5fdc 1272Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1273
1274=item dump LABEL
1275
b8099c3d 1276Not useful. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1277
1278Not implemented. (Win32)
1279
b8099c3d 1280Invokes VMS debugger. (VMS)
e41182b5
GS
1281
1282=item exec LIST
1283
1284Not implemented. (S<Mac OS>)
1285
7c5ffed3 1286Implemented via Spawn. (VM/ESA)
3c075c7d 1287
e41182b5
GS
1288=item fcntl FILEHANDLE,FUNCTION,SCALAR
1289
1290Not implemented. (Win32, VMS)
1291
1292=item flock FILEHANDLE,OPERATION
1293
495c5fdc 1294Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
e41182b5
GS
1295
1296Available only on Windows NT (not on Windows 95). (Win32)
1297
1298=item fork
1299
7c5ffed3 1300Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1301
1302=item getlogin
1303
b8099c3d 1304Not implemented. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1305
1306=item getpgrp PID
1307
495c5fdc 1308Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1309
1310=item getppid
1311
b8099c3d 1312Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1313
1314=item getpriority WHICH,WHO
1315
7c5ffed3 1316Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1317
1318=item getpwnam NAME
1319
1320Not implemented. (S<Mac OS>, Win32)
1321
b8099c3d
CN
1322Not useful. (S<RISC OS>)
1323
e41182b5
GS
1324=item getgrnam NAME
1325
b8099c3d 1326Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1327
1328=item getnetbyname NAME
1329
1330Not implemented. (S<Mac OS>, Win32, Plan9)
1331
1332=item getpwuid UID
1333
1334Not implemented. (S<Mac OS>, Win32)
1335
b8099c3d
CN
1336Not useful. (S<RISC OS>)
1337
e41182b5
GS
1338=item getgrgid GID
1339
b8099c3d 1340Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1341
1342=item getnetbyaddr ADDR,ADDRTYPE
1343
1344Not implemented. (S<Mac OS>, Win32, Plan9)
1345
1346=item getprotobynumber NUMBER
1347
1348Not implemented. (S<Mac OS>)
1349
1350=item getservbyport PORT,PROTO
1351
1352Not implemented. (S<Mac OS>)
1353
1354=item getpwent
1355
7c5ffed3 1356Not implemented. (S<Mac OS>, Win32, VM/ESA)
e41182b5
GS
1357
1358=item getgrent
1359
7c5ffed3 1360Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
e41182b5
GS
1361
1362=item gethostent
1363
1364Not implemented. (S<Mac OS>, Win32)
1365
1366=item getnetent
1367
1368Not implemented. (S<Mac OS>, Win32, Plan9)
1369
1370=item getprotoent
1371
1372Not implemented. (S<Mac OS>, Win32, Plan9)
1373
1374=item getservent
1375
1376Not implemented. (Win32, Plan9)
1377
1378=item setpwent
1379
b8099c3d 1380Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1381
1382=item setgrent
1383
b8099c3d 1384Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1385
1386=item sethostent STAYOPEN
1387
b8099c3d 1388Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1389
1390=item setnetent STAYOPEN
1391
b8099c3d 1392Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1393
1394=item setprotoent STAYOPEN
1395
b8099c3d 1396Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1397
1398=item setservent STAYOPEN
1399
b8099c3d 1400Not implemented. (Plan9, Win32, S<RISC OS>)
e41182b5
GS
1401
1402=item endpwent
1403
7c5ffed3 1404Not implemented. (S<Mac OS>, Win32, VM/ESA)
e41182b5
GS
1405
1406=item endgrent
1407
7c5ffed3 1408Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VM/ESA)
e41182b5
GS
1409
1410=item endhostent
1411
1412Not implemented. (S<Mac OS>, Win32)
1413
1414=item endnetent
1415
1416Not implemented. (S<Mac OS>, Win32, Plan9)
1417
1418=item endprotoent
1419
1420Not implemented. (S<Mac OS>, Win32, Plan9)
1421
1422=item endservent
1423
1424Not implemented. (Plan9, Win32)
1425
1426=item getsockopt SOCKET,LEVEL,OPTNAME
1427
1428Not implemented. (S<Mac OS>, Plan9)
1429
1430=item glob EXPR
1431
1432=item glob
1433
1434Globbing built-in, but only C<*> and C<?> metacharacters are supported.
1435(S<Mac OS>)
1436
b7df3edc 1437Features depend on external perlglob.exe or perlglob.bat. May be
0a47030a
GS
1438overridden with something like File::DosGlob, which is recommended.
1439(Win32)
e41182b5 1440
b8099c3d 1441Globbing built-in, but only C<*> and C<?> metacharacters are supported.
0a47030a
GS
1442Globbing relies on operating system calls, which may return filenames
1443in any order. As most filesystems are case-insensitive, even "sorted"
1444filenames will not be in case-sensitive order. (S<RISC OS>)
b8099c3d 1445
e41182b5
GS
1446=item ioctl FILEHANDLE,FUNCTION,SCALAR
1447
1448Not implemented. (VMS)
1449
1450Available only for socket handles, and it does what the ioctlsocket() call
1451in the Winsock API does. (Win32)
1452
b8099c3d
CN
1453Available only for socket handles. (S<RISC OS>)
1454
b350dd2f 1455=item kill SIGNAL, LIST
e41182b5 1456
0a47030a
GS
1457Not implemented, hence not useful for taint checking. (S<Mac OS>,
1458S<RISC OS>)
e41182b5 1459
b350dd2f
GS
1460Unlike Unix platforms, C<kill(0, $pid)> will actually terminate
1461the process. (Win32)
e41182b5
GS
1462
1463=item link OLDFILE,NEWFILE
1464
b8099c3d 1465Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5 1466
433acd8a
JH
1467Link count not updated because hard links are not quite that hard
1468(They are sort of half-way between hard and soft links). (AmigaOS)
1469
e41182b5
GS
1470=item lstat FILEHANDLE
1471
1472=item lstat EXPR
1473
1474=item lstat
1475
b8099c3d 1476Not implemented. (VMS, S<RISC OS>)
e41182b5 1477
b8099c3d 1478Return values may be bogus. (Win32)
e41182b5
GS
1479
1480=item msgctl ID,CMD,ARG
1481
1482=item msgget KEY,FLAGS
1483
1484=item msgsnd ID,MSG,FLAGS
1485
1486=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1487
495c5fdc 1488Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1489
1490=item open FILEHANDLE,EXPR
1491
1492=item open FILEHANDLE
1493
b7df3edc 1494The C<|> variants are supported only if ToolServer is installed.
e41182b5
GS
1495(S<Mac OS>)
1496
b8099c3d 1497open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1498
1499=item pipe READHANDLE,WRITEHANDLE
1500
1501Not implemented. (S<Mac OS>)
1502
433acd8a
JH
1503Very limited functionality. (MiNT)
1504
e41182b5
GS
1505=item readlink EXPR
1506
1507=item readlink
1508
b8099c3d 1509Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1510
1511=item select RBITS,WBITS,EBITS,TIMEOUT
1512
1513Only implemented on sockets. (Win32)
1514
b8099c3d
CN
1515Only reliable on sockets. (S<RISC OS>)
1516
e41182b5
GS
1517=item semctl ID,SEMNUM,CMD,ARG
1518
1519=item semget KEY,NSEMS,FLAGS
1520
1521=item semop KEY,OPSTRING
1522
495c5fdc 1523Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1524
1525=item setpgrp PID,PGRP
1526
495c5fdc 1527Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1528
1529=item setpriority WHICH,WHO,PRIORITY
1530
495c5fdc 1531Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1532
1533=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1534
1535Not implemented. (S<Mac OS>, Plan9)
1536
1537=item shmctl ID,CMD,ARG
1538
1539=item shmget KEY,SIZE,FLAGS
1540
1541=item shmread ID,VAR,POS,SIZE
1542
1543=item shmwrite ID,STRING,POS,SIZE
1544
495c5fdc 1545Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1546
1547=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1548
7c5ffed3 1549Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1550
1551=item stat FILEHANDLE
1552
1553=item stat EXPR
1554
1555=item stat
1556
1557mtime and atime are the same thing, and ctime is creation time instead of
1558inode change time. (S<Mac OS>)
1559
1560device and inode are not meaningful. (Win32)
1561
1562device and inode are not necessarily reliable. (VMS)
1563
b8099c3d
CN
1564mtime, atime and ctime all return the last modification time. Device and
1565inode are not necessarily reliable. (S<RISC OS>)
1566
e41182b5
GS
1567=item symlink OLDFILE,NEWFILE
1568
b8099c3d 1569Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1570
1571=item syscall LIST
1572
7c5ffed3 1573Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5 1574
f34d0673
GS
1575=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1576
dd9f0070 1577The traditional "0", "1", and "2" MODEs are implemented with different
322422de
GS
1578numeric values on some systems. The flags exported by C<Fcntl>
1579(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
7c5ffed3 1580OS>, OS/390, VM/ESA)
f34d0673 1581
e41182b5
GS
1582=item system LIST
1583
1584Only implemented if ToolServer is installed. (S<Mac OS>)
1585
1586As an optimization, may not call the command shell specified in
b7df3edc 1587C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
e41182b5
GS
1588process and immediately returns its process designator, without
1589waiting for it to terminate. Return value may be used subsequently
1590in C<wait> or C<waitpid>. (Win32)
1591
b8099c3d
CN
1592There is no shell to process metacharacters, and the native standard is
1593to pass a command line terminated by "\n" "\r" or "\0" to the spawned
1594program. Redirection such as C<E<gt> foo> is performed (if at all) by
1595the run time library of the spawned program. C<system> I<list> will call
1596the Unix emulation library's C<exec> emulation, which attempts to provide
1597emulation of the stdin, stdout, stderr in force in the parent, providing
1598the child program uses a compatible version of the emulation library.
1599I<scalar> will call the native command line direct and no such emulation
1600of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
1601
433acd8a
JH
1602Far from being POSIX compliant. Because there may be no underlying
1603/bin/sh tries to work around the problem by forking and execing the
9b63e9ec
CN
1604first token in its argument string. Handles basic redirection
1605("E<lt>" or "E<gt>") on its own behalf. (MiNT)
433acd8a 1606
e41182b5
GS
1607=item times
1608
1609Only the first entry returned is nonzero. (S<Mac OS>)
1610
1611"cumulative" times will be bogus. On anything other than Windows NT,
1612"system" time will be bogus, and "user" time is actually the time
1613returned by the clock() function in the C runtime library. (Win32)
1614
b8099c3d
CN
1615Not useful. (S<RISC OS>)
1616
e41182b5
GS
1617=item truncate FILEHANDLE,LENGTH
1618
1619=item truncate EXPR,LENGTH
1620
1621Not implemented. (VMS)
1622
495c5fdc
GP
1623Truncation to zero-length only. (VOS)
1624
4cfdb94f
GS
1625If a FILEHANDLE is supplied, it must be writable and opened in append
1626mode (i.e., use C<open(FH, '>>filename')>
1627or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
1628should not be held open elsewhere. (Win32)
1629
e41182b5
GS
1630=item umask EXPR
1631
1632=item umask
1633
1634Returns undef where unavailable, as of version 5.005.
1635
b7df3edc
GS
1636C<umask> works but the correct permissions are set only when the file
1637is finally closed. (AmigaOS)
433acd8a 1638
e41182b5
GS
1639=item utime LIST
1640
b8099c3d 1641Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
e41182b5 1642
322422de
GS
1643May not behave as expected. Behavior depends on the C runtime
1644library's implementation of utime(), and the filesystem being
1645used. The FAT filesystem typically does not support an "access
1646time" field, and it may limit timestamps to a granularity of
1647two seconds. (Win32)
e41182b5
GS
1648
1649=item wait
1650
1651=item waitpid PID,FLAGS
1652
495c5fdc 1653Not implemented. (S<Mac OS>, VOS)
e41182b5
GS
1654
1655Can only be applied to process handles returned for processes spawned
1656using C<system(1, ...)>. (Win32)
1657
b8099c3d
CN
1658Not useful. (S<RISC OS>)
1659
e41182b5
GS
1660=back
1661
b8099c3d
CN
1662=head1 CHANGES
1663
1664=over 4
1665
d1e3b762
GS
1666=item v1.44, 19 July 1999
1667
1668A bunch of updates from Peter Prymmer for C<$^O> values,
1669endianness, File::Spec, VMS, BS2000, OS/400.
1670
b7df3edc
GS
1671=item v1.43, 24 May 1999
1672
1673Added a lot of cleaning up from Tom Christiansen.
1674
19799a22 1675=item v1.42, 22 May 1999
b7df3edc 1676
19799a22 1677Added notes about tests, sprintf/printf, and epoch offsets.
b7df3edc 1678
6ab3f9cb
GS
1679=item v1.41, 19 May 1999
1680
1681Lots more little changes to formatting and content.
1682
d1e3b762 1683Added a bunch of C<$^O> and related values
6ab3f9cb
GS
1684for various platforms; fixed mail and web addresses, and added
1685and changed miscellaneous notes. (Peter Prymmer)
1686
1687=item v1.40, 11 April 1999
1688
1689Miscellaneous changes.
1690
1691=item v1.39, 11 February 1999
2ee0eb3c
CN
1692
1693Changes from Jarkko and EMX URL fixes Michael Schwern. Additional
1694note about newlines added.
1695
9b63e9ec
CN
1696=item v1.38, 31 December 1998
1697
1698More changes from Jarkko.
1699
3c075c7d
CN
1700=item v1.37, 19 December 1998
1701
1702More minor changes. Merge two separate version 1.35 documents.
1703
1704=item v1.36, 9 September 1998
1705
1706Updated for Stratus VOS. Also known as version 1.35.
1707
1708=item v1.35, 13 August 1998
495c5fdc 1709
3c075c7d
CN
1710Integrate more minor changes, plus addition of new sections under
1711L<"ISSUES">: L<"Numbers endianness and Width">,
1712L<"Character sets and character encoding">,
1713L<"Internationalisation">.
495c5fdc 1714
3c075c7d 1715=item v1.33, 06 August 1998
0a47030a
GS
1716
1717Integrate more minor changes.
1718
3c075c7d 1719=item v1.32, 05 August 1998
dd9f0070
CN
1720
1721Integrate more minor changes.
1722
3c075c7d 1723=item v1.30, 03 August 1998
b8099c3d
CN
1724
1725Major update for RISC OS, other minor changes.
1726
3c075c7d 1727=item v1.23, 10 July 1998
b8099c3d
CN
1728
1729First public release with perl5.005.
1730
1731=back
e41182b5
GS
1732
1733=head1 AUTHORS / CONTRIBUTORS
1734
dd9f0070 1735Abigail E<lt>abigail@fnx.comE<gt>,
bd3fa61c 1736Charles Bailey E<lt>bailey@newman.upenn.eduE<gt>,
dd9f0070 1737Graham Barr E<lt>gbarr@pobox.comE<gt>,
e41182b5 1738Tom Christiansen E<lt>tchrist@perl.comE<gt>,
dd9f0070 1739Nicholas Clark E<lt>Nicholas.Clark@liverpool.ac.ukE<gt>,
d1e3b762 1740Thomas Dorner E<lt>Thomas.Dorner@start.deE<gt>,
dd9f0070
CN
1741Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>,
1742Dominic Dunlop E<lt>domo@vo.luE<gt>,
d1e3b762
GS
1743Neale Ferguson E<lt>neale@mailbox.tabnsw.com.auE<gt>,
1744David J. Fiander E<lt>davidf@mks.comE<gt>,
495c5fdc 1745Paul Green E<lt>Paul_Green@stratus.comE<gt>,
dd9f0070 1746M.J.T. Guy E<lt>mjtg@cus.cam.ac.ukE<gt>,
7c5ffed3 1747Jarkko Hietaniemi E<lt>jhi@iki.fi<gt>,
dd9f0070
CN
1748Luther Huffman E<lt>lutherh@stratcom.comE<gt>,
1749Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>,
322422de 1750Andreas J. KE<ouml>nig E<lt>koenig@kulturbox.deE<gt>,
3c075c7d 1751Markus Laker E<lt>mlaker@contax.co.ukE<gt>,
dd9f0070 1752Andrew M. Langmead E<lt>aml@world.std.comE<gt>,
19799a22 1753Larry Moore E<lt>ljmoore@freespace.netE<gt>,
e41182b5 1754Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>,
dd9f0070 1755Chris Nandor E<lt>pudge@pobox.comE<gt>,
322422de 1756Matthias Neeracher E<lt>neeri@iis.ee.ethz.chE<gt>,
e41182b5 1757Gary Ng E<lt>71564.1743@CompuServe.COME<gt>,
e41182b5 1758Tom Phoenix E<lt>rootbeer@teleport.comE<gt>,
dd9f0070 1759Peter Prymmer E<lt>pvhp@forte.comE<gt>,
322422de 1760Hugo van der Sanden E<lt>hv@crypt0.demon.co.ukE<gt>,
dd9f0070
CN
1761Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>,
1762Paul J. Schinder E<lt>schinder@pobox.comE<gt>,
2ee0eb3c 1763Michael G Schwern E<lt>schwern@pobox.comE<gt>,
e41182b5 1764Dan Sugalski E<lt>sugalskd@ous.eduE<gt>,
dd9f0070 1765Nathan Torkington E<lt>gnat@frii.comE<gt>.
e41182b5 1766
3c075c7d
CN
1767This document is maintained by Chris Nandor
1768E<lt>pudge@pobox.comE<gt>.
e41182b5
GS
1769
1770=head1 VERSION
1771
d1e3b762 1772Version 1.44, last modified 22 July 1999