This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Document SvPV_free
authorKarl Williamson <khw@cpan.org>
Thu, 8 Oct 2020 20:14:46 +0000 (14:14 -0600)
committerKarl Williamson <khw@cpan.org>
Sat, 31 Oct 2020 17:52:08 +0000 (11:52 -0600)
sv.h

diff --git a/sv.h b/sv.h
index 4b6fe93..b946568 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -824,8 +824,8 @@ Remember to free the previous PV buffer. There are many things to check.
 Beware that the existing pointer may be involved in copy-on-write or other
 mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
 C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
 Beware that the existing pointer may be involved in copy-on-write or other
 mischief, so do C<SvOOK_off(sv)> and use C<sv_force_normal> or
 C<SvPV_force> (or check the C<SvIsCOW> flag) first to make sure this
-modification is safe. Then finally, if it is not a COW, call C<SvPV_free> to
-free the previous PV buffer.
+modification is safe. Then finally, if it is not a COW, call
+C<L</SvPV_free>> to free the previous PV buffer.
 
 =for apidoc Am|void|SvUV_set|SV* sv|UV val
 Set the value of the UV pointer in C<sv> to val.  See C<L</SvIV_set>>.
 
 =for apidoc Am|void|SvUV_set|SV* sv|UV val
 Set the value of the UV pointer in C<sv> to val.  See C<L</SvIV_set>>.
@@ -1380,6 +1380,14 @@ object type. Exposed to perl code via Internals::SvREADONLY().
                   SvPV_renew(sv, _lEnGtH); \
                 } STMT_END
 
                   SvPV_renew(sv, _lEnGtH); \
                 } STMT_END
 
+/*
+=for apidoc Am|void|SvPV_free|SV * sv
+
+Frees the PV buffer in C<sv>, leaving things in a precarious state, so should
+only be used as part of a larger operation
+
+=cut
+*/
 #define SvPV_free(sv)                                                  \
     STMT_START {                                                       \
                     assert(SvTYPE(sv) >= SVt_PV);                      \
 #define SvPV_free(sv)                                                  \
     STMT_START {                                                       \
                     assert(SvTYPE(sv) >= SVt_PV);                      \