From: Gurusamy Sarathy Date: Sat, 11 Jul 1998 00:25:17 +0000 (+0000) Subject: add perlport.pod v1.23 from Chris Nandor X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e41182b575eaa0023db9380ce3ad8398f8ffe918;p=p5sagit%2Fp5-mst-13.2.git add perlport.pod v1.23 from Chris Nandor p4raw-id: //depot/perl@1412 --- diff --git a/pod/perl.pod b/pod/perl.pod index 4c9808f..1924d46 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -49,6 +49,7 @@ of sections: perldiag Perl diagnostic messages perlsec Perl security perltrap Perl traps for the unwary + perlport Perl portability guide perlstyle Perl style guide perlpod Perl plain old documentation diff --git a/pod/perlport.pod b/pod/perlport.pod new file mode 100644 index 0000000..8365468 --- /dev/null +++ b/pod/perlport.pod @@ -0,0 +1,1160 @@ +=head1 NAME + +perlport - Writing portable Perl + + +=head1 DESCRIPTION + +Perl runs on a variety of operating systems. While most of them share +a lot in common, they also have their own very particular and unique +features. + +This document is meant to help you to find out what constitutes portable +perl code, so that once you have made your decision to write portably, +you know where the lines are drawn, and you can stay within them. + +There is a tradeoff between taking full advantage of B particular type +of computer, and taking advantage of a full B of them. Naturally, +as you make your range bigger (and thus more diverse), the common denominators +drop, and you are left with fewer areas of common ground in which +you can operate to accomplish a particular task. Thus, when you begin +attacking a problem, it is important to consider which part of the tradeoff +curve you want to operate under. Specifically, whether it is important to +you that the task that you are coding needs the full generality of being +portable, or if it is sufficient to just get the job done. This is the +hardest choice to be made. The rest is easy, because Perl provides lots +of choices, whichever way you want to approach your problem. + +Looking at it another way, writing portable code is usually about willfully +limiting your available choices. Naturally, it takes discipline to do that. + +Be aware of two important points: + +=over 4 + +=item Not all Perl programs have to be portable + +There is no reason why you should not use Perl as a language to glue Unix +tools together, or to prototype a Macintosh application, or to manage the +Windows registry. If it makes no sense to aim for portability for one +reason or another in a given program, then don't bother. + +=item The vast majority of Perl B portable + +Don't be fooled into thinking that it is hard to create portable Perl +code. It isn't. Perl tries its level-best to bridge the gaps between +what's available on different platforms, and all the means available to +use those features. Thus almost all Perl code runs on any machine +without modification. But there I some significant issues in +writing portable code, and this document is entirely about those issues. + +=back + +Here's the general rule: When you approach a task that is commonly done +using a whole range of platforms, think in terms of writing portable +code. That way, you don't sacrifice much by way of the implementation +choices you can avail yourself of, and at the same time you can give +your users lots of platform choices. On the other hand, when you have to +take advantage of some unique feature of a particular platform, as is +often the case with systems programming (whether for Unix, Windows, +S, VMS, etc.), consider writing platform-specific code. + +When the code will run on only two or three operating systems, then you may +only need to consider the differences of those particular systems. The +important thing is to decide where the code will run, and to be deliberate +in your decision. + +This information should not be considered complete; it includes possibly +transient information about idiosyncracies of some of the ports, almost +all of which are in a state of constant evolution. Thus this material +should be considered a perpetual work in progress +(EIMG SRC="yellow_sign.gif" ALT="Under Construction"E). + + +=head1 ISSUES + +=head2 Newlines + +In most operating systems, lines in files are separated with newlines. +Just what is used as a newline may vary from OS to OS. Unix +traditionally uses C<\012>, one kind of Windows I/O uses C<\015\012>, +and S uses C<\015>. + +Perl uses C<\n> to represent the "logical" newline, where what +is logical may depend on the platform in use. In MacPerl, C<\n> +always means C<\015>. In DOSish perls, C<\n> usually means C<\012>, but +when accessing a file in "text" mode, STDIO translates it to (or from) +C<\015\012>. + +Due to the "text" mode translation, DOSish perls have limitations +of using C and C when a file is being accessed in "text" +mode. Specifically, if you stick to C-ing to locations you got +from C (and no others), you are usually free to use C and +C even in "text" mode. In general, using C or C or +other file operations that count bytes instead of characters, without +considering the length of C<\n>, may be non-portable. If you use +C on a file, however, you can usually use C and C +with arbitrary values quite safely. + +A common misconception in socket programming is that C<\n> eq C<\012> +everywhere. When using protocols, such as common Internet protocols, +C<\012> and C<\015> are called for specifically, and the values of +the logical C<\n> and C<\r> (carriage return) are not reliable. + + print SOCKET "Hi there, client!\r\n"; # WRONG + print SOCKET "Hi there, client!\015\012"; # RIGHT + +[NOTE: this does not necessarily apply to communications that are +filtered by another program or module before sending to the socket; the +the most popular EBCDIC webserver, for instance, accepts C<\r\n>, +which translates those characters, along with all other +characters in text streams, from EBCDIC to ASCII.] + +However, C<\015\012> (or C<\cM\cJ>, or C<\x0D\x0A>) can be tedious and +unsightly, as well as confusing to those maintaining the code. As such, +the C module supplies the Right Thing for those who want it. + + use Socket qw(:DEFAULT :crlf); + print SOCKET "Hi there, client!$CRLF" # RIGHT + +When reading I a socket, remember that the default input record +separator (C<$/>) is C<\n>, but code like this should recognize C<$/> as +C<\012> or C<\015\012>: + + while () { + # ... + } + +Better: + + use Socket qw(:DEFAULT :crlf); + local($/) = LF; # not needed if $/ is already \012 + + while () { + s/$CR?$LF/\n/; # not sure if socket uses LF or CRLF, OK + # s/\015?\012/\n/; # same thing + } + +And this example is actually better than the previous one even for Unix +platforms, because now any C<\015>'s (C<\cM>'s) are stripped out +(and there was much rejoicing). + + +=head2 File Paths + +Most platforms these days structure files in a hierarchical fashion. +So, it is reasonably safe to assume that any platform supports the +notion of a "path" to uniquely identify a file on the system. Just +how that path is actually written, differs. + +While they are similar, file path specifications differ between Unix, +Windows, S, OS/2, VMS and probably others. Unix, for example, is +one of the few OSes that has the idea of a root directory. S +uses C<:> as a path separator instead of C. VMS, Windows, and OS/2 +can work similarly to Unix with C as path separator, or in their own +idiosyncratic ways. + +As with the newline problem above, there are modules that can help. The +C modules provide methods to do the Right Thing on whatever +platform happens to be running the program. + + use File::Spec; + chdir(File::Spec->updir()); # go up one directory + $file = File::Spec->catfile( + File::Spec->curdir(), 'temp', 'file.txt' + ); + # on Unix and Win32, './temp/file.txt' + # on Mac OS, ':temp:file.txt' + +File::Spec is available in the standard distribution, as of version +5.004_05. + +In general, production code should not have file paths hardcoded; making +them user supplied or from a configuration file is better, keeping in mind +that file path syntax varies on different machines. + +This is especially noticeable in scripts like Makefiles and test suites, +which often assume C as a path separator for subdirectories. + +Also of use is C, from the standard distribution, which +splits a pathname into pieces (base filename, full path to directory, +and file suffix). + +Remember not to count on the existence of system-specific files, like +F. If code does need to rely on such a file, include a +description of the file and its format in the code's documentation, and +make it easy for the user to override the default location of the file. + + +=head2 System Interaction + +Not all platforms provide for the notion of a command line, necessarily. +These are usually platforms that rely on a Graphical User Interface (GUI) +for user interaction. So a program requiring command lines might not work +everywhere. But this is probably for the user of the program to deal +with. + +Some platforms can't delete or rename files that are being held open by +the system. Remember to C files when you are done with them. +Don't C or C an open file. Don't C to or C a +file that is already tied to or opened; C or C first. + +Don't count on a specific environment variable existing in C<%ENV>. +Don't even count on C<%ENV> entries being case-sensitive, or even +case-preserving. + +Don't count on signals in portable programs. + +Don't count on filename globbing. Use C, C, and +C instead. + + +=head2 Interprocess Communication (IPC) + +In general, don't directly access the system in code that is meant to be +portable. That means, no: C, C, C, C, C<``>, +C, C with a C<|>, or any of the other things that makes being +a Unix perl hacker worth being. + +Commands that launch external processes are generally supported on +most platforms (though many of them do not support any type of forking), +but the problem with using them arises from what you invoke with them. +External tools are often named differently on different platforms, often +not available in the same location, often accept different arguments, +often behave differently, and often represent their results in a +platform-dependent way. Thus you should seldom depend on them to produce +consistent results. + +One especially common bit of Perl code is opening a pipe to sendmail: + + open(MAIL, '|/usr/lib/sendmail -t') or die $!; + +This is fine for systems programming when sendmail is known to be +available. But it is not fine for many non-Unix systems, and even +some Unix systems that may not have sendmail installed. If a portable +solution is needed, see the C and C modules +in the C distribution. C provides several +mailing methods, including mail, sendmail, and direct SMTP +(via C) if a mail transfer agent is not available. + +The rule of thumb for portable code is: Do it all in portable Perl, or +use a module that may internally implement it with platform-specific code, +but expose a common interface. By portable Perl, we mean code that +avoids the constructs described in this document as being non-portable. + + +=head2 External Subroutines (XS) + +XS code, in general, can be made to work with any platform; but dependent +libraries, header files, etc., might not be readily available or +portable, or the XS code itself might be platform-specific, just as Perl +code might be. If the libraries and headers are portable, then it is +normally reasonable to make sure the XS code is portable, too. + +There is a different kind of portability issue with writing XS +code: availability of a C compiler on the end-user's system. C brings with +it its own portability issues, and writing XS code will expose you to +some of those. Writing purely in perl is a comparatively easier way to +achieve portability. + + +=head2 Standard Modules + +In general, the standard modules work across platforms. Notable +exceptions are C (which currently makes connections to external +programs that may not be available), platform-specific modules (like +C), and DBM modules. + +There is no one DBM module that is available on all platforms. +C and the others are generally available on all Unix and DOSish +ports, but not in MacPerl, where C and C are available. + +The good news is that at least some DBM module should be available, and +C will use whichever module it can find. Of course, then +the code needs to be fairly strict, dropping to the lowest common +denominator (e.g., not exceeding 1K for each record). + + +=head2 Time and Date + +The system's notion of time of day and calendar date is controlled in widely +different ways. Don't assume the timezone is stored in C<$ENV{TZ}>, and even +if it is, don't assume that you can control the timezone through that +variable. + +Don't assume that the epoch starts at January 1, 1970, because that is +OS-specific. Better to store a date in an unambiguous representation. +A text representation (like C<1 Jan 1970>) can be easily converted into an +OS-specific value using a module like C. An array of values, +such as those returned by C, can be converted to an OS-specific +representation using C. + + +=head2 System Resources + +If your code is destined for systems with severely constrained (or missing!) +virtual memory systems then you want to be especially mindful of avoiding +wasteful constructs such as: + + # NOTE: this is no longer "bad" in perl5.005 + for (0..10000000) {} # bad + for (my $x = 0; $x <= 10000000; ++$x) {} # good + + @lines = ; # bad + + while () {$file .= $_} # sometimes bad + $file = join '', ; # better + +The last two may appear unintuitive to most people. The first of those +two constructs repeatedly grows a string, while the second allocates a +large chunk of memory in one go. On some systems, the latter is more +efficient that the former. + +=head2 Security + +Most Unix platforms provide basic levels of security that is usually felt +at the file-system level. Other platforms usually don't (unfortunately). +Thus the notion of User-ID, or "home" directory, or even the state of +being logged-in may be unrecognizable on may platforms. If you write +programs that are security conscious, it is usually best to know what +type of system you will be operating under, and write code explicitly +for that platform (or class of platforms). + +=head2 Style + +For those times when it is necessary to have platform-specific code, +consider keeping the platform-specific code in one place, making porting +to other platforms easier. Use the C module and the special +variable C<$^O> to differentiate platforms, as described in L<"PLATFORMS">. + + +=head1 CPAN TESTERS + +Module uploaded to CPAN are tested by a variety of volunteers on +different platforms. These CPAN testers are notified by e-mail of each +new upload, and reply to the list with PASS, FAIL, NA (not applicable to +this platform), or ???? (unknown), along with any relevant notations. + +The purpose of the testing is twofold: one, to help developers fix any +problems in their code; two, to provide users with information about +whether or not a given module works on a given platform. + +=over 4 + +=item Mailing list: cpan-testers@perl.org + +=item Testing results: C + +=back + + +=head1 PLATFORMS + +As of version 5.002, Perl is built with a C<$^O> variable that +indicates the operating system it was built on. This was implemented +to help speed up code that would otherwise have to C and +use the value of C<$Config{'osname'}>. Of course, to get +detailed information about the system, looking into C<%Config> is +certainly recommended. + +=head2 Unix + +Perl works on a bewildering variety of Unix and Unix-like platforms (see +e.g. most of the files in the F directory in the source code kit). +On most of these systems, the value of C<$^O> (hence C<$Config{'osname'}>, +too) is determined by lowercasing and stripping punctuation from the first +field of the string returned by typing + + % uname -a + +(or a similar command) at the shell prompt. Here, for example, are a few +of the more popular Unix flavors: + + uname $^O + -------------------- + AIX aix + FreeBSD freebsd + Linux linux + HP-UX hpux + OSF1 dec_osf + SunOS solaris + SunOS4 sunos + + +=head2 DOS and Derivatives + +Perl has long been ported to PC style microcomputers running under +systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can +bring yourself to mention (except for Windows CE, if you count that). +Users familiar with I and/or I style shells should +be aware that each of these file specifications may have subtle +differences: + + $filespec0 = "c:/foo/bar/file.txt"; + $filespec1 = "c:\\foo\\bar\\file.txt"; + $filespec2 = 'c:\foo\bar\file.txt'; + $filespec3 = 'c:\\foo\\bar\\file.txt'; + +System calls accept either C or C<\> as the path separator. However, +many command-line utilities of DOS vintage treat C as the option +prefix, so they may get confused by filenames containing C. Aside +from calling any external programs, C will work just fine, and +probably better, as it is more consistent with popular usage, and avoids +the problem of remembering what to backwhack and what not to. + +The DOS FAT file system can only accomodate "8.3" style filenames. Under +the "case insensitive, but case preserving" HPFS (OS/2) and NTFS (NT) +file systems you may have to be careful about case returned with functions +like C or used with functions like C or C. + +DOS also treats several filenames as special, such as AUX, PRN, NUL, CON, +COM1, LPT1, LPT2 etc. Unfortunately these filenames won't even work +if you include an explicit directory prefix, in some cases. It is best +to avoid such filenames, if you want your code to be portable to DOS +and its derivatives. + +Users of these operating systems may also wish to make use of +scripts such as I or I as appropriate to +put wrappers around your scripts. + +Newline (C<\n>) is translated as C<\015\012> by STDIO when reading from +and writing to files. C will keep C<\n> translated +as C<\012> for that filehandle. Since it is a noop on other systems, +C should be used for cross-platform code that deals with binary +data. + +The C<$^O> variable and the C<$Config{'archname'}> values for various +DOSish perls are as follows: + + OS $^O $Config{'archname'} + -------------------------------------------- + MS-DOS dos + PC-DOS dos + OS/2 os2 + Windows 95 MSWin32 MSWin32-x86 + Windows NT MSWin32 MSWin32-x86 + Windows NT MSWin32 MSWin32-alpha + Windows NT MSWin32 MSWin32-ppc + +Also see: + +=over 4 + +=item The djgpp environment for DOS, C + +=item The EMX environment for DOS, OS/2, etc. C, +C + +=item Build instructions for Win32, L. + +=item The ActiveState Pages, C + +=back + + +=head2 MacPerl + +Any module requiring XS compilation is right out for most people, because +MacPerl is built using non-free (and non-cheap!) compilers. Some XS +modules that can work with MacPerl are built and distributed in binary +form on CPAN. See I for more details. + +Directories are specified as: + + volume:folder:file for absolute pathnames + volume:folder: for absolute pathnames + :folder:file for relative pathnames + :folder: for relative pathnames + :file for relative pathnames + file for relative pathnames + +Files in a directory are stored in alphabetical order. Filenames are +limited to 31 characters, and may include any character except C<:>, +which is reserved as a path separator. + +Instead of C, see C and C in +C. + +In the MacPerl application, you can't run a program from the command line; +programs that expect C<@ARGV> to be populated can be edited with something +like the following, which brings up a dialog box asking for the command +line arguments. + + if (!@ARGV) { + @ARGV = split /\s+/, MacPerl::Ask('Arguments?'); + } + +A MacPerl script saved as a droplet will populate C<@ARGV> with the full +pathnames of the files dropped onto the script. + +Mac users can use programs on a kind of command line under MPW (Macintosh +Programmer's Workshop, a free development environment from Apple). +MacPerl was first introduced as an MPW tool, and MPW can be used like a +shell: + + perl myscript.plx some arguments + +ToolServer is another app from Apple that provides access to MPW tools +from MPW and the MacPerl app, which allows MacPerl program to use +C, backticks, and piped C. + +"S" is the proper name for the operating system, but the value +in C<$^O> is "MacOS". To determine architecture, version, or whether +the application or MPW tool version is running, check: + + $is_app = $MacPerl::Version =~ /App/; + $is_tool = $MacPerl::Version =~ /MPW/; + ($version) = $MacPerl::Version =~ /^(\S+)/; + $is_ppc = $MacPerl::Architecture eq 'MacPPC'; + $is_68k = $MacPerl::Architecture eq 'Mac68K'; + + +Also see: + +=over 4 + +=item The MacPerl Pages, C. + +=item The MacPerl mailing list, C. + +=back + + +=head2 VMS + +Perl on VMS is discussed in F in the perl distribution. +Note that perl on VMS can accept either VMS or Unix style file +specifications as in either of the following: + + $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM + $ perl -ne "print if /perl_setup/i" /sys$login/login.com + +but not a mixture of both as in: + + $ perl -ne "print if /perl_setup/i" sys$login:/login.com + Can't open sys$login:/login.com: file specification syntax error + +Interacting with Perl from the Digital Command Language (DCL) shell +often requires a different set of quotation marks than Unix shells do. +For example: + + $ perl -e "print ""Hello, world.\n""" + Hello, world. + +There are a number of ways to wrap your perl scripts in DCL .COM files if +you are so inclined. For example: + + $ write sys$output "Hello from DCL!" + $ if p1 .eqs. "" + $ then perl -x 'f$environment("PROCEDURE") + $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8 + $ deck/dollars="__END__" + #!/usr/bin/perl + + print "Hello from Perl!\n"; + + __END__ + $ endif + +Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your +perl-in-DCL script expects to do things like C<$read = ESTDINE;>. + +Filenames are in the format "name.extension;version". The maximum +length for filenames is 39 characters, and the maximum length for +extensions is also 39 characters. Version is a number from 1 to +32767. Valid characters are C. + +VMS' RMS filesystem is case insensitive and does not preserve case. +C returns lowercased filenames, but specifying a file for +opening remains case insensitive. Files without extensions have a +trailing period on them, so doing a C with a file named F +will return F (though that file could be opened with C. + +RMS has an eight level limit on directory depths from any rooted logical +(allowing 16 levels overall). Hence C +is a valid directory specification but C +is not. F authors might have to take this into account, but +at least they can refer to the former as C. + +The C module, which gets installed as part +of the build process on VMS, is a pure Perl module that can easily be +installed on non-VMS platforms and can be helpful for conversions to +and from RMS native formats. + +What C<\n> represents depends on the type of file that is open. It could +be C<\015>, C<\012>, C<\015\012>, or nothing. Reading from a file +translates newlines to C<\012>, unless C was executed on that +handle, just like DOSish perls. + +TCP/IP stacks are optional on VMS, so socket routines might not be +implemented. UDP sockets may not be supported. + +The value of C<$^O> on OpenVMS is "VMS". To determine the architecture +that you are running on without resorting to loading all of C<%Config> +you can examine the content of the C<@INC> array like so: + + if (grep(/VMS_AXP/, @INC)) { + print "I'm on Alpha!\n"; + } elsif (grep(/VMS_VAX/, @INC)) { + print "I'm on VAX!\n"; + } else { + print "I'm not so sure about where $^O is...\n"; + } + +Also see: + +=over 4 + +=item L + +=item vmsperl list, C + +Put words C in message body. + +=item vmsperl on the web, C + +=back + + +=head2 EBCDIC Platforms + +Recent versions of Perl have been ported to platforms such as OS/400 on +AS/400 minicomputers as well as OS/390 for IBM Mainframes. Such computers +use EBCDIC character sets internally (usually Character Code Set ID 00819 +for OS/400 and IBM-1047 for OS/390). Note that on the mainframe perl +currently works under the "Unix system services for OS/390" (formerly +known as OpenEdition). + +As of R2.5 of USS for OS/390 that Unix sub-system did not support the +C<#!> shebang trick for script invocation. Hence, on OS/390 perl scripts +can executed with a header similar to the following simple script: + + : # use perl + eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}' + if 0; + #!/usr/local/bin/perl # just a comment really + + print "Hello from perl!\n"; + +On these platforms, bear in mind that the EBCDIC character set may have +an effect on what happens with perl functions such as C, C, +C, C, C, C, C, C; as well as +bit-fiddling with ASCII constants using operators like C<^>, C<&> and +C<|>; not to mention dealing with socket interfaces to ASCII computers +(see L<"NEWLINES">). + +Fortunately, most web servers for the mainframe will correctly translate +the C<\n> in the following statement to its ASCII equivalent (note that +C<\r> is the same under both ASCII and EBCDIC): + + print "Content-type: text/html\r\n\r\n"; + +The value of C<$^O> on OS/390 is "os390". + +Some simple tricks for determining if you are running on an EBCDIC +platform could include any of the following (perhaps all): + + if ("\t" eq "\05") { print "EBCDIC may be spoken here!\n"; } + + if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; } + + if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; } + +Note that one thing you may not want to rely on is the EBCDIC encoding +of punctuation characters since these may differ from code page to code page +(and once your module or script is rumoured to work with EBCDIC, folks will +want it to work with all EBCDIC character sets). + +Also see: + +=over 4 + +=item perl-mvs list + +The perl-mvs@perl.org list is for discussion of porting issues as well as +general usage issues for all EBCDIC Perls. Send a message body of +"subscribe perl-mvs" to majordomo@perl.org. + +=item AS/400 Perl information at C + +=back + +=head2 Other perls + +Perl has been ported to a variety of platforms that do not fit into any of +the above categories. Some, such as AmigaOS, BeOS, QNX, and Plan 9, have +been well integrated into the standard Perl source code kit. You may need +to see the F directory on CPAN for information, and possibly +binaries, for the likes of: acorn, aos, atari, lynxos, HP-MPE/iX, riscos, +Tandem Guardian, vos, I (yes we know that some of these OSes may fall +under the Unix category but we are not a standards body.) + +See also: + +=over 4 + +=item Atari, Guido Flohr's page C + +=item HP 300 MPE/iX C + +=item Novell Netware + +A free Perl 5 based PERL.NLM for Novell Netware is available from +C + +=back + + +=head1 FUNCTION IMPLEMENTATIONS + +Listed below are functions unimplemented or implemented differently on +various platforms. Following each description will be, in parentheses, a +list of platforms that the description applies to. + +The list may very well be incomplete, or wrong in some places. When in +doubt, consult the platform-specific README files in the Perl source +distribution, and other documentation resources for a given port. + +Be aware, moreover, that even among Unix-ish systems there are variations, +and not all functions listed here are necessarily available, though +most usually are. + +For many functions, you can also query C<%Config>, exported by default +from C. For example, to check if the platform has the C +call, check C<$Config{'d_lstat'}>. See L for a full description +of available variables. + + +=head2 Alphabetical Listing of Perl Functions + +=over 8 + +=item -X FILEHANDLE + +=item -X EXPR + +=item -X + +C<-r>, C<-w>, and C<-x> have only a very limited meaning; directories +and applications are executable, and there are no uid/gid +considerations. C<-o> is not supported. (S) + +C<-r>, C<-w>, C<-x>, and C<-o> tell whether or not file is accessible, +which may not reflect UIC-based file protections. (VMS) + +C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>, +C<-x>, C<-o>. (S, Win32, VMS) + +C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented. +(S) + +C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful. +(Win32, VMS) + +C<-d> is true if passed a device spec without an explicit directory. +(VMS) + +C<-T> and C<-B> are implemented, but might misclassify Mac text files +with foreign characters; this is the case will all platforms, but +affects S a lot. (S) + +C<-x> (or C<-X>) determine if a file ends in one of the executable +suffixes. C<-S> is meaningless. (Win32) + +=item binmode FILEHANDLE + +Meaningless. (S) + +Reopens file and restores pointer; if function fails, underlying +filehandle may be closed, or pointer may be in a different position. +(VMS) + +The value returned by C may be affected after the call, and +the filehandle may be flushed. (Win32) + +=item chmod LIST + +Only limited meaning. Disabling/enabling write permission is mapped to +locking/unlocking the file. (S) + +Only good for changing "owner" read-write access, "group", and "other" +bits are meaningless. (Win32) + +=item chown LIST + +Not implemented. (S, Win32, Plan9) + +Does nothing, but won't fail. (Win32) + +=item chroot FILENAME + +=item chroot + +Not implemented. (S, Win32, VMS, Plan9) + +=item crypt PLAINTEXT,SALT + +May not be available if library or source was not provided when building +perl. (Win32) + +=item dbmclose HASH + +Not implemented. (VMS, Plan9) + +=item dbmopen HASH,DBNAME,MODE + +Not implemented. (VMS, Plan9) + +=item dump LABEL + +Not useful. (S) + +Not implemented. (Win32) + +Invokes VMS debugger. (VMS) + +=item exec LIST + +Not implemented. (S) + +=item fcntl FILEHANDLE,FUNCTION,SCALAR + +Not implemented. (Win32, VMS) + +=item flock FILEHANDLE,OPERATION + +Not implemented (S, VMS). + +Available only on Windows NT (not on Windows 95). (Win32) + +=item fork + +Not implemented. (S, Win32, AmigaOS) + +=item getlogin + +Not implemented. (S) + +=item getpgrp PID + +Not implemented. (S, Win32, VMS) + +=item getppid + +Not implemented. (S, Win32, VMS) + +=item getpriority WHICH,WHO + +Not implemented. (S, Win32, VMS) + +=item getpwnam NAME + +Not implemented. (S, Win32) + +=item getgrnam NAME + +Not implemented. (S, Win32, VMS) + +=item getnetbyname NAME + +Not implemented. (S, Win32, Plan9) + +=item getpwuid UID + +Not implemented. (S, Win32) + +=item getgrgid GID + +Not implemented. (S, Win32, VMS) + +=item getnetbyaddr ADDR,ADDRTYPE + +Not implemented. (S, Win32, Plan9) + +=item getprotobynumber NUMBER + +Not implemented. (S) + +=item getservbyport PORT,PROTO + +Not implemented. (S) + +=item getpwent + +Not implemented. (S, Win32) + +=item getgrent + +Not implemented. (S, Win32, VMS) + +=item gethostent + +Not implemented. (S, Win32) + +=item getnetent + +Not implemented. (S, Win32, Plan9) + +=item getprotoent + +Not implemented. (S, Win32, Plan9) + +=item getservent + +Not implemented. (Win32, Plan9) + +=item setpwent + +Not implemented. (S, Win32) + +=item setgrent + +Not implemented. (S, Win32, VMS) + +=item sethostent STAYOPEN + +Not implemented. (S, Win32, Plan9) + +=item setnetent STAYOPEN + +Not implemented. (S, Win32, Plan9) + +=item setprotoent STAYOPEN + +Not implemented. (S, Win32, Plan9) + +=item setservent STAYOPEN + +Not implemented. (Plan9, Win32) + +=item endpwent + +Not implemented. (S, Win32) + +=item endgrent + +Not implemented. (S, Win32, VMS) + +=item endhostent + +Not implemented. (S, Win32) + +=item endnetent + +Not implemented. (S, Win32, Plan9) + +=item endprotoent + +Not implemented. (S, Win32, Plan9) + +=item endservent + +Not implemented. (Plan9, Win32) + +=item getsockopt SOCKET,LEVEL,OPTNAME + +Not implemented. (S, Plan9) + +=item glob EXPR + +=item glob + +Globbing built-in, but only C<*> and C metacharacters are supported. +(S) + +Features depend on external perlglob.exe or perlglob.bat. May be overridden +with something like File::DosGlob, which is recommended. (Win32) + +=item ioctl FILEHANDLE,FUNCTION,SCALAR + +Not implemented. (VMS) + +Available only for socket handles, and it does what the ioctlsocket() call +in the Winsock API does. (Win32) + +=item kill LIST + +Not implemented. (S) + +Available only for process handles returned by the C method of +spawning a process. (Win32) + +=item link OLDFILE,NEWFILE + +Not implemented. (S, Win32, VMS) + +=item lstat FILEHANDLE + +=item lstat EXPR + +=item lstat + +Not implemented. (VMS) + +Return values may be bogus. (Win32) + +=item msgctl ID,CMD,ARG + +=item msgget KEY,FLAGS + +=item msgsnd ID,MSG,FLAGS + +=item msgrcv ID,VAR,SIZE,TYPE,FLAGS + +Not implemented. (S, Win32, VMS, Plan9) + +=item open FILEHANDLE,EXPR + +=item open FILEHANDLE + +The C<|> variants are only supported if ToolServer is installed. +(S) + +open to C<|-> and C<-|> are unsupported. (S, Win32) + +=item pipe READHANDLE,WRITEHANDLE + +Not implemented. (S) + +=item readlink EXPR + +=item readlink + +Not implemented. (Win32, VMS) + +=item select RBITS,WBITS,EBITS,TIMEOUT + +Only implemented on sockets. (Win32) + +=item semctl ID,SEMNUM,CMD,ARG + +=item semget KEY,NSEMS,FLAGS + +=item semop KEY,OPSTRING + +Not implemented. (S, Win32, VMS) + +=item setpgrp PID,PGRP + +Not implemented. (S, Win32, VMS) + +=item setpriority WHICH,WHO,PRIORITY + +Not implemented. (S, Win32, VMS) + +=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL + +Not implemented. (S, Plan9) + +=item shmctl ID,CMD,ARG + +=item shmget KEY,SIZE,FLAGS + +=item shmread ID,VAR,POS,SIZE + +=item shmwrite ID,STRING,POS,SIZE + +Not implemented. (S, Win32, VMS) + +=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL + +Not implemented. (S, Win32, VMS) + +=item stat FILEHANDLE + +=item stat EXPR + +=item stat + +mtime and atime are the same thing, and ctime is creation time instead of +inode change time. (S) + +device and inode are not meaningful. (Win32) + +device and inode are not necessarily reliable. (VMS) + +=item symlink OLDFILE,NEWFILE + +Not implemented. (Win32, VMS) + +=item syscall LIST + +Not implemented. (S, Win32, VMS) + +=item system LIST + +Only implemented if ToolServer is installed. (S) + +As an optimization, may not call the command shell specified in +C<$ENV{PERL5SHELL}>. C spawns an external +process and immediately returns its process designator, without +waiting for it to terminate. Return value may be used subsequently +in C or C. (Win32) + +=item times + +Only the first entry returned is nonzero. (S) + +"cumulative" times will be bogus. On anything other than Windows NT, +"system" time will be bogus, and "user" time is actually the time +returned by the clock() function in the C runtime library. (Win32) + +=item truncate FILEHANDLE,LENGTH + +=item truncate EXPR,LENGTH + +Not implemented. (VMS) + +=item umask EXPR + +=item umask + +Returns undef where unavailable, as of version 5.005. + +=item utime LIST + +Only the modification time is updated. (S, VMS) + +May not behave as expected. (Win32) + +=item wait + +=item waitpid PID,FLAGS + +Not implemented. (S) + +Can only be applied to process handles returned for processes spawned +using C. (Win32) + +=back + + +=head1 AUTHORS / CONTRIBUTORS + +Chris Nandor Epudge@pobox.comE, +Gurusamy Sarathy Egsar@umich.eduE, +Peter Prymmer Epvhp@forte.comE, +Tom Christiansen Etchrist@perl.comE, +Nathan Torkington Egnat@frii.comE, +Paul Moore EPaul.Moore@uk.origin-it.comE, +Matthias Neercher Eneeri@iis.ee.ethz.chE, +Charles Bailey Ebailey@genetics.upenn.eduE, +Luther Huffman Elutherh@stratcom.comE, +Gary Ng E71564.1743@CompuServe.COME, +Nick Ing-Simmons Enick@ni-s.u-net.comE, +Paul J. Schinder Eschinder@pobox.comE, +Tom Phoenix Erootbeer@teleport.comE, +Hugo van der Sanden Eh.sanden@elsevier.nlE, +Dominic Dunlop Edomo@vo.luE, +Dan Sugalski Esugalskd@ous.eduE, +Andreas J. Koenig Ekoenig@kulturbox.deE, +Andrew M. Langmead Eaml@world.std.comE, +Andy Dougherty Edoughera@lafcol.lafayette.eduE, +Abigail Eabigail@fnx.comE. + +This document is maintained by Chris Nandor. + +=head1 VERSION + +Version 1.23, last modified 10 July 1998. +