MATLAB^®

mxCalloc (C and Fortran) - Allocate dynamic memory for array using MATLAB memory manager

C Syntax

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

Fortran Syntax

mwPointer mxCalloc(n, size)
mwSize n, size

Arguments

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.)

Returns

A pointer to the start of the allocated dynamic memory, if successful. If unsuccessful in a stand alone (non-MEX-file) application, mxCalloc returns NULL in C (0 in Fortran). 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 to allocate memory. The mxCalloc function 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 manager.

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

In stand alone MATLAB C applications, mxCalloc calls the ANSI C calloc function.

By default, in a MEX-file, mxCalloc generates nonpersistent mxCalloc 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 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 to deallocate the memory.

C Examples

See

explore.c in the mex subdirectory of the examples directory
phonebook.c and revord.c in the refbook subdirectory of the examples directory

For additional examples, see mxcalcsinglesubscript.c and mxsetdimensions.c in the mx subdirectory of the examples directory.