(octave.info)Getting Started with Mex-Files

---

Next: Working with Matrices and Arrays in Mex-Files Up: Mex-Files

---

Enter node , (file) or (file)node

A.2.1 Getting Started with Mex-Files
------------------------------------

The basic command to build a mex-file is either ‘mkoctfile --mex’ or
‘mex’.  The first command can be used either from within Octave or from
the command line.  To avoid issues with MATLAB’s own ‘mex’ command, the
use of the command ‘mex’ is limited to within Octave.  Compiled
mex-files have the extension ‘.mex’.

 -- : mex [options] file ...
     Compile source code written in C, C++, or Fortran, to a MEX file.

     This is equivalent to ‘mkoctfile --mex [options] file’.

     See also: Note: mkoctfile, Note: mexext.

 -- : mexext ()
     Return the filename extension used for MEX files.

     See also: Note: mex.

   Consider the following short example:

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       mexPrintf ("Hello, World!\n");
     
       mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);
     
       /* Return empty matrices for any outputs */
       int i;
       for (i = 0; i < nlhs; i++)
         plhs[i] = mxCreateDoubleMatrix (0, 0, mxREAL);
     }

   The first line ‘#include "mex.h"’ makes available all of the
definitions necessary for a mex-file.  One important difference between
Octave and MATLAB is that the header file "matrix.h" is implicitly
included through the inclusion of "mex.h".  This is necessary to avoid a
conflict with the Octave file "Matrix.h" for operating systems and
compilers that don’t distinguish between filenames in upper and lower
case.

   The entry point into the mex-file is defined by ‘mexFunction’.  The
function takes four arguments:

  1. The number of return arguments (# of left-hand side args).

  2. An array of pointers to return arguments.

  3. The number of input arguments (# of right-hand side args).

  4. An array of pointers to input arguments.

   Note that the function name definition is not explicitly included in
‘mexFunction’ and so there can only be a single ‘mexFunction’ entry
point per file.  Instead, the name of the function as seen in Octave is
determined by the name of the mex-file itself minus the extension.  If
the above function is in the file ‘myhello.c’, it can be compiled with

     mkoctfile --mex myhello.c

which creates a file ‘myhello.mex’.  The function can then be run from
Octave as

     myhello (1,2,3)
     ⇒ Hello, World!
     ⇒ I have 3 inputs and 0 outputs

   It should be noted that the mex-file contains no help string.  To
document mex-files, there should exist an m-file in the same directory
as the mex-file itself.  Taking the above as an example, there would
need to be a file ‘myhello.m’ which might contain the text

     %MYHELLO Simple test of the functionality of a mex-file.

   In this case, the function that will be executed within Octave will
be given by the mex-file, while the help string will come from the
m-file.  This can also be useful to allow a sample implementation of the
mex-file within the Octave language itself for testing purposes.

   Although there cannot be multiple entry points in a single mex-file,
one can use the ‘mexFunctionName’ function to determine what name the
mex-file was called with.  This can be used to alter the behavior of the
mex-file based on the function name.  For example, if

     #include "mex.h"
     
     void
     mexFunction (int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[])
     {
       const char *nm;
     
       nm = mexFunctionName ();
       mexPrintf ("You called function: %s\n", nm);
       if (strcmp (nm, "myfunc") == 0)
         mexPrintf ("This is the principal function\n", nm);
     
       return;
     }

is in the file ‘myfunc.c’, and is compiled with

     mkoctfile --mex myfunc.c
     ln -s myfunc.mex myfunc2.mex

then as can be seen by

     myfunc ()
     ⇒ You called function: myfunc
         This is the principal function
     myfunc2 ()
     ⇒ You called function: myfunc2

the behavior of the mex-file can be altered depending on the function’s
name.

   Although the user should only include ‘mex.h’ in their code, Octave
declares additional functions, typedefs, etc., available to the user to
write mex-files in the headers ‘mexproto.h’ and ‘mxarray.h’.