From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS22989 209.51.188.0/24 X-Spam-Status: No, score=-3.8 required=3.0 tests=AWL,BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 7189A1F4B4 for ; Mon, 19 Apr 2021 04:02:27 +0000 (UTC) Received: from localhost ([::1]:38760 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lYL7C-0007dT-0l for normalperson@yhbt.net; Mon, 19 Apr 2021 00:02:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51016) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lYL76-0007b7-4w for bug-gnulib@gnu.org; Mon, 19 Apr 2021 00:02:21 -0400 Received: from zimbra.cs.ucla.edu ([131.179.128.68]:46222) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lYL6z-00044j-KB for bug-gnulib@gnu.org; Mon, 19 Apr 2021 00:02:18 -0400 Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id B043416011C; Sun, 18 Apr 2021 21:02:08 -0700 (PDT) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id F9ZS-1obYo7E; Sun, 18 Apr 2021 21:02:07 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id C627416011A; Sun, 18 Apr 2021 21:02:07 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id eFdJkrcRP6mI; Sun, 18 Apr 2021 21:02:07 -0700 (PDT) Received: from day.example.com (cpe-172-91-119-151.socal.res.rr.com [172.91.119.151]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 9BAF7160095; Sun, 18 Apr 2021 21:02:07 -0700 (PDT) From: Paul Eggert To: bug-gnulib@gnu.org, berrange@redhat.com Subject: [PATCH 1/8] safe-alloc: improve doc Date: Sun, 18 Apr 2021 21:01:51 -0700 Message-Id: <20210419040158.1902066-1-eggert@cs.ucla.edu> X-Mailer: git-send-email 2.27.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=131.179.128.68; envelope-from=eggert@cs.ucla.edu; helo=zimbra.cs.ucla.edu X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: bug-gnulib@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Gnulib discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paul Eggert Errors-To: bug-gnulib-bounces+normalperson=yhbt.net@gnu.org Sender: "bug-gnulib" * doc/safe-alloc.texi: Clarify that reallocating an array appends uninitialized storage. Say =E2=80=98sizeof *p=E2=80=99 rather than =E2=80= =98sizeof(*p)=E2=80=99 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 =20 + safe-alloc: improve doc + * doc/safe-alloc.texi: Clarify that reallocating an array appends + uninitialized storage. Say =E2=80=98sizeof *p=E2=80=99 rather than =E2= =80=98sizeof(*p)=E2=80=99 + 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 =20 @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. =20 @@ -50,7 +52,7 @@ Returns @minus{}1 on failure, 0 on success. =20 @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. =20 @@ -59,7 +61,7 @@ Returns @minus{}1 on failure, 0 on success. =20 @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. =20 @@ -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. =20 Returns @minus{}1 on failure, 0 on success. @end defmac --=20 2.27.0