<!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta name="generator" content="AsciiDoc 8.6.8"> <title>CallingFromCToSML</title> <link rel="stylesheet" href="./asciidoc.css" type="text/css"> <link rel="stylesheet" href="./pygments.css" type="text/css"> <script type="text/javascript" src="./asciidoc.js"></script> <script type="text/javascript"> /*<![CDATA[*/ asciidoc.install(); /*]]>*/ </script> <link rel="stylesheet" href="./mlton.css" type="text/css"/> </head> <body class="article"> <div id="banner"> <div id="banner-home"> <a href="./Home">MLton 20130715</a> </div> </div> <div id="header"> <h1>CallingFromCToSML</h1> </div> <div id="content"> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"><p>MLton’s <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> allows programs to <em>export</em> SML functions to be called from C. Suppose you would like export from SML a function of type <span class="monospaced">real * char -> int</span> as the C function <span class="monospaced">foo</span>. MLton extends the syntax of SML to allow expressions like the following:</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>_export "foo": (real * char -> int) -> unit;</pre> </div></div> <div class="paragraph"><p>The above expression exports a C function named <span class="monospaced">foo</span>, with prototype</p></div> <div class="listingblock"> <div class="content"><div class="highlight"><pre><span class="n">Int32</span> <span class="n">foo</span> <span class="p">(</span><span class="n">Real64</span> <span class="n">x0</span><span class="p">,</span> <span class="n">Char</span> <span class="n">x1</span><span class="p">);</span> </pre></div></div></div> <div class="paragraph"><p>The <span class="monospaced">_export</span> expression denotes a function of type <span class="monospaced">(real * char -> int) -> unit</span> that when called with a function <span class="monospaced">f</span>, arranges for the exported <span class="monospaced">foo</span> function to call <span class="monospaced">f</span> when <span class="monospaced">foo</span> is called. So, for example, the following exports and defines <span class="monospaced">foo</span>.</p></div> <div class="listingblock"> <div class="content"><div class="highlight"><pre><span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"foo"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">real</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">char</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">int</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">c</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="mi">13</span><span class="w"> </span><span class="n">+</span><span class="w"> </span><span class="n">Real</span><span class="p">.</span><span class="n">floor</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="n">+</span><span class="w"> </span><span class="n">Char</span><span class="p">.</span><span class="n">ord</span><span class="w"> </span><span class="n">c</span><span class="p">)</span><span class="w"></span> </pre></div></div></div> <div class="paragraph"><p>The general form of an <span class="monospaced">_export</span> expression is</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>_export "C function name" attr... : cFuncTy -> unit;</pre> </div></div> <div class="paragraph"><p>The type and the semicolon are not optional. As with <span class="monospaced">_import</span>, a sequence of attributes may follow the function name.</p></div> <div class="paragraph"><p>MLton’s <span class="monospaced">-export-header</span> option generates a C header file with prototypes for all of the functions exported from SML. Include this header file in your C files to type check calls to functions exported from SML. This header file includes <span class="monospaced">typedef</span>s for the <a href="ForeignFunctionInterfaceTypes"> types that can be passed between SML and C</a>.</p></div> </div> </div> <div class="sect1"> <h2 id="_example">Example</h2> <div class="sectionbody"> <div class="paragraph"><p>Suppose that <span class="monospaced">export.sml</span> is</p></div> <div class="listingblock"> <div class="content"><div class="highlight"><pre><span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">real</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">char</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">char</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="p">_)</span><span class="w"> </span><span class="p">=></span><span class="w"></span> <span class="w"> </span><span class="p">(</span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="n">concat</span><span class="w"> </span><span class="p">[</span><span class="s">"i = "</span><span class="p">,</span><span class="w"> </span><span class="n">Int</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="n">i</span><span class="p">,</span><span class="w"></span> <span class="w"> </span><span class="s">" r = "</span><span class="p">,</span><span class="w"> </span><span class="n">Real</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">])</span><span class="w"></span> <span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="p">#</span><span class="s">"g"</span><span class="p">))</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">()</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">()</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f2"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">Word8</span><span class="p">.</span><span class="n">word</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">word</span><span class="w"> </span><span class="n">array</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="n">w</span><span class="w"> </span><span class="p">=></span><span class="w"></span> <span class="w"> </span><span class="n">Array</span><span class="p">.</span><span class="n">tabulate</span><span class="w"> </span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="n">Word</span><span class="p">.</span><span class="n">fromLargeWord</span><span class="w"> </span><span class="p">(</span><span class="n">Word8</span><span class="p">.</span><span class="n">toLargeWord</span><span class="w"> </span><span class="n">w</span><span class="p">)))</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">g2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g2"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">word</span><span class="w"> </span><span class="n">array</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g2</span><span class="w"> </span><span class="p">()</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="n">concat</span><span class="w"> </span><span class="p">[</span><span class="s">"0wx"</span><span class="p">,</span><span class="w"> </span><span class="n">Word</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="p">(</span><span class="n">Array</span><span class="p">.</span><span class="n">sub</span><span class="w"> </span><span class="p">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">)),</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">])</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f3"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">"hello</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">g3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g3"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g3</span><span class="w"> </span><span class="p">()</span><span class="w"></span> <span class="cm">(* This example demonstrates mutual recursion between C and SML. *)</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f4"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g4"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="n">-</span><span class="w"> </span><span class="mi">1</span><span class="p">))</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="mi">13</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">(_,</span><span class="w"> </span><span class="n">zzzSet</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">symbol</span><span class="w"> </span><span class="s">"zzz"</span><span class="w"> </span><span class="n">alloc</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">int</span><span class="p">)</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">);</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zzzSet</span><span class="w"> </span><span class="mi">42</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="n">g5</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g5"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g5</span><span class="w"> </span><span class="p">()</span><span class="w"></span> <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">"success</span><span class="se">\n</span><span class="s">"</span><span class="w"></span> </pre></div></div></div> <div class="paragraph"><p>Create the header file with <span class="monospaced">-export-header</span>.</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>% mlton -default-ann 'allowFFI true' \ -export-header export.h \ -stop tc \ export.sml</pre> </div></div> <div class="paragraph"><p><span class="monospaced">export.h</span> now contains the following C prototypes.</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>Int8 f (Int32 x0, Real64 x1, Int8 x2); Pointer f2 (Word8 x0); void f3 (); void f4 (Int32 x0); extern Int32 zzz;</pre> </div></div> <div class="paragraph"><p>Use <span class="monospaced">export.h</span> in a C program, <span class="monospaced">ffi-export.c</span>, as follows.</p></div> <div class="listingblock"> <div class="content"><div class="highlight"><pre><span class="cp">#include <stdio.h></span> <span class="cp">#include "export.h"</span> <span class="cm">/* Functions in C are by default PUBLIC symbols */</span> <span class="kt">void</span> <span class="nf">g</span> <span class="p">()</span> <span class="p">{</span> <span class="n">Char8</span> <span class="n">c</span><span class="p">;</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="n">c</span> <span class="o">=</span> <span class="n">f</span> <span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="mf">17.15</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g done char = %c</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">c</span><span class="p">);</span> <span class="p">}</span> <span class="n">Pointer</span> <span class="nf">g2</span> <span class="p">()</span> <span class="p">{</span> <span class="n">Pointer</span> <span class="n">res</span><span class="p">;</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g2 starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="n">res</span> <span class="o">=</span> <span class="n">f2</span> <span class="p">(</span><span class="mh">0xFF</span><span class="p">);</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g2 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span> <span class="p">}</span> <span class="kt">void</span> <span class="nf">g3</span> <span class="p">()</span> <span class="p">{</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g3 starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="n">f3</span> <span class="p">();</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g3 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span> <span class="kt">void</span> <span class="nf">g4</span> <span class="p">(</span><span class="n">Int32</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g4 (%d)</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span> <span class="n">f4</span> <span class="p">(</span><span class="n">i</span><span class="p">);</span> <span class="p">}</span> <span class="kt">void</span> <span class="nf">g5</span> <span class="p">()</span> <span class="p">{</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g5 ()</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"zzz = %i</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">zzz</span><span class="p">);</span> <span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g5 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span> </pre></div></div></div> <div class="paragraph"><p>Compile <span class="monospaced">ffi-export.c</span> and <span class="monospaced">export.sml</span>.</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>% gcc -c ffi-export.c % mlton -default-ann 'allowFFI true' \ export.sml ffi-export.o</pre> </div></div> <div class="paragraph"><p>Finally, run <span class="monospaced">export</span>.</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>% ./export g starting ... g4 (0) success</pre> </div></div> </div> </div> <div class="sect1"> <h2 id="_download">Download</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> <a href="https://raw.github.com/MLton/mlton/master/doc/examples/ffi/export.sml"><span class="monospaced">export.sml</span></a> </p> </li> <li> <p> <a href="https://raw.github.com/MLton/mlton/master/doc/examples/ffi/ffi-export.c"><span class="monospaced">ffi-export.c</span></a> </p> </li> </ul></div> </div> </div> </div> <div id="footnotes"><hr></div> <div id="footer"> <div id="footer-text"> </div> <div id="footer-badges"> </div> </div> </body> </html>