contains everything else. These are, if you like, the C code for Perl's
built-in functions and operators.
+Note that each C<pp_> function is expected to return a pointer to the next
+op. Calls to perl subs (and eval blocks) are handled within the same
+runops loop, and do not consume extra space on the C stack. For example,
+C<pp_entersub> and C<pp_entertry> just push a C<CxSUB> or C<CxEVAL> block
+struct onto the context stack which contain the address of the op
+following the sub call or eval. They then return the first op of that sub
+or eval block, and so execution continues of that sub or block. Later, a
+C<pp_leavesub> or C<pp_leavetry> op pops the C<CxSUB> or C<CxEVAL>,
+retrieves the return op from it, and returns it.
+
+=item Exception handing
+
+Perl's exception handing (ie C<die> etc) is built on top of the low-level
+C<setjmp()>/C<longjmp()> C-library functions. These basically provide a
+way to capture the current PC and SP registers and later restore them; ie
+a C<longjmp()> continues at the point in code where a previous C<setjmp()>
+was done, with anything further up on the C stack being lost. This is why
+code should always save values using C<SAVE_FOO> rather than in auto
+variables.
+
+The perl core wraps C<setjmp()> etc in the macros C<JMPENV_PUSH> and
+C<JMPENV_JUMP>. The basic rule of perl exceptions is that C<exit>, and
+C<die> (in the absence of C<eval>) perform a C<JMPENV_JUMP(2)>, while
+C<die> within C<eval> does a C<JMPENV_JUMP(3)>.
+
+At entry points to perl, such as C<perl_parse()>, C<perl_run()> and
+C<call_sv(cv, G_EVAL)> each does a C<JMPENV_PUSH>, then enter a runops
+loop or whatever, and handle possible exception returns. For a 2 return,
+final cleanup is performed, such as popping stacks and calling C<CHECK> or
+C<END> blocks. Amongst other things, this is how scope cleanup still
+occurs during an C<exit>.
+
+If a C<die> can find a C<CxEVAL> block on the context stack, then the
+stack is popped to that level and the return op in that block is assigned
+to C<PL_restartop>; then a C<JMPENV_JUMP(3)> is performed. This normally
+passes control back to the guard. In the case of C<perl_run> and
+C<call_sv>, a non-null C<PL_restartop> triggers re-entry to the runops
+loop. The is the normal way that C<die> or C<croak> is handled within an
+C<eval>.
+
+Sometimes ops are executed within an inner runops loop, such as tie, sort
+or overload code. In this case, something like
+
+ sub FETCH { eval { die } }
+
+would cause a longjmp right back to the guard in C<perl_run>, popping both
+runops loops, which is clearly incorrect. One way to avoid this is for the
+tie code to do a C<JMPENV_PUSH> before executing C<FETCH> in the inner
+runops loop, but for efficiency reasons, perl in fact just sets a flag,
+using C<CATCH_SET(TRUE)>. The C<pp_require>, C<pp_entereval> and
+C<pp_entertry> ops check this flag, and if true, they call C<docatch>,
+which does a C<JMPENV_PUSH> and starts a new runops level to execute the
+code, rather than doing it on the current loop.
+
+As a further optimisation, on exit from the eval block in the C<FETCH>,
+execution of the code following the block is still carried on in the inner
+loop. When an exception is raised, C<docatch> compares the C<JMPENV>
+level of the C<CxEVAL> with C<PL_top_env> and if they differ, just
+re-throws the exception. In this way any inner loops get popped.
+
+Here's an example.
+
+ 1: eval { tie @a, 'A' };
+ 2: sub A::TIEARRAY {
+ 3: eval { die };
+ 4: die;
+ 5: }
+
+To run this code, C<perl_run> is called, which does a C<JMPENV_PUSH> then
+enters a runops loop. This loop executes the eval and tie ops on line 1,
+with the eval pushing a C<CxEVAL> onto the context stack.
+
+The C<pp_tie> does a C<CATCH_SET(TRUE)>, then starts a second runops loop
+to execute the body of C<TIEARRAY>. When it executes the entertry op on
+line 3, C<CATCH_GET> is true, so C<pp_entertry> calls C<docatch> which
+does a C<JMPENV_PUSH> and starts a third runops loop, which then executes
+the die op. At this point the C call stack looks like this:
+
+ Perl_pp_die
+ Perl_runops # third loop
+ S_docatch_body
+ S_docatch
+ Perl_pp_entertry
+ Perl_runops # second loop
+ S_call_body
+ Perl_call_sv
+ Perl_pp_tie
+ Perl_runops # first loop
+ S_run_body
+ perl_run
+ main
+
+and the context and data stacks, as shown by C<-Dstv>, look like:
+
+ STACK 0: MAIN
+ CX 0: BLOCK =>
+ CX 1: EVAL => AV() PV("A"\0)
+ retop=leave
+ STACK 1: MAGIC
+ CX 0: SUB =>
+ retop=(null)
+ CX 1: EVAL => *
+ retop=nextstate
+
+The die pops the first C<CxEVAL> off the context stack, sets
+C<PL_restartop> from it, does a C<JMPENV_JUMP(3)>, and control returns to
+the top C<docatch>. This then starts another third-level runops level,
+which executes the nextstate, pushmark and die ops on line 4. At the point
+that the second C<pp_die> is called, the C call stack looks exactly like
+that above, even though we are no longer within an inner eval; this is
+because of the optimization mentioned earlier. However, the context stack
+now looks like this, ie with the top CxEVAL popped:
+
+ STACK 0: MAIN
+ CX 0: BLOCK =>
+ CX 1: EVAL => AV() PV("A"\0)
+ retop=leave
+ STACK 1: MAGIC
+ CX 0: SUB =>
+ retop=(null)
+
+The die on line 4 pops the context stack back down to the CxEVAL, leaving
+it as:
+
+ STACK 0: MAIN
+ CX 0: BLOCK =>
+
+As usual, C<PL_restartop> is extracted from the C<CxEVAL>, and a
+C<JMPENV_JUMP(3)> done, which pops the C stack back to the docatch:
+
+ S_docatch
+ Perl_pp_entertry
+ Perl_runops # second loop
+ S_call_body
+ Perl_call_sv
+ Perl_pp_tie
+ Perl_runops # first loop
+ S_run_body
+ perl_run
+ main
+
+In this case, because the C<JMPENV> level recorded in the C<CxEVAL>
+differs from the current one, C<docatch> just does a C<JMPENV_JUMP(3)>
+and the C stack unwinds to:
+
+ perl_run
+ main
+
+Because C<PL_restartop> is non-null, C<run_body> starts a new runops loop
+and execution continues.
+
=back
=head2 Internal Variable Types
deliberate in your decision.
The material below is separated into three main sections: main issues of
-portability (L<"ISSUES">, platform-specific issues (L<"PLATFORMS">, and
+portability (L<"ISSUES">), platform-specific issues (L<"PLATFORMS">), and
built-in perl functions that behave differently on various ports
-(L<"FUNCTION IMPLEMENTATIONS">.
+(L<"FUNCTION IMPLEMENTATIONS">).
This information should not be considered complete; it includes possibly
transient information about idiosyncrasies of some of the ports, almost
You can get away with this on Unix and Mac OS (they have a single
character end-of-line), but the same program will break under DOSish
perls because you're only chop()ing half the end-of-line. Instead,
-chomp() should be used to trim newlines. The Dunce::Files module can
-help audit your code for misuses of chop().
+chomp() should be used to trim newlines. The L<Dunce::Files> module
+can help audit your code for misuses of chop().
When dealing with binary files (or text files in binary mode) be sure
to explicitly set $/ to the appropriate value for your file format
To convert $^X to a file pathname, taking account of the requirements
of the various operating system possibilities, say:
+
use Config;
$thisperl = $^X;
if ($^O ne 'VMS')
{$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
To convert $Config{perlpath} to a file pathname, say:
+
use Config;
$thisperl = $Config{perlpath};
if ($^O ne 'VMS')
Don't assume that any particular port (service) will respond.
-Don't assume that Sys::Hostname() (or any other API or command)
+Don't assume that Sys::Hostname (or any other API or command)
returns either a fully qualified hostname or a non-qualified hostname:
it all depends on how the system had been configured. Also remember
things like DHCP and NAT-- the hostname you get back might not be very
platforms; two, to provide users with information about whether
a given module works on a given platform.
+Also see:
+
=over 4
-=item Mailing list: cpan-testers@perl.org
+=item *
-=item Testing results: http://testers.cpan.org/
+Mailing list: cpan-testers@perl.org
+
+=item *
+
+Testing results: http://testers.cpan.org/
=back
Windows NT MSWin32 MSWin32-x86 2 4 xx
Windows NT MSWin32 MSWin32-ALPHA 2 4 xx
Windows NT MSWin32 MSWin32-ppc 2 4 xx
- Windows 2000 MSWin32 MSWin32-x86 2 5 xx
- Windows XP MSWin32 MSWin32-x86 2 ?
+ Windows 2000 MSWin32 MSWin32-x86 2 5 00
+ Windows XP MSWin32 MSWin32-x86 2 5 01
+ Windows 2003 MSWin32 MSWin32-x86 2 5 02
Windows CE MSWin32 ? 3
- Cygwin cygwin ?
+ Cygwin cygwin cygwin
The various MSWin32 Perl's can distinguish the OS they are running on
via the value of the fifth element of the list returned from
The MacPerl mailing lists, http://lists.perl.org/ .
+=item *
+
+MPW, ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/
+
=back
=head2 VMS
=item *
-*
-
L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
L<perlebcdic>.
general usage issues for all EBCDIC Perls. Send a message body of
"subscribe perl-mvs" to majordomo@perl.org.
-=item *
+=item *
AS/400 Perl information at
http://as400.rochester.ibm.com/
=over 8
-=item -X FILEHANDLE
-
-=item -X EXPR
-
=item -X
C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
C<-x> (or C<-X>) determine if a file has an executable file type.
(S<RISC OS>)
-=item binmode FILEHANDLE
+=item atan2
+
+Due to issues with various CPUs, math libraries, compilers, and standards,
+results for C<atan2()> may vary depending on any combination of the above.
+Perl attempts to conform to the Open Group/IEEE standards for the results
+returned from C<atan2()>, but cannot force the issue if the system Perl is
+run on does not allow it. (Tru64, HP-UX 10.20)
+
+The current version of the standards for C<atan2()> is available at
+L<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
+
+=item binmode
Meaningless. (S<Mac OS>, S<RISC OS>)
The value returned by C<tell> may be affected after the call, and
the filehandle may be flushed. (Win32)
-=item chmod LIST
+=item chmod
Only limited meaning. Disabling/enabling write permission is mapped to
locking/unlocking the file. (S<Mac OS>)
The actual permissions set depend on the value of the C<CYGWIN>
in the SYSTEM environment settings. (Cygwin)
-=item chown LIST
+=item chown
Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>, VOS)
Does nothing, but won't fail. (Win32)
-=item chroot FILENAME
-
=item chroot
Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS, VM/ESA)
-=item crypt PLAINTEXT,SALT
+=item crypt
May not be available if library or source was not provided when building
perl. (Win32)
Not implemented. (VOS)
-=item dbmclose HASH
+=item dbmclose
Not implemented. (VMS, S<Plan 9>, VOS)
-=item dbmopen HASH,DBNAME,MODE
+=item dbmopen
Not implemented. (VMS, S<Plan 9>, VOS)
-=item dump LABEL
+=item dump
Not useful. (S<Mac OS>, S<RISC OS>)
Invokes VMS debugger. (VMS)
-=item exec LIST
+=item exec
Not implemented. (S<Mac OS>)
Does not automatically flush output handles on some platforms.
(SunOS, Solaris, HP-UX)
-=item exit EXPR
-
=item exit
Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
(C<1>); this mapping cannot be overridden. Any other argument to exit()
is used directly as Perl's exit status. (VMS)
-=item fcntl FILEHANDLE,FUNCTION,SCALAR
+=item fcntl
Not implemented. (Win32, VMS)
-=item flock FILEHANDLE,OPERATION
+=item flock
Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
Not implemented. (S<Mac OS>, S<RISC OS>)
-=item getpgrp PID
+=item getpgrp
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
-=item getpriority WHICH,WHO
+=item getpriority
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
-=item getpwnam NAME
+=item getpwnam
Not implemented. (S<Mac OS>, Win32)
Not useful. (S<RISC OS>)
-=item getgrnam NAME
+=item getgrnam
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
-=item getnetbyname NAME
+=item getnetbyname
Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
-=item getpwuid UID
+=item getpwuid
Not implemented. (S<Mac OS>, Win32)
Not useful. (S<RISC OS>)
-=item getgrgid GID
+=item getgrgid
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
-=item getnetbyaddr ADDR,ADDRTYPE
+=item getnetbyaddr
Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
-=item getprotobynumber NUMBER
+=item getprotobynumber
Not implemented. (S<Mac OS>)
-=item getservbyport PORT,PROTO
+=item getservbyport
Not implemented. (S<Mac OS>)
Not implemented. (Win32, S<Plan 9>)
-=item sethostent STAYOPEN
+=item sethostent
Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
-=item setnetent STAYOPEN
+=item setnetent
Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
-=item setprotoent STAYOPEN
+=item setprotoent
Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
-=item setservent STAYOPEN
+=item setservent
Not implemented. (S<Plan 9>, Win32, S<RISC OS>)
Not implemented. (S<Plan 9>)
-=item glob EXPR
-
=item glob
This operator is implemented via the File::Glob extension on most
platforms. See L<File::Glob> for portability information.
+=item gmtime
+
+Same portability caveats as L<localtime>.
+
=item ioctl FILEHANDLE,FUNCTION,SCALAR
Not implemented. (VMS)
Available only for socket handles. (S<RISC OS>)
-=item kill SIGNAL, LIST
+=item kill
C<kill(0, LIST)> is implemented for the sake of taint checking;
use with other signals is unimplemented. (S<Mac OS>)
$sig is 0 and the specified process exists, it returns true without
actually terminating it. (Win32)
-=item link OLDFILE,NEWFILE
+=item link
Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
Hard links are implemented on Win32 (Windows NT and Windows 2000)
under NTFS only.
-=item lstat FILEHANDLE
+=item localtime
-=item lstat EXPR
+Because Perl currently relies on the native standard C localtime()
+function, it is only safe to use times between 0 and (2**31)-1. Times
+outside this range may result in unexpected behavior depending on your
+operating system's implementation of localtime().
=item lstat
Return values (especially for device and inode) may be bogus. (Win32)
-=item msgctl ID,CMD,ARG
+=item msgctl
-=item msgget KEY,FLAGS
+=item msgget
-=item msgsnd ID,MSG,FLAGS
+=item msgsnd
-=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+=item msgrcv
Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
-=item open FILEHANDLE,EXPR
-
-=item open FILEHANDLE
+=item open
The C<|> variants are supported only if ToolServer is installed.
(S<Mac OS>)
Opening a process does not automatically flush output handles on some
platforms. (SunOS, Solaris, HP-UX)
-=item pipe READHANDLE,WRITEHANDLE
+=item pipe
Very limited functionality. (MiNT)
-=item readlink EXPR
-
=item readlink
Not implemented. (Win32, VMS, S<RISC OS>)
-=item rename OLDNAME,NEWNAME
+=item rename
Can't move directories between directories on different logical volumes. (Win32)
-=item select RBITS,WBITS,EBITS,TIMEOUT
+=item select
Only implemented on sockets. (Win32, VMS)
Note that the C<select FILEHANDLE> form is generally portable.
-=item semctl ID,SEMNUM,CMD,ARG
+=item semctl
-=item semget KEY,NSEMS,FLAGS
+=item semget
-=item semop KEY,OPSTRING
+=item semop
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
Not implemented. (S<Mac OS>, MPE/iX, VMS, Win32, S<RISC OS>)
-=item setpgrp PID,PGRP
+=item setpgrp
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
-=item setpriority WHICH,WHO,PRIORITY
+=item setpriority
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
Not implemented. (S<Mac OS>, MPE/iX, Win32, S<RISC OS>)
-=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+=item setsockopt
Not implemented. (S<Plan 9>)
-=item shmctl ID,CMD,ARG
+=item shmctl
-=item shmget KEY,SIZE,FLAGS
+=item shmget
-=item shmread ID,VAR,POS,SIZE
+=item shmread
-=item shmwrite ID,STRING,POS,SIZE
+=item shmwrite
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
-=item sockatmark SOCKET
+=item sockatmark
A relatively recent addition to socket functions, may not
be implemented even in UNIX platforms.
-=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+=item socketpair
Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
-=item stat FILEHANDLE
-
-=item stat EXPR
-
=item stat
Platforms that do not have rdev, blksize, or blocks will return these
some versions of cygwin when doing a stat("foo") and if not finding it
may then attempt to stat("foo.exe") (Cygwin)
-=item symlink OLDFILE,NEWFILE
+=item symlink
Not implemented. (Win32, VMS, S<RISC OS>)
-=item syscall LIST
+=item syscall
Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
-=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
+=item sysopen
The traditional "0", "1", and "2" MODEs are implemented with different
numeric values on some systems. The flags exported by C<Fcntl>
(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
OS>, OS/390, VM/ESA)
-=item system LIST
+=item system
In general, do not assume the UNIX/POSIX semantics that you can shift
C<$?> right by eight to get the exit value, or that C<$? & 127>
Not useful. (S<RISC OS>)
-=item truncate FILEHANDLE,LENGTH
-
-=item truncate EXPR,LENGTH
+=item truncate
Not implemented. (Older versions of VMS)
or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it
should not be held open elsewhere. (Win32)
-=item umask EXPR
-
=item umask
Returns undef where unavailable, as of version 5.005.
C<umask> works but the correct permissions are set only when the file
is finally closed. (AmigaOS)
-=item utime LIST
+=item utime
Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
=item wait
-=item waitpid PID,FLAGS
+=item waitpid
Not implemented. (S<Mac OS>, VOS)
=back
-=head1 CHANGES
-
-=over 4
-
-=item v1.48, 02 February 2001
-
-Various updates from perl5-porters over the past year, supported
-platforms update from Jarkko Hietaniemi.
-
-=item v1.47, 22 March 2000
-
-Various cleanups from Tom Christiansen, including migration of
-long platform listings from L<perl>.
-
-=item v1.46, 12 February 2000
-
-Updates for VOS and MPE/iX. (Peter Prymmer) Other small changes.
-
-=item v1.45, 20 December 1999
-
-Small changes from 5.005_63 distribution, more changes to EBCDIC info.
-
-=item v1.44, 19 July 1999
-
-A bunch of updates from Peter Prymmer for C<$^O> values,
-endianness, File::Spec, VMS, BS2000, OS/400.
-
-=item v1.43, 24 May 1999
-
-Added a lot of cleaning up from Tom Christiansen.
-
-=item v1.42, 22 May 1999
-
-Added notes about tests, sprintf/printf, and epoch offsets.
-
-=item v1.41, 19 May 1999
-
-Lots more little changes to formatting and content.
-
-Added a bunch of C<$^O> and related values
-for various platforms; fixed mail and web addresses, and added
-and changed miscellaneous notes. (Peter Prymmer)
-
-=item v1.40, 11 April 1999
-
-Miscellaneous changes.
-
-=item v1.39, 11 February 1999
-
-Changes from Jarkko and EMX URL fixes Michael Schwern. Additional
-note about newlines added.
-
-=item v1.38, 31 December 1998
-
-More changes from Jarkko.
-
-=item v1.37, 19 December 1998
-
-More minor changes. Merge two separate version 1.35 documents.
-
-=item v1.36, 9 September 1998
-
-Updated for Stratus VOS. Also known as version 1.35.
-
-=item v1.35, 13 August 1998
-
-Integrate more minor changes, plus addition of new sections under
-L<"ISSUES">: L<"Numbers endianness and Width">,
-L<"Character sets and character encoding">,
-L<"Internationalisation">.
-
-=item v1.33, 06 August 1998
-
-Integrate more minor changes.
-
-=item v1.32, 05 August 1998
-
-Integrate more minor changes.
-
-=item v1.30, 03 August 1998
-
-Major update for RISC OS, other minor changes.
-
-=item v1.23, 10 July 1998
-
-First public release with perl5.005.
-
-=back
=head1 Supported Platforms
https://perl5.git.perl.org / perl5.git / commitdiff