Getting Started with Mex-Files (GNU Octave (version 6.4.0))

Next: Working with Matrices and Arrays in Mex-Files, Up: Mex-Files [Contents][Index]

#### 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 …
: `status` = mex (…)

  Compile source code written in C, C++, or Fortran, to a MEX file.

  status is the return status of the `mkoctfile` function.

  If the compilation fails, and the output argument is not requested, an error is raised. If the programmer requests status, however, Octave will merely issue a warning and it is the programmer’s responsibility to verify the command was successful.

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

  See also: mkoctfile, mexext.

: mexext ()

  Return the filename extension used for MEX files.

  See also: 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`.

Next: Working with Matrices and Arrays in Mex-Files, Up: Mex-Files [Contents][Index]