X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlclib.pod;h=e89a67a14092f4acc7f3ca36331884066c535ee2;hb=10ac92784f49d4a1fe54cc1ed7d05f0d3b2a2f29;hp=80e6194d1f56e942a6a12d9cebf25f9d098b85ca;hpb=328bf3738a02f1c1bfa010034ca56aee254f8a25;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlclib.pod b/pod/perlclib.pod
index 80e6194..e89a67a 100644
--- 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)            	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)
+    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!)
@@ -130,6 +132,16 @@ 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 Newz() 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()
+macro, which has similar arguments as Zero():
+
+    Poison(dst, n, t)
+
 =head2 Character Class Tests
 
 There are two types of character class tests that Perl implements: one