libmpatrol.3

debug source code under unix platform.

\fIsize\fP bytes and returns a pointer to the first byte of the new allocation
after copying \fIptr\fP to the newly-allocated memory, which will be truncated
if \fInelem\fP * \fIsize\fP 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 \fInelem\fP * \fIsize\fP bytes in length.  If
\fIptr\fP is \fBNULL\fP then the call will be equivalent to \fBcalloc\fP.  If
\fInelem\fP * \fIsize\fP is \fI0\fP then the existing memory allocation will be
freed and the null pointer will be returned.  If \fInelem\fP * \fIsize\fP 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 \fBerrno\fP will be set to \fBENOMEM\fP.  The
allocated memory must be deallocated with \fBfree\fP and can be reallocated
again with \fBrealloc\fP.  This function is available for backwards
compatibility with older C libraries and \fBcalloc\fP and should not be used in
new code.
.TP
\fBexpand\fP
Attempts to resize the memory allocation beginning at \fIptr\fP to \fIsize\fP
bytes and either returns \fIptr\fP if there was enough space to resize it, or
\fBNULL\fP if the block could not be resized for a particular reason.  If
\fIptr\fP is \fBNULL\fP then the call will be equivalent to \fBmalloc\fP.  If
\fIsize\fP is \fB0\fP then the existing memory allocation will be freed and the
\fBNULL\fP pointer will be returned.  If \fIsize\fP is greater than the original
allocation then the extra space will be filled with uninitialised bytes and if
\fIsize\fP is less than the original allocation then the memory block will be
truncated.  If there is not enough space in the heap then the \fBNULL\fP pointer
will be returned and \fBerrno\fP will be set to \fBENOMEM\fP.  The allocated
memory must be deallocated with \fBfree\fP and can be reallocated again with
\fBrealloc\fP.  This function is available for backwards compatibility with
older C libraries and should not be used in new code.
.TP
\fBfree\fP
Frees the memory allocation beginning at \fIptr\fP so the memory can be reused
by another call to allocate memory.  If \fIptr\fP is \fBNULL\fP then no memory
will be freed.  All of the previous contents will be destroyed.
.TP
\fBcfree\fP
Frees the memory allocation beginning at \fIptr\fP so the memory can be reused
by another call to allocate memory.  If \fIptr\fP is \fBNULL\fP then no memory
will be freed.  All of the previous contents will be destroyed.  The \fInelem\fP
and \fIsize\fP parameters are ignored in this implementation.  This function is
available for backwards compatibility with older C libraries and \fBcalloc\fP
and should not be used in new code.
.TP
\fBdealloca\fP
Explicitly frees the temporary memory allocation beginning at \fIptr\fP so the
memory can be reused by another call to allocate memory.  If \fIptr\fP is
\fBNULL\fP then no memory will be explicitly freed.  All of the previous
contents will be destroyed.  This function can only be used to free memory that
was allocated with the \fBalloca\fP, \fBstrdupa\fP and \fBstrndupa\fP 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.
.PP
The following 5 functions are available as replacements for existing C library
extension functions that always abort and never return \fBNULL\fP if there is
insufficient memory to fulfil a request.  To use these you must include
\fImpatrol.h\fP before all other header files, although on UNIX and Windows
platforms (and AmigaOS when using \fBgcc\fP) they will be used anyway, albeit
with slightly less tracing information:
.TP
\fBxmalloc\fP
Allocates \fIsize\fP 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
\fIsize\fP bytes in length.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then the program will be terminated and the \fIOUTMEM\fP error will be
given.  The allocated memory must be deallocated with \fBxfree\fP or reallocated
with \fBxrealloc\fP.
.TP
\fBxcalloc\fP
Allocates \fInelem\fP elements of \fIsize\fP 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 \fInelem * size\fP bytes in length.  If \fInelem * size\fP
is \fI0\fP then the amount of memory allocated will be implicitly rounded up to
\fI1\fP byte.  If there is not enough space in the heap then the program will be
terminated and the \fIOUTMEM\fP error will be given.  The allocated memory must
be deallocated with \fBxfree\fP or reallocated with \fBxrealloc\fP.
.TP
\fBxstrdup\fP
Allocates exactly enough memory from the heap to duplicate \fIstr\fP (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP 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 \fIOUTMEM\fP error
will be given.  The allocated memory must be deallocated with \fBxfree\fP or
reallocated with \fBxrealloc\fP.
.TP
\fBxrealloc\fP
Resizes the memory allocation beginning at \fIptr\fP to \fIsize\fP bytes and
returns a pointer to the first byte of the new allocation after copying
\fIptr\fP to the newly-allocated memory, which will be truncated if \fIsize\fP
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
\fIsize\fP bytes in length.  If \fIptr\fP is \fBNULL\fP then the call will be
equivalent to \fBxmalloc\fP.  If \fIsize\fP is \fI0\fP then it will be implictly
rounded up to \fI1\fP.  If \fIsize\fP 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
\fIOUTMEM\fP error will be given.  The allocated memory must be deallocated with
\fBxfree\fP and can be reallocated again with \fBxrealloc\fP.
.TP
\fBxfree\fP
Frees the memory allocation beginning at \fIptr\fP so the memory can be reused
by another call to allocate memory.  If \fIptr\fP is \fBNULL\fP then no memory
will be freed.  All of the previous contents will be destroyed.
.PP
The following 5 functions are available as replacements for existing C++ library
functions, but the replacements in \fImpatrol.h\fP will only be used if the
\fBMP_NOCPLUSPLUS\fP preprocessor macro is not defined.  The replacement
operators make use of the preprocessor in order to obtain source-level
information.  If this causes problems then you should define the
\fBMP_NONEWDELETE\fP preprocessor macro and use the \fBMP_NEW\fP,
\fBMP_NEW_NOTHROW\fP and \fBMP_DELETE\fP macros instead of \fBnew\fP and
\fBdelete\fP directly.  To use these C++ features you must include
\fImpatrol.h\fP before all other header files, although on UNIX and Windows
platforms (and AmigaOS when using \fBgcc\fP) they will be used anyway, albeit
with slightly less tracing information:
.TP
\fBoperator new\fP
Allocates \fIsize\fP 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
\fIsize\fP bytes in length.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then either the \fIstd::bad_alloc\fP exception will be thrown or the
null pointer will be returned and \fBerrno\fP will be set to \fBENOMEM\fP - the
behaviour depends on whether the nothrow version of the operator is used.  The
allocated memory must be deallocated with \fBoperator delete\fP.
.TP
\fBoperator new[]\fP
Allocates \fIsize\fP 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
\fIsize\fP bytes in length.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then either the \fIstd::bad_alloc\fP exception will be thrown or the
null pointer will be returned and \fBerrno\fP will be set to \fBENOMEM\fP - the
behaviour depends on whether the nothrow version of the operator is used.  The
allocated memory must be deallocated with \fBoperator delete[]\fP.
.TP
\fBoperator delete\fP
Frees the memory allocation beginning at \fIptr\fP so the memory can be reused
by another call to allocate memory.  If \fIptr\fP is \fBNULL\fP then no memory
will be freed.  All of the previous contents will be destroyed.  This function
must only be used with memory allocated by \fBoperator new\fP.
.TP
\fBoperator delete[]\fP
Frees the memory allocation beginning at \fIptr\fP so the memory can be reused
by another call to allocate memory.  If \fIptr\fP is \fBNULL\fP then no memory
will be freed.  All of the previous contents will be destroyed.  This function
must only be used with memory allocated by \fBoperator new[]\fP.
.TP
\fBset_new_handler\fP
Installs a low-memory handler specifically for use with \fBoperator new\fP and
\fBoperator new[]\fP and returns a pointer to the previously installed handler,
or the null pointer if no handler had been previously installed.  This will be
called repeatedly by both functions when they would normally return \fBNULL\fP,
and this loop will continue until they manage to allocate the requested space.
Note that this function is equivalent to \fB__mp_nomemory\fP and will replace
the handler installed by that function.
.PP
The following 10 functions are available as replacements for existing C library
memory operation functions.  To use these you must include \fImpatrol.h\fP
before all other header files, although on UNIX and Windows platforms (and
AmigaOS when using \fBgcc\fP) they will be used anyway, albeit with slightly
less tracing information:
.TP
\fBmemset\fP
Writes \fIsize\fP bytes of value \fIbyte\fP to the memory location beginning at
\fIptr\fP and returns \fIptr\fP.  If \fIsize\fP is \fB0\fP then no bytes will
be written.  If the operation would affect an existing memory allocation in the
heap but would straddle that allocation's boundaries then an error message will
be generated in the log file and no bytes will be written.
.TP
\fBbzero\fP
Writes \fIsize\fP zero bytes to the memory location beginning at \fIptr\fP.  If
\fIsize\fP is \fB0\fP then no bytes will be written.  If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be written.  This function is available for backwards
compatibility with older C libraries and should not be used in new code.
.TP
\fBmemccpy\fP
Copies \fIsize\fP bytes from \fIsrc\fP to \fIdest\fP and returns \fBNULL\fP, or
copies the number of bytes up to and including the first occurrence of
\fIbyte\fP if \fIbyte\fP exists within the specified range and returns a pointer
to the first byte after \fIbyte\fP.  If \fIsize\fP is \fB0\fP or \fIsrc\fP is
the same as \fIdest\fP then no bytes will be copied.  The source and destination
ranges should not overlap, otherwise a warning will be written to the log file.
If the operation would affect an existing memory allocation in the heap but
would straddle that allocation's boundaries then an error message will be
generated in the log file and no bytes will be copied.
.TP
\fBmemcpy\fP
Copies \fIsize\fP bytes from \fIsrc\fP to \fIdest\fP and returns \fIdest\fP.  If
\fIsize\fP is \fB0\fP or \fIsrc\fP is the same as \fIdest\fP then no bytes will
be copied.  The source and destination ranges should not overlap, otherwise a
warning will be written to the log file.  If the operation would affect an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be copied.
.TP
\fBmemmove\fP
Copies \fIsize\fP bytes from \fIsrc\fP to \fIdest\fP and returns \fIdest\fP.  If
\fIsize\fP is \fB0\fP or \fIsrc\fP is the same as \fIdest\fP then no bytes will
be copied.  If the operation would affect an existing memory allocation in the
heap but would straddle that allocation's boundaries then an error message will
be generated in the log file and no bytes will be copied.
.TP
\fBbcopy\fP
Copies \fIsize\fP bytes from \fIsrc\fP to \fIdest\fP.  If \fIsize\fP is \fB0\fP
or \fIsrc\fP is the same as \fIdest\fP then no bytes will be copied.  If the
operation would affect an existing memory allocation in the heap but would
straddle that allocation's boundaries then an error message will be generated in
the log file and no bytes will be copied.  This function is available for
backwards compatibility with older C libraries and should not be used in new
code.
.TP
\fBmemcmp\fP
Compares \fIsize\fP bytes from \fIptr1\fP and \fIptr2\fP and returns \fB0\fP if
all of the bytes are identical, or returns the byte difference of the first
differing bytes.  If \fIsize\fP is \fB0\fP or \fIptr1\fP is the same as
\fIptr2\fP then no bytes will be compared.  If the operation would read from an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be compared.
.TP
\fBbcmp\fP
Compares \fIsize\fP bytes from \fIptr1\fP and \fIptr2\fP and returns \fB0\fP if
all of the bytes are identical, or returns the byte difference of the first
differing bytes.  If \fIsize\fP is \fB0\fP or \fIptr1\fP is the same as
\fIptr2\fP then no bytes will be compared.  If the operation would read from an
existing memory allocation in the heap but would straddle that allocation's
boundaries then an error message will be generated in the log file and no bytes
will be compared.  This function is available for backwards compatibility with
older C libraries and should not be used in new code.
.TP
\fBmemchr\fP