bug-gnulib@gnu.org mirror (unofficial)
 help / color / mirror / Atom feed
* [PATCH 1/8] safe-alloc: improve doc
@ 2021-04-19  4:01 Paul Eggert
  2021-04-19  4:01 ` [PATCH 2/8] backupfile: simplify via realloc-gnu Paul Eggert
                   ` (7 more replies)
  0 siblings, 8 replies; 15+ messages in thread
From: Paul Eggert @ 2021-04-19  4:01 UTC (permalink / raw)
  To: bug-gnulib, berrange; +Cc: 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



^ permalink raw reply related	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2021-10-19 23:50 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-04-19  4:01 [PATCH 1/8] safe-alloc: improve doc Paul Eggert
2021-04-19  4:01 ` [PATCH 2/8] backupfile: simplify via realloc-gnu Paul Eggert
2021-04-19  4:01 ` [PATCH 3/8] group-member: " Paul Eggert
2021-04-19  4:01 ` [PATCH 4/8] xalloc: new function xreallocarray Paul Eggert
2021-04-22  0:18   ` Bruno Haible
2021-04-22 19:39     ` Paul Eggert
2021-10-19 23:49     ` Paul Eggert
2021-04-19  4:01 ` [PATCH 5/8] xalloc-oversized: fix SIZE_MAX optimization bug Paul Eggert
2021-04-19  4:01 ` [PATCH 6/8] safe-alloc: simplify via reallocarray Paul Eggert
2021-04-19  4:01 ` [PATCH 7/8] calloc-gnu: now LGPLv2+ Paul Eggert
2021-04-19  4:01 ` [PATCH 8/8] safe-alloc: fix pointer implementation Paul Eggert
2021-04-22 18:20 ` [PATCH 1/8] safe-alloc: improve doc Eric Blake
2021-04-22 19:32   ` Paul Eggert
2021-04-22 19:43     ` Eric Blake
2021-04-22 20:27   ` Eric Blake

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).