better POD for mg_get and SvGROW

SvGROW unconditionally derefs SvANY to check SvLEN. A crash occurs if the
sv is SVt_NULL. Also mg_get uses SvMAGIC which also has the same problem.
Rather than having people finding these properties out by trial and error,
document them. There is no sense in adding type checks since these 2 calls
have been had sv type restrictions since probably day 1 and for
performance reason. Anyone who hit the restrictions would have either
fixed their code immediately, or abandoned using XS. I observed someone
abandoning XS in the field over these undocumented restrictions.

diff --git a/mg.c b/mg.c
index 2d063db..e4711e7 100644 (file)
--- a/mg.c
+++ b/mg.c
@@ -162,7 +162,8 @@ Perl_mg_magical(pTHX_ SV *sv)
 /*
 =for apidoc mg_get
 
-Do magic before a value is retrieved from the SV.  See C<sv_magic>.
+Do magic before a value is retrieved from the SV.  The type of SV must
+be >= SVt_PVMG. See C<sv_magic>.
 
 =cut
 */

diff --git a/sv.h b/sv.h
index bea0a2f..e3c2673 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -2010,7 +2010,8 @@ has been loaded.
 Expands the character buffer in the SV so that it has room for the
 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.
+Returns a pointer to the character buffer. SV must be of type >= SVt_PV. One
+alternative is to call C<sv_grow> if you are not sure of the type of SV.
 
 =cut
 */