koffi 1.3.9 → 1.3.12

package/doc/dist/html/functions.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 <link rel="index" title="Index" href="genindex" /><link rel="search" title="Search" href="search" /><link rel="next" title="Memory usage" href="memory" /><link rel="prev" title="Data types" href="types" />
 
-    <meta name="generator" content="sphinx-5.0.2, furo 2022.06.21"/>
+    <meta name="generator" content="sphinx-5.0.1, furo 2022.06.04.1"/>
         <title>Function calls - Koffi</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=40978830699223671f4072448e654b5958f38b89" />
@@ -208,8 +208,8 @@
 <section id="function-definitions">
 <h2>Function definitions<a class="headerlink" href="#function-definitions" title="Permalink to this heading">#</a></h2>
 <p>To declare functions, start by loading the shared library with <code class="docutils literal notranslate"><span class="pre">koffi.load(filename)</span></code>.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;/path/to/shared/library&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// File extension depends on platforms: .so, .dll, .dylib, etc.</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;/path/to/shared/library&#39;</span><span class="p">);</span> <span class="c1">// File extension depends on platforms: .so, .dll, .dylib, etc.</span>
 </pre></div>
 </div>
 <p>You can use the returned object to load C functions from the library. To do so, you can use two syntaxes:</p>
@@ -220,24 +220,26 @@
 <section id="classic-syntax">
 <h3>Classic syntax<a class="headerlink" href="#classic-syntax" title="Permalink to this heading">#</a></h3>
 <p>To declare a function, you need to specify its non-mangled name, its return type, and its parameters. Use an ellipsis as the last parameter for variadic functions.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;printf&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;...&#39;</span><span class="p">]);</span><span class="w"></span>
-<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;atoi&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">]);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">printf</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;printf&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;...&#39;</span><span class="p">]);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">atoi</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;atoi&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">]);</span>
 </pre></div>
 </div>
-<p>Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section <a class="reference internal" href="#synchronous-calls"><span class="std std-doc">on standard calls</span></a> for more information on this subject.</p>
+<p>Koffi automatically tries mangled names for non-standard x86 calling conventions. See the section on <a class="reference internal" href="#calling-conventions"><span class="std std-doc">calling conventions</span></a> for more information on this subject.</p>
 </section>
 <section id="c-like-prototypes">
 <h3>C-like prototypes<a class="headerlink" href="#c-like-prototypes" title="Permalink to this heading">#</a></h3>
 <p>If you prefer, you can declare functions using simple C-like prototype strings, as shown below:</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int printf(const char *fmt, ...)&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int atoi(str)&#39;</span><span class="p">);</span><span class="w"> </span><span class="c1">// The parameter name is not used by Koffi, and optional</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">printf</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int printf(const char *fmt, ...)&#39;</span><span class="p">);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">atoi</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int atoi(str)&#39;</span><span class="p">);</span> <span class="c1">// The parameter name is not used by Koffi, and optional</span>
 </pre></div>
 </div>
 <p>You can use <code class="docutils literal notranslate"><span class="pre">()</span></code> or <code class="docutils literal notranslate"><span class="pre">(void)</span></code> for functions that take no argument.</p>
 </section>
 </section>
-<section id="synchronous-calls">
-<h2>Synchronous calls<a class="headerlink" href="#synchronous-calls" title="Permalink to this heading">#</a></h2>
+<section id="id1">
+<h2>Function calls<a class="headerlink" href="#id1" title="Permalink to this heading">#</a></h2>
+<section id="calling-conventions">
+<h3>Calling conventions<a class="headerlink" href="#calling-conventions" title="Permalink to this heading">#</a></h3>
 <p>By default, calling a C function happens synchronously.</p>
 <p>Most architectures only support one procedure call standard per process. The 32-bit x86 platform is an exception to this, and Koffi supports several x86 conventions:</p>
 <div class="table-wrapper colwidths-auto docutils container">
@@ -275,31 +277,31 @@
 </div>
 <p>You can safely use these on non-x86 platforms, they are simply ignored.</p>
 <p>Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;user32.dll&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;user32.dll&#39;</span><span class="p">);</span>
 <span class="linenos">3</span>
-<span class="linenos">4</span><span class="c1">// The following two declarations are equivalent, and use Stdcall</span><span class="w"></span>
-<span class="linenos">5</span><span class="kd">const</span><span class="w"> </span><span class="nx">MessageBoxA_1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">stdcall</span><span class="p">(</span><span class="s1">&#39;MessageBoxA&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;void *&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;uint&#39;</span><span class="p">]);</span><span class="w"></span>
-<span class="linenos">6</span><span class="kd">const</span><span class="w"> </span><span class="nx">MessageBoxA_2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">4</span><span class="c1">// The following two declarations are equivalent, and use stdcall on x86 (and the default ABI on other platforms)</span>
+<span class="linenos">5</span><span class="kd">const</span> <span class="nx">MessageBoxA_1</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">stdcall</span><span class="p">(</span><span class="s1">&#39;MessageBoxA&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;void *&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;uint&#39;</span><span class="p">]);</span>
+<span class="linenos">6</span><span class="kd">const</span> <span class="nx">MessageBoxA_2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)&#39;</span><span class="p">);</span>
 </pre></div>
 </div>
 </section>
 <section id="asynchronous-calls">
-<h2>Asynchronous calls<a class="headerlink" href="#asynchronous-calls" title="Permalink to this heading">#</a></h2>
+<h3>Asynchronous calls<a class="headerlink" href="#asynchronous-calls" title="Permalink to this heading">#</a></h3>
 <p>You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with <code class="docutils literal notranslate"><span class="pre">(err,</span> <span class="pre">res)</span></code> parameters.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span>
 <span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">atoi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int atoi(const char *str)&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">atoi</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int atoi(const char *str)&#39;</span><span class="p">);</span>
 <span class="linenos"> 5</span>
-<span class="linenos"> 6</span><span class="nx">atoi</span><span class="p">.</span><span class="k">async</span><span class="p">(</span><span class="s1">&#39;1257&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="nx">err</span><span class="p">,</span><span class="w"> </span><span class="nx">res</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
-<span class="linenos"> 7</span><span class="w">    </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Result:&#39;</span><span class="p">,</span><span class="w"> </span><span class="nx">res</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 8</span><span class="p">})</span><span class="w"></span>
-<span class="linenos"> 9</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Hello World!&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos"> 6</span><span class="nx">atoi</span><span class="p">.</span><span class="k">async</span><span class="p">(</span><span class="s1">&#39;1257&#39;</span><span class="p">,</span> <span class="p">(</span><span class="nx">err</span><span class="p">,</span> <span class="nx">res</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
+<span class="linenos"> 7</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Result:&#39;</span><span class="p">,</span> <span class="nx">res</span><span class="p">);</span>
+<span class="linenos"> 8</span><span class="p">})</span>
+<span class="linenos"> 9</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Hello World!&#39;</span><span class="p">);</span>
 <span class="linenos">10</span>
-<span class="linenos">11</span><span class="c1">// This program will print:</span><span class="w"></span>
-<span class="linenos">12</span><span class="c1">//   Hello World!</span><span class="w"></span>
-<span class="linenos">13</span><span class="c1">//   Result: 1257</span><span class="w"></span>
+<span class="linenos">11</span><span class="c1">// This program will print:</span>
+<span class="linenos">12</span><span class="c1">//   Hello World!</span>
+<span class="linenos">13</span><span class="c1">//   Result: 1257</span>
 </pre></div>
 </div>
 <p>These calls are executed by worker threads. It is <strong>your responsibility to deal with data sharing issues</strong> in the native code that may be caused by multi-threading.</p>
@@ -307,19 +309,22 @@
 <p>Variadic functions cannot be called asynchronously.</p>
 </section>
 <section id="variadic-functions">
-<h2>Variadic functions<a class="headerlink" href="#variadic-functions" title="Permalink to this heading">#</a></h2>
+<h3>Variadic functions<a class="headerlink" href="#variadic-functions" title="Permalink to this heading">#</a></h3>
 <p>Variadic functions are declared with an ellipsis as the last argument.</p>
 <p>In order to call a variadic function, you must provide two Javascript arguments for each additional C parameter, the first one is the expected type and the second one is the value.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;printf&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;...&#39;</span><span class="p">]);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">printf</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;printf&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;...&#39;</span><span class="p">]);</span>
 <span class="linenos">2</span>
-<span class="linenos">3</span><span class="c1">// The variadic arguments are: 6 (int), 8.5 (double), &#39;THE END&#39; (const char *)</span><span class="w"></span>
-<span class="linenos">4</span><span class="nx">printf</span><span class="p">(</span><span class="s1">&#39;Integer %d, double %g, str %s&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="mf">6</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;double&#39;</span><span class="p">,</span><span class="w"> </span><span class="mf">8.5</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;THE END&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">3</span><span class="c1">// The variadic arguments are: 6 (int), 8.5 (double), &#39;THE END&#39; (const char *)</span>
+<span class="linenos">4</span><span class="nx">printf</span><span class="p">(</span><span class="s1">&#39;Integer %d, double %g, str %s&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="mf">6</span><span class="p">,</span> <span class="s1">&#39;double&#39;</span><span class="p">,</span> <span class="mf">8.5</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;THE END&#39;</span><span class="p">);</span>
 </pre></div>
 </div>
 <p>On x86 platforms, only the Cdecl convention can be used for variadic functions.</p>
 </section>
+</section>
+<section id="c-to-js-conversion-gotchas">
+<h2>C to JS conversion gotchas<a class="headerlink" href="#c-to-js-conversion-gotchas" title="Permalink to this heading">#</a></h2>
 <section id="output-parameters">
-<h2>Output parameters<a class="headerlink" href="#output-parameters" title="Permalink to this heading">#</a></h2>
+<h3>Output parameters<a class="headerlink" href="#output-parameters" title="Permalink to this heading">#</a></h3>
 <p>By default, Koffi will only forward arguments from Javascript to C. However, many C functions use pointer arguments for output values, or input/output values.</p>
 <p>For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:</p>
 <ul class="simple">
@@ -337,67 +342,123 @@
 <li><p><code class="docutils literal notranslate"><span class="pre">_Inout_</span></code> for dual input/output parameters</p></li>
 </ul>
 <section id="struct-example">
-<h3>Struct example<a class="headerlink" href="#struct-example" title="Permalink to this heading">#</a></h3>
+<h4>Struct example<a class="headerlink" href="#struct-example" title="Permalink to this heading">#</a></h4>
 <p>This example calls the POSIX function <code class="docutils literal notranslate"><span class="pre">gettimeofday()</span></code>, and uses the prototype-like syntax.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span>
 <span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">timeval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">&#39;timeval&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
-<span class="linenos"> 5</span><span class="w">    </span><span class="nx">tv_sec</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;unsigned int&#39;</span><span class="p">,</span><span class="w"></span>
-<span class="linenos"> 6</span><span class="w">    </span><span class="nx">tv_usec</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;unsigned int&#39;</span><span class="w"></span>
-<span class="linenos"> 7</span><span class="p">});</span><span class="w"></span>
-<span class="linenos"> 8</span><span class="kd">const</span><span class="w"> </span><span class="nx">timezone</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">&#39;timezone&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
-<span class="linenos"> 9</span><span class="w">    </span><span class="nx">tz_minuteswest</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"></span>
-<span class="linenos">10</span><span class="w">    </span><span class="nx">tz_dsttime</span><span class="o">:</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="w"></span>
-<span class="linenos">11</span><span class="p">});</span><span class="w"></span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">timeval</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">&#39;timeval&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 5</span>    <span class="nx">tv_sec</span><span class="o">:</span> <span class="s1">&#39;unsigned int&#39;</span><span class="p">,</span>
+<span class="linenos"> 6</span>    <span class="nx">tv_usec</span><span class="o">:</span> <span class="s1">&#39;unsigned int&#39;</span>
+<span class="linenos"> 7</span><span class="p">});</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">timezone</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">struct</span><span class="p">(</span><span class="s1">&#39;timezone&#39;</span><span class="p">,</span> <span class="p">{</span>
+<span class="linenos"> 9</span>    <span class="nx">tz_minuteswest</span><span class="o">:</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span>
+<span class="linenos">10</span>    <span class="nx">tz_dsttime</span><span class="o">:</span> <span class="s1">&#39;int&#39;</span>
+<span class="linenos">11</span><span class="p">});</span>
 <span class="linenos">12</span>
-<span class="linenos">13</span><span class="c1">// The _Out_ qualifiers instruct Koffi to marshal out the values</span><span class="w"></span>
-<span class="linenos">14</span><span class="kd">const</span><span class="w"> </span><span class="nx">gettimeofday</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">13</span><span class="c1">// The _Out_ qualifiers instruct Koffi to marshal out the values</span>
+<span class="linenos">14</span><span class="kd">const</span> <span class="nx">gettimeofday</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)&#39;</span><span class="p">);</span>
 <span class="linenos">15</span>
-<span class="linenos">16</span><span class="kd">let</span><span class="w"> </span><span class="nx">tv</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{};</span><span class="w"></span>
-<span class="linenos">17</span><span class="nx">gettimeofday</span><span class="p">(</span><span class="nx">tv</span><span class="p">,</span><span class="w"> </span><span class="kc">null</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">16</span><span class="kd">let</span> <span class="nx">tv</span> <span class="o">=</span> <span class="p">{};</span>
+<span class="linenos">17</span><span class="nx">gettimeofday</span><span class="p">(</span><span class="nx">tv</span><span class="p">,</span> <span class="kc">null</span><span class="p">);</span>
 <span class="linenos">18</span>
-<span class="linenos">19</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">tv</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">19</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">tv</span><span class="p">);</span>
 </pre></div>
 </div>
 </section>
 <section id="opaque-handle-example">
-<h3>Opaque handle example<a class="headerlink" href="#opaque-handle-example" title="Permalink to this heading">#</a></h3>
+<h4>Opaque handle example<a class="headerlink" href="#opaque-handle-example" title="Permalink to this heading">#</a></h4>
 <p>This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 2</span><span class="kd">const</span><span class="w"> </span><span class="nx">lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;sqlite.so&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;sqlite.so&#39;</span><span class="p">);</span>
 <span class="linenos"> 3</span>
-<span class="linenos"> 4</span><span class="kd">const</span><span class="w"> </span><span class="nx">sqlite3_db</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;sqlite3_db&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">sqlite3_db</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">handle</span><span class="p">(</span><span class="s1">&#39;sqlite3_db&#39;</span><span class="p">);</span>
 <span class="linenos"> 5</span>
-<span class="linenos"> 6</span><span class="c1">// Use koffi.out() on a pointer to copy out (from C to JS) after the call</span><span class="w"></span>
-<span class="linenos"> 7</span><span class="kd">const</span><span class="w"> </span><span class="nx">sqlite3_open_v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;sqlite3_open_v2&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">out</span><span class="p">(</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">sqlite3_db</span><span class="p">)),</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;str&#39;</span><span class="p">]);</span><span class="w"></span>
-<span class="linenos"> 8</span><span class="kd">const</span><span class="w"> </span><span class="nx">sqlite3_close_v2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;sqlite3_close_v2&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;int&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="nx">sqlite3_db</span><span class="p">]);</span><span class="w"></span>
+<span class="linenos"> 6</span><span class="c1">// Use koffi.out() on a double pointer to copy out (from C to JS) after the call</span>
+<span class="linenos"> 7</span><span class="kd">const</span> <span class="nx">sqlite3_open_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;sqlite3_open_v2&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">out</span><span class="p">(</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">sqlite3_db</span><span class="p">,</span> <span class="mf">2</span><span class="p">)),</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">]);</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">sqlite3_close_v2</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;sqlite3_close_v2&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">sqlite3_db</span><span class="p">)]);</span>
 <span class="linenos"> 9</span>
-<span class="linenos">10</span><span class="kd">const</span><span class="w"> </span><span class="nx">SQLITE_OPEN_READWRITE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mh">0x2</span><span class="p">;</span><span class="w"></span>
-<span class="linenos">11</span><span class="kd">const</span><span class="w"> </span><span class="nx">SQLITE_OPEN_CREATE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mh">0x4</span><span class="p">;</span><span class="w"></span>
+<span class="linenos">10</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">=</span> <span class="mh">0x2</span><span class="p">;</span>
+<span class="linenos">11</span><span class="kd">const</span> <span class="nx">SQLITE_OPEN_CREATE</span> <span class="o">=</span> <span class="mh">0x4</span><span class="p">;</span>
 <span class="linenos">12</span>
-<span class="linenos">13</span><span class="kd">let</span><span class="w"> </span><span class="nx">db</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{};</span><span class="w"></span>
-<span class="linenos">14</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nx">sqlite3_open_v2</span><span class="p">(</span><span class="s1">&#39;:memory:&#39;</span><span class="p">,</span><span class="w"> </span><span class="nx">db</span><span class="p">,</span><span class="w"> </span><span class="nx">SQLITE_OPEN_READWRITE</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="nx">SQLITE_OPEN_CREATE</span><span class="p">,</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="mf">0</span><span class="p">)</span><span class="w"></span>
-<span class="linenos">15</span><span class="w">    </span><span class="k">throw</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open database&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">16</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">13</span><span class="kd">let</span> <span class="nx">db</span> <span class="o">=</span> <span class="p">{};</span>
+<span class="linenos">14</span><span class="k">if</span> <span class="p">(</span><span class="nx">sqlite3_open_v2</span><span class="p">(</span><span class="s1">&#39;:memory:&#39;</span><span class="p">,</span> <span class="nx">db</span><span class="p">,</span> <span class="nx">SQLITE_OPEN_READWRITE</span> <span class="o">|</span> <span class="nx">SQLITE_OPEN_CREATE</span><span class="p">,</span> <span class="kc">null</span><span class="p">)</span> <span class="o">!=</span> <span class="mf">0</span><span class="p">)</span>
+<span class="linenos">15</span>    <span class="k">throw</span> <span class="ow">new</span> <span class="ne">Error</span><span class="p">(</span><span class="s1">&#39;Failed to open database&#39;</span><span class="p">);</span>
+<span class="linenos">16</span><span class="nx">sqlite3_close_v2</span><span class="p">(</span><span class="nx">db</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
+</section>
+<section id="heap-allocated-values">
+<h3>Heap-allocated values<a class="headerlink" href="#heap-allocated-values" title="Permalink to this heading">#</a></h3>
+<p>Some C functions return heap-allocated values directly or through output parameters. While Koffi automatically converts values from C to JS (to a string or an object), it does not know when something needs to be freed, or how.</p>
+<p>For opaque handles, such as FILE, this does not matter because you will explicitly call <code class="docutils literal notranslate"><span class="pre">fclose()</span></code> on them. But some values (such as strings) get implicitly converted by Koffi, and you lose access to the original pointer. This creates a leak if the string is heap-allocated.</p>
+<p>To avoid this, you can instruct Koffi to call a function on the original pointer once the conversion is done, by creating a disposable type with <code class="docutils literal notranslate"><span class="pre">koffi.dispose(name,</span> <span class="pre">type,</span> <span class="pre">func)</span></code>. This creates a type derived from another type, the only difference being that <em>func</em> gets called with the original pointer once the value has been converted and is not needed anymore.</p>
+<p>The <em>name</em> can be omitted to create an anonymous disposable type. If <em>func</em> is omitted or is null, Koffi will use <code class="docutils literal notranslate"><span class="pre">koffi.free(ptr)</span></code> (which calls the standard C library <em>free</em> function under the hood).</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">AnonHeapStr</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">disposable</span><span class="p">(</span><span class="s1">&#39;str&#39;</span><span class="p">);</span> <span class="c1">// Anonymous type (cannot be used in function prototypes)</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">NamedHeapStr</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">disposable</span><span class="p">(</span><span class="s1">&#39;HeapStr&#39;</span><span class="p">,</span> <span class="s1">&#39;str&#39;</span><span class="p">);</span> <span class="c1">// Same thing, but named so usable in function prototypes</span>
+<span class="linenos">3</span><span class="kd">const</span> <span class="nx">ExplicitFree</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">disposable</span><span class="p">(</span><span class="s1">&#39;HeapStr16&#39;</span><span class="p">,</span> <span class="s1">&#39;str16&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">free</span><span class="p">);</span> <span class="c1">// You can specify any other JS function</span>
+</pre></div>
+</div>
+<p>The following example illustrates the use of a disposable type derived from <em>str</em>.</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span>
+<span class="linenos">3</span>
+<span class="linenos">4</span><span class="c1">// You can also use: const strdup = lib.func(&#39;const char *! asprintf(const char *str)&#39;)</span>
+<span class="linenos">5</span><span class="kd">const</span> <span class="nx">HeapStr</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">disposable</span><span class="p">(</span><span class="s1">&#39;str&#39;</span><span class="p">);</span>
+<span class="linenos">6</span><span class="kd">const</span> <span class="nx">strdup</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">cdecl</span><span class="p">(</span><span class="s1">&#39;strdup&#39;</span><span class="p">,</span> <span class="nx">HeapStr</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">]);</span>
+<span class="linenos">7</span>
+<span class="linenos">8</span><span class="kd">let</span> <span class="nx">copy</span> <span class="o">=</span> <span class="nx">strdup</span><span class="p">(</span><span class="s1">&#39;Hello!&#39;</span><span class="p">);</span>
+<span class="linenos">9</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">copy</span><span class="p">);</span> <span class="c1">// Prints Hello!</span>
+</pre></div>
+</div>
+<p>When you declare functions with the <a class="reference internal" href="#c-like-prototypes"><span class="std std-doc">prototype-like syntax</span></a>, you can either use named disposables types or use the ‘!’ shortcut qualifier with compatibles types, as shown in the example below. This qualifier creates an anonymous disposable type that calls <code class="docutils literal notranslate"><span class="pre">koffi.free(ptr)</span></code>.</p>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos">2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;libc.so.6&#39;</span><span class="p">);</span>
+<span class="linenos">3</span>
+<span class="linenos">4</span><span class="c1">// You can also use: const strdup = lib.func(&#39;const char *! strdup(const char *str)&#39;)</span>
+<span class="linenos">5</span><span class="kd">const</span> <span class="nx">strdup</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;str! strdup(const char *str)&#39;</span><span class="p">);</span>
+<span class="linenos">6</span>
+<span class="linenos">7</span><span class="kd">let</span> <span class="nx">copy</span> <span class="o">=</span> <span class="nx">strdup</span><span class="p">(</span><span class="s1">&#39;World!&#39;</span><span class="p">);</span>
+<span class="linenos">8</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">copy</span><span class="p">);</span> <span class="c1">// Prints World!</span>
 </pre></div>
 </div>
+<p>Disposable types can only be created from pointer or string types.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Be careful on Windows: if your shared library uses a different CRT (such as msvcrt), the memory could have been allocated by a different malloc/free implementation or heap, resulting in undefined behavior if you use <code class="docutils literal notranslate"><span class="pre">koffi.free()</span></code>.</p>
+</div>
 </section>
 </section>
 <section id="javascript-callbacks">
 <h2>Javascript callbacks<a class="headerlink" href="#javascript-callbacks" title="Permalink to this heading">#</a></h2>
 <p>In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.</p>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
 <span class="linenos">2</span>
-<span class="linenos">3</span><span class="c1">// With the classic syntax, this callback expects an integer and returns nothing</span><span class="w"></span>
-<span class="linenos">4</span><span class="kd">const</span><span class="w"> </span><span class="nx">ExampleCallback</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;ExampleCallback&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;void&#39;</span><span class="p">,</span><span class="w"> </span><span class="p">[</span><span class="s1">&#39;int&#39;</span><span class="p">]);</span><span class="w"></span>
+<span class="linenos">3</span><span class="c1">// With the classic syntax, this callback expects an integer and returns nothing</span>
+<span class="linenos">4</span><span class="kd">const</span> <span class="nx">ExampleCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;ExampleCallback&#39;</span><span class="p">,</span> <span class="s1">&#39;void&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;int&#39;</span><span class="p">]);</span>
 <span class="linenos">5</span>
-<span class="linenos">6</span><span class="c1">// With the prototype parser, this callback expects a double and float, and returns the sum as a double</span><span class="w"></span>
-<span class="linenos">7</span><span class="kd">const</span><span class="w"> </span><span class="nx">AddDoubleFloat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;double AddDoubleFloat(double d, float f)&#39;</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">6</span><span class="c1">// With the prototype parser, this callback expects a double and float, and returns the sum as a double</span>
+<span class="linenos">7</span><span class="kd">const</span> <span class="nx">AddDoubleFloat</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;double AddDoubleFloat(double d, float f)&#39;</span><span class="p">);</span>
 </pre></div>
 </div>
-<p>Once your callback type is declared, you can use it in struct definitions, or as function parameter and/or return type.</p>
-<p>Here is a small example with the C part and the JS part.</p>
+<p>Once your callback type is declared, you can use a pointer to it in struct definitions, or as function parameters and/or return types.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Callbacks <strong>have changed in version 2.0</strong>.</p>
+<p>In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.</p>
+<p>Now, you must use them through a pointer: <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">CallIt(CallbackType</span> <span class="pre">func)</span></code> in Koffi 1.x becomes <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">CallIt(CallbackType</span> <span class="pre">*func)</span></code> in version 2.0 and newer.</p>
+</div>
+<p>Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.</p>
+<p>Thus, Koffi distinguishes two callback modes:</p>
+<ul class="simple">
+<li><p><a class="reference internal" href="#transient-callbacks"><span class="std std-doc">Transient callbacks</span></a> can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don’t require any special handling.</p></li>
+<li><p><a class="reference internal" href="#registered-callbacks"><span class="std std-doc">Registered callbacks</span></a> can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.</p></li>
+</ul>
+<p>You need to specify the correct <a class="reference internal" href="#calling-conventions"><span class="std std-doc">calling convention</span></a> on x86 platforms, or the behavior is undefined (Node will probably crash). Only <em>cdecl</em> and <em>stdcall</em> callbacks are supported.</p>
+<section id="transient-callbacks">
+<h3>Transient callbacks<a class="headerlink" href="#transient-callbacks" title="Permalink to this heading">#</a></h3>
+<p>Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, <code class="docutils literal notranslate"><span class="pre">sqlite3_exec</span></code>). Here is a small example with the C part and the JS part.</p>
 <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;string.h&gt;</span><span class="cp"></span>
 <span class="linenos">2</span>
 <span class="linenos">3</span><span class="kt">int</span><span class="w"> </span><span class="nf">TransferToJS</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">age</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">cb</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">str</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">age</span><span class="p">))</span><span class="w"></span>
@@ -408,26 +469,73 @@
 <span class="linenos">8</span><span class="p">}</span><span class="w"></span>
 </pre></div>
 </div>
-<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span><span class="w"> </span><span class="nx">koffi</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 2</span>
-<span class="linenos"> 3</span><span class="kd">const</span><span class="w"> </span><span class="nx">TransferCallback</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;int TransferCallback(const char *str, int age)&#39;</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 4</span>
-<span class="linenos"> 5</span><span class="kd">const</span><span class="w"> </span><span class="nx">TransferToJS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;int TransferToJS(const char *str, int age, TransferCallback cb)&#39;</span><span class="p">);</span><span class="w"></span>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;./callbacks.so&#39;</span><span class="p">);</span> <span class="c1">// Fake path</span>
+<span class="linenos"> 3</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">TransferCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;int TransferCallback(const char *str, int age)&#39;</span><span class="p">);</span>
+<span class="linenos"> 5</span>
+<span class="linenos"> 6</span><span class="kd">const</span> <span class="nx">TransferToJS</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;TransferToJS&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;str&#39;</span><span class="p">,</span> <span class="s1">&#39;int&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">TransferCallback</span><span class="p">)]);</span>
+<span class="linenos"> 7</span>
+<span class="linenos"> 8</span><span class="kd">let</span> <span class="nx">ret</span> <span class="o">=</span> <span class="nx">TransferToJS</span><span class="p">(</span><span class="s1">&#39;Niels&#39;</span><span class="p">,</span> <span class="mf">27</span><span class="p">,</span> <span class="p">(</span><span class="nx">str</span><span class="p">,</span> <span class="nx">age</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
+<span class="linenos"> 9</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">str</span><span class="p">);</span>
+<span class="linenos">10</span>    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Your age is:&#39;</span><span class="p">,</span> <span class="nx">age</span><span class="p">);</span>
+<span class="linenos">11</span>    <span class="k">return</span> <span class="mf">42</span><span class="p">;</span>
+<span class="linenos">12</span><span class="p">});</span>
+<span class="linenos">13</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span>
+<span class="linenos">14</span>
+<span class="linenos">15</span><span class="c1">// This example prints:</span>
+<span class="linenos">16</span><span class="c1">//   Hello Niels!</span>
+<span class="linenos">17</span><span class="c1">//   Your age is: 27</span>
+<span class="linenos">18</span><span class="c1">//   42</span>
+</pre></div>
+</div>
+</section>
+<section id="registered-callbacks">
+<h3>Registered callbacks<a class="headerlink" href="#registered-callbacks" title="Permalink to this heading">#</a></h3>
+<p>Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, <code class="docutils literal notranslate"><span class="pre">fopencookie/funopen</span></code>). Call <code class="docutils literal notranslate"><span class="pre">koffi.register(func,</span> <span class="pre">type)</span></code> to register a callback function, with two arguments: the JS function, and the callback type.</p>
+<p>When you are done, call <code class="docutils literal notranslate"><span class="pre">koffi.unregister()</span></code> (with the value returned by <code class="docutils literal notranslate"><span class="pre">koffi.register()</span></code>) to release the slot. A maximum of 16 registered callbacks can exist at the same time. Failure to do so will leak the slot, and subsequent registrations may fail (with an exception) once all slots are used.</p>
+<p>The example below shows how to register and unregister delayed callbacks.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="k">static</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">g_cb1</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">);</span><span class="w"></span>
+<span class="linenos"> 2</span><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">g_cb2</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">str</span><span class="p">);</span><span class="w"></span>
+<span class="linenos"> 3</span>
+<span class="linenos"> 4</span><span class="kt">void</span><span class="w"> </span><span class="nf">RegisterFunctions</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">cb1</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">),</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">cb2</span><span class="p">)(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">str</span><span class="p">))</span><span class="w"></span>
+<span class="linenos"> 5</span><span class="p">{</span><span class="w"></span>
+<span class="linenos"> 6</span><span class="w">    </span><span class="n">g_cb1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cb1</span><span class="p">;</span><span class="w"></span>
+<span class="linenos"> 7</span><span class="w">    </span><span class="n">g_cb2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cb2</span><span class="p">;</span><span class="w"></span>
+<span class="linenos"> 8</span><span class="p">}</span><span class="w"></span>
+<span class="linenos"> 9</span>
+<span class="linenos">10</span><span class="kt">void</span><span class="w"> </span><span class="nf">SayIt</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">)</span><span class="w"></span>
+<span class="linenos">11</span><span class="p">{</span><span class="w"></span>
+<span class="linenos">12</span><span class="w">    </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">str</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">g_cb1</span><span class="p">(</span><span class="n">name</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">13</span><span class="w">    </span><span class="n">g_cb2</span><span class="p">(</span><span class="n">str</span><span class="p">);</span><span class="w"></span>
+<span class="linenos">14</span><span class="p">}</span><span class="w"></span>
+</pre></div>
+</div>
+<div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kd">const</span> <span class="nx">koffi</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;koffi&#39;</span><span class="p">);</span>
+<span class="linenos"> 2</span><span class="kd">const</span> <span class="nx">lib</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">load</span><span class="p">(</span><span class="s1">&#39;./callbacks.so&#39;</span><span class="p">);</span> <span class="c1">// Fake path</span>
+<span class="linenos"> 3</span>
+<span class="linenos"> 4</span><span class="kd">const</span> <span class="nx">GetCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;const char *GetCallback(const char *name)&#39;</span><span class="p">);</span>
+<span class="linenos"> 5</span><span class="kd">const</span> <span class="nx">PrintCallback</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">callback</span><span class="p">(</span><span class="s1">&#39;void PrintCallback(const char *str)&#39;</span><span class="p">);</span>
 <span class="linenos"> 6</span>
-<span class="linenos"> 7</span><span class="kd">let</span><span class="w"> </span><span class="nx">ret</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">TransferToJS</span><span class="p">(</span><span class="s1">&#39;Niels&#39;</span><span class="p">,</span><span class="w"> </span><span class="mf">27</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="nx">str</span><span class="p">,</span><span class="w"> </span><span class="nx">age</span><span class="p">)</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
-<span class="linenos"> 8</span><span class="w">    </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">str</span><span class="p">);</span><span class="w"></span>
-<span class="linenos"> 9</span><span class="w">    </span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Your age is:&#39;</span><span class="p">,</span><span class="w"> </span><span class="nx">age</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">10</span><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="mf">42</span><span class="p">;</span><span class="w"></span>
-<span class="linenos">11</span><span class="p">});</span><span class="w"></span>
-<span class="linenos">12</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">ret</span><span class="p">);</span><span class="w"></span>
-<span class="linenos">13</span>
-<span class="linenos">14</span><span class="c1">// This example prints:</span><span class="w"></span>
-<span class="linenos">15</span><span class="c1">//   Hello Niels!</span><span class="w"></span>
-<span class="linenos">16</span><span class="c1">//   Your age is: 27</span><span class="w"></span>
-<span class="linenos">17</span><span class="c1">//   42</span><span class="w"></span>
+<span class="linenos"> 7</span><span class="kd">const</span> <span class="nx">RegisterFunctions</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;void RegisterFunctions(GetCallback *cb1, PrintCallback *cb2)&#39;</span><span class="p">);</span>
+<span class="linenos"> 8</span><span class="kd">const</span> <span class="nx">SayIt</span> <span class="o">=</span> <span class="nx">lib</span><span class="p">.</span><span class="nx">func</span><span class="p">(</span><span class="s1">&#39;void SayIt(const char *name)&#39;</span><span class="p">);</span>
+<span class="linenos"> 9</span>
+<span class="linenos">10</span><span class="kd">let</span> <span class="nx">cb1</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">register</span><span class="p">(</span><span class="nx">name</span> <span class="p">=&gt;</span> <span class="s1">&#39;Hello &#39;</span> <span class="o">+</span> <span class="nx">name</span> <span class="o">+</span> <span class="s1">&#39;!&#39;</span><span class="p">,</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">pointer</span><span class="p">(</span><span class="nx">GetCallback</span><span class="p">));</span>
+<span class="linenos">11</span><span class="kd">let</span> <span class="nx">cb2</span> <span class="o">=</span> <span class="nx">koffi</span><span class="p">.</span><span class="nx">register</span><span class="p">(</span><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">,</span> <span class="s1">&#39;PrintCallback *&#39;</span><span class="p">);</span>
+<span class="linenos">12</span>
+<span class="linenos">13</span><span class="nx">RegisterFunctions</span><span class="p">(</span><span class="nx">cb1</span><span class="p">,</span> <span class="nx">cb2</span><span class="p">);</span>
+<span class="linenos">14</span><span class="nx">SayIt</span><span class="p">(</span><span class="s1">&#39;Kyoto&#39;</span><span class="p">);</span> <span class="c1">// Prints Hello Kyoto!</span>
+<span class="linenos">15</span>
+<span class="linenos">16</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">unregister</span><span class="p">(</span><span class="nx">cb1</span><span class="p">);</span>
+<span class="linenos">17</span><span class="nx">koffi</span><span class="p">.</span><span class="nx">unregister</span><span class="p">(</span><span class="nx">cb2</span><span class="p">);</span>
 </pre></div>
 </div>
-<p>On x86 platforms, only Cdecl and Stdcall callbacks are supported.</p>
+</section>
+<section id="handling-of-exceptions">
+<h3>Handling of exceptions<a class="headerlink" href="#handling-of-exceptions" title="Permalink to this heading">#</a></h3>
+<p>If an exception happens inside the JS callback, the C API will receive 0 or NULL (depending on the return value type).</p>
+<p>Handle the exception yourself (with try/catch) if you need to handle exceptions differently.</p>
+</section>
 </section>
 <section id="thread-safety">
 <h2>Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this heading">#</a></h2>
@@ -499,15 +607,27 @@
 <li><a class="reference internal" href="#c-like-prototypes">C-like prototypes</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#synchronous-calls">Synchronous calls</a></li>
+<li><a class="reference internal" href="#id1">Function calls</a><ul>
+<li><a class="reference internal" href="#calling-conventions">Calling conventions</a></li>
 <li><a class="reference internal" href="#asynchronous-calls">Asynchronous calls</a></li>
 <li><a class="reference internal" href="#variadic-functions">Variadic functions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-to-js-conversion-gotchas">C to JS conversion gotchas</a><ul>
 <li><a class="reference internal" href="#output-parameters">Output parameters</a><ul>
 <li><a class="reference internal" href="#struct-example">Struct example</a></li>
 <li><a class="reference internal" href="#opaque-handle-example">Opaque handle example</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#javascript-callbacks">Javascript callbacks</a></li>
+<li><a class="reference internal" href="#heap-allocated-values">Heap-allocated values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#javascript-callbacks">Javascript callbacks</a><ul>
+<li><a class="reference internal" href="#transient-callbacks">Transient callbacks</a></li>
+<li><a class="reference internal" href="#registered-callbacks">Registered callbacks</a></li>
+<li><a class="reference internal" href="#handling-of-exceptions">Handling of exceptions</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#thread-safety">Thread safety</a></li>
 </ul>
 </li>