X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=d608eef3c3c4003d765c503c95a60edf5a1de671;hb=77004dee2553ce034a8a58b2b2849e3656df46c3;hp=2931da4c5b8af1c38c3ea7386135117416fa00f1;hpb=7b9ef14019d3c4d1aa14641dbd421c81c2cd18a4;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 2931da4..d608eef 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -768,6 +768,17 @@ See L. =for hackers Found in file mathoms.c +=item pack_cat +X + +The engine implementing pack() Perl function. Note: parameters next_in_list and +flags are not used. This call should not be used; use packlist instead. + + void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + +=for hackers +Found in file mathoms.c + =item sv_2pvbyte_nolen X @@ -973,6 +984,28 @@ being zero. See C. =for hackers Found in file mathoms.c +=item sv_usepvn +X + +Tells an SV to use C to find its string value. Implemented by +calling C with C of 0, hence does not handle 'set' +magic. See C. + + void sv_usepvn(SV* sv, char* ptr, STRLEN len) + +=for hackers +Found in file mathoms.c + +=item sv_usepvn_mg +X + +Like C, but also handles 'set' magic. + + void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + +=for hackers +Found in file mathoms.c + =item sv_uv X @@ -984,6 +1017,17 @@ cope with complex macro expressions. Always use the macro instead. =for hackers Found in file mathoms.c +=item unpack_str +X + +The engine implementing unpack() Perl function. Note: parameters strbeg, new_s +and ocnt are not used. This call should not be used, use unpackstring instead. + + I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags) + +=for hackers +Found in file mathoms.c + =back @@ -1002,17 +1046,6 @@ The engine implementing pack() Perl function. =for hackers Found in file pp_pack.c -=item pack_cat -X - -The engine implementing pack() Perl function. Note: parameters next_in_list and -flags are not used. This call should not be used; use packlist instead. - - void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) - -=for hackers -Found in file pp_pack.c - =item unpackstring X @@ -1025,17 +1058,6 @@ Issue C before and C after the call to this function. =for hackers Found in file pp_pack.c -=item unpack_str -X - -The engine implementing unpack() Perl function. Note: parameters strbeg, new_s -and ocnt are not used. This call should not be used, use unpackstring instead. - - I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags) - -=for hackers -Found in file pp_pack.c - =back @@ -1119,6 +1141,19 @@ Return the SV from the GV. =for hackers Found in file gv.h +=item gv_const_sv +X + +If C is a typeglob whose subroutine entry is a constant sub eligible for +inlining, or C is a placeholder reference that would be promoted to such +a typeglob, then returns the value returned by the sub. Otherwise, returns +NULL. + + SV* gv_const_sv(GV* gv) + +=for hackers +Found in file gv.c + =item gv_fetchmeth X @@ -1360,7 +1395,7 @@ Found in file hv.h =item HeSVKEY X -Returns the key as an C, or C if the hash entry does not +Returns the key as an C, or C if the hash entry does not contain an C key. SV* HeSVKEY(HE* he) @@ -1975,7 +2010,7 @@ The XSUB-writer's interface to the C C function. In 5.9.3, Newx() and friends replace the older New() API, and drops the first parameter, I, a debug aid which allowed callers to identify -themselves. This aid has been superceded by a new build option, +themselves. This aid has been superseded by a new build option, PERL_MEM_LOG (see L). The older API is still there for use in XS modules supporting older perls. @@ -2009,14 +2044,34 @@ Found in file handy.h =item Poison X -Fill up memory with a pattern (byte 0xAB over and over again) that -hopefully catches attempts to access uninitialized memory. +PoisonWith(0xEF) for catching access to freed memory. void Poison(void* dest, int nitems, type) =for hackers Found in file handy.h +=item PoisonNew +X + +PoisonWith(0xAB) for catching access to allocated but uninitialized memory. + + void PoisonNew(void* dest, int nitems, type) + +=for hackers +Found in file handy.h + +=item PoisonWith +X + +Fill up memory with a byte pattern (a byte repeated over and over +again) that hopefully catches attempts to access uninitialized memory. + + void PoisonWith(void* dest, int nitems, type, U8 byte) + +=for hackers +Found in file handy.h + =item Renew X @@ -2066,8 +2121,8 @@ X Perl's version of what C would be if it existed. Returns a pointer to a newly allocated string which is a duplicate of the first -C bytes from C. The memory allocated for the new string can be -freed with the C function. +C bytes from C, plus a trailing NUL byte. The memory allocated for +the new string can be freed with the C function. char* savepvn(const char* pv, I32 len) @@ -2150,7 +2205,7 @@ Found in file util.c X Returns the location of the SV in the string delimited by C and -C. It returns C if the string can't be found. The C +C. It returns C if the string can't be found. The C does not have to be fbm_compiled, but the search will not be as fast then. @@ -2670,7 +2725,8 @@ Found in file op.c =item newXS X -Used by C to hook up XSUBs as Perl subs. +Used by C to hook up XSUBs as Perl subs. I needs to be +static storage, as it is used directly as CvFILE(), without a copy being made. =for hackers Found in file op.c @@ -3427,18 +3483,6 @@ NOTE: the perl_ form of this function is deprecated. =for hackers Found in file perl.c -=item looks_like_number -X - -Test if the content of an SV looks like a number (or is a number). -C and C are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. - - I32 looks_like_number(SV* sv) - -=for hackers -Found in file sv.c - =item newRV_inc X @@ -3450,164 +3494,6 @@ incremented. =for hackers Found in file sv.h -=item newRV_noinc -X - -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. - - SV* newRV_noinc(SV *sv) - -=for hackers -Found in file sv.c - -=item NEWSV -X - -Creates a new SV. A non-zero C parameter indicates the number of -bytes of preallocated string space the SV should have. An extra byte for a -tailing NUL is also reserved. (SvPOK is not set for the SV even if string -space is allocated.) The reference count for the new SV is set to 1. -C 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 newSV -X - -Create a new null SV, or if len > 0, create a new empty SVt_PV type SV -with an initial PV allocation of len+1. Normally accessed via the C -macro. - - SV* newSV(STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVhek -X - -Creates a new SV from the hash key structure. It will generate scalars that -point to the shared string table where possible. Returns a new (undefined) -SV if the hek is NULL. - - SV* newSVhek(const HEK *hek) - -=for hackers -Found in file sv.c - -=item newSViv -X - -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. - - SV* newSViv(IV i) - -=for hackers -Found in file sv.c - -=item newSVnv -X - -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. - - SV* newSVnv(NV n) - -=for hackers -Found in file sv.c - -=item newSVpv -X - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C is zero, Perl will compute the length using -strlen(). For efficiency, consider using C instead. - - SV* newSVpv(const char* s, STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvf -X - -Creates a new SV and initializes it with the string formatted like -C. - - SV* newSVpvf(const char* pat, ...) - -=for hackers -Found in file sv.c - -=item newSVpvn -X - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. If the C argument is NULL the new SV will be undefined. - - SV* newSVpvn(const char* s, STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvn_share -X - -Creates a new SV with its SvPVX_const pointing to a shared string in the string -table. If the string does not already exist in the table, it is created -first. Turns on READONLY and FAKE. The string's hash is stored in the UV -slot of the SV; if the C parameter is non-zero, that value is used; -otherwise the hash is computed. The idea here is that as the string table -is used for shared hash keys these strings will have SvPVX_const == HeKEY and -hash lookup will avoid string compare. - - SV* newSVpvn_share(const char* s, I32 len, U32 hash) - -=for hackers -Found in file sv.c - -=item newSVrv -X - -Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded to one. If C is non-null then the new SV will -be blessed in the specified package. The new SV is returned and its -reference count is 1. - - SV* newSVrv(SV* rv, const char* classname) - -=for hackers -Found in file sv.c - -=item newSVsv -X - -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). - - SV* newSVsv(SV* old) - -=for hackers -Found in file sv.c - -=item newSVuv -X - -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 SvCUR X @@ -3640,6 +3526,20 @@ See C. Access the character as *(SvEND(sv)). =for hackers Found in file sv.h +=item SvGAMAGIC +X + +Returns true if the SV has get magic or overloading. If either is true then +the scalar is active data, and has the potential to return a new value every +time it is accessed. Hence you must be careful to only read it once per user +logical operation and work with that returned value. If neither is true then +the scalar's value cannot change unless written to. + + char* SvGAMAGIC(SV* sv) + +=for hackers +Found in file sv.h + =item SvGROW X @@ -4286,22 +4186,93 @@ Increments the reference count of the given SV. =for hackers Found in file sv.h -=item SvROK -X +=item SvREFCNT_inc_NN +X -Tests if the SV is an RV. +Same as SvREFCNT_inc, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. - bool SvROK(SV* sv) + SV* SvREFCNT_inc_NN(SV* sv) =for hackers Found in file sv.h -=item SvROK_off -X +=item SvREFCNT_inc_simple +X -Unsets the RV status of an SV. +Same as SvREFCNT_inc, but can only be used with simple variables, not +expressions or pointer dereferences. Since we don't have to store a +temporary value, it's faster. - void SvROK_off(SV* sv) + SV* SvREFCNT_inc_simple(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_NN +X + +Same as SvREFCNT_inc_simple, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. + + SV* SvREFCNT_inc_simple_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_void +X + +Same as SvREFCNT_inc_simple, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_simple_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void +X + +Same as SvREFCNT_inc, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void_NN +X + +Same as SvREFCNT_inc, but can only be used if you don't need the return +value, and you know that I is not NULL. The macro doesn't need +to return a meaningful value, or check for NULLness, so it's smaller +and faster. + + SV* SvREFCNT_inc_void_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvROK +X + +Tests if the SV is an RV. + + bool SvROK(SV* sv) + +=for hackers +Found in file sv.h + +=item SvROK_off +X + +Unsets the RV status of an SV. + + void SvROK_off(SV* sv) =for hackers Found in file sv.h @@ -4538,6 +4509,228 @@ Returns a boolean indicating whether the SV contains a v-string. =for hackers Found in file sv.h +=item sv_catpvn_nomg +X + +Like C but doesn't process magic. + + void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) + +=for hackers +Found in file sv.h + +=item sv_catsv_nomg +X + +Like C but doesn't process magic. + + void sv_catsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + +=item sv_derived_from +X + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C. It works +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_report_used +X + +Dump the contents of all SVs not yet freed. (Debugging aid). + + void sv_report_used() + +=for hackers +Found in file sv.c + +=item sv_setsv_nomg +X + +Like C but doesn't process magic. + + void sv_setsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + + +=back + +=head1 SV-Body Allocation + +=over 8 + +=item looks_like_number +X + +Test if the content of an SV looks like a number (or is a number). +C and C are treated as numbers (so will not issue a +non-numeric warning), even if your atof() doesn't grok them. + + I32 looks_like_number(SV* sv) + +=for hackers +Found in file sv.c + +=item newRV_noinc +X + +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. + + SV* newRV_noinc(SV* sv) + +=for hackers +Found in file sv.c + +=item newSV +X + +Creates a new SV. A non-zero C parameter indicates the number of +bytes of preallocated string space the SV should have. An extra byte for a +trailing NUL is also reserved. (SvPOK is not set for the SV even if string +space is allocated.) The reference count for the new SV is set to 1. + +In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first +parameter, I, a debug aid which allowed callers to identify themselves. +This aid has been superseded by a new build option, PERL_MEM_LOG (see +L). The older API is still there for use in XS +modules supporting older perls. + + SV* newSV(STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVhek +X + +Creates a new SV from the hash key structure. It will generate scalars that +point to the shared string table where possible. Returns a new (undefined) +SV if the hek is NULL. + + SV* newSVhek(const HEK *hek) + +=for hackers +Found in file sv.c + +=item newSViv +X + +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. + + SV* newSViv(IV i) + +=for hackers +Found in file sv.c + +=item newSVnv +X + +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. + + SV* newSVnv(NV n) + +=for hackers +Found in file sv.c + +=item newSVpv +X + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. If C is zero, Perl will compute the length using +strlen(). For efficiency, consider using C instead. + + SV* newSVpv(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvf +X + +Creates a new SV and initializes it with the string formatted like +C. + + SV* newSVpvf(const char* pat, ...) + +=for hackers +Found in file sv.c + +=item newSVpvn +X + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. Note that if C is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C bytes long. If the C argument is NULL the new SV will be undefined. + + SV* newSVpvn(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvn_share +X + +Creates a new SV with its SvPVX_const pointing to a shared string in the string +table. If the string does not already exist in the table, it is created +first. Turns on READONLY and FAKE. The string's hash is stored in the UV +slot of the SV; if the C parameter is non-zero, that value is used; +otherwise the hash is computed. The idea here is that as the string table +is used for shared hash keys these strings will have SvPVX_const == HeKEY and +hash lookup will avoid string compare. + + SV* newSVpvn_share(const char* s, I32 len, U32 hash) + +=for hackers +Found in file sv.c + +=item newSVrv +X + +Creates a new SV for the RV, C, to point to. If C is not an RV then +it will be upgraded to one. If C is non-null then the new SV will +be blessed in the specified package. The new SV is returned and its +reference count is 1. + + SV* newSVrv(SV* rv, const char* classname) + +=for hackers +Found in file sv.c + +=item newSVsv +X + +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). + + SV* newSVsv(SV* old) + +=for hackers +Found in file sv.c + +=item newSVuv +X + +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 sv_2bool X @@ -4554,6 +4747,7 @@ X Using various gambits, try to get a CV from an SV; in addition, try if possible to set C<*st> and C<*gvp> to the stash and GV associated with it. +The flags in C are passed to sv_fetchsv. CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) @@ -4752,16 +4946,6 @@ in terms of this function. =for hackers Found in file sv.c -=item sv_catpvn_nomg -X - -Like C but doesn't process magic. - - void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) - -=for hackers -Found in file sv.h - =item sv_catpv_mg X @@ -4797,16 +4981,6 @@ and C are implemented in terms of this function. =for hackers Found in file sv.c -=item sv_catsv_nomg -X - -Like C but doesn't process magic. - - void sv_catsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_chop X @@ -4905,18 +5079,6 @@ if necessary. Handles 'get' magic. =for hackers Found in file sv.c -=item sv_derived_from -X - -Returns a boolean indicating whether the SV is derived from the specified -class. This is the function that implements C. It works -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 X @@ -5085,7 +5247,7 @@ to contain an C and is stored as-is with its REFCNT incremented. (This is now used as a subroutine by C.) - MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen) + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen) =for hackers Found in file sv.c @@ -5225,16 +5387,6 @@ time you'll want to use C or one of its many macro front-ends. =for hackers Found in file sv.c -=item sv_report_used -X - -Dump the contents of all SVs not yet freed. (Debugging aid). - - void sv_report_used() - -=for hackers -Found in file sv.c - =item sv_reset X @@ -5392,7 +5544,7 @@ X Copies an integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_iv(SV* rv, const char* classname, IV iv) @@ -5406,7 +5558,7 @@ X Copies a double into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_nv(SV* rv, const char* classname, NV nv) @@ -5421,7 +5573,7 @@ Copies a pointer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. If the C argument is NULL then C will be placed into the SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Do not use with other Perl types such as HV, AV, SV, CV, because those @@ -5441,7 +5593,7 @@ Copies a string into a new SV, optionally blessing the SV. The length of the string must be specified with C. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the blessing. Set C to -C to avoid the blessing. The new SV will have a reference count +C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Note that C copies the pointer while this copies the string. @@ -5457,7 +5609,7 @@ X Copies an unsigned integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_uv(SV* rv, const char* classname, UV uv) @@ -5518,16 +5670,6 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setsv_nomg -X - -Like C but doesn't process magic. - - void sv_setsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_setuv X @@ -5617,28 +5759,24 @@ You generally want to use the C macro wrapper. See also C. =for hackers Found in file sv.c -=item sv_usepvn -X - -Tells an SV to use C to find its string value. Normally the string is -stored inside the SV but sv_usepvn allows the SV to use an outside string. -The C should point to memory that was allocated by C. The -string length, C, must be supplied. This function will realloc the -memory pointed to by C, so that pointer should not be freed or used by -the programmer after giving it to sv_usepvn. Does not handle 'set' magic. -See C. +=item sv_usepvn_flags +X - void sv_usepvn(SV* sv, char* ptr, STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_usepvn_mg -X +Tells an SV to use C to find its string value. Normally the +string is stored inside the SV but sv_usepvn allows the SV to use an +outside string. The C should point to memory that was allocated +by C. The string length, C, must be supplied. By default +this function will realloc (i.e. move) the memory pointed to by C, +so that pointer should not be freed or used by the programmer after +giving it to sv_usepvn, and neither should any pointers from "behind" +that pointer (e.g. ptr + 1) be used. -Like C, but also handles 'set' magic. +If C & SV_SMAGIC is true, will call SvSETMAGIC. If C & +SV_HAS_TRAILING_NUL is true, then C must be NUL, and the realloc +will be skipped. (i.e. the buffer is actually at least 1 byte longer than +C, and already meets the requirements for storing in C) - void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags) =for hackers Found in file sv.c @@ -6191,6 +6329,8 @@ Unlike C, this over-writes the original string, and updates len to contain the new length. Returns zero on failure, setting C to -1. +If you need a copy of the string, see C. + NOTE: this function is experimental and may change or be removed without notice. @@ -6495,11 +6635,11 @@ function. Calling C returns control directly to Perl, sidestepping the normal C order of execution. See C. If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): +C<$@> and then pass C to croak(): errsv = get_sv("@", TRUE); sv_setsv(errsv, exception_object); - croak(Nullch); + croak(NULL); void croak(const char* pat, ...)