Adding upstream version 2.12.1.upstream/2.12.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 13 insertions, 10 deletions

diff --git a/gl/lib/hash.h b/gl/lib/hash.h
index 54d3f22..f764985 100644
--- a/gl/lib/hash.h
+++ b/gl/lib/hash.h
@@ -1,5 +1,5 @@
 /* hash - hashing table processing.
-   Copyright (C) 1998-1999, 2001, 2003, 2009-2023 Free Software Foundation,
+   Copyright (C) 1998-1999, 2001, 2003, 2009-2024 Free Software Foundation,
    Inc.
    Written by Jim Meyering <meyering@ascend.com>, 1998.
 
@@ -148,7 +148,7 @@ typedef void (*Hash_data_freer) (void *entry);
 /* Reclaim all storage associated with a hash table.  If a data_freer
    function has been supplied by the user when the hash table was created,
    this function applies it to the data of each entry before freeing that
-   entry.  */
+   entry.  This function preserves errno, like 'free'.  */
 extern void hash_free (Hash_table *table);
 
 /* Allocate and return a new hash table, or NULL upon failure.  The initial
@@ -183,7 +183,9 @@ extern void hash_free (Hash_table *table);
    You should specify this function only if you want these functions to free
    all of your 'data' data.  This is typically the case when your data is
    simply an auxiliary struct that you have malloc'd to aggregate several
-   values.  */
+   values.
+
+   Set errno on failure; otherwise errno is unspecified.  */
 _GL_ATTRIBUTE_NODISCARD
 extern Hash_table *hash_initialize (size_t candidate,
                                     const Hash_tuning *tuning,
@@ -192,7 +194,7 @@ extern Hash_table *hash_initialize (size_t candidate,
                                     Hash_data_freer data_freer)
   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (hash_free, 1);
 
-/* Same as hash_initialize, but invokes xalloc_die on memory exhaustion.  */
+/* Like hash_initialize, but invokes xalloc_die instead of returning NULL.  */
 /* This function is defined by module 'xhash'.  */
 _GL_ATTRIBUTE_NODISCARD
 extern Hash_table *hash_xinitialize (size_t candidate,
@@ -218,25 +220,26 @@ extern void hash_clear (Hash_table *table);
    the table may receive at least CANDIDATE different user entries, including
    those already in the table, before any other growth of the hash table size
    occurs.  If TUNING->IS_N_BUCKETS is true, then CANDIDATE specifies the
-   exact number of buckets desired.  Return true iff the rehash succeeded.  */
+   exact number of buckets desired.  Return true iff the rehash succeeded,
+   false (setting errno) otherwise.  */
 _GL_ATTRIBUTE_NODISCARD
 extern bool hash_rehash (Hash_table *table, size_t candidate);
 
 /* If ENTRY matches an entry already in the hash table, return the pointer
    to the entry from the table.  Otherwise, insert ENTRY and return ENTRY.
-   Return NULL if the storage required for insertion cannot be allocated.
-   This implementation does not support duplicate entries or insertion of
-   NULL.  */
+   Return NULL (setting errno) if the storage required for insertion
+   cannot be allocated.  This implementation does not support
+   duplicate entries or insertion of NULL.  */
 _GL_ATTRIBUTE_NODISCARD
 extern void *hash_insert (Hash_table *table, const void *entry);
 
-/* Same as hash_insert, but invokes xalloc_die on memory exhaustion.  */
+/* Same as hash_insert, but invokes xalloc_die instead of returning NULL.  */
 /* This function is defined by module 'xhash'.  */
 extern void *hash_xinsert (Hash_table *table, const void *entry);
 
 /* Insert ENTRY into hash TABLE if there is not already a matching entry.
 
-   Return -1 upon memory allocation failure.
+   Return -1 (setting errno) upon memory allocation failure.
    Return 1 if insertion succeeded.
    Return 0 if there is already a matching entry in the table,
    and in that case, if MATCHED_ENT is non-NULL, set *MATCHED_ENT