X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlclib.pod;h=39488f0fa671e8c81fdc9d258fc0fff4a0dc3bd1;hb=6fa4d285bff5644bebb95aff09143322042282cc;hp=7c527a9a7a207048be6bbb178e81aa996f8df4a4;hpb=702eb6d058ad90bee8332952b92588ced38f499f;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlclib.pod b/pod/perlclib.pod
index 7c527a9..39488f0 100644
--- a/pod/perlclib.pod
+++ b/pod/perlclib.pod
@@ -99,12 +99,12 @@ There is no equivalent to C<fgets>; one should use C<sv_gets> instead:
 
     Instead Of:                 	Use:
 
-    t* p = malloc(n)            	New(id, p, n, t)
-    t* p = calloc(n, s)         	Newz(id, p, n, t)
+    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)
+    memcpy(dst, src, sizeof(t))		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)
@@ -132,6 +132,19 @@ instead of raw C<char *> strings:
 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
@@ -163,9 +176,9 @@ table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
 
     atof(s)                     Atof(s)
     atol(s)                     Atol(s)
-    strtod(s, *p)               Nothing.  Just don't use it.
-    strtol(s, *p, n)            Strtol(s, *p, n)
-    strtoul(s, *p, n)           Strtoul(s, *p, n)
+    strtod(s, &p)               Nothing.  Just don't use it.
+    strtol(s, &p, n)            Strtol(s, &p, n)
+    strtoul(s, &p, n)           Strtoul(s, &p, n)
 
 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