-*- buffer-read-only: t -*-
!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by autodoc.pl extracting documentation from the C source
files.
Any changes made here will be lost!
=encoding UTF-8
=head1 NAME
perlapi - autogenerated documentation for the perl public API
=head1 DESCRIPTION
X X X
This file contains most of the documentation of the perl public API, as
generated by F. Specifically, it is a listing of functions,
macros, flags, and variables that may be used by extension writers. Besides
L and F, some items are listed here as being actually
documented in another pod.
L is a list of functions which have yet
to be documented. Patches welcome! The interfaces of these are subject to
change without notice.
Some of the functions documented here are consolidated so that a single entry
serves for multiple functions which all do basically the same thing, but have
some slight differences. For example, one form might process magic, while
another doesn't. The name of each variation is listed at the top of the
single entry. But if all have the same signature (arguments and return type)
except for their names, only the usage for the base form is shown. If any
one of the forms has a different signature (such as returning C or
not) every function's signature is explicitly displayed.
Anything not listed here or in the other mentioned pods 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 F is to be avoided when
writing extensions.
In Perl, unlike C, a string of characters may generally contain embedded
C 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 C
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, L.) 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
sometimes 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
L). 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 C
(and variants of that name, including in function names),
it also (essentially transparently) means C.
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 organization of this document is tentative and subject to change.
Suggestions and patches welcome
L.
The sections in this document currently are
=over
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
The listing below is alphabetical, case insensitive.
=head1 AV Handling
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
X
Returns a pointer to the AV's internal SV* array.
This is useful for doing pointer arithmetic on the array.
If all you need is to look up an array element, then prefer C.
=over 3
SV** AvARRAY(AV* av)
=back
=back
=for hackers
Found in file av.h
=over 4
=item C
X
Frees all the elements of an array, leaving it empty.
The XS equivalent of C. See also L.
Note that it is possible that the actions of a destructor called directly
or indirectly by freeing an element of the array could cause the reference
count of the array itself to be reduced (e.g. by deleting an entry in the
symbol table). So it is a possibility that the AV could have been freed
(or even reallocated) on return from the call unless you hold a reference
to it.
=over 3
void av_clear(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Returns the number of elements in the array C. This is the true length of
the array, including any undefined elements. It is always the same as
S>.
=over 3
Size_t av_count(AV *av)
=back
=back
=for hackers
Found in file inline.h
=over 4
=item C
X
NOTE: C is B and may change or be
removed without notice.
Push an SV onto the end of the array, creating the array if necessary.
A small internal helper function to remove a commonly duplicated idiom.
NOTE: C must be explicitly called as
C
with an C parameter.
=over 3
void Perl_av_create_and_push(pTHX_ AV **const avp,
SV *const val)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
NOTE: C is B and may change or be
removed without notice.
Unshifts an SV onto the beginning of the array, creating the array if
necessary.
A small internal helper function to remove a commonly duplicated idiom.
NOTE: C must be explicitly called as
C
with an C parameter.
=over 3
SV** Perl_av_create_and_unshift_one(pTHX_ AV **const avp,
SV *const val)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Deletes the element indexed by C from the array, makes the element
mortal, and returns it. If C equals C, the element is
freed and NULL is returned. NULL is also returned if C is out of
range.
Perl equivalent: S> (with the
C in void context if C is present).
=over 3
SV* av_delete(AV *av, SSize_t key, I32 flags)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Returns true if the element indexed by C has been initialized.
This relies on the fact that uninitialized array elements are set to
C.
Perl equivalent: C.
=over 3
bool av_exists(AV *av, SSize_t key)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Pre-extend an array so that it is capable of storing values at indexes
C. Thus C guarantees that the array can store 100
elements, i.e. that C through C
on a plain array will work without any further memory allocation.
If the av argument is a tied array then will call the C tied
array method with an argument of C.
=over 3
void av_extend(AV *av, SSize_t key)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Returns the SV at the specified index in the array. The C is the
index. If lval is true, you are guaranteed to get a real SV back (in case
it wasn't real before), which you can then modify. Check that the return
value is non-null before dereferencing it to a C.
See L for
more information on how to use this function on tied arrays.
The rough perl equivalent is C.
=over 3
SV** av_fetch(AV *av, SSize_t key, I32 lval)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Same as C> or C>.
=over 3
SSize_t AvFILL(AV* av)
=back
=back
=for hackers
Found in file av.h
=over 4
=item C
X
Set the highest index in the array to the given number, equivalent to
Perl's S>.
The number of elements in the array will be S> after
C returns. If the array was previously shorter, then the
additional elements appended are set to NULL. If the array
was longer, then the excess elements are freed. S> is
the same as C.
=over 3
void av_fill(AV *av, SSize_t fill)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Same as L. Note that, unlike what the name implies, it returns
the maximum index in the array. This is unlike L, which returns what
you would expect.
B>>.
=over 3
SSize_t av_len(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Creates a new AV and populates it with a list of SVs. The SVs are copied
into the array, so they may be freed after the call to C. The new AV
will have a reference count of 1.
Perl equivalent: C
=over 3
AV* av_make(SSize_t size, SV **strp)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Removes one SV from the end of the array, reducing its size by one and
returning the SV (transferring control of one reference count) to the
caller. Returns C if the array is empty.
Perl equivalent: C
=over 3
SV* av_pop(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Pushes an SV (transferring control of one reference count) onto the end of the
array. The array will grow automatically to accommodate the addition.
Perl equivalent: C.
=over 3
void av_push(AV *av, SV *val)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Removes one SV from the start of the array, reducing its size by one and
returning the SV (transferring control of one reference count) to the
caller. Returns C if the array is empty.
Perl equivalent: C
=over 3
SV* av_shift(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Stores an SV in an array. The array index is specified as C. The
return value will be C if the operation failed or if the value did not
need to be actually stored within the array (as in the case of tied
arrays). Otherwise, it can be dereferenced
to get the C that was stored
there (= C)).
Note that the caller is responsible for suitably incrementing the reference
count of C before the call, and decrementing it if the function
returned C.
Approximate Perl equivalent: C.
See L for
more information on how to use this function on tied arrays.
=over 3
SV** av_store(AV *av, SSize_t key, SV *val)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
=item C
XX
These behave identically.
If the array C is empty, these return -1; otherwise they return the maximum
value of the indices of all the array elements which are currently defined in
C.
They process 'get' magic.
The Perl equivalent for these is C.
Use C> to get the number of elements in an array.
=over 3
SSize_t av_tindex(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Undefines the array. The XS equivalent of C.
As well as freeing all the elements of the array (like C), this
also frees the memory used by the av to store its list of scalars.
See L for a note about the array possibly being invalid on
return.
=over 3
void av_undef(AV *av)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Unshift the given number of C values onto the beginning of the
array. The array will grow automatically to accommodate the addition.
Perl equivalent: S>
=over 3
void av_unshift(AV *av, SSize_t num)
=back
=back
=for hackers
Found in file av.c
=over 4
=item C
X
Returns the AV of the specified Perl global or package array with the given
name (so it won't work on lexical variables). C are passed
to C. If C is set and the
Perl variable does not exist then it will be created. If C is zero
and the variable does not exist then NULL is returned.
Perl equivalent: C.
NOTE: the C form is B.
=over 3
AV* get_av(const char *name, I32 flags)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Creates a new AV. The reference count is set to 1.
Perl equivalent: C.
=over 3
AV* newAV()
=back
=back
=for hackers
Found in file av.h
=over 4
=item C
X
C> It is planned to remove C from a
future release of Perl. Do not use it for new code; remove it from
existing code.
Null AV pointer.
(deprecated - use C instead)
=back
=for hackers
Found in file av.h
=head1 Callback Functions
=over 4
=item C
X
Performs a callback to the specified named and package-scoped Perl subroutine
with C (a C-terminated array of strings) as arguments. See
L.
Approximate Perl equivalent: C.
NOTE: the C form is B.
=over 3
I32 call_argv(const char* sub_name, I32 flags, char** argv)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Performs a callback to the specified Perl method. The blessed object must
be on the stack. See L.
NOTE: the C form is B.
=over 3
I32 call_method(const char* methname, I32 flags)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Performs a callback to the specified Perl sub. See L.
NOTE: the C form is B.
=over 3
I32 call_pv(const char* sub_name, I32 flags)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Performs a callback to the Perl sub specified by the SV.
If neither the C nor C flag is supplied, the
SV may be any of a CV, a GV, a reference to a CV, a reference to a GV
or C will be used as the name of the sub to call.
If the C flag is supplied, the SV may be a reference to a CV or
C will be used as the name of the method to call.
If the C flag is supplied, C will be used as
the name of the method to call.
Some other values are treated specially for internal use and should
not be depended on.
See L.
NOTE: the C form is B.
=over 3
I32 call_sv(SV* sv, volatile I32 flags)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Opening bracket on a callback. See C> and L.
=over 3
ENTER;
=back
=back
=for hackers
Found in file scope.h
=over 4
=item C
X
Same as C>, but when debugging is enabled it also associates the
given literal string with the new scope.
=over 3
ENTER_with_name("name");
=back
=back
=for hackers
Found in file scope.h
=over 4
=item C
X
Tells Perl to C the given string in scalar context and return an SV* result.
NOTE: the C form is B.
=over 3
SV* eval_pv(const char* p, I32 croak_on_error)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Tells Perl to C the string in the SV. It supports the same flags
as C, with the obvious exception of C. See L.
The C flag can be used if you only need eval_sv() to
execute code specified by a string, but not catch any errors.
NOTE: the C form is B.
=over 3
I32 eval_sv(SV* sv, I32 flags)
=back
=back
=for hackers
Found in file perl.c
=over 4
=item C
X
Closing bracket for temporaries on a callback. See C> and
L.
=over 3
FREETMPS;
=back
=back
=for hackers
Found in file scope.h
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
X
C> It is planned to remove C from a
future release of Perl. Do not use it for new code; remove it from
existing code.
A backward-compatible version of C which can only return
C or C; in a void context, it returns C.
Deprecated. Use C instead.
=over 3
U32 GIMME
=back
=back
=for hackers
Found in file op.h
=over 4
=item C
X
The XSUB-writer's equivalent to Perl's C. Returns C,
C or C for void, scalar or list context,
respectively. See L for a usage example.
=over 3
U32 GIMME_V
=back
=back
=for hackers
Found in file op.h
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
X
Closing bracket on a callback. See C> and L.
=over 3
LEAVE;
=back
=back
=for hackers
Found in file scope.h
=over 4
=item C
X
Same as C>, but when debugging is enabled it first checks that the
scope has the given name. C must be a literal string.
=over 3
LEAVE_with_name("name");
=back
=back
=for hackers
Found in file scope.h
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlcall.pod
=over 4
=item C
X
Opening bracket for temporaries on a callback. See C> and
L.
=over 3
SAVETMPS;
=back
=back
=for hackers
Found in file scope.h
=head1 Casting
=over 4
=item C
X
Cast-to-bool. A simple S>> cast may not do the right thing:
if C is defined as C, for example, then the cast from C is
implementation-defined.
C in a ternary triggers a bug in xlc on AIX
=over 3
bool cBOOL(bool expr)
=back
=back
=for hackers
Found in file handy.h
=over 4
=item C
X
Cast an NV to I32 while avoiding undefined C behavior
=over 3
I32 I_32(NV what)
=back
=back
=for hackers
Found in file perl.h
=over 4
=item C
Described in L.
=over 3
type INT2PTR(type, int value)
=back
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
X
Cast an NV to IV while avoiding undefined C behavior
=over 3
IV I_V(NV what)
=back
=back
=for hackers
Found in file perl.h
=over 4
=item C
Described in L.
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
Described in L.
=over 3
IV PTR2IV(void * ptr)
=back
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
Described in L.
=over 3
IV PTR2nat(void *)
=back
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
Described in L.
=over 3
NV PTR2NV(void * ptr)
=back
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C
Described in L.
=over 3
unsigned long PTR2ul(void *)
=back
=back
=for hackers
Found in file pod/perlguts.pod
=over 4
=item C