GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# memory

## Memory allocation/deallocation functions

Contents

- MagickAllocFunctions
- MagickMalloc
- MagickMallocAligned
- MagickMallocCleared
- MagickCloneMemory
- MagickRealloc
- MagickFree
- MagickFreeAligned

# MagickAllocFunctions

## Synopsis

    void MagickAllocFunctions( MagickFreeFunc free_func, MagickMallocFunc malloc_func,
                               MagickReallocFunc realloc_func );

## Description

MagickAllocFunctions() provides a way for the user to supply a preferred free(), malloc(), and realloc() functions. Otherwise the default system versions are used. If an alternative allocator is to be used, this function should be invoked prior to invoking InitializeMagick().

The format of the MagickAllocFunctions method is:

    void MagickAllocFunctions( MagickFreeFunc free_func, MagickMallocFunc malloc_func,
                               MagickReallocFunc realloc_func );

free_func:
  Function to free memory.
malloc_func:
  Function to allocate memory.
realloc_func:
  Function to reallocate memory.

# MagickMalloc

## Synopsis

    void *MagickMalloc( const size_t size );

## Description

MagickMalloc() returns a pointer to a block of memory of at least size bytes suitably aligned for any use. NULL is returned if insufficient memory is available or the requested size is zero.

The format of the MagickMalloc method is:

    void *MagickMalloc( const size_t size );

A description of each parameter follows:

size:
  The size of the memory in bytes to allocate.

# MagickMallocAligned

## Synopsis

    void *MagickMallocAligned( size_t alignment, const size_t size );

## Description

MagickMallocAligned() allocates memory and returns a pointer to a block of memory capable of storing at least size bytes with the allocation's base address being an even multiple of alignment. The size of the buffer allocation is rounded up as required in order to consume a block of memory starting at least at the requested alignment and ending at at least the requested alignment.

The requested alignment should be a power of 2 at least as large as sizeof a void pointer.

NULL is returned if insufficient memory is available, the requested size is zero, or integer overflow was detected.

This function is intended for allocating special-purpose buffers which benefit from specific alignment.

The allocated memory should only be freed using MagickFreeAligned() and may not be reallocated.

The format of the MagickMallocAligned method is:

    void *MagickMallocAligned( size_t alignment, const size_t size );

A description of each parameter follows:

alignment:
  The alignment of the base and size of the allocated memory.
size:
  The size of the memory in bytes to allocate.

# MagickMallocCleared

## Synopsis

    void *MagickMallocCleared( const size_t size );

## Description

MagickMallocCleared() returns a pointer to a block of memory of at least size bytes suitably aligned for any use. NULL is returned if insufficient memory is available or the requested size is zero. This version differs from MagickMalloc in that the allocated bytes are cleared to zero.

The format of the MagickMallocCleared method is:

    void *MagickMallocCleared( const size_t size );

A description of each parameter follows:

size:
  The size of the memory in bytes to allocate.

# MagickCloneMemory

## Synopsis

    void *MagickCloneMemory( void *destination, const void *source, const size_t size );

## Description

MagickCloneMemory() copies size bytes from memory area source to the destination. Copying between objects that overlap will take place correctly. It returns destination.

The format of the MagickCloneMemory method is:

    void *MagickCloneMemory( void *destination, const void *source, const size_t size );

size:
  The size of the memory in bytes to allocate.

# MagickRealloc

## Synopsis

    void *MagickRealloc( void *memory, const size_t size );

## Description

MagickRealloc() changes the size of the memory and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. If size is zero, then the memory is freed and a NULL value is returned. If the memory allocation fails, then the existing memory is freed, and a NULL value is returned.

Note that the behavior of this function is similar to BSD reallocf(3), see https://www.freebsd.org/cgi/man.cgi?query=reallocf

The format of the MagickRealloc method is:

    void *MagickRealloc( void *memory, const size_t size );

A description of each parameter follows:

memory:
  A pointer to a memory allocation.
size:
  The new size of the allocated memory.

# MagickFree

## Synopsis

    void MagickFree( void *memory );

## Description

MagickFree() frees memory that has already been allocated by MagickMalloc() or other other other allocators directly compatible with the currently defined memory allocator (which defaults to the system malloc()). For convenience, a NULL argument is ignored.

The format of the MagickFree method is:

    void MagickFree( void *memory );

A description of each parameter follows:

memory:
  A pointer to a block of memory to free for reuse.

# MagickFreeAligned

## Synopsis

    void MagickFreeAligned( void *memory );

## Description

MagickFreeAligned() frees aligned memory that has previously been allocated via MagickMallocAligned(). For convenience, a NULL argument is ignored.

This function exists in case the pointer allocated by MagickMallocAligned() can not be used directly with MagickFree().

The format of the MagickFreeAligned method is:

    void MagickFreeAligned( void *memory );

A description of each parameter follows:

memory:
  A pointer to a block of memory to free for reuse.