Syntax-K

Know-How für Ihr Projekt

Perl Documentation

NAME

perlapi - autogenerated documentation for the perl public API

DESCRIPTION

This file contains the documentation of the perl public API generated by embed.pl, specifically a listing of functions, macros, flags, and variables that may be used by extension writers. At the end is a list of functions which have yet to be documented. The interfaces of those are subject to change without notice. Anything not listed here is not part of the public API, and should not be used by extension writers at all. For these reasons, blindly using functions listed in proto.h is to be avoided when writing extensions.

In Perl, unlike C, a string of characters may generally contain embedded NUL characters. Sometimes in the documentation a Perl string is referred to as a "buffer" to distinguish it from a C string, but sometimes they are both just referred to as strings.

Note that all Perl API global variables must be referenced with the PL_ prefix. Again, those not listed here are not to be used by extension writers, and can be changed or removed without notice; same with macros. Some macros are provided for compatibility with the older, unadorned names, but this support may be disabled in a future release.

Perl was originally written to handle US-ASCII only (that is characters whose ordinal numbers are in the range 0 - 127). And documentation and comments may still use the term ASCII, when sometimes in fact the entire range from 0 - 255 is meant.

The non-ASCII characters below 256 can have various meanings, depending on various things. (See, most notably, perllocale.) But usually the whole range can be referred to as ISO-8859-1. Often, the term "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1. But some people treat "Latin1" as referring just to the characters in the range 128 through 255, or somethimes from 160 through 255. This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters.

Note that Perl can be compiled and run under either ASCII or EBCDIC (See perlebcdic). Most of the documentation (and even comments in the code) ignore the EBCDIC possibility. For almost all purposes the differences are transparent. As an example, under EBCDIC, instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever this documentation refers to utf8 (and variants of that name, including in function names), it also (essentially transparently) means UTF-EBCDIC. But the ordinals of characters differ between ASCII, EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different number of bytes than in UTF-8.

The listing below is alphabetical, case insensitive.

Array Manipulation Functions

Callback Functions

Character case changing

Character classification

This section is about functions (really macros) that classify characters into types, such as punctuation versus alphabetic, etc. Most of these are analogous to regular expression character classes. (See "POSIX Character Classes" in perlrecharclass.) There are several variants for each class. (Not all macros have all variants; each item below lists the ones valid for it.) None are affected by use bytes, and only the ones with LC in the name are affected by the current locale.

The base function, e.g., isALPHA(), takes an octet (either a char or a U8) as input and returns a boolean as to whether or not the character represented by that octet is (or on non-ASCII platforms, corresponds to) an ASCII character in the named class based on platform, Unicode, and Perl rules. If the input is a number that doesn't fit in an octet, FALSE is returned.

Variant isFOO_A (e.g., isALPHA_A()) is identical to the base function with no suffix "_A".

Variant isFOO_L1 imposes the Latin-1 (or EBCDIC equivlalent) character set onto the platform. That is, the code points that are ASCII are unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code points are treated as if they are Latin-1 characters. For example, isWORDCHAR_L1() will return true when called with the code point 0xDF, which is a word character in both ASCII and EBCDIC (though it represents different characters in each).

Variant isFOO_uvchr is like the isFOO_L1 variant, but accepts any UV code point as input. If the code point is larger than 255, Unicode rules are used to determine if it is in the character class. For example, isWORDCHAR_uvchr(0x100) returns TRUE, since 0x100 is LATIN CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.

Variant isFOO_utf8 is like isFOO_uvchr, but the input is a pointer to a (known to be well-formed) UTF-8 encoded string (U8* or char*, and possibly containing embedded NUL characters). The classification of just the first (possibly multi-byte) character in the string is tested.

Variant isFOO_LC is like the isFOO_A and isFOO_L1 variants, but the result is based on the current locale, which is what LC in the name stands for. If Perl can determine that the current locale is a UTF-8 locale, it uses the published Unicode rules; otherwise, it uses the C library function that gives the named classification. For example, isDIGIT_LC() when not in a UTF-8 locale returns the result of calling isdigit(). FALSE is always returned if the input won't fit into an octet. On some platforms where the C library function is known to be defective, Perl changes its result to follow the POSIX standard's rules.

Variant isFOO_LC_uvchr is like isFOO_LC, but is defined on any UV. It returns the same as isFOO_LC for input code points less than 256, and returns the hard-coded, not-affected-by-locale, Unicode results for larger ones.

Variant isFOO_LC_utf8 is like isFOO_LC_uvchr, but the input is a pointer to a (known to be well-formed) UTF-8 encoded string (U8* or char*, and possibly containing embedded NUL characters). The classification of just the first (possibly multi-byte) character in the string is tested.

Cloning an interpreter

Compile-time scope hooks

COP Hint Hashes

COP Hint Reading

Custom Operators

CV Manipulation Functions

This section documents functions to manipulate CVs which are code-values, or subroutines. For more information, see perlguts.

xsubpp variables and internal functions

Debugging Utilities

Display and Dump functions

Embedding Functions

Exception Handling (simple) Macros

Functions in file scope.c

Functions in file vutil.c

"Gimme" Values

Global Variables

These variables are global to an entire process. They are shared between all interpreters and all threads in a process. Any variables not documented here may be changed or removed without notice, so don't use them! If you feel you really do need to use an unlisted variable, first send email to perl5-porters@perl.org. It may be that someone there will point out a way to accomplish what you need without using an internal variable. But if not, you should get a go-ahead to document and then use the variable.

GV Functions

A GV is a structure which corresponds to to a Perl typeglob, ie *foo. It is a structure that holds a pointer to a scalar, an array, a hash etc, corresponding to $foo, @foo, %foo.

GVs are usually found as values in stashes (symbol table hashes) where Perl stores its global variables.

Handy Values

Hash Manipulation Functions

A HV structure represents a Perl hash. It consists mainly of an array of pointers, each of which points to a linked list of HE structures. The array is indexed by the hash function of the key, so each linked list represents all the hash entries with the same hash value. Each HE contains a pointer to the actual value, plus a pointer to a HEK structure which holds the key and hash value.

Hook manipulation

These functions provide convenient and thread-safe means of manipulating hook variables.

Lexer interface

This is the lower layer of the Perl parser, managing characters and tokens.

Locale-related functions and macros

Magical Functions

Memory Management

Miscellaneous Functions

MRO Functions

These functions are related to the method resolution order of perl classes

Multicall Functions

Numeric functions

Obsolete backwards compatibility functions

Some of these are also deprecated. You can exclude these from your compiled Perl by adding this option to Configure: -Accflags='-DNO_MATHOMS'

Optree construction

Optree Manipulation Functions

Pack and Unpack

Pad Data Structures

Per-Interpreter Variables

REGEXP Functions

Stack Manipulation Macros

SV-Body Allocation

SV Flags

SV Manipulation Functions

Unicode Support

"Unicode Support" in perlguts has an introduction to this API.

See also "Character classification", and "Character case changing". Various functions outside this section also work specially with Unicode. Search for the string "utf8" in this document.

Variables created by xsubpp and xsubpp internal functions

Warning and Dieing

Undocumented functions

The following functions have been flagged as part of the public API, but are currently undocumented. Use them at your own risk, as the interfaces are subject to change. Functions that are not listed in this document are not intended for public use, and should NOT be used under any circumstances.

If you feel you need to use one of these functions, first send email to perl5-porters@perl.org. It may be that there is a good reason for the function not being documented, and it should be removed from this list; or it may just be that no one has gotten around to documenting it. In the latter case, you will be asked to submit a patch to document the function. Once your patch is accepted, it will indicate that the interface is stable (unless it is explicitly marked otherwise) and usable by you.

AUTHORS

Until May 1997, this document was maintained by Jeff Okamoto <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.

With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, and Gurusamy Sarathy.

API Listing originally by Dean Roehrich <roehrich@cray.com>.

Updated to be autogenerated from comments in the source by Benjamin Stuhl.

SEE ALSO

perlguts, perlxs, perlxstut, perlintern