Safe Allocation Macros
======================

The standard C library malloc/realloc/calloc/free APIs are prone to a number of common coding errors. The safe-alloc module provides macros that make it easier to avoid many of them. It still uses the standard C allocation functions behind the scenes.

Some of the memory allocation mistakes that are commonly made are

  * passing the incorrect number of bytes to malloc, especially when allocationg an array

  * fail to check the return value of malloc and realloc for errors

  * forget to fully initialize memory just allocated with malloc

  * duplicate calls to free by forgetting to set the pointer variable to NULL

  * leaking memory in calls to realloc when that call fails

The safe-alloc module addresses these problems in the following way:

  * Define macros that wrap around the standard C allocation functions. That makes it possible to use the compiler's knowledge of the size of objects for allocation; it also allows setting pointers passed in as arguments when appropriate

  * Use return values only for a success/fail error condition flag, and annotate them with GCC's __warn_unused_result__

  * Use calloc in favor of malloc

 -- Macro: int ALLOC (ptr)
     Allocate sizeof(*ptr) bytes of memory and store the address of allocated memory in ptr. Fill the newly allocated memory with zeros.

     Returns -1 on failure, 0 on success.

 -- Macro: int ALLOC_N(ptr, count)
     Allocate an array of count elements, each sizeof(*ptr) bytes long and store the address of allocated memory in ptr. Fill the newly allocated memory with zeros.

     Returns -1 on failure, 0 on success.

 -- Macro: int ALLOC_N_UNINITIALIZED(ptr, count)
     Allocate an array of count elements, each sizeof(*ptr) bytes long and store the address of allocated memory in ptr. The allocated memory is not initialized.

     Returns -1 on failure, 0 on success.

 -- Macro: int REALLOC_N(ptr, count)
     Reallocate the memory pointedto by ptr to be big enough to hold at least count elements, each sizeof(*ptr) bytes long and store the address of allocated memory in ptr. If reallocation fails, the ptr is not modified.

     Returns -1 on failure, 0 on success.

 -- Macro: void FREE(ptr)
     Free the memory stored in ptr and set ptr to NULL.