mexFunction Gateway Routine

The gateway routine is the entry point to the MEX file. It is through this routine that MATLAB^® accesses the rest of the routines in your MEX files. The name of the gateway routine is mexFunction. It takes the place of the main function in your source code.

Naming the MEX File

The name of the source file containing mexFunction is the name of your MEX file, and, hence, the name of the function you call in MATLAB.

The file extension of the binary MEX file is platform-dependent. You find the file extension using the mexext function, which returns the value for the current machine.

Required Parameters

The signature for mexFunction is:

void mexFunction(
    int nlhs, mxArray *plhs[],
    int nrhs, const mxArray *prhs[])

Place this function after your computational routine and any other functions in your source file.

This table describes the parameters for mexFunction.

Declare prhs and plhs as type mxArray *, which means they point to MATLAB arrays. They are vectors that contain pointers to the arguments of the MEX file. The keyword const, which modifies prhs, means that your MEX file does not modify the input arguments.

You can think of the name prhs as representing the “parameters, right-hand side,” that is, the input parameters. Likewise, plhs represents the “parameters, left-hand side,” or output parameters.

Managing Input and Output Parameters

Input parameters (found in the prhs array) are read-only; do not modify them in your MEX file. Changing data in an input parameter can produce undesired side effects.

You also must take care when using an input parameter to create output data or any data used locally in your MEX file. To copy an input array into a locally defined variable, myData, call the mxDuplicateArray function to make of copy of the input array. For example:

mxArray *myData = mxCreateStructMatrix(1,1,nfields,fnames);
mxSetField(myData,0,"myFieldName",mxDuplicateArray(prhs[0]));

For more information, see the troubleshooting topic Incorrectly Constructing a Cell or Structure mxArray.

Validating Inputs

For a list of functions to validate inputs to your functions, see the C Matrix API.

The mxIsClass function is a general-purpose way to test an mxArray. For example, suppose your second input argument (identified by prhs[1]) must be a full matrix of real numbers. To check this condition, use the following statements.

if(mxIsSparse(prhs[1]) || 
   mxIsComplex(prhs[1]) || 
   mxIsClass(prhs[1],"char")) {
      mexErrMsgIdAndTxt("MyToolbox:myfcn:nrhs",
          "input2 must be full matrix of real values.");
}

This example is not an exhaustive check. You can also test for structures, cell arrays, function handles, and MATLAB objects.

Computational Routine

The computational routine contains the code for performing the computations you want implemented in the binary MEX file. Although not required, consider writing the gateway routine, mexFunction, to call a computational routine. Use the mexFunction code as a wrapper to validate input parameters and to convert them into the types required by the computational routine.

If you write separate gateway and computational routines, you can combine them into one source file or into separate files. If you use separate files, the file containing mexFunction must be the first source file listed in the mex command.