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>
156 <para>NOTE: when linking the final program, it is normally
157 easiest to do the link using GHC, although this isn't
158 essential. If you do use GHC, then don't forget the flag
159 <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
160 </indexterm>, otherwise GHC will try to link
161 to the <literal>Main</literal> Haskell module.</para>
164 <sect3 id="foreign-export-dynamic-ghc">
165 <title>Using <literal>foreign export dynamic</literal> with
168 <indexterm><primary><literal>foreign export
169 dynamic</literal></primary><secondary>with GHC</secondary>
172 <para>When <literal>foreign export dynamic</literal> is used
173 in a Haskell module, The C stub file
174 <filename>M_stub.c</filename> generated by GHC contains small
175 helper functions used by the code generated for the
176 <literal>foreign export dynamic</literal>, so it must be
177 linked in to the final program. When linking the program,
178 remember to include <filename>M_stub.o</filename> in the final
179 link command line, or you'll get link errors for the missing
180 function(s) (this isn't necessary when building your program
181 with <literal>ghc --make</literal>, as GHC will automatically
182 link in the correct bits).</para>
186 <sect2 id="glasgow-foreign-headers">
187 <title>Using function headers</title>
189 <indexterm><primary>C calls, function headers</primary></indexterm>
191 <para>When generating C (using the <option>-fvia-C</option>
193 directive), one can assist the C compiler in detecting type
194 errors by using the <option>-#include</option> directive
195 (<xref linkend="options-C-compiler">) to provide
196 <filename>.h</filename> files containing function
199 <para>For example,</para>
204 void initialiseEFS (HsInt size);
205 HsInt terminateEFS (void);
206 HsForeignObj emptyEFS(void);
207 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
208 HsInt lookupEFS (HsForeignObj a, HsInt i);
211 <para>The types <literal>HsInt</literal>,
212 <literal>HsForeignObj</literal> etc. are described in <xref
213 linkend="sec-ffi-mapping-table">.</para>
215 <para>Note that this approach is only
216 <emphasis>essential</emphasis> for returning
217 <literal>float</literal>s (or if <literal>sizeof(int) !=
218 sizeof(int *)</literal> on your architecture) but is a Good
219 Thing for anyone who cares about writing solid code. You're
220 crazy not to do it.</para>
227 ;;; Local Variables: ***
229 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***