Strengthen description of recallocarray(3) behaviour, hoping that readers

make the behaviour -> use case connection.
help from jmc and jsing

1 files changed, 10 insertions, 5 deletions

diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index e24a811bec3..0053748991a 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/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.103 2017/03/07 06:07:50 otto Exp $
+.\"	$OpenBSD: malloc.3,v 1.104 2017/03/17 17:00:38 deraadt Exp $
 .\"
-.Dd $Mdocdate: March 7 2017 $
+.Dd $Mdocdate: March 17 2017 $
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -119,9 +119,14 @@ The
 .Fn recallocarray
 function is similar to
 .Fn reallocarray
-except that it takes care of clearing newly allocated memory.
-Additionally, the memory that becomes unallocated while shrinking
-or moving existing allocations is erased.
+except it ensures newly allocated memory is cleared similar to
+.Xr calloc 3 .
+Memory that becomes unallocated while shrinking or moving existing
+allocations is explicitly discarded (meaning, pages of memory
+are disposed via
+.Xr munmap 2 ,
+and smaller allocations are cleared with
+.Xr explicit_bzero 3 Ns ).
 If
 .Fa ptr
 is a