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