MATLAB Application Program Interface Reference Help Desk

mexFunction

Purpose

Entry point to a C MEX-file

C Syntax

Arguments

nlhs

MATLAB sets nlhs with the number of expected mxArrays.

plhs

MATLAB sets plhs to a pointer to an array of NULL pointers.

nrhs

MATLAB sets nrhs to the number of input mxArrays.

prhs

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.

Description

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

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.

Examples

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:

For an additional example, see mexFunction.c in the mex subdirectory of the examples directory.



[ Previous | Help Desk | Next ]