Sophie: octave-doc-0:3.2.3-3mdv2010.0 i586

octave-doc-3.2.3-3mdv2010.0.i586.rpm

<html lang="en">
<head>
<title>Getting Started with Mex-Files - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<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:&nbsp;<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:&nbsp;<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 the installation of other
products, the use of the command <code>mex</code> is limited to within Octave.

<!-- ./miscellaneous/mex.m -->
   <p><a name="doc_002dmex"></a>

<div class="defun">
&mdash; Function File:  <b>mex</b> [<var>options</var>]<var> file <small class="dots">...</small><a name="index-mex-2482"></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>

<!-- ./miscellaneous/mexext.m -->
   <p><a name="doc_002dmexext"></a>

<div class="defun">
&mdash; Function File:  <b>mexext</b> ()<var><a name="index-mexext-2483"></a></var><br>
<blockquote><p>Return the filename extension used for MEX files. 
</p></blockquote></div>

   <p>One important difference between the use of mex with other products and
with 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()
     &rArr; 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()
     &rArr; You called function: myfunc
         This is the principal function
     myfunc2()
     &rArr; 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>