| MATLAB Application Program Interface Reference | Help Desk |
mexFunction
Entry point to a C MEX-file
#include "mex.h" void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]);nlhs
MATLAB sets nlhs with the number of expected mxArrays.
MATLAB sets plhs to a pointer to an array of NULL pointers.
MATLAB sets nrhs to the number of input mxArrays.
MATLAB sets prhs to a pointer to an array of input mxArrays. These mxArrays are declared as constant; they are read only and should not be modified by your MEX-file. Changing the data in these mxArrays may produce undesired side effects.
mexFunction is not a routine you call. Rather, mexFunction is the generic name of the function entry point that must exist in every C source MEX-file. When you invoke a MEX-function, MATLAB finds and loads the corresponding MEX-file of the same name. MATLAB then searches for a symbol named mexFunction within the MEX-file. If it finds one, it calls the MEX-function using the address of the mexFunction symbol. If MATLAB cannot find a routine named mexFunction inside the MEX-file, it issues an error message.
When you invoke a MEX-file, MATLAB automatically seeds nlhs, plhs, nrhs, and prhs with the caller's information. In the syntax of the MATLAB language, functions have the general form
[a,b,c,...] = fun(d,e,f,...)where the
a,b,c... are left-hand side arguments and the d,e,f... are right-hand side arguments. The arguments nlhs and nrhs contain the number of left-hand side and right-hand side arguments, respectively, with which the MEX-function is called. prhs is a pointer to a length nrhs array of pointers to the right-hand side mxArrays. plhs is a pointer to a length nlhs array where your C function must put pointers for the returned left-hand side mxArrays.
Consider a MEX-file named FirstMex that figures out the class (category) of each input argument. FirstMex then places a random scalar in each left-hand side argument:
mxClassID determine_class(mxArray *array_ptr)
{
mxClassID category;
/* Display the class name of each input mxArray. */
category = mxGetClassID(array_ptr);
switch (category) {
case mxCHAR_CLASS: mexPrintf("String "); break;
case mxSTRUCT_CLASS:mexPrintf("Structure "); break;
case mxSPARSE_CLASS:mexPrintf("Sparse "); break;
case mxCELL_CLASS: mexPrintf("Cell "); break;
case mxUNKNOWN_CLASS:mexWarnMsgTxt("Unknown Class.");
break;
default: mexPrintf("Full Numeric "); break;
}
}
void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray
*prhs[])
{
mxArray *array_ptr, *new_array_ptr;
int c;
double pr[1];
/* Examine input (right-hand-side) arguments. */
mexPrintf("\nThere are %d right-hand-side arguments.",
nrhs);
for (c=0; c<nrhs; c++) {
mexPrintf("\n\tInput Arg %d: ", c+1);
array_ptr = (mxArray *)prhs[c];
determine_class(array_ptr);
}
/* Examine output (left-hand-side) arguments. */
mexPrintf("\n\nThere are %d left-hand-side arguments.\n",
nlhs);
for (c=0; c<nlhs; c++) {
plhs(c) = mxCreateDoubleMatrix(1, 1, mxREAL);
mxGetPr(plhs(c))(0) = rand();
}
}
For an additional example, see mexFunction.c in the mex subdirectory of the examples directory.