A.3 C dynamic memory alternative functions

The following 6 functions are provided as convenient alternatives to the ANSI C dynamic memory allocation functions (although strdup() is not strictly an ANSI C function). They are implemented as preprocessor macro functions which may evaluate their arguments more than once, so extra care should be taken to avoid passing arguments with side-effects. None of the functions return `NULL' if no memory is available and instead abort the program with a useful error message indicating where the call to allocate memory came from and what was being allocated. To use these you should include the mpatrol.h or mpalloc.h header files.

void *MP_MALLOC(void *ptr, size_t count, typename type)

Allocates count uninitialised items of type type from the heap, sets ptr to the result and returns a suitably-cast pointer to the first item of the allocation. The pointer returned will be suitably aligned for holding items of type type. If count is `0' then it will be implicitly rounded up to `1'. If there is not enough space in the heap then the program will be aborted after calling the allocation failure handler, which by default writes an appropriate error message to the standard error file stream. The allocated memory in ptr must be deallocated with MP_FREE() or reallocated with MP_REALLOC().

void *MP_CALLOC(void *ptr, size_t count, typename type)

Allocates count zero-initialised items of type type from the heap, sets ptr to the result and returns a suitably-cast pointer to the first item of the allocation. The pointer returned will be suitably aligned for holding items of type type. If count is `0' then it will be implicitly rounded up to `1'. If there is not enough space in the heap then the program will be aborted after calling the allocation failure handler, which by default writes an appropriate error message to the standard error file stream. The allocated memory in ptr must be deallocated with MP_FREE() or reallocated with MP_REALLOC().

char *MP_STRDUP(char *ptr, const char *str)

Allocates exactly enough memory from the heap to duplicate str (including the terminating nul character), sets ptr to the result and returns a suitably-cast pointer to the first byte of the allocation after copying str to the newly-allocated memory. The pointer returned will have no alignment constraints and can be used to store character data up to the length of str. If there is not enough space in the heap then the program will be aborted after calling the allocation failure handler, which by default writes an appropriate error message to the standard error file stream. The allocated memory in ptr must be deallocated with MP_FREE() or reallocated with MP_REALLOC().

void *MP_REALLOC(void *ptr, size_t count, typename type)

Resizes the memory allocation beginning at ptr to count items of type type and returns a suitably-cast pointer to the first item of the new allocation after copying ptr to the newly-allocated memory, which will be truncated if count is smaller than the original number of items. The pointer returned will be suitably aligned for holding items of type type. If ptr is `NULL' then the call will be equivalent to MP_MALLOC(). If count is `0' then it will be implicitly rounded up to `1'. If count is greater than the original number of items then the extra space will be filled with uninitialised bytes. If there is not enough space in the heap then the program will be aborted after calling the allocation failure handler, which by default writes an appropriate error message to the standard error file stream. The allocated memory must be deallocated with MP_FREE() and can be reallocated again with MP_REALLOC().

void MP_FREE(void *ptr)

Frees the memory allocation beginning at ptr so the memory can be reused by another call to allocate memory, and sets ptr to `NULL' after freeing the memory. If ptr is `NULL' then no memory will be freed.

__mp_failhandler MP_FAILURE(__mp_failhandler func)

Installs an allocation failure handler specifically for use with MP_MALLOC(), MP_CALLOC(), MP_STRDUP() and MP_REALLOC() and returns a pointer to the previously installed handler, normally the default handler if no handler had been previously installed. This will be called by the above functions when there is not enough space in the heap for them to satisfy their allocation request. The default allocation failure handler will terminate the program after writing an error message to the standard error file stream indicating where the original allocation request took place and what was being allocated.