doc/safe-alloc.texi

   1 @node Safe Allocation Macros
   2 @section Safe Allocation Macros
   3
   4 The standard C library malloc/realloc/calloc/free APIs are prone to a
   5 number of common coding errors. The @code{safe-alloc} module provides
   6 macros that make it easier to avoid many of them. It still uses the
   7 standard C allocation functions behind the scenes.
   8
   9 Some of the memory allocation mistakes that are commonly made are
  10
  11 @itemize @bullet
  12 @item
  13 passing the incorrect number of bytes to @code{malloc}, especially
  14 when allocationg an array
  15 @item
  16 fail to check the return value of @code{malloc} and @code{realloc} for
  17 errors
  18 @item
  19 forget to fully initialize memory just allocated with @code{malloc}
  20 @item
  21 duplicate calls to @code{free} by forgetting to set the pointer
  22 variable to @code{NULL}
  23 @item
  24 leaking memory in calls to @code{realloc} when that call fails
  25 @end itemize
  26
  27 The @code{safe-alloc} module addresses these problems in the following way:
  28
  29 @itemize @bullet
  30 @item
  31 Define macros that wrap around the standard C allocation
  32 functions. That makes it possible to use the compiler's knowledge of
  33 the size of objects for allocation; it also allows setting pointers
  34 passed in as arguments when appropriate
  35 @item
  36 Use return values only for a success/fail error condition flag,
  37 and annotate them with GCC's @code{__warn_unused_result__}
  38 @item
  39 Use @code{calloc} in favor of @code{malloc}
  40 @end itemize
  41
  42 @defmac {int} ALLOC (ptr)
  43 @findex ALLOC
  44 Allocate @code{sizeof(*ptr)} bytes of memory and store the address of
  45 allocated memory in @code{ptr}. Fill the newly allocated memory with
  46 zeros.
  47
  48 Returns -1 on failure, 0 on success.
  49 @end defmac
  50
  51 @defmac {int} ALLOC_N(ptr, count)
  52 @findex ALLOC_N
  53 Allocate an array of @code{count} elements, each @code{sizeof(*ptr)}
  54 bytes long and store the address of allocated memory in
  55 @code{ptr}. Fill the newly allocated memory with zeros.
  56
  57 Returns -1 on failure, 0 on success.
  58 @end defmac
  59
  60 @defmac {int} ALLOC_N_UNINITIALIZED(ptr, count)
  61 @findex ALLOC_N_UNINITIALIZED
  62 Allocate an array of @code{count} elements, each @code{sizeof(*ptr)}
  63 bytes long and store the address of allocated memory in
  64 @code{ptr}. The allocated memory is not initialized.
  65
  66 Returns -1 on failure, 0 on success.
  67 @end defmac
  68
  69 @defmac {int} REALLOC_N(ptr, count)
  70 @findex REALLOC_N
  71 Reallocate the memory pointedto by @code{ptr} to be big enough to hold
  72 at least @code{count} elements, each @code{sizeof(*ptr)} bytes long
  73 and store the address of allocated memory in @code{ptr}. If
  74 reallocation fails, the @code{ptr} is not modified.
  75
  76 Returns -1 on failure, 0 on success.
  77 @end defmac
  78
  79 @defmac {void} FREE(ptr)
  80 @findex FREE
  81 Free the memory stored in @code{ptr} and set @code{ptr} to
  82 @code{NULL}.
  83 @end defmac