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.


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

1 perl


Next: , Up: perl   [Contents]

1.1 NAME

perl - The Perl 5 language interpreter


Next: , Previous: , 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 ]...

For more information on these options, you can run perldoc perlrun.


Next: , Previous: , 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.


Next: , Up: perl GETTING HELP   [Contents]

1.3.1 Overview

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

Next: , Previous: , 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: , 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
    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 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: , 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: , 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
    perl5200delta       Perl changes in version 5.20.0
    perl5182delta       Perl changes in version 5.18.2
    perl5181delta       Perl changes in version 5.18.1
    perl5180delta       Perl changes in version 5.18.0
    perl5161delta       Perl changes in version 5.16.1
    perl5162delta       Perl changes in version 5.16.2
    perl5163delta       Perl changes in version 5.16.3
    perl5160delta       Perl changes in version 5.16.0
    perl5144delta       Perl changes in version 5.14.4
    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
    perl5125delta       Perl changes in version 5.12.5
    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: , 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: , Up: perl GETTING HELP   [Contents]

1.3.7 Platform-Specific

    perlaix             Perl notes for AIX
    perlamiga           Perl notes for AmigaOS
    perlandroid         Perl notes for Android
    perlbs2000          Perl notes for POSIX-BC BS2000
    perlce              Perl notes for WinCE
    perlcygwin          Perl notes for Cygwin
    perldos             Perl notes for DOS
    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
    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
    perlsynology        Perl notes for Synology
    perltru64           Perl notes for Tru64
    perlvms             Perl notes for VMS
    perlvos             Perl notes for Stratus VOS
    perlwin32           Perl notes for Windows

Previous: , Up: perl GETTING HELP   [Contents]

1.3.8 Stubs for Deleted Documents

    perlboot            
    perlbot             
    perlrepository
    perltodo
    perltooc            
    perltoot            

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

Some documentation is not available as man pages, so if a cross-reference is not found by man, try it with (perldoc). Perldoc can also take you directly to documentation for functions (with the -f switch). See perldoc --help (or perldoc perldoc or man perldoc) for other helpful options (perldoc) has to offer.

In general, if something strange has gone wrong with your program and you’re not sure where you should look for help, try making your code comply with use strict and use warnings. These will often point out exactly where the trouble is.


Next: , Previous: , 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). It combines (in the author’s opinion, anyway) some of the best features of sed, awk, and sh, making it familiar and easy to use for Unix users to whip up quick solutions to annoying problems. Its general-purpose programming facilities support procedural, functional, and object-oriented programming paradigms, making Perl a comfortable language for the long haul on major projects, whatever your bent.

Perl’s roots in text processing haven’t been forgotten over the years. It still boasts some of the most powerful regular expressions to be found anywhere, and its support for Unicode text is world-class. It handles all kinds of structured text, too, through an extensive collection of extensions. Those libraries, collected in the CPAN, provide ready-made solutions to an astounding array of problems. When they haven’t set the standard themselves, they steal from the best – just like Perl itself.


Next: , Previous: , 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: , Up: perl   [Contents]

1.6 ENVIRONMENT

See perlrun NAME.


Next: , Previous: , 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: , Up: perl   [Contents]

1.8 FILES

 "@INC"                 locations of perl libraries

Next: , Previous: , 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: , Up: perl   [Contents]

1.10 DIAGNOSTICS

Using the use strict pragma ensures that all variables are properly declared and prevents other misuses of legacy Perl features.

The use warnings pragma produces some lovely diagnostics. One can also use the -w flag, but its use is normally discouraged, because it gets applied to all executed Perl code, including that not under your control.

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 use warnings pragma?


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

1.11 BUGS

The behavior implied by the use warnings pragma 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: , 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: , Up: Top   [Contents]

2 perlapio


Next: , Up: perlapio   [Contents]

2.1 NAME

perlapio - perl’s IO abstraction interface.


Next: , Previous: , 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);
    SSize_t 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);
    SSize_t 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);
    SSize_t PerlIO_get_cnt(PerlIO *f);
    char   *PerlIO_get_ptr(PerlIO *f);
    void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t 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);
    SSize_t 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: , 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_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.)


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: , 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: , 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: , Up: Top   [Contents]

3 perlartistic


Next: , Up: perlartistic   [Contents]

3.1 NAME

perlartistic - the Perl Artistic License


Next: , Previous: , 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: , 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: , Up: perlartistic   [Contents]

3.4 The "Artistic License"


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: , 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: , 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: , Up: Top   [Contents]

4 perlbook


Next: , Up: perlbook   [Contents]

4.1 NAME

perlbook - Books about and related to Perl


Previous: , 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/ ).


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 Tom Christiansen, brian d foy, Larry Wall with Jon Orwant
        ISBN 978-0-596-00492-7 [4th edition February 2012]
        ISBN 978-1-4493-9890-3 [ebook]
        http://oreilly.com/catalog/9780596004927

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-1-4493-0358-7 [6th edition June 2011]
        http://oreilly.com/catalog/0636920018452

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-1-4493-9309-0 [2nd edition August 2012]
        http://oreilly.com/catalog/0636920012689/

Next: , Previous: , 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-1-4493-0370-9 [5th edition July 2011]
        ISBN 978-1-4493-0813-1 [ebook]
        http://oreilly.com/catalog/0636920018476/
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: , 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: , 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: , 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: , 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: , 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: , 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: , 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: , Up: Top   [Contents]

5 perlboot


Next: , Up: perlboot   [Contents]

5.1 NAME

perlboot - Links to information on object-oriented programming in Perl


Previous: , Up: perlboot   [Contents]

5.2 DESCRIPTION

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

(The above documents supersede the tutorial that was formerly here in perlboot.)


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

6 perlbot


Next: , Up: perlbot   [Contents]

6.1 NAME

perlbot - Links to information on object-oriented programming in Perl


Previous: , Up: perlbot   [Contents]

6.2 DESCRIPTION

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

(The above documents supersede the collection of tricks that was formerly here in perlbot.)


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

7 perlcall


Next: , Up: perlcall   [Contents]

7.1 NAME

perlcall - Perl calling conventions from C


Next: , Previous: , 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: , 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, 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 NAME 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: , 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.


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: , 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: , 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: , 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: , 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: , 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: , 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: , 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: , 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.


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: , 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: , 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: , 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: , 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: , 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: , 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: , 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: , 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, however, Perl 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: , 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: , 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: , 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: , 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: , 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: , 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: , 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: , 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: , Up: perlcall   [Contents]

7.7 SEE ALSO

(perlxs), perlguts NAME, perlembed NAME


Next: , Previous: , 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: , Up: perlcall   [Contents]

7.9 DATE

Version 1.3, 14th Apr 1997


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

8 perlcheat


Next: , Up: perlcheat   [Contents]

8.1 NAME

perlcheat - Perl 5 Cheat Sheet


Next: , Previous: , 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.


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
                         SYNTAX
  OPERATOR PRECEDENCE    foreach (LIST) { }     for (a;b;c) { }
  ->                     while   (e) { }        until (e)   { }
  ++ --                  if      (e) { } elsif (e) { } else { }
  **                     unless  (e) { } elsif (e) { } else { }
  ! ~ \ u+ u-            given   (e) { when (e) {} default {} }
  =~ !~
  * / % x                 NUMBERS vs STRINGS  FALSE vs TRUE
  + - .                   =          =        undef, "", 0, "0"
  << >>                   +          .        anything else
  named uops              == !=      eq ne
  < > <= >= lt gt le ge   < > <= >=  lt gt le ge
  == != <=> eq ne cmp ~~  <=>        cmp
  &
  | ^             REGEX MODIFIERS       REGEX METACHARS
  &&              /i case insensitive   ^      string begin
  || //           /m line based ^$      $      str end (bfr \n)
  .. ...          /s . includes \n      +      one or more
  ?:              /x ignore wh.space    *      zero or more
  = += last goto  /p preserve           ?      zero or one
  , =>            /a ASCII    /aa safe  {3,7}  repeat in range
  list ops        /l locale   /d  dual  |      alternation
  not             /u Unicode            []     character class
  and             /e evaluate /ee rpts  \b     word boundary
  or xor          /g global             \z     string end
                  /o compile pat once   ()     capture
  DEBUG                                 (?:p)  no capture
  -MO=Deparse     REGEX CHARCLASSES     (?#t)  comment
  -MO=Terse       .   [^\n]             (?=p)  ZW pos ahead
  -D##            \s  whitespace        (?!p)  ZW neg ahead
  -d:Trace        \w  word chars        (?<=p) ZW pos behind \K
                  \d  digits            (?<!p) ZW neg behind
  CONFIGURATION   \pP named property    (?>p)  no backtrack
  perl -V:ivsize  \h  horiz.wh.space    (?|p|p)branch reset
                  \R  linebreak         (?<n>p)named capture
                  \S \W \D \H negate    \g{n}  ref to named cap
                                        \K     keep left part
  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: , 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: , Up: perlcheat   [Contents]

8.4 AUTHOR

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


Previous: , Up: perlcheat   [Contents]

8.5 SEE ALSO


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

9 perlclib


Next: , Up: perlclib   [Contents]

9.1 NAME

perlclib - Internal replacements for standard C library functions


Next: , Previous: , 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.


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: , 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) (Dep-
                               recated)
 fflush(stream)              PerlIO_flush(perlio)
 fclose(stream)              PerlIO_close(perlio)

Next: , Previous: , 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: , 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: , Up: perlclib DESCRIPTION   [Contents]

9.2.5 Memory Management and String Handling

 Instead Of:                    Use:

 t* p = malloc(n)               Newx(p, n, t)
 t* p = calloc(n, s)            Newxz(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: , Up: perlclib DESCRIPTION   [Contents]

9.2.6 Character Class Tests

There are several types of character class tests that Perl implements. The only ones described here are those that directly correspond to C library functions that operate on 8-bit characters, but there are equivalents that operate on wide characters, and UTF-8 encoded strings. All are more fully described in (perlapi)Character classes and (perlapi)Character case changing.

The C library routines listed in the table below return values based on the current locale. Use the entries in the final column for that functionality. The other two columns always assume a POSIX (or C) locale. The entries in the ASCII column are only meaningful for ASCII inputs, returning FALSE for anything else. Use these only when you know that is what you want. The entries in the Latin1 column assume that the non-ASCII 8-bit characters are as Unicode defines, them, the same as ISO-8859-1, often called Latin 1.

 Instead Of:  Use for ASCII:   Use for Latin1:      Use for locale:

 isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
 isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
 isascii(c)  isASCII(c)                             isASCII_LC(c)
 isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
 iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
 isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
 isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
 islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
 isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
 ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
 isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
 isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
 isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)

 tolower(c)  toLOWER(c)        toLOWER_L1(c)        toLOWER_LC(c)
 toupper(c)  toUPPER(c)                             toUPPER_LC(c)

To emphasize that you are operating only on ASCII characters, you can append _A to each of the macros in the ASCII column: isALPHA_A, isDIGIT_A, and so on.

(There is no entry in the Latin1 column for isascii even though there is an isASCII_L1, which is identical to isASCII; the latter name is clearer. There is no entry in the Latin1 column for toupper because the result can be non-Latin1. You have to use toUPPER_uni, as described in (perlapi)Character case changing.)


Next: , Previous: , 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: , 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: , Up: perlclib   [Contents]

9.3 SEE ALSO

(perlapi), perlapio NAME, perlguts NAME


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

10 perlcommunity


Next: , Up: perlcommunity   [Contents]

10.1 NAME

perlcommunity - a brief overview of the Perl community


Next: , Previous: , 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.


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: , 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: , 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: , 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.


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://blogs.perl.org/

Many members of the community have a Perl-related blog on this site. If you’d like to join them, you can sign up for free.

http://use.perl.org/

use Perl; used to provide a slashdot-style news/blog website covering all things Perl, from minutes of the meetings of the Perl 6 Design team to conference announcements with (ir)relevant discussion. It no longer accepts updates, but you can still use the site to read old entries and comments.


Previous: , 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."

http://stackoverflow.com/

Stack Overflow is a free question-and-answer site for programmers. It’s not focussed solely on Perl, but it does have an active group of users who do their best to help people with their Perl programming questions.


Next: , Previous: , 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: , 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: , 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: , 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: , 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: , Up: perlcommunity   [Contents]

10.3 AUTHOR

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


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

11 perldata


Next: , Up: perldata   [Contents]

11.1 NAME

perldata - Perl data types


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

11.2 DESCRIPTION


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 NAME). 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). For a more in-depth discussion on identifiers, see Identifier parsing. 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 NAME.

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 NAME and perlre NAME). 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 NAME.

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: , Up: perldata DESCRIPTION   [Contents]

11.2.2 Identifier parsing

Up until Perl 5.18, the actual rules of what a valid identifier was were a bit fuzzy. However, in general, anything defined here should work on previous versions of Perl, while the opposite – edge cases that work in previous versions, but aren’t defined here – probably won’t work on newer versions. As an important side note, please note that the following only applies to bareword identifiers as found in Perl source code, not identifiers introduced through symbolic references, which have much fewer restrictions. If working under the effect of the use utf8; pragma, the following rules apply:

    / (?[ ( \p{Word} & \p{XID_Start} ) + [_] ])
      (?[ ( \p{Word} & \p{XID_Continue} ) ]) *    /x

That is, a "start" character followed by any number of "continue" characters. Perl requires every character in an identifier to also match \w (this prevents some problematic cases); and Perl additionally accepts identfier names beginning with an underscore.

If not under use utf8, the source is treated as ASCII + 128 extra controls, and identifiers should match

    / (?aa) (?!\d) \w+ /x

That is, any word character in the ASCII range, as long as the first character is not a digit.

There are two package separators in Perl: A double colon (::) and a single quote ('). Normal identifiers can start or end with a double colon, and can contain several parts delimited by double colons. Single quotes have similar rules, but with the exception that they are not legal at the end of an identifier: That is, $'foo and $foo'bar are legal, but $foo'bar' is not.

Additionally, if the identifier is preceded by a sigil – that is, if the identifier is part of a variable name – it may optionally be enclosed in braces.

While you can mix double colons with singles quotes, the quotes must come after the colons: $::::'foo and $foo::'bar are legal, but $::'::foo and $foo'::bar are not.

Put together, a grammar to match a basic identifier becomes

 /
  (?(DEFINE)
      (?<variable>
          (?&sigil)
          (?:
                  (?&normal_identifier)
              |   \{ \s* (?&normal_identifier) \s* \}
          )
      )
      (?<normal_identifier>
          (?: :: )* '?
           (?&basic_identifier)
           (?: (?= (?: :: )+ '? | (?: :: )* ' ) (?&normal_identifier) )?
          (?: :: )*
      )
      (?<basic_identifier>
        # is use utf8 on?
          (?(?{ (caller(0))[8] & $utf8::hint_bits })
              (?&Perl_XIDS) (?&Perl_XIDC)*
            | (?aa) (?!\d) \w+
          )
      )
      (?<sigil> [&*\$\@\%])
      (?<Perl_XIDS> (?[ ( \p{Word} & \p{XID_Start} ) + [_] ]) )
      (?<Perl_XIDC> (?[ \p{Word} & \p{XID_Continue} ]) )
  )
 /x

Meanwhile, special identifiers don’t follow the above rules; For the most part, all of the identifiers in this category have a special meaning given by Perl. Because they have special parsing rules, these generally can’t be fully-qualified. They come in four forms:

A sigil, followed solely by digits matching \p{POSIX_Digit}, like $0, $1, or $10000.
A sigil, followed by either a caret and a single POSIX uppercase letter, like $^V or $^W, or a sigil followed by a literal control character matching the \p{POSIX_Cntrl} property. Due to a historical oddity, if not running under use utf8, the 128 extra controls in the [0x80-0xff] range may also be used in length one variables. The use of a literal control character is deprecated. Support for this form will be removed in a future version of perl.
Similar to the above, a sigil, followed by bareword text in brackets, where the first character is either a caret followed by an uppercase letter, or a literal control, like ${^GLOBAL_PHASE} or ${\7LOBAL_PHASE}. The use of a literal control character is deprecated. Support for this form will be removed in a future version of perl.
A sigil followed by a single character matching the \p{POSIX_Punct} property, like $! or %+.

Note that as of Perl 5.20, literal control characters in variable names are deprecated.


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

11.2.3 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: , Up: perldata DESCRIPTION   [Contents]

11.2.4 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 NAME. 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 NAME).

    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.

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: , Up: perldata DESCRIPTION   [Contents]

11.2.5 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, a simple identifier within such curlies is forced to be a string, and likewise 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'}++.


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

11.2.5.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: , Up: perldata Scalar value constructors   [Contents]

11.2.5.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: , Up: perldata Scalar value constructors   [Contents]

11.2.5.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: , Up: perldata Scalar value constructors   [Contents]

11.2.5.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: , Up: perldata DESCRIPTION   [Contents]

11.2.6 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 NAME.

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.

If a key appears more than once in the initializer list of a hash, the last occurrence wins:

    %circle = (
                  center => [5, 10],
                  center => [27, 9],
                  radius => 100,
                  color => [0xDF, 0xFF, 0x00],
                  radius => 54,
    );

    # same as
    %circle = (
                  center => [27, 9],
                  color => [0xDF, 0xFF, 0x00],
                  radius => 54,
    );

This can be used to provide overridable configuration defaults:

    # values in %args take priority over %config_defaults
    %config = (%config_defaults, %args);

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

11.2.7 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: , Up: perldata DESCRIPTION   [Contents]

11.2.8 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: , Up: perldata DESCRIPTION   [Contents]

11.2.9 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

But:

    @a = (1)[1,0];          # @a has two elements
    @b = (1,undef)[1,0,2];  # @b has three elements

More generally, a slice yields the empty list if it indexes only beyond the end of a list:

    @a = (1)[  1,2];        # @a has no elements
    @b = (1)[0,1,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).


Next: , Up: perldata Slices   [Contents]

11.2.9.1 Key/Value Hash Slices

Starting in Perl 5.20, a hash slice operation with the % symbol is a variant of slice operation returning a list of key/value pairs rather than just values:

    %h = (blonk => 2, foo => 3, squink => 5, bar => 8);
    %subset = %h{'foo', 'bar'}; # key/value hash slice
    # %subset is now (foo => 3, bar => 8)

However, the result of such a slice cannot be localized, deleted or used in assignment. These are otherwise very much consistent with hash slices using the @ symbol.


Previous: , Up: perldata Slices   [Contents]

11.2.9.2 Index/Value Array Slices

Similar to key/value hash slices (and also introduced in Perl 5.20), the % array slice syntax returns a list of index/value pairs:

    @a = "a".."z";
    @list = %a[3,4,6];
    # @list is now (3, "d", 4, "e", 6, "g")

Previous: , Up: perldata DESCRIPTION   [Contents]

11.2.10 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 NAME 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: , 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 NAME, perlsub NAME, and perlmod Symbol Tables for more discussion on typeglobs and the *foo{THING} syntax.


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

12 perldbmfilter


Next: , Up: perldbmfilter   [Contents]

12.1 NAME

perldbmfilter - Perl DBM Filters


Next: , Previous: , 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: , 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.


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: , 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: , 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: , Up: perldbmfilter   [Contents]

12.4 SEE ALSO

(DB_File), (GDBM_File), (NDBM_File), (ODBM_File) and (SDBM_File).


Previous: , Up: perldbmfilter   [Contents]

12.5 AUTHOR

Paul Marquess


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

13 perldebguts


Next: , Up: perldebguts   [Contents]

13.1 NAME

perldebguts - Guts of Perl debugging


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

13.2 DESCRIPTION

This is not perldebug NAME, 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: , 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.


Up: perldebguts Debugger Internals   [Contents]

13.3.1 Writing Your Own Debugger


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: , 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: , 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 NAME) are considered for internal use only, and as such are subject to change without notice.


Next: , Previous: , 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: , 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.


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: , Up: perldebguts Debugging Regular Expressions   [Contents]

13.5.2 Types of Nodes

Here are the current 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 rules for non-utf8
 BOUNDL          no         Match "" at any locale word boundary
 BOUNDU          no         Match "" at any word boundary using Unicode
                            rules
 BOUNDA          no         Match "" at any word boundary using ASCII
                            rules
 NBOUND          no         Match "" at any word non-boundary using
                            native charset rules for non-utf8
 NBOUNDL         no         Match "" at any locale word non-boundary
 NBOUNDU         no         Match "" at any word non-boundary using
                            Unicode rules
 NBOUNDA         no         Match "" at any word non-boundary using
                            ASCII rules
 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

 POSIXD          none       Some [[:class:]] under /d; the FLAGS field
                            gives which one
 POSIXL          none       Some [[:class:]] under /l; the FLAGS field
                            gives which one
 POSIXU          none       Some [[:class:]] under /u; the FLAGS field
                            gives which one
 POSIXA          none       Some [[:class:]] under /a; the FLAGS field
                            gives which one
 NPOSIXD         none       complement of POSIXD, [[:^class:]]
 NPOSIXL         none       complement of POSIXL, [[:^class:]]
 NPOSIXU         none       complement of POSIXU, [[:^class:]]
 NPOSIXA         none       complement of POSIXA, [[:^class:]]

 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 non-UTF-8 string (not guaranteed
                            to be folded) using /id rules (w/len).
 EXACTFL         str        Match this string (not guaranteed to be
                            folded) using /il rules (w/len).
 EXACTFU         str        Match this string (folded iff in UTF-8,
                            length in folding doesn't change if not in
                            UTF-8) using /iu rules (w/len).
 EXACTFA         str        Match this string (not guaranteed to be
                            folded) using /iaa rules (w/len).
 EXACTFU_SS      str        Match this string (folded iff in UTF-8,
                            length in folding may change even if not in
                            UTF-8) using /iu rules (w/len).
 EXACTFA_NO_TRIE str        Match this string (which is not trie-able;
                            not guaranteed to be folded) using /iaa
                            rules (w/len).

 # 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 rules for non-utf8
 REFFL           num 1      Match already matched string, folded in loc.
 REFFU           num 1      Match already matched string, folded using
                            unicode rules for non-utf8
 REFFA           num 1      Match already matched string, folded using
                            unicode rules 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 rules for non-utf8
 NREFFL          no-sv 1    Match already matched string, folded in loc.
 NREFFU          num 1      Match already matched string, folded using
                            unicode rules for non-utf8
 NREFFA          num 1      Match already matched string, folded using
                            unicode rules 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.

 TRIE            trie 1     Match many EXACT(F[ALU]?)? at once.
                            flags==type
 TRIEC           trie       Same as TRIE, but with embedded charclass
                 charclass  data

 AHOCORASICK     trie 1     Aho Corasick stclass. flags==type
 AHOCORASICKC    trie       Same as AHOCORASICK, but with embedded
                 charclass  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

 # 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: , 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: , 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}.


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: , Up: perldebguts   [Contents]

13.7 SEE ALSO

perldebug NAME, perlguts NAME, perlrun NAME (re), and (Devel-DProf).


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

14 perldebtut


Next: , Up: perldebtut   [Contents]

14.1 NAME

perldebtut - Perl debugging tutorial


Next: , Previous: , 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: , 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: , 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: , 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 NAME and perlreftut NAME


Next: , Previous: , 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: , 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: , 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 NAME, perlretut NAME, and to decode the mysterious labels (BOL and CURLYN, etc. above), see perldebguts NAME.


Next: , Previous: , 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: , 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: , 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: , 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 NAME is probably the next place to go), and of course, experiment.


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

14.13 SEE ALSO

perldebug NAME, perldebguts NAME, perldiag NAME, perlrun NAME


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

14.14 AUTHOR

Richard Foley <richard.foley@rfi.net> Copyright (c) 2000


Previous: , 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: , Up: Top   [Contents]

15 perldebug


Next: , Up: perldebug   [Contents]

15.1 NAME

perldebug - Perl debugging


Next: , Previous: , Up: perldebug   [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: , Up: perldebug   [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.


Next: , Up: perldebug 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: , Up: perldebug 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: , Up: perldebug 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 a command or spawn a 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.

HistFile

The path of the file from which the history (assuming a usable Term::ReadLine backend) will be read on the debugger’s startup, and to which it will be saved on shutdown (for persistence across sessions). Similar in concept to Bash’s .bash_history file.

HistSize

The count of the saved lines in the history (assuming HistFile above).

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: , Up: perldebug 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: , Up: perldebug 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: , Up: perldebug 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: , Up: perldebug 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: , Up: perldebug The Perl Debugger   [Contents]

15.3.8 Editor Support for Debugging

If you have the GNU’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).

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: , Up: perldebug 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: , Up: perldebug   [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: , Up: perldebug   [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: , Up: perldebug   [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: , Up: perldebug   [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: , Up: Top   [Contents]

16 perldiag


Next: , Up: perldiag   [Contents]

16.1 NAME

perldiag - various Perl diagnostics


Next: , Previous: , 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. E.g. (W closed) means a warning in the closed category.

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 in %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

(S ambiguous) 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 -%s resolved as -&%s()

(S 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 %c resolved as operator %c

(S 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';.

’|’ 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).

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.

A sequence of multiple spaces in a charnames alias definition is deprecated

(D deprecated) You defined a character name which had multiple space characters in a row. Change them to single spaces. Usually these names are defined in the :alias import argument to use charnames, but they could be defined by a translator installed into $^H{charnames}. See (charnames)CUSTOM ALIASES.

assertion botched: %s

(X) The malloc package that comes with Perl had an internal failure.

Assertion %s failed: file "%s", line %d

(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.

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 freed package

(F) You wrote bless $foo with one argument after somehow causing the current package to be freed. Perl cannot figure out what to do, so it throws up in hands in despair.

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

(S 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 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 misc) 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 prototype(%s) discards earlier prototype attribute in same sub

(W misc) A sub was declared as sub foo : prototype(A) : prototype(B) {}, for example. Since each sub can only have one prototype, the earlier declaration(s) are discarded while the last one is applied.

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 = "mypack::$var";
Bad plugin affecting keyword ’%s’

(F) An extension using the keyword plugin mechanism violated the plugin API.

Bad realloc() ignored

(S malloc) An internal routine called realloc() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by setting the environment variable PERL_BADFREE to 1.

Bad symbol for array

(P) An internal request asked to add an array entry to something that wasn’t a symbol table entry.

Bad symbol for dirhandle

(P) An internal request asked to add a dirhandle entry to something that wasn’t a symbol table entry.

Bad symbol for filehandle

(P) An internal request asked to add a filehandle entry to something that wasn’t a symbol table entry.

Bad symbol for hash

(P) An internal request asked to add a hash entry to something that wasn’t a symbol table entry.

Bareword found in conditional

(W bareword) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

    open FOO || die;

It may also indicate a misspelled constant that has been interpreted as a bareword:

    use constant TYPO => 1;
    if (TYOP) { print "foo" }

The strict pragma is useful in avoiding such errors.

Bareword "%s" not allowed while "strict subs" in use

(F) With "strict subs" in use, a bareword is only allowed as a subroutine identifier, in curly brackets or to the left of the "=>" symbol. Perhaps you need to predeclare a subroutine?

Bareword "%s" refers to nonexistent package

(W bareword) You used a qualified bareword of the form Foo::, but the compiler saw no other uses of that namespace before that point. Perhaps you need to predeclare a package?

BEGIN failed–compilation aborted

(F) An untrapped exception was raised while executing a BEGIN subroutine. Compilation stops immediately and the interpreter is exited.

BEGIN not safe after errors–compilation aborted

(F) Perl found a BEGIN {} subroutine (or a use directive, which implies a BEGIN {}) after one or more compilation errors had already occurred. Since the intended environment for the BEGIN {} could not be guaranteed (due to the errors), and since subsequent code likely depends on its correct operation, Perl just gave up.

\%d better written as $%d

(W syntax) Outside of patterns, backreferences live on as variables. The use of backslashes is grandfathered on the right-hand side of a substitution, but stylistically it’s better to use the variable form because other Perl programmers will expect it, and it works better if there are more than 9 backreferences.

Binary number > 0b11111111111111111111111111111111 non-portable

(W portable) The binary number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See perlport NAME for more on portability concerns.

bind() on closed socket %s

(W closed) You tried to do a bind on a closed socket. Did you forget to check the return value of your socket() call? See ‘perlfunc bind’.

binmode() on closed filehandle %s

(W unopened) You tried binmode() on a filehandle that was never opened. Check your control flow and number of arguments.

"\b{" is deprecated; use "\b\{" or "\b[{]" instead in regex; marked by <– HERE in m/%s/
"\B{" is deprecated; use "\B\{" or "\B[{]" instead in regex; marked by <– HERE in m/%s/

(D deprecated) Use of an unescaped "{" immediately following a \b or \B is now deprecated so as to reserve its use for Perl itself in a future release. You can either precede the brace with a backslash, or enclose it in square brackets; the latter is the way to go if the pattern delimiters are {}.

Bit vector size > 32 non-portable

(W portable) Using bit vector sizes larger than 32 is non-portable.

Bizarre copy of %s

(P) Perl detected an attempt to copy an internal value that is not copiable.

Bizarre SvTYPE [%d]

(P) When starting a new thread or returning values from a thread, Perl encountered an invalid data type.

Buffer overflow in prime_env_iter: %s

(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over %ENV, it encountered a logical name or symbol definition which was too long, so it was truncated to the string shown.

Callback called exit

(F) A subroutine invoked from an external package via call_sv() exited by calling exit.

%s() called too early to check prototype

(W prototype) You’ve called a function that has a prototype before the parser saw a definition or declaration for it, and Perl could not check that the call conforms to the prototype. You need to either add an early prototype declaration for the subroutine in question, or move the subroutine definition ahead of the call to get proper prototype checking. Alternatively, if you are certain that you’re calling the function correctly, you may put an ampersand before the name to avoid the warning. See perlsub NAME.

Calling POSIX::%s() is deprecated

(D deprecated) You called a function whose use is deprecated. See the function’s name in (POSIX) for details.

Cannot compress integer in pack

(F) An argument to pack("w",...) was too large to compress. The BER compressed integer format can only be used with positive integers, and you attempted to compress Infinity or a very large number (> 1e308). See ‘perlfunc pack’.

Cannot compress negative numbers in pack

(F) An argument to pack("w",...) was negative. The BER compressed integer format can only be used with positive integers. See ‘perlfunc pack’.

Cannot convert a reference to %s to typeglob

(F) You manipulated Perl’s symbol table directly, stored a reference in it, then tried to access that symbol via conventional Perl syntax. The access triggers Perl to autovivify that typeglob, but it there is no legal conversion from that type of reference to a typeglob.

Cannot copy to %s

(P) Perl detected an attempt to copy a value to an internal type that cannot be directly assigned to.

Cannot find encoding "%s"

(S io) You tried to apply an encoding that did not exist to a filehandle, either with open() or binmode().

Cannot set tied @DB::args

(F) caller tried to set @DB::args, but found it tied. Tying @DB::args is not supported. (Before this error was added, it used to crash.)

Cannot tie unreifiable array

(P) You somehow managed to call tie on an array that does not keep a reference count on its arguments and cannot be made to do so. Such arrays are not even supposed to be accessible to Perl code, but are only used internally.

Can only compress unsigned integers in pack

(F) An argument to pack("w",...) was not an integer. The BER compressed integer format can only be used with positive integers, and you attempted to compress something else. See ‘perlfunc pack’.

Can’t bless non-reference value

(F) Only hard references may be blessed. This is how Perl "enforces" encapsulation of objects. See perlobj NAME.

Can’t "break" in a loop topicalizer

(F) You called break, but you’re in a foreach block rather than a given block. You probably meant to use next or last.

Can’t "break" outside a given block

(F) You called break, but you’re not inside a given block.

Can’t call method "%s" on an undefined value

(F) You used the syntax of a method call, but the slot filled by the object reference or package name contains an undefined value. Something like this will reproduce the error:

    $BADREF = undef;
    process $BADREF 1,2,3;
    $BADREF->process(1,2,3);
Can’t call method "%s" on unblessed reference

(F) A method call must know in what package it’s supposed to run. It ordinarily finds this out from the object reference you supply, but you didn’t supply an object reference in this case. A reference isn’t an object reference until it has been blessed. See perlobj NAME.

Can’t call method "%s" without a package or object reference

(F) You used the syntax of a method call, but the slot filled by the object reference or package name contains an expression that returns a defined value which is neither an object reference nor a package name. Something like this will reproduce the error:

    $BADREF = 42;
    process $BADREF 1,2,3;
    $BADREF->process(1,2,3);
Can’t call mro_isa_changed_in() on anonymous symbol table

(P) Perl got confused as to whether a hash was a plain hash or a symbol table hash when trying to update @ISA caches.

Can’t call mro_method_changed_in() on anonymous symbol table

(F) An XS module tried to call mro_method_changed_in on a hash that was not attached to the symbol table.

Can’t chdir to %s

(F) You called perl -x/foo/bar, but /foo/bar is not a directory that you can chdir to, possibly because it doesn’t exist.

Can’t check filesystem of script "%s" for nosuid

(P) For some reason you can’t check the filesystem of the script for nosuid.

Can’t coerce %s to %s in %s

(F) Certain types of SVs, in particular real symbol table entries (typeglobs), can’t be forced to stop being what they are. So you can’t say things like:

    *foo += 1;

You CAN say

    $foo = *foo;
    $foo += 1;

but then $foo no longer contains a glob.

Can’t "continue" outside a when block

(F) You called continue, but you’re not inside a when or default block.

Can’t create pipe mailbox

(P) An error peculiar to VMS. The process is suffering from exhausted quotas or other plumbing problems.

Can’t declare %s in "%s"

(F) Only scalar, array, and hash variables may be declared as "my", "our" or "state" variables. They must have ordinary identifiers as names.

Can’t "default" outside a topicalizer

(F) You have used a default block that is neither inside a foreach loop nor a given block. (Note that this error is issued on exit from the default block, so you won’t get the error if you use an explicit continue.)

Can’t do inplace edit: %s is not a regular file

(S inplace) You tried to use the -i switch on a special file, such as a file in /dev, a FIFO or an uneditable directory. The file was ignored.

Can’t do inplace edit on %s: %s

(S inplace) The creation of the new file failed for the indicated reason.

Can’t do inplace edit without backup

(F) You’re on a system such as MS-DOS that gets confused if you try reading from a deleted (but still opened) file. You have to say -i.bak, or some such.

Can’t do inplace edit: %s would not be unique

(S inplace) Your filesystem does not support filenames longer than 14 characters and Perl was unable to create a unique filename during inplace editing with the -i switch. The file was ignored.

Can’t do waitpid with flags

(F) This machine doesn’t have either waitpid() or wait4(), so only waitpid() without flags is emulated.

Can’t emulate -%s on #! line

(F) The #! line specifies a switch that doesn’t make sense at this point. For example, it’d be kind of silly to put a -x on the #! line.

Can’t %s %s-endian %ss on this platform

(F) Your platform’s byte-order is neither big-endian nor little-endian, or it has a very strange pointer size. Packing and unpacking big- or little-endian floating point values and pointers may not be possible. See ‘perlfunc pack’.

Can’t exec "%s": %s

(W exec) A system(), exec(), or piped open call could not execute the named program for the indicated reason. Typical reasons include: the permissions were wrong on the file, the file wasn’t found in $ENV{PATH}, the executable in question was compiled for another architecture, or the #! line in a script points to an interpreter that can’t be run for similar reasons. (Or maybe your system doesn’t support #! at all.)

Can’t exec %s

(F) Perl was trying to execute the indicated program for you because that’s what the #! line said. If that’s not what you wanted, you may need to mention "perl" on the #! line somewhere.

Can’t execute %s

(F) You used the -S switch, but the copies of the script to execute found in the PATH did not have correct permissions.

Can’t find an opnumber for "%s"

(F) A string of a form CORE::word was given to prototype(), but there is no builtin with the name word.

Can’t find %s character property "%s"

(F) You used \p{} or \P{} but the character property by that name could not be found. Maybe you misspelled the name of the property? See (perluniprops)Properties accessible through \p{} and \P{} for a complete list of available official properties.

Can’t find label %s

(F) You said to goto a label that isn’t mentioned anywhere that it’s possible for us to go to. See ‘perlfunc goto’.

Can’t find %s on PATH

(F) You used the -S switch, but the script to execute could not be found in the PATH.

Can’t find %s on PATH, ’.’ not in PATH

(F) You used the -S switch, but the script to execute could not be found in the PATH, or at least not with the correct permissions. The script exists in the current directory, but PATH prohibits running it.

Can’t find string terminator %s anywhere before EOF

(F) Perl strings can stretch over multiple lines. This message means that the closing delimiter was omitted. Because bracketed quotes count nesting levels, the following is missing its final parenthesis:

    print q(The character '(' starts a side comment.);

If you’re getting this error from a here-document, you may have included unseen whitespace before or after your closing tag or there may not be a linebreak after it. A good programmer’s editor will have a way to help you find these characters (or lack of characters). See perlop NAME for the full details on here-documents.

Can’t find Unicode property definition "%s"

(F) You may have tried to use \p which means a Unicode property (for example \p{Lu} matches all uppercase letters). If you did mean to use a Unicode property, see (perluniprops)Properties accessible through \p{} and \P{} for a complete list of available properties. If you didn’t mean to use a Unicode property, escape the \p, either by \\p (just the \p) or by \Q\p (the rest of the string, or until \E).