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*);
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*);
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.
SvIV(SV*)
SvNV(SV*)
SvPV(SV*, STRLEN len)
+ SvPV_nolen(SV*)
which will automatically coerce the actual scalar type into an IV, double,
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>, though
-this is rather less efficient than using a local variable. Remember,
-however, that Perl allows arbitrary strings of data that may both contain
-NULs and might not be terminated by a NUL.
+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 C<SvPV_nolen> macro.
+Historically the C<SvPV> macro with the global variable C<PL_na> has been
+used in this case. But that 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:
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_catpv(SV*, const char*);
+ void sv_catpvn(SV*, const 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*);
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<klen> parameter is the length of the key being passed in (Note that
you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
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<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
create and return a mortal copy of the deleted value.
point to. If C<classname> 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<rv>. SV is blessed
if C<classname> 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<the address, not the string!>) into an SV whose
reference is rv. SV is blessed if C<classname> 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<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, const char* classname, PV iv, STRLEN 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.
a reference to a blessed object or a string containing a class name. This
is the function implementing the C<UNIVERSAL::isa> 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:
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
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<sv> argument is a pointer to the SV that is to acquire a new magical
feature.
If the SV does not have that magical feature, C<NULL> 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<sv> has. If the mg_type
field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
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<perl_call_sv>. The C<SV*> argument
contains either the name of the Perl subroutine to be called, or a
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<GvCV> 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
=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.
The warning against passing the GV returned by C<gv_fetchmeth> to
C<perl_call_sv> 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
then the package will be created if it does not already exist. If C<create>
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
C<flags> 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
Returns a boolean indicating whether the specified hash key exists. The
C<klen> 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
See L<Understanding the Magic of Tied Hashes and Arrays> 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
See L<Understanding the Magic of Tied Hashes and Arrays> 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
Copies the magic from one SV to another. See C<sv_magic>.
- int mg_copy (SV *, SV *, char *, STRLEN)
+ int mg_copy (SV *, SV *, const char *, STRLEN)
=item mg_find
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.
+either declare a local variable and use that instead or to use the C<SvPV_nolen>
+macro.
=item New
=item newSVpv
Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero then Perl will compute the length.
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
- SV* newSVpv (char* s, STRLEN len)
+ SV* newSVpv (const char* s, STRLEN len)
=item newSVpvf
Creates a new SV an initialize it with the string formatted like
C<sprintf>.
- SV* newSVpvf(const char* pat, ...);
+ SV* newSVpvf(const char* pat, ...)
=item newSVpvn
Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero then Perl will create a zero length
-string.
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long.
- SV* newSVpvn (char* s, STRLEN len)
+ SV* newSVpvn (const char* s, STRLEN len)
=item newSVrv
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
Performs a callback to the specified Perl sub. See L<perlcall>.
- 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<perlcall>.
- 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<perlcall>.
- I32 perl_call_pv (char* subname, I32 flags)
+ I32 perl_call_pv (const char* subname, I32 flags)
=item perl_call_sv
Tells Perl to C<eval> 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
Perl variable does not exist then it will be created. If C<create> 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
-Returns the CV of the specified Perl sub. If C<create> is set and the Perl
-variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+Returns the CV of the specified Perl subroutine. If C<create> is set and
+the Perl subroutine does not exist then it will be declared (which has
+the same effect as saying C<sub name;>). If C<create> is not
+set and the subroutine 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
variable does not exist then it will be created. If C<create> 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
Perl variable does not exist then it will be created. If C<create> 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
Tells Perl to C<require> a module.
- void perl_require_pv (char* pv)
+ void perl_require_pv (const char* pv)
=item perl_run
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<len> 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
Concatenates the string onto the end of the string which is in the SV.
Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
- void sv_catpv (SV* sv, char* ptr)
+ void sv_catpv (SV* sv, const char* ptr)
=item sv_catpv_mg
Like C<sv_catpv>, but also handles 'set' magic.
- void sv_catpvn (SV* sv, char* ptr)
+ void sv_catpvn (SV* sv, const char* ptr)
=item sv_catpvn
C<len> indicates number of bytes to copy. Handles 'get' magic, but not
'set' magic. See C<sv_catpvn_mg>.
- 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<sv_catpvn>, 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
somewhere inside the string buffer. The C<ptr> 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
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
=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.
- bool sv_derived_from _((SV* sv, char* name));
+ bool sv_derived_from (SV* sv, const char* name);
=item SvEND
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
trailing NUL character). Calls C<sv_grow> 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
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
Returns a pointer to the string in the SV, or a stringified form of the SV
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 SvPV_nolen
+
+Returns a pointer to the string in the SV, or a stringified form of the SV
+if the SV does not contain a string. Handles 'get' magic.
+ char* SvPV_nolen (SV* sv)
=item SvPVX
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
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
to an SV. Uses an array of SVs if the C style variable argument list is
missing (NULL). Indicates if locale information has been used for formatting.
- void sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen,
- va_list *args, SV **svargs, I32 svmax,
- bool *used_locale));
+ void sv_catpvfn (SV* sv, const char* pat, STRLEN patlen,
+ va_list *args, SV **svargs, I32 svmax,
+ bool *used_locale);
=item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale)
Works like C<vcatpvfn> but copies the text into the SV instead of
appending it.
- void sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen,
- va_list *args, SV **svargs, I32 svmax,
- bool *used_locale));
+ void sv_setpvfn (SV* sv, const char* pat, STRLEN patlen,
+ va_list *args, SV **svargs, I32 svmax,
+ bool *used_locale);
=item SvUV
https://perl5.git.perl.org / perl5.git / blobdiff