lib/xalloc.h

   1 /* xalloc.h -- malloc with out-of-memory checking
   2
   3    Copyright (C) 1990-2000, 2003-2004, 2006-2021 Free Software Foundation, Inc.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 #ifndef XALLOC_H_
  19 #define XALLOC_H_
  20
  21 #include <stddef.h>
  22 #include <stdint.h>
  23
  24 #if GNULIB_XALLOC
  25 # include "idx.h"
  26 # include "intprops.h"
  27 #endif
  28
  29 #ifndef _GL_INLINE_HEADER_BEGIN
  30  #error "Please include config.h first."
  31 #endif
  32 _GL_INLINE_HEADER_BEGIN
  33 #ifndef XALLOC_INLINE
  34 # define XALLOC_INLINE _GL_INLINE
  35 #endif
  36
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42
  43 #if GNULIB_XALLOC_DIE
  44
  45 /* This function is always triggered when memory is exhausted.
  46    It must be defined by the application, either explicitly
  47    or by using gnulib's xalloc-die module.  This is the
  48    function to call when one wants the program to die because of a
  49    memory allocation failure.  */
  50 /*extern*/ _Noreturn void xalloc_die (void);
  51
  52 #endif /* GNULIB_XALLOC_DIE */
  53
  54 #if GNULIB_XALLOC
  55
  56 void *xmalloc (size_t s)
  57       _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_ALLOC_SIZE ((1));
  58 void *xzalloc (size_t s)
  59       _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_ALLOC_SIZE ((1));
  60 void *xcalloc (size_t n, size_t s)
  61       _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_ALLOC_SIZE ((1, 2));
  62 void *xrealloc (void *p, size_t s)
  63       _GL_ATTRIBUTE_ALLOC_SIZE ((2));
  64 void *xreallocarray (void *p, size_t n, size_t s)
  65       _GL_ATTRIBUTE_ALLOC_SIZE ((2, 3));
  66 void *x2realloc (void *p, size_t *pn);
  67 void *xpalloc (void *pa, idx_t *nitems, idx_t nitems_incr_min,
  68                ptrdiff_t nitems_max, idx_t item_size);
  69 void *xmemdup (void const *p, size_t s)
  70       _GL_ATTRIBUTE_ALLOC_SIZE ((2));
  71 char *xstrdup (char const *str)
  72       _GL_ATTRIBUTE_MALLOC;
  73
  74 /* In the following macros, T must be an elementary or structure/union or
  75    typedef'ed type, or a pointer to such a type.  To apply one of the
  76    following macros to a function pointer or array type, you need to typedef
  77    it first and use the typedef name.  */
  78
  79 /* Allocate an object of type T dynamically, with error checking.  */
  80 /* extern t *XMALLOC (typename t); */
  81 # define XMALLOC(t) ((t *) xmalloc (sizeof (t)))
  82
  83 /* Allocate memory for N elements of type T, with error checking.  */
  84 /* extern t *XNMALLOC (size_t n, typename t); */
  85 # define XNMALLOC(n, t) \
  86     ((t *) (sizeof (t) == 1 ? xmalloc (n) : xnmalloc (n, sizeof (t))))
  87
  88 /* Allocate an object of type T dynamically, with error checking,
  89    and zero it.  */
  90 /* extern t *XZALLOC (typename t); */
  91 # define XZALLOC(t) ((t *) xzalloc (sizeof (t)))
  92
  93 /* Allocate memory for N elements of type T, with error checking,
  94    and zero it.  */
  95 /* extern t *XCALLOC (size_t n, typename t); */
  96 # define XCALLOC(n, t) \
  97     ((t *) (sizeof (t) == 1 ? xzalloc (n) : xcalloc (n, sizeof (t))))
  98
  99
 100 /* Allocate an array of N objects, each with S bytes of memory,
 101    dynamically, with error checking.  S must be nonzero.  */
 102
 103 XALLOC_INLINE void *xnmalloc (size_t n, size_t s)
 104                     _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_ALLOC_SIZE ((1, 2));
 105 XALLOC_INLINE void *
 106 xnmalloc (size_t n, size_t s)
 107 {
 108   return xreallocarray (NULL, n, s);
 109 }
 110
 111 /* FIXME: Deprecate this in favor of xreallocarray?  */
 112 /* Change the size of an allocated block of memory P to an array of N
 113    objects each of S bytes, with error checking.  S must be nonzero.  */
 114
 115 XALLOC_INLINE void *xnrealloc (void *p, size_t n, size_t s)
 116                     _GL_ATTRIBUTE_ALLOC_SIZE ((2, 3));
 117 XALLOC_INLINE void *
 118 xnrealloc (void *p, size_t n, size_t s)
 119 {
 120   return xreallocarray (p, n, s);
 121 }
 122
 123 /* If P is null, allocate a block of at least *PN such objects;
 124    otherwise, reallocate P so that it contains more than *PN objects
 125    each of S bytes.  S must be nonzero.  Set *PN to the new number of
 126    objects, and return the pointer to the new block.  *PN is never set
 127    to zero, and the returned pointer is never null.
 128
 129    Repeated reallocations are guaranteed to make progress, either by
 130    allocating an initial block with a nonzero size, or by allocating a
 131    larger block.
 132
 133    In the following implementation, nonzero sizes are increased by a
 134    factor of approximately 1.5 so that repeated reallocations have
 135    O(N) overall cost rather than O(N**2) cost, but the
 136    specification for this function does not guarantee that rate.
 137
 138    Here is an example of use:
 139
 140      int *p = NULL;
 141      size_t used = 0;
 142      size_t allocated = 0;
 143
 144      void
 145      append_int (int value)
 146        {
 147          if (used == allocated)
 148            p = x2nrealloc (p, &allocated, sizeof *p);
 149          p[used++] = value;
 150        }
 151
 152    This causes x2nrealloc to allocate a block of some nonzero size the
 153    first time it is called.
 154
 155    To have finer-grained control over the initial size, set *PN to a
 156    nonzero value before calling this function with P == NULL.  For
 157    example:
 158
 159      int *p = NULL;
 160      size_t used = 0;
 161      size_t allocated = 0;
 162      size_t allocated1 = 1000;
 163
 164      void
 165      append_int (int value)
 166        {
 167          if (used == allocated)
 168            {
 169              p = x2nrealloc (p, &allocated1, sizeof *p);
 170              allocated = allocated1;
 171            }
 172          p[used++] = value;
 173        }
 174
 175    */
 176
 177 XALLOC_INLINE void *
 178 x2nrealloc (void *p, size_t *pn, size_t s)
 179 {
 180   size_t n = *pn;
 181
 182   if (! p)
 183     {
 184       if (! n)
 185         {
 186           /* The approximate size to use for initial small allocation
 187              requests, when the invoking code specifies an old size of
 188              zero.  This is the largest "small" request for the GNU C
 189              library malloc.  */
 190           enum { DEFAULT_MXFAST = 64 * sizeof (size_t) / 4 };
 191
 192           n = DEFAULT_MXFAST / s;
 193           n += !n;
 194         }
 195     }
 196   else
 197     {
 198       /* Set N = floor (1.5 * N) + 1 to make progress even if N == 0.  */
 199       if (INT_ADD_WRAPV (n, (n >> 1) + 1, &n))
 200         xalloc_die ();
 201     }
 202
 203   p = xreallocarray (p, n, s);
 204   *pn = n;
 205   return p;
 206 }
 207
 208 /* Return a pointer to a new buffer of N bytes.  This is like xmalloc,
 209    except it returns char *.  */
 210
 211 XALLOC_INLINE char *xcharalloc (size_t n)
 212                     _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_ALLOC_SIZE ((1));
 213 XALLOC_INLINE char *
 214 xcharalloc (size_t n)
 215 {
 216   return XNMALLOC (n, char);
 217 }
 218
 219 #endif /* GNULIB_XALLOC */
 220
 221
 222 #ifdef __cplusplus
 223 }
 224 #endif
 225
 226
 227 #if GNULIB_XALLOC && defined __cplusplus
 228
 229 /* C++ does not allow conversions from void * to other pointer types
 230    without a cast.  Use templates to work around the problem when
 231    possible.  */
 232
 233 template <typename T> inline T *
 234 xrealloc (T *p, size_t s)
 235 {
 236   return (T *) xrealloc ((void *) p, s);
 237 }
 238
 239 template <typename T> inline T *
 240 xreallocarray (T *p, size_t n, size_t s)
 241 {
 242   return (T *) xreallocarray ((void *) p, n, s);
 243 }
 244
 245 /* FIXME: Deprecate this in favor of xreallocarray?  */
 246 template <typename T> inline T *
 247 xnrealloc (T *p, size_t n, size_t s)
 248 {
 249   return xreallocarray (p, n, s);
 250 }
 251
 252 template <typename T> inline T *
 253 x2realloc (T *p, size_t *pn)
 254 {
 255   return (T *) x2realloc ((void *) p, pn);
 256 }
 257
 258 template <typename T> inline T *
 259 x2nrealloc (T *p, size_t *pn, size_t s)
 260 {
 261   return (T *) x2nrealloc ((void *) p, pn, s);
 262 }
 263
 264 template <typename T> inline T *
 265 xmemdup (T const *p, size_t s)
 266 {
 267   return (T *) xmemdup ((void const *) p, s);
 268 }
 269
 270 #endif /* GNULIB_XALLOC && C++ */
 271
 272
 273 _GL_INLINE_HEADER_END
 274
 275 #endif /* !XALLOC_H_ */