Calling Conventions (MATLAB C Math Library)

MATLAB C Math Library

Calling Conventions

This section demonstrates the calling conventions that apply to the MATLAB C Math Library functions, including what data type to use for C input and output arguments, how to handle optional arguments, and how to handle MATLAB's multiple output values in C.

Refer to the "How to Call MATLAB Functions" section of Chapter 6 in the MATLAB C Math Library User's Guide for further discussion of the calling conventions and for a list of exceptions to the calling conventions.

How the C Prototype Is Constructed

One C prototype supports all the possible ways to call a particular MATLAB C Math Library function. You can reconstruct the C prototype by examining the MATLAB syntax for a function.

In the following procedure, the MATLAB function svd() and the corresponding library function mlfSvd() are used to illustrate the process.

MATLAB Syntax

s = svd(X)
[U,S,V] = svd(X)
[U,S,V] = svd(X,0)

The C prototype for mlfSvd() is constructed step-by-step. Until the last step, the prototype is incomplete.

Adding the Output Arguments

1.: Find the statement that includes the largest number of output arguments.

: Choose:

[U,S,V] = svd(X,0)

2.: Subtract out the first output argument, U, to be the return value from the function. The data type for the return value is mxArray *.

mxArray *mlfSvd(

3.: Add the remaining number of MATLAB output arguments, S and V, as the first, second, etc., arguments to the C function. The data type for a C output argument is mxArray **.

mxArray *mlfSvd(mxArray **S, mxArray **V,

Adding the Input Arguments

1.: Find the syntax that includes the largest number of input arguments.

: Choose:

[U,S,V] = svd(X,0)

2.: Add that number of input arguments, X and Zero, to the prototype, one after another following the output arguments. The data type for an input argument is mxArray *.

mxArray *mlfSvd(mxArray **S, mxArray **V, mxArray *X,
                mxArray *Zero);

The prototype is complete.

Note Contrast the data type for an output argument with the data type for an input argument. The type for an output argument is the address of a pointer to an mxArray. The type for an input argument is a pointer to an mxArray.

How to Translate a MATLAB Call into a C Call

This procedure demonstrates how to translate the MATLAB svd() calls into MATLAB C Math Library calls to mlfSvd(). The procedure applies to library functions in general.

In this procedure, mlfAssign(), rather than the assignment operator (=), assigns the return value from mlfSvd() to an array variable. This usage indicates that the automated memory management provided by the library is in effect.

Note that within a call to a MATLAB C Math Library function, an output argument is preceded by &; an input argument is not.

MATLAB Syntax

s = svd(X)
[U,S,V] = svd(X)
[U,S,V] = svd(X,0)

The MATLAB arguments to svd() fall into these categories:

U (or s) is a required output argument.

S and V are optional output arguments.

X is a required input argument.

0 is an optional input argument.

1.: Declare input, output, and return variables as mxArray * variables. Assign values to the input variables. Initialize output and return variables to NULL.

2.: Make the first output argument the return value from the function.

mlfAssign(&s, 
mlfAssign(&U,
mlfAssign(&U,

3.: Pass any additional required or optional output arguments as the first arguments to the function. Pass a NULL argument wherever an optional output argument does not apply to the particular call.

mlfAssign(&s, mlfSvd(NULL,NULL,
mlfAssign(&U, mlfSvd(&S,&V,
mlfAssign(&U, mlfSvd(&S,&V,

4.: Pass any required or optional input arguments that apply to the C function, following the output arguments. Pass a NULL argument wherever an optional input argument does not apply to the particular call.

mlfAssign(&s, mlfSvd(NULL,NULL,X,NULL));
mlfAssign(&U, mlfSvd(&S,&V,X,NULL));
mlfAssign(&U, mlfSvd(&S,&V,X,Zero));

Note NULL arguments always follow significant arguments; a NULL argument cannot appear between two output arguments or between two input arguments. Move the significant output or input argument before the NULL argument.

[ Previous | Help Desk | Next ]