diff options
Diffstat (limited to 'contrib/perl5/pod/perlguts.pod')
| -rw-r--r-- | contrib/perl5/pod/perlguts.pod | 183 |
1 files changed, 111 insertions, 72 deletions
diff --git a/contrib/perl5/pod/perlguts.pod b/contrib/perl5/pod/perlguts.pod index 20a07d3..90bb716 100644 --- a/contrib/perl5/pod/perlguts.pod +++ b/contrib/perl5/pod/perlguts.pod @@ -48,8 +48,8 @@ To change the value of an *already-existing* SV, there are seven routines: void sv_setiv(SV*, IV); void sv_setuv(SV*, UV); void sv_setnv(SV*, double); - void sv_setpv(SV*, char*); - void sv_setpvn(SV*, char*, int) + void sv_setpv(SV*, const char*); + void sv_setpvn(SV*, const char*, int) void sv_setpvf(SV*, const char*, ...); void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_setsv(SV*, SV*); @@ -68,7 +68,7 @@ C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify either a pointer to a variable argument list or the address and length of an array of SVs. The last argument points to a boolean; on return, if that boolean is true, then locale-specific information has been used to format -the string, and the string's contents are therefore untrustworty (see +the string, and the string's contents are therefore untrustworthy (see L<perlsec>). This pointer may be NULL if that information is not important. Note that this function requires you to specify the length of the format. @@ -95,9 +95,20 @@ or string. In the C<SvPV> macro, the length of the string returned is placed into the variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not -care what the length of the data is, use the global variable C<PL_na>. Remember, -however, that Perl allows arbitrary strings of data that may both contain -NULs and might not be terminated by a NUL. +care what the length of the data is, use the global variable C<PL_na> or a +local variable of type C<STRLEN>. However using C<PL_na> can be quite +inefficient because C<PL_na> must be accessed in thread-local storage in +threaded Perl. In any case, remember that Perl allows arbitrary strings of +data that may both contain NULs and might not be terminated by a NUL. + +Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len), +len);>. It might work with your compiler, but it won't work for everyone. +Break this sort of statement up into separate assignments: + + STRLEN len; + char * ptr; + ptr = SvPV(len); + foo(ptr, len); If you want to know if the scalar value is TRUE, you can use: @@ -138,7 +149,7 @@ If you want to append something to the end of string stored in an C<SV*>, you can use the following functions: void sv_catpv(SV*, char*); - void sv_catpvn(SV*, char*, int); + void sv_catpvn(SV*, char*, STRLEN); void sv_catpvf(SV*, const char*, ...); void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_catsv(SV*, SV*); @@ -262,9 +273,9 @@ return value. The C<av_clear> function deletes all the elements in the AV* array, but does not actually delete the array itself. The C<av_undef> function will delete all the elements in the array plus the array itself. The -C<av_extend> function extends the array so that it contains C<key> -elements. If C<key> is less than the current length of the array, then -nothing is done. +C<av_extend> function extends the array so that it contains at least C<key+1> +elements. If C<key+1> is less than the currently allocated length of the array, +then nothing is done. If you know the name of an array variable, you can get a pointer to its AV by using the following: @@ -350,11 +361,9 @@ This returns NULL if the variable does not exist. The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro: - i = klen; hash = 0; - s = key; - while (i--) - hash = hash * 33 + *s++; + while (klen--) + hash = (hash * 33) + *key++; See L<Understanding the Magic of Tied Hashes and Arrays> for more information on how to use the hash access functions on tied hashes. @@ -488,7 +497,7 @@ reference is rv. SV is blessed if C<classname> is non-null. Copies string into an SV whose reference is C<rv>. Set length to 0 to let Perl calculate the string length. SV is blessed if C<classname> is non-null. - SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length); + SV* sv_setref_pvn(SV* rv, char* classname, PV iv, STRLEN length); Tests whether the SV is blessed into the specified class. It does not check inheritance relationships. @@ -861,7 +870,20 @@ C<mg_ptr> field points to a C<ufuncs> structure: When the SV is read from or written to, the C<uf_val> or C<uf_set> function will be called with C<uf_index> as the first arg and a -pointer to the SV as the second. +pointer to the SV as the second. A simple example of how to add 'U' +magic is shown below. Note that the ufuncs structure is copied by +sv_magic, so you can safely allocate it on the stack. + + void + Umagic(sv) + SV *sv; + PREINIT: + struct ufuncs uf; + CODE: + uf.uf_val = &my_get_fn; + uf.uf_set = &my_set_fn; + uf.uf_index = 0; + sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf)); Note that because multiple extensions may be using '~' or 'U' magic, it is important for extensions to take extra care to avoid conflict. @@ -907,6 +929,33 @@ in later releases, and are bracketed with [MAYCHANGE] below. If you find yourself actually applying such information in this section, be aware that the behavior may change in the future, umm, without warning. +The perl tie function associates a variable with an object that implements +the various GET, SET etc methods. To perform the equivalent of the perl +tie function from an XSUB, you must mimic this behaviour. The code below +carries out the necessary steps - firstly it creates a new hash, and then +creates a second hash which it blesses into the class which will implement +the tie methods. Lastly it ties the two hashes together, and returns a +reference to the new tied hash. Note that the code below does NOT call the +TIEHASH method in the MyTie class - +see L<Calling Perl Routines from within C Programs> for details on how +to do this. + + SV* + mytie() + PREINIT: + HV *hash; + HV *stash; + SV *tie; + CODE: + hash = newHV(); + tie = newRV_noinc((SV*)newHV()); + stash = gv_stashpv("MyTie", TRUE); + sv_bless(tie, stash); + hv_magic(hash, tie, 'P'); + RETVAL = newRV_noinc(hash); + OUTPUT: + RETVAL + The C<av_store> function, when given a tied array argument, merely copies the magic of the array onto the value to be "stored", using C<mg_copy>. It may also return NULL, indicating that the value did not @@ -982,13 +1031,13 @@ There is a way to achieve a similar task from C via Perl API: create a I<pseudo-block>, and arrange for some changes to be automatically undone at the end of it, either explicit, or via a non-local exit (via die()). A I<block>-like construct is created by a pair of -C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a -Scalar">). Such a construct may be created specially for some -important localized task, or an existing one (like boundaries of -enclosing Perl subroutine/block, or an existing pair for freeing TMPs) -may be used. (In the second case the overhead of additional -localization must be almost negligible.) Note that any XSUB is -automatically enclosed in an C<ENTER>/C<LEAVE> pair. +C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">). +Such a construct may be created specially for some important localized +task, or an existing one (like boundaries of enclosing Perl +subroutine/block, or an existing pair for freeing TMPs) may be +used. (In the second case the overhead of additional localization must +be almost negligible.) Note that any XSUB is automatically enclosed in +an C<ENTER>/C<LEAVE> pair. Inside such a I<pseudo-block> the following service is available: @@ -1193,7 +1242,12 @@ consult L<perlcall>. =head2 Memory Allocation -It is suggested that you use the version of malloc that is distributed +All memory meant to be used with the Perl API functions should be manipulated +using the macros described in this section. The macros provide the necessary +transparency between differences in the actual malloc implementation that is +used within perl. + +It is suggested that you enable the version of malloc that is distributed with Perl. It keeps pools of various sizes of unallocated memory in order to satisfy allocation requests more quickly. However, on some platforms, it may cause spurious malloc or free errors. @@ -1460,7 +1514,7 @@ It is strongly recommended that all Perl API functions that don't begin with C<perl> be referenced with an explicit C<Perl_> prefix. The sort order of the listing is case insensitive, with any -occurrences of '_' ignored for the the purpose of sorting. +occurrences of '_' ignored for the purpose of sorting. =over 8 @@ -1594,7 +1648,7 @@ the SV which holds the name of the sub being debugged. This is the C variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>. The sub name can be found by - SvPV( GvSV( PL_DBsub ), PL_na ) + SvPV( GvSV( PL_DBsub ), len ) =item PL_DBtrace @@ -1731,7 +1785,7 @@ method's CV, which can be obtained from the GV with the C<GvCV> macro. =item gv_fetchmethod_autoload Returns the glob which contains the subroutine to call to invoke the -method on the C<stash>. In fact in the presense of autoloading this may +method on the C<stash>. In fact in the presence of autoloading this may be the glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is already setup. @@ -1814,7 +1868,8 @@ Returns the key slot of the hash entry as a C<char*> value, doing any necessary dereferencing of possibly C<SV*> keys. The length of the string is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do not care about what the length of the key is, -you may use the global variable C<PL_na>. Remember though, that hash +you may use the global variable C<PL_na>, though this is rather less +efficient than using a local variable. Remember though, that hash keys in perl are free to contain embedded nulls, so using C<strlen()> or similar is not a good way to find the length of hash keys. This is very similar to the C<SvPV()> macro described elsewhere in @@ -1855,15 +1910,6 @@ Clears a hash, making it empty. void hv_clear (HV* tb) -=item hv_delayfree_ent - -Releases a hash entry, such as while iterating though the hash, but -delays actual freeing of key and value until the end of the current -statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext> -and C<hv_free_ent>. - - void hv_delayfree_ent (HV* hv, HE* entry) - =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the hash @@ -1923,13 +1969,6 @@ information on how to use this function on tied hashes. HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash) -=item hv_free_ent - -Releases a hash entry, such as while iterating though the hash. See -C<hv_iternext> and C<hv_delayfree_ent>. - - void hv_free_ent (HV* hv, HE* entry) - =item hv_iterinit Prepares a starting point to traverse a hash table. @@ -2143,6 +2182,14 @@ Do magic after a value is assigned to the SV. See C<sv_magic>. int mg_set (SV* sv) +=item modglobal + +C<modglobal> is a general purpose, interpreter global HV for use by +extensions that need to keep information on a per-interpreter basis. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. + =item Move The XSUB-writer's interface to the C C<memmove> function. The C<s> is the @@ -2153,8 +2200,9 @@ the type. Can do overlapping moves. See also C<Copy>. =item PL_na -A variable which may be used with C<SvPV> to tell Perl to calculate the -string length. +A convenience variable which is typically used with C<SvPV> when one doesn't +care about the length of the string. It is usually more efficient to +declare a local variable and use that instead. =item New @@ -2632,7 +2680,7 @@ Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. Like C<sv_catpv>, but also handles 'set' magic. - void sv_catpvn (SV* sv, char* ptr) + void sv_catpv_mg (SV* sv, const char* ptr) =item sv_catpvn @@ -2703,7 +2751,7 @@ Returns the length of the string which is in the SV. See C<SvLEN>. Set the length of the string which is in the SV. See C<SvCUR>. - void SvCUR_set (SV* sv, int val ) + void SvCUR_set (SV* sv, int val) =item sv_dec @@ -2713,13 +2761,6 @@ Auto-decrement of the value in the SV. =item sv_derived_from -Returns a boolean indicating whether the SV is a subclass of the -specified class. - - int sv_derived_from(SV* sv, char* class) - -=item sv_derived_from - Returns a boolean indicating whether the SV is derived from the specified class. This is the function that implements C<UNIVERSAL::isa>. It works for class names as well as for objects. @@ -2745,7 +2786,7 @@ identical. Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its argument more than once. - void SvGETMAGIC( SV *sv ) + void SvGETMAGIC(SV *sv) =item SvGROW @@ -2754,7 +2795,7 @@ indicated number of bytes (remember to reserve space for an extra trailing NUL character). Calls C<sv_grow> to perform the expansion if necessary. Returns a pointer to the character buffer. - char* SvGROW( SV* sv, int len ) + char* SvGROW(SV* sv, STRLEN len) =item sv_grow @@ -2825,13 +2866,13 @@ will return false. =item SvIV -Returns the integer which is in the SV. +Coerces the given SV to an integer and returns it. int SvIV (SV* sv) =item SvIVX -Returns the integer which is stored in the SV. +Returns the integer which is stored in the SV, assuming SvIOK is true. int SvIVX (SV* sv) @@ -2923,13 +2964,13 @@ B<private> setting. Use C<SvNOK>. =item SvNV -Returns the double which is stored in the SV. +Coerce the given SV to a double and return it. double SvNV (SV* sv) =item SvNVX -Returns the double which is stored in the SV. +Returns the double which is stored in the SV, assuming SvNOK is true. double SvNVX (SV* sv) @@ -2982,18 +3023,16 @@ Checks the B<private> setting. Use C<SvPOK>. =item SvPV Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. If C<len> is C<PL_na> then Perl will -handle the length on its own. Handles 'get' magic. +if the SV does not contain a string. Handles 'get' magic. - char* SvPV (SV* sv, int len ) + char* SvPV (SV* sv, STRLEN len) =item SvPV_force Like <SvPV> but will force the SV into becoming a string (SvPOK). You want force if you are going to update the SvPVX directly. - char* SvPV_force(SV* sv, int len) - + char* SvPV_force(SV* sv, STRLEN len) =item SvPVX @@ -3081,13 +3120,13 @@ Like C<sv_setnv>, but also handles 'set' magic. Copies a string into an SV. The string must be null-terminated. Does not handle 'set' magic. See C<sv_setpv_mg>. - void sv_setpv (SV* sv, char* ptr) + void sv_setpv (SV* sv, const char* ptr) =item sv_setpv_mg Like C<sv_setpv>, but also handles 'set' magic. - void sv_setpv_mg (SV* sv, char* ptr) + void sv_setpv_mg (SV* sv, const char* ptr) =item sv_setpviv @@ -3107,13 +3146,13 @@ Like C<sv_setpviv>, but also handles 'set' magic. Copies a string into an SV. The C<len> parameter indicates the number of bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>. - void sv_setpvn (SV* sv, char* ptr, STRLEN len) + void sv_setpvn (SV* sv, const char* ptr, STRLEN len) =item sv_setpvn_mg Like C<sv_setpvn>, but also handles 'set' magic. - void sv_setpvn_mg (SV* sv, char* ptr, STRLEN len) + void sv_setpvn_mg (SV* sv, const char* ptr, STRLEN len) =item sv_setpvf @@ -3361,13 +3400,13 @@ appending it. =item SvUV -Returns the unsigned integer which is in the SV. +Coerces the given SV to an unsigned integer and returns it. UV SvUV(SV* sv) =item SvUVX -Returns the unsigned integer which is stored in the SV. +Returns the unsigned integer which is stored in the SV, assuming SvIOK is true. UV SvUVX(SV* sv) |
