MATLAB^®

mxMalloc (C and Fortran) - Allocate dynamic memory using MATLAB memory manager

C Syntax

#include "matrix.h"
#include <stdlib.h>
void *mxMalloc(mwSize n);

Fortran Syntax

mwPointer mxMalloc(n)
mwSize n

Arguments

n: Number of bytes to allocate

Returns

A pointer to the start of the allocated dynamic memory, if successful. If unsuccessful in a stand alone (non-MEX-file) application, mxMalloc returns NULL in C (0 in Fortran). If unsuccessful in a MEX-file, the MEX-file terminates and control returns to the MATLAB prompt.

mxMalloc is unsuccessful when there is insufficient free heap space.

Description

MATLAB applications should always call mxMalloc rather than malloc to allocate memory.

mxMalloc works differently in MEX-files than in stand alone MATLAB applications. In MEX-files, mxMalloc automatically

Allocates enough contiguous heap space to hold n bytes.
Registers the returned heap space with the MATLAB memory manager.

The MATLAB memory manager maintains a list of all memory allocated by mxMalloc. The MATLAB memory manager automatically frees (deallocates) all MEX-file parcels when control returns to the MATLAB prompt.

In stand alone MATLAB C applications, mxMalloc calls the ANSI C malloc function.

By default, in a MEX-file, mxMalloc generates nonpersistent mxMalloc data. In other words, the memory manager automatically deallocates the memory as soon as the MEX-file ends. If you want the memory to persist after the MEX-file completes, call mexMakeMemoryPersistent after calling mxMalloc. If you write a MEX-file with persistent memory, be sure to register a mexAtExit function to free allocated memory in the event your MEX-file is cleared.

When you finish using the memory allocated by mxMalloc, call mxFree to deallocate the memory.

C Examples

See mxmalloc.c in the mx subdirectory of the examples directory. For an additional example, see mxsetdimensions.c in the mx subdirectory of the examples directory.