[PATCH 1/8] safe-alloc: improve doc

[Paul Eggert]

* doc/safe-alloc.texi: Clarify that reallocating an array appends
uninitialized storage.  Say ‘sizeof *p’ rather than ‘sizeof(*p)’
which would need a space before the paren to follow GNU style.
---
 ChangeLog           |  5 +++++
 doc/safe-alloc.texi | 14 +++++++++-----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ab6045fd3..d2d12058e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2021-04-18  Paul Eggert  <eggert@cs.ucla.edu>
 
+       safe-alloc: improve doc
+       * doc/safe-alloc.texi: Clarify that reallocating an array appends
+       uninitialized storage.  Say ‘sizeof *p’ rather than ‘sizeof(*p)’
+       which would need a space before the paren to follow GNU style.
+
        malloc-gnu-tests, etc.: test ptrdiff_t overflow
        * modules/calloc-gnu-tests (Depends-on):
        * modules/malloc-gnu-tests (Depends-on):
diff --git a/doc/safe-alloc.texi b/doc/safe-alloc.texi
index 60304472f..d40ec65b6 100644
--- a/doc/safe-alloc.texi
+++ b/doc/safe-alloc.texi
@@ -36,12 +36,14 @@ passed in as arguments when appropriate.
 It uses return values only for a success/failure error condition flag,
 and annotates them with GCC's @code{__warn_unused_result__} attribute.
 @item
-It uses @code{calloc} instead of @code{malloc}.
+When allocating a fresh array, it uses @code{calloc} instead of
+@code{malloc} so that the array's contents are zeroed.
+However, memory added to an already-existing array is uninitialized.
 @end itemize
 
 @defmac {int} ALLOC (ptr)
 @findex ALLOC
-Allocate @code{sizeof(*ptr)} bytes of memory and store the address of
+Allocate @code{sizeof *ptr} bytes of memory and store the address of
 allocated memory in @code{ptr}.  Fill the newly allocated memory with
 zeros.
 
@@ -50,7 +52,7 @@ Returns @minus{}1 on failure, 0 on success.
 
 @defmac {int} ALLOC_N (ptr, count)
 @findex ALLOC_N
-Allocate an array of @code{count} elements, each @code{sizeof(*ptr)}
+Allocate an array of @code{count} elements, each @code{sizeof *ptr}
 bytes long, and store the address of allocated memory in
 @code{ptr}.  Fill the newly allocated memory with zeros.
 
@@ -59,7 +61,7 @@ Returns @minus{}1 on failure, 0 on success.
 
 @defmac {int} ALLOC_N_UNINITIALIZED (ptr, count)
 @findex ALLOC_N_UNINITIALIZED
-Allocate an array of @code{count} elements, each @code{sizeof(*ptr)}
+Allocate an array of @code{count} elements, each @code{sizeof *ptr}
 bytes long, and store the address of allocated memory in
 @code{ptr}.  The allocated memory is not initialized.
 
@@ -69,9 +71,11 @@ Returns @minus{}1 on failure, 0 on success.
 @defmac {int} REALLOC_N (ptr, count)
 @findex REALLOC_N
 Reallocate the memory pointed to by @code{ptr} to be big enough to hold
-at least @code{count} elements, each @code{sizeof(*ptr)} bytes long,
+at least @code{count} elements, each @code{sizeof *ptr} bytes long,
 and store the address of allocated memory in @code{ptr}.  If
 reallocation fails, the @code{ptr} variable is not modified.
+If the new array is smaller than the old one, discard excess contents;
+if larger, the newly added storage is not initialized.
 
 Returns @minus{}1 on failure, 0 on success.
 @end defmac
-- 
2.27.0