<html lang="en">
<head>
<title>Getting Started with Mex-Files - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Mex_002dFiles.html#Mex_002dFiles" title="Mex-Files">
<link rel="next" href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html#Working-with-Matrices-and-Arrays-in-Mex_002dFiles" title="Working with Matrices and Arrays in Mex-Files">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Getting-Started-with-Mex-Files"></a>
<a name="Getting-Started-with-Mex_002dFiles"></a>
<p>
Next: <a rel="next" accesskey="n" href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html#Working-with-Matrices-and-Arrays-in-Mex_002dFiles">Working with Matrices and Arrays in Mex-Files</a>,
Up: <a rel="up" accesskey="u" href="Mex_002dFiles.html#Mex_002dFiles">Mex-Files</a>
<hr>
</div>
<h4 class="subsection">A.2.1 Getting Started with Mex-Files</h4>
<p>The basic command to build a mex-file is either <code>mkoctfile --mex</code>
or <code>mex</code>. The first can either be used from within Octave or from
the command line. However, to avoid issues with <span class="sc">matlab</span>'s own <code>mex</code>
command, the use of the command <code>mex</code> is limited to within Octave.
<!-- mex scripts/miscellaneous/mex.m -->
<p><a name="doc_002dmex"></a>
<div class="defun">
— Function File: <b>mex</b> [<var>options</var>]<var> file <small class="dots">...</small><a name="index-mex-3372"></a></var><br>
<blockquote><p>Compile source code written in C, C++, or Fortran, to a MEX file.
This is equivalent to <code>mkoctfile --mex [options] file</code>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dmkoctfile.html#doc_002dmkoctfile">mkoctfile</a>.
</p></blockquote></div>
<!-- mexext scripts/miscellaneous/mexext.m -->
<p><a name="doc_002dmexext"></a>
<div class="defun">
— Function File: <b>mexext</b> ()<var><a name="index-mexext-3373"></a></var><br>
<blockquote><p>Return the filename extension used for MEX files.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dmex.html#doc_002dmex">mex</a>.
</p></blockquote></div>
<p>One important difference with the use of <code>mex</code> between <span class="sc">matlab</span> and
Octave is that the header file "matrix.h" is implicitly included through
the inclusion of "mex.h". This is to avoid a conflict with the Octave
file "Matrix.h" with operating systems and compilers that don't
distinguish between filenames in upper and lower case
<p>Consider the short example:
<pre class="example"><pre class="verbatim"> #include "mex.h"
void
mexFunction (int nlhs, mxArray *plhs[], int nrhs,
const mxArray *prhs[])
{
mxArray *v = mxCreateDoubleMatrix (1, 1, mxREAL);
double *data = mxGetPr (v);
*data = 1.23456789;
plhs[0] = v;
}
</pre>
</pre>
<p>This simple example demonstrates the basics of writing a mex-file. The
entry point into the mex-file is defined by <code>mexFunction</code>. Note
that the function name is not explicitly included in the
<code>mexFunction</code> and so there can only be a single <code>mexFunction</code>
entry point per-file. Also the name of the function is determined by the
name of the mex-file itself. Therefore if the above function is in the
file <samp><span class="file">firstmexdemo.c</span></samp>, it can be compiled with
<pre class="example"> mkoctfile --mex firstmexdemo.c
</pre>
<p class="noindent">which creates a file <samp><span class="file">firstmexdemo.mex</span></samp>. The function can then be run
from Octave as
<pre class="example"> firstmexdemo()
⇒ 1.2346
</pre>
<p>It should be noted that the mex-file contains no help string for the
functions it contains. 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, we would therefore have a file <samp><span class="file">firstmexdemo.m</span></samp> that might
contain the text
<pre class="example"> %FIRSTMEXDEMO Simple test of the functionality of a mex-file.
</pre>
<p>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.
<p>Although we cannot have multiple entry points into a single mex-file,
we can use the <code>mexFunctionName</code> 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
<pre class="example"><pre class="verbatim"> #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;
}
</pre>
</pre>
<p class="noindent">is in file <samp><span class="file">myfunc.c</span></samp>, and it is compiled with
<pre class="example"> mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex
</pre>
<p>Then as can be seen by
<pre class="example"> myfunc()
⇒ You called function: myfunc
This is the principal function
myfunc2()
⇒ You called function: myfunc2
</pre>
<p class="noindent">the behavior of the mex-file can be altered depending on the functions
name.
<p>Allow the user should only include <code>mex.h</code> in their code, Octave
declares additional functions, typedefs, etc., available to the user to
write mex-files in the headers <code>mexproto.h</code> and <code>mxarray.h</code>.
</body></html>
