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