1 <!-- FFI docs as a chapter -->
4 <Title>Foreign function interface</Title>
6 <para>The foreign function interface consists of the following
11 <para>The Foreign Function Interface language specification
12 (which constitutes most of this Chapter, beginning with <xref
13 linkend="sec-ffi-intro">). You must use the
14 <option>-fglasgow-exts</option> command-line option to make GHC
15 understand the <literal>foreign</literal> declarations defined
20 <para>Several library modules which provide access to types used
21 by foreign languages and utilties for marshalling values to and
22 from foreign functions, and for converting errors in the foreign
23 language into Haskell IO errors. See <xref linkend="sec-Foreign"> for
31 <title>Using the FFI with GHC</title>
33 <para>The following sections also give some hints and tips on the
34 use of the foreign function interface in GHC.</para>
36 <sect2 id="foreign-export-ghc">
37 <title>Using <literal>foreign export</literal> with GHC</title>
39 <indexterm><primary><literal>foreign export
40 </literal></primary><secondary>with GHC</secondary>
43 <para>When GHC compiles a module (say <filename>M.hs</filename>)
44 which uses <literal>foreign export</literal> or <literal>foreign
45 export dynamic</literal>, it generates two
46 additional files, <filename>M_stub.c</filename> and
47 <filename>M_stub.h</filename>. GHC will automatically compile
48 <filename>M_stub.c</filename> to generate
49 <filename>M_stub.o</filename> at the same time.</para>
51 <para>For a plain <literal>foreign export</literal>, the file
52 <filename>M_stub.h</filename> contains a C prototype for the
53 foreign exported function, and <filename>M_stub.c</filename>
54 contains its definition. For example, if we compile the
55 following module:</para>
60 foreign export foo :: Int -> IO Int
63 foo n = return (length (f n))
67 f n = n:(f (n-1))</programlisting>
69 <para>Then <filename>Foo_stub.h</filename> will contain
70 something like this:</para>
74 extern HsInt foo(HsInt a0);</programlisting>
76 <para>and <filename>Foo_stub.c</filename> contains the
77 compiler-generated definition of <literal>foo()</literal>. To
78 invoke <literal>foo()</literal> from C, just <literal>#include
79 "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
82 <title>Using your own <literal>main()</literal></title>
84 <para>Normally, GHC's runtime system provides a
85 <literal>main()</literal>, which arranges to invoke
86 <literal>Main.main</literal> in the Haskell program. However,
87 you might want to link some Haskell code into a program which
88 has a main function written in another languagem, say C. In
89 order to do this, you have to initialize the Haskell runtime
90 system explicitly.</para>
92 <para>Let's take the example from above, and invoke it from a
93 standalone C program. Here's the C code:</para>
96 #include <stdio.h>
101 extern void __stginit_Foo ( void );
103 int main(int argc, char *argv[])
107 startupHaskell(argc, argv, __stginit_Foo);
109 for (i = 0; i < 5; i++) {
110 printf("%d\n", foo(2500));
118 <para>The call to <literal>startupHaskell()</literal>
119 initializes GHC's runtime system. Do NOT try to invoke any
120 Haskell functions before calling
121 <literal>startupHaskell()</literal>: strange things will
122 undoubtedly happen.</para>
124 <para>We pass <literal>argc</literal> and
125 <literal>argv</literal> to <literal>startupHaskell()</literal>
126 so that it can separate out any arguments for the RTS
127 (i.e. those arguments between
128 <literal>+RTS...-RTS</literal>).</para>
130 <para>The third argument to <literal>startupHaskell()</literal>
131 is used for initializing the Haskell modules in the program.
132 It must be the name of the initialization function for the
133 "top" module in the program/library - in other words, the
134 module which directly or indirectly imports all the other
135 Haskell modules in the program. In a standalone Haskell
136 program this would be module <literal>Main</literal>, but when
137 you are only using the Haskell code as a library it may not
138 be. If your library doesn't have such a module, then it is
139 straightforward to create one, purely for this initialization
140 process. The name of the initialization function for module
141 <replaceable>M</replaceable> is
142 <literal>__stginit_<replaceable>M</replaceable></literal>, and
143 it may be declared as an external function symbol as in the
146 <para>After we've finished invoking our Haskell functions, we
147 can call <literal>shutdownHaskell()</literal>, which
148 terminates the RTS. It runs any outstanding finalizers and
149 generates any profiling or stats output that might have been
152 <para>The functions <literal>startupHaskell()</literal> and
153 <literal>shutdownHaskell()</literal> may be called only once
154 each, and only in that order.</para>
157 <sect3 id="foreign-export-dynamic-ghc">
158 <title>Using <literal>foreign export dynamic</literal> with
161 <indexterm><primary><literal>foreign export
162 dynamic</literal></primary><secondary>with GHC</secondary>
165 <para>When <literal>foreign export dynamic</literal> is used
166 in a Haskell module, The C stub file
167 <filename>M_stub.c</filename> generated by GHC contains small
168 helper functions used by the code generated for the
169 <literal>foreign export dynamic</literal>, so it must be
170 linked in to the final program. When linking the program,
171 remember to include <filename>M_stub.o</filename> in the final
172 link command line, or you'll get link errors for the missing
173 function(s) (this isn't necessary when building your program
174 with <literal>ghc --make</literal>, as GHC will automatically
175 link in the correct bits).</para>
179 <sect2 id="glasgow-foreign-headers">
180 <title>Using function headers</title>
182 <indexterm><primary>C calls, function headers</primary></indexterm>
184 <para>When generating C (using the <option>-fvia-C</option>
186 directive), one can assist the C compiler in detecting type
187 errors by using the <option>-#include</option> directive
188 (<xref linkend="options-C-compiler">) to provide
189 <filename>.h</filename> files containing function
192 <para>For example,</para>
197 void initialiseEFS (HsInt size);
198 HsInt terminateEFS (void);
199 HsForeignObj emptyEFS(void);
200 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
201 HsInt lookupEFS (HsForeignObj a, HsInt i);
204 <para>The types <literal>HsInt</literal>,
205 <literal>HsForeignObj</literal> etc. are described in <xref
206 linkend="sec-ffi-mapping-table">.</para>
208 <para>Note that this approach is only
209 <emphasis>essential</emphasis> for returning
210 <literal>float</literal>s (or if <literal>sizeof(int) !=
211 sizeof(int *)</literal> on your architecture) but is a Good
212 Thing for anyone who cares about writing solid code. You're
213 crazy not to do it.</para>
220 ;;; Local Variables: ***
222 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***