<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>