xmlmemory: interface for the memory allocator

## xmlmemory

xmlmemory - interface for the memory allocator

provides interfaces for the memory allocator, including debugging capabilities.

Author(s): Daniel Veillard

## Synopsis

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

## Description

## Details

### Macro DEBUG_MEMORY

    #define 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 * freeFunc,
    					 xmlMallocFunc * mallocFunc,
    					 xmlMallocFunc * mallocAtomicFunc,
    					 xmlReallocFunc * reallocFunc,
    					 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 freeFunc,
    					 xmlMallocFunc mallocFunc,
    					 xmlMallocFunc mallocAtomicFunc,
    					 xmlReallocFunc reallocFunc,
    					 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 unsigned 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 * freeFunc,
    					 xmlMallocFunc * mallocFunc,
    					 xmlReallocFunc * reallocFunc,
    					 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 freeFunc,
    					 xmlMallocFunc mallocFunc,
    					 xmlReallocFunc reallocFunc,
    					 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.