consting for .c files in tests

[perl5.git] / pod / perlclib.pod

diff --git a/pod/perlclib.pod b/pod/perlclib.pod
index a0f4a80..f676842 100644 (file)
--- a/pod/perlclib.pod
+++ b/pod/perlclib.pod
@@ -97,15 +97,17 @@ There is no equivalent to C<fgets>; one should use C<sv_gets> instead:
 
 =head2 Memory Management and String Handling
 
-    Instead Of:                 Use:
-
-    t* p = malloc(n)            New(id, p, n, t)
-    t* p = calloc(n, s)         Newz(id, p, n, t)
-    p = realloc(p, n)           Renew(p, n, t)
-    memcpy(dst, src, n)         Copy(src, dst, n, t)
-    memmove(dst, src, n)        Move(src, dst, n, t)
-    memcpy/*(struct foo *)      StructCopy(src, dst, t)
-    free(p)                     Safefree(p)
+    Instead Of:                        Use:
+
+    t* p = malloc(n)                   Newx(id, p, n, t)
+    t* p = calloc(n, s)                Newxz(id, p, n, t)
+    p = realloc(p, n)                  Renew(p, n, t)
+    memcpy(dst, src, n)                Copy(src, dst, n, t)
+    memmove(dst, src, n)               Move(src, dst, n, t)
+    memcpy/*(struct foo *)             StructCopy(src, dst, t)
+    memset(dst, 0, n * sizeof(t))      Zero(dst, n, t)
+    memzero(dst, 0)                    Zero(dst, n, char)
+    free(p)                            Safefree(p)
 
     strdup(p)                   savepv(p)
     strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
@@ -127,9 +129,22 @@ instead of raw C<char *> strings:
     strncat(dt, src)            sv_catpvn(sv, s)
     sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
 
-Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining
+Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
 concatenation with formatting.
 
+Sometimes instead of zeroing the allocated heap by using Newxz() you
+should consider "poisoning" the data.  This means writing a bit
+pattern into it that should be illegal as pointers (and floating point
+numbers), and also hopefully surprising enough as integers, so that
+any code attempting to use the data without forethought will break
+sooner rather than later.  Poisoning can be done using the Poison()
+macros, which have similar arguments as Zero():
+
+    PoisonWith(dst, n, t, b)    scribble memory with byte b
+    PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
+    PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
+    Poison(dst, n, t)           equal to PoisonFree(dst, n, t)
+
 =head2 Character Class Tests
 
 There are two types of character class tests that Perl implements: one
@@ -165,8 +180,8 @@ table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
     strtol(s, *p, n)            Strtol(s, *p, n)
     strtoul(s, *p, n)           Strtoul(s, *p, n)
 
-Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in
-F<util.c> for converting strings representing numbers in the respective
+Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
+F<numeric.c> for converting strings representing numbers in the respective
 bases into C<NV>s.
 
 In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is