This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: Weird $ENV{FOO} = undef warning
[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
ad75418a 426Do not use either the bare result of C<pack("N", 10, 20, 30, 40)>
518ae4c9 427or bare v-strings (such as C<v10.20.30.40>) or to represent
6b2463a0
JH
428IPv4 addresses: both forms just pack the four bytes into network order.
429That this would be equal to the C language C<in_addr> struct (which is
430what the socket code internally uses) is not guaranteed. To be
431portable use the routines of the Socket extension, such as
432C<inet_aton()>, C<inet_ntoa()>, and C<sockaddr_in()>.
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
562checking C<$!> after an system call. Some platforms expect a certain
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
693 OS $^O $Config{'archname'}
694 --------------------------------------------
695 MS-DOS dos
696 PC-DOS dos
697 OS/2 os2
698 Windows 95 MSWin32 MSWin32-x86
6ab3f9cb 699 Windows 98 MSWin32 MSWin32-x86
e41182b5 700 Windows NT MSWin32 MSWin32-x86
6ab3f9cb 701 Windows NT MSWin32 MSWin32-ALPHA
e41182b5 702 Windows NT MSWin32 MSWin32-ppc
b4bc034f 703 Cygwin cygwin
e41182b5 704
34aaaa84
PP
705The various MSWin32 Perl's can distinguish the OS they are running on
706via the value of the fifth element of the list returned from
707Win32::GetOSVersion(). For example:
708
709 if ($^O eq 'MSWin32') {
710 my @os_version_info = Win32::GetOSVersion();
711 print +('3.1','95','NT')[$os_version_info[4]],"\n";
712 }
713
e41182b5
GS
714Also see:
715
716=over 4
717
c997b287 718=item *
e41182b5 719
c997b287
GS
720The djgpp environment for DOS, http://www.delorie.com/djgpp/
721and L<perldos>.
e41182b5 722
c997b287 723=item *
e41182b5 724
c997b287
GS
725The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
726http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or
727ftp://hobbes.nmsu.edu/pub/os2/dev/emx. Also L<perlos2>.
e41182b5 728
c997b287 729=item *
d1e3b762 730
c997b287
GS
731Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
732in L<perlcygwin>.
733
734=item *
735
736The C<Win32::*> modules in L<Win32>.
737
738=item *
739
740The ActiveState Pages, http://www.activestate.com/
741
742=item *
743
744The Cygwin environment for Win32; F<README.cygwin> (installed
47dafe4d 745as L<perlcygwin>), http://www.cygwin.com/
c997b287
GS
746
747=item *
748
749The U/WIN environment for Win32,
cea6626f 750http://www.research.att.com/sw/tools/uwin/
c997b287 751
cea6626f 752=item *
d1e3b762 753
cea6626f 754Build instructions for OS/2, L<perlos2>
d1e3b762 755
e41182b5
GS
756=back
757
dd9f0070 758=head2 S<Mac OS>
e41182b5
GS
759
760Any module requiring XS compilation is right out for most people, because
761MacPerl is built using non-free (and non-cheap!) compilers. Some XS
762modules that can work with MacPerl are built and distributed in binary
6ab3f9cb 763form on CPAN.
e41182b5
GS
764
765Directories are specified as:
766
767 volume:folder:file for absolute pathnames
768 volume:folder: for absolute pathnames
769 :folder:file for relative pathnames
770 :folder: for relative pathnames
771 :file for relative pathnames
772 file for relative pathnames
773
b7df3edc 774Files are stored in the directory in alphabetical order. Filenames are
6ab3f9cb 775limited to 31 characters, and may include any character except for
b7df3edc 776null and C<:>, which is reserved as the path separator.
e41182b5 777
0a47030a 778Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the
6ab3f9cb 779Mac::Files module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>.
e41182b5
GS
780
781In the MacPerl application, you can't run a program from the command line;
782programs that expect C<@ARGV> to be populated can be edited with something
783like the following, which brings up a dialog box asking for the command
784line arguments.
785
786 if (!@ARGV) {
787 @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
788 }
789
b7df3edc 790A MacPerl script saved as a "droplet" will populate C<@ARGV> with the full
e41182b5
GS
791pathnames of the files dropped onto the script.
792
b7df3edc
GS
793Mac users can run programs under a type of command line interface
794under MPW (Macintosh Programmer's Workshop, a free development
795environment from Apple). MacPerl was first introduced as an MPW
796tool, and MPW can be used like a shell:
e41182b5
GS
797
798 perl myscript.plx some arguments
799
800ToolServer is another app from Apple that provides access to MPW tools
0a47030a 801from MPW and the MacPerl app, which allows MacPerl programs to use
e41182b5
GS
802C<system>, backticks, and piped C<open>.
803
804"S<Mac OS>" is the proper name for the operating system, but the value
805in C<$^O> is "MacOS". To determine architecture, version, or whether
806the application or MPW tool version is running, check:
807
808 $is_app = $MacPerl::Version =~ /App/;
809 $is_tool = $MacPerl::Version =~ /MPW/;
810 ($version) = $MacPerl::Version =~ /^(\S+)/;
811 $is_ppc = $MacPerl::Architecture eq 'MacPPC';
812 $is_68k = $MacPerl::Architecture eq 'Mac68K';
813
b787fad4
JH
814S<Mac OS X>, based on NeXT's OpenStep OS, runs MacPerl natively, under the
815"Classic" environment. There is no "Carbon" version of MacPerl to run
816under the primary Mac OS X environment. S<Mac OS X> and its Open Source
817version, Darwin, both run Unix perl natively.
6ab3f9cb 818
e41182b5
GS
819Also see:
820
821=over 4
822
c997b287
GS
823=item *
824
862b5365 825MacPerl Development, http://dev.macperl.org/ .
c997b287
GS
826
827=item *
828
862b5365 829The MacPerl Pages, http://www.macperl.com/ .
e41182b5 830
c997b287 831=item *
6ab3f9cb 832
862b5365 833The MacPerl mailing lists, http://lists.perl.org/ .
e41182b5
GS
834
835=back
836
e41182b5
GS
837=head2 VMS
838
c997b287 839Perl on VMS is discussed in L<perlvms> in the perl distribution.
b7df3edc 840Perl on VMS can accept either VMS- or Unix-style file
e41182b5
GS
841specifications as in either of the following:
842
843 $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
844 $ perl -ne "print if /perl_setup/i" /sys$login/login.com
845
846but not a mixture of both as in:
847
848 $ perl -ne "print if /perl_setup/i" sys$login:/login.com
849 Can't open sys$login:/login.com: file specification syntax error
850
851Interacting with Perl from the Digital Command Language (DCL) shell
852often requires a different set of quotation marks than Unix shells do.
853For example:
854
855 $ perl -e "print ""Hello, world.\n"""
856 Hello, world.
857
b7df3edc 858There are several ways to wrap your perl scripts in DCL F<.COM> files, if
e41182b5
GS
859you are so inclined. For example:
860
861 $ write sys$output "Hello from DCL!"
862 $ if p1 .eqs. ""
863 $ then perl -x 'f$environment("PROCEDURE")
864 $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
865 $ deck/dollars="__END__"
866 #!/usr/bin/perl
867
868 print "Hello from Perl!\n";
869
870 __END__
871 $ endif
872
873Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
c47ff5f1 874perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
e41182b5
GS
875
876Filenames are in the format "name.extension;version". The maximum
877length for filenames is 39 characters, and the maximum length for
878extensions is also 39 characters. Version is a number from 1 to
87932767. Valid characters are C</[A-Z0-9$_-]/>.
880
b7df3edc 881VMS's RMS filesystem is case-insensitive and does not preserve case.
e41182b5 882C<readdir> returns lowercased filenames, but specifying a file for
b7df3edc 883opening remains case-insensitive. Files without extensions have a
e41182b5 884trailing period on them, so doing a C<readdir> with a file named F<A.;5>
0a47030a
GS
885will return F<a.> (though that file could be opened with
886C<open(FH, 'A')>).
e41182b5 887
f34d0673 888RMS had an eight level limit on directory depths from any rooted logical
dd9f0070
CN
889(allowing 16 levels overall) prior to VMS 7.2. Hence
890C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a valid directory specification but
891C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is not. F<Makefile.PL> authors might
892have to take this into account, but at least they can refer to the former
f34d0673 893as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
e41182b5 894
6ab3f9cb 895The VMS::Filespec module, which gets installed as part of the build
0a47030a
GS
896process on VMS, is a pure Perl module that can easily be installed on
897non-VMS platforms and can be helpful for conversions to and from RMS
898native formats.
e41182b5 899
5e12dbfa
PP
900What C<\n> represents depends on the type of file opened. It usually
901represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>,
902C<\000>, C<\040>, or nothing depending on the file organiztion and
903record format. The VMS::Stdio module provides access to the
904special fopen() requirements of files with unusual attributes on VMS.
e41182b5
GS
905
906TCP/IP stacks are optional on VMS, so socket routines might not be
907implemented. UDP sockets may not be supported.
908
909The value of C<$^O> on OpenVMS is "VMS". To determine the architecture
910that you are running on without resorting to loading all of C<%Config>
911you can examine the content of the C<@INC> array like so:
912
913 if (grep(/VMS_AXP/, @INC)) {
914 print "I'm on Alpha!\n";
6ab3f9cb 915
e41182b5
GS
916 } elsif (grep(/VMS_VAX/, @INC)) {
917 print "I'm on VAX!\n";
6ab3f9cb 918
e41182b5
GS
919 } else {
920 print "I'm not so sure about where $^O is...\n";
921 }
922
b7df3edc
GS
923On VMS, perl determines the UTC offset from the C<SYS$TIMEZONE_DIFFERENTIAL>
924logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
6ab3f9cb 925calls to C<localtime> are adjusted to count offsets from
b7df3edc 92601-JAN-1970 00:00:00.00, just like Unix.
6ab3f9cb 927
e41182b5
GS
928Also see:
929
930=over 4
931
c997b287
GS
932=item *
933
934F<README.vms> (installed as L<README_vms>), L<perlvms>
935
936=item *
937
938vmsperl list, majordomo@perl.org
e41182b5 939
c997b287 940(Put the words C<subscribe vmsperl> in message body.)
e41182b5 941
c997b287 942=item *
e41182b5 943
c997b287 944vmsperl on the web, http://www.sidhe.org/vmsperl/index.html
e41182b5
GS
945
946=back
947
495c5fdc
GP
948=head2 VOS
949
9a997319
JH
950Perl on VOS is discussed in F<README.vos> in the perl distribution
951(installed as L<perlvos>). Perl on VOS can accept either VOS- or
952Unix-style file specifications as in either of the following:
495c5fdc
GP
953
954 $ perl -ne "print if /perl_setup/i" >system>notices
955 $ perl -ne "print if /perl_setup/i" /system/notices
956
957or even a mixture of both as in:
958
959 $ perl -ne "print if /perl_setup/i" >system/notices
960
b7df3edc 961Even though VOS allows the slash character to appear in object
495c5fdc
GP
962names, because the VOS port of Perl interprets it as a pathname
963delimiting character, VOS files, directories, or links whose names
964contain a slash character cannot be processed. Such files must be
a3dfe201
GS
965renamed before they can be processed by Perl. Note that VOS limits
966file names to 32 or fewer characters.
495c5fdc 967
5b8c1387
JH
968See F<README.vos> for restrictions that apply when Perl is built
969with the alpha version of VOS POSIX.1 support.
970
971Perl on VOS is built without any extensions and does not support
972dynamic loading.
495c5fdc
GP
973
974The value of C<$^O> on VOS is "VOS". To determine the architecture that
975you are running on without resorting to loading all of C<%Config> you
c997b287 976can examine the content of the @INC array like so:
495c5fdc 977
24e8e380 978 if ($^O =~ /VOS/) {
495c5fdc
GP
979 print "I'm on a Stratus box!\n";
980 } else {
981 print "I'm not on a Stratus box!\n";
982 die;
983 }
984
985 if (grep(/860/, @INC)) {
986 print "This box is a Stratus XA/R!\n";
6ab3f9cb 987
495c5fdc 988 } elsif (grep(/7100/, @INC)) {
24e8e380 989 print "This box is a Stratus HP 7100 or 8xxx!\n";
6ab3f9cb 990
495c5fdc 991 } elsif (grep(/8000/, @INC)) {
24e8e380 992 print "This box is a Stratus HP 8xxx!\n";
6ab3f9cb 993
495c5fdc 994 } else {
24e8e380 995 print "This box is a Stratus 68K!\n";
495c5fdc
GP
996 }
997
998Also see:
999
1000=over 4
1001
c997b287 1002=item *
495c5fdc 1003
c997b287
GS
1004F<README.vos>
1005
1006=item *
1007
1008The VOS mailing list.
495c5fdc
GP
1009
1010There is no specific mailing list for Perl on VOS. You can post
1011comments to the comp.sys.stratus newsgroup, or subscribe to the general
1012Stratus mailing list. Send a letter with "Subscribe Info-Stratus" in
1013the message body to majordomo@list.stratagy.com.
1014
c997b287
GS
1015=item *
1016
1017VOS Perl on the web at http://ftp.stratus.com/pub/vos/vos.html
495c5fdc
GP
1018
1019=back
1020
e41182b5
GS
1021=head2 EBCDIC Platforms
1022
1023Recent versions of Perl have been ported to platforms such as OS/400 on
d1e3b762
GS
1024AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
1025Mainframes. Such computers use EBCDIC character sets internally (usually
0cc436d0
GS
1026Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
1027systems). On the mainframe perl currently works under the "Unix system
1028services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
1029the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
c997b287 1030See L<perlos390> for details.
e41182b5 1031
7c5ffed3
JH
1032As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
1033sub-systems do not support the C<#!> shebang trick for script invocation.
1034Hence, on OS/390 and VM/ESA perl scripts can be executed with a header
1035similar to the following simple script:
e41182b5
GS
1036
1037 : # use perl
1038 eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
1039 if 0;
1040 #!/usr/local/bin/perl # just a comment really
1041
1042 print "Hello from perl!\n";
1043
d1e3b762
GS
1044OS/390 will support the C<#!> shebang trick in release 2.8 and beyond.
1045Calls to C<system> and backticks can use POSIX shell syntax on all
1046S/390 systems.
1047
b7df3edc 1048On the AS/400, if PERL5 is in your library list, you may need
6ab3f9cb
GS
1049to wrap your perl scripts in a CL procedure to invoke them like so:
1050
1051 BEGIN
1052 CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
1053 ENDPGM
1054
1055This will invoke the perl script F<hello.pl> in the root of the
1056QOpenSys file system. On the AS/400 calls to C<system> or backticks
1057must use CL syntax.
1058
e41182b5 1059On these platforms, bear in mind that the EBCDIC character set may have
0a47030a
GS
1060an effect on what happens with some perl functions (such as C<chr>,
1061C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
1062well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
1063and C<|>, not to mention dealing with socket interfaces to ASCII computers
6ab3f9cb 1064(see L<"Newlines">).
e41182b5 1065
b7df3edc
GS
1066Fortunately, most web servers for the mainframe will correctly
1067translate the C<\n> in the following statement to its ASCII equivalent
1068(C<\r> is the same under both Unix and OS/390 & VM/ESA):
e41182b5
GS
1069
1070 print "Content-type: text/html\r\n\r\n";
1071
d1e3b762 1072The values of C<$^O> on some of these platforms includes:
e41182b5 1073
d1e3b762
GS
1074 uname $^O $Config{'archname'}
1075 --------------------------------------------
1076 OS/390 os390 os390
1077 OS400 os400 os400
1078 POSIX-BC posix-bc BS2000-posix-bc
1079 VM/ESA vmesa vmesa
3c075c7d 1080
e41182b5
GS
1081Some simple tricks for determining if you are running on an EBCDIC
1082platform could include any of the following (perhaps all):
1083
1084 if ("\t" eq "\05") { print "EBCDIC may be spoken here!\n"; }
1085
1086 if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
1087
1088 if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
1089
b7df3edc 1090One thing you may not want to rely on is the EBCDIC encoding
0a47030a
GS
1091of punctuation characters since these may differ from code page to code
1092page (and once your module or script is rumoured to work with EBCDIC,
1093folks will want it to work with all EBCDIC character sets).
e41182b5
GS
1094
1095Also see:
1096
1097=over 4
1098
c997b287
GS
1099=item *
1100
1101*
d1e3b762 1102
dc5c060f 1103L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
bb462878 1104L<perlebcdic>.
c997b287
GS
1105
1106=item *
e41182b5
GS
1107
1108The perl-mvs@perl.org list is for discussion of porting issues as well as
1109general usage issues for all EBCDIC Perls. Send a message body of
1110"subscribe perl-mvs" to majordomo@perl.org.
1111
c997b287
GS
1112=item *
1113
1114AS/400 Perl information at
b1866b2d 1115http://as400.rochester.ibm.com/
d1e3b762 1116as well as on CPAN in the F<ports/> directory.
e41182b5
GS
1117
1118=back
1119
b8099c3d
CN
1120=head2 Acorn RISC OS
1121
b7df3edc
GS
1122Because Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
1123Unix, and because Unix filename emulation is turned on by default,
1124most simple scripts will probably work "out of the box". The native
6ab3f9cb 1125filesystem is modular, and individual filesystems are free to be
0a47030a 1126case-sensitive or insensitive, and are usually case-preserving. Some
b7df3edc 1127native filesystems have name length limits, which file and directory
6ab3f9cb
GS
1128names are silently truncated to fit. Scripts should be aware that the
1129standard filesystem currently has a name length limit of B<10>
1130characters, with up to 77 items in a directory, but other filesystems
0a47030a 1131may not impose such limitations.
b8099c3d
CN
1132
1133Native filenames are of the form
1134
6ab3f9cb 1135 Filesystem#Special_Field::DiskName.$.Directory.Directory.File
dd9f0070 1136
b8099c3d
CN
1137where
1138
1139 Special_Field is not usually present, but may contain . and $ .
1140 Filesystem =~ m|[A-Za-z0-9_]|
1141 DsicName =~ m|[A-Za-z0-9_/]|
1142 $ represents the root directory
1143 . is the path separator
1144 @ is the current directory (per filesystem but machine global)
1145 ^ is the parent directory
1146 Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
1147
1148The default filename translation is roughly C<tr|/.|./|;>
1149
6ab3f9cb 1150Note that C<"ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File'> and that
0a47030a
GS
1151the second stage of C<$> interpolation in regular expressions will fall
1152foul of the C<$.> if scripts are not careful.
1153
1154Logical paths specified by system variables containing comma-separated
b7df3edc 1155search lists are also allowed; hence C<System:Modules> is a valid
0a47030a 1156filename, and the filesystem will prefix C<Modules> with each section of
6ab3f9cb 1157C<System$Path> until a name is made that points to an object on disk.
b7df3edc 1158Writing to a new file C<System:Modules> would be allowed only if
0a47030a
GS
1159C<System$Path> contains a single item list. The filesystem will also
1160expand system variables in filenames if enclosed in angle brackets, so
c47ff5f1 1161C<< <System$Dir>.Modules >> would look for the file
0a47030a 1162S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is
c47ff5f1 1163that B<fully qualified filenames can start with C<< <> >>> and should
0a47030a 1164be protected when C<open> is used for input.
b8099c3d
CN
1165
1166Because C<.> was in use as a directory separator and filenames could not
1167be assumed to be unique after 10 characters, Acorn implemented the C
1168compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
1169filenames specified in source code and store the respective files in
b7df3edc 1170subdirectories named after the suffix. Hence files are translated:
b8099c3d
CN
1171
1172 foo.h h.foo
1173 C:foo.h C:h.foo (logical path variable)
1174 sys/os.h sys.h.os (C compiler groks Unix-speak)
1175 10charname.c c.10charname
1176 10charname.o o.10charname
1177 11charname_.c c.11charname (assuming filesystem truncates at 10)
1178
1179The Unix emulation library's translation of filenames to native assumes
b7df3edc
GS
1180that this sort of translation is required, and it allows a user-defined list
1181of known suffixes that it will transpose in this fashion. This may
1182seem transparent, but consider that with these rules C<foo/bar/baz.h>
0a47030a
GS
1183and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
1184C<glob> cannot and do not attempt to emulate the reverse mapping. Other
6ab3f9cb 1185C<.>'s in filenames are translated to C</>.
0a47030a 1186
b7df3edc 1187As implied above, the environment accessed through C<%ENV> is global, and
0a47030a 1188the convention is that program specific environment variables are of the
6ab3f9cb
GS
1189form C<Program$Name>. Each filesystem maintains a current directory,
1190and the current filesystem's current directory is the B<global> current
b7df3edc
GS
1191directory. Consequently, sociable programs don't change the current
1192directory but rely on full pathnames, and programs (and Makefiles) cannot
0a47030a
GS
1193assume that they can spawn a child process which can change the current
1194directory without affecting its parent (and everyone else for that
1195matter).
1196
b7df3edc
GS
1197Because native operating system filehandles are global and are currently
1198allocated down from 255, with 0 being a reserved value, the Unix emulation
0a47030a
GS
1199library emulates Unix filehandles. Consequently, you can't rely on
1200passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
1201
1202The desire of users to express filenames of the form
c47ff5f1 1203C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
0a47030a 1204too: C<``> command output capture has to perform a guessing game. It
c47ff5f1 1205assumes that a string C<< <[^<>]+\$[^<>]> >> is a
0a47030a 1206reference to an environment variable, whereas anything else involving
c47ff5f1 1207C<< < >> or C<< > >> is redirection, and generally manages to be 99%
0a47030a
GS
1208right. Of course, the problem remains that scripts cannot rely on any
1209Unix tools being available, or that any tools found have Unix-like command
1210line arguments.
1211
b7df3edc
GS
1212Extensions and XS are, in theory, buildable by anyone using free
1213tools. In practice, many don't, as users of the Acorn platform are
1214used to binary distributions. MakeMaker does run, but no available
1215make currently copes with MakeMaker's makefiles; even if and when
1216this should be fixed, the lack of a Unix-like shell will cause
1217problems with makefile rules, especially lines of the form C<cd
1218sdbm && make all>, and anything using quoting.
b8099c3d
CN
1219
1220"S<RISC OS>" is the proper name for the operating system, but the value
1221in C<$^O> is "riscos" (because we don't like shouting).
1222
e41182b5
GS
1223=head2 Other perls
1224
b7df3edc
GS
1225Perl has been ported to many platforms that do not fit into any of
1226the categories listed above. Some, such as AmigaOS, Atari MiNT,
1227BeOS, HP MPE/iX, QNX, Plan 9, and VOS, have been well-integrated
1228into the standard Perl source code kit. You may need to see the
1229F<ports/> directory on CPAN for information, and possibly binaries,
1230for the likes of: aos, Atari ST, lynxos, riscos, Novell Netware,
1231Tandem Guardian, I<etc.> (Yes, we know that some of these OSes may
1232fall under the Unix category, but we are not a standards body.)
e41182b5 1233
d1e3b762
GS
1234Some approximate operating system names and their C<$^O> values
1235in the "OTHER" category include:
1236
1237 OS $^O $Config{'archname'}
1238 ------------------------------------------
1239 Amiga DOS amigaos m68k-amigos
1240 MPE/iX mpeix PA-RISC1.1
1241
e41182b5
GS
1242See also:
1243
1244=over 4
1245
c997b287
GS
1246=item *
1247
1248Amiga, F<README.amiga> (installed as L<perlamiga>).
1249
1250=item *
d1e3b762 1251
c997b287
GS
1252Atari, F<README.mint> and Guido Flohr's web page
1253http://stud.uni-sb.de/~gufl0000/
e41182b5 1254
c997b287 1255=item *
d1e3b762 1256
c997b287 1257Be OS, F<README.beos>
e41182b5 1258
c997b287
GS
1259=item *
1260
1261HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
34aaaa84 1262http://www.bixby.org/mark/perlix.html
c997b287
GS
1263
1264=item *
e41182b5 1265
6ab3f9cb 1266A free perl5-based PERL.NLM for Novell Netware is available in
c997b287 1267precompiled binary and source code form from http://www.novell.com/
6ab3f9cb 1268as well as from CPAN.
e41182b5 1269
13a2d996 1270=item *
c997b287
GS
1271
1272Plan 9, F<README.plan9>
d1e3b762 1273
e41182b5
GS
1274=back
1275
e41182b5
GS
1276=head1 FUNCTION IMPLEMENTATIONS
1277
b7df3edc
GS
1278Listed below are functions that are either completely unimplemented
1279or else have been implemented differently on various platforms.
1280Following each description will be, in parentheses, a list of
1281platforms that the description applies to.
e41182b5 1282
b7df3edc
GS
1283The list may well be incomplete, or even wrong in some places. When
1284in doubt, consult the platform-specific README files in the Perl
1285source distribution, and any other documentation resources accompanying
1286a given port.
e41182b5 1287
0a47030a 1288Be aware, moreover, that even among Unix-ish systems there are variations.
e41182b5 1289
b7df3edc
GS
1290For many functions, you can also query C<%Config>, exported by
1291default from the Config module. For example, to check whether the
1292platform has the C<lstat> call, check C<$Config{d_lstat}>. See
1293L<Config> for a full description of available variables.
e41182b5
GS
1294
1295=head2 Alphabetical Listing of Perl Functions
1296
1297=over 8
1298
1299=item -X FILEHANDLE
1300
1301=item -X EXPR
1302
1303=item -X
1304
b7df3edc 1305C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
e41182b5 1306and applications are executable, and there are no uid/gid
b7df3edc 1307considerations. C<-o> is not supported. (S<Mac OS>)
e41182b5 1308
b7df3edc
GS
1309C<-r>, C<-w>, C<-x>, and C<-o> tell whether the file is accessible,
1310which may not reflect UIC-based file protections. (VMS)
e41182b5 1311
b8099c3d
CN
1312C<-s> returns the size of the data fork, not the total size of data fork
1313plus resource fork. (S<Mac OS>).
1314
1315C<-s> by name on an open file will return the space reserved on disk,
1316rather than the current extent. C<-s> on an open filehandle returns the
b7df3edc 1317current size. (S<RISC OS>)
b8099c3d 1318
e41182b5 1319C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
b8099c3d 1320C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1321
1322C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
1323(S<Mac OS>)
1324
1325C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
b8099c3d 1326(Win32, VMS, S<RISC OS>)
e41182b5
GS
1327
1328C<-d> is true if passed a device spec without an explicit directory.
1329(VMS)
1330
1331C<-T> and C<-B> are implemented, but might misclassify Mac text files
0a47030a 1332with foreign characters; this is the case will all platforms, but may
b7df3edc 1333affect S<Mac OS> often. (S<Mac OS>)
e41182b5
GS
1334
1335C<-x> (or C<-X>) determine if a file ends in one of the executable
b7df3edc 1336suffixes. C<-S> is meaningless. (Win32)
e41182b5 1337
b8099c3d
CN
1338C<-x> (or C<-X>) determine if a file has an executable file type.
1339(S<RISC OS>)
1340
63f87e49
GS
1341=item alarm SECONDS
1342
1343=item alarm
1344
1345Not implemented. (Win32)
1346
e41182b5
GS
1347=item binmode FILEHANDLE
1348
b7df3edc 1349Meaningless. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1350
1351Reopens file and restores pointer; if function fails, underlying
1352filehandle may be closed, or pointer may be in a different position.
1353(VMS)
1354
1355The value returned by C<tell> may be affected after the call, and
1356the filehandle may be flushed. (Win32)
1357
1358=item chmod LIST
1359
b7df3edc 1360Only limited meaning. Disabling/enabling write permission is mapped to
e41182b5
GS
1361locking/unlocking the file. (S<Mac OS>)
1362
1363Only good for changing "owner" read-write access, "group", and "other"
1364bits are meaningless. (Win32)
1365
b8099c3d
CN
1366Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
1367
495c5fdc
GP
1368Access permissions are mapped onto VOS access-control list changes. (VOS)
1369
e41182b5
GS
1370=item chown LIST
1371
495c5fdc 1372Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1373
1374Does nothing, but won't fail. (Win32)
1375
1376=item chroot FILENAME
1377
1378=item chroot
1379
7c5ffed3 1380Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1381
1382=item crypt PLAINTEXT,SALT
1383
1384May not be available if library or source was not provided when building
b8099c3d 1385perl. (Win32)
e41182b5 1386
495c5fdc
GP
1387Not implemented. (VOS)
1388
e41182b5
GS
1389=item dbmclose HASH
1390
495c5fdc 1391Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1392
1393=item dbmopen HASH,DBNAME,MODE
1394
495c5fdc 1395Not implemented. (VMS, Plan9, VOS)
e41182b5
GS
1396
1397=item dump LABEL
1398
b8099c3d 1399Not useful. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1400
1401Not implemented. (Win32)
1402
b8099c3d 1403Invokes VMS debugger. (VMS)
e41182b5
GS
1404
1405=item exec LIST
1406
1407Not implemented. (S<Mac OS>)
1408
7c5ffed3 1409Implemented via Spawn. (VM/ESA)
3c075c7d 1410
0f897271
GS
1411Does not automatically flush output handles on some platforms.
1412(SunOS, Solaris, HP-UX)
1413
e41182b5
GS
1414=item fcntl FILEHANDLE,FUNCTION,SCALAR
1415
1416Not implemented. (Win32, VMS)
1417
1418=item flock FILEHANDLE,OPERATION
1419
495c5fdc 1420Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
e41182b5
GS
1421
1422Available only on Windows NT (not on Windows 95). (Win32)
1423
1424=item fork
1425
0f897271
GS
1426Not implemented. (S<Mac OS>, AmigaOS, S<RISC OS>, VOS, VM/ESA)
1427
1428Emulated using multiple interpreters. See L<perlfork>. (Win32)
1429
1430Does not automatically flush output handles on some platforms.
1431(SunOS, Solaris, HP-UX)
e41182b5
GS
1432
1433=item getlogin
1434
b8099c3d 1435Not implemented. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1436
1437=item getpgrp PID
1438
495c5fdc 1439Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1440
1441=item getppid
1442
b8099c3d 1443Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1444
1445=item getpriority WHICH,WHO
1446
7c5ffed3 1447Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1448
1449=item getpwnam NAME
1450
1451Not implemented. (S<Mac OS>, Win32)
1452
b8099c3d
CN
1453Not useful. (S<RISC OS>)
1454
e41182b5
GS
1455=item getgrnam NAME
1456
b8099c3d 1457Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1458
1459=item getnetbyname NAME
1460
1461Not implemented. (S<Mac OS>, Win32, Plan9)
1462
1463=item getpwuid UID
1464
1465Not implemented. (S<Mac OS>, Win32)
1466
b8099c3d
CN
1467Not useful. (S<RISC OS>)
1468
e41182b5
GS
1469=item getgrgid GID
1470
b8099c3d 1471Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1472
1473=item getnetbyaddr ADDR,ADDRTYPE
1474
1475Not implemented. (S<Mac OS>, Win32, Plan9)
1476
1477=item getprotobynumber NUMBER
1478
1479Not implemented. (S<Mac OS>)
1480
1481=item getservbyport PORT,PROTO
1482
1483Not implemented. (S<Mac OS>)
1484
1485=item getpwent
1486
7c5ffed3 1487Not implemented. (S<Mac OS>, Win32, VM/ESA)
e41182b5
GS
1488
1489=item getgrent
1490
7c5ffed3 1491Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA)
e41182b5
GS
1492
1493=item gethostent
1494
1495Not implemented. (S<Mac OS>, Win32)
1496
1497=item getnetent
1498
1499Not implemented. (S<Mac OS>, Win32, Plan9)
1500
1501=item getprotoent
1502
1503Not implemented. (S<Mac OS>, Win32, Plan9)
1504
1505=item getservent
1506
1507Not implemented. (Win32, Plan9)
1508
1509=item setpwent
1510
b8099c3d 1511Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1512
1513=item setgrent
1514
b8099c3d 1515Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1516
1517=item sethostent STAYOPEN
1518
b8099c3d 1519Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1520
1521=item setnetent STAYOPEN
1522
b8099c3d 1523Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1524
1525=item setprotoent STAYOPEN
1526
b8099c3d 1527Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1528
1529=item setservent STAYOPEN
1530
b8099c3d 1531Not implemented. (Plan9, Win32, S<RISC OS>)
e41182b5
GS
1532
1533=item endpwent
1534
a3dfe201 1535Not implemented. (S<Mac OS>, MPE/iX, VM/ESA, Win32)
e41182b5
GS
1536
1537=item endgrent
1538
a3dfe201 1539Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
e41182b5
GS
1540
1541=item endhostent
1542
1543Not implemented. (S<Mac OS>, Win32)
1544
1545=item endnetent
1546
1547Not implemented. (S<Mac OS>, Win32, Plan9)
1548
1549=item endprotoent
1550
1551Not implemented. (S<Mac OS>, Win32, Plan9)
1552
1553=item endservent
1554
1555Not implemented. (Plan9, Win32)
1556
9bc98430
CB
1557=item exit EXPR
1558
1559=item exit
1560
1561Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
1562mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden
1563with the pragma C<use vmsish 'exit'>. As with the CRTL's exit()
1564function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
1565(C<1>); this mapping cannot be overridden. Any other argument to exit()
1566is used directly as Perl's exit status. (VMS)
1567
e41182b5
GS
1568=item getsockopt SOCKET,LEVEL,OPTNAME
1569
1570Not implemented. (S<Mac OS>, Plan9)
1571
1572=item glob EXPR
1573
1574=item glob
1575
63f87e49
GS
1576This operator is implemented via the File::Glob extension on most
1577platforms. See L<File::Glob> for portability information.
b8099c3d 1578
e41182b5
GS
1579=item ioctl FILEHANDLE,FUNCTION,SCALAR
1580
1581Not implemented. (VMS)
1582
1583Available only for socket handles, and it does what the ioctlsocket() call
1584in the Winsock API does. (Win32)
1585
b8099c3d
CN
1586Available only for socket handles. (S<RISC OS>)
1587
b350dd2f 1588=item kill SIGNAL, LIST
e41182b5 1589
862b5365
JH
1590C<kill(0, LIST)> is implemented for the sake of taint checking;
1591use with other signals is unimplemented. (S<Mac OS>)
1592
1593Not implemented, hence not useful for taint checking. (S<RISC OS>)
e41182b5 1594
63f87e49
GS
1595C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
1596a signal to the identified process like it does on Unix platforms.
1597Instead C<kill($sig, $pid)> terminates the process identified by $pid,
1598and makes it exit immediately with exit status $sig. As in Unix, if
1599$sig is 0 and the specified process exists, it returns true without
1600actually terminating it. (Win32)
e41182b5
GS
1601
1602=item link OLDFILE,NEWFILE
1603
a3dfe201 1604Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
e41182b5 1605
433acd8a
JH
1606Link count not updated because hard links are not quite that hard
1607(They are sort of half-way between hard and soft links). (AmigaOS)
1608
a3dfe201
GS
1609Hard links are implemented on Win32 (Windows NT and Windows 2000)
1610under NTFS only.
1611
e41182b5
GS
1612=item lstat FILEHANDLE
1613
1614=item lstat EXPR
1615
1616=item lstat
1617
b8099c3d 1618Not implemented. (VMS, S<RISC OS>)
e41182b5 1619
63f87e49 1620Return values (especially for device and inode) may be bogus. (Win32)
e41182b5
GS
1621
1622=item msgctl ID,CMD,ARG
1623
1624=item msgget KEY,FLAGS
1625
1626=item msgsnd ID,MSG,FLAGS
1627
1628=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1629
495c5fdc 1630Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS)
e41182b5
GS
1631
1632=item open FILEHANDLE,EXPR
1633
1634=item open FILEHANDLE
1635
b7df3edc 1636The C<|> variants are supported only if ToolServer is installed.
e41182b5
GS
1637(S<Mac OS>)
1638
c47ff5f1 1639open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5 1640
0f897271
GS
1641Opening a process does not automatically flush output handles on some
1642platforms. (SunOS, Solaris, HP-UX)
1643
e41182b5
GS
1644=item pipe READHANDLE,WRITEHANDLE
1645
433acd8a
JH
1646Very limited functionality. (MiNT)
1647
e41182b5
GS
1648=item readlink EXPR
1649
1650=item readlink
1651
b8099c3d 1652Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1653
1654=item select RBITS,WBITS,EBITS,TIMEOUT
1655
1656Only implemented on sockets. (Win32)
1657
b8099c3d
CN
1658Only reliable on sockets. (S<RISC OS>)
1659
63f87e49
GS
1660Note that the C<socket FILEHANDLE> form is generally portable.
1661
e41182b5
GS
1662=item semctl ID,SEMNUM,CMD,ARG
1663
1664=item semget KEY,NSEMS,FLAGS
1665
1666=item semop KEY,OPSTRING
1667
495c5fdc 1668Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5 1669
a3dfe201
GS
1670=item setgrent
1671
1672Not implemented. (MPE/iX, Win32)
1673
e41182b5
GS
1674=item setpgrp PID,PGRP
1675
495c5fdc 1676Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5
GS
1677
1678=item setpriority WHICH,WHO,PRIORITY
1679
495c5fdc 1680Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5 1681
a3dfe201
GS
1682=item setpwent
1683
1684Not implemented. (MPE/iX, Win32)
1685
e41182b5
GS
1686=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1687
1688Not implemented. (S<Mac OS>, Plan9)
1689
1690=item shmctl ID,CMD,ARG
1691
1692=item shmget KEY,SIZE,FLAGS
1693
1694=item shmread ID,VAR,POS,SIZE
1695
1696=item shmwrite ID,STRING,POS,SIZE
1697
495c5fdc 1698Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
e41182b5 1699
80cbd5ad
JH
1700=item sockatmark SOCKET
1701
1702A relatively recent addition to socket functions, may not
1703be implemented even in UNIX platforms.
1704
e41182b5
GS
1705=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1706
862b5365 1707Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5
GS
1708
1709=item stat FILEHANDLE
1710
1711=item stat EXPR
1712
1713=item stat
1714
d62e1b7f
JH
1715Platforms that do not have rdev, blksize, or blocks will return these
1716as '', so numeric comparison or manipulation of these fields may cause
1717'not numeric' warnings.
1718
e41182b5
GS
1719mtime and atime are the same thing, and ctime is creation time instead of
1720inode change time. (S<Mac OS>)
1721
1722device and inode are not meaningful. (Win32)
1723
1724device and inode are not necessarily reliable. (VMS)
1725
b8099c3d
CN
1726mtime, atime and ctime all return the last modification time. Device and
1727inode are not necessarily reliable. (S<RISC OS>)
1728
d62e1b7f
JH
1729dev, rdev, blksize, and blocks are not available. inode is not
1730meaningful and will differ between stat calls on the same file. (os2)
1731
73e9292c
JH
1732some versions of cygwin when doing a stat("foo") and if not finding it
1733may then attempt to stat("foo.exe") (Cygwin)
1734
e41182b5
GS
1735=item symlink OLDFILE,NEWFILE
1736
b8099c3d 1737Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1738
1739=item syscall LIST
1740
7c5ffed3 1741Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
e41182b5 1742
f34d0673
GS
1743=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1744
dd9f0070 1745The traditional "0", "1", and "2" MODEs are implemented with different
322422de
GS
1746numeric values on some systems. The flags exported by C<Fcntl>
1747(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
7c5ffed3 1748OS>, OS/390, VM/ESA)
f34d0673 1749
e41182b5
GS
1750=item system LIST
1751
1752Only implemented if ToolServer is installed. (S<Mac OS>)
1753
1754As an optimization, may not call the command shell specified in
b7df3edc 1755C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
e41182b5
GS
1756process and immediately returns its process designator, without
1757waiting for it to terminate. Return value may be used subsequently
63f87e49
GS
1758in C<wait> or C<waitpid>. Failure to spawn() a subprocess is indicated
1759by setting $? to "255 << 8". C<$?> is set in a way compatible with
1760Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8",
1761as described in the documentation). (Win32)
e41182b5 1762
b8099c3d
CN
1763There is no shell to process metacharacters, and the native standard is
1764to pass a command line terminated by "\n" "\r" or "\0" to the spawned
c47ff5f1 1765program. Redirection such as C<< > foo >> is performed (if at all) by
b8099c3d
CN
1766the run time library of the spawned program. C<system> I<list> will call
1767the Unix emulation library's C<exec> emulation, which attempts to provide
1768emulation of the stdin, stdout, stderr in force in the parent, providing
1769the child program uses a compatible version of the emulation library.
1770I<scalar> will call the native command line direct and no such emulation
1771of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
1772
433acd8a
JH
1773Far from being POSIX compliant. Because there may be no underlying
1774/bin/sh tries to work around the problem by forking and execing the
9b63e9ec 1775first token in its argument string. Handles basic redirection
c47ff5f1 1776("<" or ">") on its own behalf. (MiNT)
433acd8a 1777
0f897271
GS
1778Does not automatically flush output handles on some platforms.
1779(SunOS, Solaris, HP-UX)
1780
9bc98430
CB
1781The return value is POSIX-like (shifted up by 8 bits), which only allows
1782room for a made-up value derived from the severity bits of the native
178332-bit condition code (unless overridden by C<use vmsish 'status'>).
1784For more details see L<perlvms/$?>. (VMS)
1785
e41182b5
GS
1786=item times
1787
1788Only the first entry returned is nonzero. (S<Mac OS>)
1789
63f87e49
GS
1790"cumulative" times will be bogus. On anything other than Windows NT
1791or Windows 2000, "system" time will be bogus, and "user" time is
1792actually the time returned by the clock() function in the C runtime
1793library. (Win32)
e41182b5 1794
b8099c3d
CN
1795Not useful. (S<RISC OS>)
1796
e41182b5
GS
1797=item truncate FILEHANDLE,LENGTH
1798
1799=item truncate EXPR,LENGTH
1800
6d738113 1801Not implemented. (Older versions of VMS)
e41182b5 1802
495c5fdc
GP
1803Truncation to zero-length only. (VOS)
1804
4cfdb94f 1805If a FILEHANDLE is supplied, it must be writable and opened in append
e71a7dc8 1806mode (i.e., use C<<< open(FH, '>>filename') >>>
4cfdb94f
GS
1807or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
1808should not be held open elsewhere. (Win32)
1809
e41182b5
GS
1810=item umask EXPR
1811
1812=item umask
1813
1814Returns undef where unavailable, as of version 5.005.
1815
b7df3edc
GS
1816C<umask> works but the correct permissions are set only when the file
1817is finally closed. (AmigaOS)
433acd8a 1818
e41182b5
GS
1819=item utime LIST
1820
b8099c3d 1821Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
e41182b5 1822
322422de
GS
1823May not behave as expected. Behavior depends on the C runtime
1824library's implementation of utime(), and the filesystem being
1825used. The FAT filesystem typically does not support an "access
1826time" field, and it may limit timestamps to a granularity of
1827two seconds. (Win32)
e41182b5
GS
1828
1829=item wait
1830
1831=item waitpid PID,FLAGS
1832
495c5fdc 1833Not implemented. (S<Mac OS>, VOS)
e41182b5
GS
1834
1835Can only be applied to process handles returned for processes spawned
a6f858fb 1836using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32)
e41182b5 1837
b8099c3d
CN
1838Not useful. (S<RISC OS>)
1839
e41182b5
GS
1840=back
1841
b8099c3d
CN
1842=head1 CHANGES
1843
1844=over 4
1845
fd46a41b
JH
1846=item v1.48, 02 February 2001
1847
1848Various updates from perl5-porters over the past year, supported
1849platforms update from Jarkko Hietaniemi.
1850
c997b287
GS
1851=item v1.47, 22 March 2000
1852
1853Various cleanups from Tom Christiansen, including migration of
1854long platform listings from L<perl>.
1855
56d7751a
GS
1856=item v1.46, 12 February 2000
1857
1858Updates for VOS and MPE/iX. (Peter Prymmer) Other small changes.
1859
0cc436d0
GS
1860=item v1.45, 20 December 1999
1861
1862Small changes from 5.005_63 distribution, more changes to EBCDIC info.
1863
d1e3b762
GS
1864=item v1.44, 19 July 1999
1865
1866A bunch of updates from Peter Prymmer for C<$^O> values,
1867endianness, File::Spec, VMS, BS2000, OS/400.
1868
b7df3edc
GS
1869=item v1.43, 24 May 1999
1870
1871Added a lot of cleaning up from Tom Christiansen.
1872
19799a22 1873=item v1.42, 22 May 1999
b7df3edc 1874
19799a22 1875Added notes about tests, sprintf/printf, and epoch offsets.
b7df3edc 1876
6ab3f9cb
GS
1877=item v1.41, 19 May 1999
1878
1879Lots more little changes to formatting and content.
1880
d1e3b762 1881Added a bunch of C<$^O> and related values
6ab3f9cb
GS
1882for various platforms; fixed mail and web addresses, and added
1883and changed miscellaneous notes. (Peter Prymmer)
1884
1885=item v1.40, 11 April 1999
1886
1887Miscellaneous changes.
1888
1889=item v1.39, 11 February 1999
2ee0eb3c
CN
1890
1891Changes from Jarkko and EMX URL fixes Michael Schwern. Additional
1892note about newlines added.
1893
9b63e9ec
CN
1894=item v1.38, 31 December 1998
1895
1896More changes from Jarkko.
1897
3c075c7d
CN
1898=item v1.37, 19 December 1998
1899
1900More minor changes. Merge two separate version 1.35 documents.
1901
1902=item v1.36, 9 September 1998
1903
1904Updated for Stratus VOS. Also known as version 1.35.
1905
1906=item v1.35, 13 August 1998
495c5fdc 1907
3c075c7d
CN
1908Integrate more minor changes, plus addition of new sections under
1909L<"ISSUES">: L<"Numbers endianness and Width">,
1910L<"Character sets and character encoding">,
1911L<"Internationalisation">.
495c5fdc 1912
3c075c7d 1913=item v1.33, 06 August 1998
0a47030a
GS
1914
1915Integrate more minor changes.
1916
3c075c7d 1917=item v1.32, 05 August 1998
dd9f0070
CN
1918
1919Integrate more minor changes.
1920
3c075c7d 1921=item v1.30, 03 August 1998
b8099c3d
CN
1922
1923Major update for RISC OS, other minor changes.
1924
3c075c7d 1925=item v1.23, 10 July 1998
b8099c3d
CN
1926
1927First public release with perl5.005.
1928
1929=back
e41182b5 1930
ba58ab26
JH
1931=head1 Supported Platforms
1932
9ca74005
JH
1933As of early 2001 (the Perl releases 5.6.1 and 5.7.1), the following
1934platforms are able to build Perl from the standard source code
1935distribution available at http://www.perl.com/CPAN/src/index.html
ba58ab26
JH
1936
1937 AIX
fd46a41b 1938 AmigaOS
b787fad4 1939 Darwin (Mac OS X)
fd46a41b 1940 DG/UX
ba58ab26 1941 DOS DJGPP 1)
fd46a41b 1942 DYNIX/ptx
6ba81f13 1943 EPOC
ba58ab26
JH
1944 FreeBSD
1945 HP-UX
1946 IRIX
1947 Linux
ba58ab26 1948 MachTen
fd46a41b
JH
1949 MacOS Classic 2)
1950 NonStop-UX
1951 ReliantUNIX (SINIX)
ba58ab26 1952 OpenBSD
fd46a41b 1953 OpenVMS (VMS)
ba58ab26 1954 OS/2
fd46a41b 1955 OS X
ba58ab26 1956 QNX
ba58ab26 1957 Solaris
fd46a41b 1958 Tru64 UNIX (DEC OSF/1, Digital UNIX)
ba58ab26
JH
1959 UNICOS
1960 UNICOS/mk
ba58ab26 1961 VOS
fd46a41b 1962 Win32/NT/2K 3)
ba58ab26
JH
1963
1964 1) in DOS mode either the DOS or OS/2 ports can be used
fd46a41b
JH
1965 2) Mac OS Classic (pre-X) is almost 5.6.1-ready; building from
1966 the source does work with 5.6.1, but additional MacOS specific
862b5365
JH
1967 source code is needed for a complete build. See the web
1968 site http://dev.macperl.org/ for more information.
fd46a41b 1969 3) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
ba58ab26 1970
9ca74005
JH
1971The following platforms worked for the previous releases (5.6.0 and 5.7.0),
1972but we did not manage to test these in time for the 5.7.1 release.
1973There is a very good chance that these will work fine with the 5.7.1.
ba58ab26 1974
ba58ab26
JH
1975 DomainOS
1976 Hurd
fd46a41b
JH
1977 LynxOS
1978 MinGW
1979 MPE/iX
1980 NetBSD
ba58ab26 1981 PowerMAX
fd46a41b 1982 SCO SV
ba58ab26 1983 SunOS
fd46a41b
JH
1984 SVR4
1985 Unixware
1986 Windows 3.1
1987 Windows 95
1988 Windows 98
1989 Windows Me
ba58ab26 1990
fd46a41b 1991The following platform worked for the 5.005_03 major release but not
9ca74005
JH
1992for 5.6.0. Standardization on UTF-8 as the internal string
1993representation in 5.6.0 and 5.6.1 introduced incompatibilities in this
1994EBCDIC platform. While Perl 5.7.1 will build on this platform some
fd46a41b 1995regression tests may fail and the C<use utf8;> pragma typically
9ca74005 1996introduces text handling errors.
ba58ab26 1997
fd46a41b 1998 OS/390 1)
ba58ab26 1999
fd46a41b 2000 1) previously known as MVS, about to become z/OS.
ba58ab26 2001
fd46a41b 2002Strongly related to the OS/390 platform by also being EBCDIC-based
ba58ab26
JH
2003mainframe platforms are the following platforms:
2004
fd46a41b 2005 POSIX-BC (BS2000)
ba58ab26
JH
2006 VM/ESA
2007
fd46a41b
JH
2008These are also expected to work, albeit with no UTF-8 support, under 5.6.1
2009for the same reasons as OS/390. Contact the mailing list perl-mvs@perl.org
2010for more details.
ba58ab26
JH
2011
2012The following platforms have been known to build Perl from source in
fd46a41b
JH
2013the past (5.005_03 and earlier), but we haven't been able to verify
2014their status for the current release, either because the
2015hardware/software platforms are rare or because we don't have an
2016active champion on these platforms--or both. They used to work,
2017though, so go ahead and try compiling them, and let perlbug@perl.org
2018of any trouble.
ba58ab26
JH
2019
2020 3b1
fd46a41b
JH
2021 A/UX
2022 BeOS
2023 BSD/OS
ba58ab26
JH
2024 ConvexOS
2025 CX/UX
2026 DC/OSx
2027 DDE SMES
2028 DOS EMX
2029 Dynix
2030 EP/IX
2031 ESIX
2032 FPS
2033 GENIX
2034 Greenhills
2035 ISC
2036 MachTen 68k
2037 MiNT
2038 MPC
2039 NEWS-OS
fd46a41b
JH
2040 NextSTEP
2041 OpenSTEP
ba58ab26
JH
2042 Opus
2043 Plan 9
2044 PowerUX
2045 RISC/os
fd46a41b 2046 SCO ODT/OSR
ba58ab26
JH
2047 Stellar
2048 SVR2
2049 TI1500
2050 TitanOS
fd46a41b 2051 Ultrix
ba58ab26
JH
2052 Unisys Dynix
2053 Unixware
fd46a41b 2054 UTS
ba58ab26
JH
2055
2056Support for the following platform is planned for a future Perl release:
2057
2058 Netware
2059
2060The following platforms have their own source code distributions and
2061binaries available via http://www.perl.com/CPAN/ports/index.html:
2062
2063 Perl release
2064
ba58ab26 2065 Netware 5.003_07
fd46a41b 2066 OS/400 5.005_02
ba58ab26
JH
2067 Tandem Guardian 5.004
2068
2069The following platforms have only binaries available via
c997b287 2070http://www.perl.com/CPAN/ports/index.html :
ba58ab26
JH
2071
2072 Perl release
2073
2074 Acorn RISCOS 5.005_02
2075 AOS 5.002
2076 LynxOS 5.004_02
2077
2078Although we do suggest that you always build your own Perl from
2079the source code, both for maximal configurability and for security,
2080in case you are in a hurry you can check
2081http://www.perl.com/CPAN/ports/index.html for binary distributions.
2082
c997b287
GS
2083=head1 SEE ALSO
2084
a83b6f46 2085L<perlaix>, L<perlapollo>, L<perlamiga>, L<perlbeos>, L<perlbs200>,
a1f19229 2086L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>, L<perlepoc>, L<perlebcdic>,
a83b6f46 2087L<perlhurd>, L<perlhpux>, L<perlmachten>, L<perlmacos>, L<perlmint>,
9038e305
JH
2088L<perlmpeix>, L<perlnetware>, L<perlos2>, L<perlos390>, L<perlplan9>,
2089L<perlqnx>, L<perlsolaris>, L<perltru64>, L<perlunicode>,
2090L<perlvmesa>, L<perlvms>, L<perlvos>, L<perlwin32>, and L<Win32>.
c997b287 2091
e41182b5
GS
2092=head1 AUTHORS / CONTRIBUTORS
2093
06e9666b 2094Abigail <abigail@foad.org>,
c47ff5f1
GS
2095Charles Bailey <bailey@newman.upenn.edu>,
2096Graham Barr <gbarr@pobox.com>,
2097Tom Christiansen <tchrist@perl.com>,
06e9666b 2098Nicholas Clark <nick@ccl4.org>,
c47ff5f1 2099Thomas Dorner <Thomas.Dorner@start.de>,
06e9666b
A
2100Andy Dougherty <doughera@lafayette.edu>,
2101Dominic Dunlop <domo@computer.org>,
2102Neale Ferguson <neale@vma.tabnsw.com.au>,
c47ff5f1
GS
2103David J. Fiander <davidf@mks.com>,
2104Paul Green <Paul_Green@stratus.com>,
06e9666b 2105M.J.T. Guy <mjtg@cam.ac.uk>,
61f30a5e 2106Jarkko Hietaniemi <jhi@iki.fi>,
c47ff5f1 2107Luther Huffman <lutherh@stratcom.com>,
06e9666b
A
2108Nick Ing-Simmons <nick@ing-simmons.net>,
2109Andreas J. KE<ouml>nig <a.koenig@mind.de>,
c47ff5f1
GS
2110Markus Laker <mlaker@contax.co.uk>,
2111Andrew M. Langmead <aml@world.std.com>,
2112Larry Moore <ljmoore@freespace.net>,
2113Paul Moore <Paul.Moore@uk.origin-it.com>,
2114Chris Nandor <pudge@pobox.com>,
2115Matthias Neeracher <neeri@iis.ee.ethz.ch>,
e71a7dc8 2116Philip Newton <pne@cpan.org>,
c47ff5f1
GS
2117Gary Ng <71564.1743@CompuServe.COM>,
2118Tom Phoenix <rootbeer@teleport.com>,
2119AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
2120Peter Prymmer <pvhp@forte.com>,
2121Hugo van der Sanden <hv@crypt0.demon.co.uk>,
2122Gurusamy Sarathy <gsar@activestate.com>,
2123Paul J. Schinder <schinder@pobox.com>,
2124Michael G Schwern <schwern@pobox.com>,
06e9666b 2125Dan Sugalski <dan@sidhe.org>,
c47ff5f1 2126Nathan Torkington <gnat@frii.com>.
e41182b5 2127
e41182b5
GS
2128=head1 VERSION
2129
b787fad4 2130Version 1.50, last modified 10 Jul 2001