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