perlapi.pod

MSYS在windows下模拟了一个类unix的终端

=head1 NAME

perlapi - autogenerated documentation for the perl public API

=head1 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.  The interfaces of any functions that 
are not listed here are subject to change without notice.  For this reason,
blindly using functions listed in proto.h is to be avoided when writing
extensions.

Note that all Perl API global variables must be referenced with the C<PL_>
prefix.  Some macros are provided for compatibility with the older,
unadorned names, but this support may be disabled in a future release.

The listing is alphabetical, case insensitive.

=over 8

=item AvFILL

Same as C<av_len()>.  Deprecated, use C<av_len()> instead.

	int	AvFILL(AV* av)

=for hackers
Found in file av.h

=item av_clear

Clears an array, making it empty.  Does not free the memory used by the
array itself.

	void	av_clear(AV* ar)

=for hackers
Found in file av.c

=item av_delete

Deletes the element indexed by C<key> from the array.  Returns the
deleted element. C<flags> is currently ignored.

	SV*	av_delete(AV* ar, I32 key, I32 flags)

=for hackers
Found in file av.c

=item av_exists

Returns true if the element indexed by C<key> has been initialized.

This relies on the fact that uninitialized array elements are set to
C<&PL_sv_undef>.

	bool	av_exists(AV* ar, I32 key)

=for hackers
Found in file av.c

=item av_extend

Pre-extend an array.  The C<key> is the index to which the array should be
extended.

	void	av_extend(AV* ar, I32 key)

=for hackers
Found in file av.c

=item av_fetch

Returns the SV at the specified index in the array.  The C<key> is the
index.  If C<lval> is set then the fetch will be part of a store.  Check
that the return value is non-null before dereferencing it to a C<SV*>.

See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
more information on how to use this function on tied arrays. 

	SV**	av_fetch(AV* ar, I32 key, I32 lval)

=for hackers
Found in file av.c

=item av_fill

Ensure than an array has a given number of elements, equivalent to
Perl's C<$#array = $fill;>.

	void	av_fill(AV* ar, I32 fill)

=for hackers
Found in file av.c

=item av_len

Returns the highest index in the array.  Returns -1 if the array is
empty.

	I32	av_len(AV* ar)

=for hackers
Found in file av.c

=item av_make

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 av_make.  The new AV
will have a reference count of 1.

	AV*	av_make(I32 size, SV** svp)

=for hackers
Found in file av.c

=item av_pop

Pops an SV off the end of the array.  Returns C<&PL_sv_undef> if the array
is empty.

	SV*	av_pop(AV* ar)

=for hackers
Found in file av.c

=item av_push

Pushes an SV onto the end of the array.  The array will grow automatically
to accommodate the addition.

	void	av_push(AV* ar, SV* val)

=for hackers
Found in file av.c

=item av_shift

Shifts an SV off the beginning of the array.

	SV*	av_shift(AV* ar)

=for hackers
Found in file av.c

=item av_store

Stores an SV in an array.  The array index is specified as C<key>.  The
return value will be NULL 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 original C<SV*>.  Note
that the caller is responsible for suitably incrementing the reference
count of C<val> before the call, and decrementing it if the function
returned NULL.

See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
more information on how to use this function on tied arrays.

	SV**	av_store(AV* ar, I32 key, SV* val)

=for hackers
Found in file av.c

=item av_undef

Undefines the array.  Frees the memory used by the array itself.

	void	av_undef(AV* ar)

=for hackers
Found in file av.c

=item av_unshift

Unshift the given number of C<undef> values onto the beginning of the
array.  The array will grow automatically to accommodate the addition.  You
must then use C<av_store> to assign values to these new elements.

	void	av_unshift(AV* ar, I32 num)

=for hackers
Found in file av.c

=item bytes_from_utf8

Converts a string C<s> of length C<len> from UTF8 into byte encoding.
Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
the newly-created string, and updates C<len> to contain the new
length.  Returns the original string if no conversion occurs, C<len>
is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
0 if C<s> is converted or contains all 7bit characters.

NOTE: this function is experimental and may change or be
removed without notice.

	U8*	bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)

=for hackers
Found in file utf8.c

=item bytes_to_utf8

Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
Returns a pointer to the newly-created string, and sets C<len> to
reflect the new length.

NOTE: this function is experimental and may change or be
removed without notice.

	U8*	bytes_to_utf8(U8 *s, STRLEN *len)

=for hackers
Found in file utf8.c

=item call_argv

Performs a callback to the specified Perl sub.  See L<perlcall>.

NOTE: the perl_ form of this function is deprecated.

	I32	call_argv(const char* sub_name, I32 flags, char** argv)

=for hackers
Found in file perl.c

=item call_method

Performs a callback to the specified Perl method.  The blessed object must
be on the stack.  See L<perlcall>.

NOTE: the perl_ form of this function is deprecated.

	I32	call_method(const char* methname, I32 flags)

=for hackers
Found in file perl.c

=item call_pv

Performs a callback to the specified Perl sub.  See L<perlcall>.

NOTE: the perl_ form of this function is deprecated.

	I32	call_pv(const char* sub_name, I32 flags)

=for hackers
Found in file perl.c

=item call_sv

Performs a callback to the Perl sub whose name is in the SV.  See
L<perlcall>.

NOTE: the perl_ form of this function is deprecated.

	I32	call_sv(SV* sv, I32 flags)

=for hackers
Found in file perl.c

=item CLASS

Variable which is setup by C<xsubpp> to indicate the 
class name for a C++ XS constructor.  This is always a C<char*>.  See C<THIS>.

	char*	CLASS

=for hackers
Found in file XSUB.h

=item Copy

The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
the type.  May fail on overlapping copies.  See also C<Move>.

	void	Copy(void* src, void* dest, int nitems, type)

=for hackers
Found in file handy.h

=item croak

This is the XSUB-writer's interface to Perl's C<die> function.
Normally use this function the same way you use the C C<printf>
function.  See C<warn>.

If you want to throw an exception object, assign the object to
C<$@> and then pass C<Nullch> to croak():

   errsv = get_sv("@", TRUE);
   sv_setsv(errsv, exception_object);
   croak(Nullch);

	void	croak(const char* pat, ...)

=for hackers
Found in file util.c

=item CvSTASH

Returns the stash of the CV.

	HV*	CvSTASH(CV* cv)

=for hackers
Found in file cv.h

=item dMARK

Declare a stack marker variable, C<mark>, for the XSUB.  See C<MARK> and
C<dORIGMARK>.

		dMARK;

=for hackers
Found in file pp.h

=item dORIGMARK

Saves the original stack mark for the XSUB.  See C<ORIGMARK>.

		dORIGMARK;

=for hackers
Found in file pp.h

=item dSP

Declares a local copy of perl's stack pointer for the XSUB, available via
the C<SP> macro.  See C<SP>.

		dSP;

=for hackers
Found in file pp.h

=item dXSARGS

Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.  This
is usually handled automatically by C<xsubpp>.  Declares the C<items>
variable to indicate the number of items on the stack.

		dXSARGS;

=for hackers
Found in file XSUB.h

=item dXSI32

Sets up the C<ix> variable for an XSUB which has aliases.  This is usually
handled automatically by C<xsubpp>.

		dXSI32;

=for hackers
Found in file XSUB.h

=item ENTER

Opening bracket on a callback.  See C<LEAVE> and L<perlcall>.

		ENTER;

=for hackers
Found in file scope.h

=item eval_pv

Tells Perl to C<eval> the given string and return an SV* result.

NOTE: the perl_ form of this function is deprecated.

	SV*	eval_pv(const char* p, I32 croak_on_error)

=for hackers
Found in file perl.c

=item eval_sv

Tells Perl to C<eval> the string in the SV.

NOTE: the perl_ form of this function is deprecated.

	I32	eval_sv(SV* sv, I32 flags)

=for hackers
Found in file perl.c

=item EXTEND

Used to extend the argument stack for an XSUB's return values. Once
used, guarantees that there is room for at least C<nitems> to be pushed
onto the stack.

	void	EXTEND(SP, int nitems)

=for hackers
Found in file pp.h

=item fbm_compile

Analyses the string in order to make fast searches on it using fbm_instr()
-- the Boyer-Moore algorithm.

	void	fbm_compile(SV* sv, U32 flags)

=for hackers
Found in file util.c

=item fbm_instr

Returns the location of the SV in the string delimited by C<str> and
C<strend>.  It returns C<Nullch> if the string can't be found.  The C<sv>
does not have to be fbm_compiled, but the search will not be as fast
then.

	char*	fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)

=for hackers
Found in file util.c

=item FREETMPS

Closing bracket for temporaries on a callback.  See C<SAVETMPS> and
L<perlcall>.

		FREETMPS;

=for hackers
Found in file scope.h

=item get_av

Returns the AV of the specified Perl array.  If C<create> is set and the
Perl variable does not exist then it will be created.  If C<create> is not
set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

	AV*	get_av(const char* name, I32 create)

=for hackers
Found in file perl.c

=item get_cv

Returns the CV of the specified Perl subroutine.  If C<create> is set and
the Perl subroutine does not exist then it will be declared (which has the
same effect as saying C<sub name;>).  If C<create> is not set and the
subroutine does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

	CV*	get_cv(const char* name, I32 create)

=for hackers
Found in file perl.c

=item get_hv

Returns the HV of the specified Perl hash.  If C<create> is set and the
Perl variable does not exist then it will be created.  If C<create> is not
set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

	HV*	get_hv(const char* name, I32 create)

=for hackers
Found in file perl.c

=item get_sv

Returns the SV of the specified Perl scalar.  If C<create> is set and the
Perl variable does not exist then it will be created.  If C<create> is not
set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

	SV*	get_sv(const char* name, I32 create)

=for hackers
Found in file perl.c

=item GIMME

A backward-compatible version of C<GIMME_V> which can only return
C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
Deprecated.  Use C<GIMME_V> instead.

	U32	GIMME

=for hackers
Found in file op.h

=item GIMME_V

The XSUB-writer's equivalent to Perl's C<wantarray>.  Returns C<G_VOID>,
C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
respectively.

	U32	GIMME_V

=for hackers
Found in file op.h

=item GvSV

Return the SV from the GV.

	SV*	GvSV(GV* gv)

=for hackers
Found in file gv.h

=item gv_fetchmeth

Returns the glob with the given C<name> and a defined subroutine or
C<NULL>.  The glob lives in the given C<stash>, or in the stashes
accessible via @ISA and @UNIVERSAL.

The argument C<level> should be either 0 or -1.  If C<level==0>, as a
side-effect creates a glob with the given C<name> in the given C<stash>
which in the case of success contains an alias for the subroutine, and sets
up caching info for this glob.  Similarly for all the searched stashes.

This function grants C<"SUPER"> token as a postfix of the stash name. The
GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
visible to Perl code.  So when calling C<call_sv>, you should not use
the GV directly; instead, you should use the method's CV, which can be
obtained from the GV with the C<GvCV> macro.

	GV*	gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)

=for hackers
Found in file gv.c

=item gv_fetchmethod

See L<gv_fetchmethod_autoload>.

	GV*	gv_fetchmethod(HV* stash, const char* name)

=for hackers
Found in file gv.c

=item gv_fetchmethod_autoload

Returns the glob which contains the subroutine to call to invoke the method
on the C<stash>.  In fact in the presence of autoloading this may be the
glob for "AUTOLOAD".  In this case the corresponding variable $AUTOLOAD is
already setup.

The third parameter of C<gv_fetchmethod_autoload> determines whether
AUTOLOAD lookup is performed if the given method is not present: non-zero
means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
with a non-zero C<autoload> parameter.

These functions grant C<"SUPER"> token as a prefix of the method name. Note
that if you want to keep the returned glob for a long time, you need to
check for it being "AUTOLOAD", since at the later time the call may load a
different subroutine due to $AUTOLOAD changing its value. Use the glob
created via a side effect to do this.

These functions have the same side-effects and as C<gv_fetchmeth> with
C<level==0>.  C<name> should be writable if contains C<':'> or C<'
''>. The warning against passing the GV returned by C<gv_fetchmeth> to
C<call_sv> apply equally to these functions.

	GV*	gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)

=for hackers
Found in file gv.c

=item gv_stashpv

Returns a pointer to the stash for a specified package.  C<name> should
be a valid UTF-8 string.  If C<create> is set then the package will be
created if it does not already exist.  If C<create> is not set and the
package does not exist then NULL is returned.

	HV*	gv_stashpv(const char* name, I32 create)

=for hackers
Found in file gv.c

=item gv_stashsv

Returns a pointer to the stash for a specified package, which must be a
valid UTF-8 string.  See C<gv_stashpv>.

	HV*	gv_stashsv(SV* sv, I32 create)

=for hackers
Found in file gv.c

=item G_ARRAY

Used to indicate list context.  See C<GIMME_V>, C<GIMME> and
L<perlcall>.

=for hackers
Found in file cop.h

=item G_DISCARD

Indicates that arguments returned from a callback should be discarded.  See
L<perlcall>.

=for hackers
Found in file cop.h

=item G_EVAL

Used to force a Perl C<eval> wrapper around a callback.  See
L<perlcall>.

=for hackers
Found in file cop.h

=item G_NOARGS

Indicates that no arguments are being sent to a callback.  See
L<perlcall>.

=for hackers
Found in file cop.h

=item G_SCALAR

Used to indicate scalar context.  See C<GIMME_V>, C<GIMME>, and
L<perlcall>.

=for hackers
Found in file cop.h

=item G_VOID

Used to indicate void context.  See C<GIMME_V> and L<perlcall>.

=for hackers