MATLAB Application Program Interface Reference | Help Desk |
mxCalloc
Allocate dynamic memory using MATLAB's memory manager
#include "matrix.h" #include <stdlib.h> void *mxCalloc(size_t n, size_t size);n
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.)
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.
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
n
elements.
n
elements to 0.
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.
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.
mxFree
, mxDestroyArray
, mexMakeArrayPersistent
,mexMakeMemoryPersistent
, mxSetAllocFcns