MATLAB Application Program Interface Reference

Allocate dynamic memory using MATLAB's memory manager

#include "matrix.h"
#include <stdlib.h>
void *mxCalloc(size_t n, size_t size);

Arguments

Number of elements to allocate. This must be a nonnegative number.

size

Number of bytes per element. (The C sizeof operator calculates the number of bytes per element.)

Returns

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

mxCalloc is unsuccessful when there is insufficient free heap space.

Description

MATLAB applications should always call mxCalloc rather than calloc (or malloc) to allocate memory. Note that mxCalloc works differently in MEX-files than in stand-alone MATLAB applications.

In MEX-files, mxCalloc automatically

Allocates enough contiguous heap space to hold n elements.
Initializes all n elements to 0.
Registers the returned heap space with the MATLAB memory management facility.

The MATLAB memory management facility maintains a list of all memory allocated by mxCalloc (and by the mxCreate calls). The MATLAB memory management facility automatically frees (deallocates) all of a MEX-file's parcels when control returns to the MATLAB prompt.

In stand-alone MATLAB applications, mxCalloc defaults to calling the ANSI C calloc function. If this default behavior is unacceptable, you can write your own memory allocation routine, and then register this routine with mxSetAllocFcns. Then, whenever mxCalloc is called, mxCalloc calls your memory allocation routine instead of calloc.

By default, in a MEX-file, mxCalloc generates nonpersistent mxCalloc data. In other words, the memory management facility 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 mxCalloc. 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 mxCalloc, call mxFree. mxFree deallocates the memory.

Examples

This example uses mxCalloc to allocate enough heap space to hold a string.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 char *buf;
 int   buflen;
 int   status;

   if (mxIsString(prhs[0]))  {
   /* Find out how long the input string array is. */
     buflen = mxGetN(prhs[0])+1;
   /* Allocate enough memory to hold the converted string. */ 
     buf = mxCalloc(buflen, sizeof(char));
   /* Copy the string data into buf. */ 
     status = mxGetString(prhs[0], buf, buflen); 
   /* Manipulate the string.*/
...

   /* When finished using the string, deallocate it. */
     mxFree(buf);
   }
   else
     mexErrMsgTxt("Input argument must be a string.");

For an additional example, see mxCalloc.c in the mx subdirectory of the examples directory.