MATLAB^®

mxRealloc (C and Fortran) - Reallocate memory

C Syntax

#include "matrix.h"
#include <stdlib.h>
void *mxRealloc(void *ptr, mwSize size);

Fortran Syntax

mwPointer mxRealloc(ptr, size)
mwPointer ptr
mwSize size

Arguments

ptr: Pointer to a block of memory allocated by mxCalloc, mxMalloc, or mxRealloc
size: New size of allocated memory, in bytes

Returns

A pointer to the reallocated block of memory, or NULL in C (0 in Fortran) if size is 0. In a stand alone (non-MEX-file) application, if not enough memory is available to expand the block to the given size, mxRealloc returns NULL in C (0 in Fortran). In a MEX-file, if not enough memory is available to expand the block to the given size, the MEX-file terminates and control returns to the MATLAB^® prompt.

Description

mxRealloc changes the size of a memory block that has been allocated with mxCalloc, mxMalloc, or mxRealloc.

If size is 0 and ptr is not NULL in C (0 in Fortran), mxRealloc frees the memory pointed to by ptr and returns NULL in C (0 in Fortran).

If size is greater than 0 and ptr is NULL in C (0 in Fortran), mxRealloc behaves like mxMalloc, allocating a new block of memory of size bytes and returning a pointer to the new block.

Otherwise, mxRealloc changes the size of the memory block pointed to by ptr to size bytes. The contents of the reallocated memory are unchanged up to the smaller of the new and old sizes. The reallocated memory may be in a different location from the original memory, so the returned pointer can be different from ptr. If the memory location changes, mxRealloc frees the original memory block pointed to by ptr.

In a stand alone (non-MEX-file) application, if not enough memory is available to expand the block to the given size, mxRealloc returns NULL in C (0 in Fortran) and leaves the original memory block unchanged. You must use mxFree to free the original memory block.

MATLAB maintains a list of all memory allocated by mxRealloc. By default, in a MEX-file, mxRealloc generates nonpersistent mxRealloc data. The memory management facility automatically deallocates the memory as soon as the MEX-file ends.

If you want the memory to persist after a MEX-file completes, call mexMakeMemoryPersistent after calling mxRealloc. If you write a MEX-file with persistent memory, be sure to register a mexAtExit function to free allocated memory when your MEX-file is cleared.

When you finish using the memory allocated by mxRealloc, call mxFree. mxFree deallocates the memory.

C Examples

See mxsetnzmax.c in the mx subdirectory of the examples directory.