allow clearing less than allocated and document freezero(3) better

1 files changed, 21 insertions, 8 deletions

diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3
index c09b4756fa..602787532e 100644
--- a/src/lib/libc/stdlib/malloc.3
+++ b/src/lib/libc/stdlib/malloc.3
@@ -30,9 +30,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: malloc.3,v 1.111 2017/04/10 06:31:31 jmc Exp $
+.\"     $OpenBSD: malloc.3,v 1.112 2017/04/13 18:32:55 otto Exp $
 .\"
-.Dd $Mdocdate: April 10 2017 $
+.Dd $Mdocdate: April 13 2017 $
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -67,7 +67,9 @@ The standard functions
 .Fn calloc ,
 and
 .Fn realloc
-allocate memory space.
+allocate
+.Em objects ,
+regions of memory to store values.
 The
 .Fn malloc
 function allocates uninitialized space for an object of
@@ -94,6 +96,12 @@ function changes the size of the object pointed to by
 to
 .Fa size
 bytes and returns a pointer to the (possibly moved) object.
+If
+.Fa ptr
+is not
+.Dv NULL ,
+it must be a pointer returned by an earlier call to an allocation or
+reallocation function that was not freed in between.
 The contents of the object are unchanged up to the lesser
 of the new and old sizes.
 If the new size is larger, the value of the newly allocated portion
@@ -183,8 +191,7 @@ The
 .Fn freezero
 function is similar to the
 .Fn free
-function except it ensures the memory being deallocated is explicitly
-discarded.
+function except it ensures memory is explicitly discarded.
 If
 .Fa ptr
 is
@@ -196,9 +203,15 @@ is not
 .Dv NULL ,
 the
 .Fa size
-argument must be the size of the earlier allocation that returned
-.Fa ptr ,
-otherwise the behaviour is undefined.
+argument must be equal or smaller than the size of the earlier allocation
+that returned
+.Fa ptr .
+.Fn freezero
+guarantees the memory range starting at
+.Fa ptr
+with length
+.Fa size
+is discarded while deallocating the whole object originally allocated.
 .Sh RETURN VALUES
 Upon successful completion, the allocation functions
 return a pointer to the allocated space; otherwise, a