ActiveState!

ActivePerl Documentation
Table of Contents

(Usage Statistics)
(about this ver)


* Getting Started
    * Welcome To ActivePerl
    * Release Notes
    * Readme
    * ActivePerl Change Log
* Install Notes
    * Linux
    * Solaris
    * Windows
* ActivePerl Components
    * Overview
    * PPM
    * Windows Specifics
       * OLE Browser
       * PerlScript
       * Perl for ISAPI
       * PerlEZ
* ActivePerl FAQ
    * Introduction
    * Availability & Install
    * Using PPM
    * Docs & Support
    * Windows Specifics
       * Perl for ISAPI
       * Windows 9X/NT/2000
       * Quirks
       * Web Server Config
       * Web programming
       * Programming
       * Modules & Samples
       * Embedding & Extending
       * Using OLE with Perl
* Windows Scripting
    * Active Server Pages
    * Windows Script Host
    * Windows Script Components

Core Perl Documentation


* perl
* perlfaq
* perltoc
* perlbook

* perlsyn
* perldata
* perlop
* perlreftut
* perldsc
* perllol

* perllexwarn
* perldebug

* perlrun
* perlfunc
* perlopentut
* perlvar
* perlsub
* perlmod
* perlpod

* perlstyle
* perlmodlib
* perlmodinstall
* perltrap
* perlport
* perlsec

* perlref
* perlre
* perlform
* perllocale
* perlunicode

* perlboot
* perltoot
* perltootc
* perlobj
* perlbot
* perltie

* perlipc
* perlnumber
* perlfork
* perlthrtut

* perldiag
* perlfaq1
* perlfaq2
* perlfaq3
* perlfaq4
* perlfaq5
* perlfaq6
* perlfaq7
* perlfaq8
* perlfaq9

* perlcompile

* perlembed
* perlxstut
* perlxs
* perlguts
* perlcall
* perlfilter
* perldbmfilter
* perlapi
* perlintern
* perlapio
* perltodo
* perlhack

* perlhist
* perldelta
* perl5005delta
* perl5004delta

* perlamiga
* perlcygwin
* perldos
* perlhpux
* perlmachten
* perlos2
* perlos390
* perlvms
* perlwin32

Pragmas


* attributes
* attrs
* autouse
* base
* blib
* bytes
* charnames
* constant
* diagnostics
* fields
* filetest
* integer
* less
* lib
* locale
* lwpcook
* open
* ops
* overload
* perllocal
* re
* sigtrap
* strict
* subs
* utf8
* vars
* warnings

Libraries


* ActivePerl
    * DocTools
        * TOC
            * RDF
* AnyDBM_File
* Archive
    * Tar
* AutoLoader
* AutoSplit
* B
    * Asmdata
    * Assembler
    * Bblock
    * Bytecode
    * C
    * CC
    * Debug
    * Deparse
    * Disassembler
    * Lint
    * Showlex
    * Stackobj
    * Terse
    * Xref
* Benchmark
* Bundle
    * LWP
* ByteLoader
* Carp
    * Heavy
* CGI
    * Apache
    * Carp
    * Cookie
    * Fast
    * Pretty
    * Push
    * Switch
* Class
    * Struct
* Compress
    * Zlib
* Config
* CPAN
    * FirstTime
    * Nox
* Cwd
* Data
    * Dumper
* DB
* Devel
    * DProf
    * Peek
    * SelfStubber
* Digest
    * HMAC
    * HMAC_MD5
    * HMAC_SHA1
    * MD2
    * MD5
    * SHA1
* DirHandle
* Dumpvalue
* DynaLoader
* English
* Env
* Errno
* Exporter
    * Heavy
* ExtUtils
    * Command
    * Embed
    * Install
    * Installed
    * Liblist
    * MakeMaker
    * Manifest
    * Miniperl
    * Mkbootstrap
    * Mksymlists
    * MM_Cygwin
    * MM_OS2
    * MM_Unix
    * MM_VMS
    * MM_Win32
    * Packlist
    * testlib
* Fatal
* Fcntl
* File
    * Basename
    * CheckTree
    * Compare
    * Copy
    * CounterFile
    * DosGlob
    * Find
    * Glob
    * Listing
    * Path
    * Spec
        * Functions
        * Mac
        * OS2
        * Unix
        * VMS
        * Win32
    * stat
* FileCache
* FileHandle
* FindBin
* Font
    * AFM
* Getopt
    * Long
    * Std
* HTML
    * AsSubs
    * Element
    * Entities
    * Filter
    * Form
    * FormatPS
    * Formatter
    * FormatText
    * HeadParser
    * LinkExtor
    * Parse
    * Parser
    * TokeParser
    * TreeBuilder
* HTTP
    * Cookies
    * Daemon
    * Date
    * Headers
        * Util
    * Message
    * Negotiate
    * Request
        * Common
    * Response
    * Status
* I18N
    * Collate
* IO
    * Dir
    * File
    * Handle
    * Pipe
    * Poll
    * Seekable
    * Select
    * Socket
        * INET
        * UNIX
* IPC
    * Msg
    * Open2
    * Open3
    * Semaphore
    * SysV
* LWP
    * Debug
    * MediaTypes
    * MemberMixin
    * Protocol
    * RobotUA
    * Simple
    * UserAgent
* Math
    * BigFloat
    * BigInt
    * Complex
    * Trig
* MD5
* MIME
    * Base64
    * QuotedPrint
* NDBM_File
* Net
    * Cmd
    * Config
    * Domain
    * DummyInetd
    * FTP
    * hostent
    * libnetFAQ
    * netent
    * Netrc
    * NNTP
    * PH
    * Ping
    * POP3
    * protoent
    * servent
    * SMTP
    * SNPP
    * Time
* O
* ODBM_File
* Opcode
* Pod
    * Checker
    * Find
    * Html
    * InputObjects
    * Man
    * Parser
    * ParseUtils
    * Plainer
    * Select
    * Text
        * Color
        * Termcap
    * Usage
* POSIX
* PPM
    * SOAPClient
    * SOAPServer
* Safe
* SDBM_File
* Search
    * Dict
* SelectSaver
* SelfLoader
* SHA
* Shell
* SOAP
    * Defs
    * Envelope
    * EnvelopeMaker
    * GenericHashSerializer
    * GenericInputStream
    * GenericScalarSerializer
    * Lite
    * OutputStream
    * Packager
    * Parser
    * Transport
        * HTTP
            * Apache
            * CGI
            * Client
            * Server
        * LOCAL
        * MAILTO
        * POP3
        * TCP
    * TypeMapper
* Socket
* Symbol
* Sys
    * Hostname
    * Syslog
* Term
    * ANSIColor
    * Cap
    * Complete
    * ReadLine
* Test
    * Harness
* Text
    * Abbrev
    * ParseWords
    * Soundex
    * Tabs
    * Wrap
* Thread
    * Queue
    * Semaphore
    * Signal
    * Specific
* Tie
    * Array
    * Handle
    * Hash
    * RefHash
    * Scalar
    * SubstrHash
* Time
    * gmtime
    * Local
    * localtime
    * tm
* UDDI
    * Lite
* UNIVERSAL
* URI
    * data
    * Escape
    * file
    * Heuristic
    * ldap
    * URL
    * WithBase
* User
    * grent
    * pwent
* Win32
    * AuthenticateUser
    * ChangeNotify
    * Clipboard
    * Console
    * Event
    * EventLog
    * File
    * FileSecurity
    * Internet
    * IPC
    * Mutex
    * NetAdmin
    * NetResource
    * ODBC
    * OLE
        * Const
        * Enum
        * NEWS
        * NLS
        * TPJ
        * Variant
    * PerfLib
    * Pipe
    * Process
    * Registry
    * Semaphore
    * Service
    * Sound
    * TieRegistry
* Win32API
    * File
    * Net
    * Registry
* WWW
    * RobotRules
        * AnyDBM_File
* XML
    * Element
    * Parser
        * Expat
    * PPD
    * PPMConfig
    * ValidatingElement
* XSLoader


ActivePerl 5.6.0.623 -- Release Notes

Welcome, and thanks for downloading ActivePerl 5.6. This release corresponds to Perl version 5.6.0.

Please note that ActivePerl 600 series builds are NOT binary-compatible with the older 500 series builds. In particular, do not attempt to use extensions or PPM packages built for the 500 series builds with ActivePerl 600 series builds and vice versa.

Binaries for the following platforms are available:

  • Linux x86 for RedHat 6.0 or later

  • Linux x86 for Debian 2.2

  • Solaris sparc for Solaris 2.6

  • Windows x86 for Windows NT and Windows 2000


Installing ActivePerl

ActivePerl can be easily installed in each platform's native format.

Linux (x86)

RedHat 6.0 or later
The RedHat-compatible package is in RPM format. This should be installed as root, using the following command:
    % rpm -i ActivePerl-5.6.0.623-i686-linux-thread-multi.rpm

This package has only been tested with RedHat 6.0, but is expected to be compatible with other RedHat 6.0 compatible installations as well, including RedHat 6.1 installations.

Debian 2.2
The Debian-compatible package is in dpkg format. This should be installed as root, using the following command:
    % dpkg -i ActivePerl-5.6.0.623-i686-linux-thread-multi.deb

This package has only been tested with Debian 2.2, but is expected to be compatible with other Debian 2.2 compatible installations as well.

Solaris (sparc)

The Solaris package is in pkgadd format. This should be installed as root, using the following commands:

    % gunzip ActivePerl-5.6.0.623-sun4-solaris-thread-multi.gz
    % pkgadd -d ActivePerl-5.6.0.623-sun4-solaris-thread-multi

This package has only been tested with Solaris 2.6, but is expected to be compatible with other Solaris 2.6 compatible installations as well, including Solaris 2.7.

Generic ActivePerl Installer for Linux (x86) and Solaris (sparc)

The Generic Installer allows installation as an unprivileged user, and into a user-specified path.

Download the distribution to a temporary directory, extract the files, chdir to the ActivePerl directory and then run the script ``install.sh''. The installation script will prompt you for the target installation directory.

    % tar zxf ActivePerl-5.6.0.623-sun4-solaris-thread-multi.tar.gz
    % cd ActivePerl-5.6.0.623
    % ./install.sh

GNU tar may be required for extracting the files. See the ``Known Issues'' section below for details.

Windows (x86)

The Windows package is in Microsoft Windows Installer format. On Windows NT and Windows9x, you may need to download and install the MSI support package in order to begin the install process. Windows 2000 users do not need any additional software to install the package.

To install the package, simply find the directory containing the package with Explorer, and double-click on the MSI file.

Before you can install ActivePerl, Windows NT and 9x users will need to download and install Windows Installer 1.1 from:

    http://www.ActiveState.com/download/contrib/Microsoft/NT/InstMsi.exe
    http://www.ActiveState.com/download/contrib/Microsoft/9x/InstMsi.exe

If you are installing Perl on behalf of other users, we recommend running the installer with administrative privileges. Running without administrative privileges has the following limitations:

  • The PerlScript feature will be unavailable.

  • ActivePerl applications will not write messages to the event log.

  • Environment variables are set only for the current user.

  • The option to create a file association for Perl files is disabled.

  • Any registry entries created are under HKEY_CURRENT_USER and not under HKEY_LOCAL_MACHINE.

NOTE: DO NOT launch the installation package from a directory for which the ``System'' account does not have read permission. If you do, the Windows Installer Service will not be able to access the MSI file in order to perform the installation. You may get an error message to this effect or it may fail mysteriously.

NOTE: DO NOT attempt to install over a 500 series build of ActivePerl. This package must be installed into a separate directory.


Configuration

The Red Hat, Debian and Sun packages are installed into the /usr/local/ActivePerl-5.6 directory. Add the /usr/local/ActivePerl-5.6/bin directory to your PATH environment variable to conveniently access it. For example, in the C shell:

    % setenv PATH /usr/local/ActivePerl-5.6/bin:$PATH

The Generic ActivePerl installer allows you to install the package anywhere that the user has write permission. Add the bin directory to your PATH environment variable to conveniently access it. For example, in the C shell (assuming you installed into /home/larry/perl-5.6):

    % setenv PATH /home/larry/ActivePerl-5.6/bin:$PATH

On Windows, the installer allows the package to be installed anywhere. We recommend not installing over an existing Perl installation.


Incompatibilities

The following list is a general summary of the known incompatibilities between the 5.6.0 source code release and earlier releases. Be sure to consider these very carefully before upgrading.

  • Compatibility macros for global variables are not available by default, to control namespace pollution. If older extensions don't build because of missing symbols, try ``perl Makefile.PL POLLUTE=1'' first.

  • Subroutines named CHECK are considered special, and will be automatically executed when the compilation of the main program ends. Rename such functions to lower/mixed case.

  • $English::PERL_VERSION is now an alias for $^V (a string) rather than $] (a number). You may need to use the ``%vd'' sprintf format to display this correctly.

  • Literals of the form 1.2.3 parse as chr(1) . chr(2) . chr(3) rather than as "1.2" . 3.

  • rand() may yield a different (but usually more random) sequence due to internal changes.

  • Iterating over hashes may yield a different order than before due to changes in the hashing function used.

  • The undef operator raises an exception when applied to read-only values.

  • The close-on-exec bit is now set on pipe and socket handles as well, if you set $^F high enough.

  • "$$1" always means "${$1}" now, rather than $$ . "1" (which was deprecated in 5.004).

  • delete(), each(), values() and \(%h) operate on aliases to values, instead of on copies. You may need to copy the values explicitly where needed.

  • vec() will raise an exception if the BITS argument is not a power-of-two integer.

  • not followed by parentheses behaves like a list operator. This allows grep not($_), @things to work as expected, but also changes not (1,2,3)[0] to mean (not(1,2,3))[0] instead of not((1,2,3)[0]).

  • The semantics of the bareword prototype (*) has changed to make it possible to pass barewords, as in many builtins.

  • Bitwise operators on 64-bit platforms operate on the entire native width rather than just the lower 32 bits. (You must mask off the excess bits if you don't want them.)

  • More builtins taint their results due to higher security paranoia, when perl is running under taint mode (enabled via the -T switch).

  • If you have a perl installation older than 5.005, note that 5.6.0 won't be binary compatible with it. You will need to recompile all extensions when upgrading from installations older than 5.005. (This only applies when building from the source code--ActivePerl builds based on 5.6.0 are not binary compatible with builds based on 5.005 and earlier.)


Known Issues

All Platforms

A definitive summary of platform-independent changes and known issues in this release is available in perldelta and in the CHANGES log that comes with the ActivePerl distribution.

  • Unicode support still has various known bugs. Please refer to the perlunicode documentation.
    • A literal such as v2000 may be incorrectly parsed as a bareword rather than as a Unicode character if Perl is expecting to read a statement. Use +v2000 if you hit this bug.

Linux and Solaris

  • If you are upgrading from build 613, the default location for the ActivePerl installation when using the native installations on Unix (RedHat RPM, Debian dpkg, or Solaris pkgadd) has changed. Build 613 and earlier installed ActivePerl at /usr/local/perl-5.6, whereas later builds are installed at /usr/local/ActivePerl-5.6. This one-time change avoids confusion with locally installed versions built from the sources, and also avoids installing on top of existing binary-incompatible installations.

  • This build is not binary compatible with build 613 and earlier. If you installed any extensions containing XS code with build 613 or earlier builds (via PPM or otherwise), you will need to reinstall them again.

  • The suidperl executable is not included in this package due to potential security issues. If you wish to use suidperl in your installation, we recommend building Perl from source. The source code for ActivePerl is available at http://www.ActiveState.com/.

  • Some versions of tar on Solaris have bugs that prevent proper extraction of files in the package that have long path names. GNU tar may therefore be required to extract the package into the filesystem correctly. A precompiled version of GNU tar for the sparc platform is available from:
        http://www.sunfreeware.com/

Windows

  • ActivePerl depends on MSVCRT.DLL being installed on the target system. This file ships with Windows 98, Windows NT and Windows 2000 but not with Windows 95. If you do not have this file installed on your system you may experience problems installing and/or running components within ActivePerl.

    You can download a self extracting executable that contains MSVCRT.DLL from:

        ftp://ftp.microsoft.com/softlib/mslfiles/msvcrt.exe

    Save the file in a temporary directory and double click on it to extract the files. Follow the instructions in the ReadMe.txt file contained in the package in order to install the missing file.

  • The fork() emulation has known limitations. See perlfork for a detailed summary. In particular, fork() emulation will not work correctly with extensions that are either not thread-safe, or maintain internal state that cannot be cloned in the psuedo-child process. This caveat currently applies to extensions such as Tk and Storable.

  • It seems that numerous people are being bitten by this error from the ActivePerl MSI installer. The full text of the error message probably looks something lke this:
        Installer Information
        Internal Error 2744. PPM_CONFI, C:\perl\bin.
        "C:\Perl\bin\wPerl.exe" "C:\Perlbin\configPPM.pl"
        "C:\Perl\site\lib\ppm.xml" "D:\downloads\perl\\"
        "C:\Perl\site\lib\ppm.xml~"

    The first thing to note is that you CANNOT install ActivePerl 5.6 over an older version of ActivePerl based on 5.005, such as build 522 or any 500 series build.

    We have determined that one cause of this error message is due to other installations of Perl that may be pointed at by something in the environment.

    Workaround

    The sure-fire solution is to make absolutely certain that no other installations of Perl are on the target machine. Realizing that this is not always possible, you can follow these steps to ensure the other installations will not interfere.

    1) Stop the ``Windows Installer'' service. This can be accomplished from the command prompt using the following command:

        c:\> net stop "Windows Installer"

    2) Temporarily remove or rename PERLLIB and PERL5LIB environment variables in the system environment.

    3) Temporarily remove or rename the following registry values:

        [\\HKEY_LOCAL_MACHINE\Software\Perl] lib = <directory> (REG_SV)
        [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib = <directory> (REG_SV)
        [\\HKEY_LOCAL_MACHINE\Software\Perl] lib-<PerlVersion> = <directory> (REG_SV)
        [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib-<PerlVersion> = <directory>(REG_SV)

    4) Proceed with the installation.

    Once the installation has completed successfully, the above actions may be undone although restoring the environment variables or the registry values may interfere with the proper operation of your new ActivePerl installation.

    In order to perform all of the above steps, you will need to have Administrative privileges on the target machine. If you do not have the required privileges you should contact you Administrator.

    The next version of ActivePerl has a fix for this issue so none of the above actions will have to be taken.

  • Norton AntiVirus 2000 detects VBS.NewLove.A in the file ActivePerl-Winfaq12.html.

    Workaround

    This is a false positive by Norton AntiVirus. ActivePerl-Winfaq12.html has been examined by hand, and it is likely that the following example code is what causes the false report.

        <BLOCKQUOTE>
        <P><CODE>use strict;<BR>
          use Win32::OLE;<BR>
          use Win32::OLE::Const 'Microsoft Outlook';<BR>
          <BR>
          my $Outlook = Win32::OLE-&gt;new('Outlook.Application', 'Quit');<BR>
          my $ol = Win32::OLE::Const-&gt;Load($Outlook);<BR>
          <BR>
          my $namespace = $Outlook-&gt;GetNamespace(&quot;MAPI&quot;);<BR>
          my $Folder = $namespace-&gt;GetDefaultFolder(olFolderInbox);<BR>
          my $NewFolder = $Folder-&gt;Folders-&gt;Add(&quot;Test1&quot;);</CODE></P>
        </BLOCKQUOTE>

    This can be tested by removing the above code from the ActivePerl-Winfaq12.html file and rescanning with Norton AntiVirus. Norton AntiVirus will no longer detect VBS.NewLove.A.

    Symantec has been notified of this issue.

  • The following Microsoft knowledge base articles may be helpful in solving MSI problems:

    Q236597 - OFF2000: Error Message: The Installation Package Could Not Be Opened ... http://support.microsoft.com/support/kb/articles/Q236/5/97.ASP

    Q224094 - OFF2000: Error Message: This Application Requires the Windows Installer to Run http://support.microsoft.com/support/kb/articles/Q224/0/94.ASP

    Q247532 - Works 2000 Err Msg: Installer Terminated Prematurely http://support.microsoft.com/support/kb/articles/Q247/5/32.ASP

    ``Error 1303. The installer has insufficient privileges...'' Running Office Setup http://support.microsoft.com/support/kb/articles/Q228/6/58.ASP

    Error Message: Error 1316 Running Setup for Admin Installation http://support.microsoft.com/support/kb/articles/Q228/5/92.ASP

    Error 1327 Invalid Drive During Office Installation http://support.microsoft.com/support/kb/articles/Q217/6/66.ASP

  • On Windows9x, the PATH environment variable needs to be set manually. This is because the Microsoft Installer does not recognize ``path <some_path>'' as a command in the autoexec.bat file that modifies the PATH envrionment variable and therefor clobbers the contents of the PATH if it was set in this way.

Further Information

The Perl distribution comes with extensive documentation. On Unix platforms, all the standard documentation is installed as man pages under the Perl install location. The location of the man pages may need to be added to the MANPATH environment variable in order to access them. For example, in the C shell:

    % setenv MANPATH /usr/local/ActivePerl-5.6/man:$MANPATH

The documentation is installed in HTML format on all platforms. If ActivePerl was installed in /usr/local/ActivePerl-5.6 then the HTML documentation would be located in /usr/local/ActivePerl-5.6/html.

On Windows, the standard documentation along with Windows-specific Perl documentation is installed in HTML format, and is accessible from the ``Start'' menu.

Updated versions of the HTML documentation will always be available at the ActiveState website:

    http://www.ActiveState.com/ActivePerl/


Reporting Problems

Please report any problems you encounter with this release at the following location:

    http://bugs.ActiveState.com/ActivePerl/

If you do not have web access, reports can be also sent via email to ActivePerl-Bugs@ActiveState.com. Please be sure to include detailed information about the platform in your message.

As far as possible, please ensure that there is enough information in the report to reproduce the bug elsewhere. It also helps to submit a minimal test case that exhibits the bug.