From: Perl 5 Porters Date: Mon, 23 Sep 1996 20:18:01 +0000 (-0500) Subject: perl 5.003_06: pod/perlguts.pod X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=5fb8527f855f7e23052ad5a5c551df5b3e59d79c;p=p5sagit%2Fp5-mst-13.2.git perl 5.003_06: pod/perlguts.pod Date: Wed, 11 Sep 1996 11:55:18 -0500 From: "Daniel S. Lewart" Subject: POD spelling patches Date: Mon, 23 Sep 96 13:18:01 PDT From: Jeff Okamoto Subject: Re: perlguts API Listing patch Here's the lastest complete version for inclusion into _06 or .004. This incorporates and supersedes Dean's patch. Date: Fri, 20 Sep 1996 15:08:33 +0100 (BST) From: "Joseph S. Myers" Subject: Pod typos, pod2man bugs, and miscellaneous installation comments Here is a patch for various typos and other defects in the Perl 5.003_05 pods, including the pods embedded in library modules. --- diff --git a/pod/perlguts.pod b/pod/perlguts.pod index d849fe1..2e89807 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -26,7 +26,7 @@ integer or a pointer. Perl also uses two special typedefs, I32 and I16, which will always be at least 32-bits and 16-bits long, respectively. -=head2 Working with SV's +=head2 Working with SVs An SV can be created and loaded with one command. There are four types of values that can be loaded: an integer value (IV), a double (NV), a string, @@ -39,7 +39,7 @@ The four routines are: SV* newSVpv(char*, int); SV* newSVsv(SV*); -To change the value of an I SV, there are five routines: +To change the value of an *already-existing* SV, there are five routines: void sv_setiv(SV*, IV); void sv_setnv(SV*, double); @@ -67,7 +67,7 @@ In the C macro, the length of the string returned is placed into the variable C (this is a macro, so you do I use C<&len>). If you do not care what the length of the data is, use the global variable C. Remember, however, that Perl allows arbitrary strings of data that may both contain -NUL's and not be terminated by a NUL. +NULs and not be terminated by a NUL. If you simply want to know if the scalar value is TRUE, you can use: @@ -172,21 +172,21 @@ stored in your SV. The "p" stands for private. In general, though, it's best to just use the C macros. -=head2 Working with AV's +=head2 Working with AVs There are two ways to create and load an AV. The first method just creates an empty AV: AV* newAV(); -The second method both creates the AV and initially populates it with SV's: +The second method both creates the AV and initially populates it with SVs: AV* av_make(I32 num, SV **ptr); -The second argument points to an array containing C C's. Once the -AV has been created, the SV's can be destroyed, if so desired. +The second argument points to an array containing C Cs. Once the +AV has been created, the SVs can be destroyed, if so desired. -Once the AV has been created, the following operations are possible on AV's: +Once the AV has been created, the following operations are possible on AVs: void av_push(AV*, SV*); SV* av_pop(AV*); @@ -208,7 +208,7 @@ Here are some other functions: SV** av_store(AV*, I32 key, SV* val); /* Stores val at offset key */ -Take note that C and C return C's, not C's. +Take note that C and C return Cs, not Cs. void av_clear(AV*); /* Clear out all elements, but leave the array */ @@ -224,13 +224,13 @@ by using the following: This returns NULL if the variable does not exist. -=head2 Working with HV's +=head2 Working with HVs To create an HV, you use the following routine: HV* newHV(); -Once the HV has been created, the following operations are possible on HV's: +Once the HV has been created, the following operations are possible on HVs: SV** hv_store(HV*, char* key, U32 klen, SV* val, U32 hash); SV** hv_fetch(HV*, char* key, U32 klen, I32 lval); @@ -241,7 +241,7 @@ the pre-computed hash value (zero if you want C to calculate it for you). The C parameter indicates whether this fetch is actually a part of a store operation. -Remember that C and C return C's and not just +Remember that C and C return Cs and not just C. In order to access the scalar value, you must first dereference the return value. However, you should check to make sure that the return value is not NULL before dereferencing it. @@ -345,7 +345,7 @@ A reference can be blessed into a package with the following function: SV* sv_bless(SV* sv, HV* stash); The C argument must be a reference. The C argument specifies -which class the reference will belong to. See the section on L +which class the reference will belong to. See the L<"Stashes"> for information on converting class names into stashes. /* Still under construction */ @@ -393,7 +393,7 @@ There are additional bits that may be OR'ed with the TRUE argument to enable certain extra features. Those bits are: 0x02 Marks the variable as multiply defined, thus preventing the - "Indentifier used only once: possible typo" warning. + "Identifier used only once: possible typo" warning. 0x04 Issues a "Had to create unexpectedly" warning if the variable didn't actually exist. This is useful if you expected the variable to already exist and want to propagate @@ -402,7 +402,7 @@ certain extra features. Those bits are: If the C argument does not contain a package specifier, it is created in the current package. -=head1 XSUB's and the Argument Stack +=head1 XSUBs and the Argument Stack The XSUB mechanism is a simple way for Perl programs to access C subroutines. An XSUB routine will have a stack that contains the arguments from the Perl @@ -428,7 +428,7 @@ where C is the stack pointer, and C is the number of elements the stack should be extended by. Now that there is room on the stack, values can be pushed on it using the -macros to push IV's, doubles, strings, and SV pointers respectively: +macros to push IVs, doubles, strings, and SV pointers respectively: PUSHi(IV) PUSHn(double) @@ -463,10 +463,10 @@ Add cruft about reference counts. void SvREFCNT_inc(SV* sv); void SvREFCNT_dec(SV* sv); -In the above example with C, we needed to create two new SV's to push +In the above example with C, we needed to create two new SVs to push onto the argument stack, that being the two strings. However, we don't want -these new SV's to stick around forever because they will eventually be -copied into the SV's that hold the two scalar variables. +these new SVs to stick around forever because they will eventually be +copied into the SVs that hold the two scalar variables. An SV (or AV or HV) that is "mortal" acts in all ways as a normal "immortal" SV, AV, or HV, but is only valid in the "current context". When the Perl @@ -483,11 +483,11 @@ To create a mortal variable, use the functions: The first call creates a mortal SV, the second converts an existing SV to a mortal SV, the third creates a mortal copy of an existing SV. -The mortal routines are not just for SV's -- AV's and HV's can be made mortal +The mortal routines are not just for SVs -- AVs and HVs can be made mortal by passing their address (and casting them to C) to the C or C routines. ->From Ilya: +From Ilya: Beware that the sv_2mortal() call is eventually equivalent to svREFCNT_dec(). A value can happily be mortal in two different contexts, and it will be svREFCNT_dec()ed twice, once on exit from these @@ -519,7 +519,7 @@ objects of that name, including (but not limited to) the following: Perl stores various stashes in a separate GV structure (for global variable) but represents them with an HV structure. The keys in this -larger GV are the various package names; the values are the C's +larger GV are the various package names; the values are the Cs which are stashes. It may help to think of a stash purely as an HV, and that the term "GV" means the global variable hash. @@ -562,11 +562,9 @@ For more information on references and blessings, consult L. [This section still under construction. Ignore everything here. Post no bills. Everything not permitted is forbidden.] -# Version 6, 1995/1/27 - Any SV may be magical, that is, it has special features that a normal SV does not have. These features are stored in the SV structure in a -linked list of C's, typedef'ed to C. +linked list of Cs, typedef'ed to C. struct magic { MAGIC* mg_moremagic; @@ -594,12 +592,12 @@ If C is not already magical, Perl uses the C macro to set the C flag for the C. Perl then continues by adding it to the beginning of the linked list of magical features. Any prior entry of the same type of magic is deleted. Note that this can be -overriden, and multiple instances of the same type of magic can be +overridden, and multiple instances of the same type of magic can be associated with an SV. The C and C arguments are used to associate a string with the magic, typically the name of a variable. C is stored in the -C field and if C is non-null and C >= 0 a malloc'd +C field and if C is non-null and C E= 0 a malloc'd copy of the name is stored in C field. The sv_magic function uses C to determine which, if any, predefined @@ -712,7 +710,7 @@ This routine checks to see what types of magic C has. If the mg_type field is an upper-case letter, then the mg_obj is copied to C, but the mg_type field is changed to be the lower-case letter. -=head1 Double-Typed SV's +=head1 Double-Typed SVs Scalar variables normally contain only one type of value, an integer, double, pointer, or reference. Perl will automatically convert the @@ -876,8 +874,9 @@ Returns the highest index in the array. Returns -1 if the array is empty. =item av_make -Creats a new AV and populates it with a list of SVs. The SVs are copied -into the array, so they may be freed after the call to av_make. +Creates a new AV and populates it with a list of SVs. The SVs are copied +into the array, so they may be freed after the call to av_make. The new AV +will have a refcount of 1. AV* av_make _((I32 size, SV** svp)); @@ -890,7 +889,8 @@ empty. =item av_push -Pushes an SV onto the end of the array. +Pushes an SV onto the end of the array. The array will grow automatically +to accommodate the addition. void av_push _((AV* ar, SV* val)); @@ -916,14 +916,16 @@ Undefines the array. =item av_unshift -Unshift an SV onto the beginning of the array. +Unshift an SV onto the beginning of the array. The array will grow +automatically to accommodate the addition. void av_unshift _((AV* ar, I32 num)); =item CLASS Variable which is setup by C to indicate the class name for a C++ XS -constructor. This is always a C. See C and L. +constructor. This is always a C. See C and +L. =item Copy @@ -948,27 +950,40 @@ Returns the stash of the CV. When Perl is run in debugging mode, with the B<-d> switch, this SV is a boolean which indicates whether subs are being single-stepped. -Single-stepping is automatically turned on after every step. See C. +Single-stepping is automatically turned on after every step. This is the C +variable which corresponds to Perl's $DB::single variable. See C. =item DBsub When Perl is run in debugging mode, with the B<-d> switch, this GV contains -the SV which holds the name of the sub being debugged. See C. +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. The sub name can be found by SvPV( GvSV( DBsub ), na ) +=item DBtrace + +Trace variable used when Perl is run in debugging mode, with the B<-d> +switch. This is the C variable which corresponds to Perl's $DB::trace +variable. See C. + =item dMARK -Declare a stack marker for the XSUB. See C and C. +Declare a stack marker variable, C, for the XSUB. See C and +C. =item dORIGMARK Saves the original stack mark for the XSUB. See C. +=item dowarn + +The C variable which corresponds to Perl's $^W warning variable. + =item dSP -Declares a stack pointer for the XSUB. See C. +Declares a stack pointer variable, C, for the XSUB. See C. =item dXSARGS @@ -976,6 +991,16 @@ Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This is usually handled automatically by C. Declares the C variable to indicate the number of items on the stack. +=item dXSI32 + +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. + +=item dXSI32 + +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. + =item ENTER Opening bracket on a callback. See C and L. @@ -1052,7 +1077,7 @@ Clears a hash, making it empty. =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the hash -and returned to the caller. The C is the length of the key. The +and returned to the caller. The C is the length of the key. The C value will normally be zero; if set to G_DISCARD then null will be returned. @@ -1061,14 +1086,14 @@ returned. =item hv_exists Returns a boolean indicating whether the specified hash key exists. The -C is the length of the key. +C is the length of the key. bool hv_exists _((HV* tb, char* key, U32 klen)); =item hv_fetch Returns the SV which corresponds to the specified key in the hash. The -C is the length of the key. If C is set then the fetch will be +C is the length of the key. If C is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to a C. @@ -1138,13 +1163,13 @@ Undefines the hash. =item isALNUM Returns a boolean indicating whether the C C is an ascii alphanumeric -character or digit. +character. int isALNUM (char c) =item isALPHA -Returns a boolean indicating whether the C C is an ascii alphanumeric +Returns a boolean indicating whether the C C is an ascii alphabetic character. int isALPHA (char c) @@ -1176,7 +1201,12 @@ Returns a boolean indicating whether the C C is an uppercase character. =item items Variable which is setup by C to indicate the number of items on the -stack. See L. +stack. See L. + +=item ix + +Variable which is setup by C to indicate which of an XSUB's aliases +was used to invoke it. See L. =item LEAVE @@ -1186,7 +1216,7 @@ Closing bracket on a callback. See C and L. =item MARK -Stack marker for the XSUB. See C. +Stack marker variable for the XSUB. See C. =item mg_clear @@ -1319,7 +1349,7 @@ set to 1. If C is zero then Perl will compute the length. =item newSVrv Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded one. If C is non-null then the new SV will +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 refcount is 1. @@ -1327,7 +1357,7 @@ refcount is 1. =item newSVsv -Creates a new SV which is an exact duplicate of the orignal SV. +Creates a new SV which is an exact duplicate of the original SV. SV* newSVsv _((SV* old)); @@ -1544,7 +1574,8 @@ The XSUB-writer's interface to the C C function, with cast. =item RETVAL Variable which is setup by C to hold the return value for an XSUB. -This is always the proper type for the XSUB. See L. +This is always the proper type for the XSUB. +See L. =item safefree @@ -1679,11 +1710,27 @@ C indicates number of bytes to copy. =item sv_catsv -Concatentates the string from SV C onto the end of the string in SV +Concatenates the string from SV C onto the end of the string in SV C. void sv_catsv _((SV* dsv, SV* ssv)); +=item sv_cmp + +Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the +string in C is less than, equal to, or greater than the string in +C. + + I32 sv_cmp _((SV* sv1, SV* sv2)); + +=item sv_cmp + +Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the +string in C is less than, equal to, or greater than the string in +C. + + I32 sv_cmp _((SV* sv1, SV* sv2)); + =item SvCUR Returns the length of the string which is in the SV. See C. @@ -1696,6 +1743,18 @@ Set the length of the string which is in the SV. See C. SvCUR_set (SV* sv, int val ) +=item sv_dec + +Autodecrement of the value in the SV. + + void sv_dec _((SV* sv)); + +=item sv_dec + +Autodecrement of the value in the SV. + + void sv_dec _((SV* sv)); + =item SvEND Returns a pointer to the last character in the string which is in the SV. @@ -1703,12 +1762,32 @@ See C. Access the character as *SvEND(sv) +=item sv_eq + +Returns a boolean indicating whether the strings in the two SVs are +identical. + + I32 sv_eq _((SV* sv1, SV* sv2)); + =item SvGROW -Expands the character buffer in the SV. +Expands the character buffer in the SV. Calls C to perform the +expansion if necessary. Returns a pointer to the character buffer. char * SvGROW( SV* sv, int len ) +=item sv_grow + +Expands the character buffer in the SV. This will use C and will +upgrade the SV to C. Returns a pointer to the character buffer. +Use C. + +=item sv_inc + +Autoincrement of the value in the SV. + + void sv_inc _((SV* sv)); + =item SvIOK Returns a boolean indicating whether the SV contains an integer. @@ -1727,6 +1806,18 @@ Tells an SV that it is an integer. SvIOK_on (SV* sv) +=item SvIOK_only + +Tells an SV that it is an integer and disables all other OK bits. + + SvIOK_on (SV* sv) + +=item SvIOK_only + +Tells an SV that it is an integer and disables all other OK bits. + + SvIOK_on (SV* sv) + =item SvIOKp Returns a boolean indicating whether the SV contains an integer. Checks the @@ -1768,6 +1859,18 @@ Returns the size of the string buffer in the SV. See C. int SvLEN (SV* sv) +=item sv_len + +Returns the length of the string in the SV. Use C. + + STRLEN sv_len _((SV* sv)); + +=item sv_len + +Returns the length of the string in the SV. Use C. + + STRLEN sv_len _((SV* sv)); + =item sv_magic Adds magic to an SV. @@ -1835,6 +1938,18 @@ Tells an SV that it is a double. SvNOK_on (SV* sv) +=item SvNOK_only + +Tells an SV that it is a double and disables all other OK bits. + + SvNOK_on (SV* sv) + +=item SvNOK_only + +Tells an SV that it is a double and disables all other OK bits. + + SvNOK_on (SV* sv) + =item SvNOKp Returns a boolean indicating whether the SV contains a double. Checks the @@ -1872,6 +1987,18 @@ Tells an SV that it is a string. SvPOK_on (SV* sv) +=item SvPOK_only + +Tells an SV that it is a string and disables all other OK bits. + + SvPOK_on (SV* sv) + +=item SvPOK_only + +Tells an SV that it is a string and disables all other OK bits. + + SvPOK_on (SV* sv) + =item SvPOKp Returns a boolean indicating whether the SV contains a character string. @@ -1962,29 +2089,32 @@ bytes to be copied. =item sv_setref_iv -Copies an integer into an SV, optionally blessing the SV. The SV must be an -RV. The C argument indicates the package for the blessing. Set -C to C to avoid the blessing. The new SV will be -returned and will have a refcount of 1. +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 +will be returned and will have a refcount of 1. SV* sv_setref_iv _((SV *rv, char *classname, IV iv)); =item sv_setref_nv -Copies a double into an SV, optionally blessing the SV. The SV must be an -RV. The C argument indicates the package for the blessing. Set -C to C to avoid the blessing. The new SV will be -returned and will have a refcount of 1. +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 +will be returned and will have a refcount of 1. SV* sv_setref_nv _((SV *rv, char *classname, double nv)); =item sv_setref_pv -Copies a pointer into an SV, optionally blessing the SV. The SV must be an -RV. 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 will be -returned and will have a refcount of 1. +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 +will be returned and will have a refcount of 1. SV* sv_setref_pv _((SV *rv, char *classname, void* pv)); @@ -1995,8 +2125,9 @@ Note that C copies the string while this copies the pointer. =item sv_setref_pvn -Copies a string into an SV, optionally blessing the SV. The lenth of the -string must be specified with C. The SV must be an RV. The C +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 be returned and will have a refcount of 1. @@ -2008,9 +2139,7 @@ Note that C copies the pointer while this copies the string. =item sv_setsv Copies the contents of the source SV C into the destination SV C. -(B If C has the C bit set, C may simply steal -the string from C and give it to C, leaving C empty. -Caveat caller.) +The source SV may be destroyed if it is mortal. void sv_setsv _((SV* dsv, SV* ssv)); @@ -2068,16 +2197,32 @@ C enum. Test these flags with the C macro. =item SvUPGRADE -Used to upgrade an SV to a more complex form. See C. +Used to upgrade an SV to a more complex form. Uses C to perform +the upgrade if necessary. See C. + + bool SvUPGRADE _((SV* sv, svtype mt)); + +=item sv_upgrade + +Upgrade an SV to a more complex form. Use C. See C. =item sv_undef This is the C SV. Always refer to this as C<&sv_undef>. +=item sv_unref + +Unsets the RV status of the SV, and decrements the refcount of whatever was +being referenced by the RV. This can almost be thought of as a reversal of +C. See C. + + void sv_unref _((SV* sv)); + =item sv_usepvn Tells an SV to use C to find its string value. Normally the string is -stored inside the SV; this allows the SV to use an outside string. The +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. @@ -2092,7 +2237,7 @@ This is the C SV. See C. Always refer to this as C<&sv_yes>. Variable which is setup by C to designate the object in a C++ XSUB. This is always the proper type for the C++ object. See C and -L. +L. =item toLOWER @@ -2138,37 +2283,110 @@ Push an SV onto the stack, extending the stack if necessary. See C. XPUSHs(sv) +=item XS + +Macro to declare an XSUB and its C parameter list. This is handled by +C. + =item XSRETURN Return from XSUB, indicating number of items on the stack. This is usually handled by C. - XSRETURN(x); + XSRETURN(int x); =item XSRETURN_EMPTY -Return from an XSUB immediately. +Return an empty list from an XSUB immediately. XSRETURN_EMPTY; +=item XSRETURN_IV + +Return an integer from an XSUB immediately. Uses C. + + XSRETURN_IV(IV v); + =item XSRETURN_NO -Return C from an XSUB immediately. +Return C<&sv_no> from an XSUB immediately. Uses C. XSRETURN_NO; +=item XSRETURN_NV + +Return an double from an XSUB immediately. Uses C. + + XSRETURN_NV(NV v); + +=item XSRETURN_PV + +Return a copy of a string from an XSUB immediately. Uses C. + + XSRETURN_PV(char *v); + =item XSRETURN_UNDEF -Return C from an XSUB immediately. +Return C<&sv_undef> from an XSUB immediately. Uses C. XSRETURN_UNDEF; =item XSRETURN_YES -Return C from an XSUB immediately. +Return C<&sv_yes> from an XSUB immediately. Uses C. XSRETURN_YES; +=item XST_mIV + +Place an integer into the specified position C on the stack. The value is +stored in a new mortal SV. + + XST_mIV( int i, IV v ); + +=item XST_mNV + +Place a double into the specified position C on the stack. The value is +stored in a new mortal SV. + + XST_mNV( int i, NV v ); + +=item XST_mNO + +Place C<&sv_no> into the specified position C on the stack. + + XST_mNO( int i ); + +=item XST_mPV + +Place a copy of a string into the specified position C on the stack. The +value is stored in a new mortal SV. + + XST_mPV( int i, char *v ); + +=item XST_mUNDEF + +Place C<&sv_undef> into the specified position C on the stack. + + XST_mUNDEF( int i ); + +=item XST_mYES + +Place C<&sv_yes> into the specified position C on the stack. + + XST_mYES( int i ); + +=item XS_VERSION + +The version identifier for an XS module. This is usually handled +automatically by C. See C. + +=item XS_VERSION_BOOTCHECK + +Macro to verify that a PM module's $VERSION variable matches the XS module's +C variable. This is usually handled automatically by +C. See L. + =item Zero The XSUB-writer's interface to the C C function. The C is the @@ -2180,15 +2398,14 @@ destination, C is the number of items, and C is the type. =head1 AUTHOR -Jeff Okamoto +Jeff Okamoto EFE With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, and Spider Boardman. -API Listing by Dean Roehrich . +API Listing by Dean Roehrich EFE. =head1 DATE -Version 20: 1995/12/14 - +Version 22: 1996/9/23