A.1 C dynamic memory allocation functions
The following 19 functions are available as replacements for existing C library
functions. 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. If alloca() is being used and alloca.h is included
then mpatrol.h must appear before alloca.h otherwise the debugging
version of alloca() will not be used.
void *malloc(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 `NULL' pointer will be returned and
errno will be set
to ENOMEM. The allocated memory must be deallocated with free()
or reallocated with realloc().
void *calloc(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 `NULL'
pointer will be returned and errno will be set to ENOMEM. The
allocated memory must be deallocated with free() or reallocated with
realloc().
void *memalign(size_t align, 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 aligned to
align bytes and can be used to store data of up to size bytes in
length. If align is zero then the default system alignment will be used.
If align is not a power of two then it will be rounded up to the nearest
power of two. If align is greater than the system page size then it will
be truncated to that value. 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 `NULL' pointer will be returned and
errno will be
set to ENOMEM. The allocated memory must be deallocated with
free() or reallocated with realloc(), although the latter will not
guarantee the preservation of alignment.
void *valloc(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 aligned to the
system page size 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
`NULL' pointer will be returned and
errno will be set to
ENOMEM. The allocated memory must be deallocated with free() or
reallocated with realloc(), although the latter will not guarantee the
preservation of alignment.
void *pvalloc(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 aligned to the
system page size 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' page, otherwise size will be implicitly rounded up
to a multiple of the system page size. If there is not enough space in the heap
then the `NULL' pointer will be returned and
errno will be set to
ENOMEM. The allocated memory must be deallocated with free() or
reallocated with realloc(), although the latter will not guarantee the
preservation of alignment.
void *alloca(size_t size)- Allocates size temporary 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
alloca() function normally allocates its memory from the
stack, with the result that all such allocations will be freed when the function
returns. This version of alloca() allocates its memory from the heap in
order to provide better debugging, but the allocations may not necessarily be
freed immediately when the function returns. The allocated memory can be
deallocated explicitly with dealloca(), but may not be reallocated or
deallocated in any other way. This function is available for backwards
compatibility with older C source code and should not be used in new code.
char *strdup(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 `NULL' pointer will be returned and
errno will be set to ENOMEM. The allocated memory must be
deallocated with free() or reallocated with realloc().
char *strndup(const char *str, size_t size)- 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' and size
is non-zero then an error will be given and the `NULL' pointer will be
returned. If the length of str is greater than size then only
size characters will be allocated and copied, with one additional byte for
the nul character. If there is not enough space in the heap then the
`NULL' pointer will be returned and
errno will be set to
ENOMEM. The allocated memory must be deallocated with free() or
reallocated with realloc(). This function is available for backwards
compatibility with older C libraries and should not be used in new code.
char *strsave(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 `NULL' pointer will be returned and
errno will be set to ENOMEM. The allocated memory must be
deallocated with free() or reallocated with realloc(). This
function is available for backwards compatibility with older C libraries and
should not be used in new code.
char *strnsave(const char *str, size_t size)- 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' and size
is non-zero then an error will be given and the `NULL' pointer will be
returned. If the length of str is greater than size then only
size characters will be allocated and copied, with one additional byte for
the nul character. If there is not enough space in the heap then the
`NULL' pointer will be returned and
errno will be set to
ENOMEM. The allocated memory must be deallocated with free() or
reallocated with realloc(). This function is available for backwards
compatibility with older C libraries and should not be used in new code.
char *strdupa(const char *str)- Allocates exactly enough temporary 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
strdupa() function normally
allocates its memory from the stack, with the result that all such allocations
will be freed when the function returns. This version of strdupa()
allocates its memory from the heap in order to provide better debugging, but the
allocations may not necessarily be freed immediately when the function returns.
The allocated memory can be deallocated explicitly with dealloca(), but
may not be reallocated or deallocated in any other way. This function is
available for backwards compatibility with older C source code and should not be
used in new code.
char *strndupa(const char *str, size_t size)- Allocates exactly enough temporary 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' and
size is non-zero then an error will be given and the `NULL' pointer
will be returned. If the length of str is greater than size then
only size characters will be allocated and copied, with one additional
byte for the nul character. If there is not enough space in the heap then the
program will be terminated and the `OUTMEM' error will be given. The
strndupa() function normally allocates its memory from the stack, with
the result that all such allocations will be freed when the function returns.
This version of strndupa() allocates its memory from the heap in order to
provide better debugging, but the allocations may not necessarily be freed
immediately when the function returns. The allocated memory can be deallocated
explicitly with dealloca(), but may not be reallocated or deallocated in
any other way. This function is available for backwards compatibility with
older C source code and should not be used in new code.
void *realloc(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
malloc(). If size is `0' then the existing
memory allocation will be freed and the `NULL' pointer will be returned.
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 `NULL' pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free() and
can be reallocated again with realloc().
void *reallocf(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
malloc(). If size is `0' then the existing
memory allocation will be freed and the `NULL' pointer will be returned.
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 `NULL' pointer will be returned, the original allocation will be
freed and errno will be set to ENOMEM. The allocated memory must
be deallocated with free() and can be reallocated again with
realloc(). This function is available for backwards compatibility with
older C libraries and should not be used in new code.
void *recalloc(void *ptr, size_t nelem, size_t size)- Resizes the memory allocation beginning at ptr to nelem elements of
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
nelem * 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 nelem * size bytes in length. If ptr is
`NULL' then the call will be equivalent to calloc(). If
nelem * size is `0' then the existing memory allocation will be
freed and the `NULL' pointer will be returned. If nelem * size is
greater than the original allocation then the extra space will be filled with
zero-initialised bytes. If there is not enough space in the heap then the
`NULL' pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free() and
can be reallocated again with realloc(). This function is available for
backwards compatibility with older C libraries and calloc() and should
not be used in new code.
void *expand(void *ptr, size_t size)- Attempts to resize the memory allocation beginning at ptr to size
bytes and either returns ptr if there was enough space to resize it, or
`NULL' if the block could not be resized for a particular reason. If
ptr is `NULL' then the call will be equivalent to
malloc().
If size is `0' then the existing memory allocation will be freed and
the `NULL' pointer will be returned. If size is greater than the
original allocation then the extra space will be filled with uninitialised bytes
and if size is less than the original allocation then the memory block
will be truncated. If there is not enough space in the heap then the
`NULL' pointer will be returned and errno will be set to
ENOMEM. The allocated memory must be deallocated with free() and
can be reallocated again with realloc(). This function is available for
backwards compatibility with older C libraries and should not be used in new
code.
void free(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.
void cfree(void *ptr, size_t nelem, size_t size)- 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. The nelem
and size parameters are ignored in this implementation. This function is
available for backwards compatibility with older C libraries and
calloc()
and should not be used in new code.
void dealloca(void *ptr)- Explicitly frees the temporary 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. This function can only be used to free memory that was allocated
with the
alloca(), strdupa() and strndupa() functions, but
is only really required if the mpatrol library does not automatically free such
memory allocations when the allocating function returns. This function is
mpatrol-specific and should not be used in release code.