perlre: minor wordsmithing, POD formatting tweaks, etc

[perl5.git] / pod / perlguts.pod

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index cd843a0..2da946c 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -186,7 +186,7 @@ sv_insert() or sv_insert_flags().
 If you don't need the existing content of the SV, you can avoid some
 copying with:
 
-    sv_setpvn(sv, "", 0);
+    SvPVCLEAR(sv);
     s = SvGROW(sv, needlen + 1);
     /* something that modifies up to needlen bytes at s, but modifies
        newlen bytes
@@ -1087,8 +1087,9 @@ referring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
 The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
 structure.  If it is not the same as the C<sv> argument, the reference
 count of the C<obj> object is incremented.  If it is the same, or if
-the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
-then C<obj> is merely stored, without the reference count being incremented.
+the C<how> argument is C<PERL_MAGIC_arylen>, C<PERL_MAGIC_regdatum>,
+C<PERL_MAGIC_regdata>, or if it is a NULL pointer, then C<obj> is merely
+stored, without the reference count being incremented.
 
 See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
 to an SV.
@@ -1123,16 +1124,16 @@ applied to that variable.
 The C<MGVTBL> has five (or sometimes eight) pointers to the following
 routine types:
 
-    int  (*svt_get)(SV* sv, MAGIC* mg);
-    int  (*svt_set)(SV* sv, MAGIC* mg);
-    U32  (*svt_len)(SV* sv, MAGIC* mg);
-    int  (*svt_clear)(SV* sv, MAGIC* mg);
-    int  (*svt_free)(SV* sv, MAGIC* mg);
+    int  (*svt_get)  (pTHX_ SV* sv, MAGIC* mg);
+    int  (*svt_set)  (pTHX_ SV* sv, MAGIC* mg);
+    U32  (*svt_len)  (pTHX_ SV* sv, MAGIC* mg);
+    int  (*svt_clear)(pTHX_ SV* sv, MAGIC* mg);
+    int  (*svt_free) (pTHX_ SV* sv, MAGIC* mg);
 
-    int  (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
+    int  (*svt_copy) (pTHX_ SV *sv, MAGIC* mg, SV *nsv,
                                           const char *name, I32 namlen);
-    int  (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
-    int  (*svt_local)(SV *nsv, MAGIC *mg);
+    int  (*svt_dup)  (pTHX_ MAGIC *mg, CLONE_PARAMS *param);
+    int  (*svt_local)(pTHX_ SV *nsv, MAGIC *mg);
 
 
 This MGVTBL structure is set at compile-time in F<perl.h> and there are
@@ -2674,6 +2675,20 @@ whatever the compiler has.
 If you are printing addresses of pointers, use UVxf combined
 with PTR2UV(), do not use %lx or %p.
 
+=head2 Formatted Printing of Size_t and SSize_t
+
+The most general way to do this is to cast them to a UV or IV, and
+print as in the
+L<previous section|/Formatted Printing of IVs, UVs, and NVs>.
+
+But if you're using C<PerlIO_printf()>, it's less typing and visual
+clutter to use the C<"%z"> length modifier (for I<siZe>):
+
+        PerlIO_printf("STRLEN is %zu\n", len);
+
+This modifier is not portable, so its use should be restricted to
+C<PerlIO_printf()>.
+
 =head2 Pointer-To-Integer and Integer-To-Pointer
 
 Because pointer size does not necessarily equal integer size,