xmlmemory: interface for the memory allocator

| | | | | libxml2 Reference Manual |

xmlmemory

xmlmemory - interface for the memory allocator

provides interfaces for the memory allocator, including debugging capabilities.

Author(s): Daniel Veillard

Synopsis

#define[xmlRealloc](#xmlRealloc);
#define[xmlMalloc](#xmlMalloc);
#define[xmlMallocAtomic](#xmlMallocAtomic);
#define[DEBUG\_MEMORY](#DEBUG_MEMORY);
#define[xmlMemStrdup](#xmlMemStrdup);
void *[xmlMemRealloc](#xmlMemRealloc)(void * ptr,
size_t size);
int[xmlInitMemory](#xmlInitMemory)(void);
void[xmlMemFree](#xmlMemFree)(void * ptr);
void *[xmlMemMalloc](#xmlMemMalloc)(size_t size);
void[xmlMemDisplayLast](#xmlMemDisplayLast)(FILE * fp,
long nbBytes);
int[xmlMemGet](#xmlMemGet)([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)* freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)* reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)* strdupFunc);
void[xmlMemoryDump](#xmlMemoryDump)(void);
void *[xmlMallocLoc](#xmlMallocLoc)(size_t size,
const char * file,
int line);
void[xmlMemDisplay](#xmlMemDisplay)(FILE * fp);
int[xmlMemBlocks](#xmlMemBlocks)(void);
int[xmlGcMemGet](#xmlGcMemGet)([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)* freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocAtomicFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)* reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)* strdupFunc);
typedef char *[xmlStrdupFunc](#xmlStrdupFunc)(const char * str);
typedef void[xmlFreeFunc](#xmlFreeFunc)(void * mem);
void[xmlMemShow](#xmlMemShow)(FILE * fp,
int nr);
void *[xmlMallocAtomicLoc](#xmlMallocAtomicLoc)(size_t size,
const char * file,
int line);
void *[xmlReallocLoc](#xmlReallocLoc)(void * ptr,
size_t size,
const char * file,
int line);
void[xmlCleanupMemory](#xmlCleanupMemory)(void);
int[xmlMemUsed](#xmlMemUsed)(void);
int[xmlMemSetup](#xmlMemSetup)([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)strdupFunc);
typedef void *[xmlReallocFunc](#xmlReallocFunc)(void * mem,
size_t size);
typedef void *[xmlMallocFunc](#xmlMallocFunc)(size_t size);
int[xmlGcMemSetup](#xmlGcMemSetup)([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocAtomicFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)strdupFunc);
char *[xmlMemoryStrdup](#xmlMemoryStrdup)(const char * str);
char *[xmlMemStrdupLoc](#xmlMemStrdupLoc)(const char * str,
const char * file,
int line);

Description

Details

Macro DEBUG_MEMORY

#define[DEBUG\_MEMORY](#DEBUG_MEMORY);

DEBUG_MEMORY replaces the allocator with a collect and debug shell to the libc allocator. DEBUG_MEMORY should only be activated when debugging libxml i.e. if libxml has been configured with --with-debug-mem too. #define DEBUG_MEMORY_FREED #define DEBUG_MEMORY_LOCATION

Function type xmlFreeFunc

void	xmlFreeFunc (void * mem)

Signature for a free() implementation.

| mem: | an already allocated block of memory |

Function type xmlMallocFunc

void *	xmlMallocFunc (size_t size)

Signature for a malloc() implementation.

| size: | the size requested in bytes | | Returns: | a pointer to the newly allocated block or NULL in case of error. |

Function type xmlReallocFunc

void *	xmlReallocFunc (void * mem,
size_t size)

Signature for a realloc() implementation.

| mem: | an already allocated block of memory | | size: | the new size requested in bytes | | Returns: | a pointer to the newly reallocated block or NULL in case of error. |

Function type xmlStrdupFunc

char *	xmlStrdupFunc (const char * str)

Signature for an strdup() implementation.

| str: | a zero terminated string | | Returns: | the copy of the string or NULL in case of error. |

xmlCleanupMemory ()

void	xmlCleanupMemory (void)

Free up all the memory allocated by the library for its own use. This should not be called by user level code.

xmlGcMemGet ()

int	xmlGcMemGet ([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)* freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocAtomicFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)* reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)* strdupFunc)

Provides the memory access functions set currently in use The mallocAtomicFunc is specialized for atomic block allocations (i.e. of areas useful for garbage collected memory allocators

| freeFunc: | place to save the free() function in use | | mallocFunc: | place to save the malloc() function in use | | mallocAtomicFunc: | place to save the atomic malloc() function in use | | reallocFunc: | place to save the realloc() function in use | | strdupFunc: | place to save the strdup() function in use | | Returns: | 0 on success |

xmlGcMemSetup ()

int	xmlGcMemSetup ([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocAtomicFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)strdupFunc)

Override the default memory access functions with a new set This has to be called before any other libxml routines ! The mallocAtomicFunc is specialized for atomic block allocations (i.e. of areas useful for garbage collected memory allocators Should this be blocked if there was already some allocations done ?

| freeFunc: | the free() function to use | | mallocFunc: | the malloc() function to use | | mallocAtomicFunc: | the malloc() function to use for atomic allocations | | reallocFunc: | the realloc() function to use | | strdupFunc: | the strdup() function to use | | Returns: | 0 on success |

xmlInitMemory ()

int	xmlInitMemory (void)

Initialize the memory layer.

| Returns: | 0 on success |

xmlMallocAtomicLoc ()

void *	xmlMallocAtomicLoc (size_t size,
const char * file,
int line)

a malloc() equivalent, with logging of the allocation info.

| size: | an int specifying the size in byte to allocate. | | file: | the file name or NULL | | line: | the line number | | Returns: | a pointer to the allocated area or NULL in case of lack of memory. |

xmlMallocLoc ()

void *	xmlMallocLoc (size_t size,
const char * file,
int line)

a malloc() equivalent, with logging of the allocation info.

| size: | an int specifying the size in byte to allocate. | | file: | the file name or NULL | | line: | the line number | | Returns: | a pointer to the allocated area or NULL in case of lack of memory. |

xmlMemBlocks ()

int	xmlMemBlocks (void)

Provides the number of memory areas currently allocated

| Returns: | an int representing the number of blocks |

xmlMemDisplay ()

void	xmlMemDisplay (FILE * fp)

show in-extenso the memory blocks allocated

| fp: | a FILE descriptor used as the output file, if NULL, the result is written to the file .memorylist |

xmlMemDisplayLast ()

void	xmlMemDisplayLast (FILE * fp,
long nbBytes)

the last nbBytes of memory allocated and not freed, useful for dumping the memory left allocated between two places at runtime.

| fp: | a FILE descriptor used as the output file, if NULL, the result is written to the file .memorylist | | nbBytes: | the amount of memory to dump |

xmlMemFree ()

void	xmlMemFree (void * ptr)

a free() equivalent, with error checking.

| ptr: | the memory block pointer |

xmlMemGet ()

int	xmlMemGet ([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)* freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)* mallocFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)* reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)* strdupFunc)

Provides the memory access functions set currently in use

| freeFunc: | place to save the free() function in use | | mallocFunc: | place to save the malloc() function in use | | reallocFunc: | place to save the realloc() function in use | | strdupFunc: | place to save the strdup() function in use | | Returns: | 0 on success |

xmlMemMalloc ()

void *	xmlMemMalloc (size_t size)

a malloc() equivalent, with logging of the allocation info.

| size: | an int specifying the size in byte to allocate. | | Returns: | a pointer to the allocated area or NULL in case of lack of memory. |

xmlMemRealloc ()

void *	xmlMemRealloc (void * ptr,
size_t size)

a realloc() equivalent, with logging of the allocation info.

| ptr: | the initial memory block pointer | | size: | an int specifying the size in byte to allocate. | | Returns: | a pointer to the allocated area or NULL in case of lack of memory. |

xmlMemSetup ()

int	xmlMemSetup ([xmlFreeFunc](libxml2-xmlmemory.html#xmlFreeFunc)freeFunc,
[xmlMallocFunc](libxml2-xmlmemory.html#xmlMallocFunc)mallocFunc,
[xmlReallocFunc](libxml2-xmlmemory.html#xmlReallocFunc)reallocFunc,
[xmlStrdupFunc](libxml2-xmlmemory.html#xmlStrdupFunc)strdupFunc)

Override the default memory access functions with a new set This has to be called before any other libxml routines ! Should this be blocked if there was already some allocations done ?

| freeFunc: | the free() function to use | | mallocFunc: | the malloc() function to use | | reallocFunc: | the realloc() function to use | | strdupFunc: | the strdup() function to use | | Returns: | 0 on success |

xmlMemShow ()

void	xmlMemShow (FILE * fp,
int nr)

show a show display of the memory allocated, and dump the @nr last allocated areas which were not freed

| fp: | a FILE descriptor used as the output file | | nr: | number of entries to dump |

xmlMemStrdupLoc ()

char *	xmlMemStrdupLoc (const char * str,
const char * file,
int line)

a strdup() equivalent, with logging of the allocation info.

| str: | the initial string pointer | | file: | the file name or NULL | | line: | the line number | | Returns: | a pointer to the new string or NULL if allocation error occurred. |

xmlMemUsed ()

int	xmlMemUsed (void)

Provides the amount of memory currently allocated

| Returns: | an int representing the amount of memory allocated. |

xmlMemoryDump ()

void	xmlMemoryDump (void)

Dump in-extenso the memory blocks allocated to the file .memorylist

xmlMemoryStrdup ()

char *	xmlMemoryStrdup (const char * str)

a strdup() equivalent, with logging of the allocation info.

| str: | the initial string pointer | | Returns: | a pointer to the new string or NULL if allocation error occurred. |

xmlReallocLoc ()

void *	xmlReallocLoc (void * ptr,
size_t size,
const char * file,
int line)

a realloc() equivalent, with logging of the allocation info.

| ptr: | the initial memory block pointer | | size: | an int specifying the size in byte to allocate. | | file: | the file name or NULL | | line: | the line number | | Returns: | a pointer to the allocated area or NULL in case of lack of memory. |