integrate cfgperl changes#6231..6240 into mainline
[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod
index 19ab71f..f274641 100644 (file)
@@ -25,6 +25,9 @@ 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
@@ -32,6 +35,9 @@ array itself.
 
        void    av_clear(AV* ar)
 
+=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
@@ -39,6 +45,9 @@ 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
@@ -50,6 +59,9 @@ 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_len
 
 Returns the highest index in the array.  Returns -1 if the array is
@@ -57,6 +69,9 @@ 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
@@ -65,6 +80,9 @@ 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
@@ -72,6 +90,9 @@ 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
@@ -79,12 +100,18 @@ 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
@@ -100,12 +127,18 @@ 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
@@ -114,6 +147,19 @@ 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_to_utf8
+
+Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
+Returns a pointer to the newly-created string.
+
+       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>.
@@ -122,6 +168,9 @@ 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
@@ -131,6 +180,9 @@ 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>.
@@ -139,6 +191,9 @@ 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
@@ -148,6 +203,9 @@ 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 
@@ -155,6 +213,9 @@ 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
@@ -163,6 +224,9 @@ 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.
@@ -178,12 +242,18 @@ C<$@> and then pass C<Nullch> to croak():
 
        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
@@ -191,12 +261,18 @@ 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
@@ -204,6 +280,9 @@ 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
@@ -212,6 +291,9 @@ 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
@@ -219,12 +301,18 @@ 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.
@@ -233,6 +321,9 @@ 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.
@@ -241,6 +332,9 @@ 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
@@ -249,6 +343,9 @@ 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()
@@ -256,6 +353,9 @@ Analyses the string in order to make fast searches on it using fbm_instr()
 
        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
@@ -265,6 +365,9 @@ 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
@@ -272,6 +375,9 @@ 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
@@ -282,6 +388,9 @@ 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
@@ -293,6 +402,9 @@ 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
@@ -303,6 +415,9 @@ 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
@@ -313,6 +428,9 @@ 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
@@ -321,6 +439,9 @@ 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>,
@@ -329,12 +450,18 @@ 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
@@ -354,12 +481,18 @@ 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
@@ -386,6 +519,9 @@ 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
@@ -395,6 +531,9 @@ 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
@@ -402,47 +541,74 @@ 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 array 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
+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
@@ -452,6 +618,9 @@ 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
@@ -461,6 +630,9 @@ 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
@@ -475,6 +647,9 @@ 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
@@ -482,6 +657,9 @@ 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
@@ -489,6 +667,9 @@ 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
@@ -497,24 +678,36 @@ 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
@@ -524,6 +717,9 @@ 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
@@ -533,6 +729,9 @@ 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
@@ -540,6 +739,9 @@ 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>
@@ -548,6 +750,9 @@ 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
@@ -560,6 +765,9 @@ 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.
@@ -575,6 +783,9 @@ 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
@@ -587,6 +798,9 @@ 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
@@ -594,6 +808,9 @@ 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
@@ -602,12 +819,18 @@ 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
@@ -615,6 +838,9 @@ 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
@@ -622,12 +848,18 @@ 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
@@ -644,6 +876,9 @@ 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>
@@ -661,12 +896,18 @@ 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
@@ -674,6 +915,9 @@ 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
@@ -681,6 +925,9 @@ 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
@@ -688,6 +935,9 @@ 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
@@ -695,12 +945,18 @@ 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
@@ -708,6 +964,9 @@ character.
 
        bool    isUPPER(char ch)
 
+=for hackers
+Found in file handy.h
+
 =item items
 
 Variable which is setup by C<xsubpp> to indicate the number of 
@@ -715,6 +974,9 @@ 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 
@@ -722,12 +984,18 @@ 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
@@ -735,58 +1003,88 @@ 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
@@ -795,18 +1093,27 @@ 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
@@ -814,6 +1121,9 @@ 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
@@ -821,12 +1131,18 @@ 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
@@ -834,6 +1150,9 @@ 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
@@ -841,6 +1160,9 @@ 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
@@ -851,6 +1173,9 @@ 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
@@ -858,6 +1183,9 @@ 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.
@@ -865,6 +1193,9 @@ 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
@@ -873,6 +1204,9 @@ 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
@@ -880,6 +1214,9 @@ C<sprintf>.
 
        SV*     newSVpvf(const char* pat, ...)
 
+=for hackers
+Found in file sv.c
+
 =item newSVpvn
 
 Creates a new SV and copies a string into it.  The reference count for the
@@ -889,6 +1226,9 @@ C<len> bytes long.
 
        SV*     newSVpvn(const char* s, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item newSVrv
 
 Creates a new SV for the RV, C<rv>, to point to.  If C<rv> is not an RV then
@@ -898,12 +1238,18 @@ reference count is 1.
 
        SV*     newSVrv(SV* rv, const char* classname)
 
+=for hackers
+Found in file sv.c
+
 =item newSVsv
 
 Creates a new SV which is an exact duplicate of the original SV.
 
        SV*     newSVsv(SV* old)
 
+=for hackers
+Found in file sv.c
+
 =item newSVuv
 
 Creates a new SV and copies an unsigned integer into it.
@@ -911,15 +1257,24 @@ The reference count for the SV is set to 1.
 
        SV*     newSVuv(UV u)
 
+=for hackers
+Found in file sv.c
+
 =item newXS
 
 Used by C<xsubpp> to hook up XSUBs as Perl subs.
 
+=for hackers
+Found in file op.c
+
 =item newXSproto
 
 Used by C<xsubpp> to hook up XSUBs as Perl subs.  Adds Perl prototypes to
 the subs.
 
+=for hackers
+Found in file XSUB.h
+
 =item Newz
 
 The XSUB-writer's interface to the C C<malloc> function.  The allocated
@@ -927,66 +1282,105 @@ memory is zeroed with C<memzero>.
 
        void    Newz(int id, void* ptr, int nitems, type)
 
+=for hackers
+Found in file handy.h
+
 =item Nullav
 
 Null AV pointer.
 
+=for hackers
+Found in file av.h
+
 =item Nullch
 
 Null character pointer.
 
+=for hackers
+Found in file handy.h
+
 =item Nullcv
 
 Null CV pointer.
 
+=for hackers
+Found in file cv.h
+
 =item Nullhv
 
 Null HV pointer.
 
+=for hackers
+Found in file hv.h
+
 =item Nullsv
 
 Null SV pointer.
 
+=for hackers
+Found in file handy.h
+
 =item ORIGMARK
 
 The original stack mark for the XSUB.  See C<dORIGMARK>.
 
+=for hackers
+Found in file pp.h
+
 =item perl_alloc
 
 Allocates a new Perl interpreter.  See L<perlembed>.
 
        PerlInterpreter*        perl_alloc()
 
+=for hackers
+Found in file perl.c
+
 =item perl_construct
 
 Initializes a new Perl interpreter.  See L<perlembed>.
 
        void    perl_construct(PerlInterpreter* interp)
 
+=for hackers
+Found in file perl.c
+
 =item perl_destruct
 
 Shuts down a Perl interpreter.  See L<perlembed>.
 
        void    perl_destruct(PerlInterpreter* interp)
 
+=for hackers
+Found in file perl.c
+
 =item perl_free
 
 Releases a Perl interpreter.  See L<perlembed>.
 
        void    perl_free(PerlInterpreter* interp)
 
+=for hackers
+Found in file perl.c
+
 =item perl_parse
 
 Tells a Perl interpreter to parse a Perl script.  See L<perlembed>.
 
        int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
 
+=for hackers
+Found in file perl.c
+
 =item perl_run
 
 Tells a Perl interpreter to run.  See L<perlembed>.
 
        int     perl_run(PerlInterpreter* interp)
 
+=for hackers
+Found in file perl.c
+
 =item PL_DBsingle
 
 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
@@ -997,6 +1391,9 @@ C<PL_DBsub>.
 
        SV *    PL_DBsingle
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_DBsub
 
 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
@@ -1006,6 +1403,9 @@ C<PL_DBsingle>.
 
        GV *    PL_DBsub
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_DBtrace
 
 Trace variable used when Perl is run in debugging mode, with the B<-d>
@@ -1014,12 +1414,18 @@ variable.  See C<PL_DBsingle>.
 
        SV *    PL_DBtrace
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_dowarn
 
 The C variable which corresponds to Perl's $^W warning variable.
 
        bool    PL_dowarn
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_modglobal
 
 C<PL_modglobal> is a general purpose, interpreter global HV for use by 
@@ -1030,6 +1436,9 @@ prefixed by the package name of the extension that owns the data.
 
        HV*     PL_modglobal
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_na
 
 A convenience variable which is typically used with C<SvPV> when one
@@ -1039,6 +1448,9 @@ C<SvPV_nolen> macro.
 
        STRLEN  PL_na
 
+=for hackers
+Found in file thrdvar.h
+
 =item PL_sv_no
 
 This is the C<false> SV.  See C<PL_sv_yes>.  Always refer to this as
@@ -1046,12 +1458,18 @@ C<&PL_sv_no>.
 
        SV      PL_sv_no
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_sv_undef
 
 This is the C<undef> SV.  Always refer to this as C<&PL_sv_undef>.
 
        SV      PL_sv_undef
 
+=for hackers
+Found in file intrpvar.h
+
 =item PL_sv_yes
 
 This is the C<true> SV.  See C<PL_sv_no>.  Always refer to this as
@@ -1059,36 +1477,54 @@ C<&PL_sv_yes>.
 
        SV      PL_sv_yes
 
+=for hackers
+Found in file intrpvar.h
+
 =item POPi
 
 Pops an integer off the stack.
 
        IV      POPi
 
+=for hackers
+Found in file pp.h
+
 =item POPl
 
 Pops a long off the stack.
 
        long    POPl
 
+=for hackers
+Found in file pp.h
+
 =item POPn
 
 Pops a double off the stack.
 
        NV      POPn
 
+=for hackers
+Found in file pp.h
+
 =item POPp
 
 Pops a string off the stack.
 
        char*   POPp
 
+=for hackers
+Found in file pp.h
+
 =item POPs
 
 Pops an SV off the stack.
 
        SV*     POPs
 
+=for hackers
+Found in file pp.h
+
 =item PUSHi
 
 Push an integer onto the stack.  The stack must have room for this element.
@@ -1096,6 +1532,9 @@ Handles 'set' magic.  See C<XPUSHi>.
 
        void    PUSHi(IV iv)
 
+=for hackers
+Found in file pp.h
+
 =item PUSHMARK
 
 Opening bracket for arguments on a callback.  See C<PUTBACK> and
@@ -1103,6 +1542,9 @@ L<perlcall>.
 
                PUSHMARK;
 
+=for hackers
+Found in file pp.h
+
 =item PUSHn
 
 Push a double onto the stack.  The stack must have room for this element.
@@ -1110,6 +1552,9 @@ Handles 'set' magic.  See C<XPUSHn>.
 
        void    PUSHn(NV nv)
 
+=for hackers
+Found in file pp.h
+
 =item PUSHp
 
 Push a string onto the stack.  The stack must have room for this element.
@@ -1118,6 +1563,9 @@ C<XPUSHp>.
 
        void    PUSHp(char* str, STRLEN len)
 
+=for hackers
+Found in file pp.h
+
 =item PUSHs
 
 Push an SV onto the stack.  The stack must have room for this element. 
@@ -1125,6 +1573,9 @@ Does not handle 'set' magic.  See C<XPUSHs>.
 
        void    PUSHs(SV* sv)
 
+=for hackers
+Found in file pp.h
+
 =item PUSHu
 
 Push an unsigned integer onto the stack.  The stack must have room for this
@@ -1132,6 +1583,9 @@ element.  See C<XPUSHu>.
 
        void    PUSHu(UV uv)
 
+=for hackers
+Found in file pp.h
+
 =item PUTBACK
 
 Closing bracket for XSUB arguments.  This is usually handled by C<xsubpp>.
@@ -1139,12 +1593,18 @@ See C<PUSHMARK> and L<perlcall> for other uses.
 
                PUTBACK;
 
+=for hackers
+Found in file pp.h
+
 =item Renew
 
 The XSUB-writer's interface to the C C<realloc> function.
 
        void    Renew(void* ptr, int nitems, type)
 
+=for hackers
+Found in file handy.h
+
 =item Renewc
 
 The XSUB-writer's interface to the C C<realloc> function, with
@@ -1152,6 +1612,9 @@ cast.
 
        void    Renewc(void* ptr, int nitems, type, cast)
 
+=for hackers
+Found in file handy.h
+
 =item require_pv
 
 Tells Perl to C<require> a module.
@@ -1160,6 +1623,9 @@ NOTE: the perl_ form of this function is deprecated.
 
        void    require_pv(const char* pv)
 
+=for hackers
+Found in file perl.c
+
 =item RETVAL
 
 Variable which is setup by C<xsubpp> to hold the return value for an 
@@ -1168,18 +1634,27 @@ L<perlxs/"The RETVAL Variable">.
 
        (whatever)      RETVAL
 
+=for hackers
+Found in file XSUB.h
+
 =item Safefree
 
 The XSUB-writer's interface to the C C<free> function.
 
        void    Safefree(void* src, void* dest, int nitems, type)
 
+=for hackers
+Found in file handy.h
+
 =item savepv
 
 Copy a string to a safe spot.  This does not use an SV.
 
        char*   savepv(const char* sv)
 
+=for hackers
+Found in file util.c
+
 =item savepvn
 
 Copy a string to a safe spot.  The C<len> indicates number of bytes to
@@ -1187,6 +1662,9 @@ copy.  This does not use an SV.
 
        char*   savepvn(const char* sv, I32 len)
 
+=for hackers
+Found in file util.c
+
 =item SAVETMPS
 
 Opening bracket for temporaries on a callback.  See C<FREETMPS> and
@@ -1194,29 +1672,44 @@ L<perlcall>.
 
                SAVETMPS;
 
+=for hackers
+Found in file scope.h
+
 =item SP
 
 Stack pointer.  This is usually handled by C<xsubpp>.  See C<dSP> and
 C<SPAGAIN>.
 
+=for hackers
+Found in file pp.h
+
 =item SPAGAIN
 
 Refetch the stack pointer.  Used after a callback.  See L<perlcall>.
 
                SPAGAIN;
 
+=for hackers
+Found in file pp.h
+
 =item ST
 
 Used to access elements on the XSUB's stack.
 
        SV*     ST(int ix)
 
+=for hackers
+Found in file XSUB.h
+
 =item strEQ
 
 Test two strings to see if they are equal.  Returns true or false.
 
        bool    strEQ(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strGE
 
 Test two strings to see if the first, C<s1>, is greater than or equal to
@@ -1224,6 +1717,9 @@ the second, C<s2>.  Returns true or false.
 
        bool    strGE(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strGT
 
 Test two strings to see if the first, C<s1>, is greater than the second,
@@ -1231,6 +1727,9 @@ C<s2>.  Returns true or false.
 
        bool    strGT(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strLE
 
 Test two strings to see if the first, C<s1>, is less than or equal to the
@@ -1238,6 +1737,9 @@ second, C<s2>.  Returns true or false.
 
        bool    strLE(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strLT
 
 Test two strings to see if the first, C<s1>, is less than the second,
@@ -1245,6 +1747,9 @@ C<s2>.  Returns true or false.
 
        bool    strLT(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strNE
 
 Test two strings to see if they are different.  Returns true or
@@ -1252,6 +1757,9 @@ false.
 
        bool    strNE(char* s1, char* s2)
 
+=for hackers
+Found in file handy.h
+
 =item strnEQ
 
 Test two strings to see if they are equal.  The C<len> parameter indicates
@@ -1260,6 +1768,9 @@ C<strncmp>).
 
        bool    strnEQ(char* s1, char* s2, STRLEN len)
 
+=for hackers
+Found in file handy.h
+
 =item strnNE
 
 Test two strings to see if they are different.  The C<len> parameter
@@ -1268,24 +1779,36 @@ wrapper for C<strncmp>).
 
        bool    strnNE(char* s1, char* s2, STRLEN len)
 
+=for hackers
+Found in file handy.h
+
 =item StructCopy
 
 This is an architecture-independent macro to copy one structure to another.
 
        void    StructCopy(type src, type dest, type)
 
+=for hackers
+Found in file handy.h
+
 =item SvCUR
 
 Returns the length of the string which is in the SV.  See C<SvLEN>.
 
        STRLEN  SvCUR(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvCUR_set
 
 Set the length of the string which is in the SV.  See C<SvCUR>.
 
        void    SvCUR_set(SV* sv, STRLEN len)
 
+=for hackers
+Found in file sv.h
+
 =item SvEND
 
 Returns a pointer to the last character in the string which is in the SV.
@@ -1293,6 +1816,9 @@ See C<SvCUR>.  Access the character as *(SvEND(sv)).
 
        char*   SvEND(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvGETMAGIC
 
 Invokes C<mg_get> on an SV if it has 'get' magic.  This macro evaluates its
@@ -1300,6 +1826,9 @@ argument more than once.
 
        void    SvGETMAGIC(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvGROW
 
 Expands the character buffer in the SV so that it has room for the
@@ -1309,12 +1838,18 @@ Returns a pointer to the character buffer.
 
        void    SvGROW(SV* sv, STRLEN len)
 
+=for hackers
+Found in file sv.h
+
 =item SvIOK
 
 Returns a boolean indicating whether the SV contains an integer.
 
        bool    SvIOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIOKp
 
 Returns a boolean indicating whether the SV contains an integer.  Checks
@@ -1322,30 +1857,45 @@ the B<private> setting.  Use C<SvIOK>.
 
        bool    SvIOKp(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIOK_off
 
 Unsets the IV status of an SV.
 
        void    SvIOK_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIOK_on
 
 Tells an SV that it is an integer.
 
        void    SvIOK_on(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIOK_only
 
 Tells an SV that it is an integer and disables all other OK bits.
 
        void    SvIOK_only(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIV
 
 Coerces the given SV to an integer and returns it.
 
        IV      SvIV(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvIVX
 
 Returns the integer which is stored in the SV, assuming SvIOK is
@@ -1353,12 +1903,28 @@ true.
 
        IV      SvIVX(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvLEN
 
 Returns the size of the string buffer in the SV.  See C<SvCUR>.
 
        STRLEN  SvLEN(SV* sv)
 
+=for hackers
+Found in file sv.h
+
+=item SvLOCK
+
+Aquires an internal mutex for a SV. Used to make sure multiple threads
+don't stomp on the guts of an SV at the same time
+
+       void    SvLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvNIOK
 
 Returns a boolean indicating whether the SV contains a number, integer or
@@ -1366,6 +1932,9 @@ double.
 
        bool    SvNIOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNIOKp
 
 Returns a boolean indicating whether the SV contains a number, integer or
@@ -1373,18 +1942,27 @@ double.  Checks the B<private> setting.  Use C<SvNIOK>.
 
        bool    SvNIOKp(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNIOK_off
 
 Unsets the NV/IV status of an SV.
 
        void    SvNIOK_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNOK
 
 Returns a boolean indicating whether the SV contains a double.
 
        bool    SvNOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNOKp
 
 Returns a boolean indicating whether the SV contains a double.  Checks the
@@ -1392,30 +1970,45 @@ B<private> setting.  Use C<SvNOK>.
 
        bool    SvNOKp(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNOK_off
 
 Unsets the NV status of an SV.
 
        void    SvNOK_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNOK_on
 
 Tells an SV that it is a double.
 
        void    SvNOK_on(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNOK_only
 
 Tells an SV that it is a double and disables all other OK bits.
 
        void    SvNOK_only(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNV
 
 Coerce the given SV to a double and return it.
 
        NV      SvNV(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvNVX
 
 Returns the double which is stored in the SV, assuming SvNOK is
@@ -1423,12 +2016,18 @@ true.
 
        NV      SvNVX(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvOK
 
 Returns a boolean indicating whether the value is an SV.
 
        bool    SvOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvOOK
 
 Returns a boolean indicating whether the SvIVX is a valid offset value for
@@ -1438,6 +2037,9 @@ allocated string buffer is really (SvPVX - SvIVX).
 
        bool    SvOOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPOK
 
 Returns a boolean indicating whether the SV contains a character
@@ -1445,6 +2047,9 @@ string.
 
        bool    SvPOK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPOKp
 
 Returns a boolean indicating whether the SV contains a character string.
@@ -1452,24 +2057,36 @@ Checks the B<private> setting.  Use C<SvPOK>.
 
        bool    SvPOKp(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPOK_off
 
 Unsets the PV status of an SV.
 
        void    SvPOK_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPOK_on
 
 Tells an SV that it is a string.
 
        void    SvPOK_on(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPOK_only
 
 Tells an SV that it is a string and disables all other OK bits.
 
        void    SvPOK_only(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPV
 
 Returns a pointer to the string in the SV, or a stringified form of the SV
@@ -1477,6 +2094,9 @@ if the SV does not contain a string.  Handles 'get' magic.
 
        char*   SvPV(SV* sv, STRLEN len)
 
+=for hackers
+Found in file sv.h
+
 =item SvPVX
 
 Returns a pointer to the string in the SV.  The SV must contain a
@@ -1484,6 +2104,9 @@ string.
 
        char*   SvPVX(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvPV_force
 
 Like <SvPV> but will force the SV into becoming a string (SvPOK).  You want
@@ -1491,6 +2114,9 @@ force if you are going to update the SvPVX directly.
 
        char*   SvPV_force(SV* sv, STRLEN len)
 
+=for hackers
+Found in file sv.h
+
 =item SvPV_nolen
 
 Returns a pointer to the string in the SV, or a stringified form of the SV
@@ -1498,48 +2124,72 @@ if the SV does not contain a string.  Handles 'get' magic.
 
        char*   SvPV_nolen(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT
 
 Returns the value of the object's reference count.
 
        U32     SvREFCNT(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT_dec
 
 Decrements the reference count of the given SV.
 
        void    SvREFCNT_dec(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT_inc
 
 Increments the reference count of the given SV.
 
        SV*     SvREFCNT_inc(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvROK
 
 Tests if the SV is an RV.
 
        bool    SvROK(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvROK_off
 
 Unsets the RV status of an SV.
 
        void    SvROK_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvROK_on
 
 Tells an SV that it is an RV.
 
        void    SvROK_on(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvRV
 
 Dereferences an RV to return the SV.
 
        SV*     SvRV(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvSETMAGIC
 
 Invokes C<mg_set> on an SV if it has 'set' magic.  This macro evaluates its
@@ -1547,6 +2197,9 @@ argument more than once.
 
        void    SvSETMAGIC(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvSetSV
 
 Calls C<sv_setsv> if dsv is not the same as ssv.  May evaluate arguments
@@ -1554,6 +2207,9 @@ more than once.
 
        void    SvSetSV(SV* dsb, SV* ssv)
 
+=for hackers
+Found in file sv.h
+
 =item SvSetSV_nosteal
 
 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
@@ -1561,18 +2217,27 @@ ssv. May evaluate arguments more than once.
 
        void    SvSetSV_nosteal(SV* dsv, SV* ssv)
 
+=for hackers
+Found in file sv.h
+
 =item SvSTASH
 
 Returns the stash of the SV.
 
        HV*     SvSTASH(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvTAINT
 
 Taints an SV if tainting is enabled
 
        void    SvTAINT(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvTAINTED
 
 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
@@ -1580,6 +2245,9 @@ not.
 
        bool    SvTAINTED(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvTAINTED_off
 
 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
@@ -1591,12 +2259,18 @@ untainting variables.
 
        void    SvTAINTED_off(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvTAINTED_on
 
 Marks an SV as tainted.
 
        void    SvTAINTED_on(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvTRUE
 
 Returns a boolean indicating whether Perl would evaluate the SV as true or
@@ -1604,45 +2278,84 @@ false, defined or undefined.  Does not handle 'get' magic.
 
        bool    SvTRUE(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item svtype
 
 An enum of flags for Perl types.  These are found in the file B<sv.h> 
 in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
+=for hackers
+Found in file sv.h
+
 =item SvTYPE
 
 Returns the type of the SV.  See C<svtype>.
 
        svtype  SvTYPE(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SVt_IV
 
 Integer type flag for scalars.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_NV
 
 Double type flag for scalars.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_PV
 
 Pointer type flag for scalars.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_PVAV
 
 Type flag for arrays.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_PVCV
 
 Type flag for code refs.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_PVHV
 
 Type flag for hashes.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
 =item SVt_PVMG
 
 Type flag for blessed scalars.  See C<svtype>.
 
+=for hackers
+Found in file sv.h
+
+=item SvUNLOCK
+
+Release the internal mutex for an SV.
+
+       void    SvUNLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvUPGRADE
 
 Used to upgrade an SV to a more complex form.  Uses C<sv_upgrade> to
@@ -1650,12 +2363,18 @@ perform the upgrade if necessary.  See C<svtype>.
 
        void    SvUPGRADE(SV* sv, svtype type)
 
+=for hackers
+Found in file sv.h
+
 =item SvUV
 
 Coerces the given SV to an unsigned integer and returns it.
 
        UV      SvUV(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item SvUVX
 
 Returns the unsigned integer which is stored in the SV, assuming SvIOK is
@@ -1663,6 +2382,9 @@ true.
 
        UV      SvUVX(SV* sv)
 
+=for hackers
+Found in file sv.h
+
 =item sv_2mortal
 
 Marks an SV as mortal.  The SV will be destroyed when the current context
@@ -1670,6 +2392,9 @@ ends.
 
        SV*     sv_2mortal(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_bless
 
 Blesses an SV into a specified package.  The SV must be an RV.  The package
@@ -1678,6 +2403,9 @@ of the SV is unaffected.
 
        SV*     sv_bless(SV* sv, HV* stash)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpv
 
 Concatenates the string onto the end of the string which is in the SV.
@@ -1685,6 +2413,9 @@ Handles 'get' magic, but not 'set' magic.  See C<sv_catpv_mg>.
 
        void    sv_catpv(SV* sv, const char* ptr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpvf
 
 Processes its arguments like C<sprintf> and appends the formatted output
@@ -1693,12 +2424,18 @@ typically be called after calling this function to handle 'set' magic.
 
        void    sv_catpvf(SV* sv, const char* pat, ...)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpvf_mg
 
 Like C<sv_catpvf>, but also handles 'set' magic.
 
        void    sv_catpvf_mg(SV *sv, const char* pat, ...)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpvn
 
 Concatenates the string onto the end of the string which is in the SV.  The
@@ -1707,18 +2444,27 @@ C<len> indicates number of bytes to copy.  Handles 'get' magic, but not
 
        void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpvn_mg
 
 Like C<sv_catpvn>, but also handles 'set' magic.
 
        void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catpv_mg
 
 Like C<sv_catpv>, but also handles 'set' magic.
 
        void    sv_catpv_mg(SV *sv, const char *ptr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catsv
 
 Concatenates the string from SV C<ssv> onto the end of the string in SV
@@ -1726,12 +2472,18 @@ C<dsv>.  Handles 'get' magic, but not 'set' magic.  See C<sv_catsv_mg>.
 
        void    sv_catsv(SV* dsv, SV* ssv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_catsv_mg
 
 Like C<sv_catsv>, but also handles 'set' magic.
 
        void    sv_catsv_mg(SV *dstr, SV *sstr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_chop
 
 Efficient removal of characters from the beginning of the string buffer. 
@@ -1741,6 +2493,9 @@ string.
 
        void    sv_chop(SV* sv, char* ptr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_cmp
 
 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
@@ -1749,12 +2504,18 @@ C<sv2>.
 
        I32     sv_cmp(SV* sv1, SV* sv2)
 
+=for hackers
+Found in file sv.c
+
 =item sv_dec
 
 Auto-decrement of the value in the SV.
 
        void    sv_dec(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_derived_from
 
 Returns a boolean indicating whether the SV is derived from the specified
@@ -1763,6 +2524,9 @@ for class names as well as for objects.
 
        bool    sv_derived_from(SV* sv, const char* name)
 
+=for hackers
+Found in file universal.c
+
 =item sv_eq
 
 Returns a boolean indicating whether the strings in the two SVs are
@@ -1770,6 +2534,9 @@ identical.
 
        I32     sv_eq(SV* sv1, SV* sv2)
 
+=for hackers
+Found in file sv.c
+
 =item sv_grow
 
 Expands the character buffer in the SV.  This will use C<sv_unref> and will
@@ -1778,12 +2545,18 @@ Use C<SvGROW>.
 
        char*   sv_grow(SV* sv, STRLEN newlen)
 
+=for hackers
+Found in file sv.c
+
 =item sv_inc
 
 Auto-increment of the value in the SV.
 
        void    sv_inc(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_insert
 
 Inserts a string at the specified offset/length within the SV. Similar to
@@ -1791,6 +2564,9 @@ the Perl substr() function.
 
        void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
 
+=for hackers
+Found in file sv.c
+
 =item sv_isa
 
 Returns a boolean indicating whether the SV is blessed into the specified
@@ -1799,6 +2575,9 @@ an inheritance relationship.
 
        int     sv_isa(SV* sv, const char* name)
 
+=for hackers
+Found in file sv.c
+
 =item sv_isobject
 
 Returns a boolean indicating whether the SV is an RV pointing to a blessed
@@ -1807,18 +2586,27 @@ will return false.
 
        int     sv_isobject(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_len
 
 Returns the length of the string in the SV.  See also C<SvCUR>.
 
        STRLEN  sv_len(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_magic
 
 Adds magic to an SV.
 
        void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
 
+=for hackers
+Found in file sv.c
+
 =item sv_mortalcopy
 
 Creates a new SV which is a copy of the original SV.  The new SV is marked
@@ -1826,12 +2614,18 @@ as mortal.
 
        SV*     sv_mortalcopy(SV* oldsv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_newmortal
 
 Creates a new SV which is mortal.  The reference count of the SV is set to 1.
 
        SV*     sv_newmortal()
 
+=for hackers
+Found in file sv.c
+
 =item sv_setiv
 
 Copies an integer into the given SV.  Does not handle 'set' magic.  See
@@ -1839,12 +2633,18 @@ C<sv_setiv_mg>.
 
        void    sv_setiv(SV* sv, IV num)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setiv_mg
 
 Like C<sv_setiv>, but also handles 'set' magic.
 
        void    sv_setiv_mg(SV *sv, IV i)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setnv
 
 Copies a double into the given SV.  Does not handle 'set' magic.  See
@@ -1852,12 +2652,18 @@ C<sv_setnv_mg>.
 
        void    sv_setnv(SV* sv, NV num)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setnv_mg
 
 Like C<sv_setnv>, but also handles 'set' magic.
 
        void    sv_setnv_mg(SV *sv, NV num)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpv
 
 Copies a string into an SV.  The string must be null-terminated.  Does not
@@ -1865,6 +2671,9 @@ handle 'set' magic.  See C<sv_setpv_mg>.
 
        void    sv_setpv(SV* sv, const char* ptr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpvf
 
 Processes its arguments like C<sprintf> and sets an SV to the formatted
@@ -1872,12 +2681,18 @@ output.  Does not handle 'set' magic.  See C<sv_setpvf_mg>.
 
        void    sv_setpvf(SV* sv, const char* pat, ...)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpvf_mg
 
 Like C<sv_setpvf>, but also handles 'set' magic.
 
        void    sv_setpvf_mg(SV *sv, const char* pat, ...)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpviv
 
 Copies an integer into the given SV, also updating its string value.
@@ -1885,12 +2700,18 @@ Does not handle 'set' magic.  See C<sv_setpviv_mg>.
 
        void    sv_setpviv(SV* sv, IV num)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpviv_mg
 
 Like C<sv_setpviv>, but also handles 'set' magic.
 
        void    sv_setpviv_mg(SV *sv, IV iv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpvn
 
 Copies a string into an SV.  The C<len> parameter indicates the number of
@@ -1898,18 +2719,27 @@ bytes to be copied.  Does not handle 'set' magic.  See C<sv_setpvn_mg>.
 
        void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpvn_mg
 
 Like C<sv_setpvn>, but also handles 'set' magic.
 
        void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setpv_mg
 
 Like C<sv_setpv>, but also handles 'set' magic.
 
        void    sv_setpv_mg(SV *sv, const char *ptr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setref_iv
 
 Copies an integer into a new SV, optionally blessing the SV.  The C<rv>
@@ -1920,6 +2750,9 @@ will be returned and will have a reference count of 1.
 
        SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setref_nv
 
 Copies a double into a new SV, optionally blessing the SV.  The C<rv>
@@ -1930,6 +2763,9 @@ will be returned and will have a reference count of 1.
 
        SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setref_pv
 
 Copies a pointer into a new SV, optionally blessing the SV.  The C<rv>
@@ -1946,6 +2782,9 @@ Note that C<sv_setref_pvn> copies the string while this copies the pointer.
 
        SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setref_pvn
 
 Copies a string into a new SV, optionally blessing the SV.  The length of the
@@ -1959,6 +2798,9 @@ Note that C<sv_setref_pv> copies the pointer while this copies the string.
 
        SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setsv
 
 Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
@@ -1968,12 +2810,18 @@ C<sv_setsv_mg>.
 
        void    sv_setsv(SV* dsv, SV* ssv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setsv_mg
 
 Like C<sv_setsv>, but also handles 'set' magic.
 
        void    sv_setsv_mg(SV *dstr, SV *sstr)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setuv
 
 Copies an unsigned integer into the given SV.  Does not handle 'set' magic.
@@ -1981,12 +2829,18 @@ See C<sv_setuv_mg>.
 
        void    sv_setuv(SV* sv, UV num)
 
+=for hackers
+Found in file sv.c
+
 =item sv_setuv_mg
 
 Like C<sv_setuv>, but also handles 'set' magic.
 
        void    sv_setuv_mg(SV *sv, UV u)
 
+=for hackers
+Found in file sv.c
+
 =item sv_unref
 
 Unsets the RV status of the SV, and decrements the reference count of
@@ -1995,6 +2849,9 @@ as a reversal of C<newSVrv>.  See C<SvROK_off>.
 
        void    sv_unref(SV* sv)
 
+=for hackers
+Found in file sv.c
+
 =item sv_upgrade
 
 Upgrade an SV to a more complex form.  Use C<SvUPGRADE>.  See
@@ -2002,6 +2859,9 @@ C<svtype>.
 
        bool    sv_upgrade(SV* sv, U32 mt)
 
+=for hackers
+Found in file sv.c
+
 =item sv_usepvn
 
 Tells an SV to use C<ptr> to find its string value.  Normally the string is
@@ -2014,12 +2874,18 @@ See C<sv_usepvn_mg>.
 
        void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_usepvn_mg
 
 Like C<sv_usepvn>, but also handles 'set' magic.
 
        void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
 
+=for hackers
+Found in file sv.c
+
 =item sv_vcatpvfn
 
 Processes its arguments like C<vsprintf> and appends the formatted output
@@ -2030,6 +2896,9 @@ locales).
 
        void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
 
+=for hackers
+Found in file sv.c
+
 =item sv_vsetpvfn
 
 Works like C<vcatpvfn> but copies the text into the SV instead of
@@ -2037,6 +2906,9 @@ appending it.
 
        void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
 
+=for hackers
+Found in file sv.c
+
 =item THIS
 
 Variable which is setup by C<xsubpp> to designate the object in a C++ 
@@ -2045,18 +2917,37 @@ L<perlxs/"Using XS With C++">.
 
        (whatever)      THIS
 
+=for hackers
+Found in file XSUB.h
+
 =item toLOWER
 
 Converts the specified character to lowercase.
 
        char    toLOWER(char ch)
 
+=for hackers
+Found in file handy.h
+
 =item toUPPER
 
 Converts the specified character to uppercase.
 
        char    toUPPER(char ch)
 
+=for hackers
+Found in file handy.h
+
+=item utf8_to_bytes
+
+Converts a string C<s> of length C<len> from UTF8 into ASCII encoding.
+Unlike C<bytes_to_utf8>, this over-writes the original string.
+
+       U8 *    utf8_to_bytes(U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
 =item warn
 
 This is the XSUB-writer's interface to Perl's C<warn> function.  Use this
@@ -2065,6 +2956,9 @@ C<croak>.
 
        void    warn(const char* pat, ...)
 
+=for hackers
+Found in file util.c
+
 =item XPUSHi
 
 Push an integer onto the stack, extending the stack if necessary.  Handles
@@ -2072,6 +2966,9 @@ Push an integer onto the stack, extending the stack if necessary.  Handles
 
        void    XPUSHi(IV iv)
 
+=for hackers
+Found in file pp.h
+
 =item XPUSHn
 
 Push a double onto the stack, extending the stack if necessary.  Handles
@@ -2079,6 +2976,9 @@ Push a double onto the stack, extending the stack if necessary.  Handles
 
        void    XPUSHn(NV nv)
 
+=for hackers
+Found in file pp.h
+
 =item XPUSHp
 
 Push a string onto the stack, extending the stack if necessary.  The C<len>
@@ -2087,6 +2987,9 @@ C<PUSHp>.
 
        void    XPUSHp(char* str, STRLEN len)
 
+=for hackers
+Found in file pp.h
+
 =item XPUSHs
 
 Push an SV onto the stack, extending the stack if necessary.  Does not
@@ -2094,6 +2997,9 @@ handle 'set' magic.  See C<PUSHs>.
 
        void    XPUSHs(SV* sv)
 
+=for hackers
+Found in file pp.h
+
 =item XPUSHu
 
 Push an unsigned integer onto the stack, extending the stack if necessary. 
@@ -2101,11 +3007,17 @@ See C<PUSHu>.
 
        void    XPUSHu(UV uv)
 
+=for hackers
+Found in file pp.h
+
 =item XS
 
 Macro to declare an XSUB and its C parameter list.  This is handled by
 C<xsubpp>.
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN
 
 Return from XSUB, indicating number of items on the stack.  This is usually
@@ -2113,48 +3025,72 @@ handled by C<xsubpp>.
 
        void    XSRETURN(int nitems)
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_EMPTY
 
 Return an empty list from an XSUB immediately.
 
                XSRETURN_EMPTY;
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_IV
 
 Return an integer from an XSUB immediately.  Uses C<XST_mIV>.
 
        void    XSRETURN_IV(IV iv)
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_NO
 
 Return C<&PL_sv_no> from an XSUB immediately.  Uses C<XST_mNO>.
 
                XSRETURN_NO;
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_NV
 
 Return an double from an XSUB immediately.  Uses C<XST_mNV>.
 
        void    XSRETURN_NV(NV nv)
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_PV
 
 Return a copy of a string from an XSUB immediately.  Uses C<XST_mPV>.
 
        void    XSRETURN_PV(char* str)
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_UNDEF
 
 Return C<&PL_sv_undef> from an XSUB immediately.  Uses C<XST_mUNDEF>.
 
                XSRETURN_UNDEF;
 
+=for hackers
+Found in file XSUB.h
+
 =item XSRETURN_YES
 
 Return C<&PL_sv_yes> from an XSUB immediately.  Uses C<XST_mYES>.
 
                XSRETURN_YES;
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mIV
 
 Place an integer into the specified position C<pos> on the stack.  The
@@ -2162,6 +3098,9 @@ value is stored in a new mortal SV.
 
        void    XST_mIV(int pos, IV iv)
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mNO
 
 Place C<&PL_sv_no> into the specified position C<pos> on the
@@ -2169,6 +3108,9 @@ stack.
 
        void    XST_mNO(int pos)
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mNV
 
 Place a double into the specified position C<pos> on the stack.  The value
@@ -2176,6 +3118,9 @@ is stored in a new mortal SV.
 
        void    XST_mNV(int pos, NV nv)
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mPV
 
 Place a copy of a string into the specified position C<pos> on the stack. 
@@ -2183,6 +3128,9 @@ The value is stored in a new mortal SV.
 
        void    XST_mPV(int pos, char* str)
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mUNDEF
 
 Place C<&PL_sv_undef> into the specified position C<pos> on the
@@ -2190,6 +3138,9 @@ stack.
 
        void    XST_mUNDEF(int pos)
 
+=for hackers
+Found in file XSUB.h
+
 =item XST_mYES
 
 Place C<&PL_sv_yes> into the specified position C<pos> on the
@@ -2197,11 +3148,17 @@ stack.
 
        void    XST_mYES(int pos)
 
+=for hackers
+Found in file XSUB.h
+
 =item XS_VERSION
 
 The version identifier for an XS module.  This is usually
 handled automatically by C<ExtUtils::MakeMaker>.  See C<XS_VERSION_BOOTCHECK>.
 
+=for hackers
+Found in file XSUB.h
+
 =item XS_VERSION_BOOTCHECK
 
 Macro to verify that a PM module's $VERSION variable matches the XS
@@ -2210,6 +3167,9 @@ C<xsubpp>.  See L<perlxs/"The VERSIONCHECK: Keyword">.
 
                XS_VERSION_BOOTCHECK;
 
+=for hackers
+Found in file XSUB.h
+
 =item Zero
 
 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
@@ -2217,6 +3177,9 @@ destination, C<nitems> is the number of items, and C<type> is the type.
 
        void    Zero(void* dest, int nitems, type)
 
+=for hackers
+Found in file handy.h
+
 =back
 
 =head1 AUTHORS