-*- mode: Pod; 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.
The names of all API functions begin with the prefix C so as to
prevent any name collisions with your code. But, unless
C has been specified in compiling your code
(see L), synonymous macros are also available to you
that don't have this prefix, and also hide from you the need (or not) to have
a thread context parameter passed to the function. Generally, code is easier
to write and to read when the short form is used, so in practice that
compilation flag is not used. Not all functions have the short form; both
are listed here when available.
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 may 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 API elements are grouped by functionality into sections, as follows.
Within sections the elements are ordered alphabetically, ignoring case, with
non-leading underscores sorted first, and leading underscores and digits
sorted last.
=over 4
=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
=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
Documented at pod/perlguts.pod, line 30
=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)
void Perl_av_clear(pTHX_ AV *av)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 618
=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)
Size_t Perl_av_count(pTHX_ AV *av)
=back
=back
=for hackers
Declared in embed.fnc; documented at inline.h, line 48
=over 4
=item C
X
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.
=over 3
void Perl_av_create_and_push(pTHX_ AV ** const avp,
SV * const val)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 751
=over 4
=item C
X
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.
=over 3
SV ** Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
SV * const val)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 849
=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)
SV * Perl_av_delete(pTHX_ AV *av, SSize_t key, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 1065
=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)
bool Perl_av_exists(pTHX_ AV *av, SSize_t key)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 1143
=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)
void Perl_av_extend(pTHX_ AV *av, SSize_t key)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 52
=over 4
=item C
X
Returns the SV at the specified index in the array. The C is the
index. If C 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)
SV ** Perl_av_fetch(pTHX_ AV *av, SSize_t key, I32 lval)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 227
=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)
void Perl_av_fill(pTHX_ AV *av, SSize_t fill)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 1011
=over 4
=item C
Described under C>
=back
=over 4
=item C
X
Creates a new AV and populates it with a list (C, length C) of
SVs. A copy is made of each SV, so their refcounts are not changed. The new
AV will have a reference count of 1.
Perl equivalent: C
=over 3
AV * av_make( SSize_t size, SV **strp)
AV * Perl_av_make(pTHX_ SSize_t size, SV **strp)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 454
=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)
SV * Perl_av_pop(pTHX_ AV *av)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 810
=over 4
=item C
=item C
XX
These each push 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.
C is the general purpose form, suitable for all situations.
C is a cut-down version of C that assumes that the
array is very straightforward, with no magic, not readonly, and is AvREAL
(see L), and that C is not
less than -1. This function MUST NOT be used in situations where any of those
assumptions may not hold.
=over 3
void av_push ( AV *av, SV *val)
void Perl_av_push (pTHX_ AV *av, SV *val)
void av_push_simple( AV *av, SV *val)
void Perl_av_push_simple(pTHX_ AV *av, SV *val)
=back
=back
=for hackers
av_push declared in embed.fnc; all in group documented at av.c, line 770
av_push_simple declared in embed.fnc
=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)
SV * Perl_av_shift(pTHX_ AV *av)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 936
=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)
SV ** Perl_av_store(pTHX_ AV *av, SSize_t key, SV *val)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 318
=over 4
=item C
=item C
=item C
=item C
XXXX
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.
Note that, unlike what the name C implies, it returns
the maximum index in the array. This is unlike L, which returns what
you would expect. To get the actual number of elements in an array, use
C>.
=over 3
SSize_t av_top_index( AV *av)
SSize_t av_tindex ( AV *av)
SSize_t AvFILL ( AV* av)
SSize_t av_len ( AV *av)
SSize_t Perl_av_len (pTHX_ AV *av)
=back
=back
=for hackers
av_top_index declared at av.h, line 114; all in group documented at av.c, line 980
av_tindex declared at av.h, line 113
AvFILL declared at av.h, line 112
av_len declared in embed.fnc
=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)
void Perl_av_undef(pTHX_ AV *av)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 694
=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)
void Perl_av_unshift(pTHX_ AV *av, SSize_t num)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 870
=over 4
=item C
Described in L.
=over 3
AvALLOC(AV* av)
=back
=back
=for hackers
Documented at pod/perlguts.pod, line 511
=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
Declared and documented at av.h, line 80
=over 4
=item C
Described under C>
=back
=over 4
=item C
=item C
=item C
XXX
These all increment the reference count of the given SV, which must be an AV.
They are useful when assigning the result into a typed pointer as they avoid
the need to cast the result to the appropriate type.
=over 3
AV * AvREFCNT_inc (AV *av)
AV * AvREFCNT_inc_simple (AV *av)
AV * AvREFCNT_inc_simple_NN(AV *av)
=back
=back
=for hackers
AvREFCNT_inc declared at av.h, line 22; all in group documented at av.h, line 22
AvREFCNT_inc_simple declared at av.h, line 23
AvREFCNT_inc_simple_NN declared at av.h, line 24
=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
(ignoring C) and the variable does not exist then C is
returned.
Perl equivalent: C.
NOTE: the C form is B.
=over 3
AV * get_av( const char *name, I32 flags)
AV * Perl_get_av(pTHX_ const char *name, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 2919
=over 4
=item C
=item C
=item C
=item C
XXXX
These all create a new AV, setting the reference count to 1. If you also know
the initial elements of the array with, see L>.
As background, an array consists of three things:
=over
=item 1.
A data structure containing information about the array as a whole, such as its
size and reference count.
=item 2.
A C language array of pointers to the individual elements. These are treated
as pointers to SVs, so all must be castable to SV*.
=item 3.
The individual elements themselves. These could be, for instance, SVs and/or
AVs and/or HVs, etc.
=back
An empty array need only have the first data structure, and all these functions
create that. They differ in what else they do, as follows:
=over
=item C form
=for comment
'form' above and below is because otherwise have two =items with the same name,
can't link to them.
This does nothing beyond creating the whole-array data structure.
The Perl equivalent is approximately S>
This is useful when the minimum size of the array could be zero (perhaps there
are likely code paths that will entirely skip using it).
If the array does get used, the pointers data structure will need to be
allocated at that time. This will end up being done by L>,
either explicitly:
av_extend(av, len);
or implicitly when the first element is stored:
(void)av_store(av, 0, sv);
Unused array elements are typically initialized by C.
=item C form
This also creates the whole-array data structure, but also mortalises it.
(That is to say, a reference to the AV is added to the C stack.)
=item C form
This effectively does a C followed by also allocating (uninitialized)
space for the pointers array. This is used when you know ahead of time the
likely minimum size of the array. It is more efficient to do this than doing a
plain C followed by an C.
Of course the array can be extended later should it become necessary.
C must be at least 1.
=item C form
This is C, but initializes each pointer in it to NULL. This
gives added safety to guard against them being read before being set.
C must be at least 1.
=back
The following examples all result in an array that can fit four elements
(indexes 0 .. 3):
AV *av = newAV();
av_extend(av, 3);
AV *av = newAV_alloc_x(4);
AV *av = newAV_alloc_xz(4);
In contrast, the following examples allocate an array that is only guaranteed
to fit one element without extending:
AV *av = newAV_alloc_x(1);
AV *av = newAV_alloc_xz(1);
=over 3
AV * newAV ()
AV * Perl_newAV (pTHX)
AV * newAV_mortal ()
AV * newAV_alloc_x (SSize_t size)
AV * newAV_alloc_xz(SSize_t size)
=back
=back
=for hackers
newAV declared in embed.fnc; all in group documented at av.h, line 136
newAV_mortal declared in embed.fnc
newAV_alloc_x declared in embed.fnc
newAV_alloc_xz declared in embed.fnc
=over 4
=item C
X
Creates a new AV and populates it with values copied from an existing AV. The
new AV will have a reference count of 1, and will contain newly created SVs
copied from the original SV. The original source will remain unchanged.
Perl equivalent: C
=over 3
AV * newAVav( AV *oav)
AV * Perl_newAVav(pTHX_ AV *oav)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 511
=over 4
=item C
X
Creates a new AV and populates it with keys and values copied from an existing
HV. The new AV will have a reference count of 1, and will contain newly
created SVs copied from the original HV. The original source will remain
unchanged.
Perl equivalent: C
=over 3
AV * newAVhv( HV *ohv)
AV * Perl_newAVhv(pTHX_ HV *ohv)
=back
=back
=for hackers
Declared in embed.fnc; documented at av.c, line 562
=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
Declared and documented at av.h, line 69
=head1 Callback Functions
XXXXX
X
=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
SSize_t call_argv( const char *sub_name, I32 flags,
char **argv)
SSize_t Perl_call_argv(pTHX_ const char *sub_name, I32 flags,
char **argv)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3037
=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
SSize_t call_method( const char *methname, I32 flags)
SSize_t Perl_call_method(pTHX_ const char *methname, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3111
=over 4
=item C
X
Performs a callback to the specified Perl sub. See L.
NOTE: the C form is B.
=over 3
SSize_t call_pv( const char *sub_name, I32 flags)
SSize_t Perl_call_pv(pTHX_ const char *sub_name, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3093
=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
SSize_t call_sv( SV *sv, I32 flags)
SSize_t Perl_call_sv(pTHX_ SV *sv, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3138
=over 4
=item C
=item C
Described in L.
=back
=for hackers
DESTRUCTORFUNC_NOCONTEXT_t all in group documented at pod/perlguts.pod, line 2045
DESTRUCTORFUNC_t
=over 4
=item C
X
Opening bracket on a callback. See C> and L.
=over 3
ENTER;
=back
=back
=for hackers
Declared and documented at scope.h, line 97
=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
Declared and documented at scope.h, line 103
=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)
SV * Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3466
=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.
By default the code is compiled and executed with the default hints,
such as strict and features. Set C in flags to use the
current hints from C.
NOTE: the C form is B.
=over 3
SSize_t eval_sv( SV *sv, I32 flags)
SSize_t Perl_eval_sv(pTHX_ SV *sv, I32 flags)
=back
=back
=for hackers
Declared in embed.fnc; documented at perl.c, line 3319
=over 4
=item C
X
Closing bracket for temporaries on a callback. See C> and
L.
=over 3
FREETMPS;
=back
=back
=for hackers
Declared and documented at scope.h, line 93
=over 4
=item C
=item C
=item C
=item C
=item C
=item C
=item C
Described in L.
=back
=for hackers
G_DISCARD all in group documented at pod/perlcall.pod, line 233
G_EVAL
G_KEEPERR
G_LIST
G_NOARGS
G_SCALAR
G_VOID
=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
Declared and documented at op.h, line 94
=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
Declared and documented at op.h, line 89
=over 4
=item C
X
Returns non-zero if the sub calling this function is being called in an lvalue
context. Returns 0 otherwise.
=over 3
I32 is_lvalue_sub()
I32 Perl_is_lvalue_sub(pTHX)
=back
=back
=for hackers
Declared in embed.fnc; documented at pp_ctl.c, line 1585
=over 4
=item C
X
Closing bracket on a callback. See C> and L.
=over 3
LEAVE;
=back
=back
=for hackers
Declared and documented at scope.h, line 100
=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
Declared and documented at scope.h, line 108
=over 4
=item C
X
This function arranges for either a Perl code reference, or a C function
reference to be called at the B.
The C argument determines the type of function that will be
called. If it is C it is assumed to be a reference to a CV and
will arrange for the coderef to be called. If it is not SvROK() then it
is assumed to be a C which is C whose value is a pointer
to a C function of type C created using C.
Either way the C parameter will be provided to the callback as a
parameter, although the rules for doing so differ between the Perl and
C mode. Normally this function is only used directly for the Perl case
and the wrapper C is used for the C function case.
When operating in Perl callback mode the C parameter may be NULL
in which case the code reference is called with no arguments, otherwise
if it is an AV (SvTYPE(args) == SVt_PVAV) then the contents of the AV
will be used as the arguments to the code reference, and if it is any
other type then the C SV will be provided as a single argument to
the code reference.
When operating in a C callback mode the C parameter will be passed
directly to the C function as a C pointer. No additional
processing of the argument will be performed, and it is the callers
responsibility to free the C parameter if necessary.
Be aware that there is a significant difference in timing between the
I and the I. If you are looking for a mechanism to trigger a function at the
end of the B you should look at
L> instead of this function.
=over 3
void mortal_destructor_sv( SV *coderef, SV *args)
void Perl_mortal_destructor_sv(pTHX_ SV *coderef, SV *args)
=back
=back
=for hackers
Declared in embed.fnc; documented at scope.c, line 1873
=over 4
=item C
=item C
Described in L.
=over 3
MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
MORTALSVFUNC_X (SVFUNC_t f, SV *sv)
=back
=back
=for hackers
MORTALDESTRUCTOR_SV all in group documented at pod/perlguts.pod, line 2088
MORTALSVFUNC_X
=over 4
=item C
Described in L.
=back
=for hackers
Documented at pod/perlcall.pod, line 1011
=over 4
=item C
=item C
XX
These each arrange for the value of the array element C to be restored
at the end of the enclosing I.
In C, the SV at C**sptr> will be replaced by a new C
scalar. That scalar will inherit any magic from the original C,
and any 'set' magic will be processed.
In C, C being set in C causes
the function to forgo all that: the scalar at C is untouched.
If C is not set, the SV at C**sptr> will be replaced by a
new C scalar. That scalar will inherit any magic from the original
C. Any 'set' magic will be processed if and only if C
is set in in C.
=over 3
void save_aelem ( AV *av, SSize_t idx, SV **sptr)
void save_aelem_flags( AV *av, SSize_t idx, SV **sptr,
const U32 flags)
void Perl_save_aelem_flags(pTHX_ AV *av, SSize_t idx, SV **sptr,
const U32 flags)
=back
=back
=for hackers
save_aelem declared in embed.fnc; all in group documented at scope.c, line 940
save_aelem_flags declared in embed.fnc
=over 4
=item C
=item C
=item C
Described in L.
=over 3
void save_aptr( AV **aptr)
void Perl_save_aptr(pTHX_ AV **aptr)
AV * save_ary ( GV *gv)
AV * Perl_save_ary (pTHX_ GV *gv)
HV * save_hash( GV *gv)
HV * Perl_save_hash(pTHX_ GV *gv)
=back
=back
=for hackers
save_aptr declared in embed.fnc; all in group documented at pod/perlguts.pod, line 2144
save_ary declared in embed.fnc
save_hash declared in embed.fnc
=over 4
=item C
=item C
XX
These each arrange for the value of the hash element (in Perlish terms)
C to be restored at the end of the enclosing I.
In C, the SV at C**sptr> will be replaced by a new C
scalar. That scalar will inherit any magic from the original C,
and any 'set' magic will be processed.
In C, C being set in C causes
the function to forgo all that: the scalar at C is untouched.
If C is not set, the SV at C**sptr> will be replaced by a
new C scalar. That scalar will inherit any magic from the original
C. Any 'set' magic will be processed if and only if C
is set in in C.
=over 3
void save_helem ( HV *hv, SV *key, SV **sptr)
void save_helem_flags( HV *hv, SV *key, SV **sptr,
const U32 flags)
void Perl_save_helem_flags(pTHX_ HV *hv, SV *key, SV **sptr,
const U32 flags)
=back
=back
=for hackers
save_helem declared in embed.fnc; all in group documented at scope.c, line 993
save_helem_flags declared in embed.fnc
=over 4
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
=item C
Described in L.
=over 3
void save_hptr ( HV **hptr)
void Perl_save_hptr (pTHX_ HV **hptr)
void save_item ( SV *item)
void Perl_save_item (pTHX_ SV *item)
SV * save_scalar ( GV *gv)
SV * Perl_save_scalar (pTHX_ GV *gv)
SV * save_svref ( SV **sptr)
SV * Perl_save_svref (pTHX_ SV **sptr)
SAVEBOOL ( bool i)
SAVEDELETE ( HV * hv, char * key,
I32 length)
SAVEDESTRUCTOR ( DESTRUCTORFUNC_NOCONTEXT_t f,
void *p)
SAVEDESTRUCTOR_X( DESTRUCTORFUNC_t f, void *p)
SAVEFREEOP ( OP *op)
SAVEFREEPV ( char *pv)
SAVEFREERCPV ( char *pv)
SAVEFREESV ( SV* sv)
SAVEGENERICSV ( char **psv)
SAVEINT ( int i)
SAVEIV ( IV i)
SAVEI8 ( I8 i)
SAVEI16 ( I16 i)
SAVEI32 ( I32 i)
SAVEMORTALIZESV ( SV* sv)
SAVEPPTR ( char * p)
SAVERCPV ( char *pv)
SAVESPTR ( SV * s)
SAVESTACK_POS ()
SAVESTRLEN ( STRLEN i)
=back
=back
=for hackers
save_hptr declared in embed.fnc; all in group documented at pod/perlguts.pod, line 2145
save_item declared in embed.fnc
save_scalar declared in embed.fnc
save_svref declared in embed.fnc
SAVEBOOL
SAVEDELETE
SAVEDESTRUCTOR
SAVEDESTRUCTOR_X
SAVEFREEOP
SAVEFREEPV
SAVEFREERCPV
SAVEFREESV
SAVEGENERICSV
SAVEINT
SAVEIV
SAVEI8
SAVEI16
SAVEI32
SAVEMORTALIZESV
SAVEPPTR
SAVERCPV
SAVESPTR
SAVESTACK_POS
SAVESTRLEN
=over 4
=item C
X
Opening bracket for temporaries on a callback. See C> and
L.
=over 3
SAVETMPS;
=back
=back
=for hackers
Declared and documented at scope.h, line 89
=head1 Casting
=over 4
=item C