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
denotes more items of the same format. 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.