X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=c7edea92cc6abacdb76c6b8eac92fbc7791de715;hb=f3b76584ef7773843ba39a11b8bd91238af59f12;hp=e6191c0a41f9fb21edc4cb6db03bc8ad182c2baa;hpb=cb50131aab68ac6dda048612c6e853b8cb08701e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index e6191c0..c7edea9 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -25,6 +25,9 @@ Same as C. Deprecated, use C 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,31 @@ array itself. void av_clear(AV* ar) +=for hackers +Found in file av.c + +=item av_delete + +Deletes the element indexed by C from the array. Returns the +deleted element. C 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 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 is the index to which the array should be @@ -39,6 +67,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 is the @@ -50,6 +81,19 @@ 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 @@ -57,6 +101,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 +112,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 +122,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 +132,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. The @@ -100,12 +159,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 values onto the beginning of the @@ -114,6 +179,20 @@ must then use C 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 of length C from ASCII into UTF8 encoding. +Returns a pointer to the newly-created string, and sets C to +reflect the new length. + + 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. @@ -122,6 +201,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 +213,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. @@ -139,6 +224,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 +236,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 to indicate the @@ -155,6 +246,9 @@ class name for a C++ XS constructor. This is always a C. See C. char* CLASS +=for hackers +Found in file XSUB.h + =item Copy The XSUB-writer's interface to the C C function. The C is the @@ -163,20 +257,36 @@ the type. May fail on overlapping copies. See also C. 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 function. Use this -function the same way you use the C C function. See -C. +This is the XSUB-writer's interface to Perl's C function. +Normally use this function the same way you use the C C +function. See C. + +If you want to throw an exception object, assign the object to +C<$@> and then pass C 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, for the XSUB. See C and @@ -184,12 +294,18 @@ C. dMARK; +=for hackers +Found in file pp.h + =item dORIGMARK Saves the original stack mark for the XSUB. See C. dORIGMARK; +=for hackers +Found in file pp.h + =item dSP Declares a local copy of perl's stack pointer for the XSUB, available via @@ -197,6 +313,9 @@ the C macro. See C. dSP; +=for hackers +Found in file pp.h + =item dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This @@ -205,6 +324,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 variable for an XSUB which has aliases. This is usually @@ -212,12 +334,18 @@ handled automatically by C. dXSI32; +=for hackers +Found in file XSUB.h + =item ENTER Opening bracket on a callback. See C and L. ENTER; +=for hackers +Found in file scope.h + =item eval_pv Tells Perl to C the given string and return an SV* result. @@ -226,6 +354,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 the string in the SV. @@ -234,14 +365,20 @@ 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, guarrantees that there is room for at least C to be pushed +used, guarantees that there is room for at least C 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() @@ -249,6 +386,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 and @@ -258,6 +398,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 and @@ -265,6 +408,9 @@ L. FREETMPS; +=for hackers +Found in file scope.h + =item get_av Returns the AV of the specified Perl array. If C is set and the @@ -275,6 +421,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 is set and @@ -286,6 +435,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 is set and the @@ -296,6 +448,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 is set and the @@ -306,6 +461,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 which can only return @@ -314,6 +472,9 @@ Deprecated. Use C instead. U32 GIMME +=for hackers +Found in file op.h + =item GIMME_V The XSUB-writer's equivalent to Perl's C. Returns C, @@ -322,12 +483,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 and a defined subroutine or @@ -341,18 +508,24 @@ 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 may be a method cache entry, which is not -visible to Perl code. So when calling C, you should not use +visible to Perl code. So when calling C, 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 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* 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 @@ -375,67 +548,100 @@ created via a side effect to do this. These functions have the same side-effects and as C with C. C should be writable if contains C<':'> or C<' ''>. The warning against passing the GV returned by C to -C apply equally to these functions. +C 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. If C is -set then the package will be created if it does not already exist. If -C is not set and the package does not exist then NULL is -returned. +Returns a pointer to the stash for a specified package. C should +be a valid UTF-8 string. If C is set then the package will be +created if it does not already exist. If C 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. See -C. +Returns a pointer to the stash for a specified package, which must be a +valid UTF-8 string. See C. HV* gv_stashsv(SV* sv, I32 create) +=for hackers +Found in file gv.c + =item G_ARRAY Used to indicate array context. See C, C and L. +=for hackers +Found in file cop.h + =item G_DISCARD Indicates that arguments returned from a callback should be discarded. See L. +=for hackers +Found in file cop.h + =item G_EVAL Used to force a Perl C wrapper around a callback. See L. +=for hackers +Found in file cop.h + =item G_NOARGS Indicates that no arguments are being sent to a callback. See L. +=for hackers +Found in file cop.h + =item G_SCALAR Used to indicate scalar context. See C, C, and L. +=for hackers +Found in file cop.h + =item G_VOID Used to indicate void context. See C and L. +=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 pointer where a C 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 @@ -445,6 +651,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, it indicates the entry @@ -454,6 +663,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 value, doing any @@ -468,6 +680,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, or C if the hash entry does not @@ -475,6 +690,9 @@ contain an C key. SV* HeSVKEY(HE* he) +=for hackers +Found in file hv.h + =item HeSVKEY_force Returns the key as an C. Will create and return a temporary mortal @@ -482,6 +700,9 @@ C if the hash entry contains only a C key. SV* HeSVKEY_force(HE* he) +=for hackers +Found in file hv.h + =item HeSVKEY_set Sets the key to a given C, taking care to set the appropriate flags to @@ -490,24 +711,36 @@ C. SV* HeSVKEY_set(HE* he, SV* sv) +=for hackers +Found in file hv.h + =item HeVAL Returns the value slot (type C) 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, C. 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 @@ -517,6 +750,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 @@ -526,6 +762,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 @@ -533,6 +772,9 @@ C 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 @@ -541,6 +783,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 @@ -553,6 +798,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. @@ -568,6 +816,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 @@ -580,6 +831,9 @@ value, you can get it through the macro C. 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 @@ -587,6 +841,9 @@ C. char* hv_iterkey(HE* entry, I32* retlen) +=for hackers +Found in file hv.c + =item hv_iterkeysv Returns the key as an C from the current position of the hash @@ -595,12 +852,18 @@ see C. SV* hv_iterkeysv(HE* entry) +=for hackers +Found in file hv.c + =item hv_iternext Returns entries from a hash iterator. See C. HE* hv_iternext(HV* tb) +=for hackers +Found in file hv.c + =item hv_iternextsv Performs an C, C, and C in one @@ -608,6 +871,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 @@ -615,12 +881,18 @@ C. SV* hv_iterval(HV* tb, HE* entry) +=for hackers +Found in file hv.c + =item hv_magic Adds magic to a hash. See C. 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 and C is @@ -637,6 +909,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 in a hash. The hash key is specified as C. The C @@ -654,33 +929,48 @@ 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 is an ascii alphanumeric -character or digit. +Returns a boolean indicating whether the C C 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 is an ascii alphabetic +Returns a boolean indicating whether the C C 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 is an ascii +Returns a boolean indicating whether the C C 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 is a lowercase @@ -688,12 +978,18 @@ character. bool isLOWER(char ch) +=for hackers +Found in file handy.h + =item isSPACE Returns a boolean indicating whether the C C is whitespace. bool isSPACE(char ch) +=for hackers +Found in file handy.h + =item isUPPER Returns a boolean indicating whether the C C is an uppercase @@ -701,6 +997,9 @@ character. bool isUPPER(char ch) +=for hackers +Found in file handy.h + =item items Variable which is setup by C to indicate the number of @@ -708,6 +1007,9 @@ items on the stack. See L. I32 items +=for hackers +Found in file XSUB.h + =item ix Variable which is setup by C to indicate which of an @@ -715,12 +1017,18 @@ XSUB's aliases was used to invoke it. See L. I32 ix +=for hackers +Found in file XSUB.h + =item LEAVE Closing bracket on a callback. See C and L. 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 @@ -728,58 +1036,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. +=for hackers +Found in file pp.h + =item mg_clear Clear something magical that the SV represents. See C. 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. 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. 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. 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. int mg_get(SV* sv) +=for hackers +Found in file mg.c + =item mg_length Report on the SV's length. See C. 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. 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. int mg_set(SV* sv) +=for hackers +Found in file mg.c + =item Move The XSUB-writer's interface to the C C function. The C is the @@ -788,18 +1126,27 @@ the type. Can do overlapping moves. See also C. 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 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 function, with @@ -807,6 +1154,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 which is @@ -814,12 +1164,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 @@ -827,6 +1183,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 @@ -834,6 +1193,9 @@ SV is B incremented. SV* newRV_noinc(SV *sv) +=for hackers +Found in file sv.c + =item NEWSV Creates a new SV. A non-zero C parameter indicates the number of @@ -844,6 +1206,9 @@ C 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 @@ -851,6 +1216,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. @@ -858,6 +1226,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 @@ -866,6 +1237,9 @@ strlen(). For efficiency, consider using C 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 @@ -873,6 +1247,9 @@ C. 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 @@ -882,6 +1259,9 @@ C 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, to point to. If C is not an RV then @@ -891,21 +1271,43 @@ 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. +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 to hook up XSUBs as Perl subs. +=for hackers +Found in file op.c + =item newXSproto Used by C 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 function. The allocated @@ -913,66 +1315,105 @@ memory is zeroed with C. 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. +=for hackers +Found in file pp.h + =item perl_alloc Allocates a new Perl interpreter. See L. PerlInterpreter* perl_alloc() +=for hackers +Found in file perl.c + =item perl_construct Initializes a new Perl interpreter. See L. void perl_construct(PerlInterpreter* interp) +=for hackers +Found in file perl.c + =item perl_destruct Shuts down a Perl interpreter. See L. void perl_destruct(PerlInterpreter* interp) +=for hackers +Found in file perl.c + =item perl_free Releases a Perl interpreter. See L. 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. 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. 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 @@ -983,6 +1424,9 @@ C. 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 @@ -992,6 +1436,9 @@ C. 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> @@ -1000,12 +1447,18 @@ variable. See C. 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 is a general purpose, interpreter global HV for use by @@ -1016,6 +1469,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 when one @@ -1025,6 +1481,9 @@ C macro. STRLEN PL_na +=for hackers +Found in file thrdvar.h + =item PL_sv_no This is the C SV. See C. Always refer to this as @@ -1032,12 +1491,18 @@ C<&PL_sv_no>. SV PL_sv_no +=for hackers +Found in file intrpvar.h + =item PL_sv_undef This is the C 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 SV. See C. Always refer to this as @@ -1045,36 +1510,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. @@ -1082,6 +1565,9 @@ Handles 'set' magic. See C. void PUSHi(IV iv) +=for hackers +Found in file pp.h + =item PUSHMARK Opening bracket for arguments on a callback. See C and @@ -1089,6 +1575,9 @@ L. PUSHMARK; +=for hackers +Found in file pp.h + =item PUSHn Push a double onto the stack. The stack must have room for this element. @@ -1096,6 +1585,9 @@ Handles 'set' magic. See C. 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. @@ -1104,6 +1596,9 @@ C. 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. @@ -1111,6 +1606,9 @@ Does not handle 'set' magic. See C. 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 @@ -1118,6 +1616,9 @@ element. See C. void PUSHu(UV uv) +=for hackers +Found in file pp.h + =item PUTBACK Closing bracket for XSUB arguments. This is usually handled by C. @@ -1125,12 +1626,18 @@ See C and L for other uses. PUTBACK; +=for hackers +Found in file pp.h + =item Renew The XSUB-writer's interface to the C C 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 function, with @@ -1138,6 +1645,9 @@ cast. void Renewc(void* ptr, int nitems, type, cast) +=for hackers +Found in file handy.h + =item require_pv Tells Perl to C a module. @@ -1146,6 +1656,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 to hold the return value for an @@ -1154,18 +1667,27 @@ L. (whatever) RETVAL +=for hackers +Found in file XSUB.h + =item Safefree The XSUB-writer's interface to the C C 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 indicates number of bytes to @@ -1173,6 +1695,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 and @@ -1180,29 +1705,44 @@ L. SAVETMPS; +=for hackers +Found in file scope.h + =item SP Stack pointer. This is usually handled by C. See C and C. +=for hackers +Found in file pp.h + =item SPAGAIN Refetch the stack pointer. Used after a callback. See L. 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, is greater than or equal to @@ -1210,6 +1750,9 @@ the second, C. 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, is greater than the second, @@ -1217,6 +1760,9 @@ C. 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, is less than or equal to the @@ -1224,6 +1770,9 @@ second, C. 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, is less than the second, @@ -1231,6 +1780,9 @@ C. 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 @@ -1238,6 +1790,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 parameter indicates @@ -1246,6 +1801,9 @@ C). 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 parameter @@ -1254,24 +1812,36 @@ wrapper for C). bool strnNE(char* s1, char* s2, STRLEN len) +=for hackers +Found in file handy.h + =item StructCopy -This is an architecture-independant macro to copy one structure to another. +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. 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. 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. @@ -1279,6 +1849,9 @@ See C. Access the character as *(SvEND(sv)). char* SvEND(SV* sv) +=for hackers +Found in file sv.h + =item SvGETMAGIC Invokes C on an SV if it has 'get' magic. This macro evaluates its @@ -1286,6 +1859,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 @@ -1295,12 +1871,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 @@ -1308,30 +1890,45 @@ the B setting. Use C. 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 @@ -1339,12 +1936,18 @@ 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. STRLEN SvLEN(SV* sv) +=for hackers +Found in file sv.h + =item SvNIOK Returns a boolean indicating whether the SV contains a number, integer or @@ -1352,6 +1955,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 @@ -1359,18 +1965,27 @@ double. Checks the B setting. Use C. 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 @@ -1378,30 +1993,45 @@ B setting. Use C. 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 @@ -1409,12 +2039,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 @@ -1424,6 +2060,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 @@ -1431,6 +2070,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. @@ -1438,24 +2080,36 @@ Checks the B setting. Use C. 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 @@ -1463,6 +2117,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 @@ -1470,6 +2127,9 @@ string. char* SvPVX(SV* sv) +=for hackers +Found in file sv.h + =item SvPV_force Like but will force the SV into becoming a string (SvPOK). You want @@ -1477,6 +2137,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 @@ -1484,48 +2147,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 on an SV if it has 'set' magic. This macro evaluates its @@ -1533,6 +2220,9 @@ argument more than once. void SvSETMAGIC(SV* sv) +=for hackers +Found in file sv.h + =item SvSetSV Calls C if dsv is not the same as ssv. May evaluate arguments @@ -1540,6 +2230,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 if dsv is not the same as @@ -1547,18 +2240,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 @@ -1566,6 +2268,9 @@ not. bool SvTAINTED(SV* sv) +=for hackers +Found in file sv.h + =item SvTAINTED_off Untaints an SV. Be I careful with this routine, as it short-circuits @@ -1577,12 +2282,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 @@ -1590,45 +2301,75 @@ 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 +in the C enum. Test these flags with the C macro. + +=for hackers +Found in file sv.h + =item SvTYPE Returns the type of the SV. See C. svtype SvTYPE(SV* sv) -=item svtype - -An enum of flags for Perl types. These are found in the file B -in the C enum. Test these flags with the C macro. +=for hackers +Found in file sv.h =item SVt_IV Integer type flag for scalars. See C. +=for hackers +Found in file sv.h + =item SVt_NV Double type flag for scalars. See C. +=for hackers +Found in file sv.h + =item SVt_PV Pointer type flag for scalars. See C. +=for hackers +Found in file sv.h + =item SVt_PVAV Type flag for arrays. See C. +=for hackers +Found in file sv.h + =item SVt_PVCV Type flag for code refs. See C. +=for hackers +Found in file sv.h + =item SVt_PVHV Type flag for hashes. See C. +=for hackers +Found in file sv.h + =item SVt_PVMG Type flag for blessed scalars. See C. +=for hackers +Found in file sv.h + =item SvUPGRADE Used to upgrade an SV to a more complex form. Uses C to @@ -1636,12 +2377,18 @@ perform the upgrade if necessary. See C. 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 @@ -1649,6 +2396,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 @@ -1656,6 +2406,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 @@ -1664,6 +2417,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. @@ -1671,6 +2427,9 @@ Handles 'get' magic, but not 'set' magic. See C. void sv_catpv(SV* sv, const char* ptr) +=for hackers +Found in file sv.c + =item sv_catpvf Processes its arguments like C and appends the formatted output @@ -1679,12 +2438,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, 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 @@ -1693,18 +2458,27 @@ C 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, 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, 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 onto the end of the string in SV @@ -1712,12 +2486,18 @@ C. Handles 'get' magic, but not 'set' magic. See C. void sv_catsv(SV* dsv, SV* ssv) +=for hackers +Found in file sv.c + =item sv_catsv_mg Like C, 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. @@ -1727,6 +2507,19 @@ string. void sv_chop(SV* sv, char* ptr) +=for hackers +Found in file sv.c + +=item sv_clear + +Clear an SV, making it empty. Does not free the memory used by the SV +itself. + + void sv_clear(SV* sv) + +=for hackers +Found in file sv.c + =item sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the @@ -1735,12 +2528,28 @@ C. I32 sv_cmp(SV* sv1, SV* sv2) +=for hackers +Found in file sv.c + +=item sv_cmp_locale + +Compares the strings in two SVs in a locale-aware manner. See +L + + I32 sv_cmp_locale(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 @@ -1749,6 +2558,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 @@ -1756,6 +2568,28 @@ identical. I32 sv_eq(SV* sv1, SV* sv2) +=for hackers +Found in file sv.c + +=item sv_free + +Free the memory used by an SV. + + void sv_free(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_gets + +Get a line from the filehandle and store it into the SV, optionally +appending to the currently-stored string. + + char* sv_gets(SV* sv, PerlIO* fp, I32 append) + +=for hackers +Found in file sv.c + =item sv_grow Expands the character buffer in the SV. This will use C and will @@ -1764,12 +2598,18 @@ Use C. 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 @@ -1777,6 +2617,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 @@ -1785,6 +2628,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 @@ -1793,18 +2639,37 @@ 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. STRLEN sv_len(SV* sv) +=for hackers +Found in file sv.c + +=item sv_len_utf8 + +Returns the number of characters in the string in an SV, counting wide +UTF8 bytes as a single character. + + STRLEN sv_len_utf8(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 @@ -1812,12 +2677,64 @@ 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_pvn_force + +Get a sensible string out of the SV somehow. + + char* sv_pvn_force(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c + +=item sv_pvutf8n_force + +Get a sensible UTF8-encoded string out of the SV somehow. See +L. + + char* sv_pvutf8n_force(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c + +=item sv_reftype + +Returns a string describing what the SV is a reference to. + + char* sv_reftype(SV* sv, int ob) + +=for hackers +Found in file sv.c + +=item sv_replace + +Make the first argument a copy of the second, then delete the original. + + void sv_replace(SV* sv, SV* nsv) + +=for hackers +Found in file sv.c + +=item sv_rvweaken + +Weaken a reference. + + SV* sv_rvweaken(SV *sv) + +=for hackers +Found in file sv.c + =item sv_setiv Copies an integer into the given SV. Does not handle 'set' magic. See @@ -1825,12 +2742,18 @@ C. void sv_setiv(SV* sv, IV num) +=for hackers +Found in file sv.c + =item sv_setiv_mg Like C, 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 @@ -1838,12 +2761,18 @@ C. void sv_setnv(SV* sv, NV num) +=for hackers +Found in file sv.c + =item sv_setnv_mg Like C, 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 @@ -1851,6 +2780,9 @@ handle 'set' magic. See C. void sv_setpv(SV* sv, const char* ptr) +=for hackers +Found in file sv.c + =item sv_setpvf Processes its arguments like C and sets an SV to the formatted @@ -1858,12 +2790,18 @@ output. Does not handle 'set' magic. See C. void sv_setpvf(SV* sv, const char* pat, ...) +=for hackers +Found in file sv.c + =item sv_setpvf_mg Like C, 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. @@ -1871,12 +2809,18 @@ Does not handle 'set' magic. See C. void sv_setpviv(SV* sv, IV num) +=for hackers +Found in file sv.c + =item sv_setpviv_mg Like C, 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 parameter indicates the number of @@ -1884,18 +2828,27 @@ bytes to be copied. Does not handle 'set' magic. See C. void sv_setpvn(SV* sv, const char* ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_setpvn_mg Like C, 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, 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 @@ -1906,6 +2859,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 @@ -1916,6 +2872,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 @@ -1932,6 +2891,9 @@ Note that C 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 @@ -1945,6 +2907,9 @@ Note that C 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 into the destination SV C. @@ -1954,12 +2919,18 @@ C. void sv_setsv(SV* dsv, SV* ssv) +=for hackers +Found in file sv.c + =item sv_setsv_mg Like C, 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. @@ -1967,12 +2938,36 @@ See C. void sv_setuv(SV* sv, UV num) +=for hackers +Found in file sv.c + =item sv_setuv_mg Like C, but also handles 'set' magic. void sv_setuv_mg(SV *sv, UV u) +=for hackers +Found in file sv.c + +=item sv_true + +Returns true if the SV has a true value by Perl's rules. + + I32 sv_true(SV *sv) + +=for hackers +Found in file sv.c + +=item sv_unmagic + +Removes magic from an SV. + + int sv_unmagic(SV* sv, int type) + +=for hackers +Found in file sv.c + =item sv_unref Unsets the RV status of the SV, and decrements the reference count of @@ -1981,6 +2976,9 @@ as a reversal of C. See C. 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. See @@ -1988,6 +2986,9 @@ C. bool sv_upgrade(SV* sv, U32 mt) +=for hackers +Found in file sv.c + =item sv_usepvn Tells an SV to use C to find its string value. Normally the string is @@ -2000,12 +3001,55 @@ See C. void sv_usepvn(SV* sv, char* ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_usepvn_mg Like C, but also handles 'set' magic. void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) +=for hackers +Found in file sv.c + +=item sv_utf8_downgrade + +Attempt to convert the PV of an SV from UTF8-encoded to byte encoding. +This may not be possible if the PV contains non-byte encoding characters; +if this is the case, either returns false or, if C is not +true, croaks. + +NOTE: this function is experimental and may change or be +removed without notice. + + bool sv_utf8_downgrade(SV *sv, bool fail_ok) + +=for hackers +Found in file sv.c + +=item sv_utf8_encode + +Convert the PV of an SV to UTF8-encoded, but then turn off the C +flag so that it looks like bytes again. Nothing calls this. + +NOTE: this function is experimental and may change or be +removed without notice. + + void sv_utf8_encode(SV *sv) + +=for hackers +Found in file sv.c + +=item sv_utf8_upgrade + +Convert the PV of an SV to its UTF8-encoded form. + + void sv_utf8_upgrade(SV *sv) + +=for hackers +Found in file sv.c + =item sv_vcatpvfn Processes its arguments like C and appends the formatted output @@ -2016,6 +3060,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 but copies the text into the SV instead of @@ -2023,6 +3070,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 to designate the object in a C++ @@ -2031,18 +3081,48 @@ L. (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 U8 *s + +Returns true if first C bytes of the given string form valid a UTF8 +string, false otherwise. + + bool_utf8_string U8 *s(STRLEN len) + +=for hackers +Found in file utf8.c + +=item utf8_to_bytes + +Converts a string C of length C from UTF8 into ASCII encoding. +Unlike C, this over-writes the original string. +Returns zero on failure after converting as much as possible. + + 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 function. Use this @@ -2051,6 +3131,9 @@ C. 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 @@ -2058,6 +3141,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 @@ -2065,6 +3151,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 @@ -2073,6 +3162,9 @@ C. 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 @@ -2080,6 +3172,9 @@ handle 'set' magic. See C. 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. @@ -2087,11 +3182,17 @@ See C. 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. +=for hackers +Found in file XSUB.h + =item XSRETURN Return from XSUB, indicating number of items on the stack. This is usually @@ -2099,48 +3200,72 @@ handled by C. 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. 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. XSRETURN_NO; +=for hackers +Found in file XSUB.h + =item XSRETURN_NV Return an double from an XSUB immediately. Uses C. 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. 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. XSRETURN_UNDEF; +=for hackers +Found in file XSUB.h + =item XSRETURN_YES Return C<&PL_sv_yes> from an XSUB immediately. Uses C. XSRETURN_YES; +=for hackers +Found in file XSUB.h + =item XST_mIV Place an integer into the specified position C on the stack. The @@ -2148,6 +3273,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 on the @@ -2155,6 +3283,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 on the stack. The value @@ -2162,6 +3293,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 on the stack. @@ -2169,6 +3303,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 on the @@ -2176,6 +3313,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 on the @@ -2183,11 +3323,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. See C. +=for hackers +Found in file XSUB.h + =item XS_VERSION_BOOTCHECK Macro to verify that a PM module's $VERSION variable matches the XS @@ -2196,6 +3342,9 @@ C. See L. XS_VERSION_BOOTCHECK; +=for hackers +Found in file XSUB.h + =item Zero The XSUB-writer's interface to the C C function. The C is the @@ -2203,6 +3352,9 @@ destination, C is the number of items, and C is the type. void Zero(void* dest, int nitems, type) +=for hackers +Found in file handy.h + =back =head1 AUTHORS