From 2b37efcc2bc957549bbeb5c71adf3fced634e4c9 Mon Sep 17 00:00:00 2001 From: Steve Peters Date: Tue, 13 Dec 2005 12:17:57 +0000 Subject: Renaming of some of Pod::Simple's test files to make it more 8.3 friendly. p4raw-id: //depot/perl@26341 --- MANIFEST | 20 +- lib/Pod/Simple/t/junk1.pod | 8 + lib/Pod/Simple/t/junk1_out.txt | 13 + lib/Pod/Simple/t/junk2.pod | 6 + lib/Pod/Simple/t/junk2_out.txt | 13 + lib/Pod/Simple/t/perlcyg.pod | 592 ++++++++++++ lib/Pod/Simple/t/perlcyg_out.txt | 249 ++++++ lib/Pod/Simple/t/perlfaq3.pod | 814 +++++++++++++++++ lib/Pod/Simple/t/perlfaq3_out.txt | 266 ++++++ lib/Pod/Simple/t/perlvar.pod | 1234 ++++++++++++++++++++++++++ lib/Pod/Simple/t/perlvar_out.txt | 406 +++++++++ lib/Pod/Simple/t/render.t | 10 +- lib/Pod/Simple/t/test_junk1.pod | 8 - lib/Pod/Simple/t/test_junk1_out.txt | 13 - lib/Pod/Simple/t/test_junk2.pod | 6 - lib/Pod/Simple/t/test_junk2_out.txt | 13 - lib/Pod/Simple/t/test_old_perlcygwin.pod | 592 ------------ lib/Pod/Simple/t/test_old_perlcygwin_out.txt | 249 ------ lib/Pod/Simple/t/test_old_perlfaq3.pod | 814 ----------------- lib/Pod/Simple/t/test_old_perlfaq3_out.txt | 266 ------ lib/Pod/Simple/t/test_old_perlvar.pod | 1234 -------------------------- lib/Pod/Simple/t/test_old_perlvar_out.txt | 406 --------- 22 files changed, 3616 insertions(+), 3616 deletions(-) create mode 100644 lib/Pod/Simple/t/junk1.pod create mode 100644 lib/Pod/Simple/t/junk1_out.txt create mode 100644 lib/Pod/Simple/t/junk2.pod create mode 100644 lib/Pod/Simple/t/junk2_out.txt create mode 100644 lib/Pod/Simple/t/perlcyg.pod create mode 100644 lib/Pod/Simple/t/perlcyg_out.txt create mode 100644 lib/Pod/Simple/t/perlfaq3.pod create mode 100644 lib/Pod/Simple/t/perlfaq3_out.txt create mode 100644 lib/Pod/Simple/t/perlvar.pod create mode 100644 lib/Pod/Simple/t/perlvar_out.txt delete mode 100644 lib/Pod/Simple/t/test_junk1.pod delete mode 100644 lib/Pod/Simple/t/test_junk1_out.txt delete mode 100644 lib/Pod/Simple/t/test_junk2.pod delete mode 100644 lib/Pod/Simple/t/test_junk2_out.txt delete mode 100644 lib/Pod/Simple/t/test_old_perlcygwin.pod delete mode 100644 lib/Pod/Simple/t/test_old_perlcygwin_out.txt delete mode 100644 lib/Pod/Simple/t/test_old_perlfaq3.pod delete mode 100644 lib/Pod/Simple/t/test_old_perlfaq3_out.txt delete mode 100644 lib/Pod/Simple/t/test_old_perlvar.pod delete mode 100644 lib/Pod/Simple/t/test_old_perlvar_out.txt diff --git a/MANIFEST b/MANIFEST index 3e0354a822..5ce284805b 100644 --- a/MANIFEST +++ b/MANIFEST @@ -2048,10 +2048,10 @@ lib/Pod/Simple/t/search_28_glob_z_kleene_k.t Pod::Simple test file lib/Pod/Simple/t/search_29_glob_z_qmark_k.t Pod::Simple test file lib/Pod/Simple/t/search_50survey_inc.t Pod::Simple test file lib/Pod/Simple/t/stree.t Pod::Simple test file -lib/Pod/Simple/t/test_junk1_out.txt Pod::Simple test file -lib/Pod/Simple/t/test_junk1.pod Pod::Simple test file -lib/Pod/Simple/t/test_junk2_out.txt Pod::Simple test file -lib/Pod/Simple/t/test_junk2.pod Pod::Simple test file +lib/Pod/Simple/t/junk1_out.txt Pod::Simple test file +lib/Pod/Simple/t/junk1.pod Pod::Simple test file +lib/Pod/Simple/t/junk2_out.txt Pod::Simple test file +lib/Pod/Simple/t/junk2.pod Pod::Simple test file lib/Pod/Simple/t/test_lib/Blorm.pm Pod::Simple test file lib/Pod/Simple/t/test_lib/hink_honk/Glunk.pod Pod::Simple test file lib/Pod/Simple/t/test_lib/hink_honk/readme.txt Pod::Simple test file @@ -2065,12 +2065,12 @@ lib/Pod/Simple/t/test_lib/zikzik.pod Pod::Simple test file lib/Pod/Simple/t/test_lib/Zonk/Fiddle.txt Pod::Simple test file lib/Pod/Simple/t/test_lib/Zonk/Pronk.pm Pod::Simple test file lib/Pod/Simple/t/test_lib/Zonk/Veng.pm Pod::Simple test file -lib/Pod/Simple/t/test_old_perlcygwin_out.txt Pod::Simple test file -lib/Pod/Simple/t/test_old_perlcygwin.pod Pod::Simple test file -lib/Pod/Simple/t/test_old_perlfaq3_out.txt Pod::Simple test file -lib/Pod/Simple/t/test_old_perlfaq3.pod Pod::Simple test file -lib/Pod/Simple/t/test_old_perlvar_out.txt Pod::Simple test file -lib/Pod/Simple/t/test_old_perlvar.pod Pod::Simple test file +lib/Pod/Simple/t/perlcyg_out.txt Pod::Simple test file +lib/Pod/Simple/t/perlcyg.pod Pod::Simple test file +lib/Pod/Simple/t/perlfaq3_out.txt Pod::Simple test file +lib/Pod/Simple/t/perlfaq3.pod Pod::Simple test file +lib/Pod/Simple/t/perlvar_out.txt Pod::Simple test file +lib/Pod/Simple/t/perlvar.pod Pod::Simple test file lib/Pod/Simple/t/verbatim_formatted.t Pod::Simple test file lib/Pod/Simple/t/verbatims.t Pod::Simple test file lib/Pod/Simple/t/x_nixer.t Pod::Simple test file diff --git a/lib/Pod/Simple/t/junk1.pod b/lib/Pod/Simple/t/junk1.pod new file mode 100644 index 0000000000..402880109e --- /dev/null +++ b/lib/Pod/Simple/t/junk1.pod @@ -0,0 +1,8 @@ + +=cut + +=head9 I like pie + +B diff --git a/lib/Pod/Simple/t/junk1_out.txt b/lib/Pod/Simple/t/junk1_out.txt new file mode 100644 index 0000000000..1b4559ac0f --- /dev/null +++ b/lib/Pod/Simple/t/junk1_out.txt @@ -0,0 +1,13 @@ +pie is nice E + +POD ERRORS +Hey! The above document had some coding errors, which are explained below: + +Around line 2: + =cut found outside a pod block. Skipping to next block. +Around line 4: + Unknown directive: =head9 +Around line 6: + Unterminated B<...> sequence +Around line 8: + Unknown E content in E diff --git a/lib/Pod/Simple/t/junk2.pod b/lib/Pod/Simple/t/junk2.pod new file mode 100644 index 0000000000..696aabfbfa --- /dev/null +++ b/lib/Pod/Simple/t/junk2.pod @@ -0,0 +1,6 @@ + +=head9 I like pie + +B diff --git a/lib/Pod/Simple/t/junk2_out.txt b/lib/Pod/Simple/t/junk2_out.txt new file mode 100644 index 0000000000..5612c7d3a1 --- /dev/null +++ b/lib/Pod/Simple/t/junk2_out.txt @@ -0,0 +1,13 @@ +pie is nice + +E + +POD ERRORS +Hey! The above document had some coding errors, which are explained below: +Around line 2: + Unknown directive: =head9 +Around line 4: + Unterminated B<...> sequence +Around line 6: + Unknown E content in E + diff --git a/lib/Pod/Simple/t/perlcyg.pod b/lib/Pod/Simple/t/perlcyg.pod new file mode 100644 index 0000000000..6264a15788 --- /dev/null +++ b/lib/Pod/Simple/t/perlcyg.pod @@ -0,0 +1,592 @@ +If you read this file _as_is_, just ignore the funny characters you +see. It is written in the POD format (see pod/perlpod.pod) which is +specially designed to be readable as is. + +=head1 NAME + +README.cygwin - Perl for Cygwin + +=head1 SYNOPSIS + +This document will help you configure, make, test and install Perl +on Cygwin. This document also describes features of Cygwin that will +affect how Perl behaves at runtime. + +B There are pre-built Perl packages available for Cygwin and a +version of Perl is provided on the Cygwin CD. If you do not need to +customize the configuration, consider using one of these packages: + + http://cygutils.netpedia.net/ + +=head1 PREREQUISITES + +=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) + +The Cygwin tools are ports of the popular GNU development tools for Win32 +platforms. They run thanks to the Cygwin library which provides the UNIX +system calls and environment these programs expect. More information +about this project can be found at: + + http://www.cygwin.com/ + +A recent net or commercial release of Cygwin is required. + +At the time this document was last updated, Cygwin 1.1.5 was current. + +B At this point, minimal effort has been made to provide +compatibility with old (beta) Cygwin releases. The focus has been to +provide a high quality release and not worry about working around old +bugs. If you wish to use Perl with Cygwin B20.1 or earlier, consider +using perl5.005_03, which is available in source and binary form at +C. If there is significant demand, +a patch kit can be developed to port back to earlier Cygwin versions. + +=head2 Cygwin Configuration + +While building Perl some changes may be necessary to your Cygwin setup so +that Perl builds cleanly. These changes are B required for normal +Perl usage. + +B The binaries that are built will run on all Win32 versions. +They do not depend on your host system (Win9x/WinME, WinNT/Win2K) +or your Cygwin configuration (I, I, binary/text mounts). +The only dependencies come from hard-coded pathnames like C. +However, your host system and Cygwin configuration will affect Perl's +runtime behavior (see L). + +=over 4 + +=item * C + +Set the C environment variable so that Configure finds the Cygwin +versions of programs. Any Windows directories should be removed or +moved to the end of your C. + +=item * I + +If you do not have I (which is part of the I package), +Configure will B prompt you to install I pages. + +=item * Permissions + +On WinNT with either the I or I C settings, directory +and file permissions may not be set correctly. Since the build process +creates directories and files, to be safe you may want to run a `C' on the entire Perl source tree. + +Also, it is a well known WinNT "feature" that files created by a login +that is a member of the I group will be owned by the +I group. Depending on your umask, you may find that you +can not write to files that you just created (because you are no longer +the owner). When using the I C setting, this is not an +issue because it "corrects" the ownership to what you would expect on +a UNIX system. + +=back + +=head1 CONFIGURE + +The default options gathered by Configure with the assistance of +F will build a Perl that supports dynamic loading +(which requires a shared F). + +This will run Configure and keep a record: + + ./Configure 2>&1 | tee log.configure + +If you are willing to accept all the defaults run Configure with B<-de>. +However, several useful customizations are available. + +=head2 Strip Binaries + +It is possible to strip the EXEs and DLLs created by the build process. +The resulting binaries will be significantly smaller. If you want the +binaries to be stripped, you can either add a B<-s> option when Configure +prompts you, + + Any additional ld flags (NOT including libraries)? [none] -s + Any special flags to pass to gcc to use dynamic linking? [none] -s + Any special flags to pass to ld2 to create a dynamically loaded library? + [none] -s + +or you can edit F and uncomment the relevant variables +near the end of the file. + +=head2 Optional Libraries + +Several Perl functions and modules depend on the existence of +some optional libraries. Configure will find them if they are +installed in one of the directories listed as being used for library +searches. Pre-built packages for most of these are available at +C. + +=over 4 + +=item * C<-lcrypt> + +The crypt package distributed with Cygwin is a Linux compatible 56-bit +DES crypt port by Corinna Vinschen. + +Alternatively, the crypt libraries in GNU libc have been ported to Cygwin. + +The DES based Ultra Fast Crypt port was done by Alexey Truhan: + + ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz + +NOTE: There are various export restrictions on DES implementations, +see the glibc README for more details. + +The MD5 port was done by Andy Piper: + + ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz + +=item * C<-lgdbm> (C) + +GDBM is available for Cygwin. GDBM's ndbm/dbm compatibility feature +also makes C and C possible (although they add +little extra value). + +NOTE: The ndbm/dbm emulations only completely work on NTFS partitions. + +=item * C<-ldb> (C) + +BerkeleyDB is available for Cygwin. Some details can be found in +F. + +NOTE: The BerkeleyDB library only completely works on NTFS partitions. + +=item * C<-lcygipc> (C) + +A port of SysV IPC is available for Cygwin. + +NOTE: This has B been extensively tested. In particular, +C is undefined because it fails a Configure test +and on Win9x the I functions seem to hang. It also creates +a compile time dependency because F includes F<> +and F<> (which will be required in the future when compiling +CPAN modules). + +=back + +=head2 Configure-time Options + +The F document describes several Configure-time options. Some of +these will work with Cygwin, others are not yet possible. Also, some of +these are experimental. You can either select an option when Configure +prompts you or you can define (undefine) symbols on the command line. + +=over 4 + +=item * C<-Uusedl> + +Undefining this symbol forces Perl to be compiled statically. + +=item * C<-Uusemymalloc> + +By default Perl uses the malloc() included with the Perl source. If you +want to force Perl to build with the system malloc() undefine this symbol. + +=item * C<-Dusemultiplicity> + +Multiplicity is required when embedding Perl in a C program and using +more than one interpreter instance. This works with the Cygwin port. + +=item * C<-Duseperlio> + +The PerlIO abstraction works with the Cygwin port. + +=item * C<-Duse64bitint> + +I supports 64-bit integers. However, several additional long long +functions are necessary to use them within Perl (I<{strtol,strtoul}l>). +These are B yet available with Cygwin. + +=item * C<-Duselongdouble> + +I supports long doubles (12 bytes). However, several additional +long double math functions are necessary to use them within Perl +(I<{atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold>). +These are B yet available with Cygwin. + +=item * C<-Dusethreads> + +POSIX threads are B yet implemented in Cygwin. + +=item * C<-Duselargefiles> + +Although Win32 supports large files, Cygwin currently uses 32-bit integers +for internal size and position calculations. + +=back + +=head2 Suspicious Warnings + +You may see some messages during Configure that seem suspicious. + +=over 4 + +=item * I + +I is needed to build dynamic libraries, but it does not exist +when dlsym() checking occurs (it is not created until `C' runs). +You will see the following message: + + Checking whether your dlsym() needs a leading underscore ... + ld2: not found + I can't compile and run the test program. + I'm guessing that dlsym doesn't need a leading underscore. + +Since the guess is correct, this is not a problem. + +=item * Win9x and C + +Win9x does not correctly report C with a non-blocking read on a +closed pipe. You will see the following messages: + + But it also returns -1 to signal EOF, so be careful! + WARNING: you can't distinguish between EOF and no data! + + *** WHOA THERE!!! *** + The recommended value for $d_eofnblk on this machine was "define"! + Keep the recommended value? [y] + +At least for consistency with WinNT, you should keep the recommended +value. + +=item * Compiler/Preprocessor defines + +The following error occurs because of the Cygwin C<#define> of +C<_LONG_DOUBLE>: + + Guessing which symbols your C compiler and preprocessor define... + try.c:: parse error + +This failure does not seem to cause any problems. + +=back + +=head1 MAKE + +Simply run I and wait: + + make 2>&1 | tee log.make + +=head2 Warnings + +Warnings like these are normal: + + warning: overriding commands for target + warning: ignoring old commands for target + + dllwrap: no export definition file provided + dllwrap: creating one, but that may not be what you want + +=head2 ld2 + +During `C', I will be created and installed in your $installbin +directory (where you said to put public executables). It does not +wait until the `C' process to install the I script, +this is because the remainder of the `C' refers to I without +fully specifying its path and does this from multiple subdirectories. +The assumption is that $installbin is in your current C. If this +is not the case `C' will fail at some point. If this happens, +just manually copy I from the source directory to somewhere in +your C. + +=head1 TEST + +There are two steps to running the test suite: + + make test 2>&1 | tee log.make-test + + cd t;./perl harness 2>&1 | tee ../log.harness + +The same tests are run both times, but more information is provided when +running as `C<./perl harness>'. + +Test results vary depending on your host system and your Cygwin +configuration. If a test can pass in some Cygwin setup, it is always +attempted and explainable test failures are documented. It is possible +for Perl to pass all the tests, but it is more likely that some tests +will fail for one of the reasons listed below. + +=head2 File Permissions + +UNIX file permissions are based on sets of mode bits for +{read,write,execute} for each {user,group,other}. By default Cygwin +only tracks the Win32 read-only attribute represented as the UNIX file +user write bit (files are always readable, files are executable if they +have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are +always readable and executable). On WinNT with the I C +setting, the additional mode bits are stored as extended file attributes. +On WinNT with the I C setting, permissions use the standard +WinNT security descriptors and access control lists. Without one of +these options, these tests will fail: + + Failed Test List of failed + ------------------------------------ + io/fs.t 5, 7, 9-10 + lib/anydbm.t 2 + lib/db-btree.t 20 + lib/db-hash.t 16 + lib/db-recno.t 18 + lib/gdbm.t 2 + lib/ndbm.t 2 + lib/odbm.t 2 + lib/sdbm.t 2 + op/stat.t 9, 20 (.tmp not an executable extension) + +=head2 Hard Links + +FAT partitions do not support hard links (whereas NTFS does), in which +case Cygwin implements link() by copying the file. On remote (network) +drives Cygwin's stat() always sets C to 1, so the link count +for remote directories and files is not available. In either case, +these tests will fail: + + Failed Test List of failed + ------------------------------------ + io/fs.t 4 + op/stat.t 3 + +=head2 Filetime Granularity + +On FAT partitions the filetime granularity is 2 seconds. The following +test will fail: + + Failed Test List of failed + ------------------------------------ + io/fs.t 18 + +=head2 Tainting Checks + +When Perl is running in taint mode, C<$ENV{PATH}> is considered tainted +and not used, so DLLs not in the default system directories will not +be found. While the tests are running you will see warnings popup from +the system with messages like: + + Win9x + Error Starting Program + A required .DLL file, CYGWIN1.DLL, was not found + + WinNT + perl.exe - Unable to Locate DLL + The dynamic link library cygwin1.dll could not be found in the + specified path ... + +Just click OK and ignore them. When running `C', 2 popups +occur. During `C<./perl harness>', 4 popups occur. Also, these tests +will fail: + + Failed Test List of failed + ------------------------------------ + op/taint.t 1, 3, 31, 37 + +Alternatively, you can copy F into the directory where the +tests run: + + cp /bin/cygwin1.dll t + +or one of the Windows system directories (although, this is B +recommended). + +=head2 /etc/group + +Cygwin does not require F, in which case the F +test will be skipped. The check performed by F expects to +see entries that use the members field, otherwise this test will fail: + + Failed Test List of failed + ------------------------------------ + op/grent.t 1 + +=head2 Script Portability + +Cygwin does an outstanding job of providing UNIX-like semantics on top of +Win32 systems. However, in addition to the items noted above, there are +some differences that you should know about. This is a very brief guide +to portability, more information can be found in the Cygwin documentation. + +=over 4 + +=item * Pathnames + +Cygwin pathnames can be separated by forward (F) or backward (F<\>) +slashes. They may also begin with drive letters (F) or Universal +Naming Codes (F). DOS device names (F, F, F, +F, F, F) are invalid as base filenames. However, they +can be used in extensions (e.g., F). Names may contain all +printable characters except these: + + : * ? " < > | + +File names are case insensitive, but case preserving. A pathname that +contains a backslash or drive letter is a Win32 pathname (and not subject +to the translations applied to POSIX style pathnames). + +=item * Text/Binary + +When a file is opened it is in either text or binary mode. In text mode +a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default +mode for an open() is determined by the mode of the mount that underlies +the file. Perl provides a binmode() function to set binary mode on files +that otherwise would be treated as text. sysopen() with the C +flag sets text mode on files that otherwise would be treated as binary: + + sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) + +lseek(), tell() and sysseek() only work with files opened in binary mode. + +The text/binary issue is covered at length in the Cygwin documentation. + +=item * F<.exe> + +The Cygwin stat(), lstat() and readlink() functions make the F<.exe> +extension transparent by looking for F when you ask for F +(unless a F also exists). Cygwin does not require a F<.exe> +extension, but I adds it automatically when building a program. +However, when accessing an executable as a normal file (e.g., I +in a makefile) the F<.exe> is not transparent. The I included +with Cygwin automatically appends a F<.exe> when necessary. + +=item * chown() + +On WinNT chown() can change a file's user and group IDs. On Win9x chown() +is a no-op, although this is appropriate since there is no security model. + +=item * Miscellaneous + +File locking using the C command to fcntl() is a stub that +returns C. + +Win9x can not rename() an open file (although WinNT can). + +The Cygwin chroot() implementation has holes (it can not restrict file +access by native Win32 programs). + +=back + +=head1 INSTALL + +This will install Perl, including I pages. + + make install | tee log.make-install + +NOTE: If C is redirected `C' will B prompt +you to install I into F. + +You may need to be I to run `C'. If you +are not, you must have write access to the directories in question. + +Information on installing the Perl documentation in HTML format can be +found in the F document. + +=head1 MANIFEST + +These are the files in the Perl release that contain references to Cygwin. +These very brief notes attempt to explain the reason for all conditional +code. Hopefully, keeping this up to date will allow the Cygwin port to +be kept as clean as possible. + +=over 4 + +=item Documentation + + INSTALL README.cygwin README.win32 MANIFEST + Changes Changes5.005 Changes5.004 Changes5.6 + pod/perl.pod pod/perlport.pod pod/perlfaq3.pod + pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod + pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod + +=item Build, Configure, Make, Install + + cygwin/Makefile.SHs + cygwin/ld2.in + cygwin/perlld.in + ext/IPC/SysV/hints/cygwin.pl + ext/NDBM_File/hints/cygwin.pl + ext/ODBM_File/hints/cygwin.pl + hints/cygwin.sh + Configure - help finding hints from uname, + shared libperl required for dynamic loading + Makefile.SH - linklibperl + Porting/patchls - cygwin in port list + installman - man pages with :: translated to . + installperl - install dll/ld2/perlld, install to pods + makedepend.SH - uwinfix + +=item Tests + + t/io/tell.t - binmode + t/lib/b.t - ignore Cwd from os_extras + t/lib/glob-basic.t - Win32 directory list access differs from read mode + t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// + t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk + (cache manager sometimes preserves ctime of file + previously created and deleted), no -u (setuid) + +=item Compiled Perl Source + + EXTERN.h - __declspec(dllimport) + XSUB.h - __declspec(dllexport) + cygwin/cygwin.c - os_extras (getcwd, spawn) + perl.c - os_extras + perl.h - binmode + doio.c - win9x can not rename a file when it is open + pp_sys.c - do not define h_errno, pp_system with spawn + util.c - use setenv + +=item Compiled Module Source + + ext/POSIX/POSIX.xs - tzname defined externally + ext/SDBM_File/sdbm/pair.c + - EXTCONST needs to be redefined from EXTERN.h + ext/SDBM_File/sdbm/sdbm.c + - binary open + +=item Perl Modules/Scripts + + lib/Cwd.pm - hook to internal Cwd::cwd + lib/ExtUtils/MakeMaker.pm + - require MM_Cygwin.pm + lib/ExtUtils/MM_Cygwin.pm + - canonpath, cflags, manifypods, perl_archive + lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 + lib/File/Spec/Unix.pm - preserve //unc + lib/File/Temp.pm - no directory sticky bit + lib/perl5db.pl - use stdin not /dev/tty + utils/perldoc.PL - version comment + +=back + +=head1 BUGS + +When I starts, it warns about overriding commands for F. + +`C' does not remove library F<.def> or F<.exe.stackdump> +files. + +The I script contains references to the source directory. You should +change these to $installbin after `C'. + +Support for swapping real and effective user and group IDs is incomplete. +On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid(). +However, additional Cygwin calls for manipulating WinNT access tokens +and security contexts are required. + +When building DLLs, `C' is used to export +global symbols. It might be better to generate an explicit F<.def> file +(see F). Also, DLLs can now be build with `C'. + +=head1 AUTHORS + +Charles Wilson , +Eric Fifer , +alexander smishlajev , +Steven Morlock , +Sebastien Barre , +Teun Burgers . + +=head1 HISTORY + +Last updated: 9 November 2000 diff --git a/lib/Pod/Simple/t/perlcyg_out.txt b/lib/Pod/Simple/t/perlcyg_out.txt new file mode 100644 index 0000000000..d834344d6f --- /dev/null +++ b/lib/Pod/Simple/t/perlcyg_out.txt @@ -0,0 +1,249 @@ +NAME +README.cygwin - Perl for Cygwin +SYNOPSIS +This document will help you configure, make, test and install Perl on Cygwin. This document also describes features of Cygwin that will affect how Perl behaves at runtime. +NOTE: There are pre-built Perl packages available for Cygwin and a version of Perl is provided on the Cygwin CD. If you do not need to customize the configuration, consider using one of these packages: + http://cygutils.netpedia.net/ +PREREQUISITES +Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) +The Cygwin tools are ports of the popular GNU development tools for Win32 platforms. They run thanks to the Cygwin library which provides the UNIX system calls and environment these programs expect. More information about this project can be found at: + http://www.cygwin.com/ +A recent net or commercial release of Cygwin is required. +At the time this document was last updated, Cygwin 1.1.5 was current. +NOTE: At this point, minimal effort has been made to provide compatibility with old (beta) Cygwin releases. The focus has been to provide a high quality release and not worry about working around old bugs. If you wish to use Perl with Cygwin B20.1 or earlier, consider using perl5.005_03, which is available in source and binary form at http://cygutils.netpedia.net/. If there is significant demand, a patch kit can be developed to port back to earlier Cygwin versions. +Cygwin Configuration +While building Perl some changes may be necessary to your Cygwin setup so that Perl builds cleanly. These changes are not required for normal Perl usage. +NOTE: The binaries that are built will run on all Win32 versions. They do not depend on your host system (Win9x/WinME, WinNT/Win2K) or your Cygwin configuration (ntea, ntsec, binary/text mounts). The only dependencies come from hard-coded pathnames like /usr/local. However, your host system and Cygwin configuration will affect Perl's runtime behavior (see "TEST"). +PATH +Set the PATH environment variable so that Configure finds the Cygwin versions of programs. Any Windows directories should be removed or moved to the end of your PATH. +nroff +If you do not have nroff (which is part of the groff package), Configure will not prompt you to install man pages. +Permissions +On WinNT with either the ntea or ntsec CYGWIN settings, directory and file permissions may not be set correctly. Since the build process creates directories and files, to be safe you may want to run a `chmod -R +w *' on the entire Perl source tree. +Also, it is a well known WinNT "feature" that files created by a login that is a member of the Administrators group will be owned by the Administrators group. Depending on your umask, you may find that you can not write to files that you just created (because you are no longer the owner). When using the ntsec CYGWIN setting, this is not an issue because it "corrects" the ownership to what you would expect on a UNIX system. +CONFIGURE +The default options gathered by Configure with the assistance of hints/cygwin.sh will build a Perl that supports dynamic loading (which requires a shared libperl.dll). +This will run Configure and keep a record: + ./Configure 2>&1 | tee log.configure +If you are willing to accept all the defaults run Configure with -de. However, several useful customizations are available. +Strip Binaries +It is possible to strip the EXEs and DLLs created by the build process. The resulting binaries will be significantly smaller. If you want the binaries to be stripped, you can either add a -s option when Configure prompts you, + Any additional ld flags (NOT including libraries)? [none] -s + Any special flags to pass to gcc to use dynamic linking? [none] -s + Any special flags to pass to ld2 to create a dynamically loaded library? + [none] -s +or you can edit hints/cygwin.sh and uncomment the relevant variables near the end of the file. +Optional Libraries +Several Perl functions and modules depend on the existence of some optional libraries. Configure will find them if they are installed in one of the directories listed as being used for library searches. Pre-built packages for most of these are available at http://cygutils.netpedia.net/. +-lcrypt +The crypt package distributed with Cygwin is a Linux compatible 56-bit DES crypt port by Corinna Vinschen. +Alternatively, the crypt libraries in GNU libc have been ported to Cygwin. +The DES based Ultra Fast Crypt port was done by Alexey Truhan: + ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz +NOTE: There are various export restrictions on DES implementations, see the glibc README for more details. +The MD5 port was done by Andy Piper: + ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz +-lgdbm (use GDBM_File) +GDBM is available for Cygwin. GDBM's ndbm/dbm compatibility feature also makes NDBM_File and ODBM_File possible (although they add little extra value). +NOTE: The ndbm/dbm emulations only completely work on NTFS partitions. +-ldb (use DB_File) +BerkeleyDB is available for Cygwin. Some details can be found in ext/DB_File/DB_File.pm. +NOTE: The BerkeleyDB library only completely works on NTFS partitions. +-lcygipc (use IPC::SysV) +A port of SysV IPC is available for Cygwin. +NOTE: This has not been extensively tested. In particular, d_semctl_semun is undefined because it fails a Configure test and on Win9x the shm*() functions seem to hang. It also creates a compile time dependency because perl.h includes and (which will be required in the future when compiling CPAN modules). +Configure-time Options +The INSTALL document describes several Configure-time options. Some of these will work with Cygwin, others are not yet possible. Also, some of these are experimental. You can either select an option when Configure prompts you or you can define (undefine) symbols on the command line. +-Uusedl +Undefining this symbol forces Perl to be compiled statically. +-Uusemymalloc +By default Perl uses the malloc() included with the Perl source. If you want to force Perl to build with the system malloc() undefine this symbol. +-Dusemultiplicity +Multiplicity is required when embedding Perl in a C program and using more than one interpreter instance. This works with the Cygwin port. +-Duseperlio +The PerlIO abstraction works with the Cygwin port. +-Duse64bitint +gcc supports 64-bit integers. However, several additional long long functions are necessary to use them within Perl ({strtol,strtoul}l). These are not yet available with Cygwin. +-Duselongdouble +gcc supports long doubles (12 bytes). However, several additional long double math functions are necessary to use them within Perl ({atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold). These are not yet available with Cygwin. +-Dusethreads +POSIX threads are not yet implemented in Cygwin. +-Duselargefiles +Although Win32 supports large files, Cygwin currently uses 32-bit integers for internal size and position calculations. +Suspicious Warnings +You may see some messages during Configure that seem suspicious. +dlsym() +ld2 is needed to build dynamic libraries, but it does not exist when dlsym() checking occurs (it is not created until `make' runs). You will see the following message: + Checking whether your dlsym() needs a leading underscore ... + ld2: not found + I can't compile and run the test program. + I'm guessing that dlsym doesn't need a leading underscore. +Since the guess is correct, this is not a problem. +Win9x and d_eofnblk +Win9x does not correctly report EOF with a non-blocking read on a closed pipe. You will see the following messages: + But it also returns -1 to signal EOF, so be careful! + WARNING: you can't distinguish between EOF and no data! + *** WHOA THERE!!! *** + The recommended value for $d_eofnblk on this machine was "define"! + Keep the recommended value? [y] +At least for consistency with WinNT, you should keep the recommended value. +Compiler/Preprocessor defines +The following error occurs because of the Cygwin #define of _LONG_DOUBLE: + Guessing which symbols your C compiler and preprocessor define... + try.c:: parse error +This failure does not seem to cause any problems. +MAKE +Simply run make and wait: + make 2>&1 | tee log.make +Warnings +Warnings like these are normal: + warning: overriding commands for target + warning: ignoring old commands for target + dllwrap: no export definition file provided + dllwrap: creating one, but that may not be what you want +ld2 +During `make', ld2 will be created and installed in your $installbin directory (where you said to put public executables). It does not wait until the `make install' process to install the ld2 script, this is because the remainder of the `make' refers to ld2 without fully specifying its path and does this from multiple subdirectories. The assumption is that $installbin is in your current PATH. If this is not the case `make' will fail at some point. If this happens, just manually copy ld2 from the source directory to somewhere in your PATH. +TEST +There are two steps to running the test suite: + make test 2>&1 | tee log.make-test + cd t;./perl harness 2>&1 | tee ../log.harness +The same tests are run both times, but more information is provided when running as `./perl harness'. +Test results vary depending on your host system and your Cygwin configuration. If a test can pass in some Cygwin setup, it is always attempted and explainable test failures are documented. It is possible for Perl to pass all the tests, but it is more likely that some tests will fail for one of the reasons listed below. +File Permissions +UNIX file permissions are based on sets of mode bits for {read,write,execute} for each {user,group,other}. By default Cygwin only tracks the Win32 read-only attribute represented as the UNIX file user write bit (files are always readable, files are executable if they have a .{com,bat,exe} extension or begin with #!, directories are always readable and executable). On WinNT with the ntea CYGWIN setting, the additional mode bits are stored as extended file attributes. On WinNT with the ntsec CYGWIN setting, permissions use the standard WinNT security descriptors and access control lists. Without one of these options, these tests will fail: + Failed Test List of failed + ------------------------------------ + io/fs.t 5, 7, 9-10 + lib/anydbm.t 2 + lib/db-btree.t 20 + lib/db-hash.t 16 + lib/db-recno.t 18 + lib/gdbm.t 2 + lib/ndbm.t 2 + lib/odbm.t 2 + lib/sdbm.t 2 + op/stat.t 9, 20 (.tmp not an executable extension) +Hard Links +FAT partitions do not support hard links (whereas NTFS does), in which case Cygwin implements link() by copying the file. On remote (network) drives Cygwin's stat() always sets st_nlink to 1, so the link count for remote directories and files is not available. In either case, these tests will fail: + Failed Test List of failed + ------------------------------------ + io/fs.t 4 + op/stat.t 3 +Filetime Granularity +On FAT partitions the filetime granularity is 2 seconds. The following test will fail: + Failed Test List of failed + ------------------------------------ + io/fs.t 18 +Tainting Checks +When Perl is running in taint mode, $ENV{PATH} is considered tainted and not used, so DLLs not in the default system directories will not be found. While the tests are running you will see warnings popup from the system with messages like: + Win9x + Error Starting Program + A required .DLL file, CYGWIN1.DLL, was not found + WinNT + perl.exe - Unable to Locate DLL + The dynamic link library cygwin1.dll could not be found in the + specified path ... +Just click OK and ignore them. When running `make test', 2 popups occur. During `./perl harness', 4 popups occur. Also, these tests will fail: + Failed Test List of failed + ------------------------------------ + op/taint.t 1, 3, 31, 37 +Alternatively, you can copy cygwin1.dll into the directory where the tests run: + cp /bin/cygwin1.dll t +or one of the Windows system directories (although, this is not recommended). +/etc/group +Cygwin does not require /etc/group, in which case the op/grent.t test will be skipped. The check performed by op/grent.t expects to see entries that use the members field, otherwise this test will fail: + Failed Test List of failed + ------------------------------------ + op/grent.t 1 +Script Portability +Cygwin does an outstanding job of providing UNIX-like semantics on top of Win32 systems. However, in addition to the items noted above, there are some differences that you should know about. This is a very brief guide to portability, more information can be found in the Cygwin documentation. +Pathnames +Cygwin pathnames can be separated by forward (/) or backward (\) slashes. They may also begin with drive letters (C:) or Universal Naming Codes (//UNC). DOS device names (aux, con, prn, com*, lpt?, nul) are invalid as base filenames. However, they can be used in extensions (e.g., hello.aux). Names may contain all printable characters except these: + : * ? " < > | +File names are case insensitive, but case preserving. A pathname that contains a backslash or drive letter is a Win32 pathname (and not subject to the translations applied to POSIX style pathnames). +Text/Binary +When a file is opened it is in either text or binary mode. In text mode a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default mode for an open() is determined by the mode of the mount that underlies the file. Perl provides a binmode() function to set binary mode on files that otherwise would be treated as text. sysopen() with the O_TEXT flag sets text mode on files that otherwise would be treated as binary: + sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) +lseek(), tell() and sysseek() only work with files opened in binary mode. +The text/binary issue is covered at length in the Cygwin documentation. +.exe +The Cygwin stat(), lstat() and readlink() functions make the .exe extension transparent by looking for foo.exe when you ask for foo (unless a foo also exists). Cygwin does not require a .exe extension, but gcc adds it automatically when building a program. However, when accessing an executable as a normal file (e.g., cp in a makefile) the .exe is not transparent. The install included with Cygwin automatically appends a .exe when necessary. +chown() +On WinNT chown() can change a file's user and group IDs. On Win9x chown() is a no-op, although this is appropriate since there is no security model. +Miscellaneous +File locking using the F_GETLK command to fcntl() is a stub that returns ENOSYS. +Win9x can not rename() an open file (although WinNT can). +The Cygwin chroot() implementation has holes (it can not restrict file access by native Win32 programs). +INSTALL +This will install Perl, including man pages. + make install | tee log.make-install +NOTE: If STDERR is redirected `make install' will not prompt you to install perl into /usr/bin. +You may need to be Administrator to run `make install'. If you are not, you must have write access to the directories in question. +Information on installing the Perl documentation in HTML format can be found in the INSTALL document. +MANIFEST +These are the files in the Perl release that contain references to Cygwin. These very brief notes attempt to explain the reason for all conditional code. Hopefully, keeping this up to date will allow the Cygwin port to be kept as clean as possible. +Documentation + INSTALL README.cygwin README.win32 MANIFEST + Changes Changes5.005 Changes5.004 Changes5.6 + pod/perl.pod pod/perlport.pod pod/perlfaq3.pod + pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod + pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod +Build, Configure, Make, Install + cygwin/Makefile.SHs + cygwin/ld2.in + cygwin/perlld.in + ext/IPC/SysV/hints/cygwin.pl + ext/NDBM_File/hints/cygwin.pl + ext/ODBM_File/hints/cygwin.pl + hints/cygwin.sh + Configure - help finding hints from uname, + shared libperl required for dynamic loading + Makefile.SH - linklibperl + Porting/patchls - cygwin in port list + installman - man pages with :: translated to . + installperl - install dll/ld2/perlld, install to pods + makedepend.SH - uwinfix +Tests + t/io/tell.t - binmode + t/lib/b.t - ignore Cwd from os_extras + t/lib/glob-basic.t - Win32 directory list access differs from read mode + t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// + t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk + (cache manager sometimes preserves ctime of file + previously created and deleted), no -u (setuid) +Compiled Perl Source + EXTERN.h - __declspec(dllimport) + XSUB.h - __declspec(dllexport) + cygwin/cygwin.c - os_extras (getcwd, spawn) + perl.c - os_extras + perl.h - binmode + doio.c - win9x can not rename a file when it is open + pp_sys.c - do not define h_errno, pp_system with spawn + util.c - use setenv +Compiled Module Source + ext/POSIX/POSIX.xs - tzname defined externally + ext/SDBM_File/sdbm/pair.c + - EXTCONST needs to be redefined from EXTERN.h + ext/SDBM_File/sdbm/sdbm.c + - binary open +Perl Modules/Scripts + lib/Cwd.pm - hook to internal Cwd::cwd + lib/ExtUtils/MakeMaker.pm + - require MM_Cygwin.pm + lib/ExtUtils/MM_Cygwin.pm + - canonpath, cflags, manifypods, perl_archive + lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 + lib/File/Spec/Unix.pm - preserve //unc + lib/File/Temp.pm - no directory sticky bit + lib/perl5db.pl - use stdin not /dev/tty + utils/perldoc.PL - version comment +BUGS +When make starts, it warns about overriding commands for perlmain.o. +`make clean' does not remove library .def or .exe.stackdump files. +The ld2 script contains references to the source directory. You should change these to $installbin after `make install'. +Support for swapping real and effective user and group IDs is incomplete. On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid(). However, additional Cygwin calls for manipulating WinNT access tokens and security contexts are required. +When building DLLs, `dllwrap --export-all-symbols' is used to export global symbols. It might be better to generate an explicit .def file (see makedef.pl). Also, DLLs can now be build with `gcc -shared'. +AUTHORS +Charles Wilson , Eric Fifer , alexander smishlajev , Steven Morlock , Sebastien Barre , Teun Burgers . +HISTORY +Last updated: 9 November 2000 diff --git a/lib/Pod/Simple/t/perlfaq3.pod b/lib/Pod/Simple/t/perlfaq3.pod new file mode 100644 index 0000000000..49cae1a209 --- /dev/null +++ b/lib/Pod/Simple/t/perlfaq3.pod @@ -0,0 +1,814 @@ +=head1 NAME + +perlfaq3 - Programming Tools ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) + +=head1 DESCRIPTION + +This section of the FAQ answers questions related to programmer tools +and programming support. + +=head2 How do I do (anything)? + +Have you looked at CPAN (see L)? The chances are that +someone has already written a module that can solve your problem. +Have you read the appropriate man pages? Here's a brief index: + + Basics perldata, perlvar, perlsyn, perlop, perlsub + Execution perlrun, perldebug + Functions perlfunc + Objects perlref, perlmod, perlobj, perltie + Data Structures perlref, perllol, perldsc + Modules perlmod, perlmodlib, perlsub + Regexes perlre, perlfunc, perlop, perllocale + Moving to perl5 perltrap, perl + Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed + Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html + (not a man-page but still useful) + +A crude table of contents for the Perl man page set is found in L. + +=head2 How can I use Perl interactively? + +The typical approach uses the Perl debugger, described in the +perldebug(1) man page, on an ``empty'' program, like this: + + perl -de 42 + +Now just type in any legal Perl code, and it will be immediately +evaluated. You can also examine the symbol table, get stack +backtraces, check variable values, set breakpoints, and other +operations typically found in symbolic debuggers. + +=head2 Is there a Perl shell? + +In general, no. The Shell.pm module (distributed with Perl) makes +Perl try commands which aren't part of the Perl language as shell +commands. perlsh from the source distribution is simplistic and +uninteresting, but may still be what you want. + +=head2 How do I debug my Perl programs? + +Have you tried C or used C<-w>? They enable warnings +to detect dubious practices. + +Have you tried C? It prevents you from using symbolic +references, makes you predeclare any subroutines that you call as bare +words, and (probably most importantly) forces you to predeclare your +variables with C, C, or C. + +Did you check the return values of each and every system call? The operating +system (and thus Perl) tells you whether they worked, and if not +why. + + open(FH, "> /etc/cantwrite") + or die "Couldn't write to /etc/cantwrite: $!\n"; + +Did you read L? It's full of gotchas for old and new Perl +programmers and even has sections for those of you who are upgrading +from languages like I and I. + +Have you tried the Perl debugger, described in L? You can +step through your program and see what it's doing and thus work out +why what it's doing isn't what it should be doing. + +=head2 How do I profile my Perl programs? + +You should get the Devel::DProf module from the standard distribution +(or separately on CPAN) and also use Benchmark.pm from the standard +distribution. The Benchmark module lets you time specific portions of +your code, while Devel::DProf gives detailed breakdowns of where your +code spends its time. + +Here's a sample use of Benchmark: + + use Benchmark; + + @junk = `cat /etc/motd`; + $count = 10_000; + + timethese($count, { + 'map' => sub { my @a = @junk; + map { s/a/b/ } @a; + return @a + }, + 'for' => sub { my @a = @junk; + local $_; + for (@a) { s/a/b/ }; + return @a }, + }); + +This is what it prints (on one machine--your results will be dependent +on your hardware, operating system, and the load on your machine): + + Benchmark: timing 10000 iterations of for, map... + for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu) + map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) + +Be aware that a good benchmark is very hard to write. It only tests the +data you give it and proves little about the differing complexities +of contrasting algorithms. + +=head2 How do I cross-reference my Perl programs? + +The B::Xref module, shipped with the new, alpha-release Perl compiler +(not the general distribution prior to the 5.005 release), can be used +to generate cross-reference reports for Perl programs. + + perl -MO=Xref[,OPTIONS] scriptname.plx + +=head2 Is there a pretty-printer (formatter) for Perl? + +There is no program that will reformat Perl as much as indent(1) does +for C. The complex feedback between the scanner and the parser (this +feedback is what confuses the vgrind and emacs programs) makes it +challenging at best to write a stand-alone Perl parser. + +Of course, if you simply follow the guidelines in L, you +shouldn't need to reformat. The habit of formatting your code as you +write it will help prevent bugs. Your editor can and should help you +with this. The perl-mode or newer cperl-mode for emacs can provide +remarkable amounts of help with most (but not all) code, and even less +programmable editors can provide significant assistance. Tom swears +by the following settings in vi and its clones: + + set ai sw=4 + map! ^O {^M}^[O^T + +Now put that in your F<.exrc> file (replacing the caret characters +with control characters) and away you go. In insert mode, ^T is +for indenting, ^D is for undenting, and ^O is for blockdenting-- +as it were. If you haven't used the last one, you're missing +a lot. A more complete example, with comments, can be found at +http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz + +If you are used to using the I program for printing out nice code +to a laser printer, you can take a stab at this using +http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the +results are not particularly satisfying for sophisticated code. + +The a2ps at http://www.infres.enst.fr/%7Edemaille/a2ps/ does lots of things +related to generating nicely printed output of documents. + +=head2 Is there a ctags for Perl? + +There's a simple one at +http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do +the trick. And if not, it's easy to hack into what you want. + +=head2 Is there an IDE or Windows Perl Editor? + +Perl programs are just plain text, so any editor will do. + +If you're on Unix, you already have an IDE--Unix itself. The UNIX +philosophy is the philosophy of several small tools that each do one +thing and do it well. It's like a carpenter's toolbox. + +If you want a Windows IDE, check the following: + +=over 4 + +=item CodeMagicCD + +http://www.codemagiccd.com/ + +=item Komodo + +ActiveState's cross-platform, multi-language IDE has Perl support, +including a regular expression debugger and remote debugging +(http://www.ActiveState.com/Products/Komodo/index.html). +(Visual Perl, a Visual Studio.NET plug-in is currently (early 2001) +in beta (http://www.ActiveState.com/Products/VisualPerl/index.html)). + +=item The Object System + +(http://www.castlelink.co.uk/object_system/) is a Perl web +applications development IDE. + +=item PerlBuilder + +(http://www.solutionsoft.com/perl.htm) is an integrated development +environment for Windows that supports Perl development. + +=item Perl code magic + +(http://www.petes-place.com/codemagic.html). + +=item visiPerl+ + +http://helpconsulting.net/visiperl/, from Help Consulting. + +=back + +For editors: if you're on Unix you probably have vi or a vi clone already, +and possibly an emacs too, so you may not need to download anything. +In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the +best available Perl editing mode in any editor. + +For Windows editors: you can download an Emacs + +=over 4 + +=item GNU Emacs + +http://www.gnu.org/software/emacs/windows/ntemacs.html + +=item MicroEMACS + +http://members.nbci.com/uemacs/ + +=item XEmacs + +http://www.xemacs.org/Download/index.html + +=back + +or a vi clone such as + +=over 4 + +=item Elvis + +ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/ + +=item Vile + +http://vile.cx/ + +=item Vim + +http://www.vim.org/ + +win32: http://www.cs.vu.nl/%7Etmgil/vi.html + +=back + +For vi lovers in general, Windows or elsewhere: +http://www.thomer.com/thomer/vi/vi.html. + +nvi (http://www.bostic.com/vi/, available from CPAN in src/misc/) is +yet another vi clone, unfortunately not available for Windows, but in +UNIX platforms you might be interested in trying it out, firstly because +strictly speaking it is not a vi clone, it is the real vi, or the new +incarnation of it, and secondly because you can embed Perl inside it +to use Perl as the scripting language. nvi is not alone in this, +though: at least also vim and vile offer an embedded Perl. + +The following are Win32 multilanguage editor/IDESs that support Perl: + +=over 4 + +=item Codewright + +http://www.starbase.com/ + +=item MultiEdit + +http://www.MultiEdit.com/ + +=item SlickEdit + +http://www.slickedit.com/ + +=back + +There is also a toyedit Text widget based editor written in Perl +that is distributed with the Tk module on CPAN. The ptkdb +(http://world.std.com/~aep/ptkdb/) is a Perl/tk based debugger that +acts as a development environment of sorts. Perl Composer +(http://perlcomposer.sourceforge.net/vperl.html) is an IDE for Perl/Tk +GUI creation. + +In addition to an editor/IDE you might be interested in a more +powerful shell environment for Win32. Your options include + +=over 4 + +=item Bash + +from the Cygwin package (http://sources.redhat.com/cygwin/) + +=item Ksh + +from the MKS Toolkit (http://www.mks.com/), or the Bourne shell of +the U/WIN environment (http://www.research.att.com/sw/tools/uwin/) + +=item Tcsh + +ftp://ftp.astron.com/pub/tcsh/, see also +http://www.primate.wisc.edu/software/csh-tcsh-book/ + +=item Zsh + +ftp://ftp.blarg.net/users/amol/zsh/, see also http://www.zsh.org/ + +=back + +MKS and U/WIN are commercial (U/WIN is free for educational and +research purposes), Cygwin is covered by the GNU Public License (but +that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all +contain (in addition to the shells) a comprehensive set of standard +UNIX toolkit utilities. + +If you're transferring text files between Unix and Windows using FTP +be sure to transfer them in ASCII mode so the ends of lines are +appropriately converted. + +On Mac OS the MacPerl Application comes with a simple 32k text editor +that behaves like a rudimentary IDE. In contrast to the MacPerl Application +the MPW Perl tool can make use of the MPW Shell itself as an editor (with +no 32k limit). + +=over 4 + +=item BBEdit and BBEdit Lite + +are text editors for Mac OS that have a Perl sensitivity mode +(http://web.barebones.com/). + +=item Alpha + +is an editor, written and extensible in Tcl, that nonetheless has +built in support for several popular markup and programming languages +including Perl and HTML (http://alpha.olm.net/). + +=back + +Pepper and Pe are programming language sensitive text editors for Mac +OS X and BeOS respectively (http://www.hekkelman.com/). + +=head2 Where can I get Perl macros for vi? + +For a complete version of Tom Christiansen's vi configuration file, +see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz , +the standard benchmark file for vi emulators. The file runs best with nvi, +the current version of vi out of Berkeley, which incidentally can be built +with an embedded Perl interpreter--see http://www.perl.com/CPAN/src/misc. + +=head2 Where can I get perl-mode for emacs? + +Since Emacs version 19 patchlevel 22 or so, there have been both a +perl-mode.el and support for the Perl debugger built in. These should +come with the standard Emacs 19 distribution. + +In the Perl source directory, you'll find a directory called "emacs", +which contains a cperl-mode that color-codes keywords, provides +context-sensitive help, and other nifty things. + +Note that the perl-mode of emacs will have fits with C<"main'foo"> +(single quote), and mess up the indentation and highlighting. You +are probably using C<"main::foo"> in new Perl code anyway, so this +shouldn't be an issue. + +=head2 How can I use curses with Perl? + +The Curses module from CPAN provides a dynamically loadable object +module interface to a curses library. A small demo can be found at the +directory http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/rep; +this program repeats a command and updates the screen as needed, rendering +B similar to B. + +=head2 How can I use X or Tk with Perl? + +Tk is a completely Perl-based, object-oriented interface to the Tk toolkit +that doesn't force you to use Tcl just to get at Tk. Sx is an interface +to the Athena Widget set. Both are available from CPAN. See the +directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ + +Invaluable for Perl/Tk programming are the Perl/Tk FAQ at +http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference +Guide available at +http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the +online manpages at +http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html . + +=head2 How can I generate simple menus without using CGI or Tk? + +The http://www.perl.com/CPAN/authors/id/SKUNZ/perlmenu.v4.0.tar.gz +module, which is curses-based, can help with this. + +=head2 What is undump? + +See the next question on ``How can I make my Perl program run faster?'' + +=head2 How can I make my Perl program run faster? + +The best way to do this is to come up with a better algorithm. This +can often make a dramatic difference. Jon Bentley's book +``Programming Pearls'' (that's not a misspelling!) has some good tips +on optimization, too. Advice on benchmarking boils down to: benchmark +and profile to make sure you're optimizing the right part, look for +better algorithms instead of microtuning your code, and when all else +fails consider just buying faster hardware. + +A different approach is to autoload seldom-used Perl code. See the +AutoSplit and AutoLoader modules in the standard distribution for +that. Or you could locate the bottleneck and think about writing just +that part in C, the way we used to take bottlenecks in C code and +write them in assembler. Similar to rewriting in C, +modules that have critical sections can be written in C (for instance, the +PDL module from CPAN). + +In some cases, it may be worth it to use the backend compiler to +produce byte code (saving compilation time) or compile into C, which +will certainly save compilation time and sometimes a small amount (but +not much) execution time. See the question about compiling your Perl +programs for more on the compiler--the wins aren't as obvious as you'd +hope. + +If you're currently linking your perl executable to a shared I, +you can often gain a 10-25% performance benefit by rebuilding it to +link with a static libc.a instead. This will make a bigger perl +executable, but your Perl programs (and programmers) may thank you for +it. See the F file in the source distribution for more +information. + +Unsubstantiated reports allege that Perl interpreters that use sfio +outperform those that don't (for I/O intensive applications). To try +this, see the F file in the source distribution, especially +the ``Selecting File I/O mechanisms'' section. + +The undump program was an old attempt to speed up your Perl program +by storing the already-compiled form to disk. This is no longer +a viable option, as it only worked on a few architectures, and +wasn't a good solution anyway. + +=head2 How can I make my Perl program take less memory? + +When it comes to time-space tradeoffs, Perl nearly always prefers to +throw memory at a problem. Scalars in Perl use more memory than +strings in C, arrays take more than that, and hashes use even more. While +there's still a lot to be done, recent releases have been addressing +these issues. For example, as of 5.004, duplicate hash keys are +shared amongst all hashes using them, so require no reallocation. + +In some cases, using substr() or vec() to simulate arrays can be +highly beneficial. For example, an array of a thousand booleans will +take at least 20,000 bytes of space, but it can be turned into one +125-byte bit vector--a considerable memory savings. The standard +Tie::SubstrHash module can also help for certain types of data +structure. If you're working with specialist data structures +(matrices, for instance) modules that implement these in C may use +less memory than equivalent Perl modules. + +Another thing to try is learning whether your Perl was compiled with +the system malloc or with Perl's builtin malloc. Whichever one it +is, try using the other one and see whether this makes a difference. +Information about malloc is in the F file in the source +distribution. You can find out whether you are using perl's malloc by +typing C. + +=head2 Is it unsafe to return a pointer to local data? + +No, Perl's garbage collection system takes care of this. + + sub makeone { + my @a = ( 1 .. 10 ); + return \@a; + } + + for $i ( 1 .. 10 ) { + push @many, makeone(); + } + + print $many[4][5], "\n"; + + print "@many\n"; + +=head2 How can I free an array or hash so my program shrinks? + +You can't. On most operating systems, memory allocated to a program +can never be returned to the system. That's why long-running programs +sometimes re-exec themselves. Some operating systems (notably, +FreeBSD and Linux) allegedly reclaim large chunks of memory that is no +longer used, but it doesn't appear to happen with Perl (yet). The Mac +appears to be the only platform that will reliably (albeit, slowly) +return memory to the OS. + +We've had reports that on Linux (Redhat 5.1) on Intel, C will return memory to the system, while on Solaris 2.6 it +won't. In general, try it yourself and see. + +However, judicious use of my() on your variables will help make sure +that they go out of scope so that Perl can free up that space for +use in other parts of your program. A global variable, of course, never +goes out of scope, so you can't get its space automatically reclaimed, +although undef()ing and/or delete()ing it will achieve the same effect. +In general, memory allocation and de-allocation isn't something you can +or should be worrying about much in Perl, but even this capability +(preallocation of data types) is in the works. + +=head2 How can I make my CGI script more efficient? + +Beyond the normal measures described to make general Perl programs +faster or smaller, a CGI program has additional issues. It may be run +several times per second. Given that each time it runs it will need +to be re-compiled and will often allocate a megabyte or more of system +memory, this can be a killer. Compiling into C B because the process start-up overhead is where the bottleneck is. + +There are two popular ways to avoid this overhead. One solution +involves running the Apache HTTP server (available from +http://www.apache.org/) with either of the mod_perl or mod_fastcgi +plugin modules. + +With mod_perl and the Apache::Registry module (distributed with +mod_perl), httpd will run with an embedded Perl interpreter which +pre-compiles your script and then executes it within the same address +space without forking. The Apache extension also gives Perl access to +the internal server API, so modules written in Perl can do just about +anything a module written in C can. For more on mod_perl, see +http://perl.apache.org/ + +With the FCGI module (from CPAN) and the mod_fastcgi +module (available from http://www.fastcgi.com/) each of your Perl +programs becomes a permanent CGI daemon process. + +Both of these solutions can have far-reaching effects on your system +and on the way you write your CGI programs, so investigate them with +care. + +See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . + +A non-free, commercial product, ``The Velocity Engine for Perl'', +(http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ ) +might also be worth looking at. It will allow you to increase the +performance of your Perl programs, running programs up to 25 times +faster than normal CGI Perl when running in persistent Perl mode or 4 +to 5 times faster without any modification to your existing CGI +programs. Fully functional evaluation copies are available from the +web site. + +=head2 How can I hide the source for my Perl program? + +Delete it. :-) Seriously, there are a number of (mostly +unsatisfactory) solutions with varying levels of ``security''. + +First of all, however, you I take away read permission, because +the source code has to be readable in order to be compiled and +interpreted. (That doesn't mean that a CGI script's source is +readable by people on the web, though--only by people with access to +the filesystem.) So you have to leave the permissions at the socially +friendly 0755 level. + +Some people regard this as a security problem. If your program does +insecure things and relies on people not knowing how to exploit those +insecurities, it is not secure. It is often possible for someone to +determine the insecure things and exploit them without viewing the +source. Security through obscurity, the name for hiding your bugs +instead of fixing them, is little security indeed. + +You can try using encryption via source filters (Filter::* from CPAN), +but any decent programmer will be able to decrypt it. You can try using +the byte code compiler and interpreter described below, but the curious +might still be able to de-compile it. You can try using the native-code +compiler described below, but crackers might be able to disassemble it. +These pose varying degrees of difficulty to people wanting to get at +your code, but none can definitively conceal it (true of every +language, not just Perl). + +If you're concerned about people profiting from your code, then the +bottom line is that nothing but a restrictive license will give you +legal security. License your software and pepper it with threatening +statements like ``This is unpublished proprietary software of XYZ Corp. +Your access to it does not give you permission to use it blah blah +blah.'' We are not lawyers, of course, so you should see a lawyer if +you want to be sure your license's wording will stand up in court. + +=head2 How can I compile my Perl program into byte code or C? + +Malcolm Beattie has written a multifunction backend compiler, +available from CPAN, that can do both these things. It is included +in the perl5.005 release, but is still considered experimental. +This means it's fun to play with if you're a programmer but not +really for people looking for turn-key solutions. + +Merely compiling into C does not in and of itself guarantee that your +code will run very much faster. That's because except for lucky cases +where a lot of native type inferencing is possible, the normal Perl +run-time system is still present and so your program will take just as +long to run and be just as big. Most programs save little more than +compilation time, leaving execution no more than 10-30% faster. A few +rare programs actually benefit significantly (even running several times +faster), but this takes some tweaking of your code. + +You'll probably be astonished to learn that the current version of the +compiler generates a compiled form of your script whose executable is +just as big as the original perl executable, and then some. That's +because as currently written, all programs are prepared for a full +eval() statement. You can tremendously reduce this cost by building a +shared I library and linking against that. See the +F podfile in the Perl source distribution for details. If +you link your main perl binary with this, it will make it minuscule. +For example, on one author's system, F is only 11k in +size! + +In general, the compiler will do nothing to make a Perl program smaller, +faster, more portable, or more secure. In fact, it can make your +situation worse. The executable will be bigger, your VM system may take +longer to load the whole thing, the binary is fragile and hard to fix, +and compilation never stopped software piracy in the form of crackers, +viruses, or bootleggers. The real advantage of the compiler is merely +packaging, and once you see the size of what it makes (well, unless +you use a shared I), you'll probably want a complete +Perl install anyway. + +=head2 How can I compile Perl into Java? + +You can also integrate Java and Perl with the +Perl Resource Kit from O'Reilly and Associates. See +http://www.oreilly.com/catalog/prkunix/ . + +Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in +development, allows Perl code to be called from Java. See jpl/README +in the Perl source tree. + +=head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]? + +For OS/2 just use + + extproc perl -S -your_switches + +as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's +`extproc' handling). For DOS one should first invent a corresponding +batch file and codify it in C (see the +F file in the source distribution for more information). + +The Win95/NT installation, when using the ActiveState port of Perl, +will modify the Registry to associate the C<.pl> extension with the +perl interpreter. If you install another port, perhaps even building +your own Win95/NT Perl from the standard sources by using a Windows port +of gcc (e.g., with cygwin or mingw32), then you'll have to modify +the Registry yourself. In addition to associating C<.pl> with the +interpreter, NT people can use: C to let them +run the program C merely by typing C. + +Macintosh Perl programs will have the appropriate Creator and +Type, so that double-clicking them will invoke the Perl application. + +I: Whatever you do, PLEASE don't get frustrated, and just +throw the perl interpreter into your cgi-bin directory, in order to +get your programs working for a web server. This is an EXTREMELY big +security risk. Take the time to figure out how to do it correctly. + +=head2 Can I write useful Perl programs on the command line? + +Yes. Read L for more information. Some examples follow. +(These assume standard Unix shell quoting rules.) + + # sum first and last fields + perl -lane 'print $F[0] + $F[-1]' * + + # identify text files + perl -le 'for(@ARGV) {print if -f && -T _}' * + + # remove (most) comments from C program + perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c + + # make file a month younger than today, defeating reaper daemons + perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' * + + # find first unused uid + perl -le '$i++ while getpwuid($i); print $i' + + # display reasonable manpath + echo $PATH | perl -nl -072 -e ' + s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}' + +OK, the last one was actually an Obfuscated Perl Contest entry. :-) + +=head2 Why don't Perl one-liners work on my DOS/Mac/VMS system? + +The problem is usually that the command interpreters on those systems +have rather different ideas about quoting than the Unix shells under +which the one-liners were created. On some systems, you may have to +change single-quotes to double ones, which you must I do on Unix +or Plan9 systems. You might also have to change a single % to a %%. + +For example: + + # Unix + perl -e 'print "Hello world\n"' + + # DOS, etc. + perl -e "print \"Hello world\n\"" + + # Mac + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + + # VMS + perl -e "print ""Hello world\n""" + +The problem is that none of these examples are reliable: they depend on the +command interpreter. Under Unix, the first two often work. Under DOS, +it's entirely possible that neither works. If 4DOS was the command shell, +you'd probably have better luck like this: + + perl -e "print "Hello world\n"" + +Under the Mac, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Mac's non-ASCII +characters as control characters. + +Using qq(), q(), and qx(), instead of "double quotes", 'single +quotes', and `backticks`, may make one-liners easier to write. + +There is no general solution to all of this. It is a mess, pure and +simple. Sucks to be away from Unix, huh? :-) + +[Some of this answer was contributed by Kenneth Albanowski.] + +=head2 Where can I learn about CGI or Web programming in Perl? + +For modules, get the CGI or LWP modules from CPAN. For textbooks, +see the two especially dedicated to web stuff in the question on +books. For problems and questions related to the web, like ``Why +do I get 500 Errors'' or ``Why doesn't it run from the browser right +when it runs fine on the command line'', see these sources: + + WWW Security FAQ + http://www.w3.org/Security/Faq/ + + Web FAQ + http://www.boutell.com/faq/ + + CGI FAQ + http://www.webthing.com/tutorials/cgifaq.html + + HTTP Spec + http://www.w3.org/pub/WWW/Protocols/HTTP/ + + HTML Spec + http://www.w3.org/TR/REC-html40/ + http://www.w3.org/pub/WWW/MarkUp/ + + CGI Spec + http://www.w3.org/CGI/ + + CGI Security FAQ + http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt + +=head2 Where can I learn about object-oriented Perl programming? + +A good place to start is L, and you can use L, +L, and L for reference. Perltoot didn't come out +until the 5.004 release; you can get a copy (in pod, html, or +postscript) from http://www.perl.com/CPAN/doc/FMTEYEWTK/ . + +=head2 Where can I learn about linking C with Perl? [h2xs, xsubpp] + +If you want to call C from Perl, start with L, +moving on to L, L, and L. If you want to +call Perl from C, then read L, L, and +L. Don't forget that you can learn a lot from looking at +how the authors of existing extension modules wrote their code and +solved their problems. + +=head2 I've read perlembed, perlguts, etc., but I can't embed perl in +my C program; what am I doing wrong? + +Download the ExtUtils::Embed kit from CPAN and run `make test'. If +the tests pass, read the pods again and again and again. If they +fail, see L and send a bug report with the output of +C along with C. + +=head2 When I tried to run my script, I got this message. What does it +mean? + +A complete list of Perl's error messages and warnings with explanatory +text can be found in L. You can also use the splain program +(distributed with Perl) to explain the error messages: + + perl program 2>diag.out + splain [-v] [-p] diag.out + +or change your program to explain the messages for you: + + use diagnostics; + +or + + use diagnostics -verbose; + +=head2 What's MakeMaker? + +This module (part of the standard Perl distribution) is designed to +write a Makefile for an extension module from a Makefile.PL. For more +information, see L. + +=head1 AUTHOR AND COPYRIGHT + +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. +All rights reserved. + +When included as an integrated part of the Standard Distribution +of Perl or of its documentation (printed or otherwise), this works is +covered under Perl's Artistic License. For separate distributions of +all or part of this FAQ outside of that, see L. + +Irrespective of its distribution, all code examples here are in the public +domain. You are permitted and encouraged to use this code and any +derivatives thereof in your own programs for fun or for profit as you +see fit. A simple comment in the code giving credit to the FAQ would +be courteous but is not required. diff --git a/lib/Pod/Simple/t/perlfaq3_out.txt b/lib/Pod/Simple/t/perlfaq3_out.txt new file mode 100644 index 0000000000..11d73fc9b8 --- /dev/null +++ b/lib/Pod/Simple/t/perlfaq3_out.txt @@ -0,0 +1,266 @@ +NAME +perlfaq3 - Programming Tools ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) +DESCRIPTION +This section of the FAQ answers questions related to programmer tools and programming support. +How do I do (anything)? +Have you looked at CPAN (see perlfaq2)? The chances are that someone has already written a module that can solve your problem. Have you read the appropriate man pages? Here's a brief index: + Basics perldata, perlvar, perlsyn, perlop, perlsub + Execution perlrun, perldebug + Functions perlfunc + Objects perlref, perlmod, perlobj, perltie + Data Structures perlref, perllol, perldsc + Modules perlmod, perlmodlib, perlsub + Regexes perlre, perlfunc, perlop, perllocale + Moving to perl5 perltrap, perl + Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed + Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html + (not a man-page but still useful) +A crude table of contents for the Perl man page set is found in perltoc. +How can I use Perl interactively? +The typical approach uses the Perl debugger, described in the perldebug(1) man page, on an ``empty'' program, like this: + perl -de 42 +Now just type in any legal Perl code, and it will be immediately evaluated. You can also examine the symbol table, get stack backtraces, check variable values, set breakpoints, and other operations typically found in symbolic debuggers. +Is there a Perl shell? +In general, no. The Shell.pm module (distributed with Perl) makes Perl try commands which aren't part of the Perl language as shell commands. perlsh from the source distribution is simplistic and uninteresting, but may still be what you want. +How do I debug my Perl programs? +Have you tried use warnings or used -w? They enable warnings to detect dubious practices. +Have you tried use strict? It prevents you from using symbolic references, makes you predeclare any subroutines that you call as bare words, and (probably most importantly) forces you to predeclare your variables with my, our, or use vars. +Did you check the return values of each and every system call? The operating system (and thus Perl) tells you whether they worked, and if not why. + open(FH, "> /etc/cantwrite") + or die "Couldn't write to /etc/cantwrite: $!\n"; +Did you read perltrap? It's full of gotchas for old and new Perl programmers and even has sections for those of you who are upgrading from languages like awk and C. +Have you tried the Perl debugger, described in perldebug? You can step through your program and see what it's doing and thus work out why what it's doing isn't what it should be doing. +How do I profile my Perl programs? +You should get the Devel::DProf module from the standard distribution (or separately on CPAN) and also use Benchmark.pm from the standard distribution. The Benchmark module lets you time specific portions of your code, while Devel::DProf gives detailed breakdowns of where your code spends its time. +Here's a sample use of Benchmark: + use Benchmark; + @junk = `cat /etc/motd`; + $count = 10_000; + timethese($count, { + 'map' => sub { my @a = @junk; + map { s/a/b/ } @a; + return @a + }, + 'for' => sub { my @a = @junk; + local $_; + for (@a) { s/a/b/ }; + return @a }, + }); +This is what it prints (on one machine--your results will be dependent on your hardware, operating system, and the load on your machine): + Benchmark: timing 10000 iterations of for, map... + for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu) + map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) +Be aware that a good benchmark is very hard to write. It only tests the data you give it and proves little about the differing complexities of contrasting algorithms. +How do I cross-reference my Perl programs? +The B::Xref module, shipped with the new, alpha-release Perl compiler (not the general distribution prior to the 5.005 release), can be used to generate cross-reference reports for Perl programs. + perl -MO=Xref[,OPTIONS] scriptname.plx +Is there a pretty-printer (formatter) for Perl? +There is no program that will reformat Perl as much as indent(1) does for C. The complex feedback between the scanner and the parser (this feedback is what confuses the vgrind and emacs programs) makes it challenging at best to write a stand-alone Perl parser. +Of course, if you simply follow the guidelines in perlstyle, you shouldn't need to reformat. The habit of formatting your code as you write it will help prevent bugs. Your editor can and should help you with this. The perl-mode or newer cperl-mode for emacs can provide remarkable amounts of help with most (but not all) code, and even less programmable editors can provide significant assistance. Tom swears by the following settings in vi and its clones: + set ai sw=4 + map! ^O {^M}^[O^T +Now put that in your .exrc file (replacing the caret characters with control characters) and away you go. In insert mode, ^T is for indenting, ^D is for undenting, and ^O is for blockdenting-- as it were. If you haven't used the last one, you're missing a lot. A more complete example, with comments, can be found at http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz +If you are used to using the vgrind program for printing out nice code to a laser printer, you can take a stab at this using http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the results are not particularly satisfying for sophisticated code. +The a2ps at http://www.infres.enst.fr/%7Edemaille/a2ps/ does lots of things related to generating nicely printed output of documents. +Is there a ctags for Perl? +There's a simple one at http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do the trick. And if not, it's easy to hack into what you want. +Is there an IDE or Windows Perl Editor? +Perl programs are just plain text, so any editor will do. +If you're on Unix, you already have an IDE--Unix itself. The UNIX philosophy is the philosophy of several small tools that each do one thing and do it well. It's like a carpenter's toolbox. +If you want a Windows IDE, check the following: +CodeMagicCD +http://www.codemagiccd.com/ +Komodo +ActiveState's cross-platform, multi-language IDE has Perl support, including a regular expression debugger and remote debugging (http://www.ActiveState.com/Products/Komodo/index.html). (Visual Perl, a Visual Studio.NET plug-in is currently (early 2001) in beta (http://www.ActiveState.com/Products/VisualPerl/index.html)). +The Object System +(http://www.castlelink.co.uk/object_system/) is a Perl web applications development IDE. +PerlBuilder +(http://www.solutionsoft.com/perl.htm) is an integrated development environment for Windows that supports Perl development. +Perl code magic +(http://www.petes-place.com/codemagic.html). +visiPerl+ +http://helpconsulting.net/visiperl/, from Help Consulting. +For editors: if you're on Unix you probably have vi or a vi clone already, and possibly an emacs too, so you may not need to download anything. In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the best available Perl editing mode in any editor. +For Windows editors: you can download an Emacs +GNU Emacs +http://www.gnu.org/software/emacs/windows/ntemacs.html +MicroEMACS +http://members.nbci.com/uemacs/ +XEmacs +http://www.xemacs.org/Download/index.html +or a vi clone such as +Elvis +ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/ +Vile +http://vile.cx/ +Vim +http://www.vim.org/ +win32: http://www.cs.vu.nl/%7Etmgil/vi.html +For vi lovers in general, Windows or elsewhere: http://www.thomer.com/thomer/vi/vi.html. +nvi (http://www.bostic.com/vi/, available from CPAN in src/misc/) is yet another vi clone, unfortunately not available for Windows, but in UNIX platforms you might be interested in trying it out, firstly because strictly speaking it is not a vi clone, it is the real vi, or the new incarnation of it, and secondly because you can embed Perl inside it to use Perl as the scripting language. nvi is not alone in this, though: at least also vim and vile offer an embedded Perl. +The following are Win32 multilanguage editor/IDESs that support Perl: +Codewright +http://www.starbase.com/ +MultiEdit +http://www.MultiEdit.com/ +SlickEdit +http://www.slickedit.com/ +There is also a toyedit Text widget based editor written in Perl that is distributed with the Tk module on CPAN. The ptkdb (http://world.std.com/~aep/ptkdb/) is a Perl/tk based debugger that acts as a development environment of sorts. Perl Composer (http://perlcomposer.sourceforge.net/vperl.html) is an IDE for Perl/Tk GUI creation. +In addition to an editor/IDE you might be interested in a more powerful shell environment for Win32. Your options include +Bash +from the Cygwin package (http://sources.redhat.com/cygwin/) +Ksh +from the MKS Toolkit (http://www.mks.com/), or the Bourne shell of the U/WIN environment (http://www.research.att.com/sw/tools/uwin/) +Tcsh +ftp://ftp.astron.com/pub/tcsh/, see also http://www.primate.wisc.edu/software/csh-tcsh-book/ +Zsh +ftp://ftp.blarg.net/users/amol/zsh/, see also http://www.zsh.org/ +MKS and U/WIN are commercial (U/WIN is free for educational and research purposes), Cygwin is covered by the GNU Public License (but that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all contain (in addition to the shells) a comprehensive set of standard UNIX toolkit utilities. +If you're transferring text files between Unix and Windows using FTP be sure to transfer them in ASCII mode so the ends of lines are appropriately converted. +On Mac OS the MacPerl Application comes with a simple 32k text editor that behaves like a rudimentary IDE. In contrast to the MacPerl Application the MPW Perl tool can make use of the MPW Shell itself as an editor (with no 32k limit). +BBEdit and BBEdit Lite +are text editors for Mac OS that have a Perl sensitivity mode (http://web.barebones.com/). +Alpha +is an editor, written and extensible in Tcl, that nonetheless has built in support for several popular markup and programming languages including Perl and HTML (http://alpha.olm.net/). +Pepper and Pe are programming language sensitive text editors for Mac OS X and BeOS respectively (http://www.hekkelman.com/). +Where can I get Perl macros for vi? +For a complete version of Tom Christiansen's vi configuration file, see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz , the standard benchmark file for vi emulators. The file runs best with nvi, the current version of vi out of Berkeley, which incidentally can be built with an embedded Perl interpreter--see http://www.perl.com/CPAN/src/misc. +Where can I get perl-mode for emacs? +Since Emacs version 19 patchlevel 22 or so, there have been both a perl-mode.el and support for the Perl debugger built in. These should come with the standard Emacs 19 distribution. +In the Perl source directory, you'll find a directory called "emacs", which contains a cperl-mode that color-codes keywords, provides context-sensitive help, and other nifty things. +Note that the perl-mode of emacs will have fits with "main'foo" (single quote), and mess up the indentation and highlighting. You are probably using "main::foo" in new Perl code anyway, so this shouldn't be an issue. +How can I use curses with Perl? +The Curses module from CPAN provides a dynamically loadable object module interface to a curses library. A small demo can be found at the directory http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/rep; this program repeats a command and updates the screen as needed, rendering rep ps axu similar to top. +How can I use X or Tk with Perl? +Tk is a completely Perl-based, object-oriented interface to the Tk toolkit that doesn't force you to use Tcl just to get at Tk. Sx is an interface to the Athena Widget set. Both are available from CPAN. See the directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ +Invaluable for Perl/Tk programming are the Perl/Tk FAQ at http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference Guide available at http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the online manpages at http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html . +How can I generate simple menus without using CGI or Tk? +The http://www.perl.com/CPAN/authors/id/SKUNZ/perlmenu.v4.0.tar.gz module, which is curses-based, can help with this. +What is undump? +See the next question on ``How can I make my Perl program run faster?'' +How can I make my Perl program run faster? +The best way to do this is to come up with a better algorithm. This can often make a dramatic difference. Jon Bentley's book ``Programming Pearls'' (that's not a misspelling!) has some good tips on optimization, too. Advice on benchmarking boils down to: benchmark and profile to make sure you're optimizing the right part, look for better algorithms instead of microtuning your code, and when all else fails consider just buying faster hardware. +A different approach is to autoload seldom-used Perl code. See the AutoSplit and AutoLoader modules in the standard distribution for that. Or you could locate the bottleneck and think about writing just that part in C, the way we used to take bottlenecks in C code and write them in assembler. Similar to rewriting in C, modules that have critical sections can be written in C (for instance, the PDL module from CPAN). +In some cases, it may be worth it to use the backend compiler to produce byte code (saving compilation time) or compile into C, which will certainly save compilation time and sometimes a small amount (but not much) execution time. See the question about compiling your Perl programs for more on the compiler--the wins aren't as obvious as you'd hope. +If you're currently linking your perl executable to a shared libc.so, you can often gain a 10-25% performance benefit by rebuilding it to link with a static libc.a instead. This will make a bigger perl executable, but your Perl programs (and programmers) may thank you for it. See the INSTALL file in the source distribution for more information. +Unsubstantiated reports allege that Perl interpreters that use sfio outperform those that don't (for I/O intensive applications). To try this, see the INSTALL file in the source distribution, especially the ``Selecting File I/O mechanisms'' section. +The undump program was an old attempt to speed up your Perl program by storing the already-compiled form to disk. This is no longer a viable option, as it only worked on a few architectures, and wasn't a good solution anyway. +How can I make my Perl program take less memory? +When it comes to time-space tradeoffs, Perl nearly always prefers to throw memory at a problem. Scalars in Perl use more memory than strings in C, arrays take more than that, and hashes use even more. While there's still a lot to be done, recent releases have been addressing these issues. For example, as of 5.004, duplicate hash keys are shared amongst all hashes using them, so require no reallocation. +In some cases, using substr() or vec() to simulate arrays can be highly beneficial. For example, an array of a thousand booleans will take at least 20,000 bytes of space, but it can be turned into one 125-byte bit vector--a considerable memory savings. The standard Tie::SubstrHash module can also help for certain types of data structure. If you're working with specialist data structures (matrices, for instance) modules that implement these in C may use less memory than equivalent Perl modules. +Another thing to try is learning whether your Perl was compiled with the system malloc or with Perl's builtin malloc. Whichever one it is, try using the other one and see whether this makes a difference. Information about malloc is in the INSTALL file in the source distribution. You can find out whether you are using perl's malloc by typing perl -V:usemymalloc. +Is it unsafe to return a pointer to local data? +No, Perl's garbage collection system takes care of this. + sub makeone { + my @a = ( 1 .. 10 ); + return \@a; + } + for $i ( 1 .. 10 ) { + push @many, makeone(); + } + print $many[4][5], "\n"; + print "@many\n"; +How can I free an array or hash so my program shrinks? +You can't. On most operating systems, memory allocated to a program can never be returned to the system. That's why long-running programs sometimes re-exec themselves. Some operating systems (notably, FreeBSD and Linux) allegedly reclaim large chunks of memory that is no longer used, but it doesn't appear to happen with Perl (yet). The Mac appears to be the only platform that will reliably (albeit, slowly) return memory to the OS. +We've had reports that on Linux (Redhat 5.1) on Intel, undef $scalar will return memory to the system, while on Solaris 2.6 it won't. In general, try it yourself and see. +However, judicious use of my() on your variables will help make sure that they go out of scope so that Perl can free up that space for use in other parts of your program. A global variable, of course, never goes out of scope, so you can't get its space automatically reclaimed, although undef()ing and/or delete()ing it will achieve the same effect. In general, memory allocation and de-allocation isn't something you can or should be worrying about much in Perl, but even this capability (preallocation of data types) is in the works. +How can I make my CGI script more efficient? +Beyond the normal measures described to make general Perl programs faster or smaller, a CGI program has additional issues. It may be run several times per second. Given that each time it runs it will need to be re-compiled and will often allocate a megabyte or more of system memory, this can be a killer. Compiling into C isn't going to help you because the process start-up overhead is where the bottleneck is. +There are two popular ways to avoid this overhead. One solution involves running the Apache HTTP server (available from http://www.apache.org/) with either of the mod_perl or mod_fastcgi plugin modules. +With mod_perl and the Apache::Registry module (distributed with mod_perl), httpd will run with an embedded Perl interpreter which pre-compiles your script and then executes it within the same address space without forking. The Apache extension also gives Perl access to the internal server API, so modules written in Perl can do just about anything a module written in C can. For more on mod_perl, see http://perl.apache.org/ +With the FCGI module (from CPAN) and the mod_fastcgi module (available from http://www.fastcgi.com/) each of your Perl programs becomes a permanent CGI daemon process. +Both of these solutions can have far-reaching effects on your system and on the way you write your CGI programs, so investigate them with care. +See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . +A non-free, commercial product, ``The Velocity Engine for Perl'', (http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ ) might also be worth looking at. It will allow you to increase the performance of your Perl programs, running programs up to 25 times faster than normal CGI Perl when running in persistent Perl mode or 4 to 5 times faster without any modification to your existing CGI programs. Fully functional evaluation copies are available from the web site. +How can I hide the source for my Perl program? +Delete it. :-) Seriously, there are a number of (mostly unsatisfactory) solutions with varying levels of ``security''. +First of all, however, you can't take away read permission, because the source code has to be readable in order to be compiled and interpreted. (That doesn't mean that a CGI script's source is readable by people on the web, though--only by people with access to the filesystem.) So you have to leave the permissions at the socially friendly 0755 level. +Some people regard this as a security problem. If your program does insecure things and relies on people not knowing how to exploit those insecurities, it is not secure. It is often possible for someone to determine the insecure things and exploit them without viewing the source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed. +You can try using encryption via source filters (Filter::* from CPAN), but any decent programmer will be able to decrypt it. You can try using the byte code compiler and interpreter described below, but the curious might still be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (true of every language, not just Perl). +If you're concerned about people profiting from your code, then the bottom line is that nothing but a restrictive license will give you legal security. License your software and pepper it with threatening statements like ``This is unpublished proprietary software of XYZ Corp. Your access to it does not give you permission to use it blah blah blah.'' We are not lawyers, of course, so you should see a lawyer if you want to be sure your license's wording will stand up in court. +How can I compile my Perl program into byte code or C? +Malcolm Beattie has written a multifunction backend compiler, available from CPAN, that can do both these things. It is included in the perl5.005 release, but is still considered experimental. This means it's fun to play with if you're a programmer but not really for people looking for turn-key solutions. +Merely compiling into C does not in and of itself guarantee that your code will run very much faster. That's because except for lucky cases where a lot of native type inferencing is possible, the normal Perl run-time system is still present and so your program will take just as long to run and be just as big. Most programs save little more than compilation time, leaving execution no more than 10-30% faster. A few rare programs actually benefit significantly (even running several times faster), but this takes some tweaking of your code. +You'll probably be astonished to learn that the current version of the compiler generates a compiled form of your script whose executable is just as big as the original perl executable, and then some. That's because as currently written, all programs are prepared for a full eval() statement. You can tremendously reduce this cost by building a shared libperl.so library and linking against that. See the INSTALL podfile in the Perl source distribution for details. If you link your main perl binary with this, it will make it minuscule. For example, on one author's system, /usr/bin/perl is only 11k in size! +In general, the compiler will do nothing to make a Perl program smaller, faster, more portable, or more secure. In fact, it can make your situation worse. The executable will be bigger, your VM system may take longer to load the whole thing, the binary is fragile and hard to fix, and compilation never stopped software piracy in the form of crackers, viruses, or bootleggers. The real advantage of the compiler is merely packaging, and once you see the size of what it makes (well, unless you use a shared libperl.so), you'll probably want a complete Perl install anyway. +How can I compile Perl into Java? +You can also integrate Java and Perl with the Perl Resource Kit from O'Reilly and Associates. See http://www.oreilly.com/catalog/prkunix/ . +Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in development, allows Perl code to be called from Java. See jpl/README in the Perl source tree. +How can I get #!perl to work on [MS-DOS,NT,...]? +For OS/2 just use + extproc perl -S -your_switches +as the first line in *.cmd file (-S due to a bug in cmd.exe's `extproc' handling). For DOS one should first invent a corresponding batch file and codify it in ALTERNATIVE_SHEBANG (see the INSTALL file in the source distribution for more information). +The Win95/NT installation, when using the ActiveState port of Perl, will modify the Registry to associate the .pl extension with the perl interpreter. If you install another port, perhaps even building your own Win95/NT Perl from the standard sources by using a Windows port of gcc (e.g., with cygwin or mingw32), then you'll have to modify the Registry yourself. In addition to associating .pl with the interpreter, NT people can use: SET PATHEXT=%PATHEXT%;.PL to let them run the program install-linux.pl merely by typing install-linux. +Macintosh Perl programs will have the appropriate Creator and Type, so that double-clicking them will invoke the Perl application. +IMPORTANT!: Whatever you do, PLEASE don't get frustrated, and just throw the perl interpreter into your cgi-bin directory, in order to get your programs working for a web server. This is an EXTREMELY big security risk. Take the time to figure out how to do it correctly. +Can I write useful Perl programs on the command line? +Yes. Read perlrun for more information. Some examples follow. (These assume standard Unix shell quoting rules.) + # sum first and last fields + perl -lane 'print $F[0] + $F[-1]' * + # identify text files + perl -le 'for(@ARGV) {print if -f && -T _}' * + # remove (most) comments from C program + perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c + # make file a month younger than today, defeating reaper daemons + perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' * + # find first unused uid + perl -le '$i++ while getpwuid($i); print $i' + # display reasonable manpath + echo $PATH | perl -nl -072 -e ' + s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}' +OK, the last one was actually an Obfuscated Perl Contest entry. :-) +Why don't Perl one-liners work on my DOS/Mac/VMS system? +The problem is usually that the command interpreters on those systems have rather different ideas about quoting than the Unix shells under which the one-liners were created. On some systems, you may have to change single-quotes to double ones, which you must NOT do on Unix or Plan9 systems. You might also have to change a single % to a %%. +For example: + # Unix + perl -e 'print "Hello world\n"' + # DOS, etc. + perl -e "print \"Hello world\n\"" + # Mac + print "Hello world\n" + (then Run "Myscript" or Shift-Command-R) + # VMS + perl -e "print ""Hello world\n""" +The problem is that none of these examples are reliable: they depend on the command interpreter. Under Unix, the first two often work. Under DOS, it's entirely possible that neither works. If 4DOS was the command shell, you'd probably have better luck like this: + perl -e "print "Hello world\n"" +Under the Mac, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several quoting variants, except that it makes free use of the Mac's non-ASCII characters as control characters. +Using qq(), q(), and qx(), instead of "double quotes", 'single quotes', and `backticks`, may make one-liners easier to write. +There is no general solution to all of this. It is a mess, pure and simple. Sucks to be away from Unix, huh? :-) +[Some of this answer was contributed by Kenneth Albanowski.] +Where can I learn about CGI or Web programming in Perl? +For modules, get the CGI or LWP modules from CPAN. For textbooks, see the two especially dedicated to web stuff in the question on books. For problems and questions related to the web, like ``Why do I get 500 Errors'' or ``Why doesn't it run from the browser right when it runs fine on the command line'', see these sources: + WWW Security FAQ + http://www.w3.org/Security/Faq/ + Web FAQ + http://www.boutell.com/faq/ + CGI FAQ + http://www.webthing.com/tutorials/cgifaq.html + HTTP Spec + http://www.w3.org/pub/WWW/Protocols/HTTP/ + HTML Spec + http://www.w3.org/TR/REC-html40/ + http://www.w3.org/pub/WWW/MarkUp/ + CGI Spec + http://www.w3.org/CGI/ + CGI Security FAQ + http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt +Where can I learn about object-oriented Perl programming? +A good place to start is perltoot, and you can use perlobj, perlboot, and perlbot for reference. Perltoot didn't come out until the 5.004 release; you can get a copy (in pod, html, or postscript) from http://www.perl.com/CPAN/doc/FMTEYEWTK/ . +Where can I learn about linking C with Perl? [h2xs, xsubpp] +If you want to call C from Perl, start with perlxstut, moving on to perlxs, xsubpp, and perlguts. If you want to call Perl from C, then read perlembed, perlcall, and perlguts. Don't forget that you can learn a lot from looking at how the authors of existing extension modules wrote their code and solved their problems. +I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong? +Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they fail, see perlbug and send a bug report with the output of make test TEST_VERBOSE=1 along with perl -V. +When I tried to run my script, I got this message. What does it mean? +A complete list of Perl's error messages and warnings with explanatory text can be found in perldiag. You can also use the splain program (distributed with Perl) to explain the error messages: + perl program 2>diag.out + splain [-v] [-p] diag.out +or change your program to explain the messages for you: + use diagnostics; +or + use diagnostics -verbose; +What's MakeMaker? +This module (part of the standard Perl distribution) is designed to write a Makefile for an extension module from a Makefile.PL. For more information, see ExtUtils::MakeMaker. +AUTHOR AND COPYRIGHT +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. +When included as an integrated part of the Standard Distribution of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic License. For separate distributions of all or part of this FAQ outside of that, see perlfaq. +Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. \ No newline at end of file diff --git a/lib/Pod/Simple/t/perlvar.pod b/lib/Pod/Simple/t/perlvar.pod new file mode 100644 index 0000000000..765ff04825 --- /dev/null +++ b/lib/Pod/Simple/t/perlvar.pod @@ -0,0 +1,1234 @@ +=head1 NAME + +perlvar - Perl predefined variables + +=head1 DESCRIPTION + +=head2 Predefined Names + +The following names have special meaning to Perl. Most +punctuation names have reasonable mnemonics, or analogs in the +shells. Nevertheless, if you wish to use long variable names, +you need only say + + use English; + +at the top of your program. This will alias all the short names to the +long names in the current package. Some even have medium names, +generally borrowed from B. + +If you don't mind the performance hit, variables that depend on the +currently selected filehandle may instead be set by calling an +appropriate object method on the IO::Handle object. (Summary lines +below for this contain the word HANDLE.) First you must say + + use IO::Handle; + +after which you may use either + + method HANDLE EXPR + +or more safely, + + HANDLE->method(EXPR) + +Each method returns the old value of the IO::Handle attribute. +The methods each take an optional EXPR, which if supplied specifies the +new value for the IO::Handle attribute in question. If not supplied, +most methods do nothing to the current value--except for +autoflush(), which will assume a 1 for you, just to be different. +Because loading in the IO::Handle class is an expensive operation, you should +learn how to use the regular built-in variables. + +A few of these variables are considered "read-only". This means that if +you try to assign to this variable, either directly or indirectly through +a reference, you'll raise a run-time exception. + +The following list is ordered by scalar variables first, then the +arrays, then the hashes. + +=over 8 + +=item $ARG + +=item $_ + +The default input and pattern-searching space. The following pairs are +equivalent: + + while (<>) {...} # equivalent only in while! + while (defined($_ = <>)) {...} + + /^Subject:/ + $_ =~ /^Subject:/ + + tr/a-z/A-Z/ + $_ =~ tr/a-z/A-Z/ + + chomp + chomp($_) + +Here are the places where Perl will assume $_ even if you +don't use it: + +=over 3 + +=item * + +Various unary functions, including functions like ord() and int(), as well +as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to +STDIN. + +=item * + +Various list functions like print() and unlink(). + +=item * + +The pattern matching operations C, C, and C when used +without an C<=~> operator. + +=item * + +The default iterator variable in a C loop if no other +variable is supplied. + +=item * + +The implicit iterator variable in the grep() and map() functions. + +=item * + +The default place to put an input record when a C<< >> +operation's result is tested by itself as the sole criterion of a C +test. Outside a C test, this will not happen. + +=back + +(Mnemonic: underline is understood in certain operations.) + +=back + +=over 8 + +=item $> + +Contains the subpattern from the corresponding set of capturing +parentheses from the last pattern match, not counting patterns +matched in nested blocks that have been exited already. (Mnemonic: +like \digits.) These variables are all read-only and dynamically +scoped to the current BLOCK. + +=item $MATCH + +=item $& + +The string matched by the last successful pattern match (not counting +any matches hidden within a BLOCK or eval() enclosed by the current +BLOCK). (Mnemonic: like & in some editors.) This variable is read-only +and dynamically scoped to the current BLOCK. + +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See L. + +=item $PREMATCH + +=item $` + +The string preceding whatever was matched by the last successful +pattern match (not counting any matches hidden within a BLOCK or eval +enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted +string.) This variable is read-only. + +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See L. + +=item $POSTMATCH + +=item $' + +The string following whatever was matched by the last successful +pattern match (not counting any matches hidden within a BLOCK or eval() +enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted +string.) Example: + + $_ = 'abcdefghi'; + /def/; + print "$`:$&:$'\n"; # prints abc:def:ghi + +This variable is read-only and dynamically scoped to the current BLOCK. + +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See L. + +=item $LAST_PAREN_MATCH + +=item $+ + +The last bracket matched by the last search pattern. This is useful if +you don't know which one of a set of alternative patterns matched. For +example: + + /Version: (.*)|Revision: (.*)/ && ($rev = $+); + +(Mnemonic: be positive and forward looking.) +This variable is read-only and dynamically scoped to the current BLOCK. + +=item @LAST_MATCH_END + +=item @+ + +This array holds the offsets of the ends of the last successful +submatches in the currently active dynamic scope. C<$+[0]> is +the offset into the string of the end of the entire match. This +is the same value as what the C function returns when called +on the variable that was matched against. The Ith element +of this array holds the offset of the Ith submatch, so +C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset +past where $2 ends, and so on. You can use C<$#+> to determine +how many subgroups were in the last successful match. See the +examples given for the C<@-> variable. + +=item $MULTILINE_MATCHING + +=item $* + +Set to a non-zero integer value to do multi-line matching within a +string, 0 (or undefined) to tell Perl that it can assume that strings +contain a single line, for the purpose of optimizing pattern matches. +Pattern matches on strings containing multiple newlines can produce +confusing results when C<$*> is 0 or undefined. Default is undefined. +(Mnemonic: * matches multiple things.) This variable influences the +interpretation of only C<^> and C<$>. A literal newline can be searched +for even when C<$* == 0>. + +Use of C<$*> is deprecated in modern Perl, supplanted by +the C and C modifiers on pattern matching. + +Assigning a non-numerical value to C<$*> triggers a warning (and makes +C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> +makes that an implicit C is applied on the value. + +=item input_line_number HANDLE EXPR + +=item $INPUT_LINE_NUMBER + +=item $NR + +=item $. + +The current input record number for the last file handle from which +you just read() (or called a C or C on). The value +may be different from the actual physical line number in the file, +depending on what notion of "line" is in effect--see C<$/> on how +to change that. An explicit close on a filehandle resets the line +number. Because C<< <> >> never does an explicit close, line +numbers increase across ARGV files (but see examples in L). +Consider this variable read-only: setting it does not reposition +the seek pointer; you'll have to do that on your own. Localizing C<$.> +has the effect of also localizing Perl's notion of "the last read +filehandle". (Mnemonic: many programs use "." to mean the current line +number.) + +=item input_record_separator HANDLE EXPR + +=item $INPUT_RECORD_SEPARATOR + +=item $RS + +=item $/ + +The input record separator, newline by default. This +influences Perl's idea of what a "line" is. Works like B's RS +variable, including treating empty lines as a terminator if set to +the null string. (An empty line cannot contain any spaces +or tabs.) You may set it to a multi-character string to match a +multi-character terminator, or to C to read through the end +of file. Setting it to C<"\n\n"> means something slightly +different than setting to C<"">, if the file contains consecutive +empty lines. Setting to C<""> will treat two or more consecutive +empty lines as a single empty line. Setting to C<"\n\n"> will +blindly assume that the next input character belongs to the next +paragraph, even if it's a newline. (Mnemonic: / delimits +line boundaries when quoting poetry.) + + undef $/; # enable "slurp" mode + $_ = ; # whole file now here + s/\n[ \t]+/ /g; + +Remember: the value of C<$/> is a string, not a regex. B has to be +better for something. :-) + +Setting C<$/> to a reference to an integer, scalar containing an integer, or +scalar that's convertible to an integer will attempt to read records +instead of lines, with the maximum record size being the referenced +integer. So this: + + $/ = \32768; # or \"32768", or \$var_containing_32768 + open(FILE, $myfile); + $_ = ; + +will read a record of no more than 32768 bytes from FILE. If you're +not reading from a record-oriented file (or your OS doesn't have +record-oriented files), then you'll likely get a full chunk of data +with every read. If a record is larger than the record size you've +set, you'll get the record back in pieces. + +On VMS, record reads are done with the equivalent of C, +so it's best not to mix record and non-record reads on the same +file. (This is unlikely to be a problem, because any file you'd +want to read in record mode is probably unusable in line mode.) +Non-VMS systems do normal I/O, so it's safe to mix record and +non-record reads of a file. + +See also L. Also see C<$.>. + +=item autoflush HANDLE EXPR + +=item $OUTPUT_AUTOFLUSH + +=item $| + +If set to nonzero, forces a flush right away and after every write +or print on the currently selected output channel. Default is 0 +(regardless of whether the channel is really buffered by the +system or not; C<$|> tells you only whether you've asked Perl +explicitly to flush after each write). STDOUT will +typically be line buffered if output is to the terminal and block +buffered otherwise. Setting this variable is useful primarily when +you are outputting to a pipe or socket, such as when you are running +a Perl program under B and want to see the output as it's +happening. This has no effect on input buffering. See L +for that. (Mnemonic: when you want your pipes to be piping hot.) + +=item output_field_separator HANDLE EXPR + +=item $OUTPUT_FIELD_SEPARATOR + +=item $OFS + +=item $, + +The output field separator for the print operator. Ordinarily the +print operator simply prints out its arguments without further +adornment. To get behavior more like B, set this variable as +you would set B's OFS variable to specify what is printed +between fields. (Mnemonic: what is printed when there is a "," in +your print statement.) + +=item output_record_separator HANDLE EXPR + +=item $OUTPUT_RECORD_SEPARATOR + +=item $ORS + +=item $\ + +The output record separator for the print operator. Ordinarily the +print operator simply prints out its arguments as is, with no +trailing newline or other end-of-record string added. To get +behavior more like B, set this variable as you would set +B's ORS variable to specify what is printed at the end of the +print. (Mnemonic: you set C<$\> instead of adding "\n" at the +end of the print. Also, it's just like C<$/>, but it's what you +get "back" from Perl.) + +=item $LIST_SEPARATOR + +=item $" + +This is like C<$,> except that it applies to array and slice values +interpolated into a double-quoted string (or similar interpreted +string). Default is a space. (Mnemonic: obvious, I think.) + +=item $SUBSCRIPT_SEPARATOR + +=item $SUBSEP + +=item $; + +The subscript separator for multidimensional array emulation. If you +refer to a hash element as + + $foo{$a,$b,$c} + +it really means + + $foo{join($;, $a, $b, $c)} + +But don't put + + @foo{$a,$b,$c} # a slice--note the @ + +which means + + ($foo{$a},$foo{$b},$foo{$c}) + +Default is "\034", the same as SUBSEP in B. If your +keys contain binary data there might not be any safe value for C<$;>. +(Mnemonic: comma (the syntactic subscript separator) is a +semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already +taken for something more important.) + +Consider using "real" multidimensional arrays as described +in L. + +=item $OFMT + +=item $# + +The output format for printed numbers. This variable is a half-hearted +attempt to emulate B's OFMT variable. There are times, however, +when B and Perl have differing notions of what counts as +numeric. The initial value is "%.Ig", where I is the value +of the macro DBL_DIG from your system's F. This is different from +B's default OFMT setting of "%.6g", so you need to set C<$#> +explicitly to get B's value. (Mnemonic: # is the number sign.) + +Use of C<$#> is deprecated. + +=item format_page_number HANDLE EXPR + +=item $FORMAT_PAGE_NUMBER + +=item $% + +The current page number of the currently selected output channel. +Used with formats. +(Mnemonic: % is page number in B.) + +=item format_lines_per_page HANDLE EXPR + +=item $FORMAT_LINES_PER_PAGE + +=item $= + +The current page length (printable lines) of the currently selected +output channel. Default is 60. +Used with formats. +(Mnemonic: = has horizontal lines.) + +=item format_lines_left HANDLE EXPR + +=item $FORMAT_LINES_LEFT + +=item $- + +The number of lines left on the page of the currently selected output +channel. +Used with formats. +(Mnemonic: lines_on_page - lines_printed.) + +=item @LAST_MATCH_START + +=item @- + +$-[0] is the offset of the start of the last successful match. +C<$-[>IC<]> is the offset of the start of the substring matched by +I-th subpattern, or undef if the subpattern did not match. + +Thus after a match against $_, $& coincides with C. Similarly, C<$>I coincides with CIC<], +$+[>IC<] - $-[>IC<]> if C<$-[>IC<]> is defined, and $+ coincides with +C. One can use C<$#-> to find the last +matched subgroup in the last successful match. Contrast with +C<$#+>, the number of subgroups in the regular expression. Compare +with C<@+>. + +This array holds the offsets of the beginnings of the last +successful submatches in the currently active dynamic scope. +C<$-[0]> is the offset into the string of the beginning of the +entire match. The Ith element of this array holds the offset +of the Ith submatch, so C<$+[1]> is the offset where $1 +begins, C<$+[2]> the offset where $2 begins, and so on. +You can use C<$#-> to determine how many subgroups were in the +last successful match. Compare with the C<@+> variable. + +After a match against some variable $var: + +=over 5 + +=item C<$`> is the same as C + +=item C<$&> is the same as C + +=item C<$'> is the same as C + +=item C<$1> is the same as C + +=item C<$2> is the same as C + +=item C<$3> is the same as C + +=back + +=item format_name HANDLE EXPR + +=item $FORMAT_NAME + +=item $~ + +The name of the current report format for the currently selected output +channel. Default is the name of the filehandle. (Mnemonic: brother to +C<$^>.) + +=item format_top_name HANDLE EXPR + +=item $FORMAT_TOP_NAME + +=item $^ + +The name of the current top-of-page format for the currently selected +output channel. Default is the name of the filehandle with _TOP +appended. (Mnemonic: points to top of page.) + +=item format_line_break_characters HANDLE EXPR + +=item $FORMAT_LINE_BREAK_CHARACTERS + +=item $: + +The current set of characters after which a string may be broken to +fill continuation fields (starting with ^) in a format. Default is +S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in +poetry is a part of a line.) + +=item format_formfeed HANDLE EXPR + +=item $FORMAT_FORMFEED + +=item $^L + +What formats output as a form feed. Default is \f. + +=item $ACCUMULATOR + +=item $^A + +The current value of the write() accumulator for format() lines. A format +contains formline() calls that put their result into C<$^A>. After +calling its format, write() prints out the contents of C<$^A> and empties. +So you never really see the contents of C<$^A> unless you call +formline() yourself and then look at it. See L and +L. + +=item $CHILD_ERROR + +=item $? + +The status returned by the last pipe close, backtick (C<``>) command, +successful call to wait() or waitpid(), or from the system() +operator. This is just the 16-bit status word returned by the +wait() system call (or else is made up to look like it). Thus, the +exit value of the subprocess is really (C<<< $? >> 8 >>>), and +C<$? & 127> gives which signal, if any, the process died from, and +C<$? & 128> reports whether there was a core dump. (Mnemonic: +similar to B and B.) + +Additionally, if the C variable is supported in C, its value +is returned via $? if any C function fails. + +If you have installed a signal handler for C, the +value of C<$?> will usually be wrong outside that handler. + +Inside an C subroutine C<$?> contains the value that is going to be +given to C. You can modify C<$?> in an C subroutine to +change the exit status of your program. For example: + + END { + $? = 1 if $? == 255; # die would make it 255 + } + +Under VMS, the pragma C makes C<$?> reflect the +actual VMS exit status, instead of the default emulation of POSIX +status. + +Also see L. + +=item $OS_ERROR + +=item $ERRNO + +=item $! + +If used numerically, yields the current value of the C C +variable, with all the usual caveats. (This means that you shouldn't +depend on the value of C<$!> to be anything in particular unless +you've gotten a specific error return indicating a system error.) +If used an a string, yields the corresponding system error string. +You can assign a number to C<$!> to set I if, for instance, +you want C<"$!"> to return the string for error I, or you want +to set the exit value for the die() operator. (Mnemonic: What just +went bang?) + +Also see L. + +=item $EXTENDED_OS_ERROR + +=item $^E + +Error information specific to the current operating system. At +the moment, this differs from C<$!> under only VMS, OS/2, and Win32 +(and for MacPerl). On all other platforms, C<$^E> is always just +the same as C<$!>. + +Under VMS, C<$^E> provides the VMS status value from the last +system error. This is more specific information about the last +system error than that provided by C<$!>. This is particularly +important when C<$!> is set to B. + +Under OS/2, C<$^E> is set to the error code of the last call to +OS/2 API either via CRT, or directly from perl. + +Under Win32, C<$^E> always returns the last error information +reported by the Win32 call C which describes +the last error from within the Win32 API. Most Win32-specific +code will report errors via C<$^E>. ANSI C and Unix-like calls +set C and so most portable Perl code will report errors +via C<$!>. + +Caveats mentioned in the description of C<$!> generally apply to +C<$^E>, also. (Mnemonic: Extra error explanation.) + +Also see L. + +=item $EVAL_ERROR + +=item $@ + +The Perl syntax error message from the last eval() operator. If null, the +last eval() parsed and executed correctly (although the operations you +invoked may have failed in the normal fashion). (Mnemonic: Where was +the syntax error "at"?) + +Warning messages are not collected in this variable. You can, +however, set up a routine to process warnings by setting C<$SIG{__WARN__}> +as described below. + +Also see L. + +=item $PROCESS_ID + +=item $PID + +=item $$ + +The process number of the Perl running this script. You should +consider this variable read-only, although it will be altered +across fork() calls. (Mnemonic: same as shells.) + +=item $REAL_USER_ID + +=item $UID + +=item $< + +The real uid of this process. (Mnemonic: it's the uid you came I, +if you're running setuid.) + +=item $EFFECTIVE_USER_ID + +=item $EUID + +=item $> + +The effective uid of this process. Example: + + $< = $>; # set real to effective uid + ($<,$>) = ($>,$<); # swap real and effective uid + +(Mnemonic: it's the uid you went I, if you're running setuid.) +C<< $< >> and C<< $> >> can be swapped only on machines +supporting setreuid(). + +=item $REAL_GROUP_ID + +=item $GID + +=item $( + +The real gid of this process. If you are on a machine that supports +membership in multiple groups simultaneously, gives a space separated +list of groups you are in. The first number is the one returned by +getgid(), and the subsequent ones by getgroups(), one of which may be +the same as the first number. + +However, a value assigned to C<$(> must be a single number used to +set the real gid. So the value given by C<$(> should I be assigned +back to C<$(> without being forced numeric, such as by adding zero. + +(Mnemonic: parentheses are used to I things. The real gid is the +group you I, if you're running setgid.) + +=item $EFFECTIVE_GROUP_ID + +=item $EGID + +=item $) + +The effective gid of this process. If you are on a machine that +supports membership in multiple groups simultaneously, gives a space +separated list of groups you are in. The first number is the one +returned by getegid(), and the subsequent ones by getgroups(), one of +which may be the same as the first number. + +Similarly, a value assigned to C<$)> must also be a space-separated +list of numbers. The first number sets the effective gid, and +the rest (if any) are passed to setgroups(). To get the effect of an +empty list for setgroups(), just repeat the new effective gid; that is, +to force an effective gid of 5 and an effectively empty setgroups() +list, say C< $) = "5 5" >. + +(Mnemonic: parentheses are used to I things. The effective gid +is the group that's I for you, if you're running setgid.) + +C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on +machines that support the corresponding I routine. C<$(> +and C<$)> can be swapped only on machines supporting setregid(). + +=item $PROGRAM_NAME + +=item $0 + +Contains the name of the program being executed. On some operating +systems assigning to C<$0> modifies the argument area that the B +program sees. This is more useful as a way of indicating the current +program state than it is for hiding the program you're running. +(Mnemonic: same as B and B.) + +Note for BSD users: setting C<$0> does not completely remove "perl" +from the ps(1) output. For example, setting C<$0> to C<"foobar"> will +result in C<"perl: foobar (perl)">. This is an operating system +feature. + +=item $[ + +The index of the first element in an array, and of the first character +in a substring. Default is 0, but you could theoretically set it +to 1 to make Perl behave more like B (or Fortran) when +subscripting and when evaluating the index() and substr() functions. +(Mnemonic: [ begins subscripts.) + +As of release 5 of Perl, assignment to C<$[> is treated as a compiler +directive, and cannot influence the behavior of any other file. +Its use is highly discouraged. + +=item $] + +The version + patchlevel / 1000 of the Perl interpreter. This variable +can be used to determine whether the Perl interpreter executing a +script is in the right range of versions. (Mnemonic: Is this version +of perl in the right bracket?) Example: + + warn "No checksumming!\n" if $] < 3.019; + +See also the documentation of C and C +for a convenient way to fail if the running Perl interpreter is too old. + +The use of this variable is deprecated. The floating point representation +can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a +more modern representation of the Perl version that allows accurate string +comparisons. + +=item $COMPILING + +=item $^C + +The current value of the flag associated with the B<-c> switch. +Mainly of use with B<-MO=...> to allow code to alter its behavior +when being compiled, such as for example to AUTOLOAD at compile +time rather than normal, deferred loading. See L. Setting +C<$^C = 1> is similar to calling C. + +=item $DEBUGGING + +=item $^D + +The current value of the debugging flags. (Mnemonic: value of B<-D> +switch.) + +=item $SYSTEM_FD_MAX + +=item $^F + +The maximum system file descriptor, ordinarily 2. System file +descriptors are passed to exec()ed processes, while higher file +descriptors are not. Also, during an open(), system file descriptors are +preserved even if the open() fails. (Ordinary file descriptors are +closed before the open() is attempted.) The close-on-exec +status of a file descriptor will be decided according to the value of +C<$^F> when the corresponding file, pipe, or socket was opened, not the +time of the exec(). + +=item $^H + +WARNING: This variable is strictly for internal use only. Its availability, +behavior, and contents are subject to change without notice. + +This variable contains compile-time hints for the Perl interpreter. At the +end of compilation of a BLOCK the value of this variable is restored to the +value when the interpreter started to compile the BLOCK. + +When perl begins to parse any block construct that provides a lexical scope +(e.g., eval body, required file, subroutine body, loop body, or conditional +block), the existing value of $^H is saved, but its value is left unchanged. +When the compilation of the block is completed, it regains the saved value. +Between the points where its value is saved and restored, code that +executes within BEGIN blocks is free to change the value of $^H. + +This behavior provides the semantic of lexical scoping, and is used in, +for instance, the C pragma. + +The contents should be an integer; different bits of it are used for +different pragmatic flags. Here's an example: + + sub add_100 { $^H |= 0x100 } + + sub foo { + BEGIN { add_100() } + bar->baz($boon); + } + +Consider what happens during execution of the BEGIN block. At this point +the BEGIN block has already been compiled, but the body of foo() is still +being compiled. The new value of $^H will therefore be visible only while +the body of foo() is being compiled. + +Substitution of the above BEGIN block with: + + BEGIN { require strict; strict->import('vars') } + +demonstrates how C is implemented. Here's a conditional +version of the same lexical pragma: + + BEGIN { require strict; strict->import('vars') if $condition } + +=item %^H + +WARNING: This variable is strictly for internal use only. Its availability, +behavior, and contents are subject to change without notice. + +The %^H hash provides the same scoping semantic as $^H. This makes it +useful for implementation of lexically scoped pragmas. + +=item $INPLACE_EDIT + +=item $^I + +The current value of the inplace-edit extension. Use C to disable +inplace editing. (Mnemonic: value of B<-i> switch.) + +=item $^M + +By default, running out of memory is an untrappable, fatal error. +However, if suitably built, Perl can use the contents of C<$^M> +as an emergency memory pool after die()ing. Suppose that your Perl +were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. +Then + + $^M = 'a' x (1 << 16); + +would allocate a 64K buffer for use in an emergency. See the +F file in the Perl distribution for information on how to +enable this option. To discourage casual use of this advanced +feature, there is no L long name for this variable. + +=item $OSNAME + +=item $^O + +The name of the operating system under which this copy of Perl was +built, as determined during the configuration process. The value +is identical to C<$Config{'osname'}>. See also L and the +B<-V> command-line switch documented in L. + +=item $PERLDB + +=item $^P + +The internal variable for debugging support. The meanings of the +various bits are subject to change, but currently indicate: + +=over 6 + +=item 0x01 + +Debug subroutine enter/exit. + +=item 0x02 + +Line-by-line debugging. + +=item 0x04 + +Switch off optimizations. + +=item 0x08 + +Preserve more data for future interactive inspections. + +=item 0x10 + +Keep info about source lines on which a subroutine is defined. + +=item 0x20 + +Start with single-step on. + +=item 0x40 + +Use subroutine address instead of name when reporting. + +=item 0x80 + +Report C as well. + +=item 0x100 + +Provide informative "file" names for evals based on the place they were compiled. + +=item 0x200 + +Provide informative names to anonymous subroutines based on the place they +were compiled. + +=back + +Some bits may be relevant at compile-time only, some at +run-time only. This is a new mechanism and the details may change. + +=item $LAST_REGEXP_CODE_RESULT + +=item $^R + +The result of evaluation of the last successful C<(?{ code })> +regular expression assertion (see L). May be written to. + +=item $EXCEPTIONS_BEING_CAUGHT + +=item $^S + +Current state of the interpreter. Undefined if parsing of the current +module/eval is not finished (may happen in $SIG{__DIE__} and +$SIG{__WARN__} handlers). True if inside an eval(), otherwise false. + +=item $BASETIME + +=item $^T + +The time at which the program began running, in seconds since the +epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, +and B<-C> filetests are based on this value. + +=item $PERL_VERSION + +=item $^V + +The revision, version, and subversion of the Perl interpreter, represented +as a string composed of characters with those ordinals. Thus in Perl v5.6.0 +it equals C and will return true for +C<$^V eq v5.6.0>. Note that the characters in this string value can +potentially be in Unicode range. + +This can be used to determine whether the Perl interpreter executing a +script is in the right range of versions. (Mnemonic: use ^V for Version +Control.) Example: + + warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; + +See the documentation of C and C +for a convenient way to fail if the running Perl interpreter is too old. + +See also C<$]> for an older representation of the Perl version. + +=item $WARNING + +=item $^W + +The current value of the warning switch, initially true if B<-w> +was used, false otherwise, but directly modifiable. (Mnemonic: +related to the B<-w> switch.) See also L. + +=item ${^WARNING_BITS} + +The current set of warning checks enabled by the C pragma. +See the documentation of C for more details. + +=item ${^WIDE_SYSTEM_CALLS} + +Global flag that enables system calls made by Perl to use wide character +APIs native to the system, if available. This is currently only implemented +on the Windows platform. + +This can also be enabled from the command line using the C<-C> switch. + +The initial value is typically C<0> for compatibility with Perl versions +earlier than 5.6, but may be automatically set to C<1> by Perl if the system +provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>). + +The C pragma always overrides the effect of this flag in the current +lexical scope. See L. + +=item $EXECUTABLE_NAME + +=item $^X + +The name that the Perl binary itself was executed as, from C's C. +This may not be a full pathname, nor even necessarily in your path. + +=item $ARGV + +contains the name of the current file when reading from <>. + +=item @ARGV + +The array @ARGV contains the command-line arguments intended for +the script. C<$#ARGV> is generally the number of arguments minus +one, because C<$ARGV[0]> is the first argument, I the program's +command name itself. See C<$0> for the command name. + +=item @INC + +The array @INC contains the list of places that the C, +C, or C constructs look for their library files. It +initially consists of the arguments to any B<-I> command-line +switches, followed by the default Perl library, probably +F, followed by ".", to represent the current +directory. If you need to modify this at runtime, you should use +the C pragma to get the machine-dependent library properly +loaded also: + + use lib '/mypath/libdir/'; + use SomeMod; + +=item @_ + +Within a subroutine the array @_ contains the parameters passed to that +subroutine. See L. + +=item %INC + +The hash %INC contains entries for each filename included via the +C, C, or C operators. The key is the filename +you specified (with module names converted to pathnames), and the +value is the location of the file found. The C +operator uses this hash to determine whether a particular file has +already been included. + +=item %ENV + +=item $ENV{expr} + +The hash %ENV contains your current environment. Setting a +value in C changes the environment for any child processes +you subsequently fork() off. + +=item %SIG + +=item $SIG{expr} + +The hash %SIG contains signal handlers for signals. For example: + + sub handler { # 1st argument is signal name + my($sig) = @_; + print "Caught a SIG$sig--shutting down\n"; + close(LOG); + exit(0); + } + + $SIG{'INT'} = \&handler; + $SIG{'QUIT'} = \&handler; + ... + $SIG{'INT'} = 'DEFAULT'; # restore default action + $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT + +Using a value of C<'IGNORE'> usually has the effect of ignoring the +signal, except for the C signal. See L for more about +this special case. + +Here are some other examples: + + $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) + $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber + $SIG{"PIPE"} = *Plumber; # somewhat esoteric + $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? + +Be sure not to use a bareword as the name of a signal handler, +lest you inadvertently call it. + +If your system has the sigaction() function then signal handlers are +installed using it. This means you get reliable signal handling. If +your system has the SA_RESTART flag it is used when signals handlers are +installed. This means that system calls for which restarting is supported +continue rather than returning when a signal arrives. If you want your +system calls to be interrupted by signal delivery then do something like +this: + + use POSIX ':signal_h'; + + my $alarm = 0; + sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } + or die "Error setting SIGALRM handler: $!\n"; + +See L. + +Certain internal hooks can be also set using the %SIG hash. The +routine indicated by C<$SIG{__WARN__}> is called when a warning message is +about to be printed. The warning message is passed as the first +argument. The presence of a __WARN__ hook causes the ordinary printing +of warnings to STDERR to be suppressed. You can use this to save warnings +in a variable, or turn warnings into fatal errors, like this: + + local $SIG{__WARN__} = sub { die $_[0] }; + eval $proggie; + +The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception +is about to be thrown. The error message is passed as the first +argument. When a __DIE__ hook routine returns, the exception +processing continues as it would have in the absence of the hook, +unless the hook routine itself exits via a C, a loop exit, or a die(). +The C<__DIE__> handler is explicitly disabled during the call, so that you +can die from a C<__DIE__> handler. Similarly for C<__WARN__>. + +Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called +even inside an eval(). Do not use this to rewrite a pending exception +in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). +This strange action at a distance may be fixed in a future release +so that C<$SIG{__DIE__}> is only called if your program is about +to exit, as was the original intent. Any other use is deprecated. + +C<__DIE__>/C<__WARN__> handlers are very special in one respect: +they may be called to report (probable) errors found by the parser. +In such a case the parser may be in inconsistent state, so any +attempt to evaluate Perl code from such a handler will probably +result in a segfault. This means that warnings or errors that +result from parsing Perl should be used with extreme caution, like +this: + + require Carp if defined $^S; + Carp::confess("Something wrong") if defined &Carp::confess; + die "Something wrong, but could not load Carp to give backtrace... + To see backtrace try starting Perl with -MCarp switch"; + +Here the first line will load Carp I it is the parser who +called the handler. The second line will print backtrace and die if +Carp was available. The third line will be executed only if Carp was +not available. + +See L, L, L, and +L for additional information. + +=back + +=head2 Error Indicators + +The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information +about different types of error conditions that may appear during +execution of a Perl program. The variables are shown ordered by +the "distance" between the subsystem which reported the error and +the Perl process. They correspond to errors detected by the Perl +interpreter, C library, operating system, or an external program, +respectively. + +To illustrate the differences between these variables, consider the +following Perl expression, which uses a single-quoted string: + + eval q{ + open PIPE, "/cdrom/install |"; + @res = ; + close PIPE or die "bad pipe: $?, $!"; + }; + +After execution of this statement all 4 variables may have been set. + +C<$@> is set if the string to be C-ed did not compile (this +may happen if C or C were imported with bad prototypes), +or if Perl code executed during evaluation die()d . In these cases +the value of $@ is the compile error, or the argument to C +(which will interpolate C<$!> and C<$?>!). (See also L, +though.) + +When the eval() expression above is executed, open(), C<< >>, +and C are translated to calls in the C run-time library and +thence to the operating system kernel. C<$!> is set to the C library's +C if one of these calls fails. + +Under a few operating systems, C<$^E> may contain a more verbose +error indicator, such as in this case, "CDROM tray not closed." +Systems that do not support extended error messages leave C<$^E> +the same as C<$!>. + +Finally, C<$?> may be set to non-0 value if the external program +F fails. The upper eight bits reflect specific +error conditions encountered by the program (the program's exit() +value). The lower eight bits reflect mode of failure, like signal +death and core dump information See wait(2) for details. In +contrast to C<$!> and C<$^E>, which are set only if error condition +is detected, the variable C<$?> is set on each C or pipe +C, overwriting the old value. This is more like C<$@>, which +on every eval() is always set on failure and cleared on success. + +For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, +and C<$?>. + +=head2 Technical Note on the Syntax of Variable Names + +Variable names in Perl can have several formats. Usually, they +must begin with a letter or underscore, in which case they can be +arbitrarily long (up to an internal limit of 251 characters) and +may contain letters, digits, underscores, or the special sequence +C<::> or C<'>. In this case, the part before the last C<::> or +C<'> is taken to be a I; see L. + +Perl variable names may also be a sequence of digits or a single +punctuation or control character. These names are all reserved for +special uses by Perl; for example, the all-digits names are used +to hold data captured by backreferences after a regular expression +match. Perl has a special syntax for the single-control-character +names: It understands C<^X> (caret C) to mean the control-C +character. For example, the notation C<$^W> (dollar-sign caret +C) is the scalar variable whose name is the single character +control-C. This is better than typing a literal control-C +into your program. + +Finally, new in Perl 5.6, Perl variable names may be alphanumeric +strings that begin with control characters (or better yet, a caret). +These variables must be written in the form C<${^Foo}>; the braces +are not optional. C<${^Foo}> denotes the scalar variable whose +name is a control-C followed by two C's. These variables are +reserved for future special uses by Perl, except for the ones that +begin with C<^_> (control-underscore or caret-underscore). No +control-character name that begins with C<^_> will acquire a special +meaning in any future version of Perl; such names may therefore be +used safely in programs. C<$^_> itself, however, I reserved. + +Perl identifiers that begin with digits, control characters, or +punctuation characters are exempt from the effects of the C +declaration and are always forced to be in package C
. A few +other names are also exempt: + + ENV STDIN + INC STDOUT + ARGV STDERR + ARGVOUT + SIG + +In particular, the new special C<${^_XYZ}> variables are always taken +to be in package C
, regardless of any C declarations +presently in scope. + +=head1 BUGS + +Due to an unfortunate accident of Perl's implementation, C imposes a considerable performance penalty on all regular +expression matches in a program, regardless of whether they occur +in the scope of C. For that reason, saying C in libraries is strongly discouraged. See the +Devel::SawAmpersand module documentation from CPAN +(http://www.perl.com/CPAN/modules/by-module/Devel/) +for more information. + +Having to even think about the C<$^S> variable in your exception +handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented +invites grievous and difficult to track down errors. Avoid it +and use an C or CORE::GLOBAL::die override instead. diff --git a/lib/Pod/Simple/t/perlvar_out.txt b/lib/Pod/Simple/t/perlvar_out.txt new file mode 100644 index 0000000000..0a67979962 --- /dev/null +++ b/lib/Pod/Simple/t/perlvar_out.txt @@ -0,0 +1,406 @@ +NAME +perlvar - Perl predefined variables +DESCRIPTION +Predefined Names +The following names have special meaning to Perl. Most punctuation names have reasonable mnemonics, or analogs in the shells. Nevertheless, if you wish to use long variable names, you need only say + use English; +at the top of your program. This will alias all the short names to the long names in the current package. Some even have medium names, generally borrowed from awk. +If you don't mind the performance hit, variables that depend on the currently selected filehandle may instead be set by calling an appropriate object method on the IO::Handle object. (Summary lines below for this contain the word HANDLE.) First you must say + use IO::Handle; +after which you may use either + method HANDLE EXPR +or more safely, + HANDLE->method(EXPR) +Each method returns the old value of the IO::Handle attribute. The methods each take an optional EXPR, which if supplied specifies the new value for the IO::Handle attribute in question. If not supplied, most methods do nothing to the current value--except for autoflush(), which will assume a 1 for you, just to be different. Because loading in the IO::Handle class is an expensive operation, you should learn how to use the regular built-in variables. +A few of these variables are considered "read-only". This means that if you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception. +The following list is ordered by scalar variables first, then the arrays, then the hashes. +$ARG +$_ +The default input and pattern-searching space. The following pairs are equivalent: + while (<>) {...} # equivalent only in while! + while (defined($_ = <>)) {...} + /^Subject:/ + $_ =~ /^Subject:/ + tr/a-z/A-Z/ + $_ =~ tr/a-z/A-Z/ + chomp + chomp($_) +Here are the places where Perl will assume $_ even if you don't use it: + Various unary functions, including functions like ord() and int(), as well as the all file tests (-f, -d) except for -t, which defaults to STDIN. + Various list functions like print() and unlink(). + The pattern matching operations m//, s///, and tr/// when used without an =~ operator. + The default iterator variable in a foreach loop if no other variable is supplied. + The implicit iterator variable in the grep() and map() functions. + The default place to put an input record when a operation's result is tested by itself as the sole criterion of a while test. Outside a while test, this will not happen. +(Mnemonic: underline is understood in certain operations.) +$ +Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digits.) These variables are all read-only and dynamically scoped to the current BLOCK. +$MATCH +$& +The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: like & in some editors.) This variable is read-only and dynamically scoped to the current BLOCK. +The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. +$PREMATCH +$` +The string preceding whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted string.) This variable is read-only. +The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. +$POSTMATCH +$' +The string following whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted string.) Example: + $_ = 'abcdefghi'; + /def/; + print "$`:$&:$'\n"; # prints abc:def:ghi +This variable is read-only and dynamically scoped to the current BLOCK. +The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. +$LAST_PAREN_MATCH +$+ +The last bracket matched by the last search pattern. This is useful if you don't know which one of a set of alternative patterns matched. For example: + /Version: (.*)|Revision: (.*)/ && ($rev = $+); +(Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. +@LAST_MATCH_END +@+ +This array holds the offsets of the ends of the last successful submatches in the currently active dynamic scope. $+[0] is the offset into the string of the end of the entire match. This is the same value as what the pos function returns when called on the variable that was matched against. The nth element of this array holds the offset of the nth submatch, so $+[1] is the offset past where $1 ends, $+[2] the offset past where $2 ends, and so on. You can use $#+ to determine how many subgroups were in the last successful match. See the examples given for the @- variable. +$MULTILINE_MATCHING +$* +Set to a non-zero integer value to do multi-line matching within a string, 0 (or undefined) to tell Perl that it can assume that strings contain a single line, for the purpose of optimizing pattern matches. Pattern matches on strings containing multiple newlines can produce confusing results when $* is 0 or undefined. Default is undefined. (Mnemonic: * matches multiple things.) This variable influences the interpretation of only ^ and $. A literal newline can be searched for even when $* == 0. +Use of $* is deprecated in modern Perl, supplanted by the /s and /m modifiers on pattern matching. +Assigning a non-numerical value to $* triggers a warning (and makes $* act if $* == 0), while assigning a numerical value to $* makes that an implicit int is applied on the value. +input_line_number HANDLE EXPR +$INPUT_LINE_NUMBER +$NR +$. +The current input record number for the last file handle from which you just read() (or called a seek or tell on). The value may be different from the actual physical line number in the file, depending on what notion of "line" is in effect--see $/ on how to change that. An explicit close on a filehandle resets the line number. Because <> never does an explicit close, line numbers increase across ARGV files (but see examples in "eof" in perlfunc). Consider this variable read-only: setting it does not reposition the seek pointer; you'll have to do that on your own. Localizing $. has the effect of also localizing Perl's notion of "the last read filehandle". (Mnemonic: many programs use "." to mean the current line number.) +input_record_separator HANDLE EXPR +$INPUT_RECORD_SEPARATOR +$RS +$/ +The input record separator, newline by default. This influences Perl's idea of what a "line" is. Works like awk's RS variable, including treating empty lines as a terminator if set to the null string. (An empty line cannot contain any spaces or tabs.) You may set it to a multi-character string to match a multi-character terminator, or to undef to read through the end of file. Setting it to "\n\n" means something slightly different than setting to "", if the file contains consecutive empty lines. Setting to "" will treat two or more consecutive empty lines as a single empty line. Setting to "\n\n" will blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / delimits line boundaries when quoting poetry.) + undef $/; # enable "slurp" mode + $_ = ; # whole file now here + s/\n[ \t]+/ /g; +Remember: the value of $/ is a string, not a regex. awk has to be better for something. :-) +Setting $/ to a reference to an integer, scalar containing an integer, or scalar that's convertible to an integer will attempt to read records instead of lines, with the maximum record size being the referenced integer. So this: + $/ = \32768; # or \"32768", or \$var_containing_32768 + open(FILE, $myfile); + $_ = ; +will read a record of no more than 32768 bytes from FILE. If you're not reading from a record-oriented file (or your OS doesn't have record-oriented files), then you'll likely get a full chunk of data with every read. If a record is larger than the record size you've set, you'll get the record back in pieces. +On VMS, record reads are done with the equivalent of sysread, so it's best not to mix record and non-record reads on the same file. (This is unlikely to be a problem, because any file you'd want to read in record mode is probably unusable in line mode.) Non-VMS systems do normal I/O, so it's safe to mix record and non-record reads of a file. +See also "Newlines" in perlport. Also see $.. +autoflush HANDLE EXPR +$OUTPUT_AUTOFLUSH +$| +If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 (regardless of whether the channel is really buffered by the system or not; $| tells you only whether you've asked Perl explicitly to flush after each write). STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe or socket, such as when you are running a Perl program under rsh and want to see the output as it's happening. This has no effect on input buffering. See "getc" in perlfunc for that. (Mnemonic: when you want your pipes to be piping hot.) +output_field_separator HANDLE EXPR +$OUTPUT_FIELD_SEPARATOR +$OFS +$, +The output field separator for the print operator. Ordinarily the print operator simply prints out its arguments without further adornment. To get behavior more like awk, set this variable as you would set awk's OFS variable to specify what is printed between fields. (Mnemonic: what is printed when there is a "," in your print statement.) +output_record_separator HANDLE EXPR +$OUTPUT_RECORD_SEPARATOR +$ORS +$\ +The output record separator for the print operator. Ordinarily the print operator simply prints out its arguments as is, with no trailing newline or other end-of-record string added. To get behavior more like awk, set this variable as you would set awk's ORS variable to specify what is printed at the end of the print. (Mnemonic: you set $\ instead of adding "\n" at the end of the print. Also, it's just like $/, but it's what you get "back" from Perl.) +$LIST_SEPARATOR +$" +This is like $, except that it applies to array and slice values interpolated into a double-quoted string (or similar interpreted string). Default is a space. (Mnemonic: obvious, I think.) +$SUBSCRIPT_SEPARATOR +$SUBSEP +$; +The subscript separator for multidimensional array emulation. If you refer to a hash element as + $foo{$a,$b,$c} +it really means + $foo{join($;, $a, $b, $c)} +But don't put + @foo{$a,$b,$c} # a slice--note the @ +which means + ($foo{$a},$foo{$b},$foo{$c}) +Default is "\034", the same as SUBSEP in awk. If your keys contain binary data there might not be any safe value for $;. (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. Yeah, I know, it's pretty lame, but $, is already taken for something more important.) +Consider using "real" multidimensional arrays as described in perllol. +$OFMT +$# +The output format for printed numbers. This variable is a half-hearted attempt to emulate awk's OFMT variable. There are times, however, when awk and Perl have differing notions of what counts as numeric. The initial value is "%.ng", where n is the value of the macro DBL_DIG from your system's float.h. This is different from awk's default OFMT setting of "%.6g", so you need to set $# explicitly to get awk's value. (Mnemonic: # is the number sign.) +Use of $# is deprecated. +format_page_number HANDLE EXPR +$FORMAT_PAGE_NUMBER +$% +The current page number of the currently selected output channel. Used with formats. (Mnemonic: % is page number in nroff.) +format_lines_per_page HANDLE EXPR +$FORMAT_LINES_PER_PAGE +$= +The current page length (printable lines) of the currently selected output channel. Default is 60. Used with formats. (Mnemonic: = has horizontal lines.) +format_lines_left HANDLE EXPR +$FORMAT_LINES_LEFT +$- +The number of lines left on the page of the currently selected output channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.) +@LAST_MATCH_START +@- +$-[0] is the offset of the start of the last successful match. $-[n] is the offset of the start of the substring matched by n-th subpattern, or undef if the subpattern did not match. +Thus after a match against $_, $& coincides with substr $_, $-[0], $+[0] - $-[0]. Similarly, $n coincides with substr $_, $-[n], $+[n] - $-[n] if $-[n] is defined, and $+ coincides with substr $_, $-[$#-], $+[$#-]. One can use $#- to find the last matched subgroup in the last successful match. Contrast with $#+, the number of subgroups in the regular expression. Compare with @+. +This array holds the offsets of the beginnings of the last successful submatches in the currently active dynamic scope. $-[0] is the offset into the string of the beginning of the entire match. The nth element of this array holds the offset of the nth submatch, so $+[1] is the offset where $1 begins, $+[2] the offset where $2 begins, and so on. You can use $#- to determine how many subgroups were in the last successful match. Compare with the @+ variable. +After a match against some variable $var: +$` is the same as substr($var, 0, $-[0]) +$& is the same as substr($var, $-[0], $+[0] - $-[0]) +$' is the same as substr($var, $+[0]) +$1 is the same as substr($var, $-[1], $+[1] - $-[1]) +$2 is the same as substr($var, $-[2], $+[2] - $-[2]) +$3 is the same as substr $var, $-[3], $+[3] - $-[3]) +format_name HANDLE EXPR +$FORMAT_NAME +$~ +The name of the current report format for the currently selected output channel. Default is the name of the filehandle. (Mnemonic: brother to $^.) +format_top_name HANDLE EXPR +$FORMAT_TOP_NAME +$^ +The name of the current top-of-page format for the currently selected output channel. Default is the name of the filehandle with _TOP appended. (Mnemonic: points to top of page.) +format_line_break_characters HANDLE EXPR +$FORMAT_LINE_BREAK_CHARACTERS +$: +The current set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format. Default is " \n-", to break on whitespace or hyphens. (Mnemonic: a "colon" in poetry is a part of a line.) +format_formfeed HANDLE EXPR +$FORMAT_FORMFEED +$^L +What formats output as a form feed. Default is \f. +$ACCUMULATOR +$^A +The current value of the write() accumulator for format() lines. A format contains formline() calls that put their result into $^A. After calling its format, write() prints out the contents of $^A and empties. So you never really see the contents of $^A unless you call formline() yourself and then look at it. See perlform and "formline()" in perlfunc. +$CHILD_ERROR +$? +The status returned by the last pipe close, backtick (``) command, successful call to wait() or waitpid(), or from the system() operator. This is just the 16-bit status word returned by the wait() system call (or else is made up to look like it). Thus, the exit value of the subprocess is really ($? >> 8), and $? & 127 gives which signal, if any, the process died from, and $? & 128 reports whether there was a core dump. (Mnemonic: similar to sh and ksh.) +Additionally, if the h_errno variable is supported in C, its value is returned via $? if any gethost*() function fails. +If you have installed a signal handler for SIGCHLD, the value of $? will usually be wrong outside that handler. +Inside an END subroutine $? contains the value that is going to be given to exit(). You can modify $? in an END subroutine to change the exit status of your program. For example: + END { + $? = 1 if $? == 255; # die would make it 255 + } +Under VMS, the pragma use vmsish 'status' makes $? reflect the actual VMS exit status, instead of the default emulation of POSIX status. +Also see "Error Indicators". +$OS_ERROR +$ERRNO +$! +If used numerically, yields the current value of the C errno variable, with all the usual caveats. (This means that you shouldn't depend on the value of $! to be anything in particular unless you've gotten a specific error return indicating a system error.) If used an a string, yields the corresponding system error string. You can assign a number to $! to set errno if, for instance, you want "$!" to return the string for error n, or you want to set the exit value for the die() operator. (Mnemonic: What just went bang?) +Also see "Error Indicators". +$EXTENDED_OS_ERROR +$^E +Error information specific to the current operating system. At the moment, this differs from $! under only VMS, OS/2, and Win32 (and for MacPerl). On all other platforms, $^E is always just the same as $!. +Under VMS, $^E provides the VMS status value from the last system error. This is more specific information about the last system error than that provided by $!. This is particularly important when $! is set to EVMSERR. +Under OS/2, $^E is set to the error code of the last call to OS/2 API either via CRT, or directly from perl. +Under Win32, $^E always returns the last error information reported by the Win32 call GetLastError() which describes the last error from within the Win32 API. Most Win32-specific code will report errors via $^E. ANSI C and Unix-like calls set errno and so most portable Perl code will report errors via $!. +Caveats mentioned in the description of $! generally apply to $^E, also. (Mnemonic: Extra error explanation.) +Also see "Error Indicators". +$EVAL_ERROR +$@ +The Perl syntax error message from the last eval() operator. If null, the last eval() parsed and executed correctly (although the operations you invoked may have failed in the normal fashion). (Mnemonic: Where was the syntax error "at"?) +Warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting $SIG{__WARN__} as described below. +Also see "Error Indicators". +$PROCESS_ID +$PID +$$ +The process number of the Perl running this script. You should consider this variable read-only, although it will be altered across fork() calls. (Mnemonic: same as shells.) +$REAL_USER_ID +$UID +$< +The real uid of this process. (Mnemonic: it's the uid you came from, if you're running setuid.) +$EFFECTIVE_USER_ID +$EUID +$> +The effective uid of this process. Example: + $< = $>; # set real to effective uid + ($<,$>) = ($>,$<); # swap real and effective uid +(Mnemonic: it's the uid you went to, if you're running setuid.) $< and $> can be swapped only on machines supporting setreuid(). +$REAL_GROUP_ID +$GID +$( +The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getgid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. +However, a value assigned to $( must be a single number used to set the real gid. So the value given by $( should not be assigned back to $( without being forced numeric, such as by adding zero. +(Mnemonic: parentheses are used to group things. The real gid is the group you left, if you're running setgid.) +$EFFECTIVE_GROUP_ID +$EGID +$) +The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getegid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. +Similarly, a value assigned to $) must also be a space-separated list of numbers. The first number sets the effective gid, and the rest (if any) are passed to setgroups(). To get the effect of an empty list for setgroups(), just repeat the new effective gid; that is, to force an effective gid of 5 and an effectively empty setgroups() list, say $) = "5 5" . +(Mnemonic: parentheses are used to group things. The effective gid is the group that's right for you, if you're running setgid.) +$<, $>, $( and $) can be set only on machines that support the corresponding set[re][ug]id() routine. $( and $) can be swapped only on machines supporting setregid(). +$PROGRAM_NAME +$0 +Contains the name of the program being executed. On some operating systems assigning to $0 modifies the argument area that the ps program sees. This is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as sh and ksh.) +Note for BSD users: setting $0 does not completely remove "perl" from the ps(1) output. For example, setting $0 to "foobar" will result in "perl: foobar (perl)". This is an operating system feature. +$[ +The index of the first element in an array, and of the first character in a substring. Default is 0, but you could theoretically set it to 1 to make Perl behave more like awk (or Fortran) when subscripting and when evaluating the index() and substr() functions. (Mnemonic: [ begins subscripts.) +As of release 5 of Perl, assignment to $[ is treated as a compiler directive, and cannot influence the behavior of any other file. Its use is highly discouraged. +$] +The version + patchlevel / 1000 of the Perl interpreter. This variable can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: Is this version of perl in the right bracket?) Example: + warn "No checksumming!\n" if $] < 3.019; +See also the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old. +The use of this variable is deprecated. The floating point representation can sometimes lead to inaccurate numeric comparisons. See $^V for a more modern representation of the Perl version that allows accurate string comparisons. +$COMPILING +$^C +The current value of the flag associated with the -c switch. Mainly of use with -MO=... to allow code to alter its behavior when being compiled, such as for example to AUTOLOAD at compile time rather than normal, deferred loading. See perlcc. Setting $^C = 1 is similar to calling B::minus_c. +$DEBUGGING +$^D +The current value of the debugging flags. (Mnemonic: value of -D switch.) +$SYSTEM_FD_MAX +$^F +The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails. (Ordinary file descriptors are closed before the open() is attempted.) The close-on-exec status of a file descriptor will be decided according to the value of $^F when the corresponding file, pipe, or socket was opened, not the time of the exec(). +$^H +WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice. +This variable contains compile-time hints for the Perl interpreter. At the end of compilation of a BLOCK the value of this variable is restored to the value when the interpreter started to compile the BLOCK. +When perl begins to parse any block construct that provides a lexical scope (e.g., eval body, required file, subroutine body, loop body, or conditional block), the existing value of $^H is saved, but its value is left unchanged. When the compilation of the block is completed, it regains the saved value. Between the points where its value is saved and restored, code that executes within BEGIN blocks is free to change the value of $^H. +This behavior provides the semantic of lexical scoping, and is used in, for instance, the use strict pragma. +The contents should be an integer; different bits of it are used for different pragmatic flags. Here's an example: + sub add_100 { $^H |= 0x100 } + sub foo { + BEGIN { add_100() } + bar->baz($boon); + } +Consider what happens during execution of the BEGIN block. At this point the BEGIN block has already been compiled, but the body of foo() is still being compiled. The new value of $^H will therefore be visible only while the body of foo() is being compiled. +Substitution of the above BEGIN block with: + BEGIN { require strict; strict->import('vars') } +demonstrates how use strict 'vars' is implemented. Here's a conditional version of the same lexical pragma: + BEGIN { require strict; strict->import('vars') if $condition } +%^H +WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice. +The %^H hash provides the same scoping semantic as $^H. This makes it useful for implementation of lexically scoped pragmas. +$INPLACE_EDIT +$^I +The current value of the inplace-edit extension. Use undef to disable inplace editing. (Mnemonic: value of -i switch.) +$^M +By default, running out of memory is an untrappable, fatal error. However, if suitably built, Perl can use the contents of $^M as an emergency memory pool after die()ing. Suppose that your Perl were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then + $^M = 'a' x (1 << 16); +would allocate a 64K buffer for use in an emergency. See the INSTALL file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced feature, there is no English long name for this variable. +$OSNAME +$^O +The name of the operating system under which this copy of Perl was built, as determined during the configuration process. The value is identical to $Config{'osname'}. See also Config and the -V command-line switch documented in perlrun. +$PERLDB +$^P +The internal variable for debugging support. The meanings of the various bits are subject to change, but currently indicate: +0x01 +Debug subroutine enter/exit. +0x02 +Line-by-line debugging. +0x04 +Switch off optimizations. +0x08 +Preserve more data for future interactive inspections. +0x10 +Keep info about source lines on which a subroutine is defined. +0x20 +Start with single-step on. +0x40 +Use subroutine address instead of name when reporting. +0x80 +Report goto &subroutine as well. +0x100 +Provide informative "file" names for evals based on the place they were compiled. +0x200 +Provide informative names to anonymous subroutines based on the place they were compiled. +Some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change. +$LAST_REGEXP_CODE_RESULT +$^R +The result of evaluation of the last successful (?{ code }) regular expression assertion (see perlre). May be written to. +$EXCEPTIONS_BEING_CAUGHT +$^S +Current state of the interpreter. Undefined if parsing of the current module/eval is not finished (may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers). True if inside an eval(), otherwise false. +$BASETIME +$^T +The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the -M, -A, and -C filetests are based on this value. +$PERL_VERSION +$^V +The revision, version, and subversion of the Perl interpreter, represented as a string composed of characters with those ordinals. Thus in Perl v5.6.0 it equals chr(5) . chr(6) . chr(0) and will return true for $^V eq v5.6.0. Note that the characters in this string value can potentially be in Unicode range. +This can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: use ^V for Version Control.) Example: + warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; +See the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old. +See also $] for an older representation of the Perl version. +$WARNING +$^W +The current value of the warning switch, initially true if -w was used, false otherwise, but directly modifiable. (Mnemonic: related to the -w switch.) See also warnings. +${^WARNING_BITS} +The current set of warning checks enabled by the use warnings pragma. See the documentation of warnings for more details. +${^WIDE_SYSTEM_CALLS} +Global flag that enables system calls made by Perl to use wide character APIs native to the system, if available. This is currently only implemented on the Windows platform. +This can also be enabled from the command line using the -C switch. +The initial value is typically 0 for compatibility with Perl versions earlier than 5.6, but may be automatically set to 1 by Perl if the system provides a user-settable default (e.g., $ENV{LC_CTYPE}). +The bytes pragma always overrides the effect of this flag in the current lexical scope. See bytes. +$EXECUTABLE_NAME +$^X +The name that the Perl binary itself was executed as, from C's argv[0]. This may not be a full pathname, nor even necessarily in your path. +$ARGV +contains the name of the current file when reading from <>. +@ARGV +The array @ARGV contains the command-line arguments intended for the script. $#ARGV is generally the number of arguments minus one, because $ARGV[0] is the first argument, not the program's command name itself. See $0 for the command name. +@INC +The array @INC contains the list of places that the do EXPR, require, or use constructs look for their library files. It initially consists of the arguments to any -I command-line switches, followed by the default Perl library, probably /usr/local/lib/perl, followed by ".", to represent the current directory. If you need to modify this at runtime, you should use the use lib pragma to get the machine-dependent library properly loaded also: + use lib '/mypath/libdir/'; + use SomeMod; +@_ +Within a subroutine the array @_ contains the parameters passed to that subroutine. See perlsub. +%INC +The hash %INC contains entries for each filename included via the do, require, or use operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The require operator uses this hash to determine whether a particular file has already been included. +%ENV +$ENV{expr} +The hash %ENV contains your current environment. Setting a value in ENV changes the environment for any child processes you subsequently fork() off. +%SIG +$SIG{expr} +The hash %SIG contains signal handlers for signals. For example: + sub handler { # 1st argument is signal name + my($sig) = @_; + print "Caught a SIG$sig--shutting down\n"; + close(LOG); + exit(0); + } + $SIG{'INT'} = \&handler; + $SIG{'QUIT'} = \&handler; + ... + $SIG{'INT'} = 'DEFAULT'; # restore default action + $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT +Using a value of 'IGNORE' usually has the effect of ignoring the signal, except for the CHLD signal. See perlipc for more about this special case. +Here are some other examples: + $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) + $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber + $SIG{"PIPE"} = *Plumber; # somewhat esoteric + $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? +Be sure not to use a bareword as the name of a signal handler, lest you inadvertently call it. +If your system has the sigaction() function then signal handlers are installed using it. This means you get reliable signal handling. If your system has the SA_RESTART flag it is used when signals handlers are installed. This means that system calls for which restarting is supported continue rather than returning when a signal arrives. If you want your system calls to be interrupted by signal delivery then do something like this: + use POSIX ':signal_h'; + my $alarm = 0; + sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } + or die "Error setting SIGALRM handler: $!\n"; +See POSIX. +Certain internal hooks can be also set using the %SIG hash. The routine indicated by $SIG{__WARN__} is called when a warning message is about to be printed. The warning message is passed as the first argument. The presence of a __WARN__ hook causes the ordinary printing of warnings to STDERR to be suppressed. You can use this to save warnings in a variable, or turn warnings into fatal errors, like this: + local $SIG{__WARN__} = sub { die $_[0] }; + eval $proggie; +The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __DIE__ hook routine returns, the exception processing continues as it would have in the absence of the hook, unless the hook routine itself exits via a goto, a loop exit, or a die(). The __DIE__ handler is explicitly disabled during the call, so that you can die from a __DIE__ handler. Similarly for __WARN__. +Due to an implementation glitch, the $SIG{__DIE__} hook is called even inside an eval(). Do not use this to rewrite a pending exception in $@, or as a bizarre substitute for overriding CORE::GLOBAL::die(). This strange action at a distance may be fixed in a future release so that $SIG{__DIE__} is only called if your program is about to exit, as was the original intent. Any other use is deprecated. +__DIE__/__WARN__ handlers are very special in one respect: they may be called to report (probable) errors found by the parser. In such a case the parser may be in inconsistent state, so any attempt to evaluate Perl code from such a handler will probably result in a segfault. This means that warnings or errors that result from parsing Perl should be used with extreme caution, like this: + require Carp if defined $^S; + Carp::confess("Something wrong") if defined &Carp::confess; + die "Something wrong, but could not load Carp to give backtrace... + To see backtrace try starting Perl with -MCarp switch"; +Here the first line will load Carp unless it is the parser who called the handler. The second line will print backtrace and die if Carp was available. The third line will be executed only if Carp was not available. +See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and warnings for additional information. +Error Indicators +The variables $@, $!, $^E, and $? contain information about different types of error conditions that may appear during execution of a Perl program. The variables are shown ordered by the "distance" between the subsystem which reported the error and the Perl process. They correspond to errors detected by the Perl interpreter, C library, operating system, or an external program, respectively. +To illustrate the differences between these variables, consider the following Perl expression, which uses a single-quoted string: + eval q{ + open PIPE, "/cdrom/install |"; + @res = ; + close PIPE or die "bad pipe: $?, $!"; + }; +After execution of this statement all 4 variables may have been set. +$@ is set if the string to be eval-ed did not compile (this may happen if open or close were imported with bad prototypes), or if Perl code executed during evaluation die()d . In these cases the value of $@ is the compile error, or the argument to die (which will interpolate $! and $?!). (See also Fatal, though.) +When the eval() expression above is executed, open(), , and close are translated to calls in the C run-time library and thence to the operating system kernel. $! is set to the C library's errno if one of these calls fails. +Under a few operating systems, $^E may contain a more verbose error indicator, such as in this case, "CDROM tray not closed." Systems that do not support extended error messages leave $^E the same as $!. +Finally, $? may be set to non-0 value if the external program /cdrom/install fails. The upper eight bits reflect specific error conditions encountered by the program (the program's exit() value). The lower eight bits reflect mode of failure, like signal death and core dump information See wait(2) for details. In contrast to $! and $^E, which are set only if error condition is detected, the variable $? is set on each wait or pipe close, overwriting the old value. This is more like $@, which on every eval() is always set on failure and cleared on success. +For more details, see the individual descriptions at $@, $!, $^E, and $?. +Technical Note on the Syntax of Variable Names +Variable names in Perl can have several formats. Usually, they must begin with a letter or underscore, in which case they can be arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence :: or '. In this case, the part before the last :: or ' is taken to be a package qualifier; see perlmod. +Perl variable names may also be a sequence of digits or a single punctuation or control character. These names are all reserved for special uses by Perl; for example, the all-digits names are used to hold data captured by backreferences after a regular expression match. Perl has a special syntax for the single-control-character names: It understands ^X (caret X) to mean the control-X character. For example, the notation $^W (dollar-sign caret W) is the scalar variable whose name is the single character control-W. This is better than typing a literal control-W into your program. +Finally, new in Perl 5.6, Perl variable names may be alphanumeric strings that begin with control characters (or better yet, a caret). These variables must be written in the form ${^Foo}; the braces are not optional. ${^Foo} denotes the scalar variable whose name is a control-F followed by two o's. These variables are reserved for future special uses by Perl, except for the ones that begin with ^_ (control-underscore or caret-underscore). No control-character name that begins with ^_ will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. $^_ itself, however, is reserved. +Perl identifiers that begin with digits, control characters, or punctuation characters are exempt from the effects of the package declaration and are always forced to be in package main. A few other names are also exempt: + ENV STDIN + INC STDOUT + ARGV STDERR + ARGVOUT + SIG +In particular, the new special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope. +BUGS +Due to an unfortunate accident of Perl's implementation, use English imposes a considerable performance penalty on all regular expression matches in a program, regardless of whether they occur in the scope of use English. For that reason, saying use English in libraries is strongly discouraged. See the Devel::SawAmpersand module documentation from CPAN (http://www.perl.com/CPAN/modules/by-module/Devel/) for more information. +Having to even think about the $^S variable in your exception handlers is simply wrong. $SIG{__DIE__} as currently implemented invites grievous and difficult to track down errors. Avoid it and use an END{} or CORE::GLOBAL::die override instead. diff --git a/lib/Pod/Simple/t/render.t b/lib/Pod/Simple/t/render.t index cea0816b9d..81ba12eab6 100644 --- a/lib/Pod/Simple/t/render.t +++ b/lib/Pod/Simple/t/render.t @@ -35,11 +35,11 @@ sub source_path { my $outfile = '10000'; foreach my $file ( - "test_junk1.pod", - "test_junk2.pod", - "test_old_perlcygwin.pod", - "test_old_perlfaq3.pod", - "test_old_perlvar.pod", + "junk1.pod", + "junk2.pod", + "perlcyg.pod", + "perlfaq3.pod", + "perlvar.pod", ) { unless(-e source_path($file)) { diff --git a/lib/Pod/Simple/t/test_junk1.pod b/lib/Pod/Simple/t/test_junk1.pod deleted file mode 100644 index 402880109e..0000000000 --- a/lib/Pod/Simple/t/test_junk1.pod +++ /dev/null @@ -1,8 +0,0 @@ - -=cut - -=head9 I like pie - -B diff --git a/lib/Pod/Simple/t/test_junk1_out.txt b/lib/Pod/Simple/t/test_junk1_out.txt deleted file mode 100644 index 1b4559ac0f..0000000000 --- a/lib/Pod/Simple/t/test_junk1_out.txt +++ /dev/null @@ -1,13 +0,0 @@ -pie is nice E - -POD ERRORS -Hey! The above document had some coding errors, which are explained below: - -Around line 2: - =cut found outside a pod block. Skipping to next block. -Around line 4: - Unknown directive: =head9 -Around line 6: - Unterminated B<...> sequence -Around line 8: - Unknown E content in E diff --git a/lib/Pod/Simple/t/test_junk2.pod b/lib/Pod/Simple/t/test_junk2.pod deleted file mode 100644 index 696aabfbfa..0000000000 --- a/lib/Pod/Simple/t/test_junk2.pod +++ /dev/null @@ -1,6 +0,0 @@ - -=head9 I like pie - -B diff --git a/lib/Pod/Simple/t/test_junk2_out.txt b/lib/Pod/Simple/t/test_junk2_out.txt deleted file mode 100644 index 5612c7d3a1..0000000000 --- a/lib/Pod/Simple/t/test_junk2_out.txt +++ /dev/null @@ -1,13 +0,0 @@ -pie is nice - -E - -POD ERRORS -Hey! The above document had some coding errors, which are explained below: -Around line 2: - Unknown directive: =head9 -Around line 4: - Unterminated B<...> sequence -Around line 6: - Unknown E content in E - diff --git a/lib/Pod/Simple/t/test_old_perlcygwin.pod b/lib/Pod/Simple/t/test_old_perlcygwin.pod deleted file mode 100644 index 6264a15788..0000000000 --- a/lib/Pod/Simple/t/test_old_perlcygwin.pod +++ /dev/null @@ -1,592 +0,0 @@ -If you read this file _as_is_, just ignore the funny characters you -see. It is written in the POD format (see pod/perlpod.pod) which is -specially designed to be readable as is. - -=head1 NAME - -README.cygwin - Perl for Cygwin - -=head1 SYNOPSIS - -This document will help you configure, make, test and install Perl -on Cygwin. This document also describes features of Cygwin that will -affect how Perl behaves at runtime. - -B There are pre-built Perl packages available for Cygwin and a -version of Perl is provided on the Cygwin CD. If you do not need to -customize the configuration, consider using one of these packages: - - http://cygutils.netpedia.net/ - -=head1 PREREQUISITES - -=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) - -The Cygwin tools are ports of the popular GNU development tools for Win32 -platforms. They run thanks to the Cygwin library which provides the UNIX -system calls and environment these programs expect. More information -about this project can be found at: - - http://www.cygwin.com/ - -A recent net or commercial release of Cygwin is required. - -At the time this document was last updated, Cygwin 1.1.5 was current. - -B At this point, minimal effort has been made to provide -compatibility with old (beta) Cygwin releases. The focus has been to -provide a high quality release and not worry about working around old -bugs. If you wish to use Perl with Cygwin B20.1 or earlier, consider -using perl5.005_03, which is available in source and binary form at -C. If there is significant demand, -a patch kit can be developed to port back to earlier Cygwin versions. - -=head2 Cygwin Configuration - -While building Perl some changes may be necessary to your Cygwin setup so -that Perl builds cleanly. These changes are B required for normal -Perl usage. - -B The binaries that are built will run on all Win32 versions. -They do not depend on your host system (Win9x/WinME, WinNT/Win2K) -or your Cygwin configuration (I, I, binary/text mounts). -The only dependencies come from hard-coded pathnames like C. -However, your host system and Cygwin configuration will affect Perl's -runtime behavior (see L). - -=over 4 - -=item * C - -Set the C environment variable so that Configure finds the Cygwin -versions of programs. Any Windows directories should be removed or -moved to the end of your C. - -=item * I - -If you do not have I (which is part of the I package), -Configure will B prompt you to install I pages. - -=item * Permissions - -On WinNT with either the I or I C settings, directory -and file permissions may not be set correctly. Since the build process -creates directories and files, to be safe you may want to run a `C' on the entire Perl source tree. - -Also, it is a well known WinNT "feature" that files created by a login -that is a member of the I group will be owned by the -I group. Depending on your umask, you may find that you -can not write to files that you just created (because you are no longer -the owner). When using the I C setting, this is not an -issue because it "corrects" the ownership to what you would expect on -a UNIX system. - -=back - -=head1 CONFIGURE - -The default options gathered by Configure with the assistance of -F will build a Perl that supports dynamic loading -(which requires a shared F). - -This will run Configure and keep a record: - - ./Configure 2>&1 | tee log.configure - -If you are willing to accept all the defaults run Configure with B<-de>. -However, several useful customizations are available. - -=head2 Strip Binaries - -It is possible to strip the EXEs and DLLs created by the build process. -The resulting binaries will be significantly smaller. If you want the -binaries to be stripped, you can either add a B<-s> option when Configure -prompts you, - - Any additional ld flags (NOT including libraries)? [none] -s - Any special flags to pass to gcc to use dynamic linking? [none] -s - Any special flags to pass to ld2 to create a dynamically loaded library? - [none] -s - -or you can edit F and uncomment the relevant variables -near the end of the file. - -=head2 Optional Libraries - -Several Perl functions and modules depend on the existence of -some optional libraries. Configure will find them if they are -installed in one of the directories listed as being used for library -searches. Pre-built packages for most of these are available at -C. - -=over 4 - -=item * C<-lcrypt> - -The crypt package distributed with Cygwin is a Linux compatible 56-bit -DES crypt port by Corinna Vinschen. - -Alternatively, the crypt libraries in GNU libc have been ported to Cygwin. - -The DES based Ultra Fast Crypt port was done by Alexey Truhan: - - ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz - -NOTE: There are various export restrictions on DES implementations, -see the glibc README for more details. - -The MD5 port was done by Andy Piper: - - ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz - -=item * C<-lgdbm> (C) - -GDBM is available for Cygwin. GDBM's ndbm/dbm compatibility feature -also makes C and C possible (although they add -little extra value). - -NOTE: The ndbm/dbm emulations only completely work on NTFS partitions. - -=item * C<-ldb> (C) - -BerkeleyDB is available for Cygwin. Some details can be found in -F. - -NOTE: The BerkeleyDB library only completely works on NTFS partitions. - -=item * C<-lcygipc> (C) - -A port of SysV IPC is available for Cygwin. - -NOTE: This has B been extensively tested. In particular, -C is undefined because it fails a Configure test -and on Win9x the I functions seem to hang. It also creates -a compile time dependency because F includes F<> -and F<> (which will be required in the future when compiling -CPAN modules). - -=back - -=head2 Configure-time Options - -The F document describes several Configure-time options. Some of -these will work with Cygwin, others are not yet possible. Also, some of -these are experimental. You can either select an option when Configure -prompts you or you can define (undefine) symbols on the command line. - -=over 4 - -=item * C<-Uusedl> - -Undefining this symbol forces Perl to be compiled statically. - -=item * C<-Uusemymalloc> - -By default Perl uses the malloc() included with the Perl source. If you -want to force Perl to build with the system malloc() undefine this symbol. - -=item * C<-Dusemultiplicity> - -Multiplicity is required when embedding Perl in a C program and using -more than one interpreter instance. This works with the Cygwin port. - -=item * C<-Duseperlio> - -The PerlIO abstraction works with the Cygwin port. - -=item * C<-Duse64bitint> - -I supports 64-bit integers. However, several additional long long -functions are necessary to use them within Perl (I<{strtol,strtoul}l>). -These are B yet available with Cygwin. - -=item * C<-Duselongdouble> - -I supports long doubles (12 bytes). However, several additional -long double math functions are necessary to use them within Perl -(I<{atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold>). -These are B yet available with Cygwin. - -=item * C<-Dusethreads> - -POSIX threads are B yet implemented in Cygwin. - -=item * C<-Duselargefiles> - -Although Win32 supports large files, Cygwin currently uses 32-bit integers -for internal size and position calculations. - -=back - -=head2 Suspicious Warnings - -You may see some messages during Configure that seem suspicious. - -=over 4 - -=item * I - -I is needed to build dynamic libraries, but it does not exist -when dlsym() checking occurs (it is not created until `C' runs). -You will see the following message: - - Checking whether your dlsym() needs a leading underscore ... - ld2: not found - I can't compile and run the test program. - I'm guessing that dlsym doesn't need a leading underscore. - -Since the guess is correct, this is not a problem. - -=item * Win9x and C - -Win9x does not correctly report C with a non-blocking read on a -closed pipe. You will see the following messages: - - But it also returns -1 to signal EOF, so be careful! - WARNING: you can't distinguish between EOF and no data! - - *** WHOA THERE!!! *** - The recommended value for $d_eofnblk on this machine was "define"! - Keep the recommended value? [y] - -At least for consistency with WinNT, you should keep the recommended -value. - -=item * Compiler/Preprocessor defines - -The following error occurs because of the Cygwin C<#define> of -C<_LONG_DOUBLE>: - - Guessing which symbols your C compiler and preprocessor define... - try.c:: parse error - -This failure does not seem to cause any problems. - -=back - -=head1 MAKE - -Simply run I and wait: - - make 2>&1 | tee log.make - -=head2 Warnings - -Warnings like these are normal: - - warning: overriding commands for target - warning: ignoring old commands for target - - dllwrap: no export definition file provided - dllwrap: creating one, but that may not be what you want - -=head2 ld2 - -During `C', I will be created and installed in your $installbin -directory (where you said to put public executables). It does not -wait until the `C' process to install the I script, -this is because the remainder of the `C' refers to I without -fully specifying its path and does this from multiple subdirectories. -The assumption is that $installbin is in your current C. If this -is not the case `C' will fail at some point. If this happens, -just manually copy I from the source directory to somewhere in -your C. - -=head1 TEST - -There are two steps to running the test suite: - - make test 2>&1 | tee log.make-test - - cd t;./perl harness 2>&1 | tee ../log.harness - -The same tests are run both times, but more information is provided when -running as `C<./perl harness>'. - -Test results vary depending on your host system and your Cygwin -configuration. If a test can pass in some Cygwin setup, it is always -attempted and explainable test failures are documented. It is possible -for Perl to pass all the tests, but it is more likely that some tests -will fail for one of the reasons listed below. - -=head2 File Permissions - -UNIX file permissions are based on sets of mode bits for -{read,write,execute} for each {user,group,other}. By default Cygwin -only tracks the Win32 read-only attribute represented as the UNIX file -user write bit (files are always readable, files are executable if they -have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are -always readable and executable). On WinNT with the I C -setting, the additional mode bits are stored as extended file attributes. -On WinNT with the I C setting, permissions use the standard -WinNT security descriptors and access control lists. Without one of -these options, these tests will fail: - - Failed Test List of failed - ------------------------------------ - io/fs.t 5, 7, 9-10 - lib/anydbm.t 2 - lib/db-btree.t 20 - lib/db-hash.t 16 - lib/db-recno.t 18 - lib/gdbm.t 2 - lib/ndbm.t 2 - lib/odbm.t 2 - lib/sdbm.t 2 - op/stat.t 9, 20 (.tmp not an executable extension) - -=head2 Hard Links - -FAT partitions do not support hard links (whereas NTFS does), in which -case Cygwin implements link() by copying the file. On remote (network) -drives Cygwin's stat() always sets C to 1, so the link count -for remote directories and files is not available. In either case, -these tests will fail: - - Failed Test List of failed - ------------------------------------ - io/fs.t 4 - op/stat.t 3 - -=head2 Filetime Granularity - -On FAT partitions the filetime granularity is 2 seconds. The following -test will fail: - - Failed Test List of failed - ------------------------------------ - io/fs.t 18 - -=head2 Tainting Checks - -When Perl is running in taint mode, C<$ENV{PATH}> is considered tainted -and not used, so DLLs not in the default system directories will not -be found. While the tests are running you will see warnings popup from -the system with messages like: - - Win9x - Error Starting Program - A required .DLL file, CYGWIN1.DLL, was not found - - WinNT - perl.exe - Unable to Locate DLL - The dynamic link library cygwin1.dll could not be found in the - specified path ... - -Just click OK and ignore them. When running `C', 2 popups -occur. During `C<./perl harness>', 4 popups occur. Also, these tests -will fail: - - Failed Test List of failed - ------------------------------------ - op/taint.t 1, 3, 31, 37 - -Alternatively, you can copy F into the directory where the -tests run: - - cp /bin/cygwin1.dll t - -or one of the Windows system directories (although, this is B -recommended). - -=head2 /etc/group - -Cygwin does not require F, in which case the F -test will be skipped. The check performed by F expects to -see entries that use the members field, otherwise this test will fail: - - Failed Test List of failed - ------------------------------------ - op/grent.t 1 - -=head2 Script Portability - -Cygwin does an outstanding job of providing UNIX-like semantics on top of -Win32 systems. However, in addition to the items noted above, there are -some differences that you should know about. This is a very brief guide -to portability, more information can be found in the Cygwin documentation. - -=over 4 - -=item * Pathnames - -Cygwin pathnames can be separated by forward (F) or backward (F<\>) -slashes. They may also begin with drive letters (F) or Universal -Naming Codes (F). DOS device names (F, F, F, -F, F, F) are invalid as base filenames. However, they -can be used in extensions (e.g., F). Names may contain all -printable characters except these: - - : * ? " < > | - -File names are case insensitive, but case preserving. A pathname that -contains a backslash or drive letter is a Win32 pathname (and not subject -to the translations applied to POSIX style pathnames). - -=item * Text/Binary - -When a file is opened it is in either text or binary mode. In text mode -a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default -mode for an open() is determined by the mode of the mount that underlies -the file. Perl provides a binmode() function to set binary mode on files -that otherwise would be treated as text. sysopen() with the C -flag sets text mode on files that otherwise would be treated as binary: - - sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) - -lseek(), tell() and sysseek() only work with files opened in binary mode. - -The text/binary issue is covered at length in the Cygwin documentation. - -=item * F<.exe> - -The Cygwin stat(), lstat() and readlink() functions make the F<.exe> -extension transparent by looking for F when you ask for F -(unless a F also exists). Cygwin does not require a F<.exe> -extension, but I adds it automatically when building a program. -However, when accessing an executable as a normal file (e.g., I -in a makefile) the F<.exe> is not transparent. The I included -with Cygwin automatically appends a F<.exe> when necessary. - -=item * chown() - -On WinNT chown() can change a file's user and group IDs. On Win9x chown() -is a no-op, although this is appropriate since there is no security model. - -=item * Miscellaneous - -File locking using the C command to fcntl() is a stub that -returns C. - -Win9x can not rename() an open file (although WinNT can). - -The Cygwin chroot() implementation has holes (it can not restrict file -access by native Win32 programs). - -=back - -=head1 INSTALL - -This will install Perl, including I pages. - - make install | tee log.make-install - -NOTE: If C is redirected `C' will B prompt -you to install I into F. - -You may need to be I to run `C'. If you -are not, you must have write access to the directories in question. - -Information on installing the Perl documentation in HTML format can be -found in the F document. - -=head1 MANIFEST - -These are the files in the Perl release that contain references to Cygwin. -These very brief notes attempt to explain the reason for all conditional -code. Hopefully, keeping this up to date will allow the Cygwin port to -be kept as clean as possible. - -=over 4 - -=item Documentation - - INSTALL README.cygwin README.win32 MANIFEST - Changes Changes5.005 Changes5.004 Changes5.6 - pod/perl.pod pod/perlport.pod pod/perlfaq3.pod - pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod - pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod - -=item Build, Configure, Make, Install - - cygwin/Makefile.SHs - cygwin/ld2.in - cygwin/perlld.in - ext/IPC/SysV/hints/cygwin.pl - ext/NDBM_File/hints/cygwin.pl - ext/ODBM_File/hints/cygwin.pl - hints/cygwin.sh - Configure - help finding hints from uname, - shared libperl required for dynamic loading - Makefile.SH - linklibperl - Porting/patchls - cygwin in port list - installman - man pages with :: translated to . - installperl - install dll/ld2/perlld, install to pods - makedepend.SH - uwinfix - -=item Tests - - t/io/tell.t - binmode - t/lib/b.t - ignore Cwd from os_extras - t/lib/glob-basic.t - Win32 directory list access differs from read mode - t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// - t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk - (cache manager sometimes preserves ctime of file - previously created and deleted), no -u (setuid) - -=item Compiled Perl Source - - EXTERN.h - __declspec(dllimport) - XSUB.h - __declspec(dllexport) - cygwin/cygwin.c - os_extras (getcwd, spawn) - perl.c - os_extras - perl.h - binmode - doio.c - win9x can not rename a file when it is open - pp_sys.c - do not define h_errno, pp_system with spawn - util.c - use setenv - -=item Compiled Module Source - - ext/POSIX/POSIX.xs - tzname defined externally - ext/SDBM_File/sdbm/pair.c - - EXTCONST needs to be redefined from EXTERN.h - ext/SDBM_File/sdbm/sdbm.c - - binary open - -=item Perl Modules/Scripts - - lib/Cwd.pm - hook to internal Cwd::cwd - lib/ExtUtils/MakeMaker.pm - - require MM_Cygwin.pm - lib/ExtUtils/MM_Cygwin.pm - - canonpath, cflags, manifypods, perl_archive - lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 - lib/File/Spec/Unix.pm - preserve //unc - lib/File/Temp.pm - no directory sticky bit - lib/perl5db.pl - use stdin not /dev/tty - utils/perldoc.PL - version comment - -=back - -=head1 BUGS - -When I starts, it warns about overriding commands for F. - -`C' does not remove library F<.def> or F<.exe.stackdump> -files. - -The I script contains references to the source directory. You should -change these to $installbin after `C'. - -Support for swapping real and effective user and group IDs is incomplete. -On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid(). -However, additional Cygwin calls for manipulating WinNT access tokens -and security contexts are required. - -When building DLLs, `C' is used to export -global symbols. It might be better to generate an explicit F<.def> file -(see F). Also, DLLs can now be build with `C'. - -=head1 AUTHORS - -Charles Wilson , -Eric Fifer , -alexander smishlajev , -Steven Morlock , -Sebastien Barre , -Teun Burgers . - -=head1 HISTORY - -Last updated: 9 November 2000 diff --git a/lib/Pod/Simple/t/test_old_perlcygwin_out.txt b/lib/Pod/Simple/t/test_old_perlcygwin_out.txt deleted file mode 100644 index d834344d6f..0000000000 --- a/lib/Pod/Simple/t/test_old_perlcygwin_out.txt +++ /dev/null @@ -1,249 +0,0 @@ -NAME -README.cygwin - Perl for Cygwin -SYNOPSIS -This document will help you configure, make, test and install Perl on Cygwin. This document also describes features of Cygwin that will affect how Perl behaves at runtime. -NOTE: There are pre-built Perl packages available for Cygwin and a version of Perl is provided on the Cygwin CD. If you do not need to customize the configuration, consider using one of these packages: - http://cygutils.netpedia.net/ -PREREQUISITES -Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) -The Cygwin tools are ports of the popular GNU development tools for Win32 platforms. They run thanks to the Cygwin library which provides the UNIX system calls and environment these programs expect. More information about this project can be found at: - http://www.cygwin.com/ -A recent net or commercial release of Cygwin is required. -At the time this document was last updated, Cygwin 1.1.5 was current. -NOTE: At this point, minimal effort has been made to provide compatibility with old (beta) Cygwin releases. The focus has been to provide a high quality release and not worry about working around old bugs. If you wish to use Perl with Cygwin B20.1 or earlier, consider using perl5.005_03, which is available in source and binary form at http://cygutils.netpedia.net/. If there is significant demand, a patch kit can be developed to port back to earlier Cygwin versions. -Cygwin Configuration -While building Perl some changes may be necessary to your Cygwin setup so that Perl builds cleanly. These changes are not required for normal Perl usage. -NOTE: The binaries that are built will run on all Win32 versions. They do not depend on your host system (Win9x/WinME, WinNT/Win2K) or your Cygwin configuration (ntea, ntsec, binary/text mounts). The only dependencies come from hard-coded pathnames like /usr/local. However, your host system and Cygwin configuration will affect Perl's runtime behavior (see "TEST"). -PATH -Set the PATH environment variable so that Configure finds the Cygwin versions of programs. Any Windows directories should be removed or moved to the end of your PATH. -nroff -If you do not have nroff (which is part of the groff package), Configure will not prompt you to install man pages. -Permissions -On WinNT with either the ntea or ntsec CYGWIN settings, directory and file permissions may not be set correctly. Since the build process creates directories and files, to be safe you may want to run a `chmod -R +w *' on the entire Perl source tree. -Also, it is a well known WinNT "feature" that files created by a login that is a member of the Administrators group will be owned by the Administrators group. Depending on your umask, you may find that you can not write to files that you just created (because you are no longer the owner). When using the ntsec CYGWIN setting, this is not an issue because it "corrects" the ownership to what you would expect on a UNIX system. -CONFIGURE -The default options gathered by Configure with the assistance of hints/cygwin.sh will build a Perl that supports dynamic loading (which requires a shared libperl.dll). -This will run Configure and keep a record: - ./Configure 2>&1 | tee log.configure -If you are willing to accept all the defaults run Configure with -de. However, several useful customizations are available. -Strip Binaries -It is possible to strip the EXEs and DLLs created by the build process. The resulting binaries will be significantly smaller. If you want the binaries to be stripped, you can either add a -s option when Configure prompts you, - Any additional ld flags (NOT including libraries)? [none] -s - Any special flags to pass to gcc to use dynamic linking? [none] -s - Any special flags to pass to ld2 to create a dynamically loaded library? - [none] -s -or you can edit hints/cygwin.sh and uncomment the relevant variables near the end of the file. -Optional Libraries -Several Perl functions and modules depend on the existence of some optional libraries. Configure will find them if they are installed in one of the directories listed as being used for library searches. Pre-built packages for most of these are available at http://cygutils.netpedia.net/. --lcrypt -The crypt package distributed with Cygwin is a Linux compatible 56-bit DES crypt port by Corinna Vinschen. -Alternatively, the crypt libraries in GNU libc have been ported to Cygwin. -The DES based Ultra Fast Crypt port was done by Alexey Truhan: - ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz -NOTE: There are various export restrictions on DES implementations, see the glibc README for more details. -The MD5 port was done by Andy Piper: - ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz --lgdbm (use GDBM_File) -GDBM is available for Cygwin. GDBM's ndbm/dbm compatibility feature also makes NDBM_File and ODBM_File possible (although they add little extra value). -NOTE: The ndbm/dbm emulations only completely work on NTFS partitions. --ldb (use DB_File) -BerkeleyDB is available for Cygwin. Some details can be found in ext/DB_File/DB_File.pm. -NOTE: The BerkeleyDB library only completely works on NTFS partitions. --lcygipc (use IPC::SysV) -A port of SysV IPC is available for Cygwin. -NOTE: This has not been extensively tested. In particular, d_semctl_semun is undefined because it fails a Configure test and on Win9x the shm*() functions seem to hang. It also creates a compile time dependency because perl.h includes and (which will be required in the future when compiling CPAN modules). -Configure-time Options -The INSTALL document describes several Configure-time options. Some of these will work with Cygwin, others are not yet possible. Also, some of these are experimental. You can either select an option when Configure prompts you or you can define (undefine) symbols on the command line. --Uusedl -Undefining this symbol forces Perl to be compiled statically. --Uusemymalloc -By default Perl uses the malloc() included with the Perl source. If you want to force Perl to build with the system malloc() undefine this symbol. --Dusemultiplicity -Multiplicity is required when embedding Perl in a C program and using more than one interpreter instance. This works with the Cygwin port. --Duseperlio -The PerlIO abstraction works with the Cygwin port. --Duse64bitint -gcc supports 64-bit integers. However, several additional long long functions are necessary to use them within Perl ({strtol,strtoul}l). These are not yet available with Cygwin. --Duselongdouble -gcc supports long doubles (12 bytes). However, several additional long double math functions are necessary to use them within Perl ({atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold). These are not yet available with Cygwin. --Dusethreads -POSIX threads are not yet implemented in Cygwin. --Duselargefiles -Although Win32 supports large files, Cygwin currently uses 32-bit integers for internal size and position calculations. -Suspicious Warnings -You may see some messages during Configure that seem suspicious. -dlsym() -ld2 is needed to build dynamic libraries, but it does not exist when dlsym() checking occurs (it is not created until `make' runs). You will see the following message: - Checking whether your dlsym() needs a leading underscore ... - ld2: not found - I can't compile and run the test program. - I'm guessing that dlsym doesn't need a leading underscore. -Since the guess is correct, this is not a problem. -Win9x and d_eofnblk -Win9x does not correctly report EOF with a non-blocking read on a closed pipe. You will see the following messages: - But it also returns -1 to signal EOF, so be careful! - WARNING: you can't distinguish between EOF and no data! - *** WHOA THERE!!! *** - The recommended value for $d_eofnblk on this machine was "define"! - Keep the recommended value? [y] -At least for consistency with WinNT, you should keep the recommended value. -Compiler/Preprocessor defines -The following error occurs because of the Cygwin #define of _LONG_DOUBLE: - Guessing which symbols your C compiler and preprocessor define... - try.c:: parse error -This failure does not seem to cause any problems. -MAKE -Simply run make and wait: - make 2>&1 | tee log.make -Warnings -Warnings like these are normal: - warning: overriding commands for target - warning: ignoring old commands for target - dllwrap: no export definition file provided - dllwrap: creating one, but that may not be what you want -ld2 -During `make', ld2 will be created and installed in your $installbin directory (where you said to put public executables). It does not wait until the `make install' process to install the ld2 script, this is because the remainder of the `make' refers to ld2 without fully specifying its path and does this from multiple subdirectories. The assumption is that $installbin is in your current PATH. If this is not the case `make' will fail at some point. If this happens, just manually copy ld2 from the source directory to somewhere in your PATH. -TEST -There are two steps to running the test suite: - make test 2>&1 | tee log.make-test - cd t;./perl harness 2>&1 | tee ../log.harness -The same tests are run both times, but more information is provided when running as `./perl harness'. -Test results vary depending on your host system and your Cygwin configuration. If a test can pass in some Cygwin setup, it is always attempted and explainable test failures are documented. It is possible for Perl to pass all the tests, but it is more likely that some tests will fail for one of the reasons listed below. -File Permissions -UNIX file permissions are based on sets of mode bits for {read,write,execute} for each {user,group,other}. By default Cygwin only tracks the Win32 read-only attribute represented as the UNIX file user write bit (files are always readable, files are executable if they have a .{com,bat,exe} extension or begin with #!, directories are always readable and executable). On WinNT with the ntea CYGWIN setting, the additional mode bits are stored as extended file attributes. On WinNT with the ntsec CYGWIN setting, permissions use the standard WinNT security descriptors and access control lists. Without one of these options, these tests will fail: - Failed Test List of failed - ------------------------------------ - io/fs.t 5, 7, 9-10 - lib/anydbm.t 2 - lib/db-btree.t 20 - lib/db-hash.t 16 - lib/db-recno.t 18 - lib/gdbm.t 2 - lib/ndbm.t 2 - lib/odbm.t 2 - lib/sdbm.t 2 - op/stat.t 9, 20 (.tmp not an executable extension) -Hard Links -FAT partitions do not support hard links (whereas NTFS does), in which case Cygwin implements link() by copying the file. On remote (network) drives Cygwin's stat() always sets st_nlink to 1, so the link count for remote directories and files is not available. In either case, these tests will fail: - Failed Test List of failed - ------------------------------------ - io/fs.t 4 - op/stat.t 3 -Filetime Granularity -On FAT partitions the filetime granularity is 2 seconds. The following test will fail: - Failed Test List of failed - ------------------------------------ - io/fs.t 18 -Tainting Checks -When Perl is running in taint mode, $ENV{PATH} is considered tainted and not used, so DLLs not in the default system directories will not be found. While the tests are running you will see warnings popup from the system with messages like: - Win9x - Error Starting Program - A required .DLL file, CYGWIN1.DLL, was not found - WinNT - perl.exe - Unable to Locate DLL - The dynamic link library cygwin1.dll could not be found in the - specified path ... -Just click OK and ignore them. When running `make test', 2 popups occur. During `./perl harness', 4 popups occur. Also, these tests will fail: - Failed Test List of failed - ------------------------------------ - op/taint.t 1, 3, 31, 37 -Alternatively, you can copy cygwin1.dll into the directory where the tests run: - cp /bin/cygwin1.dll t -or one of the Windows system directories (although, this is not recommended). -/etc/group -Cygwin does not require /etc/group, in which case the op/grent.t test will be skipped. The check performed by op/grent.t expects to see entries that use the members field, otherwise this test will fail: - Failed Test List of failed - ------------------------------------ - op/grent.t 1 -Script Portability -Cygwin does an outstanding job of providing UNIX-like semantics on top of Win32 systems. However, in addition to the items noted above, there are some differences that you should know about. This is a very brief guide to portability, more information can be found in the Cygwin documentation. -Pathnames -Cygwin pathnames can be separated by forward (/) or backward (\) slashes. They may also begin with drive letters (C:) or Universal Naming Codes (//UNC). DOS device names (aux, con, prn, com*, lpt?, nul) are invalid as base filenames. However, they can be used in extensions (e.g., hello.aux). Names may contain all printable characters except these: - : * ? " < > | -File names are case insensitive, but case preserving. A pathname that contains a backslash or drive letter is a Win32 pathname (and not subject to the translations applied to POSIX style pathnames). -Text/Binary -When a file is opened it is in either text or binary mode. In text mode a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default mode for an open() is determined by the mode of the mount that underlies the file. Perl provides a binmode() function to set binary mode on files that otherwise would be treated as text. sysopen() with the O_TEXT flag sets text mode on files that otherwise would be treated as binary: - sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) -lseek(), tell() and sysseek() only work with files opened in binary mode. -The text/binary issue is covered at length in the Cygwin documentation. -.exe -The Cygwin stat(), lstat() and readlink() functions make the .exe extension transparent by looking for foo.exe when you ask for foo (unless a foo also exists). Cygwin does not require a .exe extension, but gcc adds it automatically when building a program. However, when accessing an executable as a normal file (e.g., cp in a makefile) the .exe is not transparent. The install included with Cygwin automatically appends a .exe when necessary. -chown() -On WinNT chown() can change a file's user and group IDs. On Win9x chown() is a no-op, although this is appropriate since there is no security model. -Miscellaneous -File locking using the F_GETLK command to fcntl() is a stub that returns ENOSYS. -Win9x can not rename() an open file (although WinNT can). -The Cygwin chroot() implementation has holes (it can not restrict file access by native Win32 programs). -INSTALL -This will install Perl, including man pages. - make install | tee log.make-install -NOTE: If STDERR is redirected `make install' will not prompt you to install perl into /usr/bin. -You may need to be Administrator to run `make install'. If you are not, you must have write access to the directories in question. -Information on installing the Perl documentation in HTML format can be found in the INSTALL document. -MANIFEST -These are the files in the Perl release that contain references to Cygwin. These very brief notes attempt to explain the reason for all conditional code. Hopefully, keeping this up to date will allow the Cygwin port to be kept as clean as possible. -Documentation - INSTALL README.cygwin README.win32 MANIFEST - Changes Changes5.005 Changes5.004 Changes5.6 - pod/perl.pod pod/perlport.pod pod/perlfaq3.pod - pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod - pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod -Build, Configure, Make, Install - cygwin/Makefile.SHs - cygwin/ld2.in - cygwin/perlld.in - ext/IPC/SysV/hints/cygwin.pl - ext/NDBM_File/hints/cygwin.pl - ext/ODBM_File/hints/cygwin.pl - hints/cygwin.sh - Configure - help finding hints from uname, - shared libperl required for dynamic loading - Makefile.SH - linklibperl - Porting/patchls - cygwin in port list - installman - man pages with :: translated to . - installperl - install dll/ld2/perlld, install to pods - makedepend.SH - uwinfix -Tests - t/io/tell.t - binmode - t/lib/b.t - ignore Cwd from os_extras - t/lib/glob-basic.t - Win32 directory list access differs from read mode - t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// - t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk - (cache manager sometimes preserves ctime of file - previously created and deleted), no -u (setuid) -Compiled Perl Source - EXTERN.h - __declspec(dllimport) - XSUB.h - __declspec(dllexport) - cygwin/cygwin.c - os_extras (getcwd, spawn) - perl.c - os_extras - perl.h - binmode - doio.c - win9x can not rename a file when it is open - pp_sys.c - do not define h_errno, pp_system with spawn - util.c - use setenv -Compiled Module Source - ext/POSIX/POSIX.xs - tzname defined externally - ext/SDBM_File/sdbm/pair.c - - EXTCONST needs to be redefined from EXTERN.h - ext/SDBM_File/sdbm/sdbm.c - - binary open -Perl Modules/Scripts - lib/Cwd.pm - hook to internal Cwd::cwd - lib/ExtUtils/MakeMaker.pm - - require MM_Cygwin.pm - lib/ExtUtils/MM_Cygwin.pm - - canonpath, cflags, manifypods, perl_archive - lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 - lib/File/Spec/Unix.pm - preserve //unc - lib/File/Temp.pm - no directory sticky bit - lib/perl5db.pl - use stdin not /dev/tty - utils/perldoc.PL - version comment -BUGS -When make starts, it warns about overriding commands for perlmain.o. -`make clean' does not remove library .def or .exe.stackdump files. -The ld2 script contains references to the source directory. You should change these to $installbin after `make install'. -Support for swapping real and effective user and group IDs is incomplete. On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid(). However, additional Cygwin calls for manipulating WinNT access tokens and security contexts are required. -When building DLLs, `dllwrap --export-all-symbols' is used to export global symbols. It might be better to generate an explicit .def file (see makedef.pl). Also, DLLs can now be build with `gcc -shared'. -AUTHORS -Charles Wilson , Eric Fifer , alexander smishlajev , Steven Morlock , Sebastien Barre , Teun Burgers . -HISTORY -Last updated: 9 November 2000 diff --git a/lib/Pod/Simple/t/test_old_perlfaq3.pod b/lib/Pod/Simple/t/test_old_perlfaq3.pod deleted file mode 100644 index 49cae1a209..0000000000 --- a/lib/Pod/Simple/t/test_old_perlfaq3.pod +++ /dev/null @@ -1,814 +0,0 @@ -=head1 NAME - -perlfaq3 - Programming Tools ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) - -=head1 DESCRIPTION - -This section of the FAQ answers questions related to programmer tools -and programming support. - -=head2 How do I do (anything)? - -Have you looked at CPAN (see L)? The chances are that -someone has already written a module that can solve your problem. -Have you read the appropriate man pages? Here's a brief index: - - Basics perldata, perlvar, perlsyn, perlop, perlsub - Execution perlrun, perldebug - Functions perlfunc - Objects perlref, perlmod, perlobj, perltie - Data Structures perlref, perllol, perldsc - Modules perlmod, perlmodlib, perlsub - Regexes perlre, perlfunc, perlop, perllocale - Moving to perl5 perltrap, perl - Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed - Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html - (not a man-page but still useful) - -A crude table of contents for the Perl man page set is found in L. - -=head2 How can I use Perl interactively? - -The typical approach uses the Perl debugger, described in the -perldebug(1) man page, on an ``empty'' program, like this: - - perl -de 42 - -Now just type in any legal Perl code, and it will be immediately -evaluated. You can also examine the symbol table, get stack -backtraces, check variable values, set breakpoints, and other -operations typically found in symbolic debuggers. - -=head2 Is there a Perl shell? - -In general, no. The Shell.pm module (distributed with Perl) makes -Perl try commands which aren't part of the Perl language as shell -commands. perlsh from the source distribution is simplistic and -uninteresting, but may still be what you want. - -=head2 How do I debug my Perl programs? - -Have you tried C or used C<-w>? They enable warnings -to detect dubious practices. - -Have you tried C? It prevents you from using symbolic -references, makes you predeclare any subroutines that you call as bare -words, and (probably most importantly) forces you to predeclare your -variables with C, C, or C. - -Did you check the return values of each and every system call? The operating -system (and thus Perl) tells you whether they worked, and if not -why. - - open(FH, "> /etc/cantwrite") - or die "Couldn't write to /etc/cantwrite: $!\n"; - -Did you read L? It's full of gotchas for old and new Perl -programmers and even has sections for those of you who are upgrading -from languages like I and I. - -Have you tried the Perl debugger, described in L? You can -step through your program and see what it's doing and thus work out -why what it's doing isn't what it should be doing. - -=head2 How do I profile my Perl programs? - -You should get the Devel::DProf module from the standard distribution -(or separately on CPAN) and also use Benchmark.pm from the standard -distribution. The Benchmark module lets you time specific portions of -your code, while Devel::DProf gives detailed breakdowns of where your -code spends its time. - -Here's a sample use of Benchmark: - - use Benchmark; - - @junk = `cat /etc/motd`; - $count = 10_000; - - timethese($count, { - 'map' => sub { my @a = @junk; - map { s/a/b/ } @a; - return @a - }, - 'for' => sub { my @a = @junk; - local $_; - for (@a) { s/a/b/ }; - return @a }, - }); - -This is what it prints (on one machine--your results will be dependent -on your hardware, operating system, and the load on your machine): - - Benchmark: timing 10000 iterations of for, map... - for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu) - map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) - -Be aware that a good benchmark is very hard to write. It only tests the -data you give it and proves little about the differing complexities -of contrasting algorithms. - -=head2 How do I cross-reference my Perl programs? - -The B::Xref module, shipped with the new, alpha-release Perl compiler -(not the general distribution prior to the 5.005 release), can be used -to generate cross-reference reports for Perl programs. - - perl -MO=Xref[,OPTIONS] scriptname.plx - -=head2 Is there a pretty-printer (formatter) for Perl? - -There is no program that will reformat Perl as much as indent(1) does -for C. The complex feedback between the scanner and the parser (this -feedback is what confuses the vgrind and emacs programs) makes it -challenging at best to write a stand-alone Perl parser. - -Of course, if you simply follow the guidelines in L, you -shouldn't need to reformat. The habit of formatting your code as you -write it will help prevent bugs. Your editor can and should help you -with this. The perl-mode or newer cperl-mode for emacs can provide -remarkable amounts of help with most (but not all) code, and even less -programmable editors can provide significant assistance. Tom swears -by the following settings in vi and its clones: - - set ai sw=4 - map! ^O {^M}^[O^T - -Now put that in your F<.exrc> file (replacing the caret characters -with control characters) and away you go. In insert mode, ^T is -for indenting, ^D is for undenting, and ^O is for blockdenting-- -as it were. If you haven't used the last one, you're missing -a lot. A more complete example, with comments, can be found at -http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz - -If you are used to using the I program for printing out nice code -to a laser printer, you can take a stab at this using -http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the -results are not particularly satisfying for sophisticated code. - -The a2ps at http://www.infres.enst.fr/%7Edemaille/a2ps/ does lots of things -related to generating nicely printed output of documents. - -=head2 Is there a ctags for Perl? - -There's a simple one at -http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do -the trick. And if not, it's easy to hack into what you want. - -=head2 Is there an IDE or Windows Perl Editor? - -Perl programs are just plain text, so any editor will do. - -If you're on Unix, you already have an IDE--Unix itself. The UNIX -philosophy is the philosophy of several small tools that each do one -thing and do it well. It's like a carpenter's toolbox. - -If you want a Windows IDE, check the following: - -=over 4 - -=item CodeMagicCD - -http://www.codemagiccd.com/ - -=item Komodo - -ActiveState's cross-platform, multi-language IDE has Perl support, -including a regular expression debugger and remote debugging -(http://www.ActiveState.com/Products/Komodo/index.html). -(Visual Perl, a Visual Studio.NET plug-in is currently (early 2001) -in beta (http://www.ActiveState.com/Products/VisualPerl/index.html)). - -=item The Object System - -(http://www.castlelink.co.uk/object_system/) is a Perl web -applications development IDE. - -=item PerlBuilder - -(http://www.solutionsoft.com/perl.htm) is an integrated development -environment for Windows that supports Perl development. - -=item Perl code magic - -(http://www.petes-place.com/codemagic.html). - -=item visiPerl+ - -http://helpconsulting.net/visiperl/, from Help Consulting. - -=back - -For editors: if you're on Unix you probably have vi or a vi clone already, -and possibly an emacs too, so you may not need to download anything. -In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the -best available Perl editing mode in any editor. - -For Windows editors: you can download an Emacs - -=over 4 - -=item GNU Emacs - -http://www.gnu.org/software/emacs/windows/ntemacs.html - -=item MicroEMACS - -http://members.nbci.com/uemacs/ - -=item XEmacs - -http://www.xemacs.org/Download/index.html - -=back - -or a vi clone such as - -=over 4 - -=item Elvis - -ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/ - -=item Vile - -http://vile.cx/ - -=item Vim - -http://www.vim.org/ - -win32: http://www.cs.vu.nl/%7Etmgil/vi.html - -=back - -For vi lovers in general, Windows or elsewhere: -http://www.thomer.com/thomer/vi/vi.html. - -nvi (http://www.bostic.com/vi/, available from CPAN in src/misc/) is -yet another vi clone, unfortunately not available for Windows, but in -UNIX platforms you might be interested in trying it out, firstly because -strictly speaking it is not a vi clone, it is the real vi, or the new -incarnation of it, and secondly because you can embed Perl inside it -to use Perl as the scripting language. nvi is not alone in this, -though: at least also vim and vile offer an embedded Perl. - -The following are Win32 multilanguage editor/IDESs that support Perl: - -=over 4 - -=item Codewright - -http://www.starbase.com/ - -=item MultiEdit - -http://www.MultiEdit.com/ - -=item SlickEdit - -http://www.slickedit.com/ - -=back - -There is also a toyedit Text widget based editor written in Perl -that is distributed with the Tk module on CPAN. The ptkdb -(http://world.std.com/~aep/ptkdb/) is a Perl/tk based debugger that -acts as a development environment of sorts. Perl Composer -(http://perlcomposer.sourceforge.net/vperl.html) is an IDE for Perl/Tk -GUI creation. - -In addition to an editor/IDE you might be interested in a more -powerful shell environment for Win32. Your options include - -=over 4 - -=item Bash - -from the Cygwin package (http://sources.redhat.com/cygwin/) - -=item Ksh - -from the MKS Toolkit (http://www.mks.com/), or the Bourne shell of -the U/WIN environment (http://www.research.att.com/sw/tools/uwin/) - -=item Tcsh - -ftp://ftp.astron.com/pub/tcsh/, see also -http://www.primate.wisc.edu/software/csh-tcsh-book/ - -=item Zsh - -ftp://ftp.blarg.net/users/amol/zsh/, see also http://www.zsh.org/ - -=back - -MKS and U/WIN are commercial (U/WIN is free for educational and -research purposes), Cygwin is covered by the GNU Public License (but -that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all -contain (in addition to the shells) a comprehensive set of standard -UNIX toolkit utilities. - -If you're transferring text files between Unix and Windows using FTP -be sure to transfer them in ASCII mode so the ends of lines are -appropriately converted. - -On Mac OS the MacPerl Application comes with a simple 32k text editor -that behaves like a rudimentary IDE. In contrast to the MacPerl Application -the MPW Perl tool can make use of the MPW Shell itself as an editor (with -no 32k limit). - -=over 4 - -=item BBEdit and BBEdit Lite - -are text editors for Mac OS that have a Perl sensitivity mode -(http://web.barebones.com/). - -=item Alpha - -is an editor, written and extensible in Tcl, that nonetheless has -built in support for several popular markup and programming languages -including Perl and HTML (http://alpha.olm.net/). - -=back - -Pepper and Pe are programming language sensitive text editors for Mac -OS X and BeOS respectively (http://www.hekkelman.com/). - -=head2 Where can I get Perl macros for vi? - -For a complete version of Tom Christiansen's vi configuration file, -see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz , -the standard benchmark file for vi emulators. The file runs best with nvi, -the current version of vi out of Berkeley, which incidentally can be built -with an embedded Perl interpreter--see http://www.perl.com/CPAN/src/misc. - -=head2 Where can I get perl-mode for emacs? - -Since Emacs version 19 patchlevel 22 or so, there have been both a -perl-mode.el and support for the Perl debugger built in. These should -come with the standard Emacs 19 distribution. - -In the Perl source directory, you'll find a directory called "emacs", -which contains a cperl-mode that color-codes keywords, provides -context-sensitive help, and other nifty things. - -Note that the perl-mode of emacs will have fits with C<"main'foo"> -(single quote), and mess up the indentation and highlighting. You -are probably using C<"main::foo"> in new Perl code anyway, so this -shouldn't be an issue. - -=head2 How can I use curses with Perl? - -The Curses module from CPAN provides a dynamically loadable object -module interface to a curses library. A small demo can be found at the -directory http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/rep; -this program repeats a command and updates the screen as needed, rendering -B similar to B. - -=head2 How can I use X or Tk with Perl? - -Tk is a completely Perl-based, object-oriented interface to the Tk toolkit -that doesn't force you to use Tcl just to get at Tk. Sx is an interface -to the Athena Widget set. Both are available from CPAN. See the -directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ - -Invaluable for Perl/Tk programming are the Perl/Tk FAQ at -http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference -Guide available at -http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the -online manpages at -http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html . - -=head2 How can I generate simple menus without using CGI or Tk? - -The http://www.perl.com/CPAN/authors/id/SKUNZ/perlmenu.v4.0.tar.gz -module, which is curses-based, can help with this. - -=head2 What is undump? - -See the next question on ``How can I make my Perl program run faster?'' - -=head2 How can I make my Perl program run faster? - -The best way to do this is to come up with a better algorithm. This -can often make a dramatic difference. Jon Bentley's book -``Programming Pearls'' (that's not a misspelling!) has some good tips -on optimization, too. Advice on benchmarking boils down to: benchmark -and profile to make sure you're optimizing the right part, look for -better algorithms instead of microtuning your code, and when all else -fails consider just buying faster hardware. - -A different approach is to autoload seldom-used Perl code. See the -AutoSplit and AutoLoader modules in the standard distribution for -that. Or you could locate the bottleneck and think about writing just -that part in C, the way we used to take bottlenecks in C code and -write them in assembler. Similar to rewriting in C, -modules that have critical sections can be written in C (for instance, the -PDL module from CPAN). - -In some cases, it may be worth it to use the backend compiler to -produce byte code (saving compilation time) or compile into C, which -will certainly save compilation time and sometimes a small amount (but -not much) execution time. See the question about compiling your Perl -programs for more on the compiler--the wins aren't as obvious as you'd -hope. - -If you're currently linking your perl executable to a shared I, -you can often gain a 10-25% performance benefit by rebuilding it to -link with a static libc.a instead. This will make a bigger perl -executable, but your Perl programs (and programmers) may thank you for -it. See the F file in the source distribution for more -information. - -Unsubstantiated reports allege that Perl interpreters that use sfio -outperform those that don't (for I/O intensive applications). To try -this, see the F file in the source distribution, especially -the ``Selecting File I/O mechanisms'' section. - -The undump program was an old attempt to speed up your Perl program -by storing the already-compiled form to disk. This is no longer -a viable option, as it only worked on a few architectures, and -wasn't a good solution anyway. - -=head2 How can I make my Perl program take less memory? - -When it comes to time-space tradeoffs, Perl nearly always prefers to -throw memory at a problem. Scalars in Perl use more memory than -strings in C, arrays take more than that, and hashes use even more. While -there's still a lot to be done, recent releases have been addressing -these issues. For example, as of 5.004, duplicate hash keys are -shared amongst all hashes using them, so require no reallocation. - -In some cases, using substr() or vec() to simulate arrays can be -highly beneficial. For example, an array of a thousand booleans will -take at least 20,000 bytes of space, but it can be turned into one -125-byte bit vector--a considerable memory savings. The standard -Tie::SubstrHash module can also help for certain types of data -structure. If you're working with specialist data structures -(matrices, for instance) modules that implement these in C may use -less memory than equivalent Perl modules. - -Another thing to try is learning whether your Perl was compiled with -the system malloc or with Perl's builtin malloc. Whichever one it -is, try using the other one and see whether this makes a difference. -Information about malloc is in the F file in the source -distribution. You can find out whether you are using perl's malloc by -typing C. - -=head2 Is it unsafe to return a pointer to local data? - -No, Perl's garbage collection system takes care of this. - - sub makeone { - my @a = ( 1 .. 10 ); - return \@a; - } - - for $i ( 1 .. 10 ) { - push @many, makeone(); - } - - print $many[4][5], "\n"; - - print "@many\n"; - -=head2 How can I free an array or hash so my program shrinks? - -You can't. On most operating systems, memory allocated to a program -can never be returned to the system. That's why long-running programs -sometimes re-exec themselves. Some operating systems (notably, -FreeBSD and Linux) allegedly reclaim large chunks of memory that is no -longer used, but it doesn't appear to happen with Perl (yet). The Mac -appears to be the only platform that will reliably (albeit, slowly) -return memory to the OS. - -We've had reports that on Linux (Redhat 5.1) on Intel, C will return memory to the system, while on Solaris 2.6 it -won't. In general, try it yourself and see. - -However, judicious use of my() on your variables will help make sure -that they go out of scope so that Perl can free up that space for -use in other parts of your program. A global variable, of course, never -goes out of scope, so you can't get its space automatically reclaimed, -although undef()ing and/or delete()ing it will achieve the same effect. -In general, memory allocation and de-allocation isn't something you can -or should be worrying about much in Perl, but even this capability -(preallocation of data types) is in the works. - -=head2 How can I make my CGI script more efficient? - -Beyond the normal measures described to make general Perl programs -faster or smaller, a CGI program has additional issues. It may be run -several times per second. Given that each time it runs it will need -to be re-compiled and will often allocate a megabyte or more of system -memory, this can be a killer. Compiling into C B because the process start-up overhead is where the bottleneck is. - -There are two popular ways to avoid this overhead. One solution -involves running the Apache HTTP server (available from -http://www.apache.org/) with either of the mod_perl or mod_fastcgi -plugin modules. - -With mod_perl and the Apache::Registry module (distributed with -mod_perl), httpd will run with an embedded Perl interpreter which -pre-compiles your script and then executes it within the same address -space without forking. The Apache extension also gives Perl access to -the internal server API, so modules written in Perl can do just about -anything a module written in C can. For more on mod_perl, see -http://perl.apache.org/ - -With the FCGI module (from CPAN) and the mod_fastcgi -module (available from http://www.fastcgi.com/) each of your Perl -programs becomes a permanent CGI daemon process. - -Both of these solutions can have far-reaching effects on your system -and on the way you write your CGI programs, so investigate them with -care. - -See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . - -A non-free, commercial product, ``The Velocity Engine for Perl'', -(http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ ) -might also be worth looking at. It will allow you to increase the -performance of your Perl programs, running programs up to 25 times -faster than normal CGI Perl when running in persistent Perl mode or 4 -to 5 times faster without any modification to your existing CGI -programs. Fully functional evaluation copies are available from the -web site. - -=head2 How can I hide the source for my Perl program? - -Delete it. :-) Seriously, there are a number of (mostly -unsatisfactory) solutions with varying levels of ``security''. - -First of all, however, you I take away read permission, because -the source code has to be readable in order to be compiled and -interpreted. (That doesn't mean that a CGI script's source is -readable by people on the web, though--only by people with access to -the filesystem.) So you have to leave the permissions at the socially -friendly 0755 level. - -Some people regard this as a security problem. If your program does -insecure things and relies on people not knowing how to exploit those -insecurities, it is not secure. It is often possible for someone to -determine the insecure things and exploit them without viewing the -source. Security through obscurity, the name for hiding your bugs -instead of fixing them, is little security indeed. - -You can try using encryption via source filters (Filter::* from CPAN), -but any decent programmer will be able to decrypt it. You can try using -the byte code compiler and interpreter described below, but the curious -might still be able to de-compile it. You can try using the native-code -compiler described below, but crackers might be able to disassemble it. -These pose varying degrees of difficulty to people wanting to get at -your code, but none can definitively conceal it (true of every -language, not just Perl). - -If you're concerned about people profiting from your code, then the -bottom line is that nothing but a restrictive license will give you -legal security. License your software and pepper it with threatening -statements like ``This is unpublished proprietary software of XYZ Corp. -Your access to it does not give you permission to use it blah blah -blah.'' We are not lawyers, of course, so you should see a lawyer if -you want to be sure your license's wording will stand up in court. - -=head2 How can I compile my Perl program into byte code or C? - -Malcolm Beattie has written a multifunction backend compiler, -available from CPAN, that can do both these things. It is included -in the perl5.005 release, but is still considered experimental. -This means it's fun to play with if you're a programmer but not -really for people looking for turn-key solutions. - -Merely compiling into C does not in and of itself guarantee that your -code will run very much faster. That's because except for lucky cases -where a lot of native type inferencing is possible, the normal Perl -run-time system is still present and so your program will take just as -long to run and be just as big. Most programs save little more than -compilation time, leaving execution no more than 10-30% faster. A few -rare programs actually benefit significantly (even running several times -faster), but this takes some tweaking of your code. - -You'll probably be astonished to learn that the current version of the -compiler generates a compiled form of your script whose executable is -just as big as the original perl executable, and then some. That's -because as currently written, all programs are prepared for a full -eval() statement. You can tremendously reduce this cost by building a -shared I library and linking against that. See the -F podfile in the Perl source distribution for details. If -you link your main perl binary with this, it will make it minuscule. -For example, on one author's system, F is only 11k in -size! - -In general, the compiler will do nothing to make a Perl program smaller, -faster, more portable, or more secure. In fact, it can make your -situation worse. The executable will be bigger, your VM system may take -longer to load the whole thing, the binary is fragile and hard to fix, -and compilation never stopped software piracy in the form of crackers, -viruses, or bootleggers. The real advantage of the compiler is merely -packaging, and once you see the size of what it makes (well, unless -you use a shared I), you'll probably want a complete -Perl install anyway. - -=head2 How can I compile Perl into Java? - -You can also integrate Java and Perl with the -Perl Resource Kit from O'Reilly and Associates. See -http://www.oreilly.com/catalog/prkunix/ . - -Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in -development, allows Perl code to be called from Java. See jpl/README -in the Perl source tree. - -=head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]? - -For OS/2 just use - - extproc perl -S -your_switches - -as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's -`extproc' handling). For DOS one should first invent a corresponding -batch file and codify it in C (see the -F file in the source distribution for more information). - -The Win95/NT installation, when using the ActiveState port of Perl, -will modify the Registry to associate the C<.pl> extension with the -perl interpreter. If you install another port, perhaps even building -your own Win95/NT Perl from the standard sources by using a Windows port -of gcc (e.g., with cygwin or mingw32), then you'll have to modify -the Registry yourself. In addition to associating C<.pl> with the -interpreter, NT people can use: C to let them -run the program C merely by typing C. - -Macintosh Perl programs will have the appropriate Creator and -Type, so that double-clicking them will invoke the Perl application. - -I: Whatever you do, PLEASE don't get frustrated, and just -throw the perl interpreter into your cgi-bin directory, in order to -get your programs working for a web server. This is an EXTREMELY big -security risk. Take the time to figure out how to do it correctly. - -=head2 Can I write useful Perl programs on the command line? - -Yes. Read L for more information. Some examples follow. -(These assume standard Unix shell quoting rules.) - - # sum first and last fields - perl -lane 'print $F[0] + $F[-1]' * - - # identify text files - perl -le 'for(@ARGV) {print if -f && -T _}' * - - # remove (most) comments from C program - perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c - - # make file a month younger than today, defeating reaper daemons - perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' * - - # find first unused uid - perl -le '$i++ while getpwuid($i); print $i' - - # display reasonable manpath - echo $PATH | perl -nl -072 -e ' - s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}' - -OK, the last one was actually an Obfuscated Perl Contest entry. :-) - -=head2 Why don't Perl one-liners work on my DOS/Mac/VMS system? - -The problem is usually that the command interpreters on those systems -have rather different ideas about quoting than the Unix shells under -which the one-liners were created. On some systems, you may have to -change single-quotes to double ones, which you must I do on Unix -or Plan9 systems. You might also have to change a single % to a %%. - -For example: - - # Unix - perl -e 'print "Hello world\n"' - - # DOS, etc. - perl -e "print \"Hello world\n\"" - - # Mac - print "Hello world\n" - (then Run "Myscript" or Shift-Command-R) - - # VMS - perl -e "print ""Hello world\n""" - -The problem is that none of these examples are reliable: they depend on the -command interpreter. Under Unix, the first two often work. Under DOS, -it's entirely possible that neither works. If 4DOS was the command shell, -you'd probably have better luck like this: - - perl -e "print "Hello world\n"" - -Under the Mac, it depends which environment you are using. The MacPerl -shell, or MPW, is much like Unix shells in its support for several -quoting variants, except that it makes free use of the Mac's non-ASCII -characters as control characters. - -Using qq(), q(), and qx(), instead of "double quotes", 'single -quotes', and `backticks`, may make one-liners easier to write. - -There is no general solution to all of this. It is a mess, pure and -simple. Sucks to be away from Unix, huh? :-) - -[Some of this answer was contributed by Kenneth Albanowski.] - -=head2 Where can I learn about CGI or Web programming in Perl? - -For modules, get the CGI or LWP modules from CPAN. For textbooks, -see the two especially dedicated to web stuff in the question on -books. For problems and questions related to the web, like ``Why -do I get 500 Errors'' or ``Why doesn't it run from the browser right -when it runs fine on the command line'', see these sources: - - WWW Security FAQ - http://www.w3.org/Security/Faq/ - - Web FAQ - http://www.boutell.com/faq/ - - CGI FAQ - http://www.webthing.com/tutorials/cgifaq.html - - HTTP Spec - http://www.w3.org/pub/WWW/Protocols/HTTP/ - - HTML Spec - http://www.w3.org/TR/REC-html40/ - http://www.w3.org/pub/WWW/MarkUp/ - - CGI Spec - http://www.w3.org/CGI/ - - CGI Security FAQ - http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt - -=head2 Where can I learn about object-oriented Perl programming? - -A good place to start is L, and you can use L, -L, and L for reference. Perltoot didn't come out -until the 5.004 release; you can get a copy (in pod, html, or -postscript) from http://www.perl.com/CPAN/doc/FMTEYEWTK/ . - -=head2 Where can I learn about linking C with Perl? [h2xs, xsubpp] - -If you want to call C from Perl, start with L, -moving on to L, L, and L. If you want to -call Perl from C, then read L, L, and -L. Don't forget that you can learn a lot from looking at -how the authors of existing extension modules wrote their code and -solved their problems. - -=head2 I've read perlembed, perlguts, etc., but I can't embed perl in -my C program; what am I doing wrong? - -Download the ExtUtils::Embed kit from CPAN and run `make test'. If -the tests pass, read the pods again and again and again. If they -fail, see L and send a bug report with the output of -C along with C. - -=head2 When I tried to run my script, I got this message. What does it -mean? - -A complete list of Perl's error messages and warnings with explanatory -text can be found in L. You can also use the splain program -(distributed with Perl) to explain the error messages: - - perl program 2>diag.out - splain [-v] [-p] diag.out - -or change your program to explain the messages for you: - - use diagnostics; - -or - - use diagnostics -verbose; - -=head2 What's MakeMaker? - -This module (part of the standard Perl distribution) is designed to -write a Makefile for an extension module from a Makefile.PL. For more -information, see L. - -=head1 AUTHOR AND COPYRIGHT - -Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. -All rights reserved. - -When included as an integrated part of the Standard Distribution -of Perl or of its documentation (printed or otherwise), this works is -covered under Perl's Artistic License. For separate distributions of -all or part of this FAQ outside of that, see L. - -Irrespective of its distribution, all code examples here are in the public -domain. You are permitted and encouraged to use this code and any -derivatives thereof in your own programs for fun or for profit as you -see fit. A simple comment in the code giving credit to the FAQ would -be courteous but is not required. diff --git a/lib/Pod/Simple/t/test_old_perlfaq3_out.txt b/lib/Pod/Simple/t/test_old_perlfaq3_out.txt deleted file mode 100644 index 11d73fc9b8..0000000000 --- a/lib/Pod/Simple/t/test_old_perlfaq3_out.txt +++ /dev/null @@ -1,266 +0,0 @@ -NAME -perlfaq3 - Programming Tools ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) -DESCRIPTION -This section of the FAQ answers questions related to programmer tools and programming support. -How do I do (anything)? -Have you looked at CPAN (see perlfaq2)? The chances are that someone has already written a module that can solve your problem. Have you read the appropriate man pages? Here's a brief index: - Basics perldata, perlvar, perlsyn, perlop, perlsub - Execution perlrun, perldebug - Functions perlfunc - Objects perlref, perlmod, perlobj, perltie - Data Structures perlref, perllol, perldsc - Modules perlmod, perlmodlib, perlsub - Regexes perlre, perlfunc, perlop, perllocale - Moving to perl5 perltrap, perl - Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed - Various http://www.perl.com/CPAN/doc/FMTEYEWTK/index.html - (not a man-page but still useful) -A crude table of contents for the Perl man page set is found in perltoc. -How can I use Perl interactively? -The typical approach uses the Perl debugger, described in the perldebug(1) man page, on an ``empty'' program, like this: - perl -de 42 -Now just type in any legal Perl code, and it will be immediately evaluated. You can also examine the symbol table, get stack backtraces, check variable values, set breakpoints, and other operations typically found in symbolic debuggers. -Is there a Perl shell? -In general, no. The Shell.pm module (distributed with Perl) makes Perl try commands which aren't part of the Perl language as shell commands. perlsh from the source distribution is simplistic and uninteresting, but may still be what you want. -How do I debug my Perl programs? -Have you tried use warnings or used -w? They enable warnings to detect dubious practices. -Have you tried use strict? It prevents you from using symbolic references, makes you predeclare any subroutines that you call as bare words, and (probably most importantly) forces you to predeclare your variables with my, our, or use vars. -Did you check the return values of each and every system call? The operating system (and thus Perl) tells you whether they worked, and if not why. - open(FH, "> /etc/cantwrite") - or die "Couldn't write to /etc/cantwrite: $!\n"; -Did you read perltrap? It's full of gotchas for old and new Perl programmers and even has sections for those of you who are upgrading from languages like awk and C. -Have you tried the Perl debugger, described in perldebug? You can step through your program and see what it's doing and thus work out why what it's doing isn't what it should be doing. -How do I profile my Perl programs? -You should get the Devel::DProf module from the standard distribution (or separately on CPAN) and also use Benchmark.pm from the standard distribution. The Benchmark module lets you time specific portions of your code, while Devel::DProf gives detailed breakdowns of where your code spends its time. -Here's a sample use of Benchmark: - use Benchmark; - @junk = `cat /etc/motd`; - $count = 10_000; - timethese($count, { - 'map' => sub { my @a = @junk; - map { s/a/b/ } @a; - return @a - }, - 'for' => sub { my @a = @junk; - local $_; - for (@a) { s/a/b/ }; - return @a }, - }); -This is what it prints (on one machine--your results will be dependent on your hardware, operating system, and the load on your machine): - Benchmark: timing 10000 iterations of for, map... - for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu) - map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) -Be aware that a good benchmark is very hard to write. It only tests the data you give it and proves little about the differing complexities of contrasting algorithms. -How do I cross-reference my Perl programs? -The B::Xref module, shipped with the new, alpha-release Perl compiler (not the general distribution prior to the 5.005 release), can be used to generate cross-reference reports for Perl programs. - perl -MO=Xref[,OPTIONS] scriptname.plx -Is there a pretty-printer (formatter) for Perl? -There is no program that will reformat Perl as much as indent(1) does for C. The complex feedback between the scanner and the parser (this feedback is what confuses the vgrind and emacs programs) makes it challenging at best to write a stand-alone Perl parser. -Of course, if you simply follow the guidelines in perlstyle, you shouldn't need to reformat. The habit of formatting your code as you write it will help prevent bugs. Your editor can and should help you with this. The perl-mode or newer cperl-mode for emacs can provide remarkable amounts of help with most (but not all) code, and even less programmable editors can provide significant assistance. Tom swears by the following settings in vi and its clones: - set ai sw=4 - map! ^O {^M}^[O^T -Now put that in your .exrc file (replacing the caret characters with control characters) and away you go. In insert mode, ^T is for indenting, ^D is for undenting, and ^O is for blockdenting-- as it were. If you haven't used the last one, you're missing a lot. A more complete example, with comments, can be found at http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz -If you are used to using the vgrind program for printing out nice code to a laser printer, you can take a stab at this using http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the results are not particularly satisfying for sophisticated code. -The a2ps at http://www.infres.enst.fr/%7Edemaille/a2ps/ does lots of things related to generating nicely printed output of documents. -Is there a ctags for Perl? -There's a simple one at http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do the trick. And if not, it's easy to hack into what you want. -Is there an IDE or Windows Perl Editor? -Perl programs are just plain text, so any editor will do. -If you're on Unix, you already have an IDE--Unix itself. The UNIX philosophy is the philosophy of several small tools that each do one thing and do it well. It's like a carpenter's toolbox. -If you want a Windows IDE, check the following: -CodeMagicCD -http://www.codemagiccd.com/ -Komodo -ActiveState's cross-platform, multi-language IDE has Perl support, including a regular expression debugger and remote debugging (http://www.ActiveState.com/Products/Komodo/index.html). (Visual Perl, a Visual Studio.NET plug-in is currently (early 2001) in beta (http://www.ActiveState.com/Products/VisualPerl/index.html)). -The Object System -(http://www.castlelink.co.uk/object_system/) is a Perl web applications development IDE. -PerlBuilder -(http://www.solutionsoft.com/perl.htm) is an integrated development environment for Windows that supports Perl development. -Perl code magic -(http://www.petes-place.com/codemagic.html). -visiPerl+ -http://helpconsulting.net/visiperl/, from Help Consulting. -For editors: if you're on Unix you probably have vi or a vi clone already, and possibly an emacs too, so you may not need to download anything. In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the best available Perl editing mode in any editor. -For Windows editors: you can download an Emacs -GNU Emacs -http://www.gnu.org/software/emacs/windows/ntemacs.html -MicroEMACS -http://members.nbci.com/uemacs/ -XEmacs -http://www.xemacs.org/Download/index.html -or a vi clone such as -Elvis -ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/ -Vile -http://vile.cx/ -Vim -http://www.vim.org/ -win32: http://www.cs.vu.nl/%7Etmgil/vi.html -For vi lovers in general, Windows or elsewhere: http://www.thomer.com/thomer/vi/vi.html. -nvi (http://www.bostic.com/vi/, available from CPAN in src/misc/) is yet another vi clone, unfortunately not available for Windows, but in UNIX platforms you might be interested in trying it out, firstly because strictly speaking it is not a vi clone, it is the real vi, or the new incarnation of it, and secondly because you can embed Perl inside it to use Perl as the scripting language. nvi is not alone in this, though: at least also vim and vile offer an embedded Perl. -The following are Win32 multilanguage editor/IDESs that support Perl: -Codewright -http://www.starbase.com/ -MultiEdit -http://www.MultiEdit.com/ -SlickEdit -http://www.slickedit.com/ -There is also a toyedit Text widget based editor written in Perl that is distributed with the Tk module on CPAN. The ptkdb (http://world.std.com/~aep/ptkdb/) is a Perl/tk based debugger that acts as a development environment of sorts. Perl Composer (http://perlcomposer.sourceforge.net/vperl.html) is an IDE for Perl/Tk GUI creation. -In addition to an editor/IDE you might be interested in a more powerful shell environment for Win32. Your options include -Bash -from the Cygwin package (http://sources.redhat.com/cygwin/) -Ksh -from the MKS Toolkit (http://www.mks.com/), or the Bourne shell of the U/WIN environment (http://www.research.att.com/sw/tools/uwin/) -Tcsh -ftp://ftp.astron.com/pub/tcsh/, see also http://www.primate.wisc.edu/software/csh-tcsh-book/ -Zsh -ftp://ftp.blarg.net/users/amol/zsh/, see also http://www.zsh.org/ -MKS and U/WIN are commercial (U/WIN is free for educational and research purposes), Cygwin is covered by the GNU Public License (but that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all contain (in addition to the shells) a comprehensive set of standard UNIX toolkit utilities. -If you're transferring text files between Unix and Windows using FTP be sure to transfer them in ASCII mode so the ends of lines are appropriately converted. -On Mac OS the MacPerl Application comes with a simple 32k text editor that behaves like a rudimentary IDE. In contrast to the MacPerl Application the MPW Perl tool can make use of the MPW Shell itself as an editor (with no 32k limit). -BBEdit and BBEdit Lite -are text editors for Mac OS that have a Perl sensitivity mode (http://web.barebones.com/). -Alpha -is an editor, written and extensible in Tcl, that nonetheless has built in support for several popular markup and programming languages including Perl and HTML (http://alpha.olm.net/). -Pepper and Pe are programming language sensitive text editors for Mac OS X and BeOS respectively (http://www.hekkelman.com/). -Where can I get Perl macros for vi? -For a complete version of Tom Christiansen's vi configuration file, see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz , the standard benchmark file for vi emulators. The file runs best with nvi, the current version of vi out of Berkeley, which incidentally can be built with an embedded Perl interpreter--see http://www.perl.com/CPAN/src/misc. -Where can I get perl-mode for emacs? -Since Emacs version 19 patchlevel 22 or so, there have been both a perl-mode.el and support for the Perl debugger built in. These should come with the standard Emacs 19 distribution. -In the Perl source directory, you'll find a directory called "emacs", which contains a cperl-mode that color-codes keywords, provides context-sensitive help, and other nifty things. -Note that the perl-mode of emacs will have fits with "main'foo" (single quote), and mess up the indentation and highlighting. You are probably using "main::foo" in new Perl code anyway, so this shouldn't be an issue. -How can I use curses with Perl? -The Curses module from CPAN provides a dynamically loadable object module interface to a curses library. A small demo can be found at the directory http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/rep; this program repeats a command and updates the screen as needed, rendering rep ps axu similar to top. -How can I use X or Tk with Perl? -Tk is a completely Perl-based, object-oriented interface to the Tk toolkit that doesn't force you to use Tcl just to get at Tk. Sx is an interface to the Athena Widget set. Both are available from CPAN. See the directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ -Invaluable for Perl/Tk programming are the Perl/Tk FAQ at http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference Guide available at http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the online manpages at http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html . -How can I generate simple menus without using CGI or Tk? -The http://www.perl.com/CPAN/authors/id/SKUNZ/perlmenu.v4.0.tar.gz module, which is curses-based, can help with this. -What is undump? -See the next question on ``How can I make my Perl program run faster?'' -How can I make my Perl program run faster? -The best way to do this is to come up with a better algorithm. This can often make a dramatic difference. Jon Bentley's book ``Programming Pearls'' (that's not a misspelling!) has some good tips on optimization, too. Advice on benchmarking boils down to: benchmark and profile to make sure you're optimizing the right part, look for better algorithms instead of microtuning your code, and when all else fails consider just buying faster hardware. -A different approach is to autoload seldom-used Perl code. See the AutoSplit and AutoLoader modules in the standard distribution for that. Or you could locate the bottleneck and think about writing just that part in C, the way we used to take bottlenecks in C code and write them in assembler. Similar to rewriting in C, modules that have critical sections can be written in C (for instance, the PDL module from CPAN). -In some cases, it may be worth it to use the backend compiler to produce byte code (saving compilation time) or compile into C, which will certainly save compilation time and sometimes a small amount (but not much) execution time. See the question about compiling your Perl programs for more on the compiler--the wins aren't as obvious as you'd hope. -If you're currently linking your perl executable to a shared libc.so, you can often gain a 10-25% performance benefit by rebuilding it to link with a static libc.a instead. This will make a bigger perl executable, but your Perl programs (and programmers) may thank you for it. See the INSTALL file in the source distribution for more information. -Unsubstantiated reports allege that Perl interpreters that use sfio outperform those that don't (for I/O intensive applications). To try this, see the INSTALL file in the source distribution, especially the ``Selecting File I/O mechanisms'' section. -The undump program was an old attempt to speed up your Perl program by storing the already-compiled form to disk. This is no longer a viable option, as it only worked on a few architectures, and wasn't a good solution anyway. -How can I make my Perl program take less memory? -When it comes to time-space tradeoffs, Perl nearly always prefers to throw memory at a problem. Scalars in Perl use more memory than strings in C, arrays take more than that, and hashes use even more. While there's still a lot to be done, recent releases have been addressing these issues. For example, as of 5.004, duplicate hash keys are shared amongst all hashes using them, so require no reallocation. -In some cases, using substr() or vec() to simulate arrays can be highly beneficial. For example, an array of a thousand booleans will take at least 20,000 bytes of space, but it can be turned into one 125-byte bit vector--a considerable memory savings. The standard Tie::SubstrHash module can also help for certain types of data structure. If you're working with specialist data structures (matrices, for instance) modules that implement these in C may use less memory than equivalent Perl modules. -Another thing to try is learning whether your Perl was compiled with the system malloc or with Perl's builtin malloc. Whichever one it is, try using the other one and see whether this makes a difference. Information about malloc is in the INSTALL file in the source distribution. You can find out whether you are using perl's malloc by typing perl -V:usemymalloc. -Is it unsafe to return a pointer to local data? -No, Perl's garbage collection system takes care of this. - sub makeone { - my @a = ( 1 .. 10 ); - return \@a; - } - for $i ( 1 .. 10 ) { - push @many, makeone(); - } - print $many[4][5], "\n"; - print "@many\n"; -How can I free an array or hash so my program shrinks? -You can't. On most operating systems, memory allocated to a program can never be returned to the system. That's why long-running programs sometimes re-exec themselves. Some operating systems (notably, FreeBSD and Linux) allegedly reclaim large chunks of memory that is no longer used, but it doesn't appear to happen with Perl (yet). The Mac appears to be the only platform that will reliably (albeit, slowly) return memory to the OS. -We've had reports that on Linux (Redhat 5.1) on Intel, undef $scalar will return memory to the system, while on Solaris 2.6 it won't. In general, try it yourself and see. -However, judicious use of my() on your variables will help make sure that they go out of scope so that Perl can free up that space for use in other parts of your program. A global variable, of course, never goes out of scope, so you can't get its space automatically reclaimed, although undef()ing and/or delete()ing it will achieve the same effect. In general, memory allocation and de-allocation isn't something you can or should be worrying about much in Perl, but even this capability (preallocation of data types) is in the works. -How can I make my CGI script more efficient? -Beyond the normal measures described to make general Perl programs faster or smaller, a CGI program has additional issues. It may be run several times per second. Given that each time it runs it will need to be re-compiled and will often allocate a megabyte or more of system memory, this can be a killer. Compiling into C isn't going to help you because the process start-up overhead is where the bottleneck is. -There are two popular ways to avoid this overhead. One solution involves running the Apache HTTP server (available from http://www.apache.org/) with either of the mod_perl or mod_fastcgi plugin modules. -With mod_perl and the Apache::Registry module (distributed with mod_perl), httpd will run with an embedded Perl interpreter which pre-compiles your script and then executes it within the same address space without forking. The Apache extension also gives Perl access to the internal server API, so modules written in Perl can do just about anything a module written in C can. For more on mod_perl, see http://perl.apache.org/ -With the FCGI module (from CPAN) and the mod_fastcgi module (available from http://www.fastcgi.com/) each of your Perl programs becomes a permanent CGI daemon process. -Both of these solutions can have far-reaching effects on your system and on the way you write your CGI programs, so investigate them with care. -See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . -A non-free, commercial product, ``The Velocity Engine for Perl'', (http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ ) might also be worth looking at. It will allow you to increase the performance of your Perl programs, running programs up to 25 times faster than normal CGI Perl when running in persistent Perl mode or 4 to 5 times faster without any modification to your existing CGI programs. Fully functional evaluation copies are available from the web site. -How can I hide the source for my Perl program? -Delete it. :-) Seriously, there are a number of (mostly unsatisfactory) solutions with varying levels of ``security''. -First of all, however, you can't take away read permission, because the source code has to be readable in order to be compiled and interpreted. (That doesn't mean that a CGI script's source is readable by people on the web, though--only by people with access to the filesystem.) So you have to leave the permissions at the socially friendly 0755 level. -Some people regard this as a security problem. If your program does insecure things and relies on people not knowing how to exploit those insecurities, it is not secure. It is often possible for someone to determine the insecure things and exploit them without viewing the source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed. -You can try using encryption via source filters (Filter::* from CPAN), but any decent programmer will be able to decrypt it. You can try using the byte code compiler and interpreter described below, but the curious might still be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (true of every language, not just Perl). -If you're concerned about people profiting from your code, then the bottom line is that nothing but a restrictive license will give you legal security. License your software and pepper it with threatening statements like ``This is unpublished proprietary software of XYZ Corp. Your access to it does not give you permission to use it blah blah blah.'' We are not lawyers, of course, so you should see a lawyer if you want to be sure your license's wording will stand up in court. -How can I compile my Perl program into byte code or C? -Malcolm Beattie has written a multifunction backend compiler, available from CPAN, that can do both these things. It is included in the perl5.005 release, but is still considered experimental. This means it's fun to play with if you're a programmer but not really for people looking for turn-key solutions. -Merely compiling into C does not in and of itself guarantee that your code will run very much faster. That's because except for lucky cases where a lot of native type inferencing is possible, the normal Perl run-time system is still present and so your program will take just as long to run and be just as big. Most programs save little more than compilation time, leaving execution no more than 10-30% faster. A few rare programs actually benefit significantly (even running several times faster), but this takes some tweaking of your code. -You'll probably be astonished to learn that the current version of the compiler generates a compiled form of your script whose executable is just as big as the original perl executable, and then some. That's because as currently written, all programs are prepared for a full eval() statement. You can tremendously reduce this cost by building a shared libperl.so library and linking against that. See the INSTALL podfile in the Perl source distribution for details. If you link your main perl binary with this, it will make it minuscule. For example, on one author's system, /usr/bin/perl is only 11k in size! -In general, the compiler will do nothing to make a Perl program smaller, faster, more portable, or more secure. In fact, it can make your situation worse. The executable will be bigger, your VM system may take longer to load the whole thing, the binary is fragile and hard to fix, and compilation never stopped software piracy in the form of crackers, viruses, or bootleggers. The real advantage of the compiler is merely packaging, and once you see the size of what it makes (well, unless you use a shared libperl.so), you'll probably want a complete Perl install anyway. -How can I compile Perl into Java? -You can also integrate Java and Perl with the Perl Resource Kit from O'Reilly and Associates. See http://www.oreilly.com/catalog/prkunix/ . -Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in development, allows Perl code to be called from Java. See jpl/README in the Perl source tree. -How can I get #!perl to work on [MS-DOS,NT,...]? -For OS/2 just use - extproc perl -S -your_switches -as the first line in *.cmd file (-S due to a bug in cmd.exe's `extproc' handling). For DOS one should first invent a corresponding batch file and codify it in ALTERNATIVE_SHEBANG (see the INSTALL file in the source distribution for more information). -The Win95/NT installation, when using the ActiveState port of Perl, will modify the Registry to associate the .pl extension with the perl interpreter. If you install another port, perhaps even building your own Win95/NT Perl from the standard sources by using a Windows port of gcc (e.g., with cygwin or mingw32), then you'll have to modify the Registry yourself. In addition to associating .pl with the interpreter, NT people can use: SET PATHEXT=%PATHEXT%;.PL to let them run the program install-linux.pl merely by typing install-linux. -Macintosh Perl programs will have the appropriate Creator and Type, so that double-clicking them will invoke the Perl application. -IMPORTANT!: Whatever you do, PLEASE don't get frustrated, and just throw the perl interpreter into your cgi-bin directory, in order to get your programs working for a web server. This is an EXTREMELY big security risk. Take the time to figure out how to do it correctly. -Can I write useful Perl programs on the command line? -Yes. Read perlrun for more information. Some examples follow. (These assume standard Unix shell quoting rules.) - # sum first and last fields - perl -lane 'print $F[0] + $F[-1]' * - # identify text files - perl -le 'for(@ARGV) {print if -f && -T _}' * - # remove (most) comments from C program - perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c - # make file a month younger than today, defeating reaper daemons - perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' * - # find first unused uid - perl -le '$i++ while getpwuid($i); print $i' - # display reasonable manpath - echo $PATH | perl -nl -072 -e ' - s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}' -OK, the last one was actually an Obfuscated Perl Contest entry. :-) -Why don't Perl one-liners work on my DOS/Mac/VMS system? -The problem is usually that the command interpreters on those systems have rather different ideas about quoting than the Unix shells under which the one-liners were created. On some systems, you may have to change single-quotes to double ones, which you must NOT do on Unix or Plan9 systems. You might also have to change a single % to a %%. -For example: - # Unix - perl -e 'print "Hello world\n"' - # DOS, etc. - perl -e "print \"Hello world\n\"" - # Mac - print "Hello world\n" - (then Run "Myscript" or Shift-Command-R) - # VMS - perl -e "print ""Hello world\n""" -The problem is that none of these examples are reliable: they depend on the command interpreter. Under Unix, the first two often work. Under DOS, it's entirely possible that neither works. If 4DOS was the command shell, you'd probably have better luck like this: - perl -e "print "Hello world\n"" -Under the Mac, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several quoting variants, except that it makes free use of the Mac's non-ASCII characters as control characters. -Using qq(), q(), and qx(), instead of "double quotes", 'single quotes', and `backticks`, may make one-liners easier to write. -There is no general solution to all of this. It is a mess, pure and simple. Sucks to be away from Unix, huh? :-) -[Some of this answer was contributed by Kenneth Albanowski.] -Where can I learn about CGI or Web programming in Perl? -For modules, get the CGI or LWP modules from CPAN. For textbooks, see the two especially dedicated to web stuff in the question on books. For problems and questions related to the web, like ``Why do I get 500 Errors'' or ``Why doesn't it run from the browser right when it runs fine on the command line'', see these sources: - WWW Security FAQ - http://www.w3.org/Security/Faq/ - Web FAQ - http://www.boutell.com/faq/ - CGI FAQ - http://www.webthing.com/tutorials/cgifaq.html - HTTP Spec - http://www.w3.org/pub/WWW/Protocols/HTTP/ - HTML Spec - http://www.w3.org/TR/REC-html40/ - http://www.w3.org/pub/WWW/MarkUp/ - CGI Spec - http://www.w3.org/CGI/ - CGI Security FAQ - http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt -Where can I learn about object-oriented Perl programming? -A good place to start is perltoot, and you can use perlobj, perlboot, and perlbot for reference. Perltoot didn't come out until the 5.004 release; you can get a copy (in pod, html, or postscript) from http://www.perl.com/CPAN/doc/FMTEYEWTK/ . -Where can I learn about linking C with Perl? [h2xs, xsubpp] -If you want to call C from Perl, start with perlxstut, moving on to perlxs, xsubpp, and perlguts. If you want to call Perl from C, then read perlembed, perlcall, and perlguts. Don't forget that you can learn a lot from looking at how the authors of existing extension modules wrote their code and solved their problems. -I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong? -Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they fail, see perlbug and send a bug report with the output of make test TEST_VERBOSE=1 along with perl -V. -When I tried to run my script, I got this message. What does it mean? -A complete list of Perl's error messages and warnings with explanatory text can be found in perldiag. You can also use the splain program (distributed with Perl) to explain the error messages: - perl program 2>diag.out - splain [-v] [-p] diag.out -or change your program to explain the messages for you: - use diagnostics; -or - use diagnostics -verbose; -What's MakeMaker? -This module (part of the standard Perl distribution) is designed to write a Makefile for an extension module from a Makefile.PL. For more information, see ExtUtils::MakeMaker. -AUTHOR AND COPYRIGHT -Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. -When included as an integrated part of the Standard Distribution of Perl or of its documentation (printed or otherwise), this works is covered under Perl's Artistic License. For separate distributions of all or part of this FAQ outside of that, see perlfaq. -Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. \ No newline at end of file diff --git a/lib/Pod/Simple/t/test_old_perlvar.pod b/lib/Pod/Simple/t/test_old_perlvar.pod deleted file mode 100644 index 765ff04825..0000000000 --- a/lib/Pod/Simple/t/test_old_perlvar.pod +++ /dev/null @@ -1,1234 +0,0 @@ -=head1 NAME - -perlvar - Perl predefined variables - -=head1 DESCRIPTION - -=head2 Predefined Names - -The following names have special meaning to Perl. Most -punctuation names have reasonable mnemonics, or analogs in the -shells. Nevertheless, if you wish to use long variable names, -you need only say - - use English; - -at the top of your program. This will alias all the short names to the -long names in the current package. Some even have medium names, -generally borrowed from B. - -If you don't mind the performance hit, variables that depend on the -currently selected filehandle may instead be set by calling an -appropriate object method on the IO::Handle object. (Summary lines -below for this contain the word HANDLE.) First you must say - - use IO::Handle; - -after which you may use either - - method HANDLE EXPR - -or more safely, - - HANDLE->method(EXPR) - -Each method returns the old value of the IO::Handle attribute. -The methods each take an optional EXPR, which if supplied specifies the -new value for the IO::Handle attribute in question. If not supplied, -most methods do nothing to the current value--except for -autoflush(), which will assume a 1 for you, just to be different. -Because loading in the IO::Handle class is an expensive operation, you should -learn how to use the regular built-in variables. - -A few of these variables are considered "read-only". This means that if -you try to assign to this variable, either directly or indirectly through -a reference, you'll raise a run-time exception. - -The following list is ordered by scalar variables first, then the -arrays, then the hashes. - -=over 8 - -=item $ARG - -=item $_ - -The default input and pattern-searching space. The following pairs are -equivalent: - - while (<>) {...} # equivalent only in while! - while (defined($_ = <>)) {...} - - /^Subject:/ - $_ =~ /^Subject:/ - - tr/a-z/A-Z/ - $_ =~ tr/a-z/A-Z/ - - chomp - chomp($_) - -Here are the places where Perl will assume $_ even if you -don't use it: - -=over 3 - -=item * - -Various unary functions, including functions like ord() and int(), as well -as the all file tests (C<-f>, C<-d>) except for C<-t>, which defaults to -STDIN. - -=item * - -Various list functions like print() and unlink(). - -=item * - -The pattern matching operations C, C, and C when used -without an C<=~> operator. - -=item * - -The default iterator variable in a C loop if no other -variable is supplied. - -=item * - -The implicit iterator variable in the grep() and map() functions. - -=item * - -The default place to put an input record when a C<< >> -operation's result is tested by itself as the sole criterion of a C -test. Outside a C test, this will not happen. - -=back - -(Mnemonic: underline is understood in certain operations.) - -=back - -=over 8 - -=item $> - -Contains the subpattern from the corresponding set of capturing -parentheses from the last pattern match, not counting patterns -matched in nested blocks that have been exited already. (Mnemonic: -like \digits.) These variables are all read-only and dynamically -scoped to the current BLOCK. - -=item $MATCH - -=item $& - -The string matched by the last successful pattern match (not counting -any matches hidden within a BLOCK or eval() enclosed by the current -BLOCK). (Mnemonic: like & in some editors.) This variable is read-only -and dynamically scoped to the current BLOCK. - -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. - -=item $PREMATCH - -=item $` - -The string preceding whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval -enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted -string.) This variable is read-only. - -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. - -=item $POSTMATCH - -=item $' - -The string following whatever was matched by the last successful -pattern match (not counting any matches hidden within a BLOCK or eval() -enclosed by the current BLOCK). (Mnemonic: C<'> often follows a quoted -string.) Example: - - $_ = 'abcdefghi'; - /def/; - print "$`:$&:$'\n"; # prints abc:def:ghi - -This variable is read-only and dynamically scoped to the current BLOCK. - -The use of this variable anywhere in a program imposes a considerable -performance penalty on all regular expression matches. See L. - -=item $LAST_PAREN_MATCH - -=item $+ - -The last bracket matched by the last search pattern. This is useful if -you don't know which one of a set of alternative patterns matched. For -example: - - /Version: (.*)|Revision: (.*)/ && ($rev = $+); - -(Mnemonic: be positive and forward looking.) -This variable is read-only and dynamically scoped to the current BLOCK. - -=item @LAST_MATCH_END - -=item @+ - -This array holds the offsets of the ends of the last successful -submatches in the currently active dynamic scope. C<$+[0]> is -the offset into the string of the end of the entire match. This -is the same value as what the C function returns when called -on the variable that was matched against. The Ith element -of this array holds the offset of the Ith submatch, so -C<$+[1]> is the offset past where $1 ends, C<$+[2]> the offset -past where $2 ends, and so on. You can use C<$#+> to determine -how many subgroups were in the last successful match. See the -examples given for the C<@-> variable. - -=item $MULTILINE_MATCHING - -=item $* - -Set to a non-zero integer value to do multi-line matching within a -string, 0 (or undefined) to tell Perl that it can assume that strings -contain a single line, for the purpose of optimizing pattern matches. -Pattern matches on strings containing multiple newlines can produce -confusing results when C<$*> is 0 or undefined. Default is undefined. -(Mnemonic: * matches multiple things.) This variable influences the -interpretation of only C<^> and C<$>. A literal newline can be searched -for even when C<$* == 0>. - -Use of C<$*> is deprecated in modern Perl, supplanted by -the C and C modifiers on pattern matching. - -Assigning a non-numerical value to C<$*> triggers a warning (and makes -C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> -makes that an implicit C is applied on the value. - -=item input_line_number HANDLE EXPR - -=item $INPUT_LINE_NUMBER - -=item $NR - -=item $. - -The current input record number for the last file handle from which -you just read() (or called a C or C on). The value -may be different from the actual physical line number in the file, -depending on what notion of "line" is in effect--see C<$/> on how -to change that. An explicit close on a filehandle resets the line -number. Because C<< <> >> never does an explicit close, line -numbers increase across ARGV files (but see examples in L). -Consider this variable read-only: setting it does not reposition -the seek pointer; you'll have to do that on your own. Localizing C<$.> -has the effect of also localizing Perl's notion of "the last read -filehandle". (Mnemonic: many programs use "." to mean the current line -number.) - -=item input_record_separator HANDLE EXPR - -=item $INPUT_RECORD_SEPARATOR - -=item $RS - -=item $/ - -The input record separator, newline by default. This -influences Perl's idea of what a "line" is. Works like B's RS -variable, including treating empty lines as a terminator if set to -the null string. (An empty line cannot contain any spaces -or tabs.) You may set it to a multi-character string to match a -multi-character terminator, or to C to read through the end -of file. Setting it to C<"\n\n"> means something slightly -different than setting to C<"">, if the file contains consecutive -empty lines. Setting to C<""> will treat two or more consecutive -empty lines as a single empty line. Setting to C<"\n\n"> will -blindly assume that the next input character belongs to the next -paragraph, even if it's a newline. (Mnemonic: / delimits -line boundaries when quoting poetry.) - - undef $/; # enable "slurp" mode - $_ = ; # whole file now here - s/\n[ \t]+/ /g; - -Remember: the value of C<$/> is a string, not a regex. B has to be -better for something. :-) - -Setting C<$/> to a reference to an integer, scalar containing an integer, or -scalar that's convertible to an integer will attempt to read records -instead of lines, with the maximum record size being the referenced -integer. So this: - - $/ = \32768; # or \"32768", or \$var_containing_32768 - open(FILE, $myfile); - $_ = ; - -will read a record of no more than 32768 bytes from FILE. If you're -not reading from a record-oriented file (or your OS doesn't have -record-oriented files), then you'll likely get a full chunk of data -with every read. If a record is larger than the record size you've -set, you'll get the record back in pieces. - -On VMS, record reads are done with the equivalent of C, -so it's best not to mix record and non-record reads on the same -file. (This is unlikely to be a problem, because any file you'd -want to read in record mode is probably unusable in line mode.) -Non-VMS systems do normal I/O, so it's safe to mix record and -non-record reads of a file. - -See also L. Also see C<$.>. - -=item autoflush HANDLE EXPR - -=item $OUTPUT_AUTOFLUSH - -=item $| - -If set to nonzero, forces a flush right away and after every write -or print on the currently selected output channel. Default is 0 -(regardless of whether the channel is really buffered by the -system or not; C<$|> tells you only whether you've asked Perl -explicitly to flush after each write). STDOUT will -typically be line buffered if output is to the terminal and block -buffered otherwise. Setting this variable is useful primarily when -you are outputting to a pipe or socket, such as when you are running -a Perl program under B and want to see the output as it's -happening. This has no effect on input buffering. See L -for that. (Mnemonic: when you want your pipes to be piping hot.) - -=item output_field_separator HANDLE EXPR - -=item $OUTPUT_FIELD_SEPARATOR - -=item $OFS - -=item $, - -The output field separator for the print operator. Ordinarily the -print operator simply prints out its arguments without further -adornment. To get behavior more like B, set this variable as -you would set B's OFS variable to specify what is printed -between fields. (Mnemonic: what is printed when there is a "," in -your print statement.) - -=item output_record_separator HANDLE EXPR - -=item $OUTPUT_RECORD_SEPARATOR - -=item $ORS - -=item $\ - -The output record separator for the print operator. Ordinarily the -print operator simply prints out its arguments as is, with no -trailing newline or other end-of-record string added. To get -behavior more like B, set this variable as you would set -B's ORS variable to specify what is printed at the end of the -print. (Mnemonic: you set C<$\> instead of adding "\n" at the -end of the print. Also, it's just like C<$/>, but it's what you -get "back" from Perl.) - -=item $LIST_SEPARATOR - -=item $" - -This is like C<$,> except that it applies to array and slice values -interpolated into a double-quoted string (or similar interpreted -string). Default is a space. (Mnemonic: obvious, I think.) - -=item $SUBSCRIPT_SEPARATOR - -=item $SUBSEP - -=item $; - -The subscript separator for multidimensional array emulation. If you -refer to a hash element as - - $foo{$a,$b,$c} - -it really means - - $foo{join($;, $a, $b, $c)} - -But don't put - - @foo{$a,$b,$c} # a slice--note the @ - -which means - - ($foo{$a},$foo{$b},$foo{$c}) - -Default is "\034", the same as SUBSEP in B. If your -keys contain binary data there might not be any safe value for C<$;>. -(Mnemonic: comma (the syntactic subscript separator) is a -semi-semicolon. Yeah, I know, it's pretty lame, but C<$,> is already -taken for something more important.) - -Consider using "real" multidimensional arrays as described -in L. - -=item $OFMT - -=item $# - -The output format for printed numbers. This variable is a half-hearted -attempt to emulate B's OFMT variable. There are times, however, -when B and Perl have differing notions of what counts as -numeric. The initial value is "%.Ig", where I is the value -of the macro DBL_DIG from your system's F. This is different from -B's default OFMT setting of "%.6g", so you need to set C<$#> -explicitly to get B's value. (Mnemonic: # is the number sign.) - -Use of C<$#> is deprecated. - -=item format_page_number HANDLE EXPR - -=item $FORMAT_PAGE_NUMBER - -=item $% - -The current page number of the currently selected output channel. -Used with formats. -(Mnemonic: % is page number in B.) - -=item format_lines_per_page HANDLE EXPR - -=item $FORMAT_LINES_PER_PAGE - -=item $= - -The current page length (printable lines) of the currently selected -output channel. Default is 60. -Used with formats. -(Mnemonic: = has horizontal lines.) - -=item format_lines_left HANDLE EXPR - -=item $FORMAT_LINES_LEFT - -=item $- - -The number of lines left on the page of the currently selected output -channel. -Used with formats. -(Mnemonic: lines_on_page - lines_printed.) - -=item @LAST_MATCH_START - -=item @- - -$-[0] is the offset of the start of the last successful match. -C<$-[>IC<]> is the offset of the start of the substring matched by -I-th subpattern, or undef if the subpattern did not match. - -Thus after a match against $_, $& coincides with C. Similarly, C<$>I coincides with CIC<], -$+[>IC<] - $-[>IC<]> if C<$-[>IC<]> is defined, and $+ coincides with -C. One can use C<$#-> to find the last -matched subgroup in the last successful match. Contrast with -C<$#+>, the number of subgroups in the regular expression. Compare -with C<@+>. - -This array holds the offsets of the beginnings of the last -successful submatches in the currently active dynamic scope. -C<$-[0]> is the offset into the string of the beginning of the -entire match. The Ith element of this array holds the offset -of the Ith submatch, so C<$+[1]> is the offset where $1 -begins, C<$+[2]> the offset where $2 begins, and so on. -You can use C<$#-> to determine how many subgroups were in the -last successful match. Compare with the C<@+> variable. - -After a match against some variable $var: - -=over 5 - -=item C<$`> is the same as C - -=item C<$&> is the same as C - -=item C<$'> is the same as C - -=item C<$1> is the same as C - -=item C<$2> is the same as C - -=item C<$3> is the same as C - -=back - -=item format_name HANDLE EXPR - -=item $FORMAT_NAME - -=item $~ - -The name of the current report format for the currently selected output -channel. Default is the name of the filehandle. (Mnemonic: brother to -C<$^>.) - -=item format_top_name HANDLE EXPR - -=item $FORMAT_TOP_NAME - -=item $^ - -The name of the current top-of-page format for the currently selected -output channel. Default is the name of the filehandle with _TOP -appended. (Mnemonic: points to top of page.) - -=item format_line_break_characters HANDLE EXPR - -=item $FORMAT_LINE_BREAK_CHARACTERS - -=item $: - -The current set of characters after which a string may be broken to -fill continuation fields (starting with ^) in a format. Default is -S<" \n-">, to break on whitespace or hyphens. (Mnemonic: a "colon" in -poetry is a part of a line.) - -=item format_formfeed HANDLE EXPR - -=item $FORMAT_FORMFEED - -=item $^L - -What formats output as a form feed. Default is \f. - -=item $ACCUMULATOR - -=item $^A - -The current value of the write() accumulator for format() lines. A format -contains formline() calls that put their result into C<$^A>. After -calling its format, write() prints out the contents of C<$^A> and empties. -So you never really see the contents of C<$^A> unless you call -formline() yourself and then look at it. See L and -L. - -=item $CHILD_ERROR - -=item $? - -The status returned by the last pipe close, backtick (C<``>) command, -successful call to wait() or waitpid(), or from the system() -operator. This is just the 16-bit status word returned by the -wait() system call (or else is made up to look like it). Thus, the -exit value of the subprocess is really (C<<< $? >> 8 >>>), and -C<$? & 127> gives which signal, if any, the process died from, and -C<$? & 128> reports whether there was a core dump. (Mnemonic: -similar to B and B.) - -Additionally, if the C variable is supported in C, its value -is returned via $? if any C function fails. - -If you have installed a signal handler for C, the -value of C<$?> will usually be wrong outside that handler. - -Inside an C subroutine C<$?> contains the value that is going to be -given to C. You can modify C<$?> in an C subroutine to -change the exit status of your program. For example: - - END { - $? = 1 if $? == 255; # die would make it 255 - } - -Under VMS, the pragma C makes C<$?> reflect the -actual VMS exit status, instead of the default emulation of POSIX -status. - -Also see L. - -=item $OS_ERROR - -=item $ERRNO - -=item $! - -If used numerically, yields the current value of the C C -variable, with all the usual caveats. (This means that you shouldn't -depend on the value of C<$!> to be anything in particular unless -you've gotten a specific error return indicating a system error.) -If used an a string, yields the corresponding system error string. -You can assign a number to C<$!> to set I if, for instance, -you want C<"$!"> to return the string for error I, or you want -to set the exit value for the die() operator. (Mnemonic: What just -went bang?) - -Also see L. - -=item $EXTENDED_OS_ERROR - -=item $^E - -Error information specific to the current operating system. At -the moment, this differs from C<$!> under only VMS, OS/2, and Win32 -(and for MacPerl). On all other platforms, C<$^E> is always just -the same as C<$!>. - -Under VMS, C<$^E> provides the VMS status value from the last -system error. This is more specific information about the last -system error than that provided by C<$!>. This is particularly -important when C<$!> is set to B. - -Under OS/2, C<$^E> is set to the error code of the last call to -OS/2 API either via CRT, or directly from perl. - -Under Win32, C<$^E> always returns the last error information -reported by the Win32 call C which describes -the last error from within the Win32 API. Most Win32-specific -code will report errors via C<$^E>. ANSI C and Unix-like calls -set C and so most portable Perl code will report errors -via C<$!>. - -Caveats mentioned in the description of C<$!> generally apply to -C<$^E>, also. (Mnemonic: Extra error explanation.) - -Also see L. - -=item $EVAL_ERROR - -=item $@ - -The Perl syntax error message from the last eval() operator. If null, the -last eval() parsed and executed correctly (although the operations you -invoked may have failed in the normal fashion). (Mnemonic: Where was -the syntax error "at"?) - -Warning messages are not collected in this variable. You can, -however, set up a routine to process warnings by setting C<$SIG{__WARN__}> -as described below. - -Also see L. - -=item $PROCESS_ID - -=item $PID - -=item $$ - -The process number of the Perl running this script. You should -consider this variable read-only, although it will be altered -across fork() calls. (Mnemonic: same as shells.) - -=item $REAL_USER_ID - -=item $UID - -=item $< - -The real uid of this process. (Mnemonic: it's the uid you came I, -if you're running setuid.) - -=item $EFFECTIVE_USER_ID - -=item $EUID - -=item $> - -The effective uid of this process. Example: - - $< = $>; # set real to effective uid - ($<,$>) = ($>,$<); # swap real and effective uid - -(Mnemonic: it's the uid you went I, if you're running setuid.) -C<< $< >> and C<< $> >> can be swapped only on machines -supporting setreuid(). - -=item $REAL_GROUP_ID - -=item $GID - -=item $( - -The real gid of this process. If you are on a machine that supports -membership in multiple groups simultaneously, gives a space separated -list of groups you are in. The first number is the one returned by -getgid(), and the subsequent ones by getgroups(), one of which may be -the same as the first number. - -However, a value assigned to C<$(> must be a single number used to -set the real gid. So the value given by C<$(> should I be assigned -back to C<$(> without being forced numeric, such as by adding zero. - -(Mnemonic: parentheses are used to I things. The real gid is the -group you I, if you're running setgid.) - -=item $EFFECTIVE_GROUP_ID - -=item $EGID - -=item $) - -The effective gid of this process. If you are on a machine that -supports membership in multiple groups simultaneously, gives a space -separated list of groups you are in. The first number is the one -returned by getegid(), and the subsequent ones by getgroups(), one of -which may be the same as the first number. - -Similarly, a value assigned to C<$)> must also be a space-separated -list of numbers. The first number sets the effective gid, and -the rest (if any) are passed to setgroups(). To get the effect of an -empty list for setgroups(), just repeat the new effective gid; that is, -to force an effective gid of 5 and an effectively empty setgroups() -list, say C< $) = "5 5" >. - -(Mnemonic: parentheses are used to I things. The effective gid -is the group that's I for you, if you're running setgid.) - -C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on -machines that support the corresponding I routine. C<$(> -and C<$)> can be swapped only on machines supporting setregid(). - -=item $PROGRAM_NAME - -=item $0 - -Contains the name of the program being executed. On some operating -systems assigning to C<$0> modifies the argument area that the B -program sees. This is more useful as a way of indicating the current -program state than it is for hiding the program you're running. -(Mnemonic: same as B and B.) - -Note for BSD users: setting C<$0> does not completely remove "perl" -from the ps(1) output. For example, setting C<$0> to C<"foobar"> will -result in C<"perl: foobar (perl)">. This is an operating system -feature. - -=item $[ - -The index of the first element in an array, and of the first character -in a substring. Default is 0, but you could theoretically set it -to 1 to make Perl behave more like B (or Fortran) when -subscripting and when evaluating the index() and substr() functions. -(Mnemonic: [ begins subscripts.) - -As of release 5 of Perl, assignment to C<$[> is treated as a compiler -directive, and cannot influence the behavior of any other file. -Its use is highly discouraged. - -=item $] - -The version + patchlevel / 1000 of the Perl interpreter. This variable -can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: Is this version -of perl in the right bracket?) Example: - - warn "No checksumming!\n" if $] < 3.019; - -See also the documentation of C and C -for a convenient way to fail if the running Perl interpreter is too old. - -The use of this variable is deprecated. The floating point representation -can sometimes lead to inaccurate numeric comparisons. See C<$^V> for a -more modern representation of the Perl version that allows accurate string -comparisons. - -=item $COMPILING - -=item $^C - -The current value of the flag associated with the B<-c> switch. -Mainly of use with B<-MO=...> to allow code to alter its behavior -when being compiled, such as for example to AUTOLOAD at compile -time rather than normal, deferred loading. See L. Setting -C<$^C = 1> is similar to calling C. - -=item $DEBUGGING - -=item $^D - -The current value of the debugging flags. (Mnemonic: value of B<-D> -switch.) - -=item $SYSTEM_FD_MAX - -=item $^F - -The maximum system file descriptor, ordinarily 2. System file -descriptors are passed to exec()ed processes, while higher file -descriptors are not. Also, during an open(), system file descriptors are -preserved even if the open() fails. (Ordinary file descriptors are -closed before the open() is attempted.) The close-on-exec -status of a file descriptor will be decided according to the value of -C<$^F> when the corresponding file, pipe, or socket was opened, not the -time of the exec(). - -=item $^H - -WARNING: This variable is strictly for internal use only. Its availability, -behavior, and contents are subject to change without notice. - -This variable contains compile-time hints for the Perl interpreter. At the -end of compilation of a BLOCK the value of this variable is restored to the -value when the interpreter started to compile the BLOCK. - -When perl begins to parse any block construct that provides a lexical scope -(e.g., eval body, required file, subroutine body, loop body, or conditional -block), the existing value of $^H is saved, but its value is left unchanged. -When the compilation of the block is completed, it regains the saved value. -Between the points where its value is saved and restored, code that -executes within BEGIN blocks is free to change the value of $^H. - -This behavior provides the semantic of lexical scoping, and is used in, -for instance, the C pragma. - -The contents should be an integer; different bits of it are used for -different pragmatic flags. Here's an example: - - sub add_100 { $^H |= 0x100 } - - sub foo { - BEGIN { add_100() } - bar->baz($boon); - } - -Consider what happens during execution of the BEGIN block. At this point -the BEGIN block has already been compiled, but the body of foo() is still -being compiled. The new value of $^H will therefore be visible only while -the body of foo() is being compiled. - -Substitution of the above BEGIN block with: - - BEGIN { require strict; strict->import('vars') } - -demonstrates how C is implemented. Here's a conditional -version of the same lexical pragma: - - BEGIN { require strict; strict->import('vars') if $condition } - -=item %^H - -WARNING: This variable is strictly for internal use only. Its availability, -behavior, and contents are subject to change without notice. - -The %^H hash provides the same scoping semantic as $^H. This makes it -useful for implementation of lexically scoped pragmas. - -=item $INPLACE_EDIT - -=item $^I - -The current value of the inplace-edit extension. Use C to disable -inplace editing. (Mnemonic: value of B<-i> switch.) - -=item $^M - -By default, running out of memory is an untrappable, fatal error. -However, if suitably built, Perl can use the contents of C<$^M> -as an emergency memory pool after die()ing. Suppose that your Perl -were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. -Then - - $^M = 'a' x (1 << 16); - -would allocate a 64K buffer for use in an emergency. See the -F file in the Perl distribution for information on how to -enable this option. To discourage casual use of this advanced -feature, there is no L long name for this variable. - -=item $OSNAME - -=item $^O - -The name of the operating system under which this copy of Perl was -built, as determined during the configuration process. The value -is identical to C<$Config{'osname'}>. See also L and the -B<-V> command-line switch documented in L. - -=item $PERLDB - -=item $^P - -The internal variable for debugging support. The meanings of the -various bits are subject to change, but currently indicate: - -=over 6 - -=item 0x01 - -Debug subroutine enter/exit. - -=item 0x02 - -Line-by-line debugging. - -=item 0x04 - -Switch off optimizations. - -=item 0x08 - -Preserve more data for future interactive inspections. - -=item 0x10 - -Keep info about source lines on which a subroutine is defined. - -=item 0x20 - -Start with single-step on. - -=item 0x40 - -Use subroutine address instead of name when reporting. - -=item 0x80 - -Report C as well. - -=item 0x100 - -Provide informative "file" names for evals based on the place they were compiled. - -=item 0x200 - -Provide informative names to anonymous subroutines based on the place they -were compiled. - -=back - -Some bits may be relevant at compile-time only, some at -run-time only. This is a new mechanism and the details may change. - -=item $LAST_REGEXP_CODE_RESULT - -=item $^R - -The result of evaluation of the last successful C<(?{ code })> -regular expression assertion (see L). May be written to. - -=item $EXCEPTIONS_BEING_CAUGHT - -=item $^S - -Current state of the interpreter. Undefined if parsing of the current -module/eval is not finished (may happen in $SIG{__DIE__} and -$SIG{__WARN__} handlers). True if inside an eval(), otherwise false. - -=item $BASETIME - -=item $^T - -The time at which the program began running, in seconds since the -epoch (beginning of 1970). The values returned by the B<-M>, B<-A>, -and B<-C> filetests are based on this value. - -=item $PERL_VERSION - -=item $^V - -The revision, version, and subversion of the Perl interpreter, represented -as a string composed of characters with those ordinals. Thus in Perl v5.6.0 -it equals C and will return true for -C<$^V eq v5.6.0>. Note that the characters in this string value can -potentially be in Unicode range. - -This can be used to determine whether the Perl interpreter executing a -script is in the right range of versions. (Mnemonic: use ^V for Version -Control.) Example: - - warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; - -See the documentation of C and C -for a convenient way to fail if the running Perl interpreter is too old. - -See also C<$]> for an older representation of the Perl version. - -=item $WARNING - -=item $^W - -The current value of the warning switch, initially true if B<-w> -was used, false otherwise, but directly modifiable. (Mnemonic: -related to the B<-w> switch.) See also L. - -=item ${^WARNING_BITS} - -The current set of warning checks enabled by the C pragma. -See the documentation of C for more details. - -=item ${^WIDE_SYSTEM_CALLS} - -Global flag that enables system calls made by Perl to use wide character -APIs native to the system, if available. This is currently only implemented -on the Windows platform. - -This can also be enabled from the command line using the C<-C> switch. - -The initial value is typically C<0> for compatibility with Perl versions -earlier than 5.6, but may be automatically set to C<1> by Perl if the system -provides a user-settable default (e.g., C<$ENV{LC_CTYPE}>). - -The C pragma always overrides the effect of this flag in the current -lexical scope. See L. - -=item $EXECUTABLE_NAME - -=item $^X - -The name that the Perl binary itself was executed as, from C's C. -This may not be a full pathname, nor even necessarily in your path. - -=item $ARGV - -contains the name of the current file when reading from <>. - -=item @ARGV - -The array @ARGV contains the command-line arguments intended for -the script. C<$#ARGV> is generally the number of arguments minus -one, because C<$ARGV[0]> is the first argument, I the program's -command name itself. See C<$0> for the command name. - -=item @INC - -The array @INC contains the list of places that the C, -C, or C constructs look for their library files. It -initially consists of the arguments to any B<-I> command-line -switches, followed by the default Perl library, probably -F, followed by ".", to represent the current -directory. If you need to modify this at runtime, you should use -the C pragma to get the machine-dependent library properly -loaded also: - - use lib '/mypath/libdir/'; - use SomeMod; - -=item @_ - -Within a subroutine the array @_ contains the parameters passed to that -subroutine. See L. - -=item %INC - -The hash %INC contains entries for each filename included via the -C, C, or C operators. The key is the filename -you specified (with module names converted to pathnames), and the -value is the location of the file found. The C -operator uses this hash to determine whether a particular file has -already been included. - -=item %ENV - -=item $ENV{expr} - -The hash %ENV contains your current environment. Setting a -value in C changes the environment for any child processes -you subsequently fork() off. - -=item %SIG - -=item $SIG{expr} - -The hash %SIG contains signal handlers for signals. For example: - - sub handler { # 1st argument is signal name - my($sig) = @_; - print "Caught a SIG$sig--shutting down\n"; - close(LOG); - exit(0); - } - - $SIG{'INT'} = \&handler; - $SIG{'QUIT'} = \&handler; - ... - $SIG{'INT'} = 'DEFAULT'; # restore default action - $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT - -Using a value of C<'IGNORE'> usually has the effect of ignoring the -signal, except for the C signal. See L for more about -this special case. - -Here are some other examples: - - $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) - $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber - $SIG{"PIPE"} = *Plumber; # somewhat esoteric - $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? - -Be sure not to use a bareword as the name of a signal handler, -lest you inadvertently call it. - -If your system has the sigaction() function then signal handlers are -installed using it. This means you get reliable signal handling. If -your system has the SA_RESTART flag it is used when signals handlers are -installed. This means that system calls for which restarting is supported -continue rather than returning when a signal arrives. If you want your -system calls to be interrupted by signal delivery then do something like -this: - - use POSIX ':signal_h'; - - my $alarm = 0; - sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } - or die "Error setting SIGALRM handler: $!\n"; - -See L. - -Certain internal hooks can be also set using the %SIG hash. The -routine indicated by C<$SIG{__WARN__}> is called when a warning message is -about to be printed. The warning message is passed as the first -argument. The presence of a __WARN__ hook causes the ordinary printing -of warnings to STDERR to be suppressed. You can use this to save warnings -in a variable, or turn warnings into fatal errors, like this: - - local $SIG{__WARN__} = sub { die $_[0] }; - eval $proggie; - -The routine indicated by C<$SIG{__DIE__}> is called when a fatal exception -is about to be thrown. The error message is passed as the first -argument. When a __DIE__ hook routine returns, the exception -processing continues as it would have in the absence of the hook, -unless the hook routine itself exits via a C, a loop exit, or a die(). -The C<__DIE__> handler is explicitly disabled during the call, so that you -can die from a C<__DIE__> handler. Similarly for C<__WARN__>. - -Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called -even inside an eval(). Do not use this to rewrite a pending exception -in C<$@>, or as a bizarre substitute for overriding CORE::GLOBAL::die(). -This strange action at a distance may be fixed in a future release -so that C<$SIG{__DIE__}> is only called if your program is about -to exit, as was the original intent. Any other use is deprecated. - -C<__DIE__>/C<__WARN__> handlers are very special in one respect: -they may be called to report (probable) errors found by the parser. -In such a case the parser may be in inconsistent state, so any -attempt to evaluate Perl code from such a handler will probably -result in a segfault. This means that warnings or errors that -result from parsing Perl should be used with extreme caution, like -this: - - require Carp if defined $^S; - Carp::confess("Something wrong") if defined &Carp::confess; - die "Something wrong, but could not load Carp to give backtrace... - To see backtrace try starting Perl with -MCarp switch"; - -Here the first line will load Carp I it is the parser who -called the handler. The second line will print backtrace and die if -Carp was available. The third line will be executed only if Carp was -not available. - -See L, L, L, and -L for additional information. - -=back - -=head2 Error Indicators - -The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information -about different types of error conditions that may appear during -execution of a Perl program. The variables are shown ordered by -the "distance" between the subsystem which reported the error and -the Perl process. They correspond to errors detected by the Perl -interpreter, C library, operating system, or an external program, -respectively. - -To illustrate the differences between these variables, consider the -following Perl expression, which uses a single-quoted string: - - eval q{ - open PIPE, "/cdrom/install |"; - @res = ; - close PIPE or die "bad pipe: $?, $!"; - }; - -After execution of this statement all 4 variables may have been set. - -C<$@> is set if the string to be C-ed did not compile (this -may happen if C or C were imported with bad prototypes), -or if Perl code executed during evaluation die()d . In these cases -the value of $@ is the compile error, or the argument to C -(which will interpolate C<$!> and C<$?>!). (See also L, -though.) - -When the eval() expression above is executed, open(), C<< >>, -and C are translated to calls in the C run-time library and -thence to the operating system kernel. C<$!> is set to the C library's -C if one of these calls fails. - -Under a few operating systems, C<$^E> may contain a more verbose -error indicator, such as in this case, "CDROM tray not closed." -Systems that do not support extended error messages leave C<$^E> -the same as C<$!>. - -Finally, C<$?> may be set to non-0 value if the external program -F fails. The upper eight bits reflect specific -error conditions encountered by the program (the program's exit() -value). The lower eight bits reflect mode of failure, like signal -death and core dump information See wait(2) for details. In -contrast to C<$!> and C<$^E>, which are set only if error condition -is detected, the variable C<$?> is set on each C or pipe -C, overwriting the old value. This is more like C<$@>, which -on every eval() is always set on failure and cleared on success. - -For more details, see the individual descriptions at C<$@>, C<$!>, C<$^E>, -and C<$?>. - -=head2 Technical Note on the Syntax of Variable Names - -Variable names in Perl can have several formats. Usually, they -must begin with a letter or underscore, in which case they can be -arbitrarily long (up to an internal limit of 251 characters) and -may contain letters, digits, underscores, or the special sequence -C<::> or C<'>. In this case, the part before the last C<::> or -C<'> is taken to be a I; see L. - -Perl variable names may also be a sequence of digits or a single -punctuation or control character. These names are all reserved for -special uses by Perl; for example, the all-digits names are used -to hold data captured by backreferences after a regular expression -match. Perl has a special syntax for the single-control-character -names: It understands C<^X> (caret C) to mean the control-C -character. For example, the notation C<$^W> (dollar-sign caret -C) is the scalar variable whose name is the single character -control-C. This is better than typing a literal control-C -into your program. - -Finally, new in Perl 5.6, Perl variable names may be alphanumeric -strings that begin with control characters (or better yet, a caret). -These variables must be written in the form C<${^Foo}>; the braces -are not optional. C<${^Foo}> denotes the scalar variable whose -name is a control-C followed by two C's. These variables are -reserved for future special uses by Perl, except for the ones that -begin with C<^_> (control-underscore or caret-underscore). No -control-character name that begins with C<^_> will acquire a special -meaning in any future version of Perl; such names may therefore be -used safely in programs. C<$^_> itself, however, I reserved. - -Perl identifiers that begin with digits, control characters, or -punctuation characters are exempt from the effects of the C -declaration and are always forced to be in package C
. A few -other names are also exempt: - - ENV STDIN - INC STDOUT - ARGV STDERR - ARGVOUT - SIG - -In particular, the new special C<${^_XYZ}> variables are always taken -to be in package C
, regardless of any C declarations -presently in scope. - -=head1 BUGS - -Due to an unfortunate accident of Perl's implementation, C imposes a considerable performance penalty on all regular -expression matches in a program, regardless of whether they occur -in the scope of C. For that reason, saying C in libraries is strongly discouraged. See the -Devel::SawAmpersand module documentation from CPAN -(http://www.perl.com/CPAN/modules/by-module/Devel/) -for more information. - -Having to even think about the C<$^S> variable in your exception -handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented -invites grievous and difficult to track down errors. Avoid it -and use an C or CORE::GLOBAL::die override instead. diff --git a/lib/Pod/Simple/t/test_old_perlvar_out.txt b/lib/Pod/Simple/t/test_old_perlvar_out.txt deleted file mode 100644 index 0a67979962..0000000000 --- a/lib/Pod/Simple/t/test_old_perlvar_out.txt +++ /dev/null @@ -1,406 +0,0 @@ -NAME -perlvar - Perl predefined variables -DESCRIPTION -Predefined Names -The following names have special meaning to Perl. Most punctuation names have reasonable mnemonics, or analogs in the shells. Nevertheless, if you wish to use long variable names, you need only say - use English; -at the top of your program. This will alias all the short names to the long names in the current package. Some even have medium names, generally borrowed from awk. -If you don't mind the performance hit, variables that depend on the currently selected filehandle may instead be set by calling an appropriate object method on the IO::Handle object. (Summary lines below for this contain the word HANDLE.) First you must say - use IO::Handle; -after which you may use either - method HANDLE EXPR -or more safely, - HANDLE->method(EXPR) -Each method returns the old value of the IO::Handle attribute. The methods each take an optional EXPR, which if supplied specifies the new value for the IO::Handle attribute in question. If not supplied, most methods do nothing to the current value--except for autoflush(), which will assume a 1 for you, just to be different. Because loading in the IO::Handle class is an expensive operation, you should learn how to use the regular built-in variables. -A few of these variables are considered "read-only". This means that if you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception. -The following list is ordered by scalar variables first, then the arrays, then the hashes. -$ARG -$_ -The default input and pattern-searching space. The following pairs are equivalent: - while (<>) {...} # equivalent only in while! - while (defined($_ = <>)) {...} - /^Subject:/ - $_ =~ /^Subject:/ - tr/a-z/A-Z/ - $_ =~ tr/a-z/A-Z/ - chomp - chomp($_) -Here are the places where Perl will assume $_ even if you don't use it: - Various unary functions, including functions like ord() and int(), as well as the all file tests (-f, -d) except for -t, which defaults to STDIN. - Various list functions like print() and unlink(). - The pattern matching operations m//, s///, and tr/// when used without an =~ operator. - The default iterator variable in a foreach loop if no other variable is supplied. - The implicit iterator variable in the grep() and map() functions. - The default place to put an input record when a operation's result is tested by itself as the sole criterion of a while test. Outside a while test, this will not happen. -(Mnemonic: underline is understood in certain operations.) -$ -Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digits.) These variables are all read-only and dynamically scoped to the current BLOCK. -$MATCH -$& -The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: like & in some editors.) This variable is read-only and dynamically scoped to the current BLOCK. -The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. -$PREMATCH -$` -The string preceding whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted string.) This variable is read-only. -The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. -$POSTMATCH -$' -The string following whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted string.) Example: - $_ = 'abcdefghi'; - /def/; - print "$`:$&:$'\n"; # prints abc:def:ghi -This variable is read-only and dynamically scoped to the current BLOCK. -The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS. -$LAST_PAREN_MATCH -$+ -The last bracket matched by the last search pattern. This is useful if you don't know which one of a set of alternative patterns matched. For example: - /Version: (.*)|Revision: (.*)/ && ($rev = $+); -(Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. -@LAST_MATCH_END -@+ -This array holds the offsets of the ends of the last successful submatches in the currently active dynamic scope. $+[0] is the offset into the string of the end of the entire match. This is the same value as what the pos function returns when called on the variable that was matched against. The nth element of this array holds the offset of the nth submatch, so $+[1] is the offset past where $1 ends, $+[2] the offset past where $2 ends, and so on. You can use $#+ to determine how many subgroups were in the last successful match. See the examples given for the @- variable. -$MULTILINE_MATCHING -$* -Set to a non-zero integer value to do multi-line matching within a string, 0 (or undefined) to tell Perl that it can assume that strings contain a single line, for the purpose of optimizing pattern matches. Pattern matches on strings containing multiple newlines can produce confusing results when $* is 0 or undefined. Default is undefined. (Mnemonic: * matches multiple things.) This variable influences the interpretation of only ^ and $. A literal newline can be searched for even when $* == 0. -Use of $* is deprecated in modern Perl, supplanted by the /s and /m modifiers on pattern matching. -Assigning a non-numerical value to $* triggers a warning (and makes $* act if $* == 0), while assigning a numerical value to $* makes that an implicit int is applied on the value. -input_line_number HANDLE EXPR -$INPUT_LINE_NUMBER -$NR -$. -The current input record number for the last file handle from which you just read() (or called a seek or tell on). The value may be different from the actual physical line number in the file, depending on what notion of "line" is in effect--see $/ on how to change that. An explicit close on a filehandle resets the line number. Because <> never does an explicit close, line numbers increase across ARGV files (but see examples in "eof" in perlfunc). Consider this variable read-only: setting it does not reposition the seek pointer; you'll have to do that on your own. Localizing $. has the effect of also localizing Perl's notion of "the last read filehandle". (Mnemonic: many programs use "." to mean the current line number.) -input_record_separator HANDLE EXPR -$INPUT_RECORD_SEPARATOR -$RS -$/ -The input record separator, newline by default. This influences Perl's idea of what a "line" is. Works like awk's RS variable, including treating empty lines as a terminator if set to the null string. (An empty line cannot contain any spaces or tabs.) You may set it to a multi-character string to match a multi-character terminator, or to undef to read through the end of file. Setting it to "\n\n" means something slightly different than setting to "", if the file contains consecutive empty lines. Setting to "" will treat two or more consecutive empty lines as a single empty line. Setting to "\n\n" will blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / delimits line boundaries when quoting poetry.) - undef $/; # enable "slurp" mode - $_ = ; # whole file now here - s/\n[ \t]+/ /g; -Remember: the value of $/ is a string, not a regex. awk has to be better for something. :-) -Setting $/ to a reference to an integer, scalar containing an integer, or scalar that's convertible to an integer will attempt to read records instead of lines, with the maximum record size being the referenced integer. So this: - $/ = \32768; # or \"32768", or \$var_containing_32768 - open(FILE, $myfile); - $_ = ; -will read a record of no more than 32768 bytes from FILE. If you're not reading from a record-oriented file (or your OS doesn't have record-oriented files), then you'll likely get a full chunk of data with every read. If a record is larger than the record size you've set, you'll get the record back in pieces. -On VMS, record reads are done with the equivalent of sysread, so it's best not to mix record and non-record reads on the same file. (This is unlikely to be a problem, because any file you'd want to read in record mode is probably unusable in line mode.) Non-VMS systems do normal I/O, so it's safe to mix record and non-record reads of a file. -See also "Newlines" in perlport. Also see $.. -autoflush HANDLE EXPR -$OUTPUT_AUTOFLUSH -$| -If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 (regardless of whether the channel is really buffered by the system or not; $| tells you only whether you've asked Perl explicitly to flush after each write). STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe or socket, such as when you are running a Perl program under rsh and want to see the output as it's happening. This has no effect on input buffering. See "getc" in perlfunc for that. (Mnemonic: when you want your pipes to be piping hot.) -output_field_separator HANDLE EXPR -$OUTPUT_FIELD_SEPARATOR -$OFS -$, -The output field separator for the print operator. Ordinarily the print operator simply prints out its arguments without further adornment. To get behavior more like awk, set this variable as you would set awk's OFS variable to specify what is printed between fields. (Mnemonic: what is printed when there is a "," in your print statement.) -output_record_separator HANDLE EXPR -$OUTPUT_RECORD_SEPARATOR -$ORS -$\ -The output record separator for the print operator. Ordinarily the print operator simply prints out its arguments as is, with no trailing newline or other end-of-record string added. To get behavior more like awk, set this variable as you would set awk's ORS variable to specify what is printed at the end of the print. (Mnemonic: you set $\ instead of adding "\n" at the end of the print. Also, it's just like $/, but it's what you get "back" from Perl.) -$LIST_SEPARATOR -$" -This is like $, except that it applies to array and slice values interpolated into a double-quoted string (or similar interpreted string). Default is a space. (Mnemonic: obvious, I think.) -$SUBSCRIPT_SEPARATOR -$SUBSEP -$; -The subscript separator for multidimensional array emulation. If you refer to a hash element as - $foo{$a,$b,$c} -it really means - $foo{join($;, $a, $b, $c)} -But don't put - @foo{$a,$b,$c} # a slice--note the @ -which means - ($foo{$a},$foo{$b},$foo{$c}) -Default is "\034", the same as SUBSEP in awk. If your keys contain binary data there might not be any safe value for $;. (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. Yeah, I know, it's pretty lame, but $, is already taken for something more important.) -Consider using "real" multidimensional arrays as described in perllol. -$OFMT -$# -The output format for printed numbers. This variable is a half-hearted attempt to emulate awk's OFMT variable. There are times, however, when awk and Perl have differing notions of what counts as numeric. The initial value is "%.ng", where n is the value of the macro DBL_DIG from your system's float.h. This is different from awk's default OFMT setting of "%.6g", so you need to set $# explicitly to get awk's value. (Mnemonic: # is the number sign.) -Use of $# is deprecated. -format_page_number HANDLE EXPR -$FORMAT_PAGE_NUMBER -$% -The current page number of the currently selected output channel. Used with formats. (Mnemonic: % is page number in nroff.) -format_lines_per_page HANDLE EXPR -$FORMAT_LINES_PER_PAGE -$= -The current page length (printable lines) of the currently selected output channel. Default is 60. Used with formats. (Mnemonic: = has horizontal lines.) -format_lines_left HANDLE EXPR -$FORMAT_LINES_LEFT -$- -The number of lines left on the page of the currently selected output channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.) -@LAST_MATCH_START -@- -$-[0] is the offset of the start of the last successful match. $-[n] is the offset of the start of the substring matched by n-th subpattern, or undef if the subpattern did not match. -Thus after a match against $_, $& coincides with substr $_, $-[0], $+[0] - $-[0]. Similarly, $n coincides with substr $_, $-[n], $+[n] - $-[n] if $-[n] is defined, and $+ coincides with substr $_, $-[$#-], $+[$#-]. One can use $#- to find the last matched subgroup in the last successful match. Contrast with $#+, the number of subgroups in the regular expression. Compare with @+. -This array holds the offsets of the beginnings of the last successful submatches in the currently active dynamic scope. $-[0] is the offset into the string of the beginning of the entire match. The nth element of this array holds the offset of the nth submatch, so $+[1] is the offset where $1 begins, $+[2] the offset where $2 begins, and so on. You can use $#- to determine how many subgroups were in the last successful match. Compare with the @+ variable. -After a match against some variable $var: -$` is the same as substr($var, 0, $-[0]) -$& is the same as substr($var, $-[0], $+[0] - $-[0]) -$' is the same as substr($var, $+[0]) -$1 is the same as substr($var, $-[1], $+[1] - $-[1]) -$2 is the same as substr($var, $-[2], $+[2] - $-[2]) -$3 is the same as substr $var, $-[3], $+[3] - $-[3]) -format_name HANDLE EXPR -$FORMAT_NAME -$~ -The name of the current report format for the currently selected output channel. Default is the name of the filehandle. (Mnemonic: brother to $^.) -format_top_name HANDLE EXPR -$FORMAT_TOP_NAME -$^ -The name of the current top-of-page format for the currently selected output channel. Default is the name of the filehandle with _TOP appended. (Mnemonic: points to top of page.) -format_line_break_characters HANDLE EXPR -$FORMAT_LINE_BREAK_CHARACTERS -$: -The current set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format. Default is " \n-", to break on whitespace or hyphens. (Mnemonic: a "colon" in poetry is a part of a line.) -format_formfeed HANDLE EXPR -$FORMAT_FORMFEED -$^L -What formats output as a form feed. Default is \f. -$ACCUMULATOR -$^A -The current value of the write() accumulator for format() lines. A format contains formline() calls that put their result into $^A. After calling its format, write() prints out the contents of $^A and empties. So you never really see the contents of $^A unless you call formline() yourself and then look at it. See perlform and "formline()" in perlfunc. -$CHILD_ERROR -$? -The status returned by the last pipe close, backtick (``) command, successful call to wait() or waitpid(), or from the system() operator. This is just the 16-bit status word returned by the wait() system call (or else is made up to look like it). Thus, the exit value of the subprocess is really ($? >> 8), and $? & 127 gives which signal, if any, the process died from, and $? & 128 reports whether there was a core dump. (Mnemonic: similar to sh and ksh.) -Additionally, if the h_errno variable is supported in C, its value is returned via $? if any gethost*() function fails. -If you have installed a signal handler for SIGCHLD, the value of $? will usually be wrong outside that handler. -Inside an END subroutine $? contains the value that is going to be given to exit(). You can modify $? in an END subroutine to change the exit status of your program. For example: - END { - $? = 1 if $? == 255; # die would make it 255 - } -Under VMS, the pragma use vmsish 'status' makes $? reflect the actual VMS exit status, instead of the default emulation of POSIX status. -Also see "Error Indicators". -$OS_ERROR -$ERRNO -$! -If used numerically, yields the current value of the C errno variable, with all the usual caveats. (This means that you shouldn't depend on the value of $! to be anything in particular unless you've gotten a specific error return indicating a system error.) If used an a string, yields the corresponding system error string. You can assign a number to $! to set errno if, for instance, you want "$!" to return the string for error n, or you want to set the exit value for the die() operator. (Mnemonic: What just went bang?) -Also see "Error Indicators". -$EXTENDED_OS_ERROR -$^E -Error information specific to the current operating system. At the moment, this differs from $! under only VMS, OS/2, and Win32 (and for MacPerl). On all other platforms, $^E is always just the same as $!. -Under VMS, $^E provides the VMS status value from the last system error. This is more specific information about the last system error than that provided by $!. This is particularly important when $! is set to EVMSERR. -Under OS/2, $^E is set to the error code of the last call to OS/2 API either via CRT, or directly from perl. -Under Win32, $^E always returns the last error information reported by the Win32 call GetLastError() which describes the last error from within the Win32 API. Most Win32-specific code will report errors via $^E. ANSI C and Unix-like calls set errno and so most portable Perl code will report errors via $!. -Caveats mentioned in the description of $! generally apply to $^E, also. (Mnemonic: Extra error explanation.) -Also see "Error Indicators". -$EVAL_ERROR -$@ -The Perl syntax error message from the last eval() operator. If null, the last eval() parsed and executed correctly (although the operations you invoked may have failed in the normal fashion). (Mnemonic: Where was the syntax error "at"?) -Warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting $SIG{__WARN__} as described below. -Also see "Error Indicators". -$PROCESS_ID -$PID -$$ -The process number of the Perl running this script. You should consider this variable read-only, although it will be altered across fork() calls. (Mnemonic: same as shells.) -$REAL_USER_ID -$UID -$< -The real uid of this process. (Mnemonic: it's the uid you came from, if you're running setuid.) -$EFFECTIVE_USER_ID -$EUID -$> -The effective uid of this process. Example: - $< = $>; # set real to effective uid - ($<,$>) = ($>,$<); # swap real and effective uid -(Mnemonic: it's the uid you went to, if you're running setuid.) $< and $> can be swapped only on machines supporting setreuid(). -$REAL_GROUP_ID -$GID -$( -The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getgid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. -However, a value assigned to $( must be a single number used to set the real gid. So the value given by $( should not be assigned back to $( without being forced numeric, such as by adding zero. -(Mnemonic: parentheses are used to group things. The real gid is the group you left, if you're running setgid.) -$EFFECTIVE_GROUP_ID -$EGID -$) -The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getegid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. -Similarly, a value assigned to $) must also be a space-separated list of numbers. The first number sets the effective gid, and the rest (if any) are passed to setgroups(). To get the effect of an empty list for setgroups(), just repeat the new effective gid; that is, to force an effective gid of 5 and an effectively empty setgroups() list, say $) = "5 5" . -(Mnemonic: parentheses are used to group things. The effective gid is the group that's right for you, if you're running setgid.) -$<, $>, $( and $) can be set only on machines that support the corresponding set[re][ug]id() routine. $( and $) can be swapped only on machines supporting setregid(). -$PROGRAM_NAME -$0 -Contains the name of the program being executed. On some operating systems assigning to $0 modifies the argument area that the ps program sees. This is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as sh and ksh.) -Note for BSD users: setting $0 does not completely remove "perl" from the ps(1) output. For example, setting $0 to "foobar" will result in "perl: foobar (perl)". This is an operating system feature. -$[ -The index of the first element in an array, and of the first character in a substring. Default is 0, but you could theoretically set it to 1 to make Perl behave more like awk (or Fortran) when subscripting and when evaluating the index() and substr() functions. (Mnemonic: [ begins subscripts.) -As of release 5 of Perl, assignment to $[ is treated as a compiler directive, and cannot influence the behavior of any other file. Its use is highly discouraged. -$] -The version + patchlevel / 1000 of the Perl interpreter. This variable can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: Is this version of perl in the right bracket?) Example: - warn "No checksumming!\n" if $] < 3.019; -See also the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old. -The use of this variable is deprecated. The floating point representation can sometimes lead to inaccurate numeric comparisons. See $^V for a more modern representation of the Perl version that allows accurate string comparisons. -$COMPILING -$^C -The current value of the flag associated with the -c switch. Mainly of use with -MO=... to allow code to alter its behavior when being compiled, such as for example to AUTOLOAD at compile time rather than normal, deferred loading. See perlcc. Setting $^C = 1 is similar to calling B::minus_c. -$DEBUGGING -$^D -The current value of the debugging flags. (Mnemonic: value of -D switch.) -$SYSTEM_FD_MAX -$^F -The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails. (Ordinary file descriptors are closed before the open() is attempted.) The close-on-exec status of a file descriptor will be decided according to the value of $^F when the corresponding file, pipe, or socket was opened, not the time of the exec(). -$^H -WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice. -This variable contains compile-time hints for the Perl interpreter. At the end of compilation of a BLOCK the value of this variable is restored to the value when the interpreter started to compile the BLOCK. -When perl begins to parse any block construct that provides a lexical scope (e.g., eval body, required file, subroutine body, loop body, or conditional block), the existing value of $^H is saved, but its value is left unchanged. When the compilation of the block is completed, it regains the saved value. Between the points where its value is saved and restored, code that executes within BEGIN blocks is free to change the value of $^H. -This behavior provides the semantic of lexical scoping, and is used in, for instance, the use strict pragma. -The contents should be an integer; different bits of it are used for different pragmatic flags. Here's an example: - sub add_100 { $^H |= 0x100 } - sub foo { - BEGIN { add_100() } - bar->baz($boon); - } -Consider what happens during execution of the BEGIN block. At this point the BEGIN block has already been compiled, but the body of foo() is still being compiled. The new value of $^H will therefore be visible only while the body of foo() is being compiled. -Substitution of the above BEGIN block with: - BEGIN { require strict; strict->import('vars') } -demonstrates how use strict 'vars' is implemented. Here's a conditional version of the same lexical pragma: - BEGIN { require strict; strict->import('vars') if $condition } -%^H -WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice. -The %^H hash provides the same scoping semantic as $^H. This makes it useful for implementation of lexically scoped pragmas. -$INPLACE_EDIT -$^I -The current value of the inplace-edit extension. Use undef to disable inplace editing. (Mnemonic: value of -i switch.) -$^M -By default, running out of memory is an untrappable, fatal error. However, if suitably built, Perl can use the contents of $^M as an emergency memory pool after die()ing. Suppose that your Perl were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then - $^M = 'a' x (1 << 16); -would allocate a 64K buffer for use in an emergency. See the INSTALL file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced feature, there is no English long name for this variable. -$OSNAME -$^O -The name of the operating system under which this copy of Perl was built, as determined during the configuration process. The value is identical to $Config{'osname'}. See also Config and the -V command-line switch documented in perlrun. -$PERLDB -$^P -The internal variable for debugging support. The meanings of the various bits are subject to change, but currently indicate: -0x01 -Debug subroutine enter/exit. -0x02 -Line-by-line debugging. -0x04 -Switch off optimizations. -0x08 -Preserve more data for future interactive inspections. -0x10 -Keep info about source lines on which a subroutine is defined. -0x20 -Start with single-step on. -0x40 -Use subroutine address instead of name when reporting. -0x80 -Report goto &subroutine as well. -0x100 -Provide informative "file" names for evals based on the place they were compiled. -0x200 -Provide informative names to anonymous subroutines based on the place they were compiled. -Some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change. -$LAST_REGEXP_CODE_RESULT -$^R -The result of evaluation of the last successful (?{ code }) regular expression assertion (see perlre). May be written to. -$EXCEPTIONS_BEING_CAUGHT -$^S -Current state of the interpreter. Undefined if parsing of the current module/eval is not finished (may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers). True if inside an eval(), otherwise false. -$BASETIME -$^T -The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the -M, -A, and -C filetests are based on this value. -$PERL_VERSION -$^V -The revision, version, and subversion of the Perl interpreter, represented as a string composed of characters with those ordinals. Thus in Perl v5.6.0 it equals chr(5) . chr(6) . chr(0) and will return true for $^V eq v5.6.0. Note that the characters in this string value can potentially be in Unicode range. -This can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: use ^V for Version Control.) Example: - warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; -See the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old. -See also $] for an older representation of the Perl version. -$WARNING -$^W -The current value of the warning switch, initially true if -w was used, false otherwise, but directly modifiable. (Mnemonic: related to the -w switch.) See also warnings. -${^WARNING_BITS} -The current set of warning checks enabled by the use warnings pragma. See the documentation of warnings for more details. -${^WIDE_SYSTEM_CALLS} -Global flag that enables system calls made by Perl to use wide character APIs native to the system, if available. This is currently only implemented on the Windows platform. -This can also be enabled from the command line using the -C switch. -The initial value is typically 0 for compatibility with Perl versions earlier than 5.6, but may be automatically set to 1 by Perl if the system provides a user-settable default (e.g., $ENV{LC_CTYPE}). -The bytes pragma always overrides the effect of this flag in the current lexical scope. See bytes. -$EXECUTABLE_NAME -$^X -The name that the Perl binary itself was executed as, from C's argv[0]. This may not be a full pathname, nor even necessarily in your path. -$ARGV -contains the name of the current file when reading from <>. -@ARGV -The array @ARGV contains the command-line arguments intended for the script. $#ARGV is generally the number of arguments minus one, because $ARGV[0] is the first argument, not the program's command name itself. See $0 for the command name. -@INC -The array @INC contains the list of places that the do EXPR, require, or use constructs look for their library files. It initially consists of the arguments to any -I command-line switches, followed by the default Perl library, probably /usr/local/lib/perl, followed by ".", to represent the current directory. If you need to modify this at runtime, you should use the use lib pragma to get the machine-dependent library properly loaded also: - use lib '/mypath/libdir/'; - use SomeMod; -@_ -Within a subroutine the array @_ contains the parameters passed to that subroutine. See perlsub. -%INC -The hash %INC contains entries for each filename included via the do, require, or use operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The require operator uses this hash to determine whether a particular file has already been included. -%ENV -$ENV{expr} -The hash %ENV contains your current environment. Setting a value in ENV changes the environment for any child processes you subsequently fork() off. -%SIG -$SIG{expr} -The hash %SIG contains signal handlers for signals. For example: - sub handler { # 1st argument is signal name - my($sig) = @_; - print "Caught a SIG$sig--shutting down\n"; - close(LOG); - exit(0); - } - $SIG{'INT'} = \&handler; - $SIG{'QUIT'} = \&handler; - ... - $SIG{'INT'} = 'DEFAULT'; # restore default action - $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT -Using a value of 'IGNORE' usually has the effect of ignoring the signal, except for the CHLD signal. See perlipc for more about this special case. -Here are some other examples: - $SIG{"PIPE"} = "Plumber"; # assumes main::Plumber (not recommended) - $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber - $SIG{"PIPE"} = *Plumber; # somewhat esoteric - $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? -Be sure not to use a bareword as the name of a signal handler, lest you inadvertently call it. -If your system has the sigaction() function then signal handlers are installed using it. This means you get reliable signal handling. If your system has the SA_RESTART flag it is used when signals handlers are installed. This means that system calls for which restarting is supported continue rather than returning when a signal arrives. If you want your system calls to be interrupted by signal delivery then do something like this: - use POSIX ':signal_h'; - my $alarm = 0; - sigaction SIGALRM, new POSIX::SigAction sub { $alarm = 1 } - or die "Error setting SIGALRM handler: $!\n"; -See POSIX. -Certain internal hooks can be also set using the %SIG hash. The routine indicated by $SIG{__WARN__} is called when a warning message is about to be printed. The warning message is passed as the first argument. The presence of a __WARN__ hook causes the ordinary printing of warnings to STDERR to be suppressed. You can use this to save warnings in a variable, or turn warnings into fatal errors, like this: - local $SIG{__WARN__} = sub { die $_[0] }; - eval $proggie; -The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __DIE__ hook routine returns, the exception processing continues as it would have in the absence of the hook, unless the hook routine itself exits via a goto, a loop exit, or a die(). The __DIE__ handler is explicitly disabled during the call, so that you can die from a __DIE__ handler. Similarly for __WARN__. -Due to an implementation glitch, the $SIG{__DIE__} hook is called even inside an eval(). Do not use this to rewrite a pending exception in $@, or as a bizarre substitute for overriding CORE::GLOBAL::die(). This strange action at a distance may be fixed in a future release so that $SIG{__DIE__} is only called if your program is about to exit, as was the original intent. Any other use is deprecated. -__DIE__/__WARN__ handlers are very special in one respect: they may be called to report (probable) errors found by the parser. In such a case the parser may be in inconsistent state, so any attempt to evaluate Perl code from such a handler will probably result in a segfault. This means that warnings or errors that result from parsing Perl should be used with extreme caution, like this: - require Carp if defined $^S; - Carp::confess("Something wrong") if defined &Carp::confess; - die "Something wrong, but could not load Carp to give backtrace... - To see backtrace try starting Perl with -MCarp switch"; -Here the first line will load Carp unless it is the parser who called the handler. The second line will print backtrace and die if Carp was available. The third line will be executed only if Carp was not available. -See "die" in perlfunc, "warn" in perlfunc, "eval" in perlfunc, and warnings for additional information. -Error Indicators -The variables $@, $!, $^E, and $? contain information about different types of error conditions that may appear during execution of a Perl program. The variables are shown ordered by the "distance" between the subsystem which reported the error and the Perl process. They correspond to errors detected by the Perl interpreter, C library, operating system, or an external program, respectively. -To illustrate the differences between these variables, consider the following Perl expression, which uses a single-quoted string: - eval q{ - open PIPE, "/cdrom/install |"; - @res = ; - close PIPE or die "bad pipe: $?, $!"; - }; -After execution of this statement all 4 variables may have been set. -$@ is set if the string to be eval-ed did not compile (this may happen if open or close were imported with bad prototypes), or if Perl code executed during evaluation die()d . In these cases the value of $@ is the compile error, or the argument to die (which will interpolate $! and $?!). (See also Fatal, though.) -When the eval() expression above is executed, open(), , and close are translated to calls in the C run-time library and thence to the operating system kernel. $! is set to the C library's errno if one of these calls fails. -Under a few operating systems, $^E may contain a more verbose error indicator, such as in this case, "CDROM tray not closed." Systems that do not support extended error messages leave $^E the same as $!. -Finally, $? may be set to non-0 value if the external program /cdrom/install fails. The upper eight bits reflect specific error conditions encountered by the program (the program's exit() value). The lower eight bits reflect mode of failure, like signal death and core dump information See wait(2) for details. In contrast to $! and $^E, which are set only if error condition is detected, the variable $? is set on each wait or pipe close, overwriting the old value. This is more like $@, which on every eval() is always set on failure and cleared on success. -For more details, see the individual descriptions at $@, $!, $^E, and $?. -Technical Note on the Syntax of Variable Names -Variable names in Perl can have several formats. Usually, they must begin with a letter or underscore, in which case they can be arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence :: or '. In this case, the part before the last :: or ' is taken to be a package qualifier; see perlmod. -Perl variable names may also be a sequence of digits or a single punctuation or control character. These names are all reserved for special uses by Perl; for example, the all-digits names are used to hold data captured by backreferences after a regular expression match. Perl has a special syntax for the single-control-character names: It understands ^X (caret X) to mean the control-X character. For example, the notation $^W (dollar-sign caret W) is the scalar variable whose name is the single character control-W. This is better than typing a literal control-W into your program. -Finally, new in Perl 5.6, Perl variable names may be alphanumeric strings that begin with control characters (or better yet, a caret). These variables must be written in the form ${^Foo}; the braces are not optional. ${^Foo} denotes the scalar variable whose name is a control-F followed by two o's. These variables are reserved for future special uses by Perl, except for the ones that begin with ^_ (control-underscore or caret-underscore). No control-character name that begins with ^_ will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. $^_ itself, however, is reserved. -Perl identifiers that begin with digits, control characters, or punctuation characters are exempt from the effects of the package declaration and are always forced to be in package main. A few other names are also exempt: - ENV STDIN - INC STDOUT - ARGV STDERR - ARGVOUT - SIG -In particular, the new special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope. -BUGS -Due to an unfortunate accident of Perl's implementation, use English imposes a considerable performance penalty on all regular expression matches in a program, regardless of whether they occur in the scope of use English. For that reason, saying use English in libraries is strongly discouraged. See the Devel::SawAmpersand module documentation from CPAN (http://www.perl.com/CPAN/modules/by-module/Devel/) for more information. -Having to even think about the $^S variable in your exception handlers is simply wrong. $SIG{__DIE__} as currently implemented invites grievous and difficult to track down errors. Avoid it and use an END{} or CORE::GLOBAL::die override instead. -- cgit v1.2.1