* 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 <egg...@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
