This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlport.pod v1.33 from Chris Nandor <pudge@pobox.com>
[perl5.git] / pod / perlport.pod
CommitLineData
e41182b5
GS
1=head1 NAME
2
3perlport - Writing portable Perl
4
5
6=head1 DESCRIPTION
7
8Perl runs on a variety of operating systems. While most of them share
9a lot in common, they also have their own very particular and unique
10features.
11
12This document is meant to help you to find out what constitutes portable
0a47030a 13Perl code, so that once you have made your decision to write portably,
e41182b5
GS
14you know where the lines are drawn, and you can stay within them.
15
16There is a tradeoff between taking full advantage of B<a> particular type
0a47030a
GS
17of computer, and taking advantage of a full B<range> of them. Naturally,
18as you make your range bigger (and thus more diverse), the common
19denominators drop, and you are left with fewer areas of common ground in
20which you can operate to accomplish a particular task. Thus, when you
21begin attacking a problem, it is important to consider which part of the
22tradeoff curve you want to operate under. Specifically, whether it is
23important to you that the task that you are coding needs the full
24generality of being portable, or if it is sufficient to just get the job
25done. This is the hardest choice to be made. The rest is easy, because
26Perl provides lots of choices, whichever way you want to approach your
27problem.
28
29Looking at it another way, writing portable code is usually about
30willfully limiting your available choices. Naturally, it takes discipline
31to do that.
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
39There is no reason why you should not use Perl as a language to glue Unix
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
44=item The vast majority of Perl B<is> portable
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
50without modification. But there I<are> some significant issues in
51writing portable code, and this document is entirely about those issues.
52
53=back
54
55Here's the general rule: When you approach a task that is commonly done
56using a whole range of platforms, think in terms of writing portable
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
0a47030a
GS
64When the code will run on only two or three operating systems, then you
65may only need to consider the differences of those particular systems.
66The important thing is to decide where the code will run, and to be
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
71builtin perl functions that behave differently on various ports
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
e41182b5
GS
76all of which are in a state of constant evolution. Thus this material
77should be considered a perpetual work in progress
78(E<lt>IMG SRC="yellow_sign.gif" ALT="Under Construction"E<gt>).
79
80
0a47030a
GS
81
82
e41182b5
GS
83=head1 ISSUES
84
85=head2 Newlines
86
87In most operating systems, lines in files are separated with newlines.
88Just what is used as a newline may vary from OS to OS. Unix
89traditionally uses C<\012>, one kind of Windows I/O uses C<\015\012>,
90and S<Mac OS> uses C<\015>.
91
92Perl uses C<\n> to represent the "logical" newline, where what
93is logical may depend on the platform in use. In MacPerl, C<\n>
94always means C<\015>. In DOSish perls, C<\n> usually means C<\012>, but
95when accessing a file in "text" mode, STDIO translates it to (or from)
96C<\015\012>.
97
98Due to the "text" mode translation, DOSish perls have limitations
99of using C<seek> and C<tell> when a file is being accessed in "text"
100mode. Specifically, if you stick to C<seek>-ing to locations you got
101from C<tell> (and no others), you are usually free to use C<seek> and
102C<tell> even in "text" mode. In general, using C<seek> or C<tell> or
103other file operations that count bytes instead of characters, without
104considering the length of C<\n>, may be non-portable. If you use
105C<binmode> on a file, however, you can usually use C<seek> and C<tell>
106with arbitrary values quite safely.
107
108A common misconception in socket programming is that C<\n> eq C<\012>
0a47030a 109everywhere. When using protocols such as common Internet protocols,
e41182b5
GS
110C<\012> and C<\015> are called for specifically, and the values of
111the logical C<\n> and C<\r> (carriage return) are not reliable.
112
113 print SOCKET "Hi there, client!\r\n"; # WRONG
114 print SOCKET "Hi there, client!\015\012"; # RIGHT
115
116[NOTE: this does not necessarily apply to communications that are
117filtered by another program or module before sending to the socket; the
118the most popular EBCDIC webserver, for instance, accepts C<\r\n>,
119which translates those characters, along with all other
120characters in text streams, from EBCDIC to ASCII.]
121
0a47030a
GS
122However, using C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious
123and unsightly, as well as confusing to those maintaining the code. As
124such, the C<Socket> module supplies the Right Thing for those who want it.
e41182b5
GS
125
126 use Socket qw(:DEFAULT :crlf);
127 print SOCKET "Hi there, client!$CRLF" # RIGHT
128
129When reading I<from> a socket, remember that the default input record
130separator (C<$/>) is C<\n>, but code like this should recognize C<$/> as
131C<\012> or C<\015\012>:
132
133 while (<SOCKET>) {
134 # ...
135 }
136
137Better:
138
139 use Socket qw(:DEFAULT :crlf);
140 local($/) = LF; # not needed if $/ is already \012
141
142 while (<SOCKET>) {
143 s/$CR?$LF/\n/; # not sure if socket uses LF or CRLF, OK
144 # s/\015?\012/\n/; # same thing
145 }
146
147And this example is actually better than the previous one even for Unix
148platforms, because now any C<\015>'s (C<\cM>'s) are stripped out
149(and there was much rejoicing).
150
151
dd9f0070 152=head2 Files
e41182b5
GS
153
154Most platforms these days structure files in a hierarchical fashion.
155So, it is reasonably safe to assume that any platform supports the
156notion of a "path" to uniquely identify a file on the system. Just
157how that path is actually written, differs.
158
159While they are similar, file path specifications differ between Unix,
0a47030a
GS
160Windows, S<Mac OS>, OS/2, VMS, S<RISC OS> and probably others. Unix, for
161example, is one of the few OSes that has the idea of a root directory.
162S<Mac OS> uses C<:> as a path separator instead of C</>. VMS, Windows,
163and OS/2 can work similarly to Unix with C</> as path separator, or in
164their own idiosyncratic ways. C<RISC OS> perl can emulate Unix filenames
165with C</> as path separator, or go native and use C<.> for path separator
166and C<:> to signal filing systems and disc names.
e41182b5
GS
167
168As with the newline problem above, there are modules that can help. The
169C<File::Spec> modules provide methods to do the Right Thing on whatever
170platform happens to be running the program.
171
172 use File::Spec;
173 chdir(File::Spec->updir()); # go up one directory
174 $file = File::Spec->catfile(
175 File::Spec->curdir(), 'temp', 'file.txt'
176 );
177 # on Unix and Win32, './temp/file.txt'
178 # on Mac OS, ':temp:file.txt'
179
180File::Spec is available in the standard distribution, as of version
1815.004_05.
182
183In general, production code should not have file paths hardcoded; making
184them user supplied or from a configuration file is better, keeping in mind
185that file path syntax varies on different machines.
186
187This is especially noticeable in scripts like Makefiles and test suites,
188which often assume C</> as a path separator for subdirectories.
189
190Also of use is C<File::Basename>, from the standard distribution, which
191splits a pathname into pieces (base filename, full path to directory,
192and file suffix).
193
194Remember not to count on the existence of system-specific files, like
195F</etc/resolv.conf>. If code does need to rely on such a file, include a
196description of the file and its format in the code's documentation, and
197make it easy for the user to override the default location of the file.
198
dd9f0070
CN
199Do not have two files of the same name with different case, like
200F<test.pl> and <Test.pl>, as many platforms have case-insensitive
201filenames. Also, try not to have non-word characters (except for C<.>)
0a47030a
GS
202in the names, and keep them to the 8.3 convention, for maximum
203portability.
dd9f0070
CN
204
205Likewise, if using C<AutoSplit>, try to keep the split functions to
2068.3 naming and case-insensitive conventions; or, at the very least,
207make it so the resulting files have a unique (case-insensitively)
208first 8 characters.
209
0a47030a
GS
210Don't assume C<E<lt>> won't be the first character of a filename. Always
211use C<E<gt>> explicitly to open a file for reading:
212
213 open(FILE, "<$existing_file") or die $!;
214
e41182b5
GS
215
216=head2 System Interaction
217
218Not all platforms provide for the notion of a command line, necessarily.
219These are usually platforms that rely on a Graphical User Interface (GUI)
220for user interaction. So a program requiring command lines might not work
221everywhere. But this is probably for the user of the program to deal
222with.
223
224Some platforms can't delete or rename files that are being held open by
225the system. Remember to C<close> files when you are done with them.
226Don't C<unlink> or C<rename> an open file. Don't C<tie> to or C<open> a
227file that is already tied to or opened; C<untie> or C<close> first.
228
0a47030a
GS
229Don't open the same file more than once at a time for writing, as some
230operating systems put mandatory locks on such files.
231
e41182b5 232Don't count on a specific environment variable existing in C<%ENV>.
0a47030a 233Don't count on C<%ENV> entries being case-sensitive, or even
e41182b5
GS
234case-preserving.
235
0a47030a 236Don't count on signals.
e41182b5
GS
237
238Don't count on filename globbing. Use C<opendir>, C<readdir>, and
239C<closedir> instead.
240
b8099c3d 241Don't count on per-program environment variables, or per-program current
dd9f0070 242directories.
b8099c3d 243
e41182b5
GS
244
245=head2 Interprocess Communication (IPC)
246
247In general, don't directly access the system in code that is meant to be
0a47030a
GS
248portable. That means, no C<system>, C<exec>, C<fork>, C<pipe>, C<``>,
249C<qx//>, C<open> with a C<|>, nor any of the other things that makes being
e41182b5
GS
250a Unix perl hacker worth being.
251
252Commands that launch external processes are generally supported on
253most platforms (though many of them do not support any type of forking),
254but the problem with using them arises from what you invoke with them.
255External tools are often named differently on different platforms, often
256not available in the same location, often accept different arguments,
257often behave differently, and often represent their results in a
258platform-dependent way. Thus you should seldom depend on them to produce
259consistent results.
260
261One especially common bit of Perl code is opening a pipe to sendmail:
262
263 open(MAIL, '|/usr/lib/sendmail -t') or die $!;
264
265This is fine for systems programming when sendmail is known to be
266available. But it is not fine for many non-Unix systems, and even
267some Unix systems that may not have sendmail installed. If a portable
268solution is needed, see the C<Mail::Send> and C<Mail::Mailer> modules
269in the C<MailTools> distribution. C<Mail::Mailer> provides several
270mailing methods, including mail, sendmail, and direct SMTP
271(via C<Net::SMTP>) if a mail transfer agent is not available.
272
273The rule of thumb for portable code is: Do it all in portable Perl, or
0a47030a
GS
274use a module (that may internally implement it with platform-specific
275code, but expose a common interface).
e41182b5
GS
276
277
278=head2 External Subroutines (XS)
279
280XS code, in general, can be made to work with any platform; but dependent
281libraries, header files, etc., might not be readily available or
282portable, or the XS code itself might be platform-specific, just as Perl
283code might be. If the libraries and headers are portable, then it is
284normally reasonable to make sure the XS code is portable, too.
285
286There is a different kind of portability issue with writing XS
0a47030a
GS
287code: availability of a C compiler on the end-user's system. C brings
288with it its own portability issues, and writing XS code will expose you to
e41182b5
GS
289some of those. Writing purely in perl is a comparatively easier way to
290achieve portability.
291
292
293=head2 Standard Modules
294
295In general, the standard modules work across platforms. Notable
296exceptions are C<CPAN.pm> (which currently makes connections to external
297programs that may not be available), platform-specific modules (like
298C<ExtUtils::MM_VMS>), and DBM modules.
299
300There is no one DBM module that is available on all platforms.
301C<SDBM_File> and the others are generally available on all Unix and DOSish
0a47030a
GS
302ports, but not in MacPerl, where only C<NBDM_File> and C<DB_File> are
303available.
e41182b5
GS
304
305The good news is that at least some DBM module should be available, and
306C<AnyDBM_File> will use whichever module it can find. Of course, then
307the code needs to be fairly strict, dropping to the lowest common
308denominator (e.g., not exceeding 1K for each record).
309
310
311=head2 Time and Date
312
0a47030a
GS
313The system's notion of time of day and calendar date is controlled in
314widely different ways. Don't assume the timezone is stored in C<$ENV{TZ}>,
315and even if it is, don't assume that you can control the timezone through
316that variable.
e41182b5
GS
317
318Don't assume that the epoch starts at January 1, 1970, because that is
319OS-specific. Better to store a date in an unambiguous representation.
320A text representation (like C<1 Jan 1970>) can be easily converted into an
321OS-specific value using a module like C<Date::Parse>. An array of values,
322such as those returned by C<localtime>, can be converted to an OS-specific
323representation using C<Time::Local>.
324
325
326=head2 System Resources
327
0a47030a
GS
328If your code is destined for systems with severely constrained (or
329missing!) virtual memory systems then you want to be I<especially> mindful
330of avoiding wasteful constructs such as:
e41182b5
GS
331
332 # NOTE: this is no longer "bad" in perl5.005
333 for (0..10000000) {} # bad
334 for (my $x = 0; $x <= 10000000; ++$x) {} # good
335
336 @lines = <VERY_LARGE_FILE>; # bad
337
338 while (<FILE>) {$file .= $_} # sometimes bad
0a47030a 339 $file = join('', <FILE>); # better
e41182b5
GS
340
341The last two may appear unintuitive to most people. The first of those
342two constructs repeatedly grows a string, while the second allocates a
343large chunk of memory in one go. On some systems, the latter is more
344efficient that the former.
345
0a47030a 346
e41182b5
GS
347=head2 Security
348
0a47030a
GS
349Most multi-user platforms provide basic levels of security that is usually
350felt at the file-system level. Other platforms usually don't
351(unfortunately). Thus the notion of user id, or "home" directory, or even
352the state of being logged-in, may be unrecognizable on many platforms. If
353you write programs that are security conscious, it is usually best to know
354what type of system you will be operating under, and write code explicitly
e41182b5
GS
355for that platform (or class of platforms).
356
0a47030a 357
e41182b5
GS
358=head2 Style
359
360For those times when it is necessary to have platform-specific code,
361consider keeping the platform-specific code in one place, making porting
362to other platforms easier. Use the C<Config> module and the special
0a47030a
GS
363variable C<$^O> to differentiate platforms, as described in
364L<"PLATFORMS">.
e41182b5
GS
365
366
0a47030a 367=head1 CPAN Testers
e41182b5 368
0a47030a
GS
369Modules uploaded to CPAN are tested by a variety of volunteers on
370different platforms. These CPAN testers are notified by mail of each
e41182b5 371new upload, and reply to the list with PASS, FAIL, NA (not applicable to
0a47030a 372this platform), or UNKNOWN (unknown), along with any relevant notations.
e41182b5
GS
373
374The purpose of the testing is twofold: one, to help developers fix any
0a47030a
GS
375problems in their code that crop up because of lack of testing on other
376platforms; two, to provide users with information about whether or not
377a given module works on a given platform.
e41182b5
GS
378
379=over 4
380
381=item Mailing list: cpan-testers@perl.org
382
383=item Testing results: C<http://www.connect.net/gbarr/cpan-test/>
384
385=back
386
387
388=head1 PLATFORMS
389
390As of version 5.002, Perl is built with a C<$^O> variable that
391indicates the operating system it was built on. This was implemented
392to help speed up code that would otherwise have to C<use Config;> and
393use the value of C<$Config{'osname'}>. Of course, to get
394detailed information about the system, looking into C<%Config> is
395certainly recommended.
396
397=head2 Unix
398
399Perl works on a bewildering variety of Unix and Unix-like platforms (see
400e.g. most of the files in the F<hints/> directory in the source code kit).
401On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>,
402too) is determined by lowercasing and stripping punctuation from the first
0a47030a
GS
403field of the string returned by typing C<uname -a> (or a similar command)
404at the shell prompt. Here, for example, are a few of the more popular
405Unix flavors:
e41182b5 406
f34d0673
GS
407 uname $^O $Config{'archname'}
408 -------------------------------------------
e41182b5
GS
409 AIX aix
410 FreeBSD freebsd
411 Linux linux
412 HP-UX hpux
413 OSF1 dec_osf
f34d0673
GS
414 SunOS solaris sun4-solaris
415 SunOS solaris i86pc-solaris
e41182b5
GS
416 SunOS4 sunos
417
418
419=head2 DOS and Derivatives
420
421Perl has long been ported to PC style microcomputers running under
422systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
423bring yourself to mention (except for Windows CE, if you count that).
424Users familiar with I<COMMAND.COM> and/or I<CMD.EXE> style shells should
425be aware that each of these file specifications may have subtle
426differences:
427
428 $filespec0 = "c:/foo/bar/file.txt";
429 $filespec1 = "c:\\foo\\bar\\file.txt";
430 $filespec2 = 'c:\foo\bar\file.txt';
431 $filespec3 = 'c:\\foo\\bar\\file.txt';
432
433System calls accept either C</> or C<\> as the path separator. However,
434many command-line utilities of DOS vintage treat C</> as the option
435prefix, so they may get confused by filenames containing C</>. Aside
436from calling any external programs, C</> will work just fine, and
437probably better, as it is more consistent with popular usage, and avoids
438the problem of remembering what to backwhack and what not to.
439
0a47030a 440The DOS FAT filesystem can only accommodate "8.3" style filenames. Under
e41182b5 441the "case insensitive, but case preserving" HPFS (OS/2) and NTFS (NT)
0a47030a 442filesystems you may have to be careful about case returned with functions
e41182b5
GS
443like C<readdir> or used with functions like C<open> or C<opendir>.
444
445DOS also treats several filenames as special, such as AUX, PRN, NUL, CON,
446COM1, LPT1, LPT2 etc. Unfortunately these filenames won't even work
447if you include an explicit directory prefix, in some cases. It is best
448to avoid such filenames, if you want your code to be portable to DOS
449and its derivatives.
450
451Users of these operating systems may also wish to make use of
452scripts such as I<pl2bat.bat> or I<pl2cmd> as appropriate to
453put wrappers around your scripts.
454
455Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from
456and writing to files. C<binmode(FILEHANDLE)> will keep C<\n> translated
457as C<\012> for that filehandle. Since it is a noop on other systems,
458C<binmode> should be used for cross-platform code that deals with binary
459data.
460
461The C<$^O> variable and the C<$Config{'archname'}> values for various
462DOSish perls are as follows:
463
464 OS $^O $Config{'archname'}
465 --------------------------------------------
466 MS-DOS dos
467 PC-DOS dos
468 OS/2 os2
469 Windows 95 MSWin32 MSWin32-x86
470 Windows NT MSWin32 MSWin32-x86
471 Windows NT MSWin32 MSWin32-alpha
472 Windows NT MSWin32 MSWin32-ppc
473
474Also see:
475
476=over 4
477
478=item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>
479
480=item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>,
481C<http://www.juge.com/bbs/Hobb.19.html>
482
483=item Build instructions for Win32, L<perlwin32>.
484
485=item The ActiveState Pages, C<http://www.activestate.com/>
486
487=back
488
489
dd9f0070 490=head2 S<Mac OS>
e41182b5
GS
491
492Any module requiring XS compilation is right out for most people, because
493MacPerl is built using non-free (and non-cheap!) compilers. Some XS
494modules that can work with MacPerl are built and distributed in binary
0a47030a
GS
495form on CPAN. See I<MacPerl: Power and Ease> and L<"CPAN Testers">
496for more details.
e41182b5
GS
497
498Directories are specified as:
499
500 volume:folder:file for absolute pathnames
501 volume:folder: for absolute pathnames
502 :folder:file for relative pathnames
503 :folder: for relative pathnames
504 :file for relative pathnames
505 file for relative pathnames
506
507Files in a directory are stored in alphabetical order. Filenames are
508limited to 31 characters, and may include any character except C<:>,
509which is reserved as a path separator.
510
0a47030a
GS
511Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the
512C<Mac::Files> module.
e41182b5
GS
513
514In the MacPerl application, you can't run a program from the command line;
515programs that expect C<@ARGV> to be populated can be edited with something
516like the following, which brings up a dialog box asking for the command
517line arguments.
518
519 if (!@ARGV) {
520 @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
521 }
522
523A MacPerl script saved as a droplet will populate C<@ARGV> with the full
524pathnames of the files dropped onto the script.
525
526Mac users can use programs on a kind of command line under MPW (Macintosh
527Programmer's Workshop, a free development environment from Apple).
528MacPerl was first introduced as an MPW tool, and MPW can be used like a
529shell:
530
531 perl myscript.plx some arguments
532
533ToolServer is another app from Apple that provides access to MPW tools
0a47030a 534from MPW and the MacPerl app, which allows MacPerl programs to use
e41182b5
GS
535C<system>, backticks, and piped C<open>.
536
537"S<Mac OS>" is the proper name for the operating system, but the value
538in C<$^O> is "MacOS". To determine architecture, version, or whether
539the application or MPW tool version is running, check:
540
541 $is_app = $MacPerl::Version =~ /App/;
542 $is_tool = $MacPerl::Version =~ /MPW/;
543 ($version) = $MacPerl::Version =~ /^(\S+)/;
544 $is_ppc = $MacPerl::Architecture eq 'MacPPC';
545 $is_68k = $MacPerl::Architecture eq 'Mac68K';
546
0a47030a
GS
547S<Mac OS X>, to be based on NeXT's OpenStep OS, will be able to run
548MacPerl natively (in the Blue Box, and even in the Yellow Box, once some
549changes to the toolbox calls are made), but Unix perl will also run
550natively.
e41182b5
GS
551
552Also see:
553
554=over 4
555
556=item The MacPerl Pages, C<http://www.ptf.com/macperl/>.
557
558=item The MacPerl mailing list, C<mac-perl-request@iis.ee.ethz.ch>.
559
560=back
561
562
563=head2 VMS
564
565Perl on VMS is discussed in F<vms/perlvms.pod> in the perl distribution.
0a47030a 566Note that perl on VMS can accept either VMS- or Unix-style file
e41182b5
GS
567specifications as in either of the following:
568
569 $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
570 $ perl -ne "print if /perl_setup/i" /sys$login/login.com
571
572but not a mixture of both as in:
573
574 $ perl -ne "print if /perl_setup/i" sys$login:/login.com
575 Can't open sys$login:/login.com: file specification syntax error
576
577Interacting with Perl from the Digital Command Language (DCL) shell
578often requires a different set of quotation marks than Unix shells do.
579For example:
580
581 $ perl -e "print ""Hello, world.\n"""
582 Hello, world.
583
584There are a number of ways to wrap your perl scripts in DCL .COM files if
585you are so inclined. For example:
586
587 $ write sys$output "Hello from DCL!"
588 $ if p1 .eqs. ""
589 $ then perl -x 'f$environment("PROCEDURE")
590 $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
591 $ deck/dollars="__END__"
592 #!/usr/bin/perl
593
594 print "Hello from Perl!\n";
595
596 __END__
597 $ endif
598
599Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
600perl-in-DCL script expects to do things like C<$read = E<lt>STDINE<gt>;>.
601
602Filenames are in the format "name.extension;version". The maximum
603length for filenames is 39 characters, and the maximum length for
604extensions is also 39 characters. Version is a number from 1 to
60532767. Valid characters are C</[A-Z0-9$_-]/>.
606
607VMS' RMS filesystem is case insensitive and does not preserve case.
608C<readdir> returns lowercased filenames, but specifying a file for
b8099c3d 609opening remains case insensitive. Files without extensions have a
e41182b5 610trailing period on them, so doing a C<readdir> with a file named F<A.;5>
0a47030a
GS
611will return F<a.> (though that file could be opened with
612C<open(FH, 'A')>).
e41182b5 613
f34d0673 614RMS had an eight level limit on directory depths from any rooted logical
dd9f0070
CN
615(allowing 16 levels overall) prior to VMS 7.2. Hence
616C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a valid directory specification but
617C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is not. F<Makefile.PL> authors might
618have to take this into account, but at least they can refer to the former
f34d0673 619as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
e41182b5 620
0a47030a
GS
621The C<VMS::Filespec> module, which gets installed as part of the build
622process on VMS, is a pure Perl module that can easily be installed on
623non-VMS platforms and can be helpful for conversions to and from RMS
624native formats.
e41182b5
GS
625
626What C<\n> represents depends on the type of file that is open. It could
627be C<\015>, C<\012>, C<\015\012>, or nothing. Reading from a file
628translates newlines to C<\012>, unless C<binmode> was executed on that
629handle, just like DOSish perls.
630
631TCP/IP stacks are optional on VMS, so socket routines might not be
632implemented. UDP sockets may not be supported.
633
634The value of C<$^O> on OpenVMS is "VMS". To determine the architecture
635that you are running on without resorting to loading all of C<%Config>
636you can examine the content of the C<@INC> array like so:
637
638 if (grep(/VMS_AXP/, @INC)) {
639 print "I'm on Alpha!\n";
640 } elsif (grep(/VMS_VAX/, @INC)) {
641 print "I'm on VAX!\n";
642 } else {
643 print "I'm not so sure about where $^O is...\n";
644 }
645
646Also see:
647
648=over 4
649
650=item L<perlvms.pod>
651
652=item vmsperl list, C<vmsperl-request@newman.upenn.edu>
653
654Put words C<SUBSCRIBE VMSPERL> in message body.
655
656=item vmsperl on the web, C<http://www.sidhe.org/vmsperl/index.html>
657
658=back
659
660
661=head2 EBCDIC Platforms
662
663Recent versions of Perl have been ported to platforms such as OS/400 on
664AS/400 minicomputers as well as OS/390 for IBM Mainframes. Such computers
665use EBCDIC character sets internally (usually Character Code Set ID 00819
666for OS/400 and IBM-1047 for OS/390). Note that on the mainframe perl
667currently works under the "Unix system services for OS/390" (formerly
668known as OpenEdition).
669
670As of R2.5 of USS for OS/390 that Unix sub-system did not support the
671C<#!> shebang trick for script invocation. Hence, on OS/390 perl scripts
672can executed with a header similar to the following simple script:
673
674 : # use perl
675 eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
676 if 0;
677 #!/usr/local/bin/perl # just a comment really
678
679 print "Hello from perl!\n";
680
681On these platforms, bear in mind that the EBCDIC character set may have
0a47030a
GS
682an effect on what happens with some perl functions (such as C<chr>,
683C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as
684well as bit-fiddling with ASCII constants using operators like C<^>, C<&>
685and C<|>, not to mention dealing with socket interfaces to ASCII computers
e41182b5
GS
686(see L<"NEWLINES">).
687
688Fortunately, most web servers for the mainframe will correctly translate
689the C<\n> in the following statement to its ASCII equivalent (note that
0a47030a 690C<\r> is the same under both Unix and OS/390):
e41182b5
GS
691
692 print "Content-type: text/html\r\n\r\n";
693
694The value of C<$^O> on OS/390 is "os390".
695
696Some simple tricks for determining if you are running on an EBCDIC
697platform could include any of the following (perhaps all):
698
699 if ("\t" eq "\05") { print "EBCDIC may be spoken here!\n"; }
700
701 if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
702
703 if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
704
705Note that one thing you may not want to rely on is the EBCDIC encoding
0a47030a
GS
706of punctuation characters since these may differ from code page to code
707page (and once your module or script is rumoured to work with EBCDIC,
708folks will want it to work with all EBCDIC character sets).
e41182b5
GS
709
710Also see:
711
712=over 4
713
714=item perl-mvs list
715
716The perl-mvs@perl.org list is for discussion of porting issues as well as
717general usage issues for all EBCDIC Perls. Send a message body of
718"subscribe perl-mvs" to majordomo@perl.org.
719
0a47030a 720=item AS/400 Perl information at C<http://as400.rochester.ibm.com/>
e41182b5
GS
721
722=back
723
b8099c3d
CN
724
725=head2 Acorn RISC OS
726
0a47030a
GS
727As Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like
728Unix and Unix filename emulation is turned on by default, it is quite
729likely that most simple scripts will work "out of the box". The native
730filing system is modular, and individual filing systems are free to be
731case-sensitive or insensitive, and are usually case-preserving. Some
732native filing systems have name length limits which file and directory
733names are silently truncated to fit - scripts should be aware that the
734standard disc filing system currently has a name length limit of B<10>
735characters, with up to 77 items in a directory, but other filing systems
736may not impose such limitations.
b8099c3d
CN
737
738Native filenames are of the form
739
740 Filesystem#Special_Field::DiscName.$.Directory.Directory.File
dd9f0070 741
b8099c3d
CN
742where
743
744 Special_Field is not usually present, but may contain . and $ .
745 Filesystem =~ m|[A-Za-z0-9_]|
746 DsicName =~ m|[A-Za-z0-9_/]|
747 $ represents the root directory
748 . is the path separator
749 @ is the current directory (per filesystem but machine global)
750 ^ is the parent directory
751 Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|
752
753The default filename translation is roughly C<tr|/.|./|;>
754
755Note that C<"ADFS::HardDisc.$.File" ne 'ADFS::HardDisc.$.File'> and that
0a47030a
GS
756the second stage of C<$> interpolation in regular expressions will fall
757foul of the C<$.> if scripts are not careful.
758
759Logical paths specified by system variables containing comma-separated
760search lists are also allowed, hence C<System:Modules> is a valid
761filename, and the filesystem will prefix C<Modules> with each section of
762C<System$Path> until a name is made that points to an object on disc.
763Writing to a new file C<System:Modules> would only be allowed if
764C<System$Path> contains a single item list. The filesystem will also
765expand system variables in filenames if enclosed in angle brackets, so
766C<E<lt>System$DirE<gt>.Modules> would look for the file
767S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is
768that B<fully qualified filenames can start with C<E<lt>E<gt>> and should
769be protected when C<open> is used for input.
b8099c3d
CN
770
771Because C<.> was in use as a directory separator and filenames could not
772be assumed to be unique after 10 characters, Acorn implemented the C
773compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from
774filenames specified in source code and store the respective files in
775subdirectories named after the suffix. Hence files are translated:
776
777 foo.h h.foo
778 C:foo.h C:h.foo (logical path variable)
779 sys/os.h sys.h.os (C compiler groks Unix-speak)
780 10charname.c c.10charname
781 10charname.o o.10charname
782 11charname_.c c.11charname (assuming filesystem truncates at 10)
783
784The Unix emulation library's translation of filenames to native assumes
0a47030a
GS
785that this sort of translation is required, and allows a user defined list
786of known suffixes which it will transpose in this fashion. This may
787appear transparent, but consider that with these rules C<foo/bar/baz.h>
788and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
789C<glob> cannot and do not attempt to emulate the reverse mapping. Other
790C<.>s in filenames are translated to C</>.
791
792As implied above the environment accessed through C<%ENV> is global, and
793the convention is that program specific environment variables are of the
794form C<Program$Name>. Each filing system maintains a current directory,
795and the current filing system's current directory is the B<global> current
796directory. Consequently, sociable scripts don't change the current
797directory but rely on full pathnames, and scripts (and Makefiles) cannot
798assume that they can spawn a child process which can change the current
799directory without affecting its parent (and everyone else for that
800matter).
801
802As native operating system filehandles are global and currently are
803allocated down from 255, with 0 being a reserved value the Unix emulation
804library emulates Unix filehandles. Consequently, you can't rely on
805passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
806
807The desire of users to express filenames of the form
808C<E<lt>Foo$DirE<gt>.Bar> on the command line unquoted causes problems,
809too: C<``> command output capture has to perform a guessing game. It
810assumes that a string C<E<lt>[^E<lt>E<gt>]+\$[^E<lt>E<gt>]E<gt>> is a
811reference to an environment variable, whereas anything else involving
812C<E<lt>> or C<E<gt>> is redirection, and generally manages to be 99%
813right. Of course, the problem remains that scripts cannot rely on any
814Unix tools being available, or that any tools found have Unix-like command
815line arguments.
816
817Extensions and XS are, in theory, buildable by anyone using free tools.
818In practice, many don't, as users of the Acorn platform are used to binary
819distribution. MakeMaker does run, but no available make currently copes
820with MakeMaker's makefiles; even if/when this is fixed, the lack of a
821Unix-like shell can cause problems with makefile rules, especially lines
822of the form C<cd sdbm && make all>, and anything using quoting.
b8099c3d
CN
823
824"S<RISC OS>" is the proper name for the operating system, but the value
825in C<$^O> is "riscos" (because we don't like shouting).
826
827Also see:
828
829=over 4
830
831=item perl list
832
833=back
834
835
e41182b5
GS
836=head2 Other perls
837
b8099c3d
CN
838Perl has been ported to a variety of platforms that do not fit into any of
839the above categories. Some, such as AmigaOS, BeOS, QNX, and Plan 9, have
0a47030a 840been well-integrated into the standard Perl source code kit. You may need
b8099c3d 841to see the F<ports/> directory on CPAN for information, and possibly
0a47030a
GS
842binaries, for the likes of: aos, atari, lynxos, riscos, Tandem Guardian,
843vos, I<etc.> (yes we know that some of these OSes may fall under the Unix
844category, but we are not a standards body.)
e41182b5
GS
845
846See also:
847
848=over 4
849
850=item Atari, Guido Flohr's page C<http://stud.uni-sb.de/~gufl0000/>
851
852=item HP 300 MPE/iX C<http://www.cccd.edu/~markb/perlix.html>
853
854=item Novell Netware
855
0a47030a 856A free perl5-based PERL.NLM for Novell Netware is available from
e41182b5
GS
857C<http://www.novell.com/>
858
859=back
860
861
862=head1 FUNCTION IMPLEMENTATIONS
863
864Listed below are functions unimplemented or implemented differently on
865various platforms. Following each description will be, in parentheses, a
866list of platforms that the description applies to.
867
868The list may very well be incomplete, or wrong in some places. When in
869doubt, consult the platform-specific README files in the Perl source
870distribution, and other documentation resources for a given port.
871
0a47030a 872Be aware, moreover, that even among Unix-ish systems there are variations.
e41182b5
GS
873
874For many functions, you can also query C<%Config>, exported by default
875from C<Config.pm>. For example, to check if the platform has the C<lstat>
0a47030a
GS
876call, check C<$Config{'d_lstat'}>. See L<Config.pm> for a full
877description of available variables.
e41182b5
GS
878
879
880=head2 Alphabetical Listing of Perl Functions
881
882=over 8
883
884=item -X FILEHANDLE
885
886=item -X EXPR
887
888=item -X
889
890C<-r>, C<-w>, and C<-x> have only a very limited meaning; directories
891and applications are executable, and there are no uid/gid
892considerations. C<-o> is not supported. (S<Mac OS>)
893
894C<-r>, C<-w>, C<-x>, and C<-o> tell whether or not file is accessible,
895which may not reflect UIC-based file protections. (VMS)
896
b8099c3d
CN
897C<-s> returns the size of the data fork, not the total size of data fork
898plus resource fork. (S<Mac OS>).
899
900C<-s> by name on an open file will return the space reserved on disk,
901rather than the current extent. C<-s> on an open filehandle returns the
902current size. (S<RISC OS>)
903
e41182b5 904C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>,
b8099c3d 905C<-x>, C<-o>. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
906
907C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented.
908(S<Mac OS>)
909
910C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful.
b8099c3d 911(Win32, VMS, S<RISC OS>)
e41182b5
GS
912
913C<-d> is true if passed a device spec without an explicit directory.
914(VMS)
915
916C<-T> and C<-B> are implemented, but might misclassify Mac text files
0a47030a
GS
917with foreign characters; this is the case will all platforms, but may
918affect S<Mac OS> often. (S<Mac OS>)
e41182b5
GS
919
920C<-x> (or C<-X>) determine if a file ends in one of the executable
921suffixes. C<-S> is meaningless. (Win32)
922
b8099c3d
CN
923C<-x> (or C<-X>) determine if a file has an executable file type.
924(S<RISC OS>)
925
e41182b5
GS
926=item binmode FILEHANDLE
927
b8099c3d 928Meaningless. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
929
930Reopens file and restores pointer; if function fails, underlying
931filehandle may be closed, or pointer may be in a different position.
932(VMS)
933
934The value returned by C<tell> may be affected after the call, and
935the filehandle may be flushed. (Win32)
936
937=item chmod LIST
938
939Only limited meaning. Disabling/enabling write permission is mapped to
940locking/unlocking the file. (S<Mac OS>)
941
942Only good for changing "owner" read-write access, "group", and "other"
943bits are meaningless. (Win32)
944
b8099c3d
CN
945Only good for changing "owner" and "other" read-write access. (S<RISC OS>)
946
e41182b5
GS
947=item chown LIST
948
b8099c3d 949Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
950
951Does nothing, but won't fail. (Win32)
952
953=item chroot FILENAME
954
955=item chroot
956
b8099c3d 957Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>)
e41182b5
GS
958
959=item crypt PLAINTEXT,SALT
960
961May not be available if library or source was not provided when building
b8099c3d 962perl. (Win32)
e41182b5
GS
963
964=item dbmclose HASH
965
966Not implemented. (VMS, Plan9)
967
968=item dbmopen HASH,DBNAME,MODE
969
970Not implemented. (VMS, Plan9)
971
972=item dump LABEL
973
b8099c3d 974Not useful. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
975
976Not implemented. (Win32)
977
b8099c3d 978Invokes VMS debugger. (VMS)
e41182b5
GS
979
980=item exec LIST
981
982Not implemented. (S<Mac OS>)
983
984=item fcntl FILEHANDLE,FUNCTION,SCALAR
985
986Not implemented. (Win32, VMS)
987
988=item flock FILEHANDLE,OPERATION
989
b8099c3d 990Not implemented (S<Mac OS>, VMS, S<RISC OS>).
e41182b5
GS
991
992Available only on Windows NT (not on Windows 95). (Win32)
993
994=item fork
995
b8099c3d 996Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>)
e41182b5
GS
997
998=item getlogin
999
b8099c3d 1000Not implemented. (S<Mac OS>, S<RISC OS>)
e41182b5
GS
1001
1002=item getpgrp PID
1003
b8099c3d 1004Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1005
1006=item getppid
1007
b8099c3d 1008Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1009
1010=item getpriority WHICH,WHO
1011
b8099c3d 1012Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1013
1014=item getpwnam NAME
1015
1016Not implemented. (S<Mac OS>, Win32)
1017
b8099c3d
CN
1018Not useful. (S<RISC OS>)
1019
e41182b5
GS
1020=item getgrnam NAME
1021
b8099c3d 1022Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1023
1024=item getnetbyname NAME
1025
1026Not implemented. (S<Mac OS>, Win32, Plan9)
1027
1028=item getpwuid UID
1029
1030Not implemented. (S<Mac OS>, Win32)
1031
b8099c3d
CN
1032Not useful. (S<RISC OS>)
1033
e41182b5
GS
1034=item getgrgid GID
1035
b8099c3d 1036Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1037
1038=item getnetbyaddr ADDR,ADDRTYPE
1039
1040Not implemented. (S<Mac OS>, Win32, Plan9)
1041
1042=item getprotobynumber NUMBER
1043
1044Not implemented. (S<Mac OS>)
1045
1046=item getservbyport PORT,PROTO
1047
1048Not implemented. (S<Mac OS>)
1049
1050=item getpwent
1051
1052Not implemented. (S<Mac OS>, Win32)
1053
1054=item getgrent
1055
1056Not implemented. (S<Mac OS>, Win32, VMS)
1057
1058=item gethostent
1059
1060Not implemented. (S<Mac OS>, Win32)
1061
1062=item getnetent
1063
1064Not implemented. (S<Mac OS>, Win32, Plan9)
1065
1066=item getprotoent
1067
1068Not implemented. (S<Mac OS>, Win32, Plan9)
1069
1070=item getservent
1071
1072Not implemented. (Win32, Plan9)
1073
1074=item setpwent
1075
b8099c3d 1076Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1077
1078=item setgrent
1079
b8099c3d 1080Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1081
1082=item sethostent STAYOPEN
1083
b8099c3d 1084Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1085
1086=item setnetent STAYOPEN
1087
b8099c3d 1088Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1089
1090=item setprotoent STAYOPEN
1091
b8099c3d 1092Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
e41182b5
GS
1093
1094=item setservent STAYOPEN
1095
b8099c3d 1096Not implemented. (Plan9, Win32, S<RISC OS>)
e41182b5
GS
1097
1098=item endpwent
1099
1100Not implemented. (S<Mac OS>, Win32)
1101
1102=item endgrent
1103
b8099c3d 1104Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1105
1106=item endhostent
1107
1108Not implemented. (S<Mac OS>, Win32)
1109
1110=item endnetent
1111
1112Not implemented. (S<Mac OS>, Win32, Plan9)
1113
1114=item endprotoent
1115
1116Not implemented. (S<Mac OS>, Win32, Plan9)
1117
1118=item endservent
1119
1120Not implemented. (Plan9, Win32)
1121
1122=item getsockopt SOCKET,LEVEL,OPTNAME
1123
1124Not implemented. (S<Mac OS>, Plan9)
1125
1126=item glob EXPR
1127
1128=item glob
1129
1130Globbing built-in, but only C<*> and C<?> metacharacters are supported.
1131(S<Mac OS>)
1132
0a47030a
GS
1133Features depend on external perlglob.exe or perlglob.bat. May be
1134overridden with something like File::DosGlob, which is recommended.
1135(Win32)
e41182b5 1136
b8099c3d 1137Globbing built-in, but only C<*> and C<?> metacharacters are supported.
0a47030a
GS
1138Globbing relies on operating system calls, which may return filenames
1139in any order. As most filesystems are case-insensitive, even "sorted"
1140filenames will not be in case-sensitive order. (S<RISC OS>)
b8099c3d 1141
e41182b5
GS
1142=item ioctl FILEHANDLE,FUNCTION,SCALAR
1143
1144Not implemented. (VMS)
1145
1146Available only for socket handles, and it does what the ioctlsocket() call
1147in the Winsock API does. (Win32)
1148
b8099c3d
CN
1149Available only for socket handles. (S<RISC OS>)
1150
e41182b5
GS
1151=item kill LIST
1152
0a47030a
GS
1153Not implemented, hence not useful for taint checking. (S<Mac OS>,
1154S<RISC OS>)
e41182b5 1155
0a47030a
GS
1156Available only for process handles returned by the C<system(1, ...)>
1157method of spawning a process. (Win32)
e41182b5
GS
1158
1159=item link OLDFILE,NEWFILE
1160
b8099c3d 1161Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1162
1163=item lstat FILEHANDLE
1164
1165=item lstat EXPR
1166
1167=item lstat
1168
b8099c3d 1169Not implemented. (VMS, S<RISC OS>)
e41182b5 1170
b8099c3d 1171Return values may be bogus. (Win32)
e41182b5
GS
1172
1173=item msgctl ID,CMD,ARG
1174
1175=item msgget KEY,FLAGS
1176
1177=item msgsnd ID,MSG,FLAGS
1178
1179=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1180
b8099c3d 1181Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>)
e41182b5
GS
1182
1183=item open FILEHANDLE,EXPR
1184
1185=item open FILEHANDLE
1186
1187The C<|> variants are only supported if ToolServer is installed.
1188(S<Mac OS>)
1189
b8099c3d 1190open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
e41182b5
GS
1191
1192=item pipe READHANDLE,WRITEHANDLE
1193
1194Not implemented. (S<Mac OS>)
1195
1196=item readlink EXPR
1197
1198=item readlink
1199
b8099c3d 1200Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1201
1202=item select RBITS,WBITS,EBITS,TIMEOUT
1203
1204Only implemented on sockets. (Win32)
1205
b8099c3d
CN
1206Only reliable on sockets. (S<RISC OS>)
1207
e41182b5
GS
1208=item semctl ID,SEMNUM,CMD,ARG
1209
1210=item semget KEY,NSEMS,FLAGS
1211
1212=item semop KEY,OPSTRING
1213
b8099c3d 1214Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1215
1216=item setpgrp PID,PGRP
1217
b8099c3d 1218Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1219
1220=item setpriority WHICH,WHO,PRIORITY
1221
b8099c3d 1222Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1223
1224=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1225
1226Not implemented. (S<Mac OS>, Plan9)
1227
1228=item shmctl ID,CMD,ARG
1229
1230=item shmget KEY,SIZE,FLAGS
1231
1232=item shmread ID,VAR,POS,SIZE
1233
1234=item shmwrite ID,STRING,POS,SIZE
1235
b8099c3d 1236Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1237
1238=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1239
b8099c3d 1240Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5
GS
1241
1242=item stat FILEHANDLE
1243
1244=item stat EXPR
1245
1246=item stat
1247
1248mtime and atime are the same thing, and ctime is creation time instead of
1249inode change time. (S<Mac OS>)
1250
1251device and inode are not meaningful. (Win32)
1252
1253device and inode are not necessarily reliable. (VMS)
1254
b8099c3d
CN
1255mtime, atime and ctime all return the last modification time. Device and
1256inode are not necessarily reliable. (S<RISC OS>)
1257
e41182b5
GS
1258=item symlink OLDFILE,NEWFILE
1259
b8099c3d 1260Not implemented. (Win32, VMS, S<RISC OS>)
e41182b5
GS
1261
1262=item syscall LIST
1263
b8099c3d 1264Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
e41182b5 1265
f34d0673
GS
1266=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1267
dd9f0070 1268The traditional "0", "1", and "2" MODEs are implemented with different
0a47030a
GS
1269numeric values on some systems. The flags exported by C<Fcntl> should
1270work everywhere though. (S<Mac OS>, OS/390)
f34d0673 1271
e41182b5
GS
1272=item system LIST
1273
1274Only implemented if ToolServer is installed. (S<Mac OS>)
1275
1276As an optimization, may not call the command shell specified in
1277C<$ENV{PERL5SHELL}>. C<system(1, @args)> spawns an external
1278process and immediately returns its process designator, without
1279waiting for it to terminate. Return value may be used subsequently
1280in C<wait> or C<waitpid>. (Win32)
1281
b8099c3d
CN
1282There is no shell to process metacharacters, and the native standard is
1283to pass a command line terminated by "\n" "\r" or "\0" to the spawned
1284program. Redirection such as C<E<gt> foo> is performed (if at all) by
1285the run time library of the spawned program. C<system> I<list> will call
1286the Unix emulation library's C<exec> emulation, which attempts to provide
1287emulation of the stdin, stdout, stderr in force in the parent, providing
1288the child program uses a compatible version of the emulation library.
1289I<scalar> will call the native command line direct and no such emulation
1290of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>)
1291
e41182b5
GS
1292=item times
1293
1294Only the first entry returned is nonzero. (S<Mac OS>)
1295
1296"cumulative" times will be bogus. On anything other than Windows NT,
1297"system" time will be bogus, and "user" time is actually the time
1298returned by the clock() function in the C runtime library. (Win32)
1299
b8099c3d
CN
1300Not useful. (S<RISC OS>)
1301
e41182b5
GS
1302=item truncate FILEHANDLE,LENGTH
1303
1304=item truncate EXPR,LENGTH
1305
1306Not implemented. (VMS)
1307
1308=item umask EXPR
1309
1310=item umask
1311
1312Returns undef where unavailable, as of version 5.005.
1313
1314=item utime LIST
1315
b8099c3d 1316Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
e41182b5
GS
1317
1318May not behave as expected. (Win32)
1319
1320=item wait
1321
1322=item waitpid PID,FLAGS
1323
1324Not implemented. (S<Mac OS>)
1325
1326Can only be applied to process handles returned for processes spawned
1327using C<system(1, ...)>. (Win32)
1328
b8099c3d
CN
1329Not useful. (S<RISC OS>)
1330
e41182b5
GS
1331=back
1332
b8099c3d
CN
1333=head1 CHANGES
1334
1335=over 4
1336
0a47030a
GS
1337=item 1.33, 06 August 1998
1338
1339Integrate more minor changes.
1340
dd9f0070
CN
1341=item 1.32, 05 August 1998
1342
1343Integrate more minor changes.
1344
b8099c3d
CN
1345=item 1.30, 03 August 1998
1346
1347Major update for RISC OS, other minor changes.
1348
1349=item 1.23, 10 July 1998
1350
1351First public release with perl5.005.
1352
1353=back
e41182b5
GS
1354
1355=head1 AUTHORS / CONTRIBUTORS
1356
dd9f0070
CN
1357Abigail E<lt>abigail@fnx.comE<gt>,
1358Charles Bailey E<lt>bailey@genetics.upenn.eduE<gt>,
1359Graham Barr E<lt>gbarr@pobox.comE<gt>,
e41182b5 1360Tom Christiansen E<lt>tchrist@perl.comE<gt>,
dd9f0070
CN
1361Nicholas Clark E<lt>Nicholas.Clark@liverpool.ac.ukE<gt>,
1362Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>,
1363Dominic Dunlop E<lt>domo@vo.luE<gt>,
1364M.J.T. Guy E<lt>mjtg@cus.cam.ac.ukE<gt>,
1365Luther Huffman E<lt>lutherh@stratcom.comE<gt>,
1366Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>,
1367Andreas J. Koenig E<lt>koenig@kulturbox.deE<gt>,
1368Andrew M. Langmead E<lt>aml@world.std.comE<gt>,
e41182b5 1369Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>,
dd9f0070 1370Chris Nandor E<lt>pudge@pobox.comE<gt>,
e41182b5 1371Matthias Neercher E<lt>neeri@iis.ee.ethz.chE<gt>,
e41182b5 1372Gary Ng E<lt>71564.1743@CompuServe.COME<gt>,
e41182b5 1373Tom Phoenix E<lt>rootbeer@teleport.comE<gt>,
dd9f0070 1374Peter Prymmer E<lt>pvhp@forte.comE<gt>,
e41182b5 1375Hugo van der Sanden E<lt>h.sanden@elsevier.nlE<gt>,
dd9f0070
CN
1376Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>,
1377Paul J. Schinder E<lt>schinder@pobox.comE<gt>,
e41182b5 1378Dan Sugalski E<lt>sugalskd@ous.eduE<gt>,
dd9f0070 1379Nathan Torkington E<lt>gnat@frii.comE<gt>.
e41182b5
GS
1380
1381This document is maintained by Chris Nandor.
1382
1383=head1 VERSION
1384
0a47030a
GS
1385Version 1.33, last modified 06 August 1998.
1386
e41182b5 1387