perlapi.pod

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

Found in file cop.h

=item HEf_SVKEY

This flag, used in the length slot of hash entries and magic structures,
specifies the structure contains a C<SV*> pointer where a C<char*> pointer
is to be expected. (For information only--not to be used).

=for hackers
Found in file hv.h

=item HeHASH

Returns the computed hash stored in the hash entry.

	U32	HeHASH(HE* he)

=for hackers
Found in file hv.h

=item HeKEY

Returns the actual pointer stored in the key slot of the hash entry. The
pointer may be either C<char*> or C<SV*>, depending on the value of
C<HeKLEN()>.  Can be assigned to.  The C<HePV()> or C<HeSVKEY()> macros are
usually preferable for finding the value of a key.

	void*	HeKEY(HE* he)

=for hackers
Found in file hv.h

=item HeKLEN

If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
holds an C<SV*> key.  Otherwise, holds the actual length of the key.  Can
be assigned to. The C<HePV()> macro is usually preferable for finding key
lengths.

	STRLEN	HeKLEN(HE* he)

=for hackers
Found in file hv.h

=item HePV

Returns the key slot of the hash entry as a C<char*> value, doing any
necessary dereferencing of possibly C<SV*> keys.  The length of the string
is placed in C<len> (this is a macro, so do I<not> use C<&len>).  If you do
not care about what the length of the key is, you may use the global
variable C<PL_na>, though this is rather less efficient than using a local
variable.  Remember though, that hash keys in perl are free to contain
embedded nulls, so using C<strlen()> or similar is not a good way to find
the length of hash keys. This is very similar to the C<SvPV()> macro
described elsewhere in this document.

	char*	HePV(HE* he, STRLEN len)

=for hackers
Found in file hv.h

=item HeSVKEY

Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
contain an C<SV*> key.

	SV*	HeSVKEY(HE* he)

=for hackers
Found in file hv.h

=item HeSVKEY_force

Returns the key as an C<SV*>.  Will create and return a temporary mortal
C<SV*> if the hash entry contains only a C<char*> key.

	SV*	HeSVKEY_force(HE* he)

=for hackers
Found in file hv.h

=item HeSVKEY_set

Sets the key to a given C<SV*>, taking care to set the appropriate flags to
indicate the presence of an C<SV*> key, and returns the same
C<SV*>.

	SV*	HeSVKEY_set(HE* he, SV* sv)

=for hackers
Found in file hv.h

=item HeVAL

Returns the value slot (type C<SV*>) stored in the hash entry.

	SV*	HeVAL(HE* he)

=for hackers
Found in file hv.h

=item HvNAME

Returns the package name of a stash.  See C<SvSTASH>, C<CvSTASH>.

	char*	HvNAME(HV* stash)

=for hackers
Found in file hv.h

=item hv_clear

Clears a hash, making it empty.

	void	hv_clear(HV* tb)

=for hackers
Found in file hv.c

=item hv_delete

Deletes a key/value pair in the hash.  The value SV is removed from the
hash and returned to the caller.  The C<klen> is the length of the key. 
The C<flags> value will normally be zero; if set to G_DISCARD then NULL
will be returned.

	SV*	hv_delete(HV* tb, const char* key, U32 klen, I32 flags)

=for hackers
Found in file hv.c

=item hv_delete_ent

Deletes a key/value pair in the hash.  The value SV is removed from the
hash and returned to the caller.  The C<flags> value will normally be zero;
if set to G_DISCARD then NULL will be returned.  C<hash> can be a valid
precomputed hash value, or 0 to ask for it to be computed.

	SV*	hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)

=for hackers
Found in file hv.c

=item hv_exists

Returns a boolean indicating whether the specified hash key exists.  The
C<klen> is the length of the key.

	bool	hv_exists(HV* tb, const char* key, U32 klen)

=for hackers
Found in file hv.c

=item hv_exists_ent

Returns a boolean indicating whether the specified hash key exists. C<hash>
can be a valid precomputed hash value, or 0 to ask for it to be
computed.

	bool	hv_exists_ent(HV* tb, SV* key, U32 hash)

=for hackers
Found in file hv.c

=item hv_fetch

Returns the SV which corresponds to the specified key in the hash.  The
C<klen> is the length of the key.  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 hashes.

	SV**	hv_fetch(HV* tb, const char* key, U32 klen, I32 lval)

=for hackers
Found in file hv.c

=item hv_fetch_ent

Returns the hash entry which corresponds to the specified key in the hash.
C<hash> must be a valid precomputed hash number for the given C<key>, or 0
if you want the function to compute it.  IF C<lval> is set then the fetch
will be part of a store.  Make sure the return value is non-null before
accessing it.  The return value when C<tb> is a tied hash is a pointer to a
static location, so be sure to make a copy of the structure if you need to
store it somewhere. 

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

	HE*	hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)

=for hackers
Found in file hv.c

=item hv_iterinit

Prepares a starting point to traverse a hash table.  Returns the number of
keys in the hash (i.e. the same as C<HvKEYS(tb)>).  The return value is
currently only meaningful for hashes without tie magic. 

NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
hash buckets that happen to be in use.  If you still need that esoteric
value, you can get it through the macro C<HvFILL(tb)>.

	I32	hv_iterinit(HV* tb)

=for hackers
Found in file hv.c

=item hv_iterkey

Returns the key from the current position of the hash iterator.  See
C<hv_iterinit>.

	char*	hv_iterkey(HE* entry, I32* retlen)

=for hackers
Found in file hv.c

=item hv_iterkeysv

Returns the key as an C<SV*> from the current position of the hash
iterator.  The return value will always be a mortal copy of the key.  Also
see C<hv_iterinit>.

	SV*	hv_iterkeysv(HE* entry)

=for hackers
Found in file hv.c

=item hv_iternext

Returns entries from a hash iterator.  See C<hv_iterinit>.

	HE*	hv_iternext(HV* tb)

=for hackers
Found in file hv.c

=item hv_iternextsv

Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
operation.

	SV*	hv_iternextsv(HV* hv, char** key, I32* retlen)

=for hackers
Found in file hv.c

=item hv_iterval

Returns the value from the current position of the hash iterator.  See
C<hv_iterkey>.

	SV*	hv_iterval(HV* tb, HE* entry)

=for hackers
Found in file hv.c

=item hv_magic

Adds magic to a hash.  See C<sv_magic>.

	void	hv_magic(HV* hv, GV* gv, int how)

=for hackers
Found in file hv.c

=item hv_store

Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
the length of the key.  The C<hash> parameter is the precomputed hash
value; if it is zero then Perl will compute it.  The return value will be
NULL if the operation failed or if the value did not need to be actually
stored within the hash (as in the case of tied hashes).  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 hashes.

	SV**	hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash)

=for hackers
Found in file hv.c

=item hv_store_ent

Stores C<val> in a hash.  The hash key is specified as C<key>.  The C<hash>
parameter is the precomputed hash value; if it is zero then Perl will
compute it.  The return value is the new hash entry so created.  It will be
NULL if the operation failed or if the value did not need to be actually
stored within the hash (as in the case of tied hashes).  Otherwise the
contents of the return value can be accessed using the C<He???> macros
described here.  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 hashes.

	HE*	hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)

=for hackers
Found in file hv.c

=item hv_undef

Undefines the hash.

	void	hv_undef(HV* tb)

=for hackers
Found in file hv.c

=item isALNUM

Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
character (including underscore) or digit.

	bool	isALNUM(char ch)

=for hackers
Found in file handy.h

=item isALPHA

Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
character.

	bool	isALPHA(char ch)

=for hackers
Found in file handy.h

=item isDIGIT

Returns a boolean indicating whether the C C<char> is an ASCII
digit.

	bool	isDIGIT(char ch)

=for hackers
Found in file handy.h

=item isLOWER

Returns a boolean indicating whether the C C<char> is a lowercase
character.

	bool	isLOWER(char ch)

=for hackers
Found in file handy.h

=item isSPACE

Returns a boolean indicating whether the C C<char> is whitespace.

	bool	isSPACE(char ch)

=for hackers
Found in file handy.h

=item isUPPER

Returns a boolean indicating whether the C C<char> is an uppercase
character.

	bool	isUPPER(char ch)

=for hackers
Found in file handy.h

=item is_utf8_char

Tests if some arbitrary number of bytes begins in a valid UTF-8 character.
The actual number of bytes in the UTF-8 character will be returned if it
is valid, otherwise 0. 
 
	STRLEN	is_utf8_char(U8 *p)

=for hackers
Found in file utf8.c

=item is_utf8_string

Returns true if first C<len> bytes of the given string form valid a UTF8
string, false otherwise.

	bool	is_utf8_string(U8 *s, STRLEN len)

=for hackers
Found in file utf8.c

=item items

Variable which is setup by C<xsubpp> to indicate the number of 
items on the stack.  See L<perlxs/"Variable-length Parameter Lists">.

	I32	items

=for hackers
Found in file XSUB.h

=item ix

Variable which is setup by C<xsubpp> to indicate which of an 
XSUB's aliases was used to invoke it.  See L<perlxs/"The ALIAS: Keyword">.

	I32	ix

=for hackers
Found in file XSUB.h

=item LEAVE

Closing bracket on a callback.  See C<ENTER> and L<perlcall>.

		LEAVE;

=for hackers
Found in file scope.h

=item looks_like_number

Test if an the content of an SV looks like a number (or is a
number).

	I32	looks_like_number(SV* sv)

=for hackers
Found in file sv.c

=item MARK

Stack marker variable for the XSUB.  See C<dMARK>.

=for hackers
Found in file pp.h

=item mg_clear

Clear something magical that the SV represents.  See C<sv_magic>.

	int	mg_clear(SV* sv)

=for hackers
Found in file mg.c

=item mg_copy

Copies the magic from one SV to another.  See C<sv_magic>.

	int	mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)

=for hackers
Found in file mg.c

=item mg_find

Finds the magic pointer for type matching the SV.  See C<sv_magic>.

	MAGIC*	mg_find(SV* sv, int type)

=for hackers
Found in file mg.c

=item mg_free

Free any magic storage used by the SV.  See C<sv_magic>.

	int	mg_free(SV* sv)

=for hackers
Found in file mg.c

=item mg_get

Do magic after a value is retrieved from the SV.  See C<sv_magic>.

	int	mg_get(SV* sv)

=for hackers
Found in file mg.c

=item mg_length

Report on the SV's length.  See C<sv_magic>.

	U32	mg_length(SV* sv)

=for hackers
Found in file mg.c

=item mg_magical

Turns on the magical status of an SV.  See C<sv_magic>.

	void	mg_magical(SV* sv)

=for hackers
Found in file mg.c

=item mg_set

Do magic after a value is assigned to the SV.  See C<sv_magic>.

	int	mg_set(SV* sv)

=for hackers
Found in file mg.c

=item Move

The XSUB-writer's interface to the C C<memmove> 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.  Can do overlapping moves.  See also C<Copy>.

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

=for hackers
Found in file handy.h

=item New

The XSUB-writer's interface to the C C<malloc> function.

	void	New(int id, void* ptr, int nitems, type)

=for hackers
Found in file handy.h

=item newAV

Creates a new AV.  The reference count is set to 1.

	AV*	newAV()

=for hackers
Found in file av.c

=item Newc

The XSUB-writer's interface to the C C<malloc> function, with
cast.

	void	Newc(int id, void* ptr, int nitems, type, cast)

=for hackers
Found in file handy.h

=item newCONSTSUB

Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
eligible for inlining at compile-time.

	void	newCONSTSUB(HV* stash, char* name, SV* sv)

=for hackers
Found in file op.c

=item newHV

Creates a new HV.  The reference count is set to 1.

	HV*	newHV()

=for hackers
Found in file hv.c

=item newRV_inc

Creates an RV wrapper for an SV.  The reference count for the original SV is
incremented.

	SV*	newRV_inc(SV* sv)

=for hackers
Found in file sv.h

=item newRV_noinc

Creates an RV wrapper for an SV.  The reference count for the original
SV is B<not> incremented.

	SV*	newRV_noinc(SV *sv)

=for hackers
Found in file sv.c

=item NEWSV

Creates a new SV.  A non-zero C<len> parameter indicates the number of
bytes of preallocated string space the SV should have.  An extra byte for a
tailing NUL is also reserved.  (SvPOK is not set for the SV even if string
space is allocated.)  The reference count for the new SV is set to 1.
C<id> is an integer id between 0 and 1299 (used to identify leaks).

	SV*	NEWSV(int id, STRLEN len)

=for hackers
Found in file handy.h

=item newSViv

Creates a new SV and copies an integer into it.  The reference count for the
SV is set to 1.

	SV*	newSViv(IV i)

=for hackers
Found in file sv.c

=item newSVnv

Creates a new SV and copies a floating point value into it.
The reference count for the SV is set to 1.

	SV*	newSVnv(NV n)

=for hackers
Found in file sv.c

=item newSVpv

Creates a new SV and copies a string into it.  The reference count for the
SV is set to 1.  If C<len> is zero, Perl will compute the length using
strlen().  For efficiency, consider using C<newSVpvn> instead.

	SV*	newSVpv(const char* s, STRLEN len)

=for hackers
Found in file sv.c

=item newSVpvf

Creates a new SV an initialize it with the string formatted like
C<sprintf>.