X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlguts.pod;h=c41778c4644fcf68ba58b9265e3379881d84eeed;hb=08105a92a3e1f0f7ac18e8807e8c0cad635b748a;hp=9c4831faa2f9c0341e94796e83c0cb1f1569cb74;hpb=86cb71737ed277fd6cd123008b871f7a00c2944b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 9c4831f..c41778c 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -38,8 +38,8 @@ The six routines are: SV* newSViv(IV); SV* newSVnv(double); - SV* newSVpv(char*, int); - SV* newSVpvn(char*, int); + SV* newSVpv(const char*, int); + SV* newSVpvn(const char*, int); SV* newSVpvf(const char*, ...); SV* newSVsv(SV*); @@ -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*); @@ -150,8 +150,8 @@ But note that these last three macros are valid only if C is true. If you want to append something to the end of string stored in an C, you can use the following functions: - void sv_catpv(SV*, char*); - void sv_catpvn(SV*, char*, int); + void sv_catpv(SV*, const char*); + void sv_catpvn(SV*, const char*, int); void sv_catpvf(SV*, const char*, ...); void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_catsv(SV*, SV*); @@ -297,8 +297,8 @@ To create an HV, you use the following routine: 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); + SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash); + SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval); The C parameter is the length of the key being passed in (Note that you cannot pass 0 in as a value of C to tell Perl to measure the @@ -316,8 +316,8 @@ not NULL before dereferencing it. These two functions check if a hash table entry exists, and deletes it. - bool hv_exists(HV*, char* key, U32 klen); - SV* hv_delete(HV*, char* key, U32 klen, I32 flags); + bool hv_exists(HV*, const char* key, U32 klen); + SV* hv_delete(HV*, const char* key, U32 klen, I32 flags); If C does not include the C flag then C will create and return a mortal copy of the deleted value. @@ -487,28 +487,28 @@ Upgrades rv to reference if not already one. Creates new SV for rv to point to. If C is non-null, the SV is blessed into the specified class. SV is returned. - SV* newSVrv(SV* rv, char* classname); + SV* newSVrv(SV* rv, const char* classname); Copies integer or double into an SV whose reference is C. SV is blessed if C is non-null. - SV* sv_setref_iv(SV* rv, char* classname, IV iv); - SV* sv_setref_nv(SV* rv, char* classname, NV iv); + SV* sv_setref_iv(SV* rv, const char* classname, IV iv); + SV* sv_setref_nv(SV* rv, const char* classname, NV iv); Copies the pointer value (I) into an SV whose reference is rv. SV is blessed if C is non-null. - SV* sv_setref_pv(SV* rv, char* classname, PV iv); + SV* sv_setref_pv(SV* rv, const char* classname, PV iv); Copies string into an SV whose reference is C. Set length to 0 to let Perl calculate the string length. SV is blessed if C is non-null. - SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length); + SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, int length); Tests whether the SV is blessed into the specified class. It does not check inheritance relationships. - int sv_isa(SV* sv, char* name); + int sv_isa(SV* sv, const char* name); Tests whether the SV is a reference to a blessed object. @@ -518,7 +518,7 @@ Tests whether the SV is derived from the specified class. SV can be either a reference to a blessed object or a string containing a class name. This is the function implementing the C functionality. - bool sv_derived_from(SV* sv, char* name); + bool sv_derived_from(SV* sv, const char* name); To check if you've got an object derived from a specific class you have to write: @@ -641,7 +641,7 @@ in the stash "Baz::" in "Bar::"'s stash. To get the stash pointer for a particular package, use the function: - HV* gv_stashpv(char* name, I32 create) + HV* gv_stashpv(const char* name, I32 create) HV* gv_stashsv(SV*, I32 create) The first function takes a literal string, the second uses the string stored @@ -739,7 +739,7 @@ Note this is current as of patchlevel 0, and could change at any time. Perl adds magic to an SV using the sv_magic function: - void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen); + void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen); The C argument is a pointer to the SV that is to acquire a new magical feature. @@ -918,7 +918,7 @@ This routine returns a pointer to the C structure stored in the SV. If the SV does not have that magical feature, C is returned. Also, if the SV is not of type SVt_PVMG, Perl may core dump. - int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen); + int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen); This routine checks to see what types of magic C has. If the mg_type field is an uppercase letter, then the mg_obj is copied to C, but @@ -1213,9 +1213,9 @@ There are four routines that can be used to call a Perl subroutine from within a C program. These four are: I32 perl_call_sv(SV*, I32); - I32 perl_call_pv(char*, I32); - I32 perl_call_method(char*, I32); - I32 perl_call_argv(char*, I32, register char**); + I32 perl_call_pv(const char*, I32); + I32 perl_call_method(const char*, I32); + I32 perl_call_argv(const char*, I32, register char**); The routine most often used is C. The C argument contains either the name of the Perl subroutine to be called, or a @@ -1784,7 +1784,7 @@ which is not 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, char* name, STRLEN len, I32 level) + GV* gv_fetchmeth (HV* stash, const char* name, STRLEN len, I32 level) =item gv_fetchmethod @@ -1813,8 +1813,8 @@ 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. - GV* gv_fetchmethod (HV* stash, char* name) - GV* gv_fetchmethod_autoload (HV* stash, char* name, I32 autoload) + GV* gv_fetchmethod (HV* stash, const char* name) + GV* gv_fetchmethod_autoload (HV* stash, const char* name, I32 autoload) =item G_VOID @@ -1826,7 +1826,7 @@ 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. - HV* gv_stashpv (char* name, I32 create) + HV* gv_stashpv (const char* name, I32 create) =item gv_stashsv @@ -1923,7 +1923,7 @@ 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. - SV* hv_delete (HV* tb, char* key, U32 klen, I32 flags) + SV* hv_delete (HV* tb, const char* key, U32 klen, I32 flags) =item hv_delete_ent @@ -1939,7 +1939,7 @@ hash value, or 0 to ask for it to be computed. Returns a boolean indicating whether the specified hash key exists. The C is the length of the key. - bool hv_exists (HV* tb, char* key, U32 klen) + bool hv_exists (HV* tb, const char* key, U32 klen) =item hv_exists_ent @@ -1958,7 +1958,7 @@ dereferencing it to a C. See L for more information on how to use this function on tied hashes. - SV** hv_fetch (HV* tb, char* key, U32 klen, I32 lval) + SV** hv_fetch (HV* tb, const char* key, U32 klen, I32 lval) =item hv_fetch_ent @@ -2050,7 +2050,7 @@ before the call, and decrementing it if the function returned NULL. See L for more information on how to use this function on tied hashes. - SV** hv_store (HV* tb, char* key, U32 klen, SV* val, U32 hash) + SV** hv_store (HV* tb, const char* key, U32 klen, SV* val, U32 hash) =item hv_store_ent @@ -2150,7 +2150,7 @@ Clear something magical that the SV represents. See C. Copies the magic from one SV to another. See C. - int mg_copy (SV *, SV *, char *, STRLEN) + int mg_copy (SV *, SV *, const char *, STRLEN) =item mg_find @@ -2288,7 +2288,7 @@ SV is set to 1. Creates a new SV and copies a string into it. The reference count for the SV is set to 1. If C is zero then Perl will compute the length. - SV* newSVpv (char* s, STRLEN len) + SV* newSVpv (const char* s, STRLEN len) =item newSVpvf @@ -2303,7 +2303,7 @@ Creates a new SV and copies a string into it. The reference count for the SV is set to 1. If C is zero then Perl will create a zero length string. - SV* newSVpvn (char* s, STRLEN len) + SV* newSVpvn (const char* s, STRLEN len) =item newSVrv @@ -2312,7 +2312,7 @@ 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, char* classname) + SV* newSVrv (SV* rv, const char* classname) =item newSVsv @@ -2368,20 +2368,20 @@ Allocates a new Perl interpreter. See L. Performs a callback to the specified Perl sub. See L. - I32 perl_call_argv (char* subname, I32 flags, char** argv) + I32 perl_call_argv (const char* subname, I32 flags, char** argv) =item perl_call_method Performs a callback to the specified Perl method. The blessed object must be on the stack. See L. - I32 perl_call_method (char* methname, I32 flags) + I32 perl_call_method (const char* methname, I32 flags) =item perl_call_pv Performs a callback to the specified Perl sub. See L. - I32 perl_call_pv (char* subname, I32 flags) + I32 perl_call_pv (const char* subname, I32 flags) =item perl_call_sv @@ -2408,7 +2408,7 @@ Tells Perl to C the string in the SV. Tells Perl to C the given string and return an SV* result. - SV* perl_eval_pv (char* p, I32 croak_on_error) + SV* perl_eval_pv (const char* p, I32 croak_on_error) =item perl_free @@ -2420,7 +2420,7 @@ Returns the AV of the specified Perl array. If C is set and the Perl variable does not exist then it will be created. If C is not set and the variable does not exist then NULL is returned. - AV* perl_get_av (char* name, I32 create) + AV* perl_get_av (const char* name, I32 create) =item perl_get_cv @@ -2428,7 +2428,7 @@ Returns the CV of the specified Perl sub. If C is set and the Perl variable does not exist then it will be created. If C is not set and the variable does not exist then NULL is returned. - CV* perl_get_cv (char* name, I32 create) + CV* perl_get_cv (const char* name, I32 create) =item perl_get_hv @@ -2436,7 +2436,7 @@ Returns the HV of the specified Perl hash. If C is set and the Perl variable does not exist then it will be created. If C is not set and the variable does not exist then NULL is returned. - HV* perl_get_hv (char* name, I32 create) + HV* perl_get_hv (const char* name, I32 create) =item perl_get_sv @@ -2444,7 +2444,7 @@ Returns the SV of the specified Perl scalar. If C is set and the Perl variable does not exist then it will be created. If C is not set and the variable does not exist then NULL is returned. - SV* perl_get_sv (char* name, I32 create) + SV* perl_get_sv (const char* name, I32 create) =item perl_parse @@ -2454,7 +2454,7 @@ Tells a Perl interpreter to parse a Perl script. See L. Tells Perl to C a module. - void perl_require_pv (char* pv) + void perl_require_pv (const char* pv) =item perl_run @@ -2574,14 +2574,14 @@ The XSUB-writer's interface to the C C function. Copy a string to a safe spot. This does not use an SV. - char* savepv (char* sv) + char* savepv (const char* sv) =item savepvn Copy a string to a safe spot. The C indicates number of bytes to copy. This does not use an SV. - char* savepvn (char* sv, I32 len) + char* savepvn (const char* sv, I32 len) =item SAVETMPS @@ -2681,13 +2681,13 @@ of the SV is unaffected. Concatenates the string onto the end of the string which is in the SV. Handles 'get' magic, but not 'set' magic. See C. - void sv_catpv (SV* sv, char* ptr) + void sv_catpv (SV* sv, const char* ptr) =item sv_catpv_mg Like C, but also handles 'set' magic. - void sv_catpvn (SV* sv, char* ptr) + void sv_catpvn (SV* sv, const char* ptr) =item sv_catpvn @@ -2695,13 +2695,13 @@ Concatenates the string onto the end of the string which is in the SV. The C indicates number of bytes to copy. Handles 'get' magic, but not 'set' magic. See C. - void sv_catpvn (SV* sv, char* ptr, STRLEN len) + void sv_catpvn (SV* sv, const char* ptr, STRLEN len) =item sv_catpvn_mg Like C, but also handles 'set' magic. - void sv_catpvn_mg (SV* sv, char* ptr, STRLEN len) + void sv_catpvn_mg (SV* sv, const char* ptr, STRLEN len) =item sv_catpvf @@ -2737,7 +2737,7 @@ buffer. SvPOK(sv) must be true and the C must be a pointer to somewhere inside the string buffer. The C becomes the first character of the adjusted string. - void sv_chop(SV* sv, char *ptr) + void sv_chop(SV* sv, const char *ptr) =item sv_cmp @@ -2758,7 +2758,7 @@ Returns the length of the string which is in the SV. See C. Set the length of the string which is in the SV. See C. - void SvCUR_set (SV* sv, int val ) + void SvCUR_set (SV* sv, int val) =item sv_dec @@ -2768,18 +2768,11 @@ 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. It works for class names as well as for objects. - bool sv_derived_from _((SV* sv, char* name)); + bool sv_derived_from _((SV* sv, const char* name)); =item SvEND @@ -2800,7 +2793,7 @@ identical. Invokes C 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 @@ -2809,7 +2802,7 @@ indicated number of bytes (remember to reserve space for an extra trailing NUL character). Calls C to perform the expansion if necessary. Returns a pointer to the character buffer. - char* SvGROW( SV* sv, STRLEN len ) + char* SvGROW(SV* sv, STRLEN len) =item sv_grow @@ -2906,7 +2899,7 @@ Returns the length of the string in the SV. Use C. Adds magic to an SV. - void sv_magic (SV* sv, SV* obj, int how, char* name, I32 namlen) + void sv_magic (SV* sv, SV* obj, int how, const char* name, I32 namlen) =item sv_mortalcopy @@ -3141,13 +3134,13 @@ Like C, but also handles 'set' magic. Copies a string into an SV. The string must be null-terminated. Does not handle 'set' magic. See C. - void sv_setpv (SV* sv, char* ptr) + void sv_setpv (SV* sv, const char* ptr) =item sv_setpv_mg Like C, 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 @@ -3167,13 +3160,13 @@ Like C, but also handles 'set' magic. Copies a string into an SV. The C parameter indicates the number of bytes to be copied. Does not handle 'set' magic. See C. - 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, 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