File: Getting-Started-with-Mex_002dFiles.html

package info (click to toggle)
octave 3.8.2-4
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 84,396 kB
ctags: 45,547
sloc: cpp: 293,356; ansic: 42,041; fortran: 23,669; sh: 13,629; objc: 7,890; yacc: 7,093; lex: 3,442; java: 2,125; makefile: 1,589; perl: 1,009; awk: 974; xml: 34
file content (211 lines) | stat: -rw-r--r-- 8,693 bytes
parent folder | download | duplicates (3)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Getting Started with Mex-Files</title>

<meta name="description" content="GNU Octave: Getting Started with Mex-Files">
<meta name="keywords" content="GNU Octave: Getting Started with Mex-Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Mex_002dFiles.html#Mex_002dFiles" rel="up" title="Mex-Files">
<link href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html#Working-with-Matrices-and-Arrays-in-Mex_002dFiles" rel="next" title="Working with Matrices and Arrays in Mex-Files">
<link href="Mex_002dFiles.html#Mex_002dFiles" rel="prev" title="Mex-Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Getting-Started-with-Mex_002dFiles"></a>
<div class="header">
<p>
Next: <a href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html#Working-with-Matrices-and-Arrays-in-Mex_002dFiles" accesskey="n" rel="next">Working with Matrices and Arrays in Mex-Files</a>, Up: <a href="Mex_002dFiles.html#Mex_002dFiles" accesskey="u" rel="up">Mex-Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Getting-Started-with-Mex_002dFiles-1"></a>
<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 command can be used either from within Octave or from
the command line.  However, to avoid issues with <small>MATLAB</small>&rsquo;s own <code>mex</code>
command, the use of the command <code>mex</code> is limited to within Octave.
Compiled mex-files have the extension <samp>.mex</samp>.
</p>
<a name="XREFmex"></a><dl>
<dt><a name="index-mex-1"></a>Command: <em></em> <strong>mex</strong> <em>[options] file &hellip;</em></dt>
<dd><p>Compile source code written in C, C++, or Fortran, to a MEX file.
This is equivalent to <code>mkoctfile --mex [options] file</code>.
</p>
<p><strong>See also:</strong> <a href="Getting-Started-with-Oct_002dFiles.html#XREFmkoctfile">mkoctfile</a>.
</p></dd></dl>


<a name="XREFmexext"></a><dl>
<dt><a name="index-mexext"></a>Function File: <em></em> <strong>mexext</strong> <em>()</em></dt>
<dd><p>Return the filename extension used for MEX files.
</p>
<p><strong>See also:</strong> <a href="#XREFmex">mex</a>.
</p></dd></dl>


<p>Consider the following short example:
</p>
<div class="example">
<pre class="verbatim">#include &quot;mex.h&quot;

void
mexFunction (int nlhs, mxArray *plhs[],
             int nrhs, const mxArray *prhs[])
{
  mexPrintf (&quot;Hello, World!\n&quot;);

  mexPrintf (&quot;I have %d inputs and %d outputs\n&quot;, nrhs, nlhs);
}
</pre><pre class="example">
</pre></div>

<p>The first line <code>#include &quot;mex.h&quot;</code> makes available all of the definitions
necessary for a mex-file.  One important difference between Octave and
<small>MATLAB</small> is that the header file <code>&quot;matrix.h&quot;</code> is implicitly included
through the inclusion of <code>&quot;mex.h&quot;</code>.  This is necessary to avoid a conflict
with the Octave file <code>&quot;Matrix.h&quot;</code> for operating systems and compilers that
don&rsquo;t distinguish between filenames in upper and lower case.
</p>
<p>The entry point into the mex-file is defined by <code>mexFunction</code>.  The
function takes four arguments:
</p>
<ol>
<li> The number of return arguments (# of left-hand side args).

</li><li> An array of pointers to return arguments.

</li><li> The number of input arguments (# of right-hand side args).

</li><li> An array of pointers to input arguments.
</li></ol>

<p>Note that the function name definition is not explicitly included in
<code>mexFunction</code> and so there can only be a single <code>mexFunction</code>
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.  Therefore,
if the above function is in the file <samp>myhello.c</samp>, it can be compiled with
</p>
<div class="example">
<pre class="example">mkoctfile --mex myhello.c
</pre></div>

<p>which creates a file <samp>myhello.mex</samp>.  The function can then be run from
Octave as
</p>
<div class="example">
<pre class="example">myhello (1,2,3)
&rArr; Hello, World!
&rArr; I have 3 inputs and 0 outputs
</pre></div>

<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>myhello.m</samp> that might
contain the text
</p>
<div class="example">
<pre class="example">%MYHELLO Simple test of the functionality of a mex-file.
</pre></div>

<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>
<p>Although there cannot be multiple entry points in a single mex-file,
one 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
</p>
<div class="example">
<pre class="verbatim">#include &quot;mex.h&quot;

void
mexFunction (int nlhs, mxArray *plhs[],
             int nrhs, const mxArray *prhs[])
{
  const char *nm;

  nm = mexFunctionName ();
  mexPrintf (&quot;You called function: %s\n&quot;, nm);
  if (strcmp (nm, &quot;myfunc&quot;) == 0)
    mexPrintf (&quot;This is the principal function\n&quot;, nm);

  return;
}
</pre><pre class="example">
</pre></div>

<p>is in file <samp>myfunc.c</samp>, and it is compiled with
</p>
<div class="example">
<pre class="example">mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex
</pre></div>

<p>then as can be seen by
</p>
<div class="example">
<pre class="example">myfunc ()
&rArr; You called function: myfunc
    This is the principal function
myfunc2 ()
&rArr; You called function: myfunc2
</pre></div>

<p>the behavior of the mex-file can be altered depending on the functions
name.
</p>
<p>Although the user should only include <samp>mex.h</samp> in their code, Octave
declares additional functions, typedefs, etc., available to the user to
write mex-files in the headers <samp>mexproto.h</samp> and <samp>mxarray.h</samp>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html#Working-with-Matrices-and-Arrays-in-Mex_002dFiles" accesskey="n" rel="next">Working with Matrices and Arrays in Mex-Files</a>, Up: <a href="Mex_002dFiles.html#Mex_002dFiles" accesskey="u" rel="up">Mex-Files</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>