A.6 mpatrol library functions

The following 42 functions are available as support routines for additional control and tracing in the mpatrol library. Although they are documented here as being prefixed by `__mp_', their equivalent functions that are prefixed by `mpatrol_' are also defined as aliases in the mpatrol.h header file. To use these you should include the mpatrol.h header file.

int __mp_atexit(void (*func)(void))

Installs a function to be called when the mpatrol library terminates. Up to 32 such functions can be registered and will be called in reverse order of registration. Returns `1' on success or `0' if func could not be registered.

unsigned long __mp_setoption(long opt, unsigned long val)

Sets the value of an mpatrol option after the library has been initialised. Options that require values are listed in mpatrol.h prefixed with `MP_OPT_*'. The opt argument should be set to one of these macros, and the val argument should be set to the option value, cast to an unsigned integer. The return value will be `0' on success and `1' on failure. Options that are flags are listed in mpatrol.h prefixed with `MP_FLG_*'. Multiple flags can be set or unset at once using the MP_OPT_SETFLAGS and MP_OPT_UNSETFLAGS options respectively, with the necessary flags specified in val. The return value will be `0' on success and a combination of all of the flags that could not be set or unset on failure.

int __mp_getoption(long opt, unsigned long *val)

Gets the value of an mpatrol option after the library has been initialised. If opt is a valid option listed in mpatrol.h then `1' will be returned and the associated value will be returned in val and cast to an unsigned integer, otherwise `0' will be returned. If opt is MP_OPT_SETFLAGS then all of the mpatrol library flags that are set will be returned in val. If opt is MP_OPT_UNSETFLAGS then all of the mpatrol library flags that are not set will be returned in val.

unsigned long __mp_libversion(void)

Returns the version number of the mpatrol library. This can be useful for verifying that the version of the mpatrol library that a program is linked with is the one expected at compile-time.

const char *__mp_strerror(__mp_errortype err)

Returns the error message corresponding to the error code err or `NULL' if no such error code exists. The most recent error code recorded by the mpatrol library can be obtained by examining __mp_errno.

const char *__mp_function(__mp_alloctype func)

Returns the name of the function corresponding to the allocation type func or `NULL' if no such allocation type exists.

int __mp_setuser(const void *ptr, const void *data)

Sets the user data for the memory allocation containing ptr. The contents of data are entirely application-specific as user data will never be examined by the mpatrol library. Such data is associated with a memory allocation for its entire lifetime unless overridden by a subsequent call to __mp_setuser(). As such, the user data must be valid for the entire lifetime of the memory allocation, perhaps even after the allocation has been freed if the NOFREE option is being used. This function returns `1' if there is an allocated memory block containing ptr, and `0' otherwise.

int __mp_setmark(const void *ptr)

Sets the marked flag for the memory allocation containing ptr, indicating that the memory allocation cannot be freed (but can be reallocated) and thus will not be listed as a memory leak. This function returns `1' if there is an allocated memory block containing ptr, and `0' otherwise. Note that a memory allocation made by alloca(), strdupa() or strndupa() may not be marked.

int __mp_info(const void *ptr, __mp_allocinfo *info)

Obtains information about a specific memory allocation by placing statistics about ptr in info. If ptr does not belong to a previously allocated memory allocation or free memory block then `0' will be returned, otherwise `1' will be returned and info will contain the following information (note that a free memory block will only contain the block and size fields and can be identified by not having the allocated flag set):

Field	Description
block	Pointer to first byte of allocation.
size	Size of allocation in bytes.
type	Type of function which allocated memory.
alloc	Allocation index.
realloc	Number of times reallocated.
thread	Thread identifier.
event	Event of last modification.
func	Function in which allocation took place.
file	File in which allocation took place.
line	Line number at which allocation took place.
stack	Pointer to function call stack.
typestr	Type stored in allocation.
typesize	Size of type stored in allocation.
userdata	User data associated with allocation.
allocated	Indicates if allocation was allocated.
freed	Indicates if allocation has been freed.
marked	Indicates if allocation has been marked.
profiled	Indicates if allocation has been profiled.
traced	Indicates if allocation has been traced.
internal	Indicates if allocation is internal.

int __mp_syminfo(const void *ptr, __mp_symbolinfo *info)

Obtains symbolic information about a specific code address by placing statistics about ptr in info. If ptr does not belong to a function symbol then `0' will be returned, otherwise `1' will be returned and info will contain the following information:

Field	Description
name	Name of symbol.
object	File containing symbol.
addr	Start address of symbol.
size	Size of symbol.
file	Filename corresponding to address.
line	Line number corresponding to address.

const char *__mp_symbol(const void *ptr)

Obtains the name of a function symbol containing the code address specified in ptr. If ptr does not belong to a function symbol then `NULL' will be returned.

int __mp_printinfo(const void *ptr)

Displays information about a specific memory allocation containing ptr to the standard error file stream. If ptr does not belong to a previously allocated memory allocation or free memory block then `0' will be returned, otherwise `1' will be returned. This function is intended to be called from within a debugger.

unsigned long __mp_snapshot(void)

Returns the current event number, effectively taking a snapshot of the heap. This number can then be used in later calls to __mp_iterate().

size_t __mp_iterate(int (*func)(const void *, void *), void *data, unsigned long event)

Iterates over all of the current allocated and freed memory allocations, calling func with the start address of every memory allocation that has been modified since event number event. If func is `NULL' then __mp_printinfo() will be used as the callback function. If event is `0' then func will be called with the start address of every memory allocation. If func returns a negative number then the iteration process will be stopped immediately. If func returns a positive number above zero then __mp_iterate() will return the number of times func returned a non-zero number after the iteration process has stopped. The data argument is passed directly to func as its second argument and is not read by the mpatrol library.

size_t __mp_iterateall(int (*func)(const void *, void *), void *data)

Iterates over all of the current allocated and freed memory allocations and any free memory blocks, calling func with the start address of every memory allocation or free block. If func is `NULL' then __mp_printinfo() will be used as the callback function. If func returns a negative number then the iteration process will be stopped immediately. If func returns a positive number above zero then __mp_iterate() will return the number of times func returned a non-zero number after the iteration process has stopped. The data argument is passed directly to func as its second argument and is not read by the mpatrol library. Note that unlike __mp_iterate(), this function will also include internal memory allocations made by the mpatrol library and is intended for walking the entire heap.

int __mp_addallocentry(const char *file, unsigned long line, size_t size)

Adds an entry representing an allocation of size size to the leak table. The allocation will be associated with a source filename of file and a line number of line if the former is non-`NULL' and the latter is non-zero. If file is non-`NULL' and line is `0' then file represents the name of the function that made the allocation. If file is `NULL' and line is non-zero then line represents the code address at which the allocation was made. If file is `NULL' and line is `0' then the location of the allocation is unknown. Returns `1' on success and `0' if there was no more memory available to add another entry to the leak table.

int __mp_addfreeentry(const char *file, unsigned long line, size_t size)

Adds an entry representing a deallocation of size size to the leak table. The deallocation will be associated with a source filename of file and a line number of line if the former is non-`NULL' and the latter is non-zero. If file is non-`NULL' and line is `0' then file represents the name of the function that made the deallocation. If file is `NULL' and line is non-zero then line represents the code address at which the deallocation was made. If file is `NULL' and line is `0' then the location of the deallocation is unknown. Returns `1' on success and `0' if there was no existing allocation from the same location in the leak table.

void __mp_clearleaktable(void)

Deletes all of the existing entries in the leak table, making it empty. This will also affect the behaviour of the LEAKTABLE option since that option will then only be able to show a summary of the entries in the leak table that were collected after the last call to this function rather than from the start of program execution.

int __mp_startleaktable(void)

Starts the automatic logging of all memory allocations, reallocations and deallocations to the leak table. Returns `1' if such logging was already being performed and `0' otherwise.

int __mp_stopleaktable(void)

Stops the automatic logging of all memory allocations, reallocations and deallocations to the leak table. Returns `1' if such logging was already being performed and `0' otherwise.

void __mp_leaktable(size_t size, int opt, unsigned char flags)

Displays a summary of up to size entries from the leak table, or all entries if size is `0'. If opt is MP_LT_ALLOCATED then all allocated entries will be displayed, if opt is MP_LT_FREED then all freed entries will be displayed and if opt is MP_LT_UNFREED then all unfreed entries will be displayed. The summary is normally sorted in descending order of total bytes from each entry, but this can be changed by setting flags to any combination of MP_LT_COUNTS (to sort by the number of occurrences in each entry) and MP_LT_BOTTOM (to sort in ascending order).

void __mp_memorymap(int stats)

If stats is non-zero then the current statistics of the mpatrol library will be displayed. If the heap contains at least one allocated, freed or free block then a map of the current heap will also be displayed.

void __mp_summary(void)

Displays information about the current state of the mpatrol library, including its settings and any relevant statistics.

int __mp_stats(__mp_heapinfo *info)

Obtains statistics about the current state of the heap and places them in info. If this information could not be determined then `0' will be returned, otherwise `1' will be returned and info will contain the following information:

Field	Description
acount	Total number of allocated blocks.
atotal	Total size of allocated blocks.
fcount	Total number of free blocks.
ftotal	Total size of free blocks.
gcount	Total number of freed blocks.
gtotal	Total size of freed blocks.
icount	Total number of internal blocks.
itotal	Total size of internal blocks.
mcount	Total number of marked blocks.
mtotal	Total size of marked blocks.

void __mp_check(void)

Forces the library to perform an immediate check of the overflow buffers of every memory allocation and to ensure that nothing has overwritten any free blocks. If any memory allocations made by the alloca() family of functions are out of scope then this function will also cause them to be freed.

__mp_prologuehandler __mp_prologue(const __mp_prologuehandler func)

Installs a prologue function to be called before any memory allocation, reallocation or deallocation function. This function will return a pointer to the previously installed prologue function, or the null pointer if no prologue function had been previously installed. The following arguments will be used to call the prologue function (the last four arguments contain the function name, file name, line number and the return address of the calling function, or null pointers and zero if they cannot be determined):

Argument 1	Argument 2	Argument 3	Called by
-1	size	align	malloc(), etc.
ptr	size	align	realloc(), etc.
ptr	-1	0	free(), etc.
ptr	-2	1	strdup(), etc.

__mp_epiloguehandler __mp_epilogue(const __mp_epiloguehandler func)

Installs an epilogue function to be called after any memory allocation, reallocation or deallocation function. This function will return a pointer to the previously installed epilogue function, or the null pointer if no epilogue function had been previously installed. The following arguments will be used to call the epilogue function (the last four arguments contain the function name, file name, line number and the return address of the calling function, or null pointers and zero if they cannot be determined):

Argument	Called by
ptr	malloc(), realloc(), strdup(), etc.
-1	free(), etc.

__mp_nomemoryhandler __mp_nomemory(const __mp_nomemoryhandler func)

Installs a low-memory handler and returns a pointer to the previously installed handler, or the `NULL' pointer if no handler had been previously installed. This will be called once by C memory allocation functions, and repeatedly by C++ memory allocation functions, when they would normally return `NULL'. The four arguments contain the function name, file name, line number and the return address of the calling function, or null pointers and zero if they cannot be determined. Note that this function is equivalent to set_new_handler() and will replace the handler installed by that function.

int __mp_printf(const char *fmt, ...)

Writes format string fmt with variable arguments to the log file, with each line prefixed by `>'. The final length of the string that is written to the log file must not exceed 1024 characters. Returns the number of characters written, or a negative number upon error.

int __mp_vprintf(const char *fmt, va_list args)

Writes format string fmt with variable argument list args to the log file, with each line prefixed by `>'. The final length of the string that is written to the log file must not exceed 1024 characters. Returns the number of characters written, or a negative number upon error.

void __mp_locprintf(const char *fmt, ...)

Writes format string fmt with variable arguments to the log file, with each line prefixed by `>'. The final length of the string that is written to the log file must not exceed 1024 characters. It also writes information to the log file about where the call to this function was made, which includes the source file location and the call stack if they are available.

void __mp_vlocprintf(const char *fmt, va_list args)

Writes format string fmt with variable argument list args to the log file, with each line prefixed by `>'. The final length of the string that is written to the log file must not exceed 1024 characters. It also writes information to the log file about where the call to this function was made, which includes the source file location and the call stack if they are available.

void __mp_logmemory(const void *ptr, size_t size)

Displays the contents of a block of memory beginning at ptr, dumping size consecutive bytes to the log file in hexadecimal format.

int __mp_logstack(size_t frames)

Displays the current call stack, skipping frames stack frames from the current stack frame before writing the symbolic stack trace to the log file. Returns `1' if successful, or `0' if the call stack could not be determined or if frames was too large for the current call stack.

int __mp_logaddr(const void *ptr)

Displays information about a specific memory allocation containing ptr to the log file. If ptr does not belong to a previously allocated memory allocation then `0' will be returned, otherwise `1' will be returned.

int __mp_edit(const char *file, unsigned long line)

Invokes a text editor to edit file at line number line via the mpedit command. Returns `1' if the text editor was successfully invoked, `-1' if there was an error, or `0' if there is no support for this feature. This function will only work on a system where the EDIT option works.

int __mp_list(const char *file, unsigned long line)

Displays a context listing of file at line number line via the mpedit command. Returns `1' if the listing was successfully performed, `-1' if there was an error, or `0' if there is no support for this feature. This function will only work on a system where the LIST option works.

int __mp_view(const char *file, unsigned long line)

Either invokes a text editor to edit file at line number line or displays a context listing of file at line number line depending on the setting of the EDIT and LIST options. This is done via the mpedit command and will have no effect if the EDIT and LIST options are not set or if these options are not supported on the system. Returns `1' if the edit or listing was successfully performed, `-1' if there was an error, or `0' if neither of the options were set or if there is no support for this feature.

int __mp_readcontents(const char *file, void *ptr)

Reads the contents of a memory allocation contents file into the memory allocation containing ptr. The name of the file is composed of the file string followed by the allocation index of the memory allocation separated by a dot. If file is `NULL' then it is assumed to be .mpatrol. Returns `1' if the contents were read successfully and `0' otherwise.

int __mp_writecontents(const char *file, const void *ptr)

Writes the contents of the memory allocation containing ptr to an allocation contents file. The name of the file is composed of the file string followed by the allocation index of the memory allocation separated by a dot. If file is `NULL' then it is assumed to be .mpatrol. Returns `1' if the contents were written successfully and `0' otherwise.

long __mp_cmpcontents(const char *file, const void *ptr)

Compares the contents of the memory allocation containing ptr with the contents of a previously written allocation contents file. The name of the file is composed of the file string followed by the allocation index of the memory allocation separated by a dot. If file is `NULL' then it is assumed to be .mpatrol. Any differences are written to the mpatrol log file. Returns the number of differences found, or `-1' if there was an error.

int __mp_remcontents(const char *file, const void *ptr)

Removes the memory allocation contents file that corresponds to the memory allocation containing ptr. The name of the file is composed of the file string followed by the allocation index of the memory allocation separated by a dot. If file is `NULL' then it is assumed to be .mpatrol. Returns `1' if the file was removed successfully and `0' otherwise.