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.

: ext = mexext () ¶

Return the filename extension used for MEX files.

Programming Note: Octave uses the extension mex for all MEX files regardless of the operating system (Linux, Windows, Apple) or the bit-width (32-bit or 64-bit) of the hardware.

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.