Perl pod documentation

Short Table of Contents

Table of Contents

Next: , Up: (dir)   [Contents]

Perl pod documentation

This translation of the Perl documentation (http://perldoc.perl.org) from POD to Texinfo is not official, and not endorsed by the Perl developers (indeed, they haven’t seen it). It was created by the GNU Texinfo developers because they found it useful to have the Perl documentation available in Info and other formats, and thought they would share the results. Suggestions welcome.

This is created entirely by the Texinfo tools; see the contrib/perldoc-all directory in the Texinfo sources for the procedure used. The output is available at http://www.gnu.org/software/perl/manual.

• perl:  
• perlapio:  
• perlartistic:  
• perlbook:  
• perlboot:  
• perlbot:  
• perlcall:  
• perlcheat:  
• perlclib:  
• perlcommunity:  
• perldata:  
• perldbmfilter:  
• perldebguts:  
• perldebtut:  
• NAME debug debugger:  
• perldiag:  
• NAME data structure complex data structure struct:  
• perldtrace:  
• perlebcdic:  
• perlembed:  
• perlexperiment:  
• perlfilter:  
• perlfork:  
• NAME format report chart:  
• NAME function:  
• perlgit:  
• perlgpl:  
• perlguts:  
• perlhack:  
• perlhacktips:  
• perlhacktut:  
• perlhist:  
• perlinterp:  
• perlintro:  
• perliol:  
• perlipc:  
• NAME warning, lexical warnings warning:  
• perllocale:  
• perllol:  
• perlmod:  
• perlmodinstall:  
• perlmodstyle:  
• perlmroapi:  
• perlnewmod:  
• perlnumber:  
• NAME object OOP:  
• perlootut:  
• NAME operator:  
• perlopentut:  
• perlpacktut:  
• perlperf:  
• NAME POD plain old documentation:  
• perlpodspec:  
• perlpodstyle:  
• perlpolicy:  
• perlport:  
• perlpragma:  
• NAME regular expression regex regexp:  
• perlreapi:  
• perlrebackslash:  
• NAME character class:  
• NAME reference pointer data structure structure struct:  
• perlreftut:  
• perlreguts:  
• perlrequick:  
• perlreref:  
• perlretut:  
• perlrun:  
• perlsec:  
• perlsource:  
• perlstyle:  
• NAME subroutine function:  
• NAME syntax:  
• perlthrtut:  
• NAME tie:  
• perltodo:  
• perltooc:  
• perltoot:  
• perltrap:  
• perlunicode:  
• perlunifaq:  
• perluniintro:  
• perlunitut:  
• perlutil:  
• perlvar:  
• perlvms:   
 — The Detailed Node Listing —

perl


• perl NAME:  



• perl SYNOPSIS:  



• perl GETTING HELP:  



• perl DESCRIPTION:  



• perl AVAILABILITY:  



• perl ENVIRONMENT:  



• perl AUTHOR:  



• perl FILES:  



• perl SEE ALSO:  



• perl DIAGNOSTICS:  



• perl BUGS:  



• perl NOTES:  



GETTING HELP


• perl Overview:  



• perl Tutorials:  



• perl Reference Manual:  



• perl Internals and C Language Interface:  



• perl Miscellaneous:  



• perl Language-Specific:  



• perl Platform-Specific:  



• perl Stubs for Deleted Documents:  



perlapio


• perlapio NAME:  



• perlapio SYNOPSIS:  



• perlapio DESCRIPTION:  



DESCRIPTION


• perlapio Co-existence with stdio:  



• perlapio "Fast gets" Functions:  



• perlapio Other Functions:  



perlartistic


• perlartistic NAME:  



• perlartistic SYNOPSIS:  



• perlartistic DESCRIPTION:  



• perlartistic The "Artistic License":  



The "Artistic License"


• perlartistic Preamble:  



• perlartistic Definitions:  



• perlartistic Conditions:  



perlbook


• perlbook NAME:  



• perlbook DESCRIPTION:  



DESCRIPTION


• perlbook The most popular books:  



• perlbook References:  



• perlbook Tutorials:  



• perlbook Task-Oriented:  



• perlbook Special Topics:  



• perlbook Free (as in beer) books:  



• perlbook Other interesting, non-Perl books:  



• perlbook A note on freshness:  



• perlbook Get your book listed:  



perlboot


• perlboot NAME:  



• perlboot DESCRIPTION:  



perlbot


• perlbot NAME:  



• perlbot DESCRIPTION:  



perlcall


• perlcall NAME:  



• perlcall DESCRIPTION:  



• perlcall THE CALL_ FUNCTIONS:  



• perlcall FLAG VALUES:  



• perlcall EXAMPLES:  



• perlcall LIGHTWEIGHT CALLBACKS:  



• perlcall SEE ALSO:  



• perlcall AUTHOR:  



• perlcall DATE:  



FLAG VALUES


• perlcall G_VOID:  



• perlcall G_SCALAR:  



• perlcall G_ARRAY:  



• perlcall G_DISCARD:  



• perlcall G_NOARGS:  



• perlcall G_EVAL:  



• perlcall G_KEEPERR:  



• perlcall Determining the Context:  



EXAMPLES


• perlcall No Parameters, Nothing Returned:  



• perlcall Passing Parameters:  



• perlcall Returning a Scalar:  



• perlcall Returning a List of Values:  



• perlcall Returning a List in a Scalar Context:  



• perlcall Returning Data from Perl via the Parameter List:  



• perlcall Using G_EVAL:  



• perlcall Using G_KEEPERR:  



• perlcall Using call_sv:  



• perlcall Using call_argv:  



• perlcall Using call_method:  



• perlcall Using GIMME_V:  



• perlcall Using Perl to Dispose of Temporaries:  



• perlcall Strategies for Storing Callback Context Information:  



• perlcall Alternate Stack Manipulation:  



• perlcall Creating and Calling an Anonymous Subroutine in C:  



perlcheat


• perlcheat NAME:  



• perlcheat DESCRIPTION:  



• perlcheat ACKNOWLEDGEMENTS:  



• perlcheat AUTHOR:  



• perlcheat SEE ALSO:  



DESCRIPTION


• perlcheat The sheet:  



perlclib


• perlclib NAME:  



• perlclib DESCRIPTION:  



• perlclib SEE ALSO:  



DESCRIPTION


• perlclib Conventions:  



• perlclib File Operations:  



• perlclib File Input and Output:  



• perlclib File Positioning:  



• perlclib Memory Management and String Handling:  



• perlclib Character Class Tests:  



• perlclib stdlib.h functions:  



• perlclib Miscellaneous functions:  



perlcommunity


• perlcommunity NAME:  



• perlcommunity DESCRIPTION:  



• perlcommunity AUTHOR:  



DESCRIPTION


• perlcommunity Where to Find the Community:  



• perlcommunity Mailing Lists and Newsgroups:  



• perlcommunity IRC:  



• perlcommunity Websites:  



• perlcommunity User Groups:  



• perlcommunity Workshops:  



• perlcommunity Hackathons:  



• perlcommunity Conventions:  



• perlcommunity Calendar of Perl Events:  



Websites


• perlcommunity News sites:  



• perlcommunity Forums:  



perldata


• perldata NAME:  



• perldata DESCRIPTION:  



• perldata SEE ALSO:  



DESCRIPTION


• perldata Variable names:  



• perldata Context:  



• perldata Scalar values:  



• perldata Scalar value constructors:  



• perldata List value constructors:  



• perldata Subscripts:  



• perldata Multi-dimensional array emulation:  



• perldata Slices:  



• perldata Typeglobs and Filehandles:  



Scalar value constructors


• perldata Version Strings:  



• perldata Special Literals:  



• perldata Barewords:  



• perldata Array Interpolation:  



perldbmfilter


• perldbmfilter NAME:  



• perldbmfilter SYNOPSIS:  



• perldbmfilter DESCRIPTION:  



• perldbmfilter SEE ALSO:  



• perldbmfilter AUTHOR:  



DESCRIPTION


• perldbmfilter The Filter:  



• perldbmfilter An Example: the NULL termination problem.:  



• perldbmfilter Another Example: Key is a C int.:  



perldebguts


• perldebguts NAME:  



• perldebguts DESCRIPTION:  



• perldebguts Debugger Internals:  



• perldebguts Frame Listing Output Examples:  



• perldebguts Debugging Regular Expressions:  



• perldebguts Debugging Perl Memory Usage:  



• perldebguts SEE ALSO:  



Debugger Internals


• perldebguts Writing Your Own Debugger:  



Writing Your Own Debugger


• perldebguts Environment Variables:  



• perldebguts Debugger Internal Variables:  



• perldebguts Debugger Customization Functions:  



Debugging Regular Expressions


• perldebguts Compile-time Output:  



• perldebguts Types of Nodes:  



• perldebguts Run-time Output:  



Debugging Perl Memory Usage


• perldebguts Using $ENV{PERL_DEBUG_MSTATS}:  



perldebtut


• perldebtut NAME:  



• perldebtut DESCRIPTION:  



• perldebtut use strict:  



• perldebtut Looking at data and -w and v:  



• perldebtut help:  



• perldebtut Stepping through code:  



• perldebtut Placeholder for a, w, t, T:  



• perldebtut REGULAR EXPRESSIONS:  



• perldebtut OUTPUT TIPS:  



• perldebtut CGI:  



• perldebtut GUIs:  



• perldebtut SUMMARY:  



• perldebtut SEE ALSO:  



• perldebtut AUTHOR:  



• perldebtut CONTRIBUTORS:  



NAME debug debugger


• NAME debug debugger NAME:  



• NAME debug debugger DESCRIPTION:  



• NAME debug debugger The Perl Debugger:  



• NAME debug debugger Debugging Regular Expressions:  



• NAME debug debugger Debugging Memory Usage:  



• NAME debug debugger SEE ALSO:  



• NAME debug debugger BUGS:  



The Perl Debugger


• NAME debug debugger Calling the Debugger:  



• NAME debug debugger Debugger Commands:  



• NAME debug debugger Configurable Options:  



• NAME debug debugger Debugger Input/Output:  



• NAME debug debugger Debugging Compile-Time Statements:  



• NAME debug debugger Debugger Customization:  



• NAME debug debugger Readline Support / History in the Debugger:  



• NAME debug debugger Editor Support for Debugging:  



• NAME debug debugger The Perl Profiler:  



perldiag


• perldiag NAME:  



• perldiag DESCRIPTION:  



• perldiag SEE ALSO:  



NAME data structure complex data structure struct


• NAME data structure complex data structure struct NAME:  



• NAME data structure complex data structure struct DESCRIPTION:  



• NAME data structure complex data structure struct REFERENCES:  



• NAME data structure complex data structure struct COMMON MISTAKES:  



• NAME data structure complex data structure struct CAVEAT ON PRECEDENCE:  



• NAME data structure complex data structure struct WHY YOU SHOULD ALWAYS use strict:  



• NAME data structure complex data structure struct DEBUGGING:  



• NAME data structure complex data structure struct CODE EXAMPLES:  



• NAME data structure complex data structure struct ARRAYS OF ARRAYS:  



• NAME data structure complex data structure struct HASHES OF ARRAYS:  



• NAME data structure complex data structure struct ARRAYS OF HASHES:  



• NAME data structure complex data structure struct HASHES OF HASHES:  



• NAME data structure complex data structure struct MORE ELABORATE RECORDS:  



• NAME data structure complex data structure struct Database Ties:  



• NAME data structure complex data structure struct SEE ALSO:  



• NAME data structure complex data structure struct AUTHOR:  



ARRAYS OF ARRAYS


• NAME data structure complex data structure struct Declaration of an ARRAY OF ARRAYS:  



• NAME data structure complex data structure struct Generation of an ARRAY OF ARRAYS:  



• NAME data structure complex data structure struct Access and Printing of an ARRAY OF ARRAYS:  



HASHES OF ARRAYS


• NAME data structure complex data structure struct Declaration of a HASH OF ARRAYS:  



• NAME data structure complex data structure struct Generation of a HASH OF ARRAYS:  



• NAME data structure complex data structure struct Access and Printing of a HASH OF ARRAYS:  



ARRAYS OF HASHES


• NAME data structure complex data structure struct Declaration of an ARRAY OF HASHES:  



• NAME data structure complex data structure struct Generation of an ARRAY OF HASHES:  



• NAME data structure complex data structure struct Access and Printing of an ARRAY OF HASHES:  



HASHES OF HASHES


• NAME data structure complex data structure struct Declaration of a HASH OF HASHES:  



• NAME data structure complex data structure struct Generation of a HASH OF HASHES:  



• NAME data structure complex data structure struct Access and Printing of a HASH OF HASHES:  



MORE ELABORATE RECORDS


• NAME data structure complex data structure struct Declaration of MORE ELABORATE RECORDS:  



• NAME data structure complex data structure struct Declaration of a HASH OF COMPLEX RECORDS:  



• NAME data structure complex data structure struct Generation of a HASH OF COMPLEX RECORDS:  



perldtrace


• perldtrace NAME:  



• perldtrace SYNOPSIS:  



• perldtrace DESCRIPTION:  



• perldtrace HISTORY:  



• perldtrace PROBES:  



• perldtrace EXAMPLES:  



• perldtrace REFERENCES:  



• perldtrace AUTHORS:  



perlebcdic


• perlebcdic NAME:  



• perlebcdic DESCRIPTION:  



• perlebcdic COMMON CHARACTER CODE SETS:  



• perlebcdic SINGLE OCTET TABLES:  



• perlebcdic IDENTIFYING CHARACTER CODE SETS:  



• perlebcdic CONVERSIONS:  



• perlebcdic OPERATOR DIFFERENCES:  



• perlebcdic FUNCTION DIFFERENCES:  



• perlebcdic REGULAR EXPRESSION DIFFERENCES:  



• perlebcdic SOCKETS:  



• perlebcdic SORTING:  



• perlebcdic TRANSFORMATION FORMATS:  



• perlebcdic Hashing order and checksums:  



• perlebcdic I18N AND L10N:  



• perlebcdic MULTI-OCTET CHARACTER SETS:  



• perlebcdic OS ISSUES:  



• perlebcdic BUGS:  



• perlebcdic SEE ALSO:  



• perlebcdic REFERENCES:  



• perlebcdic HISTORY:  



• perlebcdic AUTHOR:  



COMMON CHARACTER CODE SETS


• perlebcdic ASCII:  



• perlebcdic ISO 8859:  



• perlebcdic Latin 1 (ISO 8859-1):  



• perlebcdic EBCDIC:  



• perlebcdic The 13 variant characters:  



• perlebcdic 0037:  



• perlebcdic 1047:  



• perlebcdic POSIX-BC:  



• perlebcdic Unicode code points versus EBCDIC code points:  



• perlebcdic Remaining Perl Unicode problems in EBCDIC:  



• perlebcdic Unicode and UTF:  



• perlebcdic Using Encode:  



CONVERSIONS


• perlebcdic tr///:  



• perlebcdic iconv:  



• perlebcdic C RTL:  



SORTING


• perlebcdic Ignore ASCII vs. EBCDIC sort differences.:  



• perlebcdic MONO CASE then sort data.:  



• perlebcdic Convert, sort data, then re convert.:  



• perlebcdic Perform sorting on one type of platform only.:  



TRANSFORMATION FORMATS


• perlebcdic URL decoding and encoding:  



• perlebcdic uu encoding and decoding:  



• perlebcdic Quoted-Printable encoding and decoding:  



• perlebcdic Caesarean ciphers:  



OS ISSUES


• perlebcdic OS/400:  



• perlebcdic OS/390, z/OS:  



• perlebcdic VM/ESA?:  



• perlebcdic POSIX-BC?:  



perlembed


• perlembed NAME:  



• perlembed DESCRIPTION:  



• perlembed Hiding Perl_:  



• perlembed MORAL:  



• perlembed AUTHOR:  



• perlembed COPYRIGHT:  



DESCRIPTION


• perlembed PREAMBLE:  



• perlembed ROADMAP:  



• perlembed Compiling your C program:  



• perlembed Adding a Perl interpreter to your C program:  



• perlembed Calling a Perl subroutine from your C program:  



• perlembed Evaluating a Perl statement from your C program:  



• perlembed Performing Perl pattern matches and substitutions from your C program:  



• perlembed Fiddling with the Perl stack from your C program:  



• perlembed Maintaining a persistent interpreter:  



• perlembed Execution of END blocks:  



• perlembed $0 assignments:  



• perlembed Maintaining multiple interpreter instances:  



• perlembed Using Perl modules, which themselves use C libraries, from your C program:  



perlexperiment


• perlexperiment NAME:  



• perlexperiment DESCRIPTION:  



• perlexperiment AUTHORS:  



• perlexperiment COPYRIGHT:  



• perlexperiment LICENSE:  



DESCRIPTION


• perlexperiment Current experiments:  



• perlexperiment Accepted features:  



• perlexperiment Removed features:  



perlfilter


• perlfilter NAME:  



• perlfilter DESCRIPTION:  



• perlfilter CONCEPTS:  



• perlfilter USING FILTERS:  



• perlfilter WRITING A SOURCE FILTER:  



• perlfilter WRITING A SOURCE FILTER IN C:  



• perlfilter CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE:  



• perlfilter WRITING A SOURCE FILTER IN PERL:  



• perlfilter USING CONTEXT: THE DEBUG FILTER:  



• perlfilter CONCLUSION:  



• perlfilter THINGS TO LOOK OUT FOR:  



• perlfilter REQUIREMENTS:  



• perlfilter AUTHOR:  



• perlfilter Copyrights:  



perlfork


• perlfork NAME:  



• perlfork SYNOPSIS:  



• perlfork DESCRIPTION:  



• perlfork CAVEATS AND LIMITATIONS:  



• perlfork PORTABILITY CAVEATS:  



• perlfork BUGS:  



• perlfork AUTHOR:  



• perlfork SEE ALSO:  



DESCRIPTION


• perlfork Behavior of other Perl features in forked pseudo-processes:  



• perlfork Resource limits:  



• perlfork Killing the parent process:  



• perlfork Lifetime of the parent process and pseudo-processes:  



NAME format report chart


• NAME format report chart NAME:  



• NAME format report chart DESCRIPTION:  



• NAME format report chart NOTES:  



• NAME format report chart WARNINGS:  



DESCRIPTION


• NAME format report chart Text Fields:  



• NAME format report chart Numeric Fields:  



• NAME format report chart The Field @* for Variable-Width Multi-Line Text:  



• NAME format report chart The Field ^* for Variable-Width One-line-at-a-time Text:  



• NAME format report chart Specifying Values:  



• NAME format report chart Using Fill Mode:  



• NAME format report chart Suppressing Lines Where All Fields Are Void:  



• NAME format report chart Repeating Format Lines:  



• NAME format report chart Top of Form Processing:  



• NAME format report chart Format Variables:  



NOTES


• NAME format report chart Footers:  



• NAME format report chart Accessing Formatting Internals:  



NAME function


• NAME function NAME:  



• NAME function DESCRIPTION:  



DESCRIPTION


• NAME function Perl Functions by Category:  



• NAME function Portability:  



• NAME function Alphabetical Listing of Perl Functions:  



• NAME function Non-function Keywords by Cross-reference:  



Non-function Keywords by Cross-reference


• NAME function perldata:  



• NAME function perlmod:  



• NAME function perlobj:  



• NAME function perlop:  



• NAME function perlsub:  



• NAME function perlsyn:  



perlgit


• perlgit NAME:  



• perlgit DESCRIPTION:  



• perlgit CLONING THE REPOSITORY:  



• perlgit WORKING WITH THE REPOSITORY:  



• perlgit Topic branches and rewriting history:  



• perlgit WRITE ACCESS TO THE GIT REPOSITORY:  



• perlgit Accepting a patch:  



WORKING WITH THE REPOSITORY


• perlgit Finding out your status:  



• perlgit Patch workflow:  



• perlgit Committing your changes:  



• perlgit Using git to send patch emails:  



• perlgit A note on derived files:  



• perlgit Cleaning a working directory:  



• perlgit Bisecting:  



Topic branches and rewriting history


• perlgit Grafts:  



Accepting a patch


• perlgit Committing to blead:  



• perlgit Committing to maintenance versions:  



• perlgit Merging from a branch via GitHub:  



• perlgit A note on camel and dromedary:  



Committing to blead


• perlgit On merging and rebasing:  



perlgpl


• perlgpl NAME:  



• perlgpl SYNOPSIS:  



• perlgpl DESCRIPTION:  



• perlgpl GNU GENERAL PUBLIC LICENSE:  



perlguts


• perlguts NAME:  



• perlguts DESCRIPTION:  



• perlguts Variables:  



• perlguts Subroutines:  



• perlguts Compiled code:  



• perlguts Examining internal data structures with the dump functions:  



• perlguts How multiple interpreters and concurrency are supported:  



• perlguts Internal Functions:  



• perlguts Unicode Support:  



• perlguts Custom Operators:  



• perlguts AUTHORS:  



• perlguts SEE ALSO:  



Variables


• perlguts Datatypes:  



• perlguts What is an "IV"?:  



• perlguts Working with SVs:  



• perlguts Offsets:  



• perlguts What's Really Stored in an SV?:  



• perlguts Working with AVs:  



• perlguts Working with HVs:  



• perlguts Hash API Extensions:  



• perlguts AVs, HVs and undefined values:  



• perlguts References:  



• perlguts Blessed References and Class Objects:  



• perlguts Creating New Variables:  



• perlguts Reference Counts and Mortality:  



• perlguts Stashes and Globs:  



• perlguts Double-Typed SVs:  



• perlguts Magic Variables:  



• perlguts Assigning Magic:  



• perlguts Magic Virtual Tables:  



• perlguts Finding Magic:  



• perlguts Understanding the Magic of Tied Hashes and Arrays:  



• perlguts Localizing changes:  



Subroutines


• perlguts XSUBs and the Argument Stack:  



• perlguts Autoloading with XSUBs:  



• perlguts Calling Perl Routines from within C Programs:  



• perlguts Memory Allocation:  



• perlguts PerlIO:  



• perlguts Putting a C value on Perl stack:  



• perlguts Scratchpads:  



• perlguts Scratchpads and recursion:  



Memory Allocation


• perlguts Allocation:  



• perlguts Reallocation:  



• perlguts Moving:  



Compiled code


• perlguts Code tree:  



• perlguts Examining the tree:  



• perlguts Compile pass 1: check routines:  



• perlguts Compile pass 1a: constant folding:  



• perlguts Compile pass 2: context propagation:  



• perlguts Compile pass 3: peephole optimization:  



• perlguts Pluggable runops:  



• perlguts Compile-time scope hooks:  



How multiple interpreters and concurrency are supported


• perlguts Background and PERL_IMPLICIT_CONTEXT:  



• perlguts So what happened to dTHR?:  



• perlguts How do I use all this in extensions?:  



• perlguts Should I do anything special if I call perl from multiple threads?:  



• perlguts Future Plans and PERL_IMPLICIT_SYS:  



Internal Functions


• perlguts Formatted Printing of IVs, UVs, and NVs:  



• perlguts Pointer-To-Integer and Integer-To-Pointer:  



• perlguts Exception Handling:  



• perlguts Source Documentation:  



• perlguts Backwards compatibility:  



Unicode Support


• perlguts What is Unicode, anyway?:  



• perlguts How can I recognise a UTF-8 string?:  



• perlguts How does UTF-8 represent Unicode characters?:  



• perlguts How does Perl store UTF-8 strings?:  



• perlguts How do I convert a string to UTF-8?:  



• perlguts Is there anything else I need to know?:  



perlhack


• perlhack NAME:  



• perlhack DESCRIPTION:  



• perlhack SUPER QUICK PATCH GUIDE:  



• perlhack BUG REPORTING:  



• perlhack PERL 5 PORTERS:  



• perlhack GETTING THE PERL SOURCE:  



• perlhack PATCHING PERL:  



• perlhack TESTING:  



• perlhack MORE READING FOR GUTS HACKERS:  



• perlhack CPAN TESTERS AND PERL SMOKERS:  



• perlhack WHAT NEXT?:  



• perlhack AUTHOR:  



PERL 5 PORTERS


• perlhack perl-changes mailing list:  



• perlhack #p5p on IRC:  



GETTING THE PERL SOURCE


• perlhack Read access via Git:  



• perlhack Read access via the web:  



• perlhack Read access via rsync:  



• perlhack Write access via git:  



PATCHING PERL


• perlhack Submitting patches:  



• perlhack Getting your patch accepted:  



• perlhack Patching a core module:  



• perlhack Updating perldelta:  



• perlhack What makes for a good patch?:  



Getting your patch accepted


• perlhack Patch style:  



• perlhack Commit message:  



• perlhack Comments, Comments, Comments:  



• perlhack Style:  



• perlhack Test suite:  



What makes for a good patch?


• perlhack Does the concept match the general goals of Perl?:  



• perlhack Where is the implementation?:  



• perlhack Backwards compatibility:  



• perlhack Could it be a module instead?:  



• perlhack Is the feature generic enough?:  



• perlhack Does it potentially introduce new bugs?:  



• perlhack How big is it?:  



• perlhack Does it preclude other desirable features?:  



• perlhack Is the implementation robust?:  



• perlhack Is the implementation generic enough to be portable?:  



• perlhack Is the implementation tested?:  



• perlhack Is there enough documentation?:  



• perlhack Is there another way to do it?:  



• perlhack Does it create too much work?:  



• perlhack Patches speak louder than words:  



TESTING


• perlhack Special make test targets:  



• perlhack Parallel tests:  



• perlhack Running tests by hand:  



• perlhack Using t/harness for testing:  



Using t/harness for testing


• perlhack Other environment variables that may influence tests:  



WHAT NEXT?


• perlhack "The Road goes ever on and on, down from the door where it began.":  



• perlhack Metaphoric Quotations:  



perlhacktips


• perlhacktips NAME:  



• perlhacktips DESCRIPTION:  



• perlhacktips COMMON PROBLEMS:  



• perlhacktips DEBUGGING:  



• perlhacktips SOURCE CODE STATIC ANALYSIS:  



• perlhacktips MEMORY DEBUGGERS:  



• perlhacktips PROFILING:  



• perlhacktips MISCELLANEOUS TRICKS:  



• perlhacktips AUTHOR:  



COMMON PROBLEMS


• perlhacktips Perl environment problems:  



• perlhacktips Portability problems:  



• perlhacktips Problematic System Interfaces:  



• perlhacktips Security problems:  



DEBUGGING


• perlhacktips Poking at Perl:  



• perlhacktips Using a source-level debugger:  



• perlhacktips gdb macro support:  



• perlhacktips Dumping Perl Data Structures:  



SOURCE CODE STATIC ANALYSIS


• perlhacktips lint, splint:  



• perlhacktips Coverity:  



• perlhacktips cpd (cut-and-paste detector):  



• perlhacktips gcc warnings:  



• perlhacktips Warnings of other C compilers:  



MEMORY DEBUGGERS


• perlhacktips Rational Software's Purify:  



• perlhacktips valgrind:  



Rational Software’s Purify


• perlhacktips Purify on Unix:  



• perlhacktips Purify on NT:  



PROFILING


• perlhacktips Gprof Profiling:  



• perlhacktips GCC gcov Profiling:  



MISCELLANEOUS TRICKS


• perlhacktips PERL_DESTRUCT_LEVEL:  



• perlhacktips PERL_MEM_LOG:  



• perlhacktips DDD over gdb:  



• perlhacktips Poison:  



• perlhacktips Read-only optrees:  



• perlhacktips The .i Targets:  



perlhacktut


• perlhacktut NAME:  



• perlhacktut DESCRIPTION:  



• perlhacktut EXAMPLE OF A SIMPLE PATCH:  



• perlhacktut AUTHOR:  



EXAMPLE OF A SIMPLE PATCH


• perlhacktut Writing the patch:  



• perlhacktut Testing the patch:  



• perlhacktut Documenting the patch:  



• perlhacktut Submit:  



perlhist


• perlhist NAME:  



• perlhist DESCRIPTION:  



• perlhist INTRODUCTION:  



• perlhist THE KEEPERS OF THE PUMPKIN:  



• perlhist THE RECORDS:  



• perlhist THE KEEPERS OF THE RECORDS:  



THE KEEPERS OF THE PUMPKIN


• perlhist PUMPKIN?:  



THE RECORDS


• perlhist SELECTED RELEASE SIZES:  



• perlhist SELECTED PATCH SIZES:  



SELECTED PATCH SIZES


• perlhist The patch-free era:  



perlinterp


• perlinterp NAME:  



• perlinterp DESCRIPTION:  



• perlinterp ELEMENTS OF THE INTERPRETER:  



• perlinterp OP TREES:  



• perlinterp STACKS:  



• perlinterp MILLIONS OF MACROS:  



• perlinterp FURTHER READING:  



ELEMENTS OF THE INTERPRETER


• perlinterp Startup:  



• perlinterp Parsing:  



• perlinterp Optimization:  



• perlinterp Running:  



• perlinterp Exception handing:  



• perlinterp INTERNAL VARIABLE TYPES:  



STACKS


• perlinterp Argument stack:  



• perlinterp Mark stack:  



• perlinterp Save stack:  



perlintro


• perlintro NAME:  



• perlintro DESCRIPTION:  



• perlintro AUTHOR:  



DESCRIPTION


• perlintro What is Perl?:  



• perlintro Running Perl programs:  



• perlintro Safety net:  



• perlintro Basic syntax overview:  



• perlintro Perl variable types:  



• perlintro Variable scoping:  



• perlintro Conditional and looping constructs:  



• perlintro Builtin operators and functions:  



• perlintro Files and I/O:  



• perlintro Regular expressions:  



• perlintro Writing subroutines:  



• perlintro OO Perl:  



• perlintro Using Perl modules:  



perliol


• perliol NAME:  



• perliol SYNOPSIS:  



• perliol DESCRIPTION:  



• perliol TODO:  



DESCRIPTION


• perliol History and Background:  



• perliol Basic Structure:  



• perliol Layers vs Disciplines:  



• perliol Data Structures:  



• perliol Functions and Attributes:  



• perliol Per-instance Data:  



• perliol Layers in action.:  



• perliol Per-instance flag bits:  



• perliol Methods in Detail:  



• perliol Utilities:  



• perliol Implementing PerlIO Layers:  



• perliol Core Layers:  



• perliol Extension Layers:  



perlipc


• perlipc NAME:  



• perlipc DESCRIPTION:  



• perlipc Signals:  



• perlipc Named Pipes:  



• perlipc Using open() for IPC:  



• perlipc Sockets: Client/Server Communication:  



• perlipc TCP Clients with IO::Socket:  



• perlipc TCP Servers with IO::Socket:  



• perlipc UDP: Message Passing:  



• perlipc SysV IPC:  



• perlipc NOTES:  



• perlipc BUGS:  



• perlipc AUTHOR:  



• perlipc SEE ALSO:  



Signals


• perlipc Handling the SIGHUP Signal in Daemons:  



• perlipc Deferred Signals (Safe Signals):  



Using open() for IPC


• perlipc Filehandles:  



• perlipc Background Processes:  



• perlipc Complete Dissociation of Child from Parent:  



• perlipc Safe Pipe Opens:  



• perlipc Avoiding Pipe Deadlocks:  



• perlipc Bidirectional Communication with Another Process:  



• perlipc Bidirectional Communication with Yourself:  



Sockets: Client/Server Communication


• perlipc Internet Line Terminators:  



• perlipc Internet TCP Clients and Servers:  



• perlipc Unix-Domain TCP Clients and Servers:  



TCP Clients with IO::Socket


• perlipc A Simple Client:  



• perlipc A Webget Client:  



• perlipc Interactive Client with IO::Socket:  



NAME warning, lexical warnings warning


• NAME warning, lexical warnings warning NAME:  



• NAME warning, lexical warnings warning DESCRIPTION:  



• NAME warning, lexical warnings warning SEE ALSO:  



• NAME warning, lexical warnings warning AUTHOR:  



DESCRIPTION


• NAME warning, lexical warnings warning Default Warnings and Optional Warnings:  



• NAME warning, lexical warnings warning What's wrong with -w and $^W:  



• NAME warning, lexical warnings warning Controlling Warnings from the Command Line:  



• NAME warning, lexical warnings warning Backward Compatibility:  



• NAME warning, lexical warnings warning Category Hierarchy:  



• NAME warning, lexical warnings warning Fatal Warnings:  



• NAME warning, lexical warnings warning Reporting Warnings from a Module:  



perllocale


• perllocale NAME:  



• perllocale DESCRIPTION:  



• perllocale WHAT IS A LOCALE:  



• perllocale PREPARING TO USE LOCALES:  



• perllocale USING LOCALES:  



• perllocale LOCALE CATEGORIES:  



• perllocale SECURITY:  



• perllocale ENVIRONMENT:  



• perllocale NOTES:  



• perllocale Unicode and UTF-8:  



• perllocale BUGS:  



• perllocale SEE ALSO:  



• perllocale HISTORY:  



USING LOCALES


• perllocale The use locale pragma:  



• perllocale The setlocale function:  



• perllocale Finding locales:  



• perllocale LOCALE PROBLEMS:  



• perllocale Temporarily fixing locale problems:  



• perllocale Permanently fixing locale problems:  



• perllocale Permanently fixing your system's locale configuration:  



• perllocale Fixing system locale configuration:  



• perllocale The localeconv function:  



• perllocale I18N::Langinfo:  



LOCALE CATEGORIES


• perllocale Category LC_COLLATE: Collation 1:  



• perllocale Category LC_CTYPE: Character Types 1:  



• perllocale Category LC_NUMERIC: Numeric Formatting:  



• perllocale Category LC_MONETARY: Formatting of monetary amounts 1:  



• perllocale LC_TIME:  



• perllocale Other categories:  



ENVIRONMENT


• perllocale Examples:  



NOTES


• perllocale Backward compatibility:  



• perllocale I18N:Collate obsolete:  



• perllocale Sort speed and memory use impacts:  



• perllocale write() and LC_NUMERIC:  



• perllocale Freely available locale definitions:  



• perllocale I18n and l10n:  



• perllocale An imperfect standard:  



BUGS


• perllocale Broken systems:  



perllol


• perllol NAME:  



• perllol DESCRIPTION:  



• perllol SEE ALSO:  



• perllol AUTHOR:  



DESCRIPTION


• perllol Declaration and Access of Arrays of Arrays:  



• perllol Growing Your Own:  



• perllol Access and Printing:  



• perllol Slices:  



perlmod


• perlmod NAME:  



• perlmod DESCRIPTION:  



• perlmod SEE ALSO:  



DESCRIPTION


• perlmod Packages:  



• perlmod Symbol Tables:  



• perlmod BEGIN, UNITCHECK, CHECK, INIT and END:  



• perlmod Perl Classes:  



• perlmod Perl Modules:  



• perlmod Making your module threadsafe:  



perlmodinstall


• perlmodinstall NAME:  



• perlmodinstall DESCRIPTION:  



• perlmodinstall PORTABILITY:  



• perlmodinstall HEY:  



• perlmodinstall AUTHOR:  



• perlmodinstall COPYRIGHT:  



DESCRIPTION


• perlmodinstall PREAMBLE:  



perlmodstyle


• perlmodstyle NAME:  



• perlmodstyle INTRODUCTION:  



• perlmodstyle QUICK CHECKLIST:  



• perlmodstyle BEFORE YOU START WRITING A MODULE:  



• perlmodstyle DESIGNING AND WRITING YOUR MODULE:  



• perlmodstyle DOCUMENTING YOUR MODULE:  



• perlmodstyle RELEASE CONSIDERATIONS:  



• perlmodstyle COMMON PITFALLS:  



• perlmodstyle SEE ALSO:  



• perlmodstyle AUTHOR:  



QUICK CHECKLIST


• perlmodstyle Before you start:  



• perlmodstyle The API:  



• perlmodstyle Stability:  



• perlmodstyle Documentation:  



• perlmodstyle Release considerations:  



BEFORE YOU START WRITING A MODULE


• perlmodstyle Has it been done before?:  



• perlmodstyle Do one thing and do it well:  



• perlmodstyle What's in a name?:  



DESIGNING AND WRITING YOUR MODULE


• perlmodstyle To OO or not to OO?:  



• perlmodstyle Designing your API:  



• perlmodstyle Strictness and warnings:  



• perlmodstyle Backwards compatibility:  



• perlmodstyle Error handling and messages:  



DOCUMENTING YOUR MODULE


• perlmodstyle POD:  



• perlmodstyle README, INSTALL, release notes, changelogs:  



RELEASE CONSIDERATIONS


• perlmodstyle Version numbering:  



• perlmodstyle Pre-requisites:  



• perlmodstyle Testing:  



• perlmodstyle Packaging:  



• perlmodstyle Licensing:  



COMMON PITFALLS


• perlmodstyle Reinventing the wheel:  



• perlmodstyle Trying to do too much:  



• perlmodstyle Inappropriate documentation:  



perlmroapi


• perlmroapi NAME:  



• perlmroapi DESCRIPTION:  



• perlmroapi Callbacks:  



• perlmroapi Caching:  



• perlmroapi Examples:  



• perlmroapi AUTHORS:  



perlnewmod


• perlnewmod NAME:  



• perlnewmod DESCRIPTION:  



• perlnewmod AUTHOR:  



• perlnewmod SEE ALSO:  



DESCRIPTION


• perlnewmod Warning:  



• perlnewmod What should I make into a module?:  



• perlnewmod Step-by-step: Preparing the ground:  



• perlnewmod Step-by-step: Making the module:  



• perlnewmod Step-by-step: Distributing your module:  



perlnumber


• perlnumber NAME:  



• perlnumber SYNOPSIS:  



• perlnumber DESCRIPTION:  



• perlnumber Storing numbers:  



• perlnumber Numeric operators and numeric conversions:  



• perlnumber Flavors of Perl numeric operations:  



• perlnumber AUTHOR:  



• perlnumber SEE ALSO:  



NAME object OOP


• NAME object OOP NAME:  



• NAME object OOP DESCRIPTION:  



• NAME object OOP SEE ALSO:  



DESCRIPTION


• NAME object OOP An Object is Simply a Data Structure:  



• NAME object OOP A Class is Simply a Package:  



• NAME object OOP A Method is Simply a Subroutine:  



• NAME object OOP Method Invocation:  



• NAME object OOP Inheritance:  



• NAME object OOP Writing Constructors:  



• NAME object OOP Attributes:  



• NAME object OOP An Aside About Smarter and Safer Code:  



• NAME object OOP Method Call Variations:  



• NAME object OOP Invoking Class Methods:  



• NAME object OOP bless, blessed, and ref:  



• NAME object OOP The UNIVERSAL Class:  



• NAME object OOP AUTOLOAD:  



• NAME object OOP Destructors:  



• NAME object OOP Non-Hash Objects:  



• NAME object OOP Inside-Out objects:  



• NAME object OOP Pseudo-hashes:  



An Object is Simply a Data Structure


• NAME object OOP Objects Are Blessed; Variables Are Not:  



Inheritance


• NAME object OOP How SUPER is Resolved:  



• NAME object OOP Multiple Inheritance:  



• NAME object OOP Method Resolution Order:  



• NAME object OOP Method Resolution Caching:  



Attributes


• NAME object OOP Writing Accessors:  



Method Call Variations


• NAME object OOP Method Names as Strings:  



• NAME object OOP Class Names as Strings:  



• NAME object OOP Subroutine References as Methods:  



• NAME object OOP Deferencing Method Call:  



• NAME object OOP Method Calls on Filehandles:  



Invoking Class Methods


• NAME object OOP Indirect Object Syntax:  



Destructors


• NAME object OOP Global Destruction:  



perlootut


• perlootut NAME:  



• perlootut DATE:  



• perlootut DESCRIPTION:  



• perlootut OBJECT-ORIENTED FUNDAMENTALS:  



• perlootut PERL OO SYSTEMS:  



• perlootut CONCLUSION:  



OBJECT-ORIENTED FUNDAMENTALS


• perlootut Object:  



• perlootut Class:  



• perlootut Methods:  



• perlootut Attributes:  



• perlootut Polymorphism:  



• perlootut Inheritance:  



• perlootut Encapsulation:  



• perlootut Composition:  



• perlootut Roles:  



• perlootut When to Use OO:  



Class


• perlootut Blessing:  



• perlootut Constructor:  



Inheritance


• perlootut Overriding methods and method resolution:  



PERL OO SYSTEMS


• perlootut Moose:  



• perlootut Class::Accessor:  



• perlootut Object::Tiny:  



• perlootut Role::Tiny:  



• perlootut OO System Summary:  



• perlootut Other OO Systems:  



Moose


• perlootut Mouse:  



NAME operator


• NAME operator NAME:  



• NAME operator DESCRIPTION:  



DESCRIPTION


• NAME operator Operator Precedence and Associativity:  



• NAME operator Terms and List Operators (Leftward):  



• NAME operator The Arrow Operator:  



• NAME operator Auto-increment and Auto-decrement:  



• NAME operator Exponentiation:  



• NAME operator Symbolic Unary Operators:  



• NAME operator Binding Operators:  



• NAME operator Multiplicative Operators:  



• NAME operator Additive Operators:  



• NAME operator Shift Operators:  



• NAME operator Named Unary Operators:  



• NAME operator Relational Operators:  



• NAME operator Equality Operators:  



• NAME operator Smartmatch Operator:  



• NAME operator Bitwise And:  



• NAME operator Bitwise Or and Exclusive Or:  



• NAME operator C-style Logical And:  



• NAME operator C-style Logical Or:  



• NAME operator Logical Defined-Or:  



• NAME operator Range Operators:  



• NAME operator Conditional Operator:  



• NAME operator Assignment Operators:  



• NAME operator Comma Operator:  



• NAME operator List Operators (Rightward):  



• NAME operator Logical Not:  



• NAME operator Logical And:  



• NAME operator Logical or and Exclusive Or:  



• NAME operator C Operators Missing From Perl:  



• NAME operator Quote and Quote-like Operators:  



• NAME operator Regexp Quote-Like Operators:  



• NAME operator Quote-Like Operators:  



• NAME operator Gory details of parsing quoted constructs:  



• NAME operator I/O Operators:  



• NAME operator Constant Folding:  



• NAME operator No-ops:  



• NAME operator Bitwise String Operators:  



• NAME operator Integer Arithmetic:  



• NAME operator Floating-point Arithmetic:  



• NAME operator Bigger Numbers:  



Smartmatch Operator


• NAME operator Smartmatching of Objects:  



perlopentut


• perlopentut NAME:  



• perlopentut DESCRIPTION:  



• perlopentut Open à la shell:  



• perlopentut Open à la C:  



• perlopentut Obscure Open Tricks:  



• perlopentut Other I/O Issues:  



• perlopentut SEE ALSO:  



• perlopentut AUTHOR and COPYRIGHT:  



• perlopentut HISTORY:  



Open à la shell


• perlopentut Simple Opens:  



• perlopentut Indirect Filehandles:  



• perlopentut Pipe Opens:  



• perlopentut The Minus File:  



• perlopentut Mixing Reads and Writes:  



• perlopentut Filters:  



Open à la C


• perlopentut Permissions à la mode:  



Obscure Open Tricks


• perlopentut Re-Opening Files (dups):  



• perlopentut Dispelling the Dweomer:  



• perlopentut Paths as Opens:  



• perlopentut Single Argument Open:  



• perlopentut Playing with STDIN and STDOUT:  



Other I/O Issues


• perlopentut Opening Non-File Files:  



• perlopentut Opening Named Pipes:  



• perlopentut Opening Sockets:  



• perlopentut Binary Files:  



• perlopentut File Locking:  



• perlopentut IO Layers:  



perlpacktut


• perlpacktut NAME:  



• perlpacktut DESCRIPTION:  



• perlpacktut The Basic Principle:  



• perlpacktut Packing Text:  



• perlpacktut Packing Numbers:  



• perlpacktut Exotic Templates:  



• perlpacktut Template Grouping:  



• perlpacktut Lengths and Widths:  



• perlpacktut Packing and Unpacking C Structures:  



• perlpacktut Pack Recipes:  



• perlpacktut Funnies Section:  



• perlpacktut Authors:  



Packing Numbers


• perlpacktut Integers:  



• perlpacktut Unpacking a Stack Frame:  



• perlpacktut How to Eat an Egg on a Net:  



• perlpacktut Byte-order modifiers:  



• perlpacktut Floating point Numbers:  



Exotic Templates


• perlpacktut Bit Strings:  



• perlpacktut Uuencoding:  



• perlpacktut Doing Sums:  



• perlpacktut Unicode:  



• perlpacktut Another Portable Binary Encoding:  



Lengths and Widths


• perlpacktut String Lengths:  



• perlpacktut Dynamic Templates:  



• perlpacktut Counting Repetitions:  



• perlpacktut Intel HEX:  



Packing and Unpacking C Structures


• perlpacktut The Alignment Pit:  



• perlpacktut Dealing with Endian-ness:  



• perlpacktut Alignment, Take 2:  



• perlpacktut Alignment, Take 3:  



• perlpacktut Pointers for How to Use Them:  



perlperf


• perlperf NAME:  



• perlperf DESCRIPTION:  



• perlperf OVERVIEW:  



• perlperf GENERAL GUIDELINES:  



• perlperf BENCHMARKS:  



• perlperf PROFILING TOOLS:  



• perlperf SORTING:  



• perlperf LOGGING:  



• perlperf POSTSCRIPT:  



• perlperf SEE ALSO:  



• perlperf AUTHOR:  



OVERVIEW


• perlperf ONE STEP SIDEWAYS:  



• perlperf ONE STEP FORWARD:  



• perlperf ANOTHER STEP SIDEWAYS:  



BENCHMARKS


• perlperf Assigning and Dereferencing Variables.:  



• perlperf Search and replace or tr:  



PROFILING TOOLS


• perlperf Devel::DProf:  



• perlperf Devel::Profiler:  



• perlperf Devel::SmallProf:  



• perlperf Devel::FastProf:  



• perlperf Devel::NYTProf:  



LOGGING


• perlperf Logging if DEBUG (constant):  



SEE ALSO


• perlperf PERLDOCS:  



• perlperf MAN PAGES:  



• perlperf MODULES:  



• perlperf URLS:  



NAME POD plain old documentation


• NAME POD plain old documentation NAME:  



• NAME POD plain old documentation DESCRIPTION:  



• NAME POD plain old documentation SEE ALSO:  



• NAME POD plain old documentation AUTHOR:  



DESCRIPTION


• NAME POD plain old documentation Ordinary Paragraph:  



• NAME POD plain old documentation Verbatim Paragraph:  



• NAME POD plain old documentation Command Paragraph:  



• NAME POD plain old documentation Formatting Codes:  



• NAME POD plain old documentation The Intent:  



• NAME POD plain old documentation Embedding Pods in Perl Modules:  



• NAME POD plain old documentation Hints for Writing Pod:  



perlpodspec


• perlpodspec NAME:  



• perlpodspec DESCRIPTION:  



• perlpodspec Pod Definitions:  



• perlpodspec Pod Commands:  



• perlpodspec Pod Formatting Codes:  



• perlpodspec Notes on Implementing Pod Processors:  



• perlpodspec About L<...> Codes:  



• perlpodspec About =over...=back Regions:  



• perlpodspec About Data Paragraphs and "=begin/=end" Regions:  



• perlpodspec SEE ALSO:  



• perlpodspec AUTHOR:  



perlpodstyle


• perlpodstyle NAME:  



• perlpodstyle DESCRIPTION:  



• perlpodstyle SEE ALSO 1:  



• perlpodstyle AUTHOR 1:  



• perlpodstyle COPYRIGHT AND LICENSE 1:  



perlpolicy


• perlpolicy NAME:  



• perlpolicy DESCRIPTION:  



• perlpolicy GOVERNANCE:  



• perlpolicy MAINTENANCE AND SUPPORT:  



• perlpolicy BACKWARD COMPATIBILITY AND DEPRECATION:  



• perlpolicy MAINTENANCE BRANCHES:  



• perlpolicy CONTRIBUTED MODULES:  



• perlpolicy DOCUMENTATION:  



• perlpolicy CREDITS:  



GOVERNANCE


• perlpolicy Perl 5 Porters:  



BACKWARD COMPATIBILITY AND DEPRECATION


• perlpolicy Terminology:  



MAINTENANCE BRANCHES


• perlpolicy Getting changes into a maint branch:  



CONTRIBUTED MODULES


• perlpolicy A Social Contract about Artistic Control:  



perlport


• perlport NAME:  



• perlport DESCRIPTION:  



• perlport ISSUES:  



• perlport CPAN Testers:  



• perlport PLATFORMS:  



• perlport FUNCTION IMPLEMENTATIONS:  



• perlport Supported Platforms:  



• perlport EOL Platforms (Perl 5.14):  



• perlport Supported Platforms (Perl 5.8):  



• perlport SEE ALSO:  



• perlport AUTHORS / CONTRIBUTORS:  



ISSUES


• perlport Newlines:  



• perlport Numbers endianness and Width:  



• perlport Files and Filesystems:  



• perlport System Interaction:  



• perlport Command names versus file pathnames:  



• perlport Networking:  



• perlport Interprocess Communication (IPC):  



• perlport External Subroutines (XS):  



• perlport Standard Modules:  



• perlport Time and Date:  



• perlport Character sets and character encoding:  



• perlport Internationalisation:  



• perlport System Resources:  



• perlport Security:  



• perlport Style:  



PLATFORMS


• perlport Unix:  



• perlport DOS and Derivatives:  



• perlport VMS:  



• perlport VOS:  



• perlport EBCDIC Platforms:  



• perlport Acorn RISC OS:  



• perlport Other perls:  



FUNCTION IMPLEMENTATIONS


• perlport Alphabetical Listing of Perl Functions:  



perlpragma


• perlpragma NAME:  



• perlpragma DESCRIPTION:  



• perlpragma A basic example:  



• perlpragma Key naming:  



• perlpragma Implementation details:  



NAME regular expression regex regexp


• NAME regular expression regex regexp NAME:  



• NAME regular expression regex regexp DESCRIPTION:  



• NAME regular expression regex regexp BUGS:  



• NAME regular expression regex regexp SEE ALSO:  



DESCRIPTION


• NAME regular expression regex regexp Modifiers:  



• NAME regular expression regex regexp Regular Expressions:  



• NAME regular expression regex regexp Quoting metacharacters:  



• NAME regular expression regex regexp Extended Patterns:  



• NAME regular expression regex regexp Special Backtracking Control Verbs:  



• NAME regular expression regex regexp Backtracking:  



• NAME regular expression regex regexp Version 8 Regular Expressions:  



• NAME regular expression regex regexp Warning on \1 Instead of $1:  



• NAME regular expression regex regexp Repeated Patterns Matching a Zero-length Substring:  



• NAME regular expression regex regexp Combining RE Pieces:  



• NAME regular expression regex regexp Creating Custom RE Engines:  



• NAME regular expression regex regexp PCRE/Python Support:  



Modifiers


• NAME regular expression regex regexp /x:  



• NAME regular expression regex regexp Character set modifiers:  



• NAME regular expression regex regexp /l:  



• NAME regular expression regex regexp /u:  



• NAME regular expression regex regexp /d:  



• NAME regular expression regex regexp /a (and /aa):  



• NAME regular expression regex regexp Which character set modifier is in effect?:  



• NAME regular expression regex regexp Character set modifier behavior prior to Perl 5.14:  



Regular Expressions


• NAME regular expression regex regexp Metacharacters:  



• NAME regular expression regex regexp Quantifiers:  



• NAME regular expression regex regexp Escape sequences:  



• NAME regular expression regex regexp Character Classes and other Special Escapes:  



• NAME regular expression regex regexp Assertions:  



• NAME regular expression regex regexp Capture groups:  



perlreapi


• perlreapi NAME:  



• perlreapi DESCRIPTION:  



• perlreapi Callbacks:  



• perlreapi The REGEXP structure:  



• perlreapi HISTORY:  



• perlreapi AUTHORS:  



• perlreapi LICENSE:  



Callbacks


• perlreapi comp:  



• perlreapi exec:  



• perlreapi intuit:  



• perlreapi checkstr:  



• perlreapi free:  



• perlreapi Numbered capture callbacks:  



• perlreapi Named capture callbacks:  



• perlreapi qr_package:  



• perlreapi dupe:  



Numbered capture callbacks


• perlreapi numbered_buff_FETCH:  



• perlreapi numbered_buff_STORE:  



• perlreapi numbered_buff_LENGTH:  



Named capture callbacks


• perlreapi named_buff:  



• perlreapi named_buff_iter:  



The REGEXP structure


• perlreapi engine:  



• perlreapi mother_re:  



• perlreapi extflags:  



• perlreapi minlen minlenret:  



• perlreapi gofs:  



• perlreapi substrs:  



• perlreapi nparens, lastparen, and lastcloseparen:  



• perlreapi intflags:  



• perlreapi pprivate:  



• perlreapi swap:  



• perlreapi offs:  



• perlreapi precomp prelen:  



• perlreapi paren_names:  



• perlreapi substrs 1:  



• perlreapi subbeg sublen saved_copy:  



• perlreapi wrapped wraplen:  



• perlreapi seen_evals:  



• perlreapi refcnt:  



perlrebackslash


• perlrebackslash NAME:  



• perlrebackslash DESCRIPTION:  



DESCRIPTION


• perlrebackslash The backslash:  



• perlrebackslash All the sequences and escapes:  



• perlrebackslash Character Escapes:  



• perlrebackslash Modifiers:  



• perlrebackslash Character classes:  



• perlrebackslash Referencing:  



• perlrebackslash Assertions:  



• perlrebackslash Misc:  



Character Escapes


• perlrebackslash Fixed characters:  



• perlrebackslash Example:  



• perlrebackslash Control characters:  



• perlrebackslash Example 1:  



• perlrebackslash Named or numbered characters and character sequences:  



• perlrebackslash Example 2:  



• perlrebackslash Octal escapes:  



• perlrebackslash Examples (assuming an ASCII platform):  



• perlrebackslash Disambiguation rules between old-style octal escapes and backreferences:  



• perlrebackslash Hexadecimal escapes:  



• perlrebackslash Examples (assuming an ASCII platform) 1:  



Modifiers


• perlrebackslash Examples:  



Character classes


• perlrebackslash Unicode classes:  



Referencing


• perlrebackslash Absolute referencing:  



• perlrebackslash Examples 1:  



• perlrebackslash Relative referencing:  



• perlrebackslash Examples 2:  



• perlrebackslash Named referencing:  



• perlrebackslash Examples 3:  



Assertions


• perlrebackslash Examples 4:  



Misc


• perlrebackslash Examples 5:  



NAME character class


• NAME character class NAME:  



• NAME character class DESCRIPTION:  



DESCRIPTION


• NAME character class The dot:  



• NAME character class Backslash sequences:  



• NAME character class Bracketed Character Classes:  



Backslash sequences


• NAME character class \N:  



• NAME character class Digits:  



• NAME character class Word characters:  



• NAME character class Whitespace:  



• NAME character class Unicode Properties:  



• NAME character class Examples:  



Bracketed Character Classes


• NAME character class Special Characters Inside a Bracketed Character Class:  



• NAME character class Character Ranges:  



• NAME character class Negation:  



• NAME character class Backslash Sequences:  



• NAME character class POSIX Character Classes:  



• NAME character class Negation of POSIX character classes:  



• NAME character class [= =] and [. .]:  



• NAME character class Examples 1:  



NAME reference pointer data structure structure struct


• NAME reference pointer data structure structure struct NAME:  



• NAME reference pointer data structure structure struct NOTE:  



• NAME reference pointer data structure structure struct DESCRIPTION:  



• NAME reference pointer data structure structure struct WARNING:  



• NAME reference pointer data structure structure struct SEE ALSO:  



DESCRIPTION


• NAME reference pointer data structure structure struct Making References:  



• NAME reference pointer data structure structure struct Using References:  



• NAME reference pointer data structure structure struct Circular References:  



• NAME reference pointer data structure structure struct Symbolic references:  



• NAME reference pointer data structure structure struct Not-so-symbolic references:  



• NAME reference pointer data structure structure struct Pseudo-hashes: Using an array as a hash:  



• NAME reference pointer data structure structure struct Function Templates:  



perlreftut


• perlreftut NAME:  



• perlreftut DESCRIPTION:  



• perlreftut Who Needs Complicated Data Structures?:  



• perlreftut The Solution:  



• perlreftut Syntax:  



• perlreftut Solution:  



• perlreftut The Rest:  



• perlreftut Summary:  



• perlreftut Credits:  



Syntax


• perlreftut Making References:  



• perlreftut Using References:  



• perlreftut An Example:  



• perlreftut Arrow Rule:  



Making References


• perlreftut Make Rule 1:  



Using References


• perlreftut Use Rule 1:  



• perlreftut Use Rule 2:  



Credits


• perlreftut Distribution Conditions:  



perlreguts


• perlreguts NAME:  



• perlreguts DESCRIPTION:  



• perlreguts OVERVIEW:  



• perlreguts Process Overview:  



• perlreguts MISCELLANEOUS:  



• perlreguts SEE ALSO:  



• perlreguts AUTHOR:  



• perlreguts LICENCE:  



• perlreguts REFERENCES:  



OVERVIEW


• perlreguts A quick note on terms:  



• perlreguts What is a regular expression engine?:  



• perlreguts Structure of a Regexp Program:  



Structure of a Regexp Program


• perlreguts High Level:  



• perlreguts Regops:  



• perlreguts What regop is next?:  



Process Overview


• perlreguts Compilation:  



• perlreguts Execution:  



Compilation


• perlreguts Parsing for size:  



• perlreguts Parsing for construction:  



• perlreguts Parse Call Graph and a Grammar:  



• perlreguts Debug Output:  



• perlreguts Peep-hole Optimisation and Analysis:  



Execution


• perlreguts Start position and no-match optimisations:  



• perlreguts Program execution:  



MISCELLANEOUS


• perlreguts Unicode and Localisation Support:  



• perlreguts Base Structures:  



Base Structures


• perlreguts Perl's pprivate structure:  



perlrequick


• perlrequick NAME:  



• perlrequick DESCRIPTION:  



• perlrequick The Guide:  



• perlrequick BUGS:  



• perlrequick SEE ALSO:  



• perlrequick AUTHOR AND COPYRIGHT:  



The Guide


• perlrequick Simple word matching:  



• perlrequick Using character classes:  



• perlrequick Matching this or that:  



• perlrequick Grouping things and hierarchical matching:  



• perlrequick Extracting matches:  



• perlrequick Matching repetitions:  



• perlrequick More matching:  



• perlrequick Search and replace:  



• perlrequick The split operator:  



AUTHOR AND COPYRIGHT


• perlrequick Acknowledgments:  



perlreref


• perlreref NAME:  



• perlreref DESCRIPTION:  



• perlreref AUTHOR:  



• perlreref SEE ALSO:  



• perlreref THANKS:  



DESCRIPTION


• perlreref OPERATORS:  



• perlreref SYNTAX:  



• perlreref ESCAPE SEQUENCES:  



• perlreref CHARACTER CLASSES:  



• perlreref ANCHORS:  



• perlreref QUANTIFIERS:  



• perlreref EXTENDED CONSTRUCTS:  



• perlreref VARIABLES:  



• perlreref FUNCTIONS:  



• perlreref TERMINOLOGY:  



TERMINOLOGY


• perlreref Titlecase:  



• perlreref Foldcase:  



perlretut


• perlretut NAME:  



• perlretut DESCRIPTION:  



• perlretut Part 1: The basics:  



• perlretut Part 2: Power tools:  



• perlretut BUGS:  



• perlretut SEE ALSO:  



• perlretut AUTHOR AND COPYRIGHT:  



Part 1: The basics


• perlretut Simple word matching:  



• perlretut Using character classes:  



• perlretut Matching this or that:  



• perlretut Grouping things and hierarchical matching:  



• perlretut Extracting matches:  



• perlretut Backreferences:  



• perlretut Relative backreferences:  



• perlretut Named backreferences:  



• perlretut Alternative capture group numbering:  



• perlretut Position information:  



• perlretut Non-capturing groupings:  



• perlretut Matching repetitions:  



• perlretut Possessive quantifiers:  



• perlretut Building a regexp:  



• perlretut Using regular expressions in Perl:  



Using regular expressions in Perl


• perlretut Prohibiting substitution:  



• perlretut Global matching:  



• perlretut Search and replace:  



• perlretut The split function:  



Part 2: Power tools


• perlretut More on characters, strings, and character classes:  



• perlretut Compiling and saving regular expressions:  



• perlretut Composing regular expressions at runtime:  



• perlretut Embedding comments and modifiers in a regular expression:  



• perlretut Looking ahead and looking behind:  



• perlretut Using independent subexpressions to prevent backtracking:  



• perlretut Conditional expressions:  



• perlretut Defining named patterns:  



• perlretut Recursive patterns:  



• perlretut A bit of magic: executing Perl code in a regular expression:  



• perlretut Backtracking control verbs:  



• perlretut Pragmas and debugging:  



AUTHOR AND COPYRIGHT


• perlretut Acknowledgments:  



perlrun


• perlrun NAME:  



• perlrun SYNOPSIS:  



• perlrun DESCRIPTION:  



• perlrun ENVIRONMENT:  



DESCRIPTION


• perlrun #! and quoting on non-Unix systems:  



• perlrun Location of Perl:  



• perlrun Command Switches:  



perlsec


• perlsec NAME:  



• perlsec DESCRIPTION:  



• perlsec SECURITY VULNERABILITY CONTACT INFORMATION:  



• perlsec SECURITY MECHANISMS AND CONCERNS:  



• perlsec SEE ALSO:  



SECURITY MECHANISMS AND CONCERNS


• perlsec Taint mode:  



• perlsec Laundering and Detecting Tainted Data:  



• perlsec Switches On the "#!" Line:  



• perlsec Taint mode and @INC:  



• perlsec Cleaning Up Your Path:  



• perlsec Security Bugs:  



• perlsec Protecting Your Programs:  



• perlsec Unicode:  



• perlsec Algorithmic Complexity Attacks:  



perlsource


• perlsource NAME:  



• perlsource DESCRIPTION:  



• perlsource FINDING YOUR WAY AROUND:  



FINDING YOUR WAY AROUND


• perlsource C code:  



• perlsource Core modules:  



• perlsource Tests:  



• perlsource Documentation:  



• perlsource Hacking tools and documentation:  



• perlsource Build system:  



• perlsource AUTHORS:  



• perlsource MANIFEST:  



perlstyle


• perlstyle NAME:  



• perlstyle DESCRIPTION:  



NAME subroutine function


• NAME subroutine function NAME:  



• NAME subroutine function SYNOPSIS:  



• NAME subroutine function DESCRIPTION:  



• NAME subroutine function SEE ALSO:  



DESCRIPTION


• NAME subroutine function Private Variables via my():  



• NAME subroutine function Persistent Private Variables:  



• NAME subroutine function Temporary Values via local():  



• NAME subroutine function Lvalue subroutines:  



• NAME subroutine function Passing Symbol Table Entries (typeglobs):  



• NAME subroutine function When to Still Use local():  



• NAME subroutine function Pass by Reference:  



• NAME subroutine function Prototypes:  



• NAME subroutine function Constant Functions:  



• NAME subroutine function Overriding Built-in Functions:  



• NAME subroutine function Autoloading:  



• NAME subroutine function Subroutine Attributes:  



Persistent Private Variables


• NAME subroutine function Persistent variables via state():  



• NAME subroutine function Persistent variables with closures:  



Temporary Values via local()


• NAME subroutine function Grammatical note on local():  



• NAME subroutine function Localization of special variables:  



• NAME subroutine function Localization of globs:  



• NAME subroutine function Localization of elements of composite types:  



• NAME subroutine function Localized deletion of elements of composite types:  



NAME syntax


• NAME syntax NAME:  



• NAME syntax DESCRIPTION:  



DESCRIPTION


• NAME syntax Declarations:  



• NAME syntax Comments:  



• NAME syntax Simple Statements:  



• NAME syntax Truth and Falsehood:  



• NAME syntax Statement Modifiers:  



• NAME syntax Compound Statements:  



• NAME syntax Loop Control:  



• NAME syntax For Loops:  



• NAME syntax Foreach Loops:  



• NAME syntax Basic BLOCKs:  



• NAME syntax Switch Statements:  



• NAME syntax Goto:  



• NAME syntax The Ellipsis Statement:  



• NAME syntax PODs: Embedded Documentation:  



• NAME syntax Plain Old Comments (Not!):  



• NAME syntax Experimental Details on given and when:  



Experimental Details on given and when


• NAME syntax Breaking out:  



• NAME syntax Fall-through:  



• NAME syntax Return value:  



• NAME syntax Switching in a loop:  



• NAME syntax Differences from Perl 6:  



perlthrtut


• perlthrtut NAME:  



• perlthrtut DESCRIPTION:  



• perlthrtut What Is A Thread Anyway?:  



• perlthrtut Threaded Program Models:  



• perlthrtut What kind of threads are Perl threads?:  



• perlthrtut Thread-Safe Modules:  



• perlthrtut Thread Basics:  



• perlthrtut Threads And Data:  



• perlthrtut Synchronization and control:  



• perlthrtut General Thread Utility Routines:  



• perlthrtut A Complete Example:  



• perlthrtut Different implementations of threads:  



• perlthrtut Performance considerations:  



• perlthrtut Process-scope Changes:  



• perlthrtut Thread-Safety of System Libraries:  



• perlthrtut Conclusion:  



• perlthrtut SEE ALSO:  



• perlthrtut Bibliography:  



• perlthrtut Acknowledgements:  



• perlthrtut AUTHOR:  



• perlthrtut Copyrights:  



Threaded Program Models


• perlthrtut Boss/Worker:  



• perlthrtut Work Crew:  



• perlthrtut Pipeline:  



Thread Basics


• perlthrtut Basic Thread Support:  



• perlthrtut A Note about the Examples:  



• perlthrtut Creating Threads:  



• perlthrtut Waiting For A Thread To Exit:  



• perlthrtut Ignoring A Thread:  



• perlthrtut Process and Thread Termination:  



Threads And Data


• perlthrtut Shared And Unshared Data:  



• perlthrtut Thread Pitfalls: Races:  



Synchronization and control


• perlthrtut Controlling access: lock():  



• perlthrtut A Thread Pitfall: Deadlocks:  



• perlthrtut Queues: Passing Data Around:  



• perlthrtut Semaphores: Synchronizing Data Access:  



• perlthrtut Basic semaphores:  



• perlthrtut Advanced Semaphores:  



• perlthrtut Waiting for a Condition:  



• perlthrtut Giving up control:  



General Thread Utility Routines


• perlthrtut What Thread Am I In?:  



• perlthrtut Thread IDs:  



• perlthrtut Are These Threads The Same?:  



• perlthrtut What Threads Are Running?:  



Bibliography


• perlthrtut Introductory Texts:  



• perlthrtut OS-Related References:  



• perlthrtut Other References:  



NAME tie


• NAME tie NAME:  



• NAME tie SYNOPSIS:  



• NAME tie DESCRIPTION:  



• NAME tie SEE ALSO:  



• NAME tie BUGS:  



• NAME tie AUTHOR:  



DESCRIPTION


• NAME tie Tying Scalars:  



• NAME tie Tying Arrays:  



• NAME tie Tying Hashes:  



• NAME tie Tying FileHandles:  



• NAME tie UNTIE this 4:  



• NAME tie The untie Gotcha:  



perltodo


• perltodo NAME:  



• perltodo DESCRIPTION:  



perltooc


• perltooc NAME:  



• perltooc DESCRIPTION:  



perltoot


• perltoot NAME:  



• perltoot DESCRIPTION:  



perltrap


• perltrap NAME:  



• perltrap DESCRIPTION:  



DESCRIPTION


• perltrap Awk Traps:  



• perltrap C/C++ Traps:  



• perltrap Sed Traps:  



• perltrap Shell Traps:  



• perltrap Perl Traps:  



• perltrap Perl4 to Perl5 Traps:  



• perltrap Discontinuance, Deprecation, and BugFix traps 1:  



• perltrap Parsing Traps 1:  



• perltrap Numerical Traps 1:  



• perltrap General data type traps 1:  



• perltrap Context Traps - scalar, list contexts 1:  



• perltrap Precedence Traps 1:  



• perltrap General Regular Expression Traps using s///, etc. 1:  



• perltrap Subroutine, Signal, Sorting Traps 1:  



• perltrap OS Traps 1:  



• perltrap Interpolation Traps:  



• perltrap DBM Traps 1:  



• perltrap Unclassified Traps 1:  



perlunicode


• perlunicode NAME:  



• perlunicode DESCRIPTION:  



• perlunicode BUGS:  



• perlunicode SEE ALSO:  



DESCRIPTION


• perlunicode Important Caveats:  



• perlunicode Byte and Character Semantics:  



• perlunicode Effects of Character Semantics:  



• perlunicode Unicode Character Properties:  



• perlunicode User-Defined Character Properties:  



• perlunicode User-Defined Case Mappings (for serious hackers only):  



• perlunicode Character Encodings for Input and Output:  



• perlunicode Unicode Regular Expression Support Level:  



• perlunicode Unicode Encodings:  



• perlunicode Non-character code points:  



• perlunicode Beyond Unicode code points:  



• perlunicode Security Implications of Unicode:  



• perlunicode Unicode in Perl on EBCDIC:  



• perlunicode Locales:  



• perlunicode When Unicode Does Not Happen:  



• perlunicode The "Unicode Bug":  



• perlunicode Forcing Unicode in Perl (Or Unforcing Unicode in Perl):  



• perlunicode Using Unicode in XS:  



• perlunicode Hacking Perl to work on earlier Unicode versions (for very serious hackers only):  



Unicode Character Properties


• perlunicode General_Category:  



• perlunicode Bidirectional Character Types:  



• perlunicode Scripts:  



• perlunicode Use of "Is" Prefix:  



• perlunicode Blocks:  



• perlunicode Other Properties:  



BUGS


• perlunicode Interaction with Locales:  



• perlunicode Problems with characters in the Latin-1 Supplement range:  



• perlunicode Interaction with Extensions:  



• perlunicode Speed:  



• perlunicode Problems on EBCDIC platforms:  



• perlunicode Porting code from perl-5.6.X:  



perlunifaq


• perlunifaq NAME:  



• perlunifaq Q and A:  



• perlunifaq INTERNALS:  



• perlunifaq AUTHOR:  



• perlunifaq SEE ALSO:  



Q and A


• perlunifaq perlunitut isn't really a Unicode tutorial, is it?:  



• perlunifaq What character encodings does Perl support?:  



• perlunifaq Which version of perl should I use?:  



• perlunifaq What about binary data, like images?:  



• perlunifaq When should I decode or encode?:  



• perlunifaq What if I don't decode?:  



• perlunifaq What if I don't encode?:  



• perlunifaq Is there a way to automatically decode or encode?:  



• perlunifaq What if I don't know which encoding was used?:  



• perlunifaq Can I use Unicode in my Perl sources?:  



• perlunifaq Data::Dumper doesn't restore the UTF8 flag; is it broken?:  



• perlunifaq Why do regex character classes sometimes match only in the ASCII range?:  



• perlunifaq Why do some characters not uppercase or lowercase correctly?:  



• perlunifaq How can I determine if a string is a text string or a binary string?:  



• perlunifaq How do I convert from encoding FOO to encoding BAR?:  



• perlunifaq What are decode_utf8 and encode_utf8?:  



• perlunifaq What is a "wide character"?:  



INTERNALS


• perlunifaq What is "the UTF8 flag"?:  



• perlunifaq What about the use bytes pragma?:  



• perlunifaq What about the use encoding pragma?:  



• perlunifaq What is the difference between :encoding and :utf8?:  



• perlunifaq What's the difference between UTF-8 and utf8?:  



• perlunifaq I lost track; what encoding is the internal format really?:  



perluniintro


• perluniintro NAME:  



• perluniintro DESCRIPTION:  



• perluniintro UNICODE IN OLDER PERLS:  



• perluniintro SEE ALSO:  



• perluniintro ACKNOWLEDGMENTS:  



• perluniintro AUTHOR, COPYRIGHT, AND LICENSE:  



DESCRIPTION


• perluniintro Unicode:  



• perluniintro Perl's Unicode Support:  



• perluniintro Perl's Unicode Model:  



• perluniintro Unicode and EBCDIC:  



• perluniintro Creating Unicode:  



• perluniintro Handling Unicode:  



• perluniintro Legacy Encodings:  



• perluniintro Unicode I/O:  



• perluniintro Displaying Unicode As Text:  



• perluniintro Special Cases:  



• perluniintro Advanced Topics:  



• perluniintro Miscellaneous:  



• perluniintro Questions With Answers:  



• perluniintro Hexadecimal Notation:  



• perluniintro Further Resources:  



perlunitut


• perlunitut NAME:  



• perlunitut DESCRIPTION:  



• perlunitut SUMMARY:  



• perlunitut Q and A (or FAQ):  



• perlunitut ACKNOWLEDGEMENTS:  



• perlunitut AUTHOR:  



• perlunitut SEE ALSO:  



DESCRIPTION


• perlunitut Definitions:  



• perlunitut Your new toolkit:  



• perlunitut I/O flow (the actual 5 minute tutorial):  



Definitions


• perlunitut Unicode:  



• perlunitut UTF-8:  



• perlunitut Text strings (character strings):  



• perlunitut Binary strings (byte strings):  



• perlunitut Encoding:  



• perlunitut Decoding:  



• perlunitut Internal format:  



perlutil


• perlutil NAME:  



• perlutil DESCRIPTION:  



• perlutil LIST OF UTILITIES:  



• perlutil SEE ALSO:  



LIST OF UTILITIES


• perlutil Documentation:  



• perlutil Converters:  



• perlutil Administration:  



• perlutil Development:  



• perlutil General tools:  



• perlutil Installation:  



perlvar


• perlvar NAME:  



• perlvar DESCRIPTION:  



• perlvar SPECIAL VARIABLES:  



DESCRIPTION


• perlvar The Syntax of Variable Names:  



SPECIAL VARIABLES


• perlvar General Variables:  



• perlvar Variables related to regular expressions:  



• perlvar Variables related to filehandles:  



• perlvar Error Variables:  



• perlvar Variables related to the interpreter state:  



• perlvar Deprecated and removed variables:  



Variables related to filehandles


• perlvar Variables related to formats:  



perlvms


• perlvms NAME:  



• perlvms DESCRIPTION:  



• perlvms Installation:  



• perlvms Organization of Perl Images:  



• perlvms File specifications:  



• perlvms PERL5LIB and PERLLIB:  



• perlvms The Perl Forked Debugger:  



• perlvms PERL_VMS_EXCEPTION_DEBUG:  



• perlvms Command line:  



• perlvms Perl functions:  



• perlvms Perl variables:  



• perlvms Standard modules with VMS-specific differences:  



• perlvms Revision date:  



• perlvms AUTHOR:  



Organization of Perl Images


• perlvms Core Images:  



• perlvms Perl Extensions:  



• perlvms Installing static extensions:  



• perlvms Installing dynamic extensions:  



File specifications


• perlvms Syntax:  



• perlvms Filename Case:  



• perlvms Symbolic Links:  



• perlvms Wildcard expansion:  



• perlvms Pipes:  



Command line


• perlvms I/O redirection and backgrounding:  



• perlvms Command line switches:  



Standard modules with VMS-specific differences


• perlvms SDBM_File:  












Next: , Previous: Top, Up: Top   [Contents]





1 perl





• perl NAME:  



• perl SYNOPSIS:  



• perl GETTING HELP:  



• perl DESCRIPTION:  



• perl AVAILABILITY:  



• perl ENVIRONMENT:  



• perl AUTHOR:  



• perl FILES:  



• perl SEE ALSO:  



• perl DIAGNOSTICS:  



• perl BUGS:  



• perl NOTES:  












Next: , Up: perl   [Contents]





1.1 NAME



perl - The Perl 5 language interpreter









Next: , Previous: perl NAME, Up: perl   [Contents]





1.2 SYNOPSIS



perl	[ -sTtuUWX ]
	[ -hv ] [ -V[:configvar] ]
	[ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
	[ -pna ] [ -Fpattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
	[ -Idir ] [ -m[-]module ] [ -M[-]’module...’ ] [ -f ]
	[ -C [number/list] ]
	[ -S ]
	[ -x[dir] ]
	[ -i[extension] ]
	[ [-e|-E] ’command’ ] [ – ] [ programfile ] [ argument ]...









Next: , Previous: perl SYNOPSIS, Up: perl   [Contents]





1.3 GETTING HELP



The perldoc program gives you access to all the documentation that comes
with Perl.  You can get more documentation, tutorials and community support
online at http://www.perl.org/.



If you’re new to Perl, you should start by running perldoc perlintro,
which is a general intro for beginners and provides some background to help
you navigate the rest of Perl’s extensive documentation.  Run perldoc
perldoc to learn more things you can do with perldoc.



For ease of access, the Perl manual has been split up into several sections.





• perl Overview:  



• perl Tutorials:  



• perl Reference Manual:  



• perl Internals and C Language Interface:  



• perl Miscellaneous:  



• perl Language-Specific:  



• perl Platform-Specific:  



• perl Stubs for Deleted Documents:  












Next: , Up: perl GETTING HELP   [Contents]





1.3.1 Overview



    perl                Perl overview (this section)
    perlintro           Perl introduction for beginners
    perltoc             Perl documentation table of contents









Next: , Previous: perl Overview, Up: perl GETTING HELP   [Contents]





1.3.2 Tutorials



    perlreftut          Perl references short introduction
    perldsc             Perl data structures intro
    perllol             Perl data structures: arrays of arrays

    perlrequick         Perl regular expressions quick start
    perlretut           Perl regular expressions tutorial

    perlootut           Perl OO tutorial for beginners

    perlperf            Perl Performance and Optimization Techniques

    perlstyle           Perl style guide

    perlcheat           Perl cheat sheet
    perltrap            Perl traps for the unwary
    perldebtut          Perl debugging tutorial

    perlfaq             Perl frequently asked questions
      perlfaq1          General Questions About Perl
      perlfaq2          Obtaining and Learning about Perl
      perlfaq3          Programming Tools
      perlfaq4          Data Manipulation
      perlfaq5          Files and Formats
      perlfaq6          Regexes
      perlfaq7          Perl Language Issues
      perlfaq8          System Interaction
      perlfaq9          Networking









Next: , Previous: perl Tutorials, Up: perl GETTING HELP   [Contents]





1.3.3 Reference Manual



    perlsyn             Perl syntax
    perldata            Perl data structures
    perlop              Perl operators and precedence
    perlsub             Perl subroutines
    perlfunc            Perl built-in functions
      perlopentut       Perl open() tutorial
      perlpacktut       Perl pack() and unpack() tutorial
    perlpod             Perl plain old documentation
    perlpodspec         Perl plain old documentation format specification
    perlpodstyle        Perl POD style guide
    perlrun             Perl execution and options
    perldiag            Perl diagnostic messages
    perllexwarn         Perl warnings and their control
    perldebug           Perl debugging
    perlvar             Perl predefined variables
    perlre              Perl regular expressions, the rest of the story
    perlrebackslash     Perl regular expression backslash sequences
    perlrecharclass     Perl regular expression character classes
    perlreref           Perl regular expressions quick reference
    perlref             Perl references, the rest of the story
    perlform            Perl formats
    perlobj             Perl objects
    perltie             Perl objects hidden behind simple variables
      perldbmfilter     Perl DBM filters

    perlipc             Perl interprocess communication
    perlfork            Perl fork() information
    perlnumber          Perl number semantics

    perlthrtut          Perl threads tutorial

    perlport            Perl portability guide
    perllocale          Perl locale support
    perluniintro        Perl Unicode introduction
    perlunicode         Perl Unicode support
    perlunifaq          Perl Unicode FAQ
    perluniprops        Index of Unicode Version 6.0.0 properties in Perl
    perlunitut          Perl Unicode tutorial
    perlebcdic          Considerations for running Perl on EBCDIC platforms

    perlsec             Perl security

    perlmod             Perl modules: how they work
    perlmodlib          Perl modules: how to write and use
    perlmodstyle        Perl modules: how to write modules with style
    perlmodinstall      Perl modules: how to install from CPAN
    perlnewmod          Perl modules: preparing a new module for distribution
    perlpragma          Perl modules: writing a user pragma

    perlutil            utilities packaged with the Perl distribution

    perlfilter          Perl source filters

    perldtrace          Perl's support for DTrace

    perlglossary        Perl Glossary









Next: , Previous: perl Reference Manual, Up: perl GETTING HELP   [Contents]





1.3.4 Internals and C Language Interface



    perlembed           Perl ways to embed perl in your C or C++ application
    perldebguts         Perl debugging guts and tips
    perlxstut           Perl XS tutorial
    perlxs              Perl XS application programming interface
    perlxstypemap       Perl XS C/Perl type conversion tools
    perlclib            Internal replacements for standard C library functions
    perlguts            Perl internal functions for those doing extensions
    perlcall            Perl calling conventions from C
    perlmroapi          Perl method resolution plugin interface
    perlreapi           Perl regular expression plugin interface
    perlreguts          Perl regular expression engine internals

    perlapi             Perl API listing (autogenerated)
    perlintern          Perl internal functions (autogenerated)
    perliol             C API for Perl's implementation of IO in Layers
    perlapio            Perl internal IO abstraction interface

    perlhack            Perl hackers guide
    perlsource          Guide to the Perl source tree
    perlinterp          Overview of the Perl interpreter source and how it works
    perlhacktut         Walk through the creation of a simple C code patch
    perlhacktips        Tips for Perl core C code hacking
    perlpolicy          Perl development policies
    perlgit             Using git with the Perl repository









Next: , Previous: perl Internals and C Language Interface, Up: perl GETTING HELP   [Contents]





1.3.5 Miscellaneous



    perlbook            Perl book information
    perlcommunity       Perl community information

    perldoc             Look up Perl documentation in Pod format

    perlhist            Perl history records
    perldelta           Perl changes since previous version
    perl5162delta       Perl changes in version 5.16.2
    perl5161delta       Perl changes in version 5.16.1
    perl5160delta       Perl changes in version 5.16.0
    perl5160delta       Perl changes in version 5.16.0
    perl5143delta       Perl changes in version 5.14.3
    perl5142delta       Perl changes in version 5.14.2
    perl5141delta       Perl changes in version 5.14.1
    perl5140delta       Perl changes in version 5.14.0
    perl5124delta       Perl changes in version 5.12.4
    perl5123delta       Perl changes in version 5.12.3
    perl5122delta       Perl changes in version 5.12.2
    perl5121delta       Perl changes in version 5.12.1
    perl5120delta       Perl changes in version 5.12.0
    perl5101delta       Perl changes in version 5.10.1
    perl5100delta       Perl changes in version 5.10.0
    perl589delta        Perl changes in version 5.8.9
    perl588delta        Perl changes in version 5.8.8
    perl587delta        Perl changes in version 5.8.7
    perl586delta        Perl changes in version 5.8.6
    perl585delta        Perl changes in version 5.8.5
    perl584delta        Perl changes in version 5.8.4
    perl583delta        Perl changes in version 5.8.3
    perl582delta        Perl changes in version 5.8.2
    perl581delta        Perl changes in version 5.8.1
    perl58delta         Perl changes in version 5.8.0
    perl561delta        Perl changes in version 5.6.1
    perl56delta         Perl changes in version 5.6
    perl5005delta       Perl changes in version 5.005
    perl5004delta       Perl changes in version 5.004

    perlexperiment      A listing of experimental features in Perl

    perlartistic        Perl Artistic License
    perlgpl             GNU General Public License









Next: , Previous: perl Miscellaneous, Up: perl GETTING HELP   [Contents]





1.3.6 Language-Specific



    perlcn              Perl for Simplified Chinese (in EUC-CN)
    perljp              Perl for Japanese (in EUC-JP)
    perlko              Perl for Korean (in EUC-KR)
    perltw              Perl for Traditional Chinese (in Big5)









Next: , Previous: perl Language-Specific, Up: perl GETTING HELP   [Contents]





1.3.7 Platform-Specific



    perlaix             Perl notes for AIX
    perlamiga           Perl notes for AmigaOS
    perlbeos            Perl notes for BeOS
    perlbs2000          Perl notes for POSIX-BC BS2000
    perlce              Perl notes for WinCE
    perlcygwin          Perl notes for Cygwin
    perldgux            Perl notes for DG/UX
    perldos             Perl notes for DOS
    perlepoc            Perl notes for EPOC
    perlfreebsd         Perl notes for FreeBSD
    perlhaiku           Perl notes for Haiku
    perlhpux            Perl notes for HP-UX
    perlhurd            Perl notes for Hurd
    perlirix            Perl notes for Irix
    perllinux           Perl notes for Linux
    perlmacos           Perl notes for Mac OS (Classic)
    perlmacosx          Perl notes for Mac OS X
    perlmpeix           Perl notes for MPE/iX
    perlnetware         Perl notes for NetWare
    perlopenbsd         Perl notes for OpenBSD
    perlos2             Perl notes for OS/2
    perlos390           Perl notes for OS/390
    perlos400           Perl notes for OS/400
    perlplan9           Perl notes for Plan 9
    perlqnx             Perl notes for QNX
    perlriscos          Perl notes for RISC OS
    perlsolaris         Perl notes for Solaris
    perlsymbian         Perl notes for Symbian
    perltru64           Perl notes for Tru64
    perluts             Perl notes for UTS
    perlvmesa           Perl notes for VM/ESA
    perlvms             Perl notes for VMS
    perlvos             Perl notes for Stratus VOS
    perlwin32           Perl notes for Windows









Previous: perl Platform-Specific, Up: perl GETTING HELP   [Contents]





1.3.8 Stubs for Deleted Documents



    perlboot            
    perlbot             
    perltodo
    perltooc            
    perltoot            



On a Unix-like system, these documentation files will usually also be
available as manpages for use with the man program.



In general, if something strange has gone wrong with your program and you’re
not sure where you should look for help, try the -w switch first.  It will
often point out exactly where the trouble is.









Next: , Previous: perl GETTING HELP, Up: perl   [Contents]





1.4 DESCRIPTION



Perl officially stands for Practical Extraction and Report Language,
except when it doesn’t.



Perl was originally a language optimized for scanning arbitrary
text files, extracting information from those text files, and printing
reports based on that information.  It quickly became a good language
for many system management tasks. Over the years, Perl has grown into
a general-purpose programming language. It’s widely used for everything
from quick "one-liners" to full-scale application development.



The language is intended to be practical (easy to use, efficient,
complete) rather than beautiful (tiny, elegant, minimal).



Perl combines (in the author’s opinion, anyway) some of the best
features of C, sed, awk, and sh, so people familiar with
those languages should have little difficulty with it.  (Language
historians will also note some vestiges of csh, Pascal, and even
BASIC-PLUS.)  Expression syntax corresponds closely to C
expression syntax.  Unlike most Unix utilities, Perl does not
arbitrarily limit the size of your data–if you’ve got the memory,
Perl can slurp in your whole file as a single string.  Recursion is of
unlimited depth.  And the tables used by hashes (sometimes called
"associative arrays") grow as necessary to prevent degraded
performance.  Perl can use sophisticated pattern matching techniques to
scan large amounts of data quickly.  Although optimized for
scanning text, Perl also has many excellent tools for slicing
and dicing binary data.



But wait, there’s more...



Begun in 1993 (see perlhist NAME), Perl version 5 is nearly a complete
rewrite that provides the following additional benefits:





Okay, that’s definitely enough hype.









Next: , Previous: perl DESCRIPTION, Up: perl   [Contents]





1.5 AVAILABILITY



Perl is available for most operating systems, including virtually
all Unix-like platforms.  See perlport Supported Platforms
for a listing.









Next: , Previous: perl AVAILABILITY, Up: perl   [Contents]





1.6 ENVIRONMENT



See perlrun NAME.









Next: , Previous: perl ENVIRONMENT, Up: perl   [Contents]





1.7 AUTHOR



Larry Wall <larry@wall.org>, with the help of oodles of other folks.



If your Perl success stories and testimonials may be of help to others 
who wish to advocate the use of Perl in their applications, 
or if you wish to simply express your gratitude to Larry and the 
Perl developers, please write to perl-thanks@perl.org .









Next: , Previous: perl AUTHOR, Up: perl   [Contents]





1.8 FILES



 "@INC"                 locations of perl libraries









Next: , Previous: perl FILES, Up: perl   [Contents]





1.9 SEE ALSO



 http://www.perl.org/       the Perl homepage
 http://www.perl.com/       Perl articles (O'Reilly)
 http://www.cpan.org/       the Comprehensive Perl Archive
 http://www.pm.org/         the Perl Mongers









Next: , Previous: perl SEE ALSO, Up: perl   [Contents]





1.10 DIAGNOSTICS



The use warnings pragma (and the -w switch) produces some 
lovely diagnostics.



See perldiag NAME for explanations of all Perl’s diagnostics.  The use
diagnostics pragma automatically turns Perl’s normally terse warnings
and errors into these longer forms.



Compilation errors will tell you the line number of the error, with an
indication of the next token or token type that was to be examined.
(In a script passed to Perl via -e switches, each
-e is counted as one line.)



Setuid scripts have additional constraints that can produce error
messages such as "Insecure dependency".  See perlsec NAME.



Did we mention that you should definitely consider using the -w
switch?









Next: , Previous: perl DIAGNOSTICS, Up: perl   [Contents]





1.11 BUGS



The -w switch is not mandatory.



Perl is at the mercy of your machine’s definitions of various
operations such as type casting, atof(), and floating-point
output with sprintf().



If your stdio requires a seek or eof between reads and writes on a
particular stream, so does Perl.  (This doesn’t apply to sysread()
and syswrite().)



While none of the built-in data types have any arbitrary size limits
(apart from memory size), there are still a few arbitrary limits:  a
given variable name may not be longer than 251 characters.  Line numbers
displayed by diagnostics are internally stored as short integers,
so they are limited to a maximum of 65535 (higher numbers usually being
affected by wraparound).



You may mail your bug reports (be sure to include full configuration
information as output by the myconfig program in the perl source
tree, or by perl -V) to perlbug@perl.org .  If you’ve succeeded
in compiling perl, the (perlbug) script in the utils/ subdirectory
can be used to help mail in a bug report.



Perl actually stands for Pathologically Eclectic Rubbish Lister, but
don’t tell anyone I said that.









Previous: perl BUGS, Up: perl   [Contents]





1.12 NOTES



The Perl motto is "There’s more than one way to do it."  Divining
how many more is left as an exercise to the reader.



The three principal virtues of a programmer are Laziness,
Impatience, and Hubris.  See the Camel Book for why.









Next: , Previous: perl, Up: Top   [Contents]





2 perlapio





• perlapio NAME:  



• perlapio SYNOPSIS:  



• perlapio DESCRIPTION:  












Next: , Up: perlapio   [Contents]





2.1 NAME



perlapio - perl’s IO abstraction interface.









Next: , Previous: perlapio NAME, Up: perlapio   [Contents]





2.2 SYNOPSIS



    #define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */
    #include <perlio.h>           /* Usually via #include <perl.h> */

    PerlIO *PerlIO_stdin(void);
    PerlIO *PerlIO_stdout(void);
    PerlIO *PerlIO_stderr(void);

    PerlIO *PerlIO_open(const char *path,const char *mode);
    PerlIO *PerlIO_fdopen(int fd, const char *mode);
    PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old);  /* deprecated */
    int     PerlIO_close(PerlIO *f);

    int     PerlIO_stdoutf(const char *fmt,...)
    int     PerlIO_puts(PerlIO *f,const char *string);
    int     PerlIO_putc(PerlIO *f,int ch);
    int     PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
    int     PerlIO_printf(PerlIO *f, const char *fmt,...);
    int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
    int     PerlIO_flush(PerlIO *f);

    int     PerlIO_eof(PerlIO *f);
    int     PerlIO_error(PerlIO *f);
    void    PerlIO_clearerr(PerlIO *f);

    int     PerlIO_getc(PerlIO *d);
    int     PerlIO_ungetc(PerlIO *f,int ch);
    int     PerlIO_read(PerlIO *f, void *buf, size_t numbytes);

    int     PerlIO_fileno(PerlIO *f);

    void    PerlIO_setlinebuf(PerlIO *f);

    Off_t   PerlIO_tell(PerlIO *f);
    int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
    void    PerlIO_rewind(PerlIO *f);

    int     PerlIO_getpos(PerlIO *f, SV *save);        /* prototype changed */
    int     PerlIO_setpos(PerlIO *f, SV *saved);       /* prototype changed */

    int     PerlIO_fast_gets(PerlIO *f);
    int     PerlIO_has_cntptr(PerlIO *f);
    int     PerlIO_get_cnt(PerlIO *f);
    char   *PerlIO_get_ptr(PerlIO *f);
    void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count);

    int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
    void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */

    int     PerlIO_has_base(PerlIO *f);
    char   *PerlIO_get_base(PerlIO *f);
    int     PerlIO_get_bufsiz(PerlIO *f);

    PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
    FILE   *PerlIO_exportFILE(PerlIO *f, int flags);
    FILE   *PerlIO_findFILE(PerlIO *f);
    void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);

    int     PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
    int     PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
    void    PerlIO_debug(const char *fmt,...)









Previous: perlapio SYNOPSIS, Up: perlapio   [Contents]





2.3 DESCRIPTION



Perl’s source code, and extensions that want maximum portability,
should use the above functions instead of those defined in ANSI C’s
stdio.h.  The perl headers (in particular "perlio.h") will
#define them to the I/O mechanism selected at Configure time.



The functions are modeled on those in stdio.h, but parameter order
has been "tidied up a little".



PerlIO * takes the place of FILE *. Like FILE * it should be
treated as opaque (it is probably safe to assume it is a pointer to
something).



There are currently three implementations:





1. USE_STDIO




All above are #define’d to stdio functions or are trivial wrapper
functions which call stdio. In this case only PerlIO * is a FILE *.
This has been the default implementation since the abstraction was
introduced in perl5.003_02.





2. USE_SFIO




A "legacy" implementation in terms of the "sfio" library. Used for
some specialist applications on Unix machines ("sfio" is not widely
ported away from Unix).  Most of above are #define’d to the sfio
functions. PerlIO * is in this case Sfio_t *.





3. USE_PERLIO




Introduced just after perl5.7.0, this is a re-implementation of the
above abstraction which allows perl more control over how IO is done
as it decouples IO from the way the operating system and C library
choose to do things. For USE_PERLIO PerlIO * has an extra layer of
indirection - it is a pointer-to-a-pointer.  This allows the PerlIO *
to remain with a known value while swapping the implementation around
underneath at run time. In this case all the above are true (but
very simple) functions which call the underlying implementation.



This is the only implementation for which PerlIO_apply_layers()
does anything "interesting".



The USE_PERLIO implementation is described in perliol NAME.








Because "perlio.h" is a thin layer (for efficiency) the semantics of
these functions are somewhat dependent on the underlying implementation.
Where these variations are understood they are noted below.



Unless otherwise noted, functions return 0 on success, or a negative
value (usually EOF which is usually -1) and set errno on error.





PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()




Use these rather than stdin, stdout, stderr. They are written
to look like "function calls" rather than variables because this makes
it easier to make them function calls if platform cannot export data
to loaded modules, or if (say) different "threads" might have different
values.





PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)




These correspond to fopen()/fdopen() and the arguments are the same.
Return NULL and set errno if there is an error.  There may be an
implementation limit on the number of open handles, which may be lower
than the limit on the number of open files - errno may not be set
when NULL is returned if this limit is exceeded.





PerlIO_reopen(path,mode,f)




While this currently exists in all three implementations perl itself
does not use it. As perl does not use it, it is not well tested.



Perl prefers to dup the new low-level descriptor to the descriptor
used by the existing PerlIO. This may become the behaviour of this
function in the future.





PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)




These are fprintf()/vfprintf() equivalents.





PerlIO_stdoutf(fmt,...)




This is printf() equivalent. printf is #defined to this function,
so it is (currently) legal to use printf(fmt,...) in perl sources.





PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)




These correspond functionally to fread() and fwrite() but the
arguments and return values are different.  The PerlIO_read() and
PerlIO_write() signatures have been modeled on the more sane low level
read() and write() functions instead: The "file" argument is passed
first, there is only one "count", and the return value can distinguish
between error and EOF.



Returns a byte count if successful (which may be zero or
positive), returns negative value and sets errno on error.
Depending on implementation errno may be EINTR if operation was
interrupted by a signal.





PerlIO_close(f)




Depending on implementation errno may be EINTR if operation was
interrupted by a signal.





PerlIO_puts(f,s), PerlIO_putc(f,c)




These correspond to fputs() and fputc().
Note that arguments have been revised to have "file" first.





PerlIO_ungetc(f,c)




This corresponds to ungetc().  Note that arguments have been revised
to have "file" first.  Arranges that next read operation will return
the byte c.  Despite the implied "character" in the name only
values in the range 0..0xFF are defined. Returns the byte c on
success or -1 (EOF) on error.  The number of bytes that can be
"pushed back" may vary, only 1 character is certain, and then only if
it is the last character that was read from the handle.





PerlIO_getc(f)




This corresponds to getc().
Despite the c in the name only byte range 0..0xFF is supported.
Returns the character read or -1 (EOF) on error.





PerlIO_eof(f)




This corresponds to feof().  Returns a true/false indication of
whether the handle is at end of file.  For terminal devices this may
or may not be "sticky" depending on the implementation.  The flag is
cleared by PerlIO_seek(), or PerlIO_rewind().





PerlIO_error(f)




This corresponds to ferror().  Returns a true/false indication of
whether there has been an IO error on the handle.





PerlIO_fileno(f)




This corresponds to fileno(), note that on some platforms, the meaning
of "fileno" may not match Unix. Returns -1 if the handle has no open
descriptor associated with it.





PerlIO_clearerr(f)




This corresponds to clearerr(), i.e., clears ’error’ and (usually)
’eof’ flags for the "stream". Does not return a value.





PerlIO_flush(f)




This corresponds to fflush().  Sends any buffered write data to the
underlying file.  If called with NULL this may flush all open
streams (or core dump with some USE_STDIO implementations).  Calling
on a handle open for read only, or on which last operation was a read
of some kind may lead to undefined behaviour on some USE_STDIO
implementations.  The USE_PERLIO (layers) implementation tries to
behave better: it flushes all open streams when passed NULL, and
attempts to retain data on read streams either in the buffer or by
seeking the handle to the current logical position.





PerlIO_seek(f,offset,whence)




This corresponds to fseek().  Sends buffered write data to the
underlying file, or discards any buffered read data, then positions
the file descriptor as specified by offset and whence (sic).
This is the correct thing to do when switching between read and write
on the same handle (see issues with PerlIO_flush() above).  Offset is
of type Off_t which is a perl Configure value which may not be same
as stdio’s off_t.





PerlIO_tell(f)




This corresponds to ftell().  Returns the current file position, or
(Off_t) -1 on error.  May just return value system "knows" without
making a system call or checking the underlying file descriptor (so
use on shared file descriptors is not safe without a
PerlIO_seek()). Return value is of type Off_t which is a perl
Configure value which may not be same as stdio’s off_t.





PerlIO_getpos(f,p), PerlIO_setpos(f,p)




These correspond (loosely) to fgetpos() and fsetpos(). Rather than
stdio’s Fpos_t they expect a "Perl Scalar Value" to be passed. What is
stored there should be considered opaque. The layout of the data may
vary from handle to handle.  When not using stdio or if platform does
not have the stdio calls then they are implemented in terms of
PerlIO_tell() and PerlIO_seek().





PerlIO_rewind(f)




This corresponds to rewind(). It is usually defined as being



    PerlIO_seek(f,(Off_t)0L, SEEK_SET);
    PerlIO_clearerr(f);





PerlIO_tmpfile()




This corresponds to tmpfile(), i.e., returns an anonymous PerlIO or
NULL on error.  The system will attempt to automatically delete the
file when closed.  On Unix the file is usually unlink-ed just after
it is created so it does not matter how it gets closed. On other
systems the file may only be deleted if closed via PerlIO_close()
and/or the program exits via exit.  Depending on the implementation
there may be "race conditions" which allow other processes access to
the file, though in general it will be safer in this regard than
ad. hoc. schemes.





PerlIO_setlinebuf(f)




This corresponds to setlinebuf().  Does not return a value. What
constitutes a "line" is implementation dependent but usually means
that writing "\n" flushes the buffer.  What happens with things like
"this\nthat" is uncertain.  (Perl core uses it only when "dumping";
it has nothing to do with $| auto-flush.)










• perlapio Co-existence with stdio:  



• perlapio "Fast gets" Functions:  



• perlapio Other Functions:  












Next: , Up: perlapio DESCRIPTION   [Contents]





2.3.1 Co-existence with stdio



There is outline support for co-existence of PerlIO with stdio.
Obviously if PerlIO is implemented in terms of stdio there is no
problem. However in other cases then mechanisms must exist to create a
FILE * which can be passed to library code which is going to use stdio
calls.



The first step is to add this line:



   #define PERLIO_NOT_STDIO 0



before including any perl header files. (This will probably become
the default at some point).  That prevents "perlio.h" from attempting
to #define stdio functions onto PerlIO functions.



XS code is probably better using "typemap" if it expects FILE *
arguments.  The standard typemap will be adjusted to comprehend any
changes in this area.





PerlIO_importFILE(f,mode)




Used to get a PerlIO * from a FILE *.



The mode argument should be a string as would be passed to
fopen/PerlIO_open.  If it is NULL then - for legacy support - the code
will (depending upon the platform and the implementation) either
attempt to empirically determine the mode in which f is open, or
use "r+" to indicate a read/write stream.



Once called the FILE * should ONLY be closed by calling
PerlIO_close() on the returned PerlIO *.



The PerlIO is set to textmode. Use PerlIO_binmode if this is
not the desired mode.



This is not the reverse of PerlIO_exportFILE().





PerlIO_exportFILE(f,mode)




Given a PerlIO * create a ’native’ FILE * suitable for passing to code
expecting to be compiled and linked with ANSI C stdio.h.  The mode
argument should be a string as would be passed to fopen/PerlIO_open.
If it is NULL then - for legacy support - the FILE * is opened in same
mode as the PerlIO *.



The fact that such a FILE * has been ’exported’ is recorded, (normally
by pushing a new :stdio "layer" onto the PerlIO *), which may affect
future PerlIO operations on the original PerlIO *.  You should not
call fclose() on the file unless you call PerlIO_releaseFILE()
to disassociate it from the PerlIO *.  (Do not use PerlIO_importFILE()
for doing the disassociation.)



Calling this function repeatedly will create a FILE * on each call
(and will push an :stdio layer each time as well).





PerlIO_releaseFILE(p,f)




Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
complete. It is removed from the list of ’exported’ FILE *s, and the
associated PerlIO * should revert to its original behaviour.



Use this to disassociate a file from a PerlIO * that was associated
using PerlIO_exportFILE().





PerlIO_findFILE(f)




Returns a native FILE * used by a stdio layer. If there is none, it
will create one with PerlIO_exportFILE. In either case the FILE *
should be considered as belonging to PerlIO subsystem and should
only be closed by calling PerlIO_close().














Next: , Previous: perlapio Co-existence with stdio, Up: perlapio DESCRIPTION   [Contents]





2.3.2 "Fast gets" Functions



In addition to standard-like API defined so far above there is an
"implementation" interface which allows perl to get at internals of
PerlIO.  The following calls correspond to the various FILE_xxx macros
determined by Configure - or their equivalent in other
implementations. This section is really of interest to only those
concerned with detailed perl-core behaviour, implementing a PerlIO
mapping or writing code which can make use of the "read ahead" that
has been done by the IO system in the same way perl does. Note that
any code that uses these interfaces must be prepared to do things the
traditional way if a handle does not support them.





PerlIO_fast_gets(f)




Returns true if implementation has all the interfaces required to
allow perl’s sv_gets to "bypass" normal IO mechanism.  This can
vary from handle to handle.



  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                        PerlIO_canset_cnt(f) && \
                        'Can set pointer into buffer'





PerlIO_has_cntptr(f)




Implementation can return pointer to current position in the "buffer"
and a count of bytes available in the buffer.  Do not use this - use
PerlIO_fast_gets.





PerlIO_get_cnt(f)




Return count of readable bytes in the buffer. Zero or negative return
means no more bytes available.





PerlIO_get_ptr(f)




Return pointer to next readable byte in buffer, accessing via the
pointer (dereferencing) is only safe if PerlIO_get_cnt() has returned
a positive value.  Only positive offsets up to value returned by
PerlIO_get_cnt() are allowed.





PerlIO_set_ptrcnt(f,p,c)




Set pointer into buffer, and a count of bytes still in the
buffer. Should be used only to set pointer to within range implied by
previous calls to PerlIO_get_ptr and PerlIO_get_cnt. The two
values must be consistent with each other (implementation may only
use one or the other or may require both).





PerlIO_canset_cnt(f)




Implementation can adjust its idea of number of bytes in the buffer.
Do not use this - use PerlIO_fast_gets.





PerlIO_set_cnt(f,c)




Obscure - set count of bytes in the buffer. Deprecated.  Only usable
if PerlIO_canset_cnt() returns true.  Currently used in only doio.c to
force count less than -1 to -1.  Perhaps should be PerlIO_set_empty or
similar.  This call may actually do nothing if "count" is deduced from
pointer and a "limit".  Do not use this - use PerlIO_set_ptrcnt().





PerlIO_has_base(f)




Returns true if implementation has a buffer, and can return pointer
to whole buffer and its size. Used by perl for -T / -B tests.
Other uses would be very obscure...





PerlIO_get_base(f)




Return start of buffer. Access only positive offsets in the buffer
up to the value returned by PerlIO_get_bufsiz().





PerlIO_get_bufsiz(f)




Return the total number of bytes in the buffer, this is neither the
number that can be read, nor the amount of memory allocated to the
buffer. Rather it is what the operating system and/or implementation
happened to read() (or whatever) last time IO was requested.














Previous: perlapio "Fast gets" Functions, Up: perlapio DESCRIPTION   [Contents]





2.3.3 Other Functions





PerlIO_apply_layers(f,mode,layers)




The new interface to the USE_PERLIO implementation. The layers ":crlf"
and ":raw" are only ones allowed for other implementations and those
are silently ignored. (As of perl5.8 ":raw" is deprecated.)  Use
PerlIO_binmode() below for the portable case.





PerlIO_binmode(f,ptype,imode,layers)




The hook used by perl’s binmode operator.
ptype is perl’s character for the kind of IO:





’<’ read






’>’ write






’+’ read/write









imode is O_BINARY or O_TEXT.



layers is a string of layers to apply, only ":crlf" makes sense in
the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour
of passing NULL.)



Portable cases are:



    PerlIO_binmode(f,ptype,O_BINARY,NULL);
and
    PerlIO_binmode(f,ptype,O_TEXT,":crlf");



On Unix these calls probably have no effect whatsoever.  Elsewhere
they alter "\n" to CR,LF translation and possibly cause a special text
"end of file" indicator to be written or honoured on read. The effect
of making the call after doing any IO to the handle depends on the
implementation. (It may be ignored, affect any data which is already
buffered as well, or only apply to subsequent data.)





PerlIO_debug(fmt,...)




PerlIO_debug is a printf()-like function which can be used for
debugging.  No return value. Its main use is inside PerlIO where using
real printf, warn() etc. would recursively call PerlIO and be a
problem.



PerlIO_debug writes to the file named by $ENV{’PERLIO_DEBUG’} typical
use might be



  Bourne shells (sh, ksh, bash, zsh, ash, ...):
   PERLIO_DEBUG=/dev/tty ./perl somescript some args

  Csh/Tcsh:
   setenv PERLIO_DEBUG /dev/tty
   ./perl somescript some args

  If you have the "env" utility:
   env PERLIO_DEBUG=/dev/tty ./perl somescript some args

  Win32:
   set PERLIO_DEBUG=CON
   perl somescript some args



If $ENV{’PERLIO_DEBUG’} is not set PerlIO_debug() is a no-op.














Next: , Previous: perlapio, Up: Top   [Contents]





3 perlartistic





• perlartistic NAME:  



• perlartistic SYNOPSIS:  



• perlartistic DESCRIPTION:  



• perlartistic The "Artistic License":  












Next: , Up: perlartistic   [Contents]





3.1 NAME



perlartistic - the Perl Artistic License









Next: , Previous: perlartistic NAME, Up: perlartistic   [Contents]





3.2 SYNOPSIS



 You can refer to this document in Pod via "L<perlartistic>"
 Or you can see this document by entering "perldoc perlartistic"









Next: , Previous: perlartistic SYNOPSIS, Up: perlartistic   [Contents]





3.3 DESCRIPTION



Perl is free software; you can redistribute it and/or modify
it under the terms of either:



        a) the GNU General Public License as published by the Free
        Software Foundation; either version 1, or (at your option) any
        later version, or

        b) the "Artistic License" which comes with this Kit.



This is "The Artistic License".
It’s here so that modules, programs, etc., that want to declare
this as their distribution license can link to it.



For the GNU General Public License, see perlgpl NAME.









Previous: perlartistic DESCRIPTION, Up: perlartistic   [Contents]





3.4 The "Artistic License"





• perlartistic Preamble:  



• perlartistic Definitions:  



• perlartistic Conditions:  












Next: , Up: perlartistic The "Artistic License"   [Contents]





3.4.1 Preamble



The intent of this document is to state the conditions under which a
Package may be copied, such that the Copyright Holder maintains some
semblance of artistic control over the development of the package,
while giving the users of the package the right to use and distribute
the Package in a more-or-less customary fashion, plus the right to make
reasonable modifications.









Next: , Previous: perlartistic Preamble, Up: perlartistic The "Artistic License"   [Contents]





3.4.2 Definitions





"Package"




refers to the collection of files distributed by the
Copyright Holder, and derivatives of that collection of files created
through textual modification.





"Standard Version"




refers to such a Package if it has not been
modified, or has been modified in accordance with the wishes of the
Copyright Holder as specified below.





"Copyright Holder"




is whoever is named in the copyright or
copyrights for the package.





"You"




is you, if you’re thinking about copying or distributing this Package.





"Reasonable copying fee"




is whatever you can justify on the basis
of media cost, duplication charges, time of people involved, and so on.
(You will not be required to justify it to the Copyright Holder, but
only to the computing community at large as a market that must bear the
fee.)





"Freely Available"




means that no fee is charged for the item
itself, though there may be fees involved in handling the item. It also
means that recipients of the item may redistribute it under the same
conditions they received it.














Previous: perlartistic Definitions, Up: perlartistic The "Artistic License"   [Contents]





3.4.3 Conditions



    

  1.  You may make and give away verbatim copies of the source form of the
Standard Version of this Package without restriction, provided that you
duplicate all of the original copyright notices and associated disclaimers.


  2.  You may apply bug fixes, portability fixes and other modifications
derived from the Public Domain or from the Copyright Holder.  A Package
modified in such a way shall still be considered the Standard Version.


  3.  You may otherwise modify your copy of this Package in any way, provided
that you insert a prominent notice in each changed file stating how and
when you changed that file, and provided that you do at least ONE of the
following:


    

    a)
    

    

    place your modifications in the Public Domain or otherwise make them
Freely Available, such as by posting said modifications to Usenet or an
equivalent medium, or placing the modifications on a major archive site
such as uunet.uu.net, or by allowing the Copyright Holder to include
your modifications in the Standard Version of the Package.

    

    

    b)
    

    

    use the modified Package only within your corporation or organization.

    

    

    c)
    

    

    rename any non-standard executables so the names do not conflict with
standard executables, which must also be provided, and provide a
separate manual page for each non-standard executable that clearly
documents how it differs from the Standard Version.

    

    

    d)
    

    

    make other distribution arrangements with the Copyright Holder.

    

    

    


  4.  You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:


    

    a)
    

    

    distribute a Standard Version of the executables and library files,
together with instructions (in the manual page or equivalent) on where
to get the Standard Version.

    

    

    b)
    

    

    accompany the distribution with the machine-readable source of the
Package with your modifications.

    

    

    c)
    

    

    give non-standard executables non-standard names, and clearly
document the differences in manual pages (or equivalent), together with
instructions on where to get the Standard Version.

    

    

    d)
    

    

    make other distribution arrangements with the Copyright Holder.

    

    

    


  5.  You may charge a reasonable copying fee for any distribution of this
Package.  You may charge any fee you choose for support of this
Package.  You may not charge a fee for this Package itself.  However,
you may distribute this Package in aggregate with other (possibly
commercial) programs as part of a larger (possibly commercial) software
distribution provided that you do not advertise this Package as a
product of your own.  You may embed this Package’s interpreter within
an executable of yours (by linking); this shall be construed as a mere
form of aggregation, provided that the complete Standard Version of the
interpreter is so embedded.


  6.  The scripts and library files supplied as input to or produced as
output from the programs of this Package do not automatically fall
under the copyright of this Package, but belong to whoever generated
them, and may be sold commercially, and may be aggregated with this
Package.  If such scripts or library files are aggregated with this
Package via the so-called "undump" or "unexec" methods of producing a
binary executable image, then distribution of such an image shall
neither be construed as a distribution of this Package nor shall it
fall under the restrictions of Paragraphs 3 and 4, provided that you do
not represent such an executable image as a Standard Version of this
Package.


  7.  C subroutines (or comparably compiled subroutines in other
languages) supplied by you and linked into this Package in order to
emulate subroutines and variables of the language defined by this
Package shall not be considered part of this Package, but are the
equivalent of input as in Paragraph 6, provided these subroutines do
not change the language in any way that would cause it to fail the
regression tests for the language.


  8.  Aggregation of this Package with a commercial distribution is always
permitted provided that the use of this Package is embedded; that is,
when no overt attempt is made to make this Package’s interfaces visible
to the end user of the commercial distribution.  Such use shall not be
construed as a distribution of this Package.


  9.  The name of the Copyright Holder may not be used to endorse or promote
products derived from this software without specific prior written permission.


  10.  THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.





The End









Next: , Previous: perlartistic, Up: Top   [Contents]





4 perlbook





• perlbook NAME:  



• perlbook DESCRIPTION:  












Next: , Up: perlbook   [Contents]





4.1 NAME



perlbook - Books about and related to Perl









Previous: perlbook NAME, Up: perlbook   [Contents]





4.2 DESCRIPTION



There are many books on Perl and Perl-related. A few of these are
good, some are OK, but many aren’t worth your money. There is a list
of these books, some with extensive reviews, at http://books.perl.org/
. We list some of the books here, and while listing a book implies our
endorsement, don’t think that not including a book means anything.



Most of these books are available online through Safari Books Online
( http://safaribooksonline.com/ ).





• perlbook The most popular books:  



• perlbook References:  



• perlbook Tutorials:  



• perlbook Task-Oriented:  



• perlbook Special Topics:  



• perlbook Free (as in beer) books:  



• perlbook Other interesting, non-Perl books:  



• perlbook A note on freshness:  



• perlbook Get your book listed:  












Next: , Up: perlbook DESCRIPTION   [Contents]





4.2.1 The most popular books



The major reference book on Perl, written by the creator of Perl, is
Programming Perl:





Programming Perl (the "Camel Book"):




        by Larry Wall, Tom Christiansen, and Jon Orwant
        ISBN 978-0-596-00027-1  [3rd edition July 2000]
        http://oreilly.com/catalog/9780596000271/








The Ram is a cookbook with hundreds of examples of using Perl to
accomplish specific tasks:





The Perl Cookbook (the "Ram Book"):




        by Tom Christiansen and Nathan Torkington,
            with Foreword by Larry Wall
        ISBN 978-0-596-00313-5 [2nd Edition August 2003]
        http://oreilly.com/catalog/9780596003135/








If you want to learn the basics of Perl, you might start with the
Llama book, which assumes that you already know a little about
programming:





Learning Perl  (the "Llama Book")




        by Randal L. Schwartz, Tom Phoenix, and brian d foy
        ISBN 978-0-596-52011-3 [5th edition June 2008]
        http://oreilly.com/catalog/9780596520113








The tutorial started in the Llama continues in the Alpaca, which
introduces the intermediate features of references, data structures,
object-oriented programming, and modules:





Intermediate Perl (the "Alpaca Book")




        by Randal L. Schwartz and brian d foy, with Tom Phoenix
                foreword by Damian Conway
        ISBN 978-0-596-00478-1 [1st edition March 2006]
        http://oreilly.com/catalog/9780596004781/














Next: , Previous: perlbook The most popular books, Up: perlbook DESCRIPTION   [Contents]





4.2.2 References



You might want to keep these desktop references close by your keyboard:





Perl 5 Pocket Reference




        by Johan Vromans
        ISBN 978-0-596-00374-6 [4th edition July 2002]
        http://oreilly.com/catalog/9780596003746/





Perl Debugger Pocket Reference




        by Richard Foley
        ISBN 978-0-596-00503-0 [1st edition January 2004]
        http://oreilly.com/catalog/9780596005030/





Regular Expression Pocket Reference




        by Tony Stubblebine
        ISBN 978-0-596-51427-3 [July 2007]
        http://oreilly.com/catalog/9780596514273/














Next: , Previous: perlbook References, Up: perlbook DESCRIPTION   [Contents]





4.2.3 Tutorials





Beginning Perl




        by James Lee
        ISBN 1-59059-391-X [3rd edition April 2010]
        http://www.apress.com/9781430227939





Learning Perl




        by Randal L. Schwartz, Tom Phoenix, and brian d foy
        ISBN 978-0-596-52010-6 [5th edition June 2008]
        http://oreilly.com/catalog/9780596520106





Intermediate Perl (the "Alpaca Book")




        by Randal L. Schwartz and brian d foy, with Tom Phoenix
                foreword by Damian Conway
        ISBN 0-596-10206-2 [1st edition March 2006]
        http://oreilly.com/catalog/9780596102067





Mastering Perl




        by brian d foy
        ISBN 978-0-596-10206-7 [1st edition July 2007]
        http://www.oreilly.com/catalog/9780596527242





Effective Perl Programming




        by Joseph N. Hall, Joshua A. McAdams, brian d foy
        ISBN 0-321-49694-9 [2nd edition 2010]
        http://www.effectiveperlprogramming.com/














Next: , Previous: perlbook Tutorials, Up: perlbook DESCRIPTION   [Contents]





4.2.4 Task-Oriented





Writing Perl Modules for CPAN




        by Sam Tregar
        ISBN 1-59059-018-X [1st edition August 2002]
        http://www.apress.com/9781590590188





The Perl Cookbook




        by Tom Christiansen and Nathan Torkington
            with foreword by Larry Wall
        ISBN 1-56592-243-3 [2nd edition August 2003]
        http://oreilly.com/catalog/9780596003135





Automating System Administration with Perl




        by David N. Blank-Edelman
        ISBN 978-0-596-00639-6 [2nd edition May 2009]
        http://oreilly.com/catalog/9780596006396





Real World SQL Server Administration with Perl




        by Linchi Shea
        ISBN 1-59059-097-X [1st edition July 2003]
        http://www.apress.com/9781590590973














Next: , Previous: perlbook Task-Oriented, Up: perlbook DESCRIPTION   [Contents]





4.2.5 Special Topics





Regular Expressions Cookbook




        by Jan Goyvaerts and Steven Levithan
        ISBN 978-0-596-52069-4 [May 2009]
        http://oreilly.com/catalog/9780596520694





Programming the Perl DBI




        by Tim Bunce and Alligator Descartes
        ISBN 978-1-56592-699-8 [February 2000]
        http://oreilly.com/catalog/9781565926998





Perl Best Practices




        by Damian Conway
        ISBN: 978-0-596-00173-5 [1st edition July 2005]
        http://oreilly.com/catalog/9780596001735





Higher-Order Perl




        by Mark-Jason Dominus
        ISBN: 1-55860-701-3 [1st edition March 2005]
        http://hop.perl.plover.com/





Mastering Regular Expressions




        by Jeffrey E. F. Friedl
        ISBN 978-0-596-52812-6 [3rd edition August 2006]
        http://oreilly.com/catalog/9780596528126





Network Programming with Perl




        by Lincoln Stein
        ISBN 0-201-61571-1 [1st edition 2001]
        http://www.pearsonhighered.com/educator/product/Network-Programming-with-Perl/9780201615715.page





Perl Template Toolkit




        by Darren Chamberlain, Dave Cross, and Andy Wardley
        ISBN 978-0-596-00476-7 [December 2003]
        http://oreilly.com/catalog/9780596004767





Object Oriented Perl




        by Damian Conway
            with foreword by Randal L. Schwartz
        ISBN 1-884777-79-1 [1st edition August 1999]
        http://www.manning.com/conway/





Data Munging with Perl




        by Dave Cross
        ISBN 1-930110-00-6 [1st edition 2001]
        http://www.manning.com/cross





Mastering Perl/Tk




        by Steve Lidie and Nancy Walsh
        ISBN 978-1-56592-716-2 [1st edition January 2002]
        http://oreilly.com/catalog/9781565927162





Extending and Embedding Perl




        by Tim Jenness and Simon Cozens
        ISBN 1-930110-82-0 [1st edition August 2002]
        http://www.manning.com/jenness





Pro Perl Debugging




        by Richard Foley with Andy Lester
        ISBN 1-59059-454-1 [1st edition July 2005]
        http://www.apress.com/9781590594544














Next: , Previous: perlbook Special Topics, Up: perlbook DESCRIPTION   [Contents]





4.2.6 Free (as in beer) books



Some of these books are available as free downloads.



Higher-Order Perl: http://hop.perl.plover.com/









Next: , Previous: perlbook Free (as in beer) books, Up: perlbook DESCRIPTION   [Contents]





4.2.7 Other interesting, non-Perl books



You might notice several familiar Perl concepts in this collection of
ACM columns from Jon Bentley. The similarity to the title of the major
Perl book (which came later) is not completely accidental:





Programming Pearls




        by Jon Bentley
        ISBN 978-0-201-65788-3 [2 edition, October 1999]





More Programming Pearls




        by Jon Bentley
        ISBN 0-201-11889-0 [January 1988]














Next: , Previous: perlbook Other interesting, non-Perl books, Up: perlbook DESCRIPTION   [Contents]





4.2.8 A note on freshness



Each version of Perl comes with the documentation that was current at
the time of release. This poses a problem for content such as book
lists. There are probably very nice books published after this list
was included in your Perl release, and you can check the latest
released version at http://perldoc.perl.org/perlbook.html .



Some of the books we’ve listed appear almost ancient in internet
scale, but we’ve included those books because they still describe the
current way of doing things. Not everything in Perl changes every day.
Many of the beginner-level books, too, go over basic features and
techniques that are still valid today. In general though, we try to
limit this list to books published in the past five years.









Previous: perlbook A note on freshness, Up: perlbook DESCRIPTION   [Contents]





4.2.9 Get your book listed



If your Perl book isn’t listed and you think it should be, let us know.









Next: , Previous: perlbook, Up: Top   [Contents]





5 perlboot





• perlboot NAME:  



• perlboot DESCRIPTION:  












Next: , Up: perlboot   [Contents]





5.1 NAME



perlboot - This document has been deleted









Previous: perlboot NAME, Up: perlboot   [Contents]





5.2 DESCRIPTION



For information on OO programming with Perl, please see perlootut NAME
and (perlobj).









Next: , Previous: perlboot, Up: Top   [Contents]





6 perlbot





• perlbot NAME:  



• perlbot DESCRIPTION:  












Next: , Up: perlbot   [Contents]





6.1 NAME



perlbot - This document has been deleted









Previous: perlbot NAME, Up: perlbot   [Contents]





6.2 DESCRIPTION



For information on OO programming with Perl, please see perlootut NAME
and (perlobj).









Next: , Previous: perlbot, Up: Top   [Contents]





7 perlcall





• perlcall NAME:  



• perlcall DESCRIPTION:  



• perlcall THE CALL_ FUNCTIONS:  



• perlcall FLAG VALUES:  



• perlcall EXAMPLES:  



• perlcall LIGHTWEIGHT CALLBACKS:  



• perlcall SEE ALSO:  



• perlcall AUTHOR:  



• perlcall DATE:  












Next: , Up: perlcall   [Contents]





7.1 NAME



perlcall - Perl calling conventions from C









Next: , Previous: perlcall NAME, Up: perlcall   [Contents]





7.2 DESCRIPTION



The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write callbacks.



Apart from discussing the C interface provided by Perl for writing
callbacks the document uses a series of examples to show how the
interface actually works in practice.  In addition some techniques for
coding callbacks are covered.



Examples where callbacks are necessary include





Although the techniques described here are applicable when embedding
Perl in a C program, this is not the primary goal of this document.
There are other details that must be considered and are specific to
embedding Perl. For details on embedding Perl in C refer to
perlembed NAME.



Before you launch yourself head first into the rest of this document,
it would be a good idea to have read the following two documents–(perlxs)
and perlguts NAME.









Next: , Previous: perlcall DESCRIPTION, Up: perlcall   [Contents]





7.3 THE CALL_ FUNCTIONS



Although this stuff is easier to explain using examples, you first need
be aware of a few important definitions.



Perl has a number of C functions that allow you to call Perl
subroutines.  They are



    I32 call_sv(SV* sv, I32 flags);
    I32 call_pv(char *subname, I32 flags);
    I32 call_method(char *methname, I32 flags);
    I32 call_argv(char *subname, I32 flags, register char **argv);



The key function is call_sv.  All the other functions are
fairly simple wrappers which make it easier to call Perl subroutines in
special cases. At the end of the day they will all call call_sv
to invoke the Perl subroutine.



All the call_* functions have a flags parameter which is
used to pass a bit mask of options to Perl.  This bit mask operates
identically for each of the functions.  The settings available in the
bit mask are discussed in FLAG VALUES.



Each of the functions will now be discussed in turn.





call_sv




call_sv takes two parameters. The first, sv, is an SV*.
This allows you to specify the Perl subroutine to be called either as a
C string (which has first been converted to an SV) or a reference to a
subroutine. The section, Using call_sv, shows how you can make
use of call_sv.





call_pv




The function, call_pv, is similar to call_sv except it
expects its first parameter to be a C char* which identifies the Perl
subroutine you want to call, e.g., call_pv("fred", 0).  If the
subroutine you want to call is in another package, just include the
package name in the string, e.g., "pkg::fred".





call_method




The function call_method is used to call a method from a Perl
class.  The parameter methname corresponds to the name of the method
to be called.  Note that the class that the method belongs to is passed
on the Perl stack rather than in the parameter list. This class can be
either the name of the class (for a static method) or a reference to an
object (for a virtual method).  See (perlobj) for more information on
static and virtual methods and Using call_method for an example
of using call_method.





call_argv




call_argv calls the Perl subroutine specified by the C string
stored in the subname parameter. It also takes the usual flags
parameter.  The final parameter, argv, consists of a NULL-terminated
list of C strings to be passed as parameters to the Perl subroutine.
See Using call_argv.








All the functions return an integer. This is a count of the number of
items returned by the Perl subroutine. The actual items returned by the
subroutine are stored on the Perl stack.



As a general rule you should always check the return value from
these functions.  Even if you are expecting only a particular number of
values to be returned from the Perl subroutine, there is nothing to
stop someone from doing something unexpected–don’t say you haven’t
been warned.









Next: , Previous: perlcall THE CALL_ FUNCTIONS, Up: perlcall   [Contents]





7.4 FLAG VALUES



The flags parameter in all the call_* functions is one of G_VOID,
G_SCALAR, or G_ARRAY, which indicate the call context, OR’ed together
with a bit mask of any combination of the other G_* symbols defined below.





• perlcall G_VOID:  



• perlcall G_SCALAR:  



• perlcall G_ARRAY:  



• perlcall G_DISCARD:  



• perlcall G_NOARGS:  



• perlcall G_EVAL:  



• perlcall G_KEEPERR:  



• perlcall Determining the Context:  












Next: , Up: perlcall FLAG VALUES   [Contents]





7.4.1 G_VOID



Calls the Perl subroutine in a void context.



This flag has 2 effects:



    

  1.  It indicates to the subroutine being called that it is executing in
a void context (if it executes wantarray the result will be the
undefined value).


  2.  It ensures that nothing is actually returned from the subroutine.





The value returned by the call_* function indicates how many
items have been returned by the Perl subroutine–in this case it will
be 0.









Next: , Previous: perlcall G_VOID, Up: perlcall FLAG VALUES   [Contents]





7.4.2 G_SCALAR



Calls the Perl subroutine in a scalar context.  This is the default
context flag setting for all the call_* functions.



This flag has 2 effects:



    

  1.  It indicates to the subroutine being called that it is executing in a
scalar context (if it executes wantarray the result will be false).


  2.  It ensures that only a scalar is actually returned from the subroutine.
The subroutine can, of course,  ignore the wantarray and return a
list anyway. If so, then only the last element of the list will be
returned.





The value returned by the call_* function indicates how many
items have been returned by the Perl subroutine - in this case it will
be either 0 or 1.



If 0, then you have specified the G_DISCARD flag.



If 1, then the item actually returned by the Perl subroutine will be
stored on the Perl stack - the section Returning a Scalar shows how
to access this value on the stack.  Remember that regardless of how
many items the Perl subroutine returns, only the last one will be
accessible from the stack - think of the case where only one value is
returned as being a list with only one element.  Any other items that
were returned will not exist by the time control returns from the
call_* function.  The section Returning a list in a scalar
context shows an example of this behavior.









Next: , Previous: perlcall G_SCALAR, Up: perlcall FLAG VALUES   [Contents]





7.4.3 G_ARRAY



Calls the Perl subroutine in a list context.



As with G_SCALAR, this flag has 2 effects:



    

  1.  It indicates to the subroutine being called that it is executing in a
list context (if it executes wantarray the result will be true).


  2.  It ensures that all items returned from the subroutine will be
accessible when control returns from the call_* function.





The value returned by the call_* function indicates how many
items have been returned by the Perl subroutine.



If 0, then you have specified the G_DISCARD flag.



If not 0, then it will be a count of the number of items returned by
the subroutine. These items will be stored on the Perl stack.  The
section Returning a list of values gives an example of using the
G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.









Next: , Previous: perlcall G_ARRAY, Up: perlcall FLAG VALUES   [Contents]





7.4.4 G_DISCARD



By default, the call_* functions place the items returned from
by the Perl subroutine on the stack.  If you are not interested in
these items, then setting this flag will make Perl get rid of them
automatically for you.  Note that it is still possible to indicate a
context to the Perl subroutine by using either G_SCALAR or G_ARRAY.



If you do not set this flag then it is very important that you make
sure that any temporaries (i.e., parameters passed to the Perl
subroutine and values returned from the subroutine) are disposed of
yourself.  The section Returning a Scalar gives details of how to
dispose of these temporaries explicitly and the section Using Perl to
dispose of temporaries discusses the specific circumstances where you
can ignore the problem and let Perl deal with it for you.









Next: , Previous: perlcall G_DISCARD, Up: perlcall FLAG VALUES   [Contents]





7.4.5 G_NOARGS



Whenever a Perl subroutine is called using one of the call_*
functions, it is assumed by default that parameters are to be passed to
the subroutine.  If you are not passing any parameters to the Perl
subroutine, you can save a bit of time by setting this flag.  It has
the effect of not creating the @_ array for the Perl subroutine.



Although the functionality provided by this flag may seem
straightforward, it should be used only if there is a good reason to do
so.  The reason for being cautious is that, even if you have specified
the G_NOARGS flag, it is still possible for the Perl subroutine that
has been called to think that you have passed it parameters.



In fact, what can happen is that the Perl subroutine you have called
can access the @_ array from a previous Perl subroutine.  This will
occur when the code that is executing the call_* function has
itself been called from another Perl subroutine. The code below
illustrates this



    sub fred
      { print "@_\n"  }

    sub joe
      { &fred }

    &joe(1,2,3);



This will print



    1 2 3



What has happened is that fred accesses the @_ array which
belongs to joe.









Next: , Previous: perlcall G_NOARGS, Up: perlcall FLAG VALUES   [Contents]





7.4.6 G_EVAL



It is possible for the Perl subroutine you are calling to terminate
abnormally, e.g., by calling die explicitly or by not actually
existing.  By default, when either of these events occurs, the
process will terminate immediately.  If you want to trap this
type of event, specify the G_EVAL flag.  It will put an eval { }
around the subroutine call.



Whenever control returns from the call_* function you need to
check the $@ variable as you would in a normal Perl script.



The value returned from the call_* function is dependent on
what other flags have been specified and whether an error has
occurred.  Here are all the different cases that can occur:





See Using G_EVAL for details on using G_EVAL.









Next: , Previous: perlcall G_EVAL, Up: perlcall FLAG VALUES   [Contents]





7.4.7 G_KEEPERR



Using the G_EVAL flag described above will always set $@: clearing
it if there was no error, and setting it to describe the error if there
was an error in the called code.  This is what you want if your intention
is to handle possible errors, but sometimes you just want to trap errors
and stop them interfering with the rest of the program.



This scenario will mostly be applicable to code that is meant to be called
from within destructors, asynchronous callbacks, and signal handlers.
In such situations, where the code being called has little relation to the
surrounding dynamic context, the main program needs to be insulated from
errors in the called code, even if they can’t be handled intelligently.
It may also be useful to do this with code for __DIE__ or __WARN__
hooks, and tie functions.



The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
call_* functions that are used to implement such code, or with
eval_sv.  This flag has no effect on the call_* functions when
G_EVAL is not used.



When G_KEEPERR is used, any error in the called code will terminate the
call as usual, and the error will not propagate beyond the call (as usual
for G_EVAL), but it will not go into $@.  Instead the error will be
converted into a warning, prefixed with the string "\t(in cleanup)".
This can be disabled using no warnings 'misc'.  If there is no error,
$@ will not be cleared.



Note that the G_KEEPERR flag does not propagate into inner evals; these
may still set $@.



The G_KEEPERR flag was introduced in Perl version 5.002.



See Using G_KEEPERR for an example of a situation that warrants the
use of this flag.









Previous: perlcall G_KEEPERR, Up: perlcall FLAG VALUES   [Contents]





7.4.8 Determining the Context



As mentioned above, you can determine the context of the currently
executing subroutine in Perl with wantarray.  The equivalent test
can be made in C by using the GIMME_V macro, which returns
G_ARRAY if you have been called in a list context, G_SCALAR if
in a scalar context, or G_VOID if in a void context (i.e., the
return value will not be used).  An older version of this macro is
called GIMME; in a void context it returns G_SCALAR instead of
G_VOID.  An example of using the GIMME_V macro is shown in
section Using GIMME_V.









Next: , Previous: perlcall FLAG VALUES, Up: perlcall   [Contents]





7.5 EXAMPLES



Enough of the definition talk! Let’s have a few examples.



Perl provides many macros to assist in accessing the Perl stack.
Wherever possible, these macros should always be used when interfacing
to Perl internals.  We hope this should make the code less vulnerable
to any changes made to Perl in the future.



Another point worth noting is that in the first series of examples I
have made use of only the call_pv function.  This has been done
to keep the code simpler and ease you into the topic.  Wherever
possible, if the choice is between using call_pv and
call_sv, you should always try to use call_sv.  See
Using call_sv for details.





• perlcall No Parameters, Nothing Returned:  



• perlcall Passing Parameters:  



• perlcall Returning a Scalar:  



• perlcall Returning a List of Values:  



• perlcall Returning a List in a Scalar Context:  



• perlcall Returning Data from Perl via the Parameter List:  



• perlcall Using G_EVAL:  



• perlcall Using G_KEEPERR:  



• perlcall Using call_sv:  



• perlcall Using call_argv:  



• perlcall Using call_method:  



• perlcall Using GIMME_V:  



• perlcall Using Perl to Dispose of Temporaries:  



• perlcall Strategies for Storing Callback Context Information:  



• perlcall Alternate Stack Manipulation:  



• perlcall Creating and Calling an Anonymous Subroutine in C:  












Next: , Up: perlcall EXAMPLES   [Contents]





7.5.1 No Parameters, Nothing Returned



This first trivial example will call a Perl subroutine, PrintUID, to
print out the UID of the process.



    sub PrintUID
    {
        print "UID is $<\n";
    }



and here is a C function to call it



    static void
    call_PrintUID()
    {
        dSP;

        PUSHMARK(SP);
        call_pv("PrintUID", G_DISCARD|G_NOARGS);
    }



Simple, eh?



A few points to note about this example:



    

  1.  Ignore dSP and PUSHMARK(SP) for now. They will be discussed in
the next example.


  2.  We aren’t passing any parameters to PrintUID so G_NOARGS can be
specified.


  3.  We aren’t interested in anything returned from PrintUID, so
G_DISCARD is specified. Even if PrintUID was changed to
return some value(s), having specified G_DISCARD will mean that they
will be wiped by the time control returns from call_pv.


  4.  As call_pv is being used, the Perl subroutine is specified as a
C string. In this case the subroutine name has been ’hard-wired’ into the
code.


  5.  Because we specified G_DISCARD, it is not necessary to check the value
returned from call_pv. It will always be 0.











Next: , Previous: perlcall No Parameters, Nothing Returned, Up: perlcall EXAMPLES   [Contents]





7.5.2 Passing Parameters



Now let’s make a slightly more complex example. This time we want to
call a Perl subroutine, LeftString, which will take 2 parameters–a
string ($s) and an integer ($n).  The subroutine will simply
print the first $n characters of the string.



So the Perl subroutine would look like this:



    sub LeftString
    {
        my($s, $n) = @_;
        print substr($s, 0, $n), "\n";
    }



The C function required to call LeftString would look like this:



    static void
    call_LeftString(a, b)
    char * a;
    int b;
    {
        dSP;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(a, 0)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        call_pv("LeftString", G_DISCARD);

        FREETMPS;
        LEAVE;
    }



Here are a few notes on the C function call_LeftString.



    

  1.  Parameters are passed to the Perl subroutine using the Perl stack.
This is the purpose of the code beginning with the line dSP and
ending with the line PUTBACK.  The dSP declares a local copy
of the stack pointer.  This local copy should always be accessed
as SP.


  2.  If you are going to put something onto the Perl stack, you need to know
where to put it. This is the purpose of the macro dSP–it declares
and initializes a local copy of the Perl stack pointer.


    All the other macros which will be used in this example require you to
have used this macro.

    

    The exception to this rule is if you are calling a Perl subroutine
directly from an XSUB function. In this case it is not necessary to
use the dSP macro explicitly–it will be declared for you
automatically.

    

  3.  Any parameters to be pushed onto the stack should be bracketed by the
PUSHMARK and PUTBACK macros.  The purpose of these two macros, in
this context, is to count the number of parameters you are
pushing automatically.  Then whenever Perl is creating the @_ array for the
subroutine, it knows how big to make it.


    The PUSHMARK macro tells Perl to make a mental note of the current
stack pointer. Even if you aren’t passing any parameters (like the
example shown in the section No Parameters, Nothing Returned) you
must still call the PUSHMARK macro before you can call any of the
call_* functions–Perl still needs to know that there are no
parameters.

    

    The PUTBACK macro sets the global copy of the stack pointer to be
the same as our local copy. If we didn’t do this, call_pv
wouldn’t know where the two parameters we pushed were–remember that
up to now all the stack pointer manipulation we have done is with our
local copy, not the global copy.

    

  4.  Next, we come to XPUSHs. This is where the parameters actually get
pushed onto the stack. In this case we are pushing a string and an
integer.


    See perlguts XSUBs and the Argument Stack for details
on how the XPUSH macros work.

    

  5.  Because we created temporary values (by means of sv_2mortal() calls)
we will have to tidy up the Perl stack and dispose of mortal SVs.


    This is the purpose of

    

        ENTER;
    SAVETMPS;

    

    at the start of the function, and

    

        FREETMPS;
    LEAVE;

    

    at the end. The ENTER/SAVETMPS pair creates a boundary for any
temporaries we create.  This means that the temporaries we get rid of
will be limited to those which were created after these calls.

    

    The FREETMPS/LEAVE pair will get rid of any values returned by
the Perl subroutine (see next example), plus it will also dump the
mortal SVs we have created.  Having ENTER/SAVETMPS at the
beginning of the code makes sure that no other mortals are destroyed.

    

    Think of these macros as working a bit like { and } in Perl
to limit the scope of local variables.

    

    See the section Using Perl to Dispose of Temporaries for details of
an alternative to using these macros.

    

  6.  Finally, LeftString can now be called via the call_pv function.
The only flag specified this time is G_DISCARD. Because we are passing
2 parameters to the Perl subroutine this time, we have not specified
G_NOARGS.











Next: , Previous: perlcall Passing Parameters, Up: perlcall EXAMPLES   [Contents]





7.5.3 Returning a Scalar



Now for an example of dealing with the items returned from a Perl
subroutine.



Here is a Perl subroutine, Adder, that takes 2 integer parameters
and simply returns their sum.



    sub Adder
    {
        my($a, $b) = @_;
        $a + $b;
    }



Because we are now concerned with the return value from Adder, the C
function required to call it is now a bit more complex.



    static void
    call_Adder(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("Adder", G_SCALAR);

        SPAGAIN;

        if (count != 1)
            croak("Big trouble\n");

        printf ("The sum of %d and %d is %d\n", a, b, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
    }



Points to note this time are



    

  1.  The only flag specified this time was G_SCALAR. That means that the @_
array will be created and that the value returned by Adder will
still exist after the call to call_pv.


  2.  The purpose of the macro SPAGAIN is to refresh the local copy of the
stack pointer. This is necessary because it is possible that the memory
allocated to the Perl stack has been reallocated during the
call_pv call.


    If you are making use of the Perl stack pointer in your code you must
always refresh the local copy using SPAGAIN whenever you make use
of the call_* functions or any other Perl internal function.

    

  3.  Although only a single value was expected to be returned from Adder,
it is still good practice to check the return code from call_pv
anyway.


    Expecting a single value is not quite the same as knowing that there
will be one. If someone modified Adder to return a list and we
didn’t check for that possibility and take appropriate action the Perl
stack would end up in an inconsistent state. That is something you
really don’t want to happen ever.

    

  4.  The POPi macro is used here to pop the return value from the stack.
In this case we wanted an integer, so POPi was used.


    Here is the complete list of POP macros available, along with the types
they return.

    

        POPs        SV
    POPp        pointer
    POPn        double
    POPi        integer
    POPl        long

    

  5.  The final PUTBACK is used to leave the Perl stack in a consistent
state before exiting the function.  This is necessary because when we
popped the return value from the stack with POPi it updated only our
local copy of the stack pointer.  Remember, PUTBACK sets the global
stack pointer to be the same as our local copy.











Next: , Previous: perlcall Returning a Scalar, Up: perlcall EXAMPLES   [Contents]





7.5.4 Returning a List of Values



Now, let’s extend the previous example to return both the sum of the
parameters and the difference.



Here is the Perl subroutine



    sub AddSubtract
    {
       my($a, $b) = @_;
       ($a+$b, $a-$b);
    }



and this is the C function



    static void
    call_AddSubtract(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_ARRAY);

        SPAGAIN;

        if (count != 2)
            croak("Big trouble\n");

        printf ("%d - %d = %d\n", a, b, POPi);
        printf ("%d + %d = %d\n", a, b, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
    }



If call_AddSubtract is called like this



    call_AddSubtract(7, 4);



then here is the output



    7 - 4 = 3
    7 + 4 = 11



Notes



    

  1.  We wanted list context, so G_ARRAY was used.


  2.  Not surprisingly POPi is used twice this time because we were
retrieving 2 values from the stack. The important thing to note is that
when using the POP* macros they come off the stack in reverse
order.











Next: , Previous: perlcall Returning a List of Values, Up: perlcall EXAMPLES   [Contents]





7.5.5 Returning a List in a Scalar Context



Say the Perl subroutine in the previous section was called in a scalar
context, like this



    static void
    call_AddSubScalar(a, b)
    int a;
    int b;
    {
        dSP;
        int count;
        int i;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_SCALAR);

        SPAGAIN;

        printf ("Items Returned = %d\n", count);

        for (i = 1; i <= count; ++i)
            printf ("Value %d = %d\n", i, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
    }



The other modification made is that call_AddSubScalar will print the
number of items returned from the Perl subroutine and their value (for
simplicity it assumes that they are integer).  So if
call_AddSubScalar is called



    call_AddSubScalar(7, 4);



then the output will be



    Items Returned = 1
    Value 1 = 3



In this case the main point to note is that only the last item in the
list is returned from the subroutine. AddSubtract actually made it back to
call_AddSubScalar.









Next: , Previous: perlcall Returning a List in a Scalar Context, Up: perlcall EXAMPLES   [Contents]





7.5.6 Returning Data from Perl via the Parameter List



It is also possible to return values directly via the parameter
list–whether it is actually desirable to do it is another matter entirely.



The Perl subroutine, Inc, below takes 2 parameters and increments
each directly.



    sub Inc
    {
        ++ $_[0];
        ++ $_[1];
    }



and here is a C function to call it.



    static void
    call_Inc(a, b)
    int a;
    int b;
    {
        dSP;
        int count;
        SV * sva;
        SV * svb;

        ENTER;
        SAVETMPS;

        sva = sv_2mortal(newSViv(a));
        svb = sv_2mortal(newSViv(b));

        PUSHMARK(SP);
        XPUSHs(sva);
        XPUSHs(svb);
        PUTBACK;

        count = call_pv("Inc", G_DISCARD);

        if (count != 0)
            croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
                   count);

        printf ("%d + 1 = %d\n", a, SvIV(sva));
        printf ("%d + 1 = %d\n", b, SvIV(svb));

        FREETMPS;
        LEAVE;
    }



To be able to access the two parameters that were pushed onto the stack
after they return from call_pv it is necessary to make a note
of their addresses–thus the two variables sva and svb.



The reason this is necessary is that the area of the Perl stack which
held them will very likely have been overwritten by something else by
the time control returns from call_pv.









Next: , Previous: perlcall Returning Data from Perl via the Parameter List, Up: perlcall EXAMPLES   [Contents]





7.5.7 Using G_EVAL



Now an example using G_EVAL. Below is a Perl subroutine which computes
the difference of its 2 parameters. If this would result in a negative
result, the subroutine calls die.



    sub Subtract
    {
        my ($a, $b) = @_;

        die "death can be fatal\n" if $a < $b;

        $a - $b;
    }



and some C to call it



    static void
    call_Subtract(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("Subtract", G_EVAL|G_SCALAR);

        SPAGAIN;

        /* Check the eval first */
        if (SvTRUE(ERRSV))
        {
            printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
            POPs;
        }
        else
        {
            if (count != 1)
               croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
                        count);

            printf ("%d - %d = %d\n", a, b, POPi);
        }

        PUTBACK;
        FREETMPS;
        LEAVE;
    }



If call_Subtract is called thus



    call_Subtract(4, 5)



the following will be printed



    Uh oh - death can be fatal



Notes



    

  1.  We want to be able to catch the die so we have used the G_EVAL
flag.  Not specifying this flag would mean that the program would
terminate immediately at the die statement in the subroutine
Subtract.


  2.  The code


        if (SvTRUE(ERRSV))
    {
        printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
        POPs;
    }

    

    is the direct equivalent of this bit of Perl

    

        print "Uh oh - $@\n" if $@;

    

    PL_errgv is a perl global of type GV * that points to the
symbol table entry containing the error.  ERRSV therefore
refers to the C equivalent of $@.

    

  3.  Note that the stack is popped using POPs in the block where
SvTRUE(ERRSV) is true.  This is necessary because whenever a
call_* function invoked with G_EVAL|G_SCALAR returns an error,
the top of the stack holds the value undef. Because we want the
program to continue after detecting this error, it is essential that
the stack be tidied up by removing the undef.











Next: , Previous: perlcall Using G_EVAL, Up: perlcall EXAMPLES   [Contents]





7.5.8 Using G_KEEPERR



Consider this rather facetious example, where we have used an XS
version of the call_Subtract example above inside a destructor:



    package Foo;
    sub new { bless {}, $_[0] }
    sub Subtract {
        my($a,$b) = @_;
        die "death can be fatal" if $a < $b;
        $a - $b;
    }
    sub DESTROY { call_Subtract(5, 4); }
    sub foo { die "foo dies"; }

    package main;
    {
        my $foo = Foo->new;
        eval { $foo->foo };
    }
    print "Saw: $@" if $@;             # should be, but isn't



This example will fail to recognize that an error occurred inside the
eval {}.  Here’s why: the call_Subtract code got executed while perl
was cleaning up temporaries when exiting the outer braced block, and because
call_Subtract is implemented with call_pv using the G_EVAL
flag, it promptly reset $@.  This results in the failure of the
outermost test for $@, and thereby the failure of the error trap.



Appending the G_KEEPERR flag, so that the call_pv call in
call_Subtract reads:



        count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);



will preserve the error and restore reliable error handling.









Next: , Previous: perlcall Using G_KEEPERR, Up: perlcall EXAMPLES   [Contents]





7.5.9 Using call_sv



In all the previous examples I have ’hard-wired’ the name of the Perl
subroutine to be called from C.  Most of the time though, it is more
convenient to be able to specify the name of the Perl subroutine from
within the Perl script.



Consider the Perl code below



    sub fred
    {
        print "Hello there\n";
    }

    CallSubPV("fred");



Here is a snippet of XSUB which defines CallSubPV.



    void
    CallSubPV(name)
        char *  name
        CODE:
        PUSHMARK(SP);
        call_pv(name, G_DISCARD|G_NOARGS);



That is fine as far as it goes. The thing is, the Perl subroutine
can be specified as only a string.  For Perl 4 this was adequate,
but Perl 5 allows references to subroutines and anonymous subroutines.
This is where call_sv is useful.



The code below for CallSubSV is identical to CallSubPV except
that the name parameter is now defined as an SV* and we use
call_sv instead of call_pv.



    void
    CallSubSV(name)
        SV *    name
        CODE:
        PUSHMARK(SP);
        call_sv(name, G_DISCARD|G_NOARGS);



Because we are using an SV to call fred the following can all be used:



    CallSubSV("fred");
    CallSubSV(\&fred);
    $ref = \&fred;
    CallSubSV($ref);
    CallSubSV( sub { print "Hello there\n" } );



As you can see, call_sv gives you much greater flexibility in
how you can specify the Perl subroutine.



You should note that, if it is necessary to store the SV (name in the
example above) which corresponds to the Perl subroutine so that it can
be used later in the program, it not enough just to store a copy of the
pointer to the SV. Say the code above had been like this:



    static SV * rememberSub;

    void
    SaveSub1(name)
        SV *    name
        CODE:
        rememberSub = name;

    void
    CallSavedSub1()
        CODE:
        PUSHMARK(SP);
        call_sv(rememberSub, G_DISCARD|G_NOARGS);



The reason this is wrong is that, by the time you come to use the
pointer rememberSub in CallSavedSub1, it may or may not still refer
to the Perl subroutine that was recorded in SaveSub1.  This is
particularly true for these cases:



    SaveSub1(\&fred);
    CallSavedSub1();

    SaveSub1( sub { print "Hello there\n" } );
    CallSavedSub1();



By the time each of the SaveSub1 statements above has been executed,
the SV*s which corresponded to the parameters will no longer exist.
Expect an error message from Perl of the form



    Can't use an undefined value as a subroutine reference at ...



for each of the CallSavedSub1 lines.



Similarly, with this code



    $ref = \&fred;
    SaveSub1($ref);
    $ref = 47;
    CallSavedSub1();



you can expect one of these messages (which you actually get is dependent on
the version of Perl you are using)



    Not a CODE reference at ...
    Undefined subroutine &main::47 called ...



The variable $ref may have referred to the subroutine fred
whenever the call to SaveSub1 was made but by the time
CallSavedSub1 gets called it now holds the number 47. Because we
saved only a pointer to the original SV in SaveSub1, any changes to
$ref will be tracked by the pointer rememberSub. This means that
whenever CallSavedSub1 gets called, it will attempt to execute the
code which is referenced by the SV* rememberSub.  In this case
though, it now refers to the integer 47, so expect Perl to complain
loudly.



A similar but more subtle problem is illustrated with this code:



    $ref = \&fred;
    SaveSub1($ref);
    $ref = \&joe;
    CallSavedSub1();



This time whenever CallSavedSub1 gets called it will execute the Perl
subroutine joe (assuming it exists) rather than fred as was
originally requested in the call to SaveSub1.



To get around these problems it is necessary to take a full copy of the
SV.  The code below shows SaveSub2 modified to do that.



    static SV * keepSub = (SV*)NULL;

    void
    SaveSub2(name)
        SV *    name
        CODE:
        /* Take a copy of the callback */
        if (keepSub == (SV*)NULL)
            /* First time, so create a new SV */
            keepSub = newSVsv(name);
        else
            /* Been here before, so overwrite */
            SvSetSV(keepSub, name);

    void
    CallSavedSub2()
        CODE:
        PUSHMARK(SP);
        call_sv(keepSub, G_DISCARD|G_NOARGS);



To avoid creating a new SV every time SaveSub2 is called,
the function first checks to see if it has been called before.  If not,
then space for a new SV is allocated and the reference to the Perl
subroutine name is copied to the variable keepSub in one
operation using newSVsv.  Thereafter, whenever SaveSub2 is called,
the existing SV, keepSub, is overwritten with the new value using
SvSetSV.









Next: , Previous: perlcall Using call_sv, Up: perlcall EXAMPLES   [Contents]





7.5.10 Using call_argv



Here is a Perl subroutine which prints whatever parameters are passed
to it.



    sub PrintList
    {
        my(@list) = @_;

        foreach (@list) { print "$_\n" }
    }



And here is an example of call_argv which will call
PrintList.



    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};

    static void
    call_PrintList()
    {
        dSP;

        call_argv("PrintList", G_DISCARD, words);
    }



Note that it is not necessary to call PUSHMARK in this instance.
This is because call_argv will do it for you.









Next: , Previous: perlcall Using call_argv, Up: perlcall EXAMPLES   [Contents]





7.5.11 Using call_method



Consider the following Perl code:



    {
        package Mine;

        sub new
        {
            my($type) = shift;
            bless [@_]
        }

        sub Display
        {
            my ($self, $index) = @_;
            print "$index: $$self[$index]\n";
        }

        sub PrintID
        {
            my($class) = @_;
            print "This is Class $class version 1.0\n";
        }
    }



It implements just a very simple class to manage an array.  Apart from
the constructor, new, it declares methods, one static and one
virtual. The static method, PrintID, prints out simply the class
name and a version number. The virtual method, Display, prints out a
single element of the array.  Here is an all-Perl example of using it.



    $a = Mine->new('red', 'green', 'blue');
    $a->Display(1);
    Mine->PrintID;



will print



    1: green
    This is Class Mine version 1.0



Calling a Perl method from C is fairly straightforward. The following
things are required:





Here is a simple XSUB which illustrates the mechanics of calling both
the PrintID and Display methods from C.



    void
    call_Method(ref, method, index)
        SV *    ref
        char *  method
        int             index
        CODE:
        PUSHMARK(SP);
        XPUSHs(ref);
        XPUSHs(sv_2mortal(newSViv(index)));
        PUTBACK;

        call_method(method, G_DISCARD);

    void
    call_PrintID(class, method)
        char *  class
        char *  method
        CODE:
        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(class, 0)));
        PUTBACK;

        call_method(method, G_DISCARD);



So the methods PrintID and Display can be invoked like this:



    $a = Mine->new('red', 'green', 'blue');
    call_Method($a, 'Display', 1);
    call_PrintID('Mine', 'PrintID');



The only thing to note is that, in both the static and virtual methods,
the method name is not passed via the stack–it is used as the first
parameter to call_method.









Next: , Previous: perlcall Using call_method, Up: perlcall EXAMPLES   [Contents]





7.5.12 Using GIMME_V



Here is a trivial XSUB which prints the context in which it is
currently executing.



    void
    PrintContext()
        CODE:
        I32 gimme = GIMME_V;
        if (gimme == G_VOID)
            printf ("Context is Void\n");
        else if (gimme == G_SCALAR)
            printf ("Context is Scalar\n");
        else
            printf ("Context is Array\n");



And here is some Perl to test it.



    PrintContext;
    $a = PrintContext;
    @a = PrintContext;



The output from that will be



    Context is Void
    Context is Scalar
    Context is Array









Next: , Previous: perlcall Using GIMME_V, Up: perlcall EXAMPLES   [Contents]





7.5.13 Using Perl to Dispose of Temporaries



In the examples given to date, any temporaries created in the callback
(i.e., parameters passed on the stack to the call_* function or
values returned via the stack) have been freed by one of these methods:





There is another method which can be used, namely letting Perl do it
for you automatically whenever it regains control after the callback
has terminated.  This is done by simply not using the



    ENTER;
    SAVETMPS;
    ...
    FREETMPS;
    LEAVE;



sequence in the callback (and not, of course, specifying the G_DISCARD
flag).



If you are going to use this method you have to be aware of a possible
memory leak which can arise under very specific circumstances.  To
explain these circumstances you need to know a bit about the flow of
control between Perl and the callback routine.



The examples given at the start of the document (an error handler and
an event driven program) are typical of the two main sorts of flow
control that you are likely to encounter with callbacks.  There is a
very important distinction between them, so pay attention.



In the first example, an error handler, the flow of control could be as
follows.  You have created an interface to an external library.
Control can reach the external library like this



    perl --> XSUB --> external library



Whilst control is in the library, an error condition occurs. You have
previously set up a Perl callback to handle this situation, so it will
get executed. Once the callback has finished, control will drop back to
Perl again.  Here is what the flow of control will be like in that
situation



    perl --> XSUB --> external library
                      ...
                      error occurs
                      ...
                      external library --> call_* --> perl
                                                          |
    perl <-- XSUB <-- external library <-- call_* <----+



After processing of the error using call_* is completed,
control reverts back to Perl more or less immediately.



In the diagram, the further right you go the more deeply nested the
scope is.  It is only when control is back with perl on the extreme
left of the diagram that you will have dropped back to the enclosing
scope and any temporaries you have left hanging around will be freed.



In the second example, an event driven program, the flow of control
will be more like this



    perl --> XSUB --> event handler
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+



In this case the flow of control can consist of only the repeated
sequence



    event handler --> call_* --> perl



for practically the complete duration of the program.  This means that
control may never drop back to the surrounding scope in Perl at the
extreme left.



So what is the big problem? Well, if you are expecting Perl to tidy up
those temporaries for you, you might be in for a long wait.  For Perl
to dispose of your temporaries, control must drop back to the
enclosing scope at some stage.  In the event driven scenario that may
never happen.  This means that, as time goes on, your program will
create more and more temporaries, none of which will ever be freed. As
each of these temporaries consumes some memory your program will
eventually consume all the available memory in your system–kapow!



So here is the bottom line–if you are sure that control will revert
back to the enclosing Perl scope fairly quickly after the end of your
callback, then it isn’t absolutely necessary to dispose explicitly of
any temporaries you may have created. Mind you, if you are at all
uncertain about what to do, it doesn’t do any harm to tidy up anyway.









Next: , Previous: perlcall Using Perl to Dispose of Temporaries, Up: perlcall EXAMPLES   [Contents]





7.5.14 Strategies for Storing Callback Context Information



Potentially one of the trickiest problems to overcome when designing a
callback interface can be figuring out how to store the mapping between
the C callback function and the Perl equivalent.



To help understand why this can be a real problem first consider how a
callback is set up in an all C environment.  Typically a C API will
provide a function to register a callback.  This will expect a pointer
to a function as one of its parameters.  Below is a call to a
hypothetical function register_fatal which registers the C function
to get called when a fatal error occurs.



    register_fatal(cb1);



The single parameter cb1 is a pointer to a function, so you must
have defined cb1 in your code, say something like this



    static void
    cb1()
    {
        printf ("Fatal Error\n");
        exit(1);
    }



Now change that to call a Perl subroutine instead



    static SV * callback = (SV*)NULL;

    static void
    cb1()
    {
        dSP;

        PUSHMARK(SP);

        /* Call the Perl sub to process the callback */
        call_sv(callback, G_DISCARD);
    }


    void
    register_fatal(fn)
        SV *    fn
        CODE:
        /* Remember the Perl sub */
        if (callback == (SV*)NULL)
            callback = newSVsv(fn);
        else
            SvSetSV(callback, fn);

        /* register the callback with the external library */
        register_fatal(cb1);



where the Perl equivalent of register_fatal and the callback it
registers, pcb1, might look like this



    # Register the sub pcb1
    register_fatal(\&pcb1);

    sub pcb1
    {
        die "I'm dying...\n";
    }



The mapping between the C callback and the Perl equivalent is stored in
the global variable callback.



This will be adequate if you ever need to have only one callback
registered at any time. An example could be an error handler like the
code sketched out above. Remember though, repeated calls to
register_fatal will replace the previously registered callback
function with the new one.



Say for example you want to interface to a library which allows asynchronous
file i/o.  In this case you may be able to register a callback whenever
a read operation has completed. To be of any use we want to be able to
call separate Perl subroutines for each file that is opened.  As it
stands, the error handler example above would not be adequate as it
allows only a single callback to be defined at any time. What we
require is a means of storing the mapping between the opened file and
the Perl subroutine we want to be called for that file.



Say the i/o library has a function asynch_read which associates a C
function ProcessRead with a file handle fh–this assumes that it
has also provided some routine to open the file and so obtain the file
handle.



    asynch_read(fh, ProcessRead)



This may expect the C ProcessRead function of this form



    void
    ProcessRead(fh, buffer)
    int fh;
    char *      buffer;
    {
         ...
    }



To provide a Perl interface to this library we need to be able to map
between the fh parameter and the Perl subroutine we want called.  A
hash is a convenient mechanism for storing this mapping.  The code
below shows a possible implementation



    static HV * Mapping = (HV*)NULL;

    void
    asynch_read(fh, callback)
        int     fh
        SV *    callback
        CODE:
        /* If the hash doesn't already exist, create it */
        if (Mapping == (HV*)NULL)
            Mapping = newHV();

        /* Save the fh -> callback mapping */
        hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);

        /* Register with the C Library */
        asynch_read(fh, asynch_read_if);



and asynch_read_if could look like this



    static void
    asynch_read_if(fh, buffer)
    int fh;
    char *      buffer;
    {
        dSP;
        SV ** sv;

        /* Get the callback associated with fh */
        sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
        if (sv == (SV**)NULL)
            croak("Internal error...\n");

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(fh)));
        XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
        PUTBACK;

        /* Call the Perl sub */
        call_sv(*sv, G_DISCARD);
    }



For completeness, here is asynch_close.  This shows how to remove
the entry from the hash Mapping.



    void
    asynch_close(fh)
        int     fh
        CODE:
        /* Remove the entry from the hash */
        (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);

        /* Now call the real asynch_close */
        asynch_close(fh);



So the Perl interface would look like this



    sub callback1
    {
        my($handle, $buffer) = @_;
    }

    # Register the Perl callback
    asynch_read($fh, \&callback1);

    asynch_close($fh);



The mapping between the C callback and Perl is stored in the global
hash Mapping this time. Using a hash has the distinct advantage that
it allows an unlimited number of callbacks to be registered.



What if the interface provided by the C callback doesn’t contain a
parameter which allows the file handle to Perl subroutine mapping?  Say
in the asynchronous i/o package, the callback function gets passed only
the buffer parameter like this



    void
    ProcessRead(buffer)
    char *      buffer;
    {
        ...
    }



Without the file handle there is no straightforward way to map from the
C callback to the Perl subroutine.



In this case a possible way around this problem is to predefine a
series of C functions to act as the interface to Perl, thus



    #define MAX_CB              3
    #define NULL_HANDLE -1
    typedef void (*FnMap)();

    struct MapStruct {
        FnMap    Function;
        SV *     PerlSub;
        int      Handle;
      };

    static void  fn1();
    static void  fn2();
    static void  fn3();

    static struct MapStruct Map [MAX_CB] =
        {
            { fn1, NULL, NULL_HANDLE },
            { fn2, NULL, NULL_HANDLE },
            { fn3, NULL, NULL_HANDLE }
        };

    static void
    Pcb(index, buffer)
    int index;
    char * buffer;
    {
        dSP;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
        PUTBACK;

        /* Call the Perl sub */
        call_sv(Map[index].PerlSub, G_DISCARD);
    }

    static void
    fn1(buffer)
    char * buffer;
    {
        Pcb(0, buffer);
    }

    static void
    fn2(buffer)
    char * buffer;
    {
        Pcb(1, buffer);
    }

    static void
    fn3(buffer)
    char * buffer;
    {
        Pcb(2, buffer);
    }

    void
    array_asynch_read(fh, callback)
        int             fh
        SV *    callback
        CODE:
        int index;
        int null_index = MAX_CB;

        /* Find the same handle or an empty entry */
        for (index = 0; index < MAX_CB; ++index)
        {
            if (Map[index].Handle == fh)
                break;

            if (Map[index].Handle == NULL_HANDLE)
                null_index = index;
        }

        if (index == MAX_CB && null_index == MAX_CB)
            croak ("Too many callback functions registered\n");

        if (index == MAX_CB)
            index = null_index;

        /* Save the file handle */
        Map[index].Handle = fh;

        /* Remember the Perl sub */
        if (Map[index].PerlSub == (SV*)NULL)
            Map[index].PerlSub = newSVsv(callback);
        else
            SvSetSV(Map[index].PerlSub, callback);

        asynch_read(fh, Map[index].Function);

    void
    array_asynch_close(fh)
        int     fh
        CODE:
        int index;

        /* Find the file handle */
        for (index = 0; index < MAX_CB; ++ index)
            if (Map[index].Handle == fh)
                break;

        if (index == MAX_CB)
            croak ("could not close fh %d\n", fh);

        Map[index].Handle = NULL_HANDLE;
        SvREFCNT_dec(Map[index].PerlSub);
        Map[index].PerlSub = (SV*)NULL;

        asynch_close(fh);



In this case the functions fn1, fn2, and fn3 are used to
remember the Perl subroutine to be called. Each of the functions holds
a separate hard-wired index which is used in the function Pcb to
access the Map array and actually call the Perl subroutine.



There are some obvious disadvantages with this technique.



Firstly, the code is considerably more complex than with the previous
example.



Secondly, there is a hard-wired limit (in this case 3) to the number of
callbacks that can exist simultaneously. The only way to increase the
limit is by modifying the code to add more functions and then
recompiling.  None the less, as long as the number of functions is
chosen with some care, it is still a workable solution and in some
cases is the only one available.



To summarize, here are a number of possible methods for you to consider
for storing the mapping between C and the Perl callback





1. Ignore the problem - Allow only 1 callback




For a lot of situations, like interfacing to an error handler, this may
be a perfectly adequate solution.





2. Create a sequence of callbacks - hard wired limit




If it is impossible to tell from the parameters passed back from the C
callback what the context is, then you may need to create a sequence of C
callback interface functions, and store pointers to each in an array.





3. Use a parameter to map to the Perl callback




A hash is an ideal mechanism to store the mapping between C and Perl.














Next: , Previous: perlcall Strategies for Storing Callback Context Information, Up: perlcall EXAMPLES   [Contents]





7.5.15 Alternate Stack Manipulation



Although I have made use of only the POP* macros to access values
returned from Perl subroutines, it is also possible to bypass these
macros and read the stack using the ST macro (See (perlxs) for a
full description of the ST macro).



Most of the time the POP* macros should be adequate; the main
problem with them is that they force you to process the returned values
in sequence. This may not be the most suitable way to process the
values in some cases. What we want is to be able to access the stack in
a random order. The ST macro as used when coding an XSUB is ideal
for this purpose.



The code below is the example given in the section Returning a List
of Values recoded to use ST instead of POP*.



    static void
    call_AddSubtract2(a, b)
    int a;
    int b;
    {
        dSP;
        I32 ax;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_ARRAY);

        SPAGAIN;
        SP -= count;
        ax = (SP - PL_stack_base) + 1;

        if (count != 2)
            croak("Big trouble\n");

        printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
        printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));

        PUTBACK;
        FREETMPS;
        LEAVE;
    }



Notes



    

  1.  Notice that it was necessary to define the variable ax.  This is
because the ST macro expects it to exist.  If we were in an XSUB it
would not be necessary to define ax as it is already defined for
us.


  2.  The code


            SPAGAIN;
        SP -= count;
        ax = (SP - PL_stack_base) + 1;

    

    sets the stack up so that we can use the ST macro.

    

  3.  Unlike the original coding of this example, the returned
values are not accessed in reverse order.  So ST(0) refers to the
first value returned by the Perl subroutine and ST(count-1)
refers to the last.











Previous: perlcall Alternate Stack Manipulation, Up: perlcall EXAMPLES   [Contents]





7.5.16 Creating and Calling an Anonymous Subroutine in C



As we’ve already shown, call_sv can be used to invoke an
anonymous subroutine.  However, our example showed a Perl script
invoking an XSUB to perform this operation.  Let’s see how it can be
done inside our C code:



 ...

 SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);

 ...

 call_sv(cvrv, G_VOID|G_NOARGS);



eval_pv is used to compile the anonymous subroutine, which
will be the return value as well (read more about eval_pv in
(perlapi)eval_pv).  Once this code reference is in hand, it
can be mixed in with all the previous examples we’ve shown.









Next: , Previous: perlcall EXAMPLES, Up: perlcall   [Contents]





7.6 LIGHTWEIGHT CALLBACKS



Sometimes you need to invoke the same subroutine repeatedly.
This usually happens with a function that acts on a list of
values, such as Perl’s built-in sort(). You can pass a
comparison function to sort(), which will then be invoked
for every pair of values that needs to be compared. The first()
and reduce() functions from (List-Util) follow a similar
pattern.



In this case it is possible to speed up the routine (often
quite substantially) by using the lightweight callback API.
The idea is that the calling context only needs to be
created and destroyed once, and the sub can be called
arbitrarily many times in between.



It is usual to pass parameters using global variables (typically
$_ for one parameter, or $a and $b for two parameters) rather
than via @_. (It is possible to use the @_ mechanism if you know
what you’re doing, though there is as yet no supported API for
it. It’s also inherently slower.)



The pattern of macro calls is like this:



    dMULTICALL;                 /* Declare local variables */
    I32 gimme = G_SCALAR;       /* context of the call: G_SCALAR,
                                 * G_ARRAY, or G_VOID */

    PUSH_MULTICALL(cv);         /* Set up the context for calling cv,
                                   and set local vars appropriately */

    /* loop */ {
        /* set the value(s) af your parameter variables */
        MULTICALL;              /* Make the actual call */
    } /* end of loop */

    POP_MULTICALL;              /* Tear down the calling context */



For some concrete examples, see the implementation of the
first() and reduce() functions of List::Util 1.18. There you
will also find a header file that emulates the multicall API
on older versions of perl.









Next: , Previous: perlcall LIGHTWEIGHT CALLBACKS, Up: perlcall   [Contents]





7.7 SEE ALSO



(perlxs), perlguts NAME, perlembed NAME









Next: , Previous: perlcall SEE ALSO, Up: perlcall   [Contents]





7.8 AUTHOR



Paul Marquess 



Special thanks to the following people who assisted in the creation of
the document.



Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
and Larry Wall.









Previous: perlcall AUTHOR, Up: perlcall   [Contents]





7.9 DATE



Version 1.3, 14th Apr 1997









Next: , Previous: perlcall, Up: Top   [Contents]





8 perlcheat





• perlcheat NAME:  



• perlcheat DESCRIPTION:  



• perlcheat ACKNOWLEDGEMENTS:  



• perlcheat AUTHOR:  



• perlcheat SEE ALSO:  












Next: , Up: perlcheat   [Contents]





8.1 NAME



perlcheat - Perl 5 Cheat Sheet









Next: , Previous: perlcheat NAME, Up: perlcheat   [Contents]





8.2 DESCRIPTION



This ’cheat sheet’ is a handy reference, meant for beginning Perl
programmers. Not everything is mentioned, but 195 features may
already be overwhelming.





• perlcheat The sheet:  












Up: perlcheat DESCRIPTION   [Contents]





8.2.1 The sheet



  CONTEXTS  SIGILS  ref        ARRAYS        HASHES
  void      $scalar SCALAR     @array        %hash
  scalar    @array  ARRAY      @array[0, 2]  @hash{'a', 'b'}
  list      %hash   HASH       $array[0]     $hash{'a'}
            &sub    CODE
            *glob   GLOB       SCALAR VALUES
                    FORMAT     number, string, ref, glob, undef
  REFERENCES
  \      reference       $$foo[1]       aka $foo->[1]
  $@%&*  dereference     $$foo{bar}     aka $foo->{bar}
  []     anon. arrayref  ${$$foo[1]}[2] aka $foo->[1]->[2]
  {}     anon. hashref   ${$$foo[1]}[2] aka $foo->[1][2]
  \()    list of refs
                         NUMBERS vs STRINGS    LINKS
  OPERATOR PRECEDENCE    =          =          perldoc.perl.org
  ->                     +          .           search.cpan.org
  ++ --                  == !=      eq ne              cpan.org
  **                     < > <= >=  lt gt le ge          pm.org
  ! ~ \ u+ u-            <=>        cmp                p3rl.org
  =~ !~                                           perlmonks.org
  * / % x                SYNTAX
  + - .                  foreach (LIST) { }     for (a;b;c) { }
  << >>                  while   (e) { }        until (e)   { }
  named uops             if      (e) { } elsif (e) { } else { }
  < > <= >= lt gt le ge  unless  (e) { } elsif (e) { } else { }
  == != <=> eq ne cmp ~~ given   (e) { when (e) {} default {} }
  &
  | ^             REGEX METACHARS          REGEX MODIFIERS
  &&              ^      string begin      /i case insensitive
  || //           $      str end (bfr \n)  /m line based ^$
  .. ...          +      one or more       /s . includes \n
  ?:              *      zero or more      /x ignore wh.space
  = += -= *= etc  ?      zero or one       /p preserve
  , =>            {3,7}  repeat in range   /a ASCII    /aa safe
  list ops        |      alternation       /l locale   /d  dual
  not             []     character class   /u Unicode
  and             \b     word boundary     /e evaluate /ee rpts
  or xor          \z     string end        /g global
                  ()     capture           /o compile pat once
  DEBUG           (?:p)  no capture
   -MO=Deparse    (?#t)  comment           REGEX CHARCLASSES
   -MO=Terse      (?=p)  ZW pos ahead      .   [^\n]
   -D##           (?!p)  ZW neg ahead      \s  whitespace
   -d:Trace       (?<=p) ZW pos behind \K  \w  word chars
                  (?<!p) ZW neg behind     \d  digits
  CONFIGURATION   (?>p)  no backtrack      \pP named property
  perl -V:ivsize  (?|p|p)branch reset      \h  horiz.wh.space
                  (?&NM) cap to name       \R  linebreak
                                           \S \W \D \H negate
  FUNCTION RETURN LISTS
  stat      localtime    caller         SPECIAL VARIABLES
   0 dev    0 second      0 package     $_    default variable
   1 ino    1 minute      1 filename    $0    program name
   2 mode   2 hour        2 line        $/    input separator
   3 nlink  3 day         3 subroutine  $\    output separator
   4 uid    4 month-1     4 hasargs     $|    autoflush
   5 gid    5 year-1900   5 wantarray   $!    sys/libcall error
   6 rdev   6 weekday     6 evaltext    $@    eval error
   7 size   7 yearday     7 is_require  $$    process ID
   8 atime  8 is_dst      8 hints       $.    line number
   9 mtime                9 bitmask     @ARGV command line args
  10 ctime               10 hinthash    @INC  include paths
  11 blksz               3..10 only     @_    subroutine args
  12 blcks               with EXPR      %ENV  environment









Next: , Previous: perlcheat DESCRIPTION, Up: perlcheat   [Contents]





8.3 ACKNOWLEDGEMENTS



The first version of this document appeared on Perl Monks, where several
people had useful suggestions. Thank you, Perl Monks.



A special thanks to Damian Conway, who didn’t only suggest important changes,
but also took the time to count the number of listed features and make a
Perl 6 version to show that Perl will stay Perl.









Next: , Previous: perlcheat ACKNOWLEDGEMENTS, Up: perlcheat   [Contents]





8.4 AUTHOR



Juerd Waalboer <#####@juerd.nl>, with the help of many Perl Monks.









Previous: perlcheat AUTHOR, Up: perlcheat   [Contents]





8.5 SEE ALSO











Next: , Previous: perlcheat, Up: Top   [Contents]





9 perlclib





• perlclib NAME:  



• perlclib DESCRIPTION:  



• perlclib SEE ALSO:  












Next: , Up: perlclib   [Contents]





9.1 NAME



perlclib - Internal replacements for standard C library functions









Next: , Previous: perlclib NAME, Up: perlclib   [Contents]





9.2 DESCRIPTION



One thing Perl porters should note is that perl doesn’t tend to use that
much of the C standard library internally; you’ll see very little use of, 
for example, the ctype.h functions in there. This is because Perl
tends to reimplement or abstract standard library functions, so that we
know exactly how they’re going to operate.



This is a reference card for people who are familiar with the C library
and who want to do things the Perl way; to tell them which functions
they ought to use instead of the more normal C functions. 





• perlclib Conventions:  



• perlclib File Operations:  



• perlclib File Input and Output:  



• perlclib File Positioning:  



• perlclib Memory Management and String Handling:  



• perlclib Character Class Tests:  



• perlclib stdlib.h functions:  



• perlclib Miscellaneous functions:  












Next: , Up: perlclib DESCRIPTION   [Contents]





9.2.1 Conventions



In the following tables:





t




is a type.





p




is a pointer.





n




is a number.





s




is a string.








sv, av, hv, etc. represent variables of their respective types.









Next: , Previous: perlclib Conventions, Up: perlclib DESCRIPTION   [Contents]





9.2.2 File Operations



Instead of the stdio.h functions, you should use the Perl abstraction
layer. Instead of FILE* types, you need to be handling PerlIO*
types.  Don’t forget that with the new PerlIO layered I/O abstraction 
FILE* types may not even be available. See also the perlapio
documentation for more information about the following functions:



    Instead Of:                 Use:

    stdin                       PerlIO_stdin()
    stdout                      PerlIO_stdout()
    stderr                      PerlIO_stderr()

    fopen(fn, mode)             PerlIO_open(fn, mode)
    freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Deprecated)
    fflush(stream)              PerlIO_flush(perlio)
    fclose(stream)              PerlIO_close(perlio)









Next: , Previous: perlclib File Operations, Up: perlclib DESCRIPTION   [Contents]





9.2.3 File Input and Output



    Instead Of:                 Use:

    fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)

    [f]getc(stream)             PerlIO_getc(perlio)
    [f]putc(stream, n)          PerlIO_putc(perlio, n)
    ungetc(n, stream)           PerlIO_ungetc(perlio, n)



Note that the PerlIO equivalents of fread and fwrite are slightly
different from their C library counterparts:



    fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
    fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)

    fputs(s, stream)            PerlIO_puts(perlio, s)



There is no equivalent to fgets; one should use sv_gets instead:



    fgets(s, n, stream)         sv_gets(sv, perlio, append)









Next: , Previous: perlclib File Input and Output, Up: perlclib DESCRIPTION   [Contents]





9.2.4 File Positioning



    Instead Of:                 Use:

    feof(stream)                PerlIO_eof(perlio)
    fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
    rewind(stream)              PerlIO_rewind(perlio)

    fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
    fsetpos(stream, p)          PerlIO_setpos(perlio, sv)

    ferror(stream)              PerlIO_error(perlio)
    clearerr(stream)            PerlIO_clearerr(perlio)









Next: , Previous: perlclib File Positioning, Up: perlclib DESCRIPTION   [Contents]





9.2.5 Memory Management and String Handling



    Instead Of:                         Use:

    t* p = malloc(n)                    Newx(id, p, n, t)
    t* p = calloc(n, s)                 Newxz(id, p, n, t)
    p = realloc(p, n)                   Renew(p, n, t)
    memcpy(dst, src, n)                 Copy(src, dst, n, t)
    memmove(dst, src, n)                Move(src, dst, n, t)
    memcpy(dst, src, sizeof(t))         StructCopy(src, dst, t)
    memset(dst, 0, n * sizeof(t))       Zero(dst, n, t)
    memzero(dst, 0)                     Zero(dst, n, char)
    free(p)                             Safefree(p)

    strdup(p)                   savepv(p)
    strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)

    strstr(big, little)         instr(big, little)
    strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
    strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)



Notice the different order of arguments to Copy and Move than used
in memcpy and memmove.



Most of the time, though, you’ll want to be dealing with SVs internally
instead of raw char * strings:



    strlen(s)                   sv_len(sv)
    strcpy(dt, src)             sv_setpv(sv, s)
    strncpy(dt, src, n)         sv_setpvn(sv, s, n)
    strcat(dt, src)             sv_catpv(sv, s)
    strncat(dt, src)            sv_catpvn(sv, s)
    sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)



Note also the existence of sv_catpvf and sv_vcatpvfn, combining
concatenation with formatting.



Sometimes instead of zeroing the allocated heap by using Newxz() you
should consider "poisoning" the data.  This means writing a bit
pattern into it that should be illegal as pointers (and floating point
numbers), and also hopefully surprising enough as integers, so that
any code attempting to use the data without forethought will break
sooner rather than later.  Poisoning can be done using the Poison()
macros, which have similar arguments to Zero():



    PoisonWith(dst, n, t, b)    scribble memory with byte b
    PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
    PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
    Poison(dst, n, t)           equal to PoisonFree(dst, n, t)









Next: , Previous: perlclib Memory Management and String Handling, Up: perlclib DESCRIPTION   [Contents]





9.2.6 Character Class Tests



There are two types of character class tests that Perl implements: one
type deals in chars and are thus not Unicode aware (and hence
deprecated unless you know you should use them) and the other type
deal in UVs and know about Unicode properties. In the following
table, c is a char, and u is a Unicode codepoint.



    Instead Of:                 Use:            But better use:

    isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
    isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
    iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
    isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
    isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
    islower(c)                  isLOWER(c)      isLOWER_uni(u)
    isprint(c)                  isPRINT(c)      isPRINT_uni(u)
    ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
    isspace(c)                  isSPACE(c)      isSPACE_uni(u)
    isupper(c)                  isUPPER(c)      isUPPER_uni(u)
    isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)

    tolower(c)                  toLOWER(c)      toLOWER_uni(u)
    toupper(c)                  toUPPER(c)      toUPPER_uni(u)









Next: , Previous: perlclib Character Class Tests, Up: perlclib DESCRIPTION   [Contents]





9.2.7 stdlib.h functions



    Instead Of:                 Use: 

    atof(s)                     Atof(s)
    atol(s)                     Atol(s)
    strtod(s, &p)               Nothing.  Just don't use it.
    strtol(s, &p, n)            Strtol(s, &p, n)
    strtoul(s, &p, n)           Strtoul(s, &p, n)



Notice also the grok_bin, grok_hex, and grok_oct functions in
numeric.c for converting strings representing numbers in the respective
bases into NVs.



In theory Strtol and Strtoul may not be defined if the machine perl is
built on doesn’t actually have strtol and strtoul. But as those 2
functions are part of the 1989 ANSI C spec we suspect you’ll find them
everywhere by now.



    int rand()                  double Drand01()
    srand(n)                    { seedDrand01((Rand_seed_t)n); 
                                  PL_srand_called = TRUE; }

    exit(n)                     my_exit(n)
    system(s)                   Don't. Look at pp_system or use my_popen

    getenv(s)                   PerlEnv_getenv(s)
    setenv(s, val)              my_putenv(s, val)









Previous: perlclib stdlib.h functions, Up: perlclib DESCRIPTION   [Contents]





9.2.8 Miscellaneous functions



You should not even want to use setjmp.h functions, but if you
think you do, use the JMPENV stack in scope.h instead.



For signal/sigaction, use rsignal(signo, handler).









Previous: perlclib DESCRIPTION, Up: perlclib   [Contents]





9.3 SEE ALSO



(perlapi), perlapio NAME, perlguts NAME









Next: , Previous: perlclib, Up: Top   [Contents]





10 perlcommunity





• perlcommunity NAME:  



• perlcommunity DESCRIPTION:  



• perlcommunity AUTHOR:  












Next: , Up: perlcommunity   [Contents]





10.1 NAME



perlcommunity - a brief overview of the Perl community









Next: , Previous: perlcommunity NAME, Up: perlcommunity   [Contents]





10.2 DESCRIPTION



This document aims to provide an overview of the vast perl community, which is
far too large and diverse to provide a detailed listing. If any specific niche
has been forgotten, it is not meant as an insult but an omission for the sake
of brevity.



The Perl community is as diverse as Perl, and there is a large amount of
evidence that the Perl users apply TMTOWTDI to all endeavors, not just
programming. From websites, to IRC, to mailing lists, there is more than one
way to get involved in the community.





• perlcommunity Where to Find the Community:  



• perlcommunity Mailing Lists and Newsgroups:  



• perlcommunity IRC:  



• perlcommunity Websites:  



• perlcommunity User Groups:  



• perlcommunity Workshops:  



• perlcommunity Hackathons:  



• perlcommunity Conventions:  



• perlcommunity Calendar of Perl Events:  












Next: , Up: perlcommunity DESCRIPTION   [Contents]





10.2.1 Where to Find the Community



There is a central directory for the Perl community: http://perl.org
maintained by the Perl Foundation (http://www.perlfoundation.org/),
which tracks and provides services for a variety of other community sites.









Next: , Previous: perlcommunity Where to Find the Community, Up: perlcommunity DESCRIPTION   [Contents]





10.2.2 Mailing Lists and Newsgroups



Perl runs on e-mail; there is no doubt about it. The Camel book was originally
written mostly over e-mail and today Perl’s development is co-ordinated through
mailing lists. The largest repository of Perl mailing lists is located at
http://lists.perl.org.



Most Perl-related projects set up mailing lists for both users and
contributors. If you don’t see a certain project listed at
http://lists.perl.org, check the particular website for that project.
Most mailing lists are archived at http://nntp.perl.org/.



There are also plenty of Perl related newsgroups located under
comp.lang.perl.*.









Next: , Previous: perlcommunity Mailing Lists and Newsgroups, Up: perlcommunity DESCRIPTION   [Contents]





10.2.3 IRC



The Perl community has a rather large IRC presence. For starters, it has its
own IRC network, irc://irc.perl.org. General (not help-oriented) chat can be
found at irc://irc.perl.org/#perl. Many other more specific chats are also
hosted on the network. Information about irc.perl.org is located on the
network’s website: http://www.irc.perl.org. For a more help-oriented #perl,
check out irc://irc.freenode.net/#perl. Perl 6 development also has a
presence in irc://irc.freenode.net/#perl6. Most Perl-related channels will
be kind enough to point you in the right direction if you ask nicely.



Any large IRC network (Dalnet, EFnet) is also likely to have a #perl channel,
with varying activity levels.









Next: , Previous: perlcommunity IRC, Up: perlcommunity DESCRIPTION   [Contents]





10.2.4 Websites



Perl websites come in a variety of forms, but they fit into two large
categories: forums and news websites. There are many Perl-related
websites, so only a few of the community’s largest are mentioned here.





• perlcommunity News sites:  



• perlcommunity Forums:  












Next: , Up: perlcommunity Websites   [Contents]





10.2.4.1 News sites





http://perl.com/




Run by O’Reilly Media (the publisher of the Camel Book, among other
Perl-related literature), perl.com provides current Perl news, articles, and
resources for Perl developers as well as a directory of other useful websites.





http://use.perl.org/




use Perl; provides a slashdot-style Perl news website covering all things Perl,
from minutes of the meetings of the Perl 6 Design team to conference
announcements with (ir)relevant discussion.














Previous: perlcommunity News sites, Up: perlcommunity Websites   [Contents]





10.2.4.2 Forums





http://www.perlmonks.org/




PerlMonks is one of the largest Perl forums, and describes itself as "A place
for individuals to polish, improve, and showcase their Perl skills." and "A
community which allows everyone to grow and learn from each other."














Next: , Previous: perlcommunity Websites, Up: perlcommunity DESCRIPTION   [Contents]





10.2.5 User Groups



Many cities around the world have local Perl Mongers chapters. A Perl Mongers
chapter is a local user group which typically holds regular in-person meetings,
both social and technical; helps organize local conferences, workshops, and
hackathons; and provides a mailing list or other continual contact method for
its members to keep in touch.



To find your local Perl Mongers (or PM as they’re commonly abbreviated) group
check the international Perl Mongers directory at http://www.pm.org/.









Next: , Previous: perlcommunity User Groups, Up: perlcommunity DESCRIPTION   [Contents]





10.2.6 Workshops



Perl workshops are, as the name might suggest, workshops where Perl is taught
in a variety of ways. At the workshops, subjects range from a beginner’s
introduction (such as the Pittsburgh Perl Workshop’s "Zero To Perl") to much
more advanced subjects.



There are several great resources for locating workshops: the
websites mentioned above, the
calendar mentioned below, and the YAPC Europe
website, http://www.yapceurope.org/, which is probably the best resource for
European Perl events.









Next: , Previous: perlcommunity Workshops, Up: perlcommunity DESCRIPTION   [Contents]





10.2.7 Hackathons



Hackathons are a very different kind of gathering where Perl hackers gather to
do just that, hack nonstop for an extended (several day) period on a specific
project or projects. Information about hackathons can be located in the same
place as information about workshops as well as in
irc://irc.perl.org/#perl.



If you have never been to a hackathon, here are a few basic things you need to
know before attending: have a working laptop and know how to use it; check out
the involved projects beforehand; have the necessary version control client;
and bring backup equipment (an extra LAN cable, additional power strips, etc.)
because someone will forget.









Next: , Previous: perlcommunity Hackathons, Up: perlcommunity DESCRIPTION   [Contents]





10.2.8 Conventions



Perl has two major annual conventions: The Perl Conference (now part of OSCON),
put on by O’Reilly, and Yet Another Perl Conference or YAPC (pronounced
yap-see), which is localized into several regional YAPCs (North America,
Europe, Asia) in a stunning grassroots display by the Perl community. For more
information about either conference, check out their respective web pages:
OSCON http://conferences.oreillynet.com/; YAPC http://www.yapc.org.



A relatively new conference franchise with a large Perl portion is the
Open Source Developers Conference or OSDC. First held in Australia it has
recently also spread to Israel and France. More information can be found at:
http://www.osdc.com.au/ for Australia, http://www.osdc.org.il
for Israel, and http://www.osdc.fr/ for France.









Previous: perlcommunity Conventions, Up: perlcommunity DESCRIPTION   [Contents]





10.2.9 Calendar of Perl Events



The Perl Review, http://www.theperlreview.com maintains a website
and Google calendar
(http://www.theperlreview.com/community_calendar) for tracking
workshops, hackathons, Perl Mongers meetings, and other events. Views
of this calendar are at http://www.perl.org/events.html and
http://www.yapc.org.



Not every event or Perl Mongers group is on that calendar, so don’t lose
heart if you don’t see yours posted. To have your event or group listed,
contact brian d foy (brian@theperlreview.com).









Previous: perlcommunity DESCRIPTION, Up: perlcommunity   [Contents]





10.3 AUTHOR



Edgar "Trizor" Bering <trizor@gmail.com>









Next: , Previous: perlcommunity, Up: Top   [Contents]





11 perldata





• perldata NAME:  



• perldata DESCRIPTION:  



• perldata SEE ALSO:  












Next: , Up: perldata   [Contents]





11.1 NAME



perldata - Perl data types









Next: , Previous: perldata NAME, Up: perldata   [Contents]





11.2 DESCRIPTION





• perldata Variable names:  



• perldata Context:  



• perldata Scalar values:  



• perldata Scalar value constructors:  



• perldata List value constructors:  



• perldata Subscripts:  



• perldata Multi-dimensional array emulation:  



• perldata Slices:  



• perldata Typeglobs and Filehandles:  












Next: , Up: perldata DESCRIPTION   [Contents]





11.2.1 Variable names







Perl has three built-in data types: scalars, arrays of scalars, and
associative arrays of scalars, known as "hashes".  A scalar is a 
single string (of any size, limited only by the available memory),
number, or a reference to something (which will be discussed
in (perlref)).  Normal arrays are ordered lists of scalars indexed
by number, starting with 0.  Hashes are unordered collections of scalar 
values indexed by their associated string key.




Values are usually referred to by name, or through a named reference.
The first character of the name tells you to what sort of data
structure it refers.  The rest of the name tells you the particular
value to which it refers.  Usually this name is a single identifier,
that is, a string beginning with a letter or underscore, and
containing letters, underscores, and digits.  In some cases, it may
be a chain of identifiers, separated by :: (or by the slightly
archaic '); all but the last are interpreted as names of packages,
to locate the namespace in which to look up the final identifier
(see perlmod Packages for details).  It’s possible to substitute
for a simple identifier, an expression that produces a reference
to the value at runtime.   This is described in more detail below
and in (perlref).





Perl also has its own built-in variables whose names don’t follow
these rules.  They have strange names so they don’t accidentally
collide with one of your normal variables.  Strings that match
parenthesized parts of a regular expression are saved under names
containing only digits after the $ (see (perlop) and (perlre)).
In addition, several special variables that provide windows into
the inner working of Perl have names containing punctuation characters
and control characters.  These are documented in perlvar NAME.





Scalar values are always named with ’$’, even when referring to a
scalar that is part of an array or a hash.  The ’$’ symbol works
semantically like the English word "the" in that it indicates a
single value is expected.




    $days               # the simple scalar value "days"
    $days[28]           # the 29th element of array @days
    $days{'Feb'}        # the 'Feb' value from hash %days
    $#days              # the last index of array @days




Entire arrays (and slices of arrays and hashes) are denoted by ’@’,
which works much as the word "these" or "those" does in English,
in that it indicates multiple values are expected.




    @days               # ($days[0], $days[1],... $days[n])
    @days[3,4,5]        # same as ($days[3],$days[4],$days[5])
    @days{'a','c'}      # same as ($days{'a'},$days{'c'})




Entire hashes are denoted by ’%’:




    %days               # (key1, val1, key2, val2 ...)



In addition, subroutines are named with an initial ’&’, though this
is optional when unambiguous, just as the word "do" is often redundant
in English.  Symbol table entries can be named with an initial ’*’,
but you don’t really care about that yet (if ever :-).




Every variable type has its own namespace, as do several
non-variable identifiers.  This means that you can, without fear
of conflict, use the same name for a scalar variable, an array, or
a hash–or, for that matter, for a filehandle, a directory handle, a
subroutine name, a format name, or a label.  This means that $foo
and @foo are two different variables.  It also means that $foo[1]
is a part of @foo, not a part of $foo.  This may seem a bit weird,
but that’s okay, because it is weird.






Because variable references always start with ’$’, ’@’, or ’%’, the
"reserved" words aren’t in fact reserved with respect to variable
names.  They are reserved with respect to labels and filehandles,
however, which don’t have an initial special character.  You can’t
have a filehandle named "log", for instance.  Hint: you could say
open(LOG,'logfile') rather than open(log,'logfile').  Using
uppercase filehandles also improves readability and protects you
from conflict with future reserved words.  Case is significant–"FOO",
"Foo", and "foo" are all different names.  Names that start with a
letter or underscore may also contain digits and underscores.




It is possible to replace such an alphanumeric name with an expression
that returns a reference to the appropriate type.  For a description
of this, see (perlref).



Names that start with a digit may contain only more digits.  Names
that do not start with a letter, underscore, digit or a caret (i.e.
a control character) are limited to one character, e.g.,  $% or
$$.  (Most of these one character names have a predefined
significance to Perl.  For instance, $$ is the current process
id.)









Next: , Previous: perldata Variable names, Up: perldata DESCRIPTION   [Contents]





11.2.2 Context






The interpretation of operations and values in Perl sometimes depends
on the requirements of the context around the operation or value.
There are two major contexts: list and scalar.  Certain operations
return list values in contexts wanting a list, and scalar values
otherwise.  If this is true of an operation it will be mentioned in
the documentation for that operation.  In other words, Perl overloads
certain operations based on whether the expected return value is
singular or plural.  Some words in English work this way, like "fish"
and "sheep".



In a reciprocal fashion, an operation provides either a scalar or a
list context to each of its arguments.  For example, if you say



    int( <STDIN> )



the integer operation provides scalar context for the <>
operator, which responds by reading one line from STDIN and passing it
back to the integer operation, which will then find the integer value
of that line and return that.  If, on the other hand, you say



    sort( <STDIN> )



then the sort operation provides list context for <>, which
will proceed to read every line available up to the end of file, and
pass that list of lines back to the sort routine, which will then
sort those lines and return them as a list to whatever the context
of the sort was.



Assignment is a little bit special in that it uses its left argument
to determine the context for the right argument.  Assignment to a
scalar evaluates the right-hand side in scalar context, while
assignment to an array or hash evaluates the righthand side in list
context.  Assignment to a list (or slice, which is just a list
anyway) also evaluates the right-hand side in list context.



When you use the use warnings pragma or Perl’s -w command-line 
option, you may see warnings
about useless uses of constants or functions in "void context".
Void context just means the value has been discarded, such as a
statement containing only "fred"; or getpwuid(0);.  It still
counts as scalar context for functions that care whether or not
they’re being called in list context.



User-defined subroutines may choose to care whether they are being
called in a void, scalar, or list context.  Most subroutines do not
need to bother, though.  That’s because both scalars and lists are
automatically interpolated into lists.  See (perlfunc)wantarray
for how you would dynamically discern your function’s calling
context.









Next: , Previous: perldata Context, Up: perldata DESCRIPTION   [Contents]





11.2.3 Scalar values







All data in Perl is a scalar, an array of scalars, or a hash of
scalars.  A scalar may contain one single value in any of three
different flavors: a number, a string, or a reference.  In general,
conversion from one form to another is transparent.  Although a
scalar may not directly hold multiple values, it may contain a
reference to an array or hash which in turn contains multiple values.



Scalars aren’t necessarily one thing or another.  There’s no place
to declare a scalar variable to be of type "string", type "number",
type "reference", or anything else.  Because of the automatic
conversion of scalars, operations that return scalars don’t need
to care (and in fact, cannot care) whether their caller is looking
for a string, a number, or a reference.  Perl is a contextually
polymorphic language whose scalars can be strings, numbers, or
references (which includes objects).  Although strings and numbers
are considered pretty much the same thing for nearly all purposes,
references are strongly-typed, uncastable pointers with builtin
reference-counting and destructor invocation.








A scalar value is interpreted as FALSE in the Boolean sense
if it is undefined, the null string or the number 0 (or its
string equivalent, "0"), and TRUE if it is anything else.  The
Boolean context is just a special kind of scalar context where no 
conversion to a string or a number is ever performed.









There are actually two varieties of null strings (sometimes referred
to as "empty" strings), a defined one and an undefined one.  The
defined version is just a string of length zero, such as "".
The undefined version is the value that indicates that there is
no real value for something, such as when there was an error, or
at end of file, or when you refer to an uninitialized variable or
element of an array or hash.  Although in early versions of Perl,
an undefined scalar could become defined when first used in a
place expecting a defined value, this no longer happens except for
rare cases of autovivification as explained in (perlref).  You can
use the defined() operator to determine whether a scalar value is
defined (this has no meaning on arrays or hashes), and the undef()
operator to produce an undefined value.




To find out whether a given string is a valid non-zero number, it’s
sometimes enough to test it against both numeric 0 and also lexical
"0" (although this will cause noises if warnings are on).  That’s 
because strings that aren’t numbers count as 0, just as they do in awk:



    if ($str == 0 && $str ne "0")  {
        warn "That doesn't look like a number";
    }



That method may be best because otherwise you won’t treat IEEE
notations like NaN or Infinity properly.  At other times, you
might prefer to determine whether string data can be used numerically
by calling the POSIX::strtod() function or by inspecting your string
with a regular expression (as documented in (perlre)).



    warn "has nondigits"        if     /\D/;
    warn "not a natural number" unless /^\d+$/;             # rejects -3
    warn "not an integer"       unless /^-?\d+$/;           # rejects +3
    warn "not an integer"       unless /^[+-]?\d+$/;
    warn "not a decimal number" unless /^-?\d+\.?\d*$/;     # rejects .2
    warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
    warn "not a C float"
        unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;





The length of an array is a scalar value.  You may find the length
of array @days by evaluating $#days, as in csh.  However, this
isn’t the length of the array; it’s the subscript of the last element,
which is a different value since there is ordinarily a 0th element.
Assigning to $#days actually changes the length of the array.
Shortening an array this way destroys intervening values.  Lengthening
an array that was previously shortened does not recover values
that were in those elements.  (It used to do so in Perl 4, but we
had to break this to make sure destructors were called when expected.)




You can also gain some minuscule measure of efficiency by pre-extending
an array that is going to get big.  You can also extend an array
by assigning to an element that is off the end of the array.  You
can truncate an array down to nothing by assigning the null list
() to it.  The following are equivalent:



    @whatever = ();
    $#whatever = -1;




If you evaluate an array in scalar context, it returns the length
of the array.  (Note that this is not true of lists, which return
the last value, like the C comma operator, nor of built-in functions,
which return whatever they feel like returning.)  The following is
always true:




    scalar(@whatever) == $#whatever + 1;



Some programmers choose to use an explicit conversion so as to 
leave nothing to doubt:



    $element_count = scalar(@whatever);






If you evaluate a hash in scalar context, it returns false if the
hash is empty.  If there are any key/value pairs, it returns true;
more precisely, the value returned is a string consisting of the
number of used buckets and the number of allocated buckets, separated
by a slash.  This is pretty much useful only to find out whether
Perl’s internal hashing algorithm is performing poorly on your data
set.  For example, you stick 10,000 things in a hash, but evaluating
%HASH in scalar context reveals "1/16", which means only one out
of sixteen buckets has been touched, and presumably contains all
10,000 of your items.  This isn’t supposed to happen.  If a tied hash
is evaluated in scalar context, the SCALAR method is called (with a
fallback to FIRSTKEY).




You can preallocate space for a hash by assigning to the keys() function.
This rounds up the allocated buckets to the next power of two:



    keys(%users) = 1000;                # allocate 1024 buckets









Next: , Previous: perldata Scalar values, Up: perldata DESCRIPTION   [Contents]





11.2.4 Scalar value constructors





Numeric literals are specified in any of the following floating point or
integer formats:



    12345
    12345.67
    .23E-10             # a very small number
    3.14_15_92          # a very important number
    4_294_967_296       # underscore for legibility
    0xff                # hex
    0xdead_beef         # more hex   
    0377                # octal (only numbers, begins with 0)
    0b011011            # binary




You are allowed to use underscores (underbars) in numeric literals
between digits for legibility (but not multiple underscores in a row:
23__500 is not legal; 23_500 is).
You could, for example, group binary
digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.





String literals are usually delimited by either single or double
quotes.  They work much like quotes in the standard Unix shells:
double-quoted string literals are subject to backslash and variable
substitution; single-quoted strings are not (except for \' and
\\).  The usual C-style backslash rules apply for making
characters such as newline, tab, etc., as well as some more exotic
forms.  See (perlop)Quote and Quote-like Operators for a list.




Hexadecimal, octal, or binary, representations in string literals
(e.g. ’0xff’) are not automatically converted to their integer
representation.  The hex() and oct() functions make these conversions
for you.  See (perlfunc)hex and (perlfunc)oct for more details.




You can also embed newlines directly in your strings, i.e., they can end
on a different line than they begin.  This is nice, but if you forget
your trailing quote, the error will not be reported until Perl finds
another line containing the quote character, which may be much further
on in the script.  Variable substitution inside strings is limited to
scalar variables, arrays, and array or hash slices.  (In other words,
names beginning with $ or @, followed by an optional bracketed
expression as a subscript.)  The following code segment prints out "The
price is $100."




    $Price = '$100';    # not interpolated
    print "The price is $Price.\n";     # interpolated



There is no double interpolation in Perl, so the $100 is left as is.



By default floating point numbers substituted inside strings use the
dot (".")  as the decimal separator.  If use locale is in effect,
and POSIX::setlocale() has been called, the character used for the
decimal separator is affected by the LC_NUMERIC locale.
See perllocale NAME and (POSIX).




As in some shells, you can enclose the variable name in braces to
disambiguate it from following alphanumerics (and underscores).
You must also do
this when interpolating a variable into a string to separate the
variable name from a following double-colon or an apostrophe, since
these would be otherwise treated as a package separator:




    $who = "Larry";
    print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
    print "We use ${who}speak when ${who}'s here.\n";



Without the braces, Perl would have looked for a $whospeak, a
$who::0, and a $who's variable.  The last two would be the
$0 and the $s variables in the (presumably) non-existent package
who.



In fact, an identifier within such curlies is forced to be a string,
as is any simple identifier within a hash subscript.  Neither need
quoting.  Our earlier example, $days{'Feb'} can be written as
$days{Feb} and the quotes will be assumed automatically.  But
anything more complicated in the subscript will be interpreted as an
expression.  This means for example that $version{2.0}++ is
equivalent to $version{2}++, not to $version{'2.0'}++.





• perldata Version Strings:  



• perldata Special Literals:  



• perldata Barewords:  



• perldata Array Interpolation:  












Next: , Up: perldata Scalar value constructors   [Contents]





11.2.4.1 Version Strings






A literal of the form v1.20.300.4000 is parsed as a string composed
of characters with the specified ordinals.  This form, known as
v-strings, provides an alternative, more readable way to construct
strings, rather than use the somewhat less readable interpolation form
"\x{1}\x{14}\x{12c}\x{fa0}".  This is useful for representing
Unicode strings, and for comparing version "numbers" using the string
comparison operators, cmp, gt, lt etc.  If there are two or
more dots in the literal, the leading v may be omitted.



    print v9786;              # prints SMILEY, "\x{263a}"
    print v102.111.111;       # prints "foo"
    print 102.111.111;        # same



Such literals are accepted by both require and use for
doing a version check.  Note that using the v-strings for IPv4
addresses is not portable unless you also use the
inet_aton()/inet_ntoa() routines of the Socket package.



Note that since Perl 5.8.1 the single-number v-strings (like v65)
are not v-strings before the => operator (which is usually used
to separate a hash key from a hash value); instead they are interpreted
as literal strings (’v65’).  They were v-strings from Perl 5.6.0 to
Perl 5.8.0, but that caused more confusion and breakage than good.
Multi-number v-strings like v65.66 and 65.66.67 continue to
be v-strings always.









Next: , Previous: perldata Version Strings, Up: perldata Scalar value constructors   [Contents]





11.2.4.2 Special Literals



















The special literals __FILE__, __LINE__, and __PACKAGE__
represent the current filename, line number, and package name at that
point in your program.  __SUB__ gives a reference to the current
subroutine.  They may be used only as separate tokens; they
will not be interpolated into strings.  If there is no current package
(due to an empty package; directive), __PACKAGE__ is the undefined
value. (But the empty package; is no longer supported, as of version
5.10.)  Outside of a subroutine, __SUB__ is the undefined value.  __SUB__
is only available in 5.16 or higher, and only with a use v5.16 or
use feature "current_sub" declaration.




The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
may be used to indicate the logical end of the script before the actual
end of file.  Any following text is ignored.



Text after __DATA__ may be read via the filehandle PACKNAME::DATA,
where PACKNAME is the package that was current when the __DATA__
token was encountered.  The filehandle is left open pointing to the
line after __DATA__.  The program should close DATA when it is done
reading from it.  (Leaving it open leaks filehandles if the module is
reloaded for any reason, so it’s a safer practice to close it.)  For
compatibility with older scripts written before __DATA__ was
introduced, __END__ behaves like __DATA__ in the top level script (but
not in files loaded with require or do) and leaves the remaining
contents of the file accessible via main::DATA.



See (SelfLoader) for more description of __DATA__, and
an example of its use.  Note that you cannot read from the DATA
filehandle in a BEGIN block: the BEGIN block is executed as soon
as it is seen (during compilation), at which point the corresponding
__DATA__ (or __END__) token has not yet been seen.









Next: , Previous: perldata Special Literals, Up: perldata Scalar value constructors   [Contents]





11.2.4.3 Barewords




A word that has no other interpretation in the grammar will
be treated as if it were a quoted string.  These are known as
"barewords".  As with filehandles and labels, a bareword that consists
entirely of lowercase letters risks conflict with future reserved
words, and if you use the use warnings pragma or the -w switch, 
Perl will warn you about any such words.  Perl limits barewords (like
identifiers) to about 250 characters.  Future versions of Perl are likely
to eliminate these arbitrary limitations.



Some people may wish to outlaw barewords entirely.  If you
say



    use strict 'subs';



then any bareword that would NOT be interpreted as a subroutine call
produces a compile-time error instead.  The restriction lasts to the
end of the enclosing block.  An inner block may countermand this
by saying no strict 'subs'.









Previous: perldata Barewords, Up: perldata Scalar value constructors   [Contents]





11.2.4.4 Array Interpolation






Arrays and slices are interpolated into double-quoted strings
by joining the elements with the delimiter specified in the $"
variable ($LIST_SEPARATOR if "use English;" is specified), 
space by default.  The following are equivalent:



    $temp = join($", @ARGV);
    system "echo $temp";

    system "echo @ARGV";



Within search patterns (which also undergo double-quotish substitution)
there is an unfortunate ambiguity:  Is /$foo[bar]/ to be interpreted as
/${foo}[bar]/ (where [bar] is a character class for the regular
expression) or as /${foo[bar]}/ (where [bar] is the subscript to array
@foo)?  If @foo doesn’t otherwise exist, then it’s obviously a
character class.  If @foo exists, Perl takes a good guess about [bar],
and is almost always right.  If it does guess wrong, or if you’re just
plain paranoid, you can force the correct interpretation with curly
braces as above.



If you’re looking for the information on how to use here-documents,
which used to be here, that’s been moved to
(perlop)Quote and Quote-like Operators.









Next: , Previous: perldata Scalar value constructors, Up: perldata DESCRIPTION   [Contents]





11.2.5 List value constructors




List values are denoted by separating individual values by commas
(and enclosing the list in parentheses where precedence requires it):



    (LIST)



In a context not requiring a list value, the value of what appears
to be a list literal is simply the value of the final element, as
with the C comma operator.  For example,



    @foo = ('cc', '-E', $bar);



assigns the entire list value to array @foo, but



    $foo = ('cc', '-E', $bar);



assigns the value of variable $bar to the scalar variable $foo.
Note that the value of an actual array in scalar context is the
length of the array; the following assigns the value 3 to $foo:



    @foo = ('cc', '-E', $bar);
    $foo = @foo;                # $foo gets 3



You may have an optional comma before the closing parenthesis of a
list literal, so that you can say:



    @foo = (
        1,
        2,
        3,
    );



To use a here-document to assign an array, one line per element,
you might use an approach like this:



    @sauces = <<End_Lines =~ m/(\S.*\S)/g;
        normal tomato
        spicy tomato
        green chile
        pesto
        white wine
    End_Lines



LISTs do automatic interpolation of sublists.  That is, when a LIST is
evaluated, each element of the list is evaluated in list context, and
the resulting list value is interpolated into LIST just as if each
individual element were a member of LIST.  Thus arrays and hashes lose their
identity in a LIST–the list



    (@foo,@bar,&SomeSub,%glarch)



contains all the elements of @foo followed by all the elements of @bar,
followed by all the elements returned by the subroutine named SomeSub 
called in list context, followed by the key/value pairs of %glarch.
To make a list reference that does NOT interpolate, see (perlref).



The null list is represented by ().  Interpolating it in a list
has no effect.  Thus ((),(),()) is equivalent to ().  Similarly,
interpolating an array with no elements is the same as if no
array had been interpolated at that point.



This interpolation combines with the facts that the opening
and closing parentheses are optional (except when necessary for
precedence) and lists may end with an optional comma to mean that
multiple commas within lists are legal syntax. The list 1,,3 is a
concatenation of two lists, 1, and 3, the first of which ends
with that optional comma.  1,,3 is (1,),(3) is 1,3 (And
similarly for 1,,,3 is (1,),(,),3 is 1,3 and so on.)  Not that
we’d advise you to use this obfuscation.



A list value may also be subscripted like a normal array.  You must
put the list in parentheses to avoid ambiguity.  For example:



    # Stat returns list value.
    $time = (stat($file))[8];

    # SYNTAX ERROR HERE.
    $time = stat($file)[8];  # OOPS, FORGOT PARENTHESES

    # Find a hex digit.
    $hexdigit = ('a','b','c','d','e','f')[$digit-10];

    # A "reverse comma operator".
    return (pop(@foo),pop(@foo))[0];



Lists may be assigned to only when each element of the list
is itself legal to assign to:



    ($a, $b, $c) = (1, 2, 3);

    ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);



An exception to this is that you may assign to undef in a list.
This is useful for throwing away some of the return values of a
function:



    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);



List assignment in scalar context returns the number of elements
produced by the expression on the right side of the assignment:



    $x = (($foo,$bar) = (3,2,1));       # set $x to 3, not 2
    $x = (($foo,$bar) = f());           # set $x to f()'s return count



This is handy when you want to do a list assignment in a Boolean
context, because most list functions return a null list when finished,
which when assigned produces a 0, which is interpreted as FALSE.



It’s also the source of a useful idiom for executing a function or
performing an operation in list context and then counting the number of
return values, by assigning to an empty list and then using that
assignment in scalar context. For example, this code:



    $count = () = $string =~ /\d+/g;



will place into $count the number of digit groups found in $string.
This happens because the pattern match is in list context (since it
is being assigned to the empty list), and will therefore return a list
of all matching parts of the string. The list assignment in scalar
context will translate that into the number of elements (here, the
number of times the pattern matched) and assign that to $count. Note
that simply using



    $count = $string =~ /\d+/g;



would not have worked, since a pattern match in scalar context will
only return true or false, rather than a count of matches.



The final element of a list assignment may be an array or a hash:



    ($a, $b, @rest) = split;
    my($a, $b, %rest) = @_;



You can actually put an array or hash anywhere in the list, but the first one
in the list will soak up all the values, and anything after it will become
undefined.  This may be useful in a my() or local().



A hash can be initialized using a literal list holding pairs of
items to be interpreted as a key and a value:



    # same as map assignment above
    %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);



While literal lists and named arrays are often interchangeable, that’s
not the case for hashes.  Just because you can subscript a list value like
a normal array does not mean that you can subscript a list value as a
hash.  Likewise, hashes included as parts of other lists (including
parameters lists and return lists from functions) always flatten out into
key/value pairs.  That’s why it’s good to use references sometimes.



It is often more readable to use the => operator between key/value
pairs.  The => operator is mostly just a more visually distinctive
synonym for a comma, but it also arranges for its left-hand operand to be
interpreted as a string if it’s a bareword that would be a legal simple
identifier. => doesn’t quote compound identifiers, that contain
double colons. This makes it nice for initializing hashes:



    %map = (
                 red   => 0x00f,
                 blue  => 0x0f0,
                 green => 0xf00,
   );



or for initializing hash references to be used as records:



    $rec = {
                witch => 'Mable the Merciless',
                cat   => 'Fluffy the Ferocious',
                date  => '10/31/1776',
    };



or for using call-by-named-parameter to complicated functions:



   $field = $query->radio_group(
               name      => 'group_name',
               values    => ['eenie','meenie','minie'],
               default   => 'meenie',
               linebreak => 'true',
               labels    => \%labels
   );



Note that just because a hash is initialized in that order doesn’t
mean that it comes out in that order.  See (perlfunc)sort for examples
of how to arrange for an output ordering.









Next: , Previous: perldata List value constructors, Up: perldata DESCRIPTION   [Contents]





11.2.6 Subscripts



An array can be accessed one scalar at a
time by specifying a dollar sign ($), then the
name of the array (without the leading @), then the subscript inside
square brackets.  For example:



    @myarray = (5, 50, 500, 5000);
    print "The Third Element is", $myarray[2], "\n";



The array indices start with 0. A negative subscript retrieves its 
value from the end.  In our example, $myarray[-1] would have been 
5000, and $myarray[-2] would have been 500.



Hash subscripts are similar, only instead of square brackets curly brackets
are used. For example:



    %scientists = 
    (
        "Newton" => "Isaac",
        "Einstein" => "Albert",
        "Darwin" => "Charles",
        "Feynman" => "Richard",
    );

    print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";



You can also subscript a list to get a single element from it:



    $dir = (getpwnam("daemon"))[7];









Next: , Previous: perldata Subscripts, Up: perldata DESCRIPTION   [Contents]





11.2.7 Multi-dimensional array emulation



Multidimensional arrays may be emulated by subscripting a hash with a
list. The elements of the list are joined with the subscript separator
(see perlvar $;).



    $foo{$a,$b,$c}



is equivalent to



    $foo{join($;, $a, $b, $c)}



The default subscript separator is "\034", the same as SUBSEP in awk.









Next: , Previous: perldata Multi-dimensional array emulation, Up: perldata DESCRIPTION   [Contents]





11.2.8 Slices






A slice accesses several elements of a list, an array, or a hash
simultaneously using a list of subscripts.  It’s more convenient
than writing out the individual elements as a list of separate
scalar values.



    ($him, $her)   = @folks[0,-1];              # array slice
    @them          = @folks[0 .. 3];            # array slice
    ($who, $home)  = @ENV{"USER", "HOME"};      # hash slice
    ($uid, $dir)   = (getpwnam("daemon"))[2,7]; # list slice



Since you can assign to a list of variables, you can also assign to
an array or hash slice.



    @days[3..5]    = qw/Wed Thu Fri/;
    @colors{'red','blue','green'} 
                   = (0xff0000, 0x0000ff, 0x00ff00);
    @folks[0, -1]  = @folks[-1, 0];



The previous assignments are exactly equivalent to



    ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
    ($colors{'red'}, $colors{'blue'}, $colors{'green'})
                   = (0xff0000, 0x0000ff, 0x00ff00);
    ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);



Since changing a slice changes the original array or hash that it’s
slicing, a foreach construct will alter some–or even all–of the
values of the array or hash.



    foreach (@array[ 4 .. 10 ]) { s/peter/paul/ } 

    foreach (@hash{qw[key1 key2]}) {
        s/^\s+//;           # trim leading whitespace
        s/\s+$//;           # trim trailing whitespace
        s/(\w+)/\u\L$1/g;   # "titlecase" words
    }



A slice of an empty list is still an empty list.  Thus:



    @a = ()[1,0];           # @a has no elements
    @b = (@a)[0,1];         # @b has no elements
    @c = (0,1)[2,3];        # @c has no elements



But:



    @a = (1)[1,0];          # @a has two elements
    @b = (1,undef)[1,0,2];  # @b has three elements



This makes it easy to write loops that terminate when a null list
is returned:



    while ( ($home, $user) = (getpwent)[7,0]) {
        printf "%-8s %s\n", $user, $home;
    }



As noted earlier in this document, the scalar sense of list assignment
is the number of elements on the right-hand side of the assignment.
The null list contains no elements, so when the password file is
exhausted, the result is 0, not 2.



Slices in scalar context return the last item of the slice.



    @a = qw/first second third/;
    %h = (first => 'A', second => 'B');
    $t = @a[0, 1];                  # $t is now 'second'
    $u = @h{'first', 'second'};     # $u is now 'B'



If you’re confused about why you use an ’@’ there on a hash slice
instead of a ’%’, think of it like this.  The type of bracket (square
or curly) governs whether it’s an array or a hash being looked at.
On the other hand, the leading symbol (’$’ or ’@’) on the array or
hash indicates whether you are getting back a singular value (a
scalar) or a plural one (a list).









Previous: perldata Slices, Up: perldata DESCRIPTION   [Contents]





11.2.9 Typeglobs and Filehandles






Perl uses an internal type called a typeglob to hold an entire
symbol table entry.  The type prefix of a typeglob is a *, because
it represents all types.  This used to be the preferred way to
pass arrays and hashes by reference into a function, but now that
we have real references, this is seldom needed.  



The main use of typeglobs in modern Perl is create symbol table aliases.
This assignment:



    *this = *that;



makes $this an alias for $that, @this an alias for @that, %this an alias
for %that, &this an alias for &that, etc.  Much safer is to use a reference.
This:



    local *Here::blue = \$There::green;



temporarily makes $Here::blue an alias for $There::green, but doesn’t
make @Here::blue an alias for @There::green, or %Here::blue an alias for
%There::green, etc.  See perlmod Symbol Tables for more examples
of this.  Strange though this may seem, this is the basis for the whole
module import/export system.



Another use for typeglobs is to pass filehandles into a function or
to create new filehandles.  If you need to use a typeglob to save away
a filehandle, do it this way:



    $fh = *STDOUT;



or perhaps as a real reference, like this:



    $fh = \*STDOUT;



See (perlsub) for examples of using these as indirect filehandles
in functions.



Typeglobs are also a way to create a local filehandle using the local()
operator.  These last until their block is exited, but may be passed back.
For example:



    sub newopen {
        my $path = shift;
        local  *FH;  # not my!
        open   (FH, $path)          or  return undef;
        return *FH;
    }
    $fh = newopen('/etc/passwd');



Now that we have the *foo{THING} notation, typeglobs aren’t used as much
for filehandle manipulations, although they’re still needed to pass brand
new file and directory handles into or out of functions. That’s because
*HANDLE{IO} only works if HANDLE has already been used as a handle.
In other words, *FH must be used to create new symbol table entries;
*foo{THING} cannot.  When in doubt, use *FH.



All functions that are capable of creating filehandles (open(),
opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
automatically create an anonymous filehandle if the handle passed to
them is an uninitialized scalar variable. This allows the constructs
such as open(my $fh, ...) and open(local $fh,...) to be used to
create filehandles that will conveniently be closed automatically when
the scope ends, provided there are no other references to them. This
largely eliminates the need for typeglobs when opening filehandles
that must be passed around, as in the following example:



    sub myopen {
        open my $fh, "@_"
             or die "Can't open '@_': $!";
        return $fh;
    }

    {
        my $f = myopen("</etc/motd");
        print <$f>;
        # $f implicitly closed here
    }



Note that if an initialized scalar variable is used instead the
result is different: my $fh='zzz'; open($fh, ...) is equivalent
to open( *{'zzz'}, ...).
use strict 'refs' forbids such practice.



Another way to create anonymous filehandles is with the Symbol
module or with the IO::Handle module and its ilk.  These modules
have the advantage of not hiding different types of the same name
during the local().  See the bottom of (perlfunc)open for an
example.









Previous: perldata DESCRIPTION, Up: perldata   [Contents]





11.3 SEE ALSO



See perlvar NAME for a description of Perl’s built-in variables and
a discussion of legal variable names.  See (perlref), (perlsub),
and perlmod Symbol Tables for more discussion on typeglobs and
the *foo{THING} syntax.









Next: , Previous: perldata, Up: Top   [Contents]





12 perldbmfilter





• perldbmfilter NAME:  



• perldbmfilter SYNOPSIS:  



• perldbmfilter DESCRIPTION:  



• perldbmfilter SEE ALSO:  



• perldbmfilter AUTHOR:  












Next: , Up: perldbmfilter   [Contents]





12.1 NAME



perldbmfilter - Perl DBM Filters









Next: , Previous: perldbmfilter NAME, Up: perldbmfilter   [Contents]





12.2 SYNOPSIS



    $db = tie %hash, 'DBM', ...

    $old_filter = $db->filter_store_key  ( sub { ... } );
    $old_filter = $db->filter_store_value( sub { ... } );
    $old_filter = $db->filter_fetch_key  ( sub { ... } );
    $old_filter = $db->filter_fetch_value( sub { ... } );









Next: , Previous: perldbmfilter SYNOPSIS, Up: perldbmfilter   [Contents]





12.3 DESCRIPTION



The four filter_* methods shown above are available in all the DBM
modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
ODBM_File and SDBM_File.



Each of the methods works identically, and is used to install (or
uninstall) a single DBM Filter. The only difference between them is the
place that the filter is installed.



To summarise:





filter_store_key




If a filter has been installed with this method, it will be invoked
every time you write a key to a DBM database.





filter_store_value




If a filter has been installed with this method, it will be invoked
every time you write a value to a DBM database.





filter_fetch_key




If a filter has been installed with this method, it will be invoked
every time you read a key from a DBM database.





filter_fetch_value




If a filter has been installed with this method, it will be invoked
every time you read a value from a DBM database.








You can use any combination of the methods from none to all four.



All filter methods return the existing filter, if present, or undef
if not.



To delete a filter pass undef to it.





• perldbmfilter The Filter:  



• perldbmfilter An Example: the NULL termination problem.:  



• perldbmfilter Another Example: Key is a C int.:  












Next: , Up: perldbmfilter DESCRIPTION   [Contents]





12.3.1 The Filter



When each filter is called by Perl, a local copy of $_ will contain
the key or value to be filtered. Filtering is achieved by modifying
the contents of $_. The return code from the filter is ignored.









Next: , Previous: perldbmfilter The Filter, Up: perldbmfilter DESCRIPTION   [Contents]





12.3.2 An Example: the NULL termination problem.



DBM Filters are useful for a class of problems where you always
want to make the same transformation to all keys, all values or both.



For example, consider the following scenario. You have a DBM database
that you need to share with a third-party C application. The C application
assumes that all keys and values are NULL terminated. Unfortunately
when Perl writes to DBM databases it doesn’t use NULL termination, so
your Perl application will have to manage NULL termination itself. When
you write to the database you will have to use something like this:



    $hash{"$key\0"} = "$value\0";



Similarly the NULL needs to be taken into account when you are considering
the length of existing keys/values.



It would be much better if you could ignore the NULL terminations issue
in the main application code and have a mechanism that automatically
added the terminating NULL to all keys and values whenever you write to
the database and have them removed when you read from the database. As I’m
sure you have already guessed, this is a problem that DBM Filters can
fix very easily.



    use strict;
    use warnings;
    use SDBM_File;
    use Fcntl;

    my %hash;
    my $filename = "filt";
    unlink $filename;

    my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
      or die "Cannot open $filename: $!\n";

    # Install DBM Filters
    $db->filter_fetch_key  ( sub { s/\0$//    } );
    $db->filter_store_key  ( sub { $_ .= "\0" } );
    $db->filter_fetch_value( 
        sub { no warnings 'uninitialized'; s/\0$// } );
    $db->filter_store_value( sub { $_ .= "\0" } );

    $hash{"abc"} = "def";
    my $a = $hash{"ABC"};
    # ...
    undef $db;
    untie %hash;



The code above uses SDBM_File, but it will work with any of the DBM
modules.



Hopefully the contents of each of the filters should be
self-explanatory. Both "fetch" filters remove the terminating NULL,
and both "store" filters add a terminating NULL.









Previous: perldbmfilter An Example: the NULL termination problem., Up: perldbmfilter DESCRIPTION   [Contents]





12.3.3 Another Example: Key is a C int.



Here is another real-life example. By default, whenever Perl writes to
a DBM database it always writes the key and value as strings. So when
you use this:



    $hash{12345} = "something";



the key 12345 will get stored in the DBM database as the 5 byte string
"12345". If you actually want the key to be stored in the DBM database
as a C int, you will have to use pack when writing, and unpack
when reading.



Here is a DBM Filter that does it:



    use strict;
    use warnings;
    use DB_File;
    my %hash;
    my $filename = "filt";
    unlink $filename;


    my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH 
      or die "Cannot open $filename: $!\n";

    $db->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
    $db->filter_store_key  ( sub { $_ = pack ("i", $_) } );
    $hash{123} = "def";
    # ...
    undef $db;
    untie %hash;



The code above uses DB_File, but again it will work with any of the
DBM modules.



This time only two filters have been used; we only need to manipulate
the contents of the key, so it wasn’t necessary to install any value
filters.









Next: , Previous: perldbmfilter DESCRIPTION, Up: perldbmfilter   [Contents]





12.4 SEE ALSO



(DB_File), (GDBM_File), (NDBM_File), (ODBM_File) and (SDBM_File).









Previous: perldbmfilter SEE ALSO, Up: perldbmfilter   [Contents]





12.5 AUTHOR



Paul Marquess









Next: , Previous: perldbmfilter, Up: Top   [Contents]





13 perldebguts





• perldebguts NAME:  



• perldebguts DESCRIPTION:  



• perldebguts Debugger Internals:  



• perldebguts Frame Listing Output Examples:  



• perldebguts Debugging Regular Expressions:  



• perldebguts Debugging Perl Memory Usage:  



• perldebguts SEE ALSO:  












Next: , Up: perldebguts   [Contents]





13.1 NAME



perldebguts - Guts of Perl debugging 









Next: , Previous: perldebguts NAME, Up: perldebguts   [Contents]





13.2 DESCRIPTION



This is not (perldebug), which tells you how to use
the debugger.  This manpage describes low-level details concerning
the debugger’s internals, which range from difficult to impossible
to understand for anyone who isn’t incredibly intimate with Perl’s guts.
Caveat lector.









Next: , Previous: perldebguts DESCRIPTION, Up: perldebguts   [Contents]





13.3 Debugger Internals



Perl has special debugging hooks at compile-time and run-time used
to create debugging environments.  These hooks are not to be confused
with the perl -Dxxx command described in perlrun NAME, which is
usable only if a special Perl is built per the instructions in the
INSTALL podpage in the Perl source tree.



For example, whenever you call Perl’s built-in caller function
from the package DB, the arguments that the corresponding stack
frame was called with are copied to the @DB::args array.  These
mechanisms are enabled by calling Perl with the -d switch.
Specifically, the following additional features are enabled
(cf. perlvar $^P):





Note that if &DB::sub needs external data for it to work, no
subroutine call is possible without it. As an example, the standard
debugger’s &DB::sub depends on the $DB::deep variable
(it defines how many levels of recursion deep into the debugger you can go
before a mandatory break).  If $DB::deep is not defined, subroutine
calls are not possible, even though &DB::sub exists.





• perldebguts Writing Your Own Debugger:  












Up: perldebguts Debugger Internals   [Contents]





13.3.1 Writing Your Own Debugger





• perldebguts Environment Variables:  



• perldebguts Debugger Internal Variables:  



• perldebguts Debugger Customization Functions:  












Next: , Up: perldebguts Writing Your Own Debugger   [Contents]





13.3.1.1 Environment Variables



The PERL5DB environment variable can be used to define a debugger.
For example, the minimal "working" debugger (it actually doesn’t do anything)
consists of one line:



  sub DB::DB {}



It can easily be defined like this:



  $ PERL5DB="sub DB::DB {}" perl -d your-script



Another brief debugger, slightly more useful, can be created
with only the line:



  sub DB::DB {print ++$i; scalar <STDIN>}



This debugger prints a number which increments for each statement
encountered and waits for you to hit a newline before continuing
to the next statement.



The following debugger is actually useful:



  {
    package DB;
    sub DB  {}
    sub sub {print ++$i, " $sub\n"; &$sub}
  }



It prints the sequence number of each subroutine call and the name of the
called subroutine.  Note that &DB::sub is being compiled into the
package DB through the use of the package directive.



When it starts, the debugger reads your rc file (./.perldb or
~/.perldb under Unix), which can set important options.
(A subroutine (&afterinit) can be defined here as well; it is executed
after the debugger completes its own initialization.)



After the rc file is read, the debugger reads the PERLDB_OPTS
environment variable and uses it to set debugger options. The
contents of this variable are treated as if they were the argument
of an o ... debugger command (q.v. in (perldebug)Configurable Options).









Next: , Previous: perldebguts Environment Variables, Up: perldebguts Writing Your Own Debugger   [Contents]





13.3.1.2 Debugger Internal Variables



In addition to the file and subroutine-related variables mentioned above,
the debugger also maintains various magical internal variables.











Previous: perldebguts Debugger Internal Variables, Up: perldebguts Writing Your Own Debugger   [Contents]





13.3.1.3 Debugger Customization Functions



Some functions are provided to simplify customization.





Note that any variables and functions that are not documented in
this manpages (or in (perldebug)) are considered for internal   
use only, and as such are subject to change without notice.









Next: , Previous: perldebguts Debugger Internals, Up: perldebguts   [Contents]





13.4 Frame Listing Output Examples



The frame option can be used to control the output of frame 
information.  For example, contrast this expression trace:



 $ perl -de 42
 Stack dump during die enabled outside of evals.

 Loading DB routines from perl5db.pl patch level 0.94
 Emacs support available.

 Enter h or 'h h' for help.

 main::(-e:1):   0
   DB<1> sub foo { 14 }

   DB<2> sub bar { 3 }

   DB<3> t print foo() * bar()
 main::((eval 172):3):   print foo() + bar();
 main::foo((eval 168):2):
 main::bar((eval 170):2):
 42



with this one, once the option frame=2 has been set:



   DB<4> o f=2
                frame = '2'
   DB<5> t print foo() * bar()
 3:      foo() * bar()
 entering main::foo
  2:     sub foo { 14 };
 exited main::foo
 entering main::bar
  2:     sub bar { 3 };
 exited main::bar
 42



By way of demonstration, we present below a laborious listing
resulting from setting your PERLDB_OPTS environment variable to
the value f=n N, and running perl -d -V from the command line.
Examples using various values of n are shown to give you a feel
for the difference between settings.  Long though it may be, this
is not a complete listing, but only excerpts.



    

  1.  

      entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   entering Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
  entering Config::myconfig
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH

    

  2.  

      entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   exited Config::BEGIN
   Package lib/Config.pm.
   entering Config::TIEHASH
   exited Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
    exited Exporter::export
   exited Exporter::import
  exited main::BEGIN
  entering Config::myconfig
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH

    

  3.  

      in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574

    

  4.  

      in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  out $=main::BEGIN() from /dev/null:0
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574

    

  5.  

      in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  out $=main::BEGIN() from /dev/null:0
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574

    

  6.  

      in  $=CODE(0x15eca4)() from /dev/null:0
   in  $=CODE(0x182528)() from lib/Config.pm:2
    Package lib/Exporter.pm.
   out $=CODE(0x182528)() from lib/Config.pm:0
   scalar context return from CODE(0x182528): undef
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:628
   out $=Config::TIEHASH('Config') from lib/Config.pm:628
   scalar context return from Config::TIEHASH:   empty hash
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    scalar context return from Exporter::export: ''
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
   scalar context return from Exporter::import: ''

    




In all cases shown above, the line indentation shows the call tree.
If bit 2 of frame is set, a line is printed on exit from a
subroutine as well.  If bit 4 is set, the arguments are printed
along with the caller info.  If bit 8 is set, the arguments are
printed even if they are tied or references.  If bit 16 is set, the
return value is printed, too.



When a package is compiled, a line like this



    Package lib/Carp.pm.



is printed with proper indentation.









Next: , Previous: perldebguts Frame Listing Output Examples, Up: perldebguts   [Contents]





13.5 Debugging Regular Expressions



There are two ways to enable debugging output for regular expressions.



If your perl is compiled with -DDEBUGGING, you may use the
-Dr flag on the command line.



Otherwise, one can use re 'debug', which has effects at
compile time and run time.  Since Perl 5.9.5, this pragma is lexically
scoped.





• perldebguts Compile-time Output:  



• perldebguts Types of Nodes:  



• perldebguts Run-time Output:  












Next: , Up: perldebguts Debugging Regular Expressions   [Contents]





13.5.1 Compile-time Output



The debugging output at compile time looks like this:



  Compiling REx '[bc]d(ef*g)+h[ij]k$'
  size 45 Got 364 bytes for offset annotations.
  first at 1
  rarest char g at 0
  rarest char d at 0
     1: ANYOF[bc](12)
    12: EXACT <d>(14)
    14: CURLYX[0] {1,32767}(28)
    16:   OPEN1(18)
    18:     EXACT <e>(20)
    20:     STAR(23)
    21:       EXACT <f>(0)
    23:     EXACT <g>(25)
    25:   CLOSE1(27)
    27:   WHILEM[1/1](0)
    28: NOTHING(29)
    29: EXACT <h>(31)
    31: ANYOF[ij](42)
    42: EXACT <k>(44)
    44: EOL(45)
    45: END(0)
  anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating) 
        stclass 'ANYOF[bc]' minlen 7 
  Offsets: [45]
        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]  
  Omitting $` $& $' support.



The first line shows the pre-compiled form of the regex.  The second
shows the size of the compiled form (in arbitrary units, usually
4-byte words) and the total number of bytes allocated for the
offset/length table, usually 4+size*8.  The next line shows the
label id of the first node that does a match.



The 



  anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating) 
        stclass 'ANYOF[bc]' minlen 7 



line (split into two lines above) contains optimizer
information.  In the example shown, the optimizer found that the match 
should contain a substring de at offset 1, plus substring gh
at some offset between 3 and infinity.  Moreover, when checking for
these substrings (to abandon impossible matches quickly), Perl will check
for the substring gh before checking for the substring de.  The
optimizer may also use the knowledge that the match starts (at the
first id) with a character class, and no string 
shorter than 7 characters can possibly match.



The fields of interest which may appear in this line are





anchored STRING at POS






floating STRING at POS1..POS2




See above.





matching floating/anchored




Which substring to check first.





minlen




The minimal length of the match.





stclass TYPE




Type of first matching node.





noscan




Don’t scan for the found substrings.





isall




Means that the optimizer information is all that the regular
expression contains, and thus one does not need to enter the regex engine at
all.





GPOS




Set if the pattern contains \G.





plus




Set if the pattern starts with a repeated char (as in x+y).





implicit




Set if the pattern starts with .*.





with eval




Set if the pattern contain eval-groups, such as (?{ code }) and
(??{ code }).





anchored(TYPE)




If the pattern may match only at a handful of places, with TYPE
being BOL, MBOL, or GPOS.  See the table below.








If a substring is known to match at end-of-line only, it may be
followed by $, as in floating 'k'$.



The optimizer-specific information is used to avoid entering (a slow) regex
engine on strings that will not definitely match.  If the isall flag
is set, a call to the regex engine may be avoided even when the optimizer
found an appropriate place for the match.



Above the optimizer section is the list of nodes of the compiled
form of the regex.  Each line has format 



   id: TYPE OPTIONAL-INFO (next-id)









Next: , Previous: perldebguts Compile-time Output, Up: perldebguts Debugging Regular Expressions   [Contents]





13.5.2 Types of Nodes



Here are the possible types, with short descriptions:



 # TYPE arg-description [num-args] [longjump-len] DESCRIPTION

 # Exit points
 END   no        End of program.
 SUCCEED   no        Return from a subroutine, basically.

 # Anchors:

 BOL        no      Match "" at beginning of line.
 MBOL       no      Same, assuming multiline.
 SBOL       no      Same, assuming singleline.
 EOS        no      Match "" at end of string.
 EOL        no      Match "" at end of line.
 MEOL       no      Same, assuming multiline.
 SEOL       no      Same, assuming singleline.
 BOUND      no      Match "" at any word boundary using native charset
                    semantics for non-utf8
 BOUNDL     no      Match "" at any locale word boundary
 BOUNDU     no      Match "" at any word boundary using Unicode semantics
 BOUNDA     no      Match "" at any word boundary using ASCII semantics
 NBOUND     no      Match "" at any word non-boundary using native charset
                    semantics for non-utf8
 NBOUNDL    no      Match "" at any locale word non-boundary
 NBOUNDU    no      Match "" at any word non-boundary using Unicode semantics
 NBOUNDA    no      Match "" at any word non-boundary using ASCII semantics
 GPOS       no      Matches where last m//g left off.

 # [Special] alternatives:

 REG_ANY    no      Match any one character (except newline).
 SANY       no      Match any one character.
 CANY       no      Match any one byte.
 ANYOF      sv      Match character in (or not in) this class, single char
                    match only
 ANYOFV     sv      Match character in (or not in) this class, can
                    match-multiple chars
 ALNUM      no      Match any alphanumeric character using native charset
                    semantics for non-utf8
 ALNUML     no      Match any alphanumeric char in locale
 ALNUMU     no      Match any alphanumeric char using Unicode semantics
 ALNUMA     no      Match [A-Za-z_0-9]
 NALNUM     no      Match any non-alphanumeric character using native charset
                    semantics for non-utf8
 NALNUML    no      Match any non-alphanumeric char in locale
 NALNUMU    no      Match any non-alphanumeric char using Unicode semantics
 NALNUMA    no      Match [^A-Za-z_0-9]
 SPACE      no      Match any whitespace character using native charset
                    semantics for non-utf8
 SPACEL     no      Match any whitespace char in locale
 SPACEU     no      Match any whitespace char using Unicode semantics
 SPACEA     no      Match [ \t\n\f\r]
 NSPACE     no      Match any non-whitespace character using native charset
                    semantics for non-utf8
 NSPACEL    no      Match any non-whitespace char in locale
 NSPACEU    no      Match any non-whitespace char using Unicode semantics
 NSPACEA    no      Match [^ \t\n\f\r]
 DIGIT      no      Match any numeric character using native charset semantics
                    for non-utf8
 DIGITL     no      Match any numeric character in locale
 DIGITA     no      Match [0-9]
 NDIGIT     no      Match any non-numeric character using native charset
 i                  semantics for non-utf8
 NDIGITL    no      Match any non-numeric character in locale
 NDIGITA    no      Match [^0-9]
 CLUMP      no      Match any extended grapheme cluster sequence

 # Alternation

 # BRANCH        The set of branches constituting a single choice are hooked
 #               together with their "next" pointers, since precedence prevents
 #               anything being concatenated to any individual branch.  The
 #               "next" pointer of the last BRANCH in a choice points to the
 #               thing following the whole choice.  This is also where the
 #               final "next" pointer of each individual branch points; each
 #               branch starts with the operand node of a BRANCH node.
 #
 BRANCH node        Match this alternative, or the next...

 # Back pointer

 # BACK          Normal "next" pointers all implicitly point forward; BACK
 #               exists to make loop structures possible.
 # not used
 BACK       no      Match "", "next" ptr points backward.

 # Literals

 EXACT      str     Match this string (preceded by length).
 EXACTF     str     Match this string, folded, native charset semantics for
                    non-utf8 (prec. by length).
 EXACTFL    str     Match this string, folded in locale (w/len).
 EXACTFU    str     Match this string, folded, Unicode semantics for non-utf8
                    (prec. by length).
 EXACTFA    str     Match this string, folded, Unicode semantics for non-utf8,
                    but no ASCII-range character matches outside ASCII (prec.
                    by length),.

 # Do nothing types

 NOTHING    no        Match empty string.
 # A variant of above which delimits a group, thus stops optimizations
 TAIL       no        Match empty string. Can jump here from outside.

 # Loops

 # STAR,PLUS    '?', and complex '*' and '+', are implemented as circular
 #               BRANCH structures using BACK.  Simple cases (one character
 #               per match) are implemented with STAR and PLUS for speed
 #               and to minimize recursive plunges.
 #
 STAR       node    Match this (simple) thing 0 or more times.
 PLUS       node    Match this (simple) thing 1 or more times.

 CURLY      sv 2    Match this simple thing {n,m} times.
 CURLYN     no 2    Capture next-after-this simple thing
 CURLYM     no 2    Capture this medium-complex thing {n,m} times.
 CURLYX     sv 2    Match this complex thing {n,m} times.

 # This terminator creates a loop structure for CURLYX
 WHILEM     no      Do curly processing and see if rest matches.

 # Buffer related

 # OPEN,CLOSE,GROUPP     ...are numbered at compile time.
 OPEN       num 1   Mark this point in input as start of #n.
 CLOSE      num 1   Analogous to OPEN.

 REF        num 1   Match some already matched string
 REFF       num 1   Match already matched string, folded using native charset
                    semantics for non-utf8
 REFFL      num 1   Match already matched string, folded in loc.
 REFFU      num 1   Match already matched string, folded using unicode
                    semantics for non-utf8
 REFFA      num 1   Match already matched string, folded using unicode
                    semantics for non-utf8, no mixing ASCII, non-ASCII

 # Named references.  Code in regcomp.c assumes that these all are after the
 # numbered references
 NREF       no-sv 1 Match some already matched string
 NREFF      no-sv 1 Match already matched string, folded using native charset
                    semantics for non-utf8
 NREFFL     no-sv 1 Match already matched string, folded in loc.
 NREFFU     num   1 Match already matched string, folded using unicode
                    semantics for non-utf8
 NREFFA     num   1 Match already matched string, folded using unicode
                    semantics for non-utf8, no mixing ASCII, non-ASCII

 IFMATCH    off 1 2 Succeeds if the following matches.
 UNLESSM    off 1 2 Fails if the following matches.
 SUSPEND    off 1 1 "Independent" sub-RE.
 IFTHEN     off 1 1 Switch, should be preceded by switcher.
 GROUPP     num 1   Whether the group matched.

 # Support for long RE

 LONGJMP    off 1 1 Jump far away.
 BRANCHJ    off 1 1 BRANCH with long offset.

 # The heavy worker

 EVAL       evl 1   Execute some Perl code.

 # Modifiers

 MINMOD     no      Next operator is not greedy.
 LOGICAL    no      Next opcode should set the flag only.

 # This is not used yet
 RENUM      off 1 1 Group with independently numbered parens.

 # Trie Related

 # Behave the same as A|LIST|OF|WORDS would. The '..C' variants have
 # inline charclass data (ascii only), the 'C' store it in the structure.
 # NOTE: the relative order of the TRIE-like regops  is significant

 TRIE       trie 1    Match many EXACT(F[ALU]?)? at once. flags==type
 TRIEC      charclass Same as TRIE, but with embedded charclass data

 # For start classes, contains an added fail table.
 AHOCORASICK trie 1   Aho Corasick stclass. flags==type
 AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data

 # Regex Subroutines
 GOSUB      num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
 GOSTART    no         recurse to start of pattern

 # Special conditionals
 NGROUPP    no-sv 1   Whether the group matched.
 INSUBP     num 1     Whether we are in a specific recurse.
 DEFINEP    none 1    Never execute directly.

 # Backtracking Verbs
 ENDLIKE    none      Used only for the type field of verbs
 OPFAIL     none      Same as (?!)
 ACCEPT     parno 1   Accepts the current matched string.


 # Verbs With Arguments
 VERB       no-sv 1   Used only for the type field of verbs
 PRUNE      no-sv 1   Pattern fails at this startpoint if no-backtracking through this
 MARKPOINT  no-sv 1   Push the current location for rollback by cut.
 SKIP       no-sv 1   On failure skip forward (to the mark) before retrying
 COMMIT     no-sv 1   Pattern fails outright if backtracking through this
 CUTGROUP   no-sv 1   On failure go to the next alternation in the group

 # Control what to keep in $&.
 KEEPS      no        $& begins here.

 # New charclass like patterns
 LNBREAK    none      generic newline pattern
 VERTWS     none      vertical whitespace         (Perl 6)
 NVERTWS    none      not vertical whitespace     (Perl 6)
 HORIZWS    none      horizontal whitespace       (Perl 6)
 NHORIZWS   none      not horizontal whitespace   (Perl 6)

 FOLDCHAR   codepoint 1 codepoint with tricky case folding properties.

 # SPECIAL  REGOPS

 # This is not really a node, but an optimized away piece of a "long" node.
 # To simplify debugging output, we mark it as if it were a node
 OPTIMIZED  off       Placeholder for dump.

 # Special opcode with the property that no opcode in a compiled program
 # will ever be of this type. Thus it can be used as a flag value that
 # no other opcode has been seen. END is used similarly, in that an END
 # node cant be optimized. So END implies "unoptimizable" and PSEUDO mean
 # "not seen anything to optimize yet".
 PSEUDO     off       Pseudo opcode for internal use.



Following the optimizer information is a dump of the offset/length
table, here split across several lines:



  Offsets: [45]
        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]  



The first line here indicates that the offset/length table contains 45
entries.  Each entry is a pair of integers, denoted by offset[length].
Entries are numbered starting with 1, so entry #1 here is 1[4] and
entry #12 is 5[1].  1[4] indicates that the node labeled 1:
(the 1: ANYOF[bc]) begins at character position 1 in the
pre-compiled form of the regex, and has a length of 4 characters.
5[1] in position 12 
indicates that the node labeled 12:
(the 12: EXACT <d>) begins at character position 5 in the
pre-compiled form of the regex, and has a length of 1 character.
12[1] in position 14 
indicates that the node labeled 14:
(the 14: CURLYX[0] {1,32767}) begins at character position 12 in the
pre-compiled form of the regex, and has a length of 1 character—that
is, it corresponds to the + symbol in the precompiled regex.



0[0] items indicate that there is no corresponding node.









Previous: perldebguts Types of Nodes, Up: perldebguts Debugging Regular Expressions   [Contents]





13.5.3 Run-time Output



First of all, when doing a match, one may get no run-time output even
if debugging is enabled.  This means that the regex engine was never
entered and that all of the job was therefore done by the optimizer.



If the regex engine was entered, the output may look like this:



  Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
    Setting an EVAL scope, savestack=3
     2 <ab> <cdefg__gh_>    |  1: ANYOF
     3 <abc> <defg__gh_>    | 11: EXACT <d>
     4 <abcd> <efg__gh_>    | 13: CURLYX {1,32767}
     4 <abcd> <efg__gh_>    | 26:   WHILEM
                                0 out of 1..32767  cc=effff31c
     4 <abcd> <efg__gh_>    | 15:     OPEN1
     4 <abcd> <efg__gh_>    | 17:     EXACT <e>
     5 <abcde> <fg__gh_>    | 19:     STAR
                             EXACT <f> can match 1 times out of 32767...
    Setting an EVAL scope, savestack=3
     6 <bcdef> <g__gh__>    | 22:       EXACT <g>
     7 <bcdefg> <__gh__>    | 24:       CLOSE1
     7 <bcdefg> <__gh__>    | 26:       WHILEM
                                    1 out of 1..32767  cc=effff31c
    Setting an EVAL scope, savestack=12
     7 <bcdefg> <__gh__>    | 15:         OPEN1
     7 <bcdefg> <__gh__>    | 17:         EXACT <e>
       restoring \1 to 4(4)..7
                                    failed, try continuation...
     7 <bcdefg> <__gh__>    | 27:         NOTHING
     7 <bcdefg> <__gh__>    | 28:         EXACT <h>
                                    failed...
                                failed...



The most significant information in the output is about the particular node
of the compiled regex that is currently being tested against the target string.
The format of these lines is



    STRING-OFFSET <PRE-STRING> <POST-STRING>   |ID:  TYPE



The TYPE info is indented with respect to the backtracking level.
Other incidental information appears interspersed within.









Next: , Previous: perldebguts Debugging Regular Expressions, Up: perldebguts   [Contents]





13.6 Debugging Perl Memory Usage



Perl is a profligate wastrel when it comes to memory use.  There
is a saying that to estimate memory usage of Perl, assume a reasonable
algorithm for memory allocation, multiply that estimate by 10, and
while you still may miss the mark, at least you won’t be quite so
astonished.  This is not absolutely true, but may provide a good
grasp of what happens.



Assume that an integer cannot take less than 20 bytes of memory, a
float cannot take less than 24 bytes, a string cannot take less
than 32 bytes (all these examples assume 32-bit architectures, the
result are quite a bit worse on 64-bit architectures).  If a variable
is accessed in two of three different ways (which require an integer,
a float, or a string), the memory footprint may increase yet another
20 bytes.  A sloppy malloc(3) implementation can inflate these
numbers dramatically.



On the opposite end of the scale, a declaration like



  sub foo;



may take up to 500 bytes of memory, depending on which release of Perl
you’re running.



Anecdotal estimates of source-to-compiled code bloat suggest an
eightfold increase.  This means that the compiled form of reasonable
(normally commented, properly indented etc.) code will take
about eight times more space in memory than the code took
on disk.



The -DL command-line switch is obsolete since circa Perl 5.6.0
(it was available only if Perl was built with -DDEBUGGING).
The switch was used to track Perl’s memory allocations and possible
memory leaks.  These days the use of malloc debugging tools like
Purify or valgrind is suggested instead.  See also
perlhacktips PERL_MEM_LOG.



One way to find out how much memory is being used by Perl data
structures is to install the Devel::Size module from CPAN: it gives
you the minimum number of bytes required to store a particular data
structure.  Please be mindful of the difference between the size()
and total_size().



If Perl has been compiled using Perl’s malloc you can analyze Perl
memory usage by setting $ENV{PERL_DEBUG_MSTATS}.





• perldebguts Using $ENV{PERL_DEBUG_MSTATS}:  












Up: perldebguts Debugging Perl Memory Usage   [Contents]





13.6.1 Using $ENV{PERL_DEBUG_MSTATS}



If your perl is using Perl’s malloc() and was compiled with the
necessary switches (this is the default), then it will print memory
usage statistics after compiling your code when $ENV{PERL_DEBUG_MSTATS}
> 1, and before termination of the program when $ENV{PERL_DEBUG_MSTATS} >= 1.  The report format is similar to
the following example:



  $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
  Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
     14216 free:   130   117    28     7     9   0   2     2   1 0 0
                437    61    36     0     5
     60924 used:   125   137   161    55     7   8   6    16   2 0 1
                 74   109   304    84    20
  Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
  Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
     30888 free:   245    78    85    13     6   2   1     3   2 0 1
                315   162    39    42    11
    175816 used:   265   176  1112   111    26  22  11    27   2 1 1
                196   178  1066   798    39
  Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.



It is possible to ask for such a statistic at arbitrary points in
your execution using the mstat() function out of the standard
Devel::Peek module.



Here is some explanation of that format:





buckets SMALLEST(APPROX)..GREATEST(APPROX)




Perl’s malloc() uses bucketed allocations.  Every request is rounded
up to the closest bucket size available, and a bucket is taken from
the pool of buckets of that size.



The line above describes the limits of buckets currently in use.
Each bucket has two sizes: memory footprint and the maximal size
of user data that can fit into this bucket.  Suppose in the above
example that the smallest bucket were size 4.  The biggest bucket
would have usable size 8188, and the memory footprint would be 8192.



In a Perl built for debugging, some buckets may have negative usable
size.  This means that these buckets cannot (and will not) be used.
For larger buckets, the memory footprint may be one page greater
than a power of 2.  If so, the corresponding power of two is
printed in the APPROX field above.





Free/Used




The 1 or 2 rows of numbers following that correspond to the number
of buckets of each size between SMALLEST and GREATEST.  In
the first row, the sizes (memory footprints) of buckets are powers
of two–or possibly one page greater.  In the second row, if present,
the memory footprints of the buckets are between the memory footprints
of two buckets "above".



For example, suppose under the previous example, the memory footprints
were



     free:    8     16    32    64    128  256 512 1024 2048 4096 8192
           4     12    24    48    80



With a non-DEBUGGING perl, the buckets starting from 128 have
a 4-byte overhead, and thus an 8192-long bucket may take up to
8188-byte allocations.





Total sbrk(): SBRKed/SBRKs:CONTINUOUS




The first two fields give the total amount of memory perl sbrk(2)ed
(ess-broken? :-) and number of sbrk(2)s used.  The third number is
what perl thinks about continuity of returned chunks.  So long as
this number is positive, malloc() will assume that it is probable
that sbrk(2) will provide continuous memory.



Memory allocated by external libraries is not counted.





pad: 0




The amount of sbrk(2)ed memory needed to keep buckets aligned.





heads: 2192




Although memory overhead of bigger buckets is kept inside the bucket, for
smaller buckets, it is kept in separate areas.  This field gives the
total size of these areas.





chain: 0




malloc() may want to subdivide a bigger bucket into smaller buckets.
If only a part of the deceased bucket is left unsubdivided, the rest
is kept as an element of a linked list.  This field gives the total
size of these chunks.





tail: 6144




To minimize the number of sbrk(2)s, malloc() asks for more memory.  This
field gives the size of the yet unused part, which is sbrk(2)ed, but
never touched.














Previous: perldebguts Debugging Perl Memory Usage, Up: perldebguts   [Contents]





13.7 SEE ALSO



(perldebug),
perlguts NAME,
perlrun NAME
(re),
and
(Devel-DProf).









Next: , Previous: perldebguts, Up: Top   [Contents]





14 perldebtut





• perldebtut NAME:  



• perldebtut DESCRIPTION:  



• perldebtut use strict:  



• perldebtut Looking at data and -w and v:  



• perldebtut help:  



• perldebtut Stepping through code:  



• perldebtut Placeholder for a, w, t, T:  



• perldebtut REGULAR EXPRESSIONS:  



• perldebtut OUTPUT TIPS:  



• perldebtut CGI:  



• perldebtut GUIs:  



• perldebtut SUMMARY:  



• perldebtut SEE ALSO:  



• perldebtut AUTHOR:  



• perldebtut CONTRIBUTORS:  












Next: , Up: perldebtut   [Contents]





14.1 NAME



perldebtut - Perl debugging tutorial









Next: , Previous: perldebtut NAME, Up: perldebtut   [Contents]





14.2 DESCRIPTION



A (very) lightweight introduction in the use of the perl debugger, and a
pointer to existing, deeper sources of information on the subject of debugging
perl programs.  



There’s an extraordinary number of people out there who don’t appear to know
anything about using the perl debugger, though they use the language every
day.  
This is for them.  









Next: , Previous: perldebtut DESCRIPTION, Up: perldebtut   [Contents]





14.3 use strict



First of all, there’s a few things you can do to make your life a lot more
straightforward when it comes to debugging perl programs, without using the
debugger at all.  To demonstrate, here’s a simple script, named "hello", with
a problem:



        #!/usr/bin/perl

        $var1 = 'Hello World'; # always wanted to do that :-)
        $var2 = "$varl\n";

        print $var2; 
        exit;



While this compiles and runs happily, it probably won’t do what’s expected,
namely it doesn’t print "Hello World\n" at all;  It will on the other hand do
exactly what it was told to do, computers being a bit that way inclined.  That
is, it will print out a newline character, and you’ll get what looks like a
blank line.  It looks like there’s 2 variables when (because of the typo)
there’s really 3:



        $var1 = 'Hello World';
        $varl = undef;
        $var2 = "\n";



To catch this kind of problem, we can force each variable to be declared
before use by pulling in the strict module, by putting ’use strict;’ after the
first line of the script.



Now when you run it, perl complains about the 3 undeclared variables and we
get four error messages because one variable is referenced twice:



 Global symbol "$var1" requires explicit package name at ./t1 line 4.
 Global symbol "$var2" requires explicit package name at ./t1 line 5.
 Global symbol "$varl" requires explicit package name at ./t1 line 5.
 Global symbol "$var2" requires explicit package name at ./t1 line 7.
 Execution of ./hello aborted due to compilation errors.     



Luvverly! and to fix this we declare all variables explicitly and now our
script looks like this:	



        #!/usr/bin/perl
        use strict;

        my $var1 = 'Hello World';
        my $varl = undef;
        my $var2 = "$varl\n";

        print $var2; 
        exit;



We then do (always a good idea) a syntax check before we try to run it again:



        > perl -c hello
        hello syntax OK 



And now when we run it, we get "\n" still, but at least we know why.  Just
getting this script to compile has exposed the ’$varl’ (with the letter ’l’)
variable, and simply changing $varl to $var1 solves the problem.









Next: , Previous: perldebtut use strict, Up: perldebtut   [Contents]





14.4 Looking at data and -w and v



Ok, but how about when you want to really see your data, what’s in that
dynamic variable, just before using it?



        #!/usr/bin/perl 
        use strict;

        my $key = 'welcome';
        my %data = (
                'this' => qw(that), 
                'tom' => qw(and jerry),
                'welcome' => q(Hello World),
                'zip' => q(welcome),
        );
        my @data = keys %data;

        print "$data{$key}\n";
        exit;                               



Looks OK, after it’s been through the syntax check (perl -c scriptname), we
run it and all we get is a blank line again!  Hmmmm.



One common debugging approach here, would be to liberally sprinkle a few print
statements, to add a check just before we print out our data, and another just
after:



        print "All OK\n" if grep($key, keys %data);
        print "$data{$key}\n";
        print "done: '$data{$key}'\n";



And try again:



        > perl data
        All OK     

        done: ''



After much staring at the same piece of code and not seeing the wood for the
trees for some time, we get a cup of coffee and try another approach.  That
is, we bring in the cavalry by giving perl the ’-d’ switch on the command
line:



        > perl -d data 
        Default die handler restored.

        Loading DB routines from perl5db.pl version 1.07
        Editor support available.

        Enter h or `h h' for help, or `man perldebug' for more help.

        main::(./data:4):     my $key = 'welcome';   



Now, what we’ve done here is to launch the built-in perl debugger on our
script.  It’s stopped at the first line of executable code and is waiting for
input.



Before we go any further, you’ll want to know how to quit the debugger: use
just the letter ’q’, not the words ’quit’ or ’exit’:



        DB<1> q
        >



That’s it, you’re back on home turf again.









Next: , Previous: perldebtut Looking at data and -w and v, Up: perldebtut   [Contents]





14.5 help



Fire the debugger up again on your script and we’ll look at the help menu. 
There’s a couple of ways of calling help: a simple ’h’ will get the summary 
help list, ’|h’ (pipe-h) will pipe the help through your pager (which is 
(probably ’more’ or ’less’), and finally, ’h h’ (h-space-h) will give you 
the entire help screen.  Here is the summary page:



D1h



 List/search source lines:               Control script execution:
  l [ln|sub]  List source code            T           Stack trace
  - or .      List previous/current line  s [expr]    Single step [in expr]
  v [line]    View around line            n [expr]    Next, steps over subs
  f filename  View source in file         <CR/Enter>  Repeat last n or s
  /pattern/ ?patt?   Search forw/backw    r           Return from subroutine
  M           Show module versions        c [ln|sub]  Continue until position
 Debugger controls:                       L           List break/watch/actions
  o [...]     Set debugger options        t [expr]    Toggle trace [trace expr]
  <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
  ! [N|pat]   Redo a previous command     B ln|*      Delete a/all breakpoints
  H [-num]    Display last num commands   a [ln] cmd  Do cmd before line
  = [a val]   Define/list an alias        A ln|*      Delete a/all actions
  h [db_cmd]  Get help on command         w expr      Add a watch expression
  h h         Complete help page          W expr|*    Delete a/all watch exprs
  |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a subprocess
  q or ^D     Quit                        R           Attempt a restart
 Data Examination:     expr     Execute perl code, also see: s,n,t expr
  x|m expr       Evals expr in list context, dumps the result or lists methods.
  p expr         Print expression (uses script's current package).
  S [[!]pat]     List subroutine names [not] matching pattern
  V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or !pattern.
  X [Vars]       Same as "V current_package [Vars]".
  y [n [Vars]]   List lexicals in higher scope <n>.  Vars same as V.
 For more help, type h cmd_letter, or run man perldebug for all docs. 



More confusing options than you can shake a big stick at!  It’s not as bad as
it looks and it’s very useful to know more about all of it, and fun too!



There’s a couple of useful ones to know about straight away.  You wouldn’t
think we’re using any libraries at all at the moment, but ’M’ will show
which modules are currently loaded, and their version number, while ’m’ 
will show the methods, and ’S’ shows all subroutines (by pattern) as 
shown below.  ’V’ and ’X’ show variables in the program by package 
scope and can be constrained by pattern. 



        DB<2>S str 
        dumpvar::stringify
        strict::bits
        strict::import
        strict::unimport  



Using ’X’ and cousins requires you not to use the type identifiers ($@%), just
the ’name’:



        DM<3>X ~err
        FileHandle(stderr) => fileno(2)    



Remember we’re in our tiny program with a problem, we should have a look at
where we are, and what our data looks like. First of all let’s view some code 
at our present position (the first line of code in this case), via ’v’:



        DB<4> v
        1       #!/usr/bin/perl
        2:      use strict;
        3
        4==>    my $key = 'welcome';
        5:      my %data = (
        6               'this' => qw(that),
        7               'tom' => qw(and jerry),
        8               'welcome' => q(Hello World),
        9               'zip' => q(welcome),
        10      );                                 



At line number 4 is a helpful pointer, that tells you where you are now.  To
see more code, type ’v’ again:



        DB<4> v
        8               'welcome' => q(Hello World),
        9               'zip' => q(welcome),
        10      );
        11:     my @data = keys %data;
        12:     print "All OK\n" if grep($key, keys %data);
        13:     print "$data{$key}\n";
        14:     print "done: '$data{$key}'\n";
        15:     exit;      



And if you wanted to list line 5 again, type ’l 5’, (note the space):



        DB<4> l 5
        5:      my %data = (



In this case, there’s not much to see, but of course normally there’s pages of
stuff to wade through, and ’l’ can be very useful.  To reset your view to the
line we’re about to execute, type a lone period ’.’:



        DB<5> .
        main::(./data_a:4):     my $key = 'welcome';  



The line shown is the one that is about to be executed next, it hasn’t
happened yet.  So while we can print a variable with the letter ’p’, at
this point all we’d get is an empty (undefined) value back.  What we need to
do is to step through the next executable statement with an ’s’:



        DB<6> s
        main::(./data_a:5):     my %data = (
        main::(./data_a:6):             'this' => qw(that),
        main::(./data_a:7):             'tom' => qw(and jerry),
        main::(./data_a:8):             'welcome' => q(Hello World),
        main::(./data_a:9):             'zip' => q(welcome),
        main::(./data_a:10):    );   



Now we can have a look at that first ($key) variable:



        DB<7> p $key 
        welcome 



line 13 is where the action is, so let’s continue down to there via the letter
’c’, which by the way, inserts a ’one-time-only’ breakpoint at the given
line or sub routine:



        DB<8> c 13
        All OK
        main::(./data_a:13):    print "$data{$key}\n";



We’ve gone past our check (where ’All OK’ was printed) and have stopped just
before the meat of our task.  We could try to print out a couple of variables
to see what is happening:



        DB<9> p $data{$key}



Not much in there, lets have a look at our hash:



        DB<10> p %data
        Hello Worldziptomandwelcomejerrywelcomethisthat 

        DB<11> p keys %data
        Hello Worldtomwelcomejerrythis  



Well, this isn’t very easy to read, and using the helpful manual (h h), the
’x’ command looks promising:



        DB<12> x %data
        0  'Hello World'
        1  'zip'
        2  'tom'
        3  'and'
        4  'welcome'
        5  undef
        6  'jerry'
        7  'welcome'
        8  'this'
        9  'that'     



That’s not much help, a couple of welcomes in there, but no indication of
which are keys, and which are values, it’s just a listed array dump and, in
this case, not particularly helpful.  The trick here, is to use a reference
to the data structure:



        DB<13> x \%data
        0  HASH(0x8194bc4)
           'Hello World' => 'zip'
           'jerry' => 'welcome'
           'this' => 'that'
           'tom' => 'and'
           'welcome' => undef  



The reference is truly dumped and we can finally see what we’re dealing with. 
Our quoting was perfectly valid but wrong for our purposes, with ’and jerry’
being treated as 2 separate words rather than a phrase, thus throwing the
evenly paired hash structure out of alignment.



The ’-w’ switch would have told us about this, had we used it at the start,
and saved us a lot of trouble: 



        > perl -w data
        Odd number of elements in hash assignment at ./data line 5.    



We fix our quoting: ’tom’ => q(and jerry), and run it again, this time we get
our expected output:



        > perl -w data
        Hello World



While we’re here, take a closer look at the ’x’ command, it’s really useful
and will merrily dump out nested references, complete objects, partial objects
- just about whatever you throw at it:



Let’s make a quick object and x-plode it, first we’ll start the debugger:
it wants some form of input from STDIN, so we give it something non-committal,
a zero:



        > perl -de 0
        Default die handler restored.

        Loading DB routines from perl5db.pl version 1.07
        Editor support available.

        Enter h or `h h' for help, or `man perldebug' for more help.

        main::(-e:1):   0                       



Now build an on-the-fly object over a couple of lines (note the backslash):



        DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
        cont:   {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')



And let’s have a look at it:



        DB<2> x $obj
        0  MY_class=HASH(0x828ad98)
                'attr' => HASH(0x828ad68)
        'col' => 'black'
        'things' => ARRAY(0x828abb8)
                0  'this'
                1  'that'
                2  'etc'
                'unique_id' => 123       
        DB<3>



Useful, huh?  You can eval nearly anything in there, and experiment with bits
of code or regexes until the cows come home:



        DB<3> @data = qw(this that the other atheism leather theory scythe)

        DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
        atheism
        leather
        other
        scythe
        the
        theory  
        saw -> 6



If you want to see the command History, type an ’H’:



        DB<5> H
        4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
        3: @data = qw(this that the other atheism leather theory scythe)
        2: x $obj
        1: $obj = bless({'unique_id'=>'123', 'attr'=>
        {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
        DB<5>



And if you want to repeat any previous command, use the exclamation: ’!’:



        DB<5> !4
        p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
        atheism
        leather
        other
        scythe
        the
        theory  
        saw -> 12



For more on references see (perlref) and perlreftut NAME









Next: , Previous: perldebtut help, Up: perldebtut   [Contents]





14.6 Stepping through code



Here’s a simple program which converts between Celsius and Fahrenheit, it too
has a problem:



        #!/usr/bin/perl -w
        use strict;

        my $arg = $ARGV[0] || '-c20';

        if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
                my ($deg, $num) = ($1, $2);
                my ($in, $out) = ($num, $num);
                if ($deg eq 'c') {
                        $deg = 'f';
                        $out = &c2f($num);
                } else {
                        $deg = 'c';
                        $out = &f2c($num);
                }
                $out = sprintf('%0.2f', $out);
                $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
                print "$out $deg\n";
        } else {
                print "Usage: $0 -[c|f] num\n";
        }
        exit;

        sub f2c {
                my $f = shift;
                my $c = 5 * $f - 32 / 9;
                return $c;
        }

        sub c2f {
                my $c = shift;
                my $f = 9 * $c / 5 + 32;
                return $f;
        }



For some reason, the Fahrenheit to Celsius conversion fails to return the
expected output.  This is what it does:



        > temp -c0.72
        33.30 f

        > temp -f33.3
        162.94 c



Not very consistent!  We’ll set a breakpoint in the code manually and run it
under the debugger to see what’s going on.  A breakpoint is a flag, to which
the debugger will run without interruption, when it reaches the breakpoint, it
will stop execution and offer a prompt for further interaction.  In normal
use, these debugger commands are completely ignored, and they are safe - if a
little messy, to leave in production code.



        my ($in, $out) = ($num, $num);
        $DB::single=2; # insert at line 9!
        if ($deg eq 'c') 
                ...

        > perl -d temp -f33.3
        Default die handler restored.

        Loading DB routines from perl5db.pl version 1.07
        Editor support available.

        Enter h or `h h' for help, or `man perldebug' for more help.

        main::(temp:4): my $arg = $ARGV[0] || '-c100';     



We’ll simply continue down to our pre-set breakpoint with a ’c’:



        DB<1> c
        main::(temp:10):                if ($deg eq 'c') {   



Followed by a view command to see where we are:



        DB<1> v
        7:              my ($deg, $num) = ($1, $2);
        8:              my ($in, $out) = ($num, $num);
        9:              $DB::single=2;
        10==>           if ($deg eq 'c') {
        11:                     $deg = 'f';
        12:                     $out = &c2f($num);
        13              } else {
        14:                     $deg = 'c';
        15:                     $out = &f2c($num);
        16              }                             



And a print to show what values we’re currently using:



        DB<1> p $deg, $num
        f33.3



We can put another break point on any line beginning with a colon, we’ll use
line 17 as that’s just as we come out of the subroutine, and we’d like to
pause there later on:



        DB<2> b 17



There’s no feedback from this, but you can see what breakpoints are set by
using the list ’L’ command:



        DB<3> L
        temp:
                17:            print "$out $deg\n";
                break if (1)     



Note that to delete a breakpoint you use ’B’.



Now we’ll continue down into our subroutine, this time rather than by line
number, we’ll use the subroutine name, followed by the now familiar ’v’:



        DB<3> c f2c
        main::f2c(temp:30):             my $f = shift;  

        DB<4> v
        24:     exit;
        25
        26      sub f2c {
        27==>           my $f = shift;
        28:             my $c = 5 * $f - 32 / 9; 
        29:             return $c;
        30      }
        31
        32      sub c2f {
        33:             my $c = shift;   



Note that if there was a subroutine call between us and line 29, and we wanted
to single-step through it, we could use the ’s’ command, and to step
over it we would use ’n’ which would execute the sub, but not descend into
it for inspection.  In this case though, we simply continue down to line 29:



        DB<4> c 29  
        main::f2c(temp:29):             return $c;



And have a look at the return value:



        DB<5> p $c
        162.944444444444



This is not the right answer at all, but the sum looks correct.  I wonder if
it’s anything to do with operator precedence?  We’ll try a couple of other
possibilities with our sum:



        DB<6> p (5 * $f - 32 / 9)
        162.944444444444

        DB<7> p 5 * $f - (32 / 9) 
        162.944444444444

        DB<8> p (5 * $f) - 32 / 9
        162.944444444444

        DB<9> p 5 * ($f - 32) / 9
        0.722222222222221



:-) that’s more like it!  Ok, now we can set our return variable and we’ll
return out of the sub with an ’r’:



        DB<10> $c = 5 * ($f - 32) / 9

        DB<11> r
        scalar context return from main::f2c: 0.722222222222221



Looks good, let’s just continue off the end of the script:



        DB<12> c
        0.72 c 
        Debugged program terminated.  Use q to quit or R to restart,
        use O inhibit_exit to avoid stopping after program termination,
        h q, h R or h O to get additional info.   



A quick fix to the offending line (insert the missing parentheses) in the
actual program and we’re finished.









Next: , Previous: perldebtut Stepping through code, Up: perldebtut   [Contents]





14.7 Placeholder for a, w, t, T



Actions, watch variables, stack traces etc.: on the TODO list.



        a 

        w 

        t 

        T









Next: , Previous: perldebtut Placeholder for a, w, t, T, Up: perldebtut   [Contents]





14.8 REGULAR EXPRESSIONS



Ever wanted to know what a regex looked like?  You’ll need perl compiled with
the DEBUGGING flag for this one:



        > perl -Dr -e '/^pe(a)*rl$/i'
        Compiling REx `^pe(a)*rl$'
        size 17 first at 2
        rarest char
         at 0
           1: BOL(2)
           2: EXACTF <pe>(4)
           4: CURLYN[1] {0,32767}(14)
           6:   NOTHING(8)
           8:   EXACTF <a>(0)
          12:   WHILEM(0)
          13: NOTHING(14)
          14: EXACTF <rl>(16)
          16: EOL(17)
          17: END(0)
        floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
anchored(BOL) minlen 4
        Omitting $` $& $' support.

        EXECUTING...

        Freeing REx: `^pe(a)*rl$'  



Did you really want to know? :-)
For more gory details on getting regular expressions to work, have a look at
(perlre), perlretut NAME, and to decode the mysterious labels (BOL and CURLYN,
etc. above), see perldebguts NAME.









Next: , Previous: perldebtut REGULAR EXPRESSIONS, Up: perldebtut   [Contents]





14.9 OUTPUT TIPS



To get all the output from your error log, and not miss any messages via
helpful operating system buffering, insert a line like this, at the start of
your script:



        $|=1;   



To watch the tail of a dynamically growing logfile, (from the command line):



        tail -f $error_log



Wrapping all die calls in a handler routine can be useful to see how, and from
where, they’re being called, perlvar NAME has more information:



        BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }



Various useful techniques for the redirection of STDOUT and STDERR filehandles
are explained in perlopentut NAME and (perlfaq8).









Next: , Previous: perldebtut OUTPUT TIPS, Up: perldebtut   [Contents]





14.10 CGI



Just a quick hint here for all those CGI programmers who can’t figure out how
on earth to get past that ’waiting for input’ prompt, when running their CGI
script from the command-line, try something like this:



        > perl -d my_cgi.pl -nodebug 



Of course (CGI) and (perlfaq9) will tell you more.









Next: , Previous: perldebtut CGI, Up: perldebtut   [Contents]





14.11 GUIs



The command line interface is tightly integrated with an emacs extension
and there’s a vi interface too.  



You don’t have to do this all on the command line, though, there are a few GUI
options out there.  The nice thing about these is you can wave a mouse over a
variable and a dump of its data will appear in an appropriate window, or in a
popup balloon, no more tiresome typing of ’x $varname’ :-)



In particular have a hunt around for the following:



ptkdb perlTK based wrapper for the built-in debugger



ddd data display debugger



PerlDevKit and PerlBuilder are NT specific



NB. (more info on these and others would be appreciated).









Next: , Previous: perldebtut GUIs, Up: perldebtut   [Contents]





14.12 SUMMARY



We’ve seen how to encourage good coding practices with use strict and
-w.  We can run the perl debugger perl -d scriptname to inspect your
data from within the perl debugger with the p and x commands.  You can
walk through your code, set breakpoints with b and step through that code
with s or n, continue with c and return from a sub with r.  Fairly
intuitive stuff when you get down to it.  



There is of course lots more to find out about, this has just scratched the
surface.  The best way to learn more is to use perldoc to find out more about
the language, to read the on-line help ((perldebug) is probably the next
place to go), and of course, experiment.  









Next: , Previous: perldebtut SUMMARY, Up: perldebtut   [Contents]





14.13 SEE ALSO



(perldebug), 
perldebguts NAME, 
perldiag NAME,
perlrun NAME









Next: , Previous: perldebtut SEE ALSO, Up: perldebtut   [Contents]





14.14 AUTHOR



Richard Foley <richard.foley@rfi.net> Copyright (c) 2000









Previous: perldebtut AUTHOR, Up: perldebtut   [Contents]





14.15 CONTRIBUTORS



Various people have made helpful suggestions and contributions, in particular:



Ronald J Kimball <rjk@linguist.dartmouth.edu>



Hugo van der Sanden <hv@crypt0.demon.co.uk>



Peter Scott <Peter@PSDT.com>









Next: , Previous: perldebtut, Up: Top   [Contents]





15 NAME debug debugger





• NAME debug debugger NAME:  



• NAME debug debugger DESCRIPTION:  



• NAME debug debugger The Perl Debugger:  



• NAME debug debugger Debugging Regular Expressions:  



• NAME debug debugger Debugging Memory Usage:  



• NAME debug debugger SEE ALSO:  



• NAME debug debugger BUGS:  












Next: , Up: NAME debug debugger   [Contents]





15.1 NAME





perldebug - Perl debugging









Next: , Previous: NAME debug debugger NAME, Up: NAME debug debugger   [Contents]





15.2 DESCRIPTION



First of all, have you tried using the -w switch?



If you’re new to the Perl debugger, you may prefer to read
perldebtut NAME, which is a tutorial introduction to the debugger.









Next: , Previous: NAME debug debugger DESCRIPTION, Up: NAME debug debugger   [Contents]





15.3 The Perl Debugger




If you invoke Perl with the -d switch, your script runs under the
Perl source debugger.  This works like an interactive Perl
environment, prompting for debugger commands that let you examine
source code, set breakpoints, get stack backtraces, change the values of
variables, etc.  This is so convenient that you often fire up
the debugger all by itself just to test out Perl constructs
interactively to see what they do.  For example:




    $ perl -d -e 42



In Perl, the debugger is not a separate program the way it usually is in the
typical compiled environment.  Instead, the -d flag tells the compiler
to insert source information into the parse trees it’s about to hand off
to the interpreter.  That means your code must first compile correctly
for the debugger to work on it.  Then when the interpreter starts up, it
preloads a special Perl library file containing the debugger.



The program will halt right before the first run-time executable
statement (but see below regarding compile-time statements) and ask you
to enter a debugger command.  Contrary to popular expectations, whenever
the debugger halts and shows you a line of code, it always displays the
line it’s about to execute, rather than the one it has just executed.



Any command not recognized by the debugger is directly executed
(eval’d) as Perl code in the current package.  (The debugger
uses the DB package for keeping its own state information.)



Note that the said eval is bound by an implicit scope. As a
result any newly introduced lexical variable or any modified
capture buffer content is lost after the eval. The debugger is a
nice environment to learn Perl, but if you interactively experiment using
material which should be in the same scope, stuff it in one line.



For any text entered at the debugger prompt, leading and trailing whitespace
is first stripped before further processing.  If a debugger command
coincides with some function in your own program, merely precede the
function with something that doesn’t look like a debugger command, such
as a leading ; or perhaps a +, or by wrapping it with parentheses
or braces.





• NAME debug debugger Calling the Debugger:  



• NAME debug debugger Debugger Commands:  



• NAME debug debugger Configurable Options:  



• NAME debug debugger Debugger Input/Output:  



• NAME debug debugger Debugging Compile-Time Statements:  



• NAME debug debugger Debugger Customization:  



• NAME debug debugger Readline Support / History in the Debugger:  



• NAME debug debugger Editor Support for Debugging:  



• NAME debug debugger The Perl Profiler:  












Next: , Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.1 Calling the Debugger



There are several ways to call the debugger:





perl -d program_name




On the given program identified by program_name.





perl -d -e 0




Interactively supply an arbitrary expression using -e.





perl -d:Ptkdb program_name




Debug a given program via the Devel::Ptkdb GUI.





perl -dt threaded_program_name




Debug a given program using threads (experimental).














Next: , Previous: NAME debug debugger Calling the Debugger, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.2 Debugger Commands



The interactive debugger understands the following commands:





h





Prints out a summary help message





h [command]




Prints out a help message for the given debugger command.





h h




The special argument of h h produces the entire help page, which is quite long.



If the output of the h h command (or any command, for that matter) scrolls
past your screen, precede the command with a leading pipe symbol so
that it’s run through your pager, as in



    DB> |h h



You may change the pager which is used via o pager=... command.





p expr





Same as print {$DB::OUT} expr in the current package.  In particular,
because this is just Perl’s own print function, this means that nested
data structures and objects are not dumped, unlike with the x command.



The DB::OUT filehandle is opened to /dev/tty, regardless of
where STDOUT may be redirected to.





x [maxdepth] expr





Evaluates its expression in list context and dumps out the result in a
pretty-printed fashion.  Nested data structures are printed out
recursively, unlike the real print function in Perl.  When dumping
hashes, you’ll probably prefer ’x \%h’ rather than ’x %h’.
See (Dumpvalue) if you’d like to do this yourself.



The output format is governed by multiple options described under
Configurable Options.



If the maxdepth is included, it must be a numeral N; the value is
dumped only N levels deep, as if the dumpDepth option had been
temporarily set to N.





V [pkg [vars]]





Display all (or some) variables in package (defaulting to main)
using a data pretty-printer (hashes show their keys and values so
you see what’s what, control characters are made printable, etc.).
Make sure you don’t put the type specifier (like $) there, just
the symbol names, like this:



    V DB filename line



Use ~pattern and !pattern for positive and negative regexes.



This is similar to calling the x command on each applicable var.





X [vars]





Same as V currentpackage [vars].





y [level [vars]]





Display all (or some) lexical variables (mnemonic: mY variables)
in the current scope or level scopes higher.  You can limit the
variables that you see with vars which works exactly as it does
for the V and X commands.  Requires the PadWalker module
version 0.08 or higher; will warn if this isn’t installed.  Output
is pretty-printed in the same style as for V and the format is
controlled by the same options.





T







Produce a stack backtrace.  See below for details on its output.





s [expr]






Single step.  Executes until the beginning of another
statement, descending into subroutine calls.  If an expression is
supplied that includes function calls, it too will be single-stepped.





n [expr]





Next.  Executes over subroutine calls, until the beginning
of the next statement.  If an expression is supplied that includes
function calls, those functions will be executed with stops before
each statement.





r





Continue until the return from the current subroutine.
Dump the return value if the PrintRet option is set (default).





<CR>




Repeat last n or s command.





c [line|sub]





Continue, optionally inserting a one-time-only breakpoint
at the specified line or subroutine.





l





List next window of lines.





l min+incr




List incr+1 lines starting at min.





l min-max




List lines min through max.  l - is synonymous to -.





l line




List a single line.





l subname




List first window of lines from subroutine.  subname may
be a variable that contains a code reference.





-





List previous window of lines.





v [line]





View a few lines of code around the current line.





.





Return the internal debugger pointer to the line last
executed, and print out that line.





f filename





Switch to viewing a different file or eval statement.  If filename
is not a full pathname found in the values of %INC, it is considered
a regex.



evaled strings (when accessible) are considered to be filenames:
f (eval 7) and f eval 7\b access the body of the 7th evaled string
(in the order of execution).  The bodies of the currently executed eval
and of evaled strings that define subroutines are saved and thus
accessible.





/pattern/




Search forwards for pattern (a Perl regex); final / is optional.
The search is case-insensitive by default.





?pattern?




Search backwards for pattern; final ? is optional.
The search is case-insensitive by default.





L [abw]





List (default all) actions, breakpoints and watch expressions





S [[!]regex]





List subroutine names [not] matching the regex.





t [n]





Toggle trace mode (see also the AutoTrace option).
Optional argument is the maximum number of levels to trace below
the current one; anything deeper than that will be silent.





t [n] expr





Trace through execution of expr.
Optional first argument is the maximum number of levels to trace below
the current one; anything deeper than that will be silent.
See perldebguts Frame Listing Output Examples for examples.





b






Sets breakpoint on current line





b [line] [condition]






Set a breakpoint before the given line.  If a condition
is specified, it’s evaluated each time the statement is reached: a
breakpoint is taken only if the condition is true.  Breakpoints may
only be set on lines that begin an executable statement.  Conditions
don’t use if:



    b 237 $x > 30
    b 237 ++$count237 < 11
    b 33 /pattern/i



If the line number is ., sets a breakpoint on the current line:



    b . $n > 100





b [file]:[line] [condition]






Set a breakpoint before the given line in a (possibly different) file.  If a
condition is specified, it’s evaluated each time the statement is reached: a
breakpoint is taken only if the condition is true.  Breakpoints may only be set
on lines that begin an executable statement.  Conditions don’t use if:



    b lib/MyModule.pm:237 $x > 30
    b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11





b subname [condition]






Set a breakpoint before the first line of the named subroutine.  subname may
be a variable containing a code reference (in this case condition
is not supported).





b postpone subname [condition]






Set a breakpoint at first line of subroutine after it is compiled.





b load filename






Set a breakpoint before the first executed line of the filename,
which should be a full pathname found amongst the %INC values.





b compile subname






Sets a breakpoint before the first statement executed after the specified
subroutine is compiled.





B line






Delete a breakpoint from the specified line.





B *






Delete all installed breakpoints.





disable [file]:[line]







Disable the breakpoint so it won’t stop the execution of the program. 
Breakpoints are enabled by default and can be re-enabled using the enable
command.





disable [line]







Disable the breakpoint so it won’t stop the execution of the program. 
Breakpoints are enabled by default and can be re-enabled using the enable
command.



This is done for a breakpoint in the current file.





enable [file]:[line]







Enable the breakpoint so it will stop the execution of the program. 





enable [line]







Enable the breakpoint so it will stop the execution of the program. 



This is done for a breakpoint in the current file.





a [line] command





Set an action to be done before the line is executed.  If line is
omitted, set an action on the line about to be executed.
The sequence of steps taken by the debugger is



  1. check for a breakpoint at this line
  2. print the line if necessary (tracing)
  3. do any actions associated with that line
  4. prompt user if at a breakpoint or in single-step
  5. evaluate line



For example, this will print out $foo every time line
53 is passed:



    a 53 print "DB FOUND $foo\n"





A line





Delete an action from the specified line.





A *





Delete all installed actions.





w expr





Add a global watch-expression. Whenever a watched global changes the
debugger will stop and display the old and new values.





W expr





Delete watch-expression





W *





Delete all watch-expressions.





o





Display all options.





o booloption ...





Set each listed Boolean option to the value 1.





o anyoption? ...





Print out the value of one or more options.





o option=value ...





Set the value of one or more options.  If the value has internal
whitespace, it should be quoted.  For example, you could set o
pager="less -MQeicsNfr" to call less with those specific options.
You may use either single or double quotes, but if you do, you must
escape any embedded instances of same sort of quote you began with,
as well as any escaping any escapes that immediately precede that
quote but which are not meant to escape the quote itself.  In other
words, you follow single-quoting rules irrespective of the quote;
eg: o option='this isn\'t bad' or o option="She said, \"Isn't
it?\"".



For historical reasons, the =value is optional, but defaults to
1 only where it is safe to do so–that is, mostly for Boolean
options.  It is always better to assign a specific value using =.
The option can be abbreviated, but for clarity probably should
not be.  Several options can be set together.  See Configurable Options
for a list of these.





< ?





List out all pre-prompt Perl command actions.





< [ command ]





Set an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backslashing the newlines.





< *





Delete all pre-prompt Perl command actions.





<< command





Add an action (Perl command) to happen before every debugger prompt.
A multi-line command may be entered by backwhacking the newlines.





> ?





List out post-prompt Perl command actions.





> command





Set an action (Perl command) to happen after the prompt when you’ve
just given a command to return to executing the script.  A multi-line
command may be entered by backslashing the newlines (we bet you
couldn’t have guessed this by now).





> *





Delete all post-prompt Perl command actions.





>> command





Adds an action (Perl command) to happen after the prompt when you’ve
just given a command to return to executing the script.  A multi-line
command may be entered by backslashing the newlines.





{ ?





List out pre-prompt debugger commands.





{ [ command ]




Set an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered in the customary fashion.



Because this command is in some senses new, a warning is issued if
you appear to have accidentally entered a block instead.  If that’s
what you mean to do, write it as with ;{ ... } or even
do { ... }.





{ *





Delete all pre-prompt debugger commands.





{{ command





Add an action (debugger command) to happen before every debugger prompt.
A multi-line command may be entered, if you can guess how: see above.





! number





Redo a previous command (defaults to the previous command).





! -number





Redo number’th previous command.





! pattern





Redo last command that started with pattern.
See o recallCommand, too.





!! cmd





Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
o shellBang, also.  Note that the user’s current shell (well,
their $ENV{SHELL} variable) will be used, which can interfere
with proper interpretation of exit status or signal and coredump
information.





source file





Read and execute debugger commands from file.
file may itself contain source commands.





H -number





Display last n commands.  Only commands longer than one character are
listed.  If number is omitted, list them all.





q or ^D






Quit.  ("quit" doesn’t work for this, unless you’ve made an alias)
This is the only supported way to exit the debugger, though typing
exit twice might work.



Set the inhibit_exit option to 0 if you want to be able to step
off the end the script.  You may also need to set $finished to 0
if you want to step through global destruction.





R





Restart the debugger by exec()ing a new session.  We try to maintain
your history across this, but internal settings and command-line options
may be lost.



The following setting are currently preserved: history, breakpoints,
actions, debugger options, and the Perl command-line
options -w, -I, and -e.





|dbcmd





Run the debugger command, piping DB::OUT into your current pager.





||dbcmd





Same as |dbcmd but DB::OUT is temporarily selected as well.





= [alias value]





Define a command alias, like



    = quit q



or list current aliases.





command




Execute command as a Perl statement.  A trailing semicolon will be
supplied.  If the Perl statement would otherwise be confused for a
Perl debugger, use a leading semicolon, too.





m expr





List which methods may be called on the result of the evaluated
expression.  The expression may evaluated to a reference to a
blessed object, or to a package name.





M





Display all loaded modules and their versions.





man [manpage]





Despite its name, this calls your system’s default documentation
viewer on the given page, or on the viewer itself if manpage is
omitted.  If that viewer is man, the current Config information
is used to invoke man using the proper MANPATH or -M manpath option.  Failed lookups of the form XXX that match
known manpages of the form perlXXX will be retried.  This lets
you type man debug or man op from the debugger.



On systems traditionally bereft of a usable man command, the
debugger invokes perldoc.  Occasionally this determination is
incorrect due to recalcitrant vendors or rather more felicitously,
to enterprising users.  If you fall into either category, just
manually set the $DB::doccmd variable to whatever viewer to view
the Perl documentation on your system.  This may be set in an rc
file, or through direct assignment.  We’re still waiting for a
working example of something along the lines of:



    $DB::doccmd = 'netscape -remote http://something.here/';














Next: , Previous: NAME debug debugger Debugger Commands, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.3 Configurable Options



The debugger has numerous options settable using the o command,
either interactively or from the environment or an rc file.
(./.perldb or ~/.perldb under Unix.)





recallCommand, ShellBang






The characters used to recall command or spawn shell.  By
default, both are set to !, which is unfortunate.





pager





Program to use for output of pager-piped commands (those beginning
with a | character.)  By default, $ENV{PAGER} will be used.
Because the debugger uses your current terminal characteristics
for bold and underlining, if the chosen pager does not pass escape
sequences through unchanged, the output of some debugger commands
will not be readable when sent through the pager.





tkRunning





Run Tk while prompting (with ReadLine).





signalLevel, warnLevel, dieLevel







Level of verbosity.  By default, the debugger leaves your exceptions
and warnings alone, because altering them can break correctly running
programs.  It will attempt to print a message when uncaught INT, BUS, or
SEGV signals arrive.  (But see the mention of signals in BUGS below.)



To disable this default safe mode, set these values to something higher
than 0.  At a level of 1, you get backtraces upon receiving any kind
of warning (this is often annoying) or exception (this is
often valuable).  Unfortunately, the debugger cannot discern fatal
exceptions from non-fatal ones.  If dieLevel is even 1, then your
non-fatal exceptions are also traced and unceremoniously altered if they
came from eval'ed strings or from any kind of eval within modules
you’re attempting to load.  If dieLevel is 2, the debugger doesn’t
care where they came from:  It usurps your exception handler and prints
out a trace, then modifies all exceptions with its own embellishments.
This may perhaps be useful for some tracing purposes, but tends to hopelessly
destroy any program that takes its exception handling seriously.





AutoTrace





Trace mode (similar to t command, but can be put into
PERLDB_OPTS).





LineInfo





File or pipe to print line number info to.  If it is a pipe (say,
|visual_perl_db), then a short message is used.  This is the
mechanism used to interact with a slave editor or visual debugger,
such as the special vi or emacs hooks, or the ddd graphical
debugger.





inhibit_exit





If 0, allows stepping off the end of the script.





PrintRet





Print return value after r command if set (default).





ornaments





Affects screen appearance of the command line (see (Term-ReadLine)).
There is currently no way to disable these, which can render
some output illegible on some displays, or with some pagers.
This is considered a bug.





frame





Affects the printing of messages upon entry and exit from subroutines.  If
frame & 2 is false, messages are printed on entry only. (Printing
on exit might be useful if interspersed with other messages.)



If frame & 4, arguments to functions are printed, plus context
and caller info.  If frame & 8, overloaded stringify and
tied FETCH is enabled on the printed arguments.  If frame
& 16, the return value from the subroutine is printed.



The length at which the argument list is truncated is governed by the
next option:





maxTraceLen





Length to truncate the argument list when the frame option’s
bit 4 is set.





windowSize





Change the size of code list window (default is 10 lines).








The following options affect what happens with V, X, and x
commands:





arrayDepth, hashDepth






Print only first N elements (” for all).





dumpDepth





Limit recursion depth to N levels when dumping structures.
Negative values are interpreted as infinity.  Default: infinity.





compactDump, veryCompact






Change the style of array and hash output.  If compactDump, short array
may be printed on one line.





globPrint





Whether to print contents of globs.





DumpDBFiles





Dump arrays holding debugged files.





DumpPackages





Dump symbol tables of packages.





DumpReused





Dump contents of "reused" addresses.





quote, HighBit, undefPrint







Change the style of string dump.  The default value for quote
is auto; one can enable double-quotish or single-quotish format
by setting it to " or ', respectively.  By default, characters
with their high bit set are printed verbatim.





UsageOnly





Rudimentary per-package memory usage dump.  Calculates total
size of strings found in variables in the package.  This does not
include lexicals in a module’s file scope, or lost in closures.








After the rc file is read, the debugger reads the $ENV{PERLDB_OPTS}
environment variable and parses this as the remainder of a "O ..."
line as one might enter at the debugger prompt.  You may place the
initialization options TTY, noTTY, ReadLine, and NonStop
there.



If your rc file contains:



  parse_options("NonStop=1 LineInfo=db.out AutoTrace");



then your script will run without human intervention, putting trace
information into the file db.out.  (If you interrupt it, you’d
better reset LineInfo to /dev/tty if you expect to see anything.)





TTY





The TTY to use for debugging I/O.





noTTY





If set, the debugger goes into NonStop mode and will not connect to a TTY.  If
interrupted (or if control goes to the debugger via explicit setting of
$DB::signal or $DB::single from the Perl script), it connects to a TTY
specified in the TTY option at startup, or to a tty found at
runtime using the Term::Rendezvous module of your choice.



This module should implement a method named new that returns an object
with two methods: IN and OUT.  These should return filehandles to use
for debugging input and output correspondingly.  The new method should
inspect an argument containing the value of $ENV{PERLDB_NOTTY} at
startup, or "$ENV{HOME}/.perldbtty$$" otherwise.  This file is not
inspected for proper ownership, so security hazards are theoretically
possible.





ReadLine





If false, readline support in the debugger is disabled in order
to debug applications that themselves use ReadLine.





NonStop





If set, the debugger goes into non-interactive mode until interrupted, or
programmatically by setting $DB::signal or $DB::single.








Here’s an example of using the $ENV{PERLDB_OPTS} variable:



    $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram



That will run the script myprogram without human intervention,
printing out the call tree with entry and exit points.  Note that
NonStop=1 frame=2 is equivalent to N f=2, and that originally,
options could be uniquely abbreviated by the first letter (modulo
the Dump* options).  It is nevertheless recommended that you
always spell them out in full for legibility and future compatibility.



Other examples include



    $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram



which runs script non-interactively, printing info on each entry
into a subroutine and each executed line into the file named listing.
(If you interrupt it, you would better reset LineInfo to something
"interactive"!)



Other examples include (using standard shell syntax to show environment
variable settings):



  $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
      perl -d myprogram )



which may be useful for debugging a program that uses Term::ReadLine
itself.  Do not forget to detach your shell from the TTY in the window that
corresponds to /dev/ttyXX, say, by issuing a command like



  $ sleep 1000000



See perldebguts Debugger Internals for details.









Next: , Previous: NAME debug debugger Configurable Options, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.4 Debugger Input/Output





Prompt




The debugger prompt is something like



    DB<8>



or even



    DB<<17>>



where that number is the command number, and which you’d use to
access with the built-in csh-like history mechanism.  For example,
!17 would repeat command number 17.  The depth of the angle
brackets indicates the nesting depth of the debugger.  You could
get more than one set of brackets, for example, if you’d already
at a breakpoint and then printed the result of a function call that
itself has a breakpoint, or you step into an expression via s/n/t
expression command.





Multiline commands




If you want to enter a multi-line command, such as a subroutine
definition with several statements or a format, escape the newline
that would normally end the debugger command with a backslash.
Here’s an example:



      DB<1> for (1..4) {         \
      cont:     print "ok\n";   \
      cont: }
      ok
      ok
      ok
      ok



Note that this business of escaping a newline is specific to interactive
commands typed into the debugger.





Stack backtrace






Here’s an example of what a stack backtrace via T command might
look like:



    $ = main::infested called from file 'Ambulation.pm' line 10
    @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea' line 7
    $ = main::pests('bactrian', 4) called from file 'camel_flea' line 4



The left-hand character up there indicates the context in which the
function was called, with $ and @ meaning scalar or list
contexts respectively, and . meaning void context (which is
actually a sort of scalar context).  The display above says
that you were in the function main::infested when you ran the
stack dump, and that it was called in scalar context from line
10 of the file Ambulation.pm, but without any arguments at all,
meaning it was called as &infested.  The next stack frame shows
that the function Ambulation::legs was called in list context
from the camel_flea file with four arguments.  The last stack
frame shows that main::pests was called in scalar context,
also from camel_flea, but from line 4.



If you execute the T command from inside an active use
statement, the backtrace will contain both a require frame and
an eval frame.





Line Listing Format




This shows the sorts of output the l command can produce:



    DB<<13>> l
  101:                @i{@i} = ();
  102:b               @isa{@i,$pack} = ()
  103                     if(exists $i{$prevpack} || exists $isa{$pack});
  104             }
  105
  106             next
  107==>              if(exists $isa{$pack});
  108
  109:a           if ($extra-- > 0) {
  110:                %isa = ($pack,1);



Breakable lines are marked with :.  Lines with breakpoints are
marked by b and those with actions by a.  The line that’s
about to be executed is marked by ==>.



Please be aware that code in debugger listings may not look the same
as your original source code.  Line directives and external source
filters can alter the code before Perl sees it, causing code to move
from its original positions or take on entirely different forms.





Frame listing




When the frame option is set, the debugger would print entered (and
optionally exited) subroutines in different styles.  See perldebguts NAME
for incredibly long examples of these.














Next: , Previous: NAME debug debugger Debugger Input/Output, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.5 Debugging Compile-Time Statements



If you have compile-time executable statements (such as code within
BEGIN, UNITCHECK and CHECK blocks or use statements), these will
not be stopped by debugger, although requires and INIT blocks
will, and compile-time statements can be traced with the AutoTrace
option set in PERLDB_OPTS).  From your own Perl code, however, you
can transfer control back to the debugger using the following
statement, which is harmless if the debugger is not running:



    $DB::single = 1;



If you set $DB::single to 2, it’s equivalent to having
just typed the n command, whereas a value of 1 means the s
command.  The $DB::trace  variable should be set to 1 to simulate
having typed the t command.



Another way to debug compile-time code is to start the debugger, set a
breakpoint on the load of some module:



    DB<7> b load f:/perllib/lib/Carp.pm
  Will stop on load of 'f:/perllib/lib/Carp.pm'.



and then restart the debugger using the R command (if possible).  One can use b
compile subname for the same purpose.









Next: , Previous: NAME debug debugger Debugging Compile-Time Statements, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.6 Debugger Customization



The debugger probably contains enough configuration hooks that you
won’t ever have to modify it yourself.  You may change the behaviour
of the debugger from within the debugger using its o command, from
the command line via the PERLDB_OPTS environment variable, and
from customization files.



You can do some customization by setting up a .perldb file, which
contains initialization code.  For instance, you could make aliases
like these (the last one is one people expect to be there):



    $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
    $DB::alias{'stop'} = 's/^stop (at|in)/b/';
    $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
    $DB::alias{'quit'} = 's/^quit(\s*)/exit/';



You can change options from .perldb by using calls like this one;



    parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");



The code is executed in the package DB.  Note that .perldb is
processed before processing PERLDB_OPTS.  If .perldb defines the
subroutine afterinit, that function is called after debugger
initialization ends.  .perldb may be contained in the current
directory, or in the home directory.  Because this file is sourced
in by Perl and may contain arbitrary commands, for security reasons,
it must be owned by the superuser or the current user, and writable
by no one but its owner.



You can mock TTY input to debugger by adding arbitrary commands to
@DB::typeahead. For example, your .perldb file might contain:



    sub afterinit { push @DB::typeahead, "b 4", "b 6"; }



Which would attempt to set breakpoints on lines 4 and 6 immediately
after debugger initialization. Note that @DB::typeahead is not a supported
interface and is subject to change in future releases.



If you want to modify the debugger, copy perl5db.pl from the
Perl library to another name and hack it to your heart’s content.
You’ll then want to set your PERL5DB environment variable to say
something like this:



    BEGIN { require "myperl5db.pl" }



As a last resort, you could also use PERL5DB to customize the debugger
by directly setting internal variables or calling debugger functions.



Note that any variables and functions that are not documented in
this document (or in perldebguts NAME) are considered for internal
use only, and as such are subject to change without notice.









Next: , Previous: NAME debug debugger Debugger Customization, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.7 Readline Support / History in the Debugger



As shipped, the only command-line history supplied is a simplistic one
that checks for leading exclamation points.  However, if you install
the Term::ReadKey and Term::ReadLine modules from CPAN (such as
Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
have full editing capabilities much like those GNU readline(3) provides.
Look for these in the modules/by-module/Term directory on CPAN.
These do not support normal vi command-line editing, however.



A rudimentary command-line completion is also available, including
lexical variables in the current scope if the PadWalker module
is installed.



Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.









Next: , Previous: NAME debug debugger Readline Support / History in the Debugger, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.8 Editor Support for Debugging



If you have the FSF’s version of emacs installed on your system,
it can interact with the Perl debugger to provide an integrated
software development environment reminiscent of its interactions
with C debuggers.



Recent versions of Emacs come with a
start file for making emacs act like a
syntax-directed editor that understands (some of) Perl’s syntax.
See (perlfaq3).



A similar setup by Tom Christiansen for interacting with any
vendor-shipped vi and the X11 window system is also available.
This works similarly to the integrated multiwindow support that
emacs provides, where the debugger drives the editor.  At the
time of this writing, however, that tool’s eventual location in the
Perl distribution was uncertain.



Users of vi should also look into vim and gvim, the mousey
and windy version, for coloring of Perl keywords.



Note that only perl can truly parse Perl, so all such CASE tools
fall somewhat short of the mark, especially if you don’t program
your Perl as a C programmer might.









Previous: NAME debug debugger Editor Support for Debugging, Up: NAME debug debugger The Perl Debugger   [Contents]





15.3.9 The Perl Profiler






If you wish to supply an alternative debugger for Perl to run,
invoke your script with a colon and a package argument given to the
-d flag.  Perl’s alternative debuggers include a Perl profiler,
(Devel-NYTProf), which is available separately as a CPAN
distribution.  To profile your Perl program in the file mycode.pl,
just type:



    $ perl -d:NYTProf mycode.pl



When the script terminates the profiler will create a database of the
profile information that you can turn into reports using the profiler’s
tools. See <perlperf> for details.









Next: , Previous: NAME debug debugger The Perl Debugger, Up: NAME debug debugger   [Contents]





15.4 Debugging Regular Expressions






use re 'debug' enables you to see the gory details of how the Perl
regular expression engine works. In order to understand this typically
voluminous output, one must not only have some idea about how regular
expression matching works in general, but also know how Perl’s regular
expressions are internally compiled into an automaton. These matters
are explored in some detail in
perldebguts Debugging Regular Expressions.









Next: , Previous: NAME debug debugger Debugging Regular Expressions, Up: NAME debug debugger   [Contents]





15.5 Debugging Memory Usage




Perl contains internal support for reporting its own memory usage,
but this is a fairly advanced concept that requires some understanding
of how memory allocation works.
See perldebguts Debugging Perl Memory Usage for the details.









Next: , Previous: NAME debug debugger Debugging Memory Usage, Up: NAME debug debugger   [Contents]





15.6 SEE ALSO



You did try the -w switch, didn’t you?



perldebtut NAME,
perldebguts NAME,
(re),
(DB),
(Devel-NYTProf),
(Dumpvalue),
and
perlrun NAME.



When debugging a script that uses #! and is thus normally found in
$PATH, the -S option causes perl to search $PATH for it, so you don’t
have to type the path or which $scriptname.



  $ perl -Sd foo.pl









Previous: NAME debug debugger SEE ALSO, Up: NAME debug debugger   [Contents]





15.7 BUGS



You cannot get stack frame information or in any fashion debug functions
that were not compiled by Perl, such as those from C or C++ extensions.



If you alter your @_ arguments in a subroutine (such as with shift
or pop), the stack backtrace will not show the original values.



The debugger does not currently work in conjunction with the -W
command-line switch, because it itself is not free of warnings.



If you’re in a slow syscall (like waiting, accepting, or reading
from your keyboard or a socket) and haven’t set up your own $SIG{INT}
handler, then you won’t be able to CTRL-C your way back to the debugger,
because the debugger’s own $SIG{INT} handler doesn’t understand that
it needs to raise an exception to longjmp(3) out of slow syscalls.









Next: , Previous: NAME debug debugger, Up: Top   [Contents]





16 perldiag





• perldiag NAME:  



• perldiag DESCRIPTION:  



• perldiag SEE ALSO:  












Next: , Up: perldiag   [Contents]





16.1 NAME



perldiag - various Perl diagnostics









Next: , Previous: perldiag NAME, Up: perldiag   [Contents]





16.2 DESCRIPTION



These messages are classified as follows (listed in increasing order of
desperation):



    (W) A warning (optional).
    (D) A deprecation (enabled by default).
    (S) A severe warning (enabled by default).
    (F) A fatal error (trappable).
    (P) An internal error you should never see (trappable).
    (X) A very fatal error (nontrappable).
    (A) An alien error message (not generated by Perl).



The majority of messages from the first three classifications above
(W, D & S) can be controlled using the warnings pragma.



If a message can be controlled by the warnings pragma, its warning
category is included with the classification letter in the description
below.



Optional warnings are enabled by using the warnings pragma or the -w
and -W switches.  Warnings may be captured by setting $SIG{__WARN__}
to a reference to a routine that will be called on each warning instead
of printing it.  See perlvar NAME.



Severe warnings are always enabled, unless they are explicitly disabled
with the warnings pragma or the -X switch.



Trappable errors may be trapped using the eval operator.  See
(perlfunc)eval.  In almost all cases, warnings may be selectively
disabled or promoted to fatal errors using the warnings pragma.
See (warnings).



The messages are in alphabetical order, without regard to upper or
lower-case.  Some of these messages are generic.  Spots that vary are
denoted with a %s or other printf-style escape.  These escapes are
ignored by the alphabetical order, as are all characters other than
letters.  To look up your message, just ignore anything that is not a
letter.





accept() on closed socket %s




(W closed) You tried to do an accept on a closed socket.  Did you forget
to check the return value of your socket() call?  See
(perlfunc)accept.





Allocation too large: %x




(X) You can’t allocate more than 64K on an MS-DOS machine.





’%c’ allowed only after types %s




(F) The modifiers ’!’, ’<’ and ’>’ are allowed in pack() or unpack() only
after certain types.  See (perlfunc)pack.





Ambiguous call resolved as CORE::%s(), qualify as such or use &




(W ambiguous) A subroutine you have declared has the same name as a Perl
keyword, and you have used the name without qualification for calling
one or the other.  Perl decided to call the builtin because the
subroutine is not imported.



To force interpretation as a subroutine call, either put an ampersand
before the subroutine name, or qualify the name with its package.
Alternatively, you can import the subroutine (or pretend that it’s
imported with the use subs pragma).



To silently interpret it as the Perl operator, use the CORE:: prefix
on the operator (e.g. CORE::log($x)) or declare the subroutine
to be an object method (see (perlsub)Subroutine Attributes or
(attributes)).





Ambiguous range in transliteration operator




(F) You wrote something like tr/a-z-0// which doesn’t mean anything at
all.  To include a - character in a transliteration, put it either
first or last.  (In the past, tr/a-z-0// was synonymous with
tr/a-y//, which was probably not what you would have expected.)





Ambiguous use of %s resolved as %s




(W ambiguous)(S) You said something that may not be interpreted the way
you thought.  Normally it’s pretty easy to disambiguate it by supplying
a missing quote, operator, parenthesis pair or declaration.





Ambiguous use of %c resolved as operator %c




(W ambiguous) %, &, and * are both infix operators (modulus,
bitwise and, and multiplication) and initial special characters
(denoting hashes, subroutines and typeglobs), and you said something
like *foo * foo that might be interpreted as either of them.  We
assumed you meant the infix operator, but please try to make it more
clear – in the example given, you might write *foo * foo() if you
really meant to multiply a glob by the result of calling a function.





Ambiguous use of %c{%s} resolved to %c%s




(W ambiguous) You wrote something like @{foo}, which might be
asking for the variable @foo, or it might be calling a function
named foo, and dereferencing it as an array reference.  If you wanted
the variable, you can just write @foo.  If you wanted to call the
function, write @{foo()} ... or you could just not have a variable
and a function with the same name, and save yourself a lot of trouble.





Ambiguous use of %c{%s[...]} resolved to %c%s[...]






Ambiguous use of %c{%s{...}} resolved to %c%s{...}




(W ambiguous) You wrote something like ${foo[2]} (where foo represents
the name of a Perl keyword), which might be looking for element number
2 of the array named @foo, in which case please write $foo[2], or you
might have meant to pass an anonymous arrayref to the function named
foo, and then do a scalar deref on the value it returns.  If you meant
that, write ${foo([2])}.



In regular expressions, the ${foo[2]} syntax is sometimes necessary
to disambiguate between array subscripts and character classes.
/$length[2345]/, for instance, will be interpreted as $length followed
by the character class [2345].  If an array subscript is what you
want, you can avoid the warning by changing /${length[2345]}/ to the
unsightly /${\$length[2345]}/, by renaming your array to something
that does not coincide with a built-in keyword, or by simply turning
off warnings with no warnings 'ambiguous';.





Ambiguous use of -%s resolved as -&%s()




(W ambiguous) You wrote something like -foo, which might be the
string "-foo", or a call to the function foo, negated.  If you meant
the string, just write "-foo".  If you meant the function call,
write -foo().





Ambiguous use of ’s//le...’ resolved as ’s// le...’; Rewrite as ’s//el’ if you meant ’use locale rules and evaluate rhs as an expression’.  In Perl 5.18, it will be resolved the other way




(W deprecated, ambiguous) You wrote a pattern match with substitution
immediately followed by "le".  In Perl 5.16 and earlier, this is
resolved as meaning to take the result of the substitution, and see if
it is stringwise less-than-or-equal-to what follows in the expression.
Having the "le" immediately following a pattern is deprecated behavior,
so in Perl 5.18, this expression will be resolved as meaning to do the
pattern match using the rules of the current locale, and evaluate the
rhs as an expression when doing the substitution.  In 5.14, and 5.16 if
you want the latter interpretation, you can simply write "el" instead.
But note that the /l modifier should not be used explicitly anyway;
you should use use locale instead.  See perllocale NAME.





’|’ and ’<’ may not both be specified on command line




(F) An error peculiar to VMS.  Perl does its own command line
redirection, and found that STDIN was a pipe, and that you also tried to
redirect STDIN using ’<’.  Only one STDIN stream to a customer, please.





’|’ and ’>’ may not both be specified on command line




(F) An error peculiar to VMS.  Perl does its own command line
redirection, and thinks you tried to redirect stdout both to a file and
into a pipe to another command.  You need to choose one or the other,
though nothing’s stopping you from piping into a program or Perl script
which ’splits’ output into two streams, such as



    open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!";
    while (<STDIN>) {
        print;
        print OUT;
    }
    close OUT;





Applying %s to %s will act on scalar(%s)




(W misc) The pattern match (//), substitution (s///), and
transliteration (tr///) operators work on scalar values.  If you apply
one of them to an array or a hash, it will convert the array or hash to
a scalar value (the length of an array, or the population info of a
hash) and then work on that scalar value.  This is probably not what
you meant to do.  See (perlfunc)grep and (perlfunc)map for
alternatives.





Arg too short for msgsnd




(F) msgsnd() requires a string at least as long as sizeof(long).





%s argument is not a HASH or ARRAY element or a subroutine




(F) The argument to exists() must be a hash or array element or a
subroutine with an ampersand, such as:



    $foo{$bar}
    $ref->{"susie"}[12]
    &do_something





%s argument is not a HASH or ARRAY element or slice




(F) The argument to delete() must be either a hash or array element,
such as:



    $foo{$bar}
    $ref->{"susie"}[12]



or a hash or array slice, such as:



    @foo[$bar, $baz, $xyzzy]
    @{$ref->[12]}{"susie", "queue"}





%s argument is not a subroutine name




(F) The argument to exists() for exists &sub must be a subroutine
name, and not a subroutine call.  exists &sub() will generate this
error.





Argument "%s" isn’t numeric%s




(W numeric) The indicated string was fed as an argument to an operator
that expected a numeric value instead.  If you’re fortunate the message
will identify which operator was so unfortunate.





Argument list not closed for PerlIO layer "%s"




(W layer) When pushing a layer with arguments onto the Perl I/O
system you forgot the ) that closes the argument list.  (Layers
take care of transforming data between external and internal
representations.)  Perl stopped parsing the layer list at this
point and did not attempt to push this layer.  If your program
didn’t explicitly request the failing operation, it may be the
result of the value of the environment variable PERLIO.





Array @%s missing the @ in argument %d of %s()




(D deprecated) Really old Perl let you omit the @ on array names in some
spots.  This is now heavily deprecated.





assertion botched: %s




(X) The malloc package that comes with Perl had an internal failure.





Assertion failed: file "%s"




(X) A general assertion failed.  The file in question must be examined.





Assigning non-zero to $[ is no longer possible




(F) When the "array_base" feature is disabled (e.g., under use v5.16;)
the special variable $[, which is deprecated, is now a fixed zero value.





Assignment to both a list and a scalar




(F) If you assign to a conditional operator, the 2nd and 3rd arguments
must either both be scalars or both be lists.  Otherwise Perl won’t
know which context to supply to the right side.





A thread exited while %d threads were running




(W threads)(S) When using threaded Perl, a thread (not necessarily
the main thread) exited while there were still other threads running.
Usually it’s a good idea first to collect the return values of the
created threads by joining them, and only then to exit from the main
thread.  See (threads).





Attempt to access disallowed key ’%s’ in a restricted hash




(F) The failing code has attempted to get or set a key which is not in
the current set of allowed keys of a restricted hash.





Attempt to bless into a reference




(F) The CLASSNAME argument to the bless() operator is expected to be
the name of the package to bless the resulting object into.  You’ve
supplied instead a reference to something: perhaps you wrote



    bless $self, $proto;



when you intended



    bless $self, ref($proto) || $proto;



If you actually want to bless into the stringified version
of the reference supplied, you need to stringify it yourself, for
example by:



    bless $self, "$proto";





Attempt to clear deleted array




(S debugging) An array was assigned to when it was being freed.
Freed values are not supposed to be visible to Perl code.  This
can also happen if XS code calls av_clear from a custom magic
callback on the array.





Attempt to delete disallowed key ’%s’ from a restricted hash




(F) The failing code attempted to delete from a restricted hash a key
which is not in its key set.





Attempt to delete readonly key ’%s’ from a restricted hash




(F) The failing code attempted to delete a key whose value has been
declared readonly from a restricted hash.





Attempt to free non-arena SV: 0x%x




(S internal) All SV objects are supposed to be allocated from arenas
that will be garbage collected on exit.  An SV was discovered to be
outside any of those arenas.





Attempt to free nonexistent shared string ’%s’%s




(S internal) Perl maintains a reference-counted internal table of
strings to optimize the storage and access of hash keys and other
strings.  This indicates someone tried to decrement the reference count
of a string that can no longer be found in the table.





Attempt to free temp prematurely: SV 0x%x




(S debugging) Mortalized values are supposed to be freed by the
free_tmps() routine.  This indicates that something else is freeing the
SV before the free_tmps() routine gets a chance, which means that the
free_tmps() routine will be freeing an unreferenced scalar when it does
try to free it.





Attempt to free unreferenced glob pointers




(S internal) The reference counts got screwed up on symbol aliases.





Attempt to free unreferenced scalar: SV 0x%x




(W internal) Perl went to decrement the reference count of a scalar to
see if it would go to 0, and discovered that it had already gone to 0
earlier, and should have been freed, and in fact, probably was freed.
This could indicate that SvREFCNT_dec() was called too many times, or
that SvREFCNT_inc() was called too few times, or that the SV was
mortalized when it shouldn’t have been, or that memory has been
corrupted.





Attempt to join self




(F) You tried to join a thread from within itself, which is an
impossible task.  You may be joining the wrong thread, or you may need
to move the join() to some other thread.





Attempt to pack pointer to temporary value




(W pack) You tried to pass a temporary value (like the result of a
function, or a computed expression) to the "p" pack() template.  This
means the result contains a pointer to a location that could become
invalid anytime, even before the end of the current statement.  Use
literals or global values as arguments to the "p" pack() template to
avoid this warning.





Attempt to reload %s aborted.




(F) You tried to load a file with use or require that failed to
compile once already.  Perl will not try to compile this file again
unless you delete its entry from %INC.  See (perlfunc)require and
perlvar %INC.





Attempt to set length of freed array




(W) You tried to set the length of an array which has been freed.  You
can do this by storing a reference to the scalar representing the last index
of an array and later assigning through that reference.  For example



    $r = do {my @a; \$#a};
    $$r = 503





Attempt to use reference as lvalue in substr




(W substr) You supplied a reference as the first argument to substr()
used as an lvalue, which is pretty strange.  Perhaps you forgot to
dereference it first.  See (perlfunc)substr.





Attribute "locked" is deprecated




(D deprecated) You have used the attributes pragma to modify the
"locked" attribute on a code reference.  The :locked attribute is
obsolete, has had no effect since 5005 threads were removed, and
will be removed in a future release of Perl 5.





Attribute "unique" is deprecated




(D deprecated) You have used the attributes pragma to modify
the "unique" attribute on an array, hash or scalar reference.
The :unique attribute has had no effect since Perl 5.8.8, and
will be removed in a future release of Perl 5.





av_reify called on tied array




(S debugging) This indicates that something went wrong and Perl got very
confused about @_ or @DB::args being tied.





Bad arg length for %s, is %u, should be %d




(F) You passed a buffer of the wrong size to one of msgctl(), semctl()
or shmctl().  In C parlance, the correct sizes are, respectively,
sizeof(struct msqid_ds *), sizeof(struct semid_ds *), and
sizeof(struct shmid_ds *).





Bad evalled substitution pattern




(F) You’ve used the /e switch to evaluate the replacement for a
substitution, but perl found a syntax error in the code to evaluate,
most likely an unexpected right brace ’}’.





Bad filehandle: %s




(F) A symbol was passed to something wanting a filehandle, but the
symbol has no filehandle associated with it.  Perhaps you didn’t do an
open(), or did it in another package.





Bad free() ignored




(S malloc) An internal routine called free() on something that had never
been malloc()ed in the first place.  Mandatory, but can be disabled by
setting environment variable PERL_BADFREE to 0.



This message can be seen quite often with DB_File on systems with "hard"
dynamic linking, like AIX and OS/2.  It is a bug of Berkeley DB
which is left unnoticed if DB uses forgiving system malloc().





Bad hash




(P) One of the internal hash routines was passed a null HV pointer.





Badly placed ()’s




(A) You’ve accidentally run your script through csh instead
of Perl.  Check the #! line, or manually feed your script into
Perl yourself.





Bad name after %s




(F) You started to name a symbol by using a package prefix, and then
didn’t finish the symbol.  In particular, you can’t interpolate outside
of quotes, so



    $var = 'myvar';
    $sym = mypack::$var;



is not the same as



    $var = 'myvar';
    $sym = "