mxRealloc (C and Fortran)

C Syntax

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

Fortran Syntax

#include "fintrf.h"
mwPointer mxRealloc(ptr, size)
mwPointer ptr
mwSize size

Arguments

Returns

Pointer to the start of the reallocated block of memory, if successful. If unsuccessful in a MAT or engine standalone application, then mxRealloc returns NULL in C (0 in Fortran) and leaves the original memory block unchanged. (Use mxFree to free the original memory block). If unsuccessful in a MEX file, then the MEX file terminates and control returns to the MATLAB^® prompt.

mxRealloc is unsuccessful when there is insufficient free heap space.

Description

mxRealloc changes the size of a memory block that has been allocated with mxCalloc, mxMalloc, or mxRealloc. To allocate memory in MATLAB applications, use mxRealloc instead of the ANSI^® C realloc function.

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 might be in a different location from the original memory, so the returned pointer can be different from ptr. If the memory location changes, then mxRealloc frees the original memory block pointed to by ptr.

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

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

In MEX files, but not MAT or engine applications, mxRealloc registers the allocated memory with the MATLAB memory manager. When control returns to the MATLAB prompt, the memory manager then automatically frees, or deallocates, this memory.

How you manage the memory created by this function depends on the purpose of the data assigned to it. If you assign it to an output argument in plhs[] using a function such as mxSetDoubles, then MATLAB is responsible for freeing the memory.

If you use the data internally, then the MATLAB memory manager maintains a list of all memory allocated by the function and automatically frees (deallocates) the memory when control returns to the MATLAB prompt. In general, we recommend that MEX file functions destroy their own temporary arrays and free their own dynamically allocated memory. It is more efficient to perform this cleanup in the source MEX file than to rely on the automatic mechanism. Therefore, when you finish using the memory allocated by this function, call mxFree to deallocate the memory.

If you do not assign this data to an output argument, and you want it to persist after the MEX file completes, then call mexMakeMemoryPersistent after calling this function. If you write a MEX file with persistent memory, then be sure to register a mexAtExit function to free allocated memory in the event your MEX file is cleared.

Examples

See these examples in matlabroot/extern/examples/mx:

See Also

mexAtExit, mexMakeArrayPersistent, mexMakeMemoryPersistent, mxCalloc, mxDestroyArray, mxFree, mxMalloc