A.2 C dynamic memory extension functions

The following 5 functions are available as replacements for existing C library extension functions that always abort and never return `NULL' if there is insufficient memory to fulfil a request. To use these you must include mpatrol.h before all other header files, although on UNIX and Windows platforms (and AmigaOS when using gcc) they will be used anyway, albeit with slightly less tracing information.

void *xmalloc(size_t size)

Allocates size uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to size bytes in length. If size is `0' then the memory allocated will be implicitly rounded up to `1' byte. If there is not enough space in the heap then the program will be terminated and the `OUTMEM' error will be given. The allocated memory must be deallocated with xfree() or reallocated with xrealloc().

void *xcalloc(size_t nelem, size_t size)

Allocates nelem elements of size zero-initialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to nelem * size bytes in length. If nelem * size is `0' then the amount of memory allocated will be implicitly rounded up to `1' byte. If there is not enough space in the heap then the program will be terminated and the `OUTMEM' error will be given. The allocated memory must be deallocated with xfree() or reallocated with xrealloc().

char *xstrdup(const char *str)

Allocates exactly enough memory from the heap to duplicate str (including the terminating nul character) and returns a 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 str is `NULL' then an error will be given and the `NULL' pointer will be returned. If there is not enough space in the heap then the program will be terminated and the `OUTMEM' error will be given. The allocated memory must be deallocated with xfree() or reallocated with xrealloc().

void *xrealloc(void *ptr, size_t size)

Resizes the memory allocation beginning at ptr to size bytes and returns a pointer to the first byte of the new allocation after copying ptr to the newly-allocated memory, which will be truncated if size is smaller than the original allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to size bytes in length. If ptr is `NULL' then the call will be equivalent to xmalloc(). If size is `0' then it will be implicitly rounded up to `1'. If size is greater than the original allocation then the extra space will be filled with uninitialised bytes. If there is not enough space in the heap then the program will be terminated and the `OUTMEM' error will be given. The allocated memory must be deallocated with xfree() and can be reallocated again with xrealloc().

void xfree(void *ptr)

Frees the memory allocation beginning at ptr so the memory can be reused by another call to allocate memory. If ptr is `NULL' then no memory will be freed. All of the previous contents will be destroyed.