1 <Sect1 id="sec-ffi-intro">
6 The motivation behind this foreign function interface (FFI) specification is
7 to make it possible to describe in Haskell <Emphasis>source code</Emphasis>
8 the interface to foreign functionality in a Haskell system independent
9 manner. It builds on experiences made with the previous foreign function
10 interfaces provided by GHC and Hugs. However, the FFI specified in this
11 document is not in the market of trying to completely bridge the gap between
12 the actual type of an external function, and what is a
13 <Emphasis>convenient</Emphasis> type for that function to the Haskell
14 programmer. That is the domain of tools like HaskellDirect or Green Card, both
15 of which are capable of generating Haskell code that uses this FFI.
19 Generally, the FFI consists of three parts:
24 extensions to the base language Haskell 98 (most notably <Literal>foreign
25 import</Literal> and <Literal>foreign export</Literal> declarations), which
26 are specified in the present document,
32 a low-level marshalling library, which is part of the
33 <Emphasis>Language</Emphasis> part of the <Emphasis>Haskell Extension
34 Library</Emphasis> (see <xref linkend="sec-Storable">), and a
40 a high-level marshalling library, which is still under development.
45 Before diving into the details of the language extension coming with the FFI,
46 let us briefly outline the two other components of the interface.
50 The low-level marshalling library consists of a portion that is independent of
51 the targeted foreign language and dedicated support for Haskell bindings to C
52 libraries (special support for other languages may be added in the future).
53 The language independent part is given by the module
54 <literal>Foreign</literal> module (see <xref linkend="sec-Foreign">). It
55 provides support for handling references to foreign structures, for passing
56 references to Haskell structures out to foreign routines, and for storing
57 primitive data types in raw memory blocks in a portable manner. The support
58 for C libraries essentially provides Haskell representations for all basic
59 types of C (see <xref linkend="sec-CTypes"> and <xref
60 linkend="sec-CTypesISO">).
64 The high-level library, of which the interface definition is not yet
65 finalised, provides routines for marshalling complex Haskell structures as
66 well as handling out and in-out parameters in a convenient, yet protable way.
70 In the following, we will discuss the language extensions of the FFI (i.e. the
71 first point above). They can be split up into two complementary halves; one
72 half that provides Haskell constructs for importing foreign functionality into
73 Haskell, the other which lets you expose Haskell functions to the outside
74 world. We start with the former, how to import external functionality into
80 <Sect1 id="sec-ffi-primitive">
81 <Title>Calling foreign functions
85 To bind a Haskell variable name and type to an external function, we
86 introduce a new construct: <Literal>foreign import</Literal>. It defines the type of a Haskell function together with the name of an external function that actually implements it. The syntax of <Literal>foreign import</Literal> construct is as follows:
95 | 'foreign' 'import' [callconv] [ext_fun] ['unsafe'] varid '::' prim_type
101 A <Literal>foreign import</Literal> declaration is only allowed as a toplevel
102 declaration. It consists of two parts, one giving the Haskell type
103 (<Literal>prim_type</Literal>), Haskell name (<Literal>varid</Literal>) and a flag indicating whether the
104 primitive is unsafe, the other giving details of the name of the
105 external function (<Literal>ext_fun</Literal>) and its calling interface
106 (<Literal>callconv</Literal>.)
110 Giving a Haskell name and type to an external entry point is clearly
111 an unsafe thing to do, as the external name will in most cases be
112 untyped. The onus is on the programmer using <Literal>foreign import</Literal> to
113 ensure that the Haskell type given correctly maps on to the
114 type of the external function.
115 <XRef LinkEnd="sec-ffi-mapping"> specifies the mapping from
116 Haskell types to external types.
119 <Sect2 id="sec-ffi-prim-name">
120 <Title>Giving the external function a Haskell name
124 The external function has to be given a Haskell name. The name
125 must be a Haskell <Literal>varid</Literal>, so the language rules regarding
126 variable names must be followed, i.e., it must start with a
127 lower case letter followed by a sequence of alphanumeric
128 (`in the Unicode sense') characters or '.
132 Notice that with Haskell 98, underscore ('_') is included in
133 the character class <Literal>small</Literal>.
141 varid : small ( small | large | udigit | ' )*
147 <Sect2 id="sec-ffi-prim-ext-name">
148 <Title>Naming the external function
152 The name of the external function consists of two parts,
153 one specifying its location, the other its name:
159 ext_fun : ext_loc ext_name
175 foreign import stdcall "Advapi32" "RegCloseKey" regCloseKey :: Addr -> IO ()
181 states that the external function named <Function>RegCloseKey</Function> at location
182 <Function>Advapi32</Function> should be bound to the Haskell name <Function>regCloseKey</Function>.
183 For a Win32 Haskell implementation that supports the loading of DLLs
184 on-the-fly, this declaration will most likely cause the run-time
185 system to load the <Filename>Advapi32.dll</Filename> DLL before looking up the
186 function <Function>RegCloseKey()</Function> therein to get at the function pointer
187 to use when invoking <Function>regCloseKey</Function>.
191 Compiled implementations may do something completely different, i.e.,
192 mangle "RegCloseKey" to convert it into an archive/import library
193 symbol, that's assumed to be in scope when linking. The details of
194 which are platform (and compiler command-line) dependent.
198 If the location part is left out, the name of the external function
199 specifies a symbol that is assumed to be in scope when linking.
203 The location part can either contain an absolute `address' (i.e.,
204 path) of the archive/DLL, or just its name, leaving it up to the
205 underlying system (system meaning both RTS/compiler and OS) to resolve
206 the name to its real location.
210 An implementation is <Emphasis>expected</Emphasis> to be able to intelligently
211 transform the <Literal>ext_loc</Literal> location to fit platform-specific
212 practices for naming dynamic libraries. For instance, given the
219 foreign import "Foo" "foo" foo :: Int -> Int -> IO ()
225 an implementation should map <Filename>Foo</Filename> to <Filename>"Foo.dll"</Filename> on a Win32
226 platform, and <Filename>libFoo.so</Filename> on ELF platforms. If the lookup of the
227 dynamic library with this transformed location name should fail, the
228 implementation should then attempt to use the original name before
229 eventually giving up. As part of their documentation, implementations
230 of <Literal>foreign import</Literal> should specify the exact details of how
231 <Literal>ext_loc</Literal>s are transformed and resolved, including the list of
232 directories searched (and the order in which they are.)
236 In the case the Haskell name of the imported function is identical to
237 the external name, the <Literal>ext_fun</Literal> can be omitted. i.e.,
243 foreign import sin :: Double -> IO Double
255 foreign import "sin" sin :: Double -> IO Double
262 <Sect2 id="sec-ffi-cconv">
263 <Title>Calling conventions
267 The number of calling conventions supported is fixed:
273 callconv : ccall | stdcall
282 <Term><Literal>ccall</Literal></Term>
285 The 'default' calling convention on a platform, i.e., the one
286 used to do (C) function calls.
290 In the case of x86 platforms, the caller pushes function arguments
291 from right to left on the C stack before calling. The caller is
292 responsible for popping the arguments off of the C stack on return.
297 <Term><Literal>stdcall</Literal></Term>
300 A Win32 specific calling convention. The same as <Literal>ccall</Literal>, except
301 that the callee cleans up the C stack before returning.
305 The <Literal>stdcall</Literal> is a Microsoft Win32 specific wrinkle; it's used
306 throughout the Win32 API, for instance. On platforms where
307 <Literal>stdcall</Literal> isn't meaningful, it should be treated as being equal
308 to <Literal>ccall</Literal>.
319 <Emphasis remap="bf">Some remarks:</Emphasis>
325 Interoperating well with external code is the name of the game here,
326 so the guiding principle when deciding on what calling conventions
327 to include in <Literal>callconv</Literal> is that there's a demonstrated need for
328 a particular calling convention. Should it emerge that the inclusion
329 of other calling conventions will generally improve the quality of
330 this Haskell FFI, they will be considered for future inclusion in
331 <Literal>callconv</Literal>.
337 Supporting <Literal>stdcall</Literal> (and perhaps other platform-specific calling
338 conventions) raises the issue of whether a Haskell FFI should allow
339 the user to write platform-specific Haskell code. The calling
340 convention is clearly an integral part of an external function's
341 interface, so if the one used differs from the standard one specified
342 by the platform's ABI <Emphasis>and</Emphasis> that convention is used by a
343 non-trivial amount of external functions, the view of the FFI authors
344 is that a Haskell FFI should support it.
350 For <Literal>foreign import</Literal> (and other <Literal>foreign</Literal> declarations),
351 supplying the calling convention is optional. If it isn't supplied,
352 it is treated as if <Literal>ccall</Literal> was specified. Users are encouraged
353 to leave out the specification of the calling convention, if possible.
363 <Sect2 id="sec-ffi-prim-types">
364 <Title>External function types
368 The range of types that can be passed as arguments to an external
369 function is restricted (as are the range of results coming back):
375 prim_type : IO prim_result
377 | prim_arg '->' prim_type
388 If you associate a non-IO type with an external function, you
389 have the same 'proof obligations' as when you make use of
390 <Function>IOExts.unsafePerformIO</Function> in your Haskell programs.
396 The external function is strict in all its arguments.
402 <Emphasis>GHC only:</Emphasis> The GHC FFI implementation provides one extension
403 to <Literal>prim_type</Literal>:
408 | unsafe_arr_ty '->' prim_type
410 unsafe_arr_ty : ByteArray a
411 | MutableByteArray i s a
415 GHC permits the passing of its byte array primitive types
416 to external functions. There's some restrictions on when
417 they can be used; see <XRef LinkEnd="sec-ffi-arguments">
427 <XRef LinkEnd="sec-ffi-results"> defines
428 <Literal>prim_result</Literal>; <XRef LinkEnd="sec-ffi-arguments">
429 defines <Literal>prim_arg</Literal>.
432 <Sect3 id="sec-ffi-arguments">
433 <Title>Argument types
437 The external function expects zero or more arguments. The set of legal
438 argument types is restricted to the following set:
444 prim_arg : ext_ty | new_ty | ForeignObj
446 new_ty : a Haskell newtype of a prim_arg.
448 ext_ty : int_ty | word_ty | float_ty
449 | Addr | Char | StablePtr a
452 int_ty : Int | Int8 | Int16 | Int32 | Int64
453 word_ty : Word8 | Word16 | Word32 | Word64
454 float_ty : Float | Double
465 <Literal>ext_ty</Literal> represent the set of basic types supported by
466 C-like languages, although the numeric types are explicitly sized.
468 The <Emphasis>stable pointer</Emphasis> <Literal>StablePtr</Literal> type looks out of place in
469 this list of C-like types, but it has a well-defined and simple
470 C mapping, see <XRef LinkEnd="sec-ffi-mapping">
478 <Literal>prim_arg</Literal> represent the set of permissible argument types. In
479 addition to <Literal>ext_ty</Literal>, <Literal>ForeignObj</Literal> is also included.
481 The <Literal>ForeignObj</Literal> type represent values that are pointers to some
482 external entity/object. It differs from the <Literal>Addr</Literal> type in that
483 <Literal>ForeignObj</Literal>s are <Emphasis>finalized</Emphasis>, i.e., once the garbage collector
484 determines that a <Literal>ForeignObj</Literal> is unreachable, it will invoke a
485 finalising procedure attached to the <Literal>ForeignObj</Literal> to notify the
486 outside world that we're through with using it.
493 Haskell <Literal>newtype</Literal>s that wrap up a <Literal>prim_arg</Literal> type can also
494 be passed to external functions.
500 Haskell type synonyms for any of the above can also be used
501 in <Literal>foreign import</Literal> declarations. Qualified names likewise,
502 i.e. <Literal>Word.Word32</Literal> is legal.
509 <Literal>foreign import</Literal> does not support the binding to external
510 constants/variables. A <Literal>foreign import</Literal> declaration that takes no
511 arguments represent a binding to a function with no arguments.
517 <Emphasis>GHC only:</Emphasis> GHC's implementation of the FFI provides
524 Support for passing heap allocated byte arrays to an external
529 | prim_arg '->' prim_type
530 | unsafe_arr_ty '->' prim_type
532 unsafe_arr_ty : ByteArray a
533 | MutableByteArray i s a
537 GHC's <Literal>ByteArray</Literal> and <Literal>MutableByteArray</Literal> primitive types are
538 (im)mutable chunks of memory allocated on the Haskell heap, and
539 pointers to these can be passed to <Literal>foreign import</Literal>ed external
540 functions provided they are marked as <Literal>unsafe</Literal>. Since it is
541 inherently unsafe to hand out references to objects in the Haskell
542 heap if the external call may cause a garbage collection to happen,
543 you have to annotate the <Literal>foreign import</Literal> declaration with
544 the attribute <Literal>unsafe</Literal>. By doing so, the user explicitly states
545 that the external function won't provoke a garbage collection,
546 so passing out heap references to the external function is allright.
553 Another GHC extension is the support for unboxed types:
557 prim_arg : ... | unboxed_h_ty
558 ext_ty : .... | unboxed_ext_ty
560 unboxed_ext_ty : Int# | Word# | Char#
561 | Float# | Double# | Addr#
563 unboxed_h_ty : MutableByteArray# | ForeignObj#
568 Clearly, if you want to be portable across Haskell systems, using
569 system-specific extensions such as this is not advisable; avoid
570 using them if you can. (Support for using unboxed types might
571 be withdrawn sometime in the future.)
586 <Sect3 id="sec-ffi-results">
591 An external function is permitted to return the following
598 prim_result : ext_ty | new_ext_ty | ()
600 new_ext_ty : a Haskell newtype of an ext_ty.
606 where <Literal>()</Literal> represents <Literal>void</Literal> / no result.
615 External functions cannot raise exceptions (IO exceptions or non-IO ones.)
616 It is the responsibility of the <Literal>foreign import</Literal> user to layer
617 any error handling on top of an external function.
623 Only external types (<Literal>ext_ty</Literal>) can be passed back, i.e., returning
624 <Literal>ForeignObj</Literal>s is not supported/allowed.
630 Haskell newtypes that wrap up <Literal>ext_ty</Literal> are also permitted.
642 <Sect2 id="sec-ffi-mapping">
647 For the FFI to be of any practical use, the properties and sizes of
648 the various types that can be communicated between the Haskell world
649 and the outside, needs to be precisely defined. We do this by
650 presenting a mapping to C, as it is commonly used and most other
651 languages define a mapping to it. Table
652 <XRef LinkEnd="sec-ffi-mapping-table">
653 defines the mapping between Haskell and C types.
658 <Table id="sec-ffi-mapping-table">
659 <Title>Mapping of Haskell types to C types</Title>
662 <ColSpec Align="Left" Colsep="0">
663 <ColSpec Align="Left" Colsep="0">
664 <ColSpec Align="Left" Colsep="0">
665 <ColSpec Align="Left" Colsep="0">
668 <Entry>Haskell type </Entry>
669 <Entry> C type </Entry>
670 <Entry> requirement </Entry>
671 <Entry> range (9) </Entry>
677 <Literal>Char</Literal> </Entry>
678 <Entry> <Literal>HsChar</Literal> </Entry>
679 <Entry> unspec. integral type </Entry>
680 <Entry> <Literal>HS_CHAR_MIN</Literal> .. <Literal>HS_CHAR_MAX</Literal></Entry>
684 <Literal>Int</Literal> </Entry>
685 <Entry> <Literal>HsInt</Literal> </Entry>
686 <Entry> signed integral of unspec. size(4) </Entry>
687 <Entry> <Literal>HS_INT_MIN</Literal> ..
688 <Literal>HS_INT_MAX</Literal></Entry>
692 <Literal>Int8</Literal> (2) </Entry>
693 <Entry> <Literal>HsInt8</Literal> </Entry>
694 <Entry> 8 bit signed integral </Entry>
695 <Entry> <Literal>HS_INT8_MIN</Literal>
697 <Literal>HS_INT8_MAX</Literal></Entry>
701 <Literal>Int16</Literal> (2) </Entry>
702 <Entry> <Literal>HsInt16</Literal> </Entry>
703 <Entry> 16 bit signed integral </Entry>
704 <Entry> <Literal>HS_INT16_MIN</Literal>
705 .. <Literal>HS_INT16_MAX</Literal></Entry>
709 <Literal>Int32</Literal> (2) </Entry>
710 <Entry> <Literal>HsInt32</Literal> </Entry>
711 <Entry> 32 bit signed integral </Entry>
712 <Entry> <Literal>HS_INT32_MIN</Literal> ..
713 <Literal>HS_INT32_MAX</Literal></Entry>
717 <Literal>Int64</Literal> (2,3) </Entry>
718 <Entry> <Literal>HsInt64</Literal> </Entry>
719 <Entry> 64 bit signed integral (3) </Entry>
720 <Entry> <Literal>HS_INT64_MIN</Literal> ..
721 <Literal>HS_INT64_MAX</Literal></Entry>
725 <Literal>Word8</Literal> (2) </Entry>
726 <Entry> <Literal>HsWord8</Literal> </Entry>
727 <Entry> 8 bit unsigned integral </Entry>
728 <Entry> <Literal>0</Literal> ..
729 <Literal>HS_WORD8_MAX</Literal></Entry>
733 <Literal>Word16</Literal> (2) </Entry>
734 <Entry> <Literal>HsWord16</Literal> </Entry>
735 <Entry> 16 bit unsigned integral </Entry>
736 <Entry> <Literal>0</Literal> ..
737 <Literal>HS_WORD16_MAX</Literal></Entry>
741 <Literal>Word32</Literal> (2) </Entry>
742 <Entry> <Literal>HsWord32</Literal> </Entry>
743 <Entry> 32 bit unsigned integral </Entry>
744 <Entry> <Literal>0</Literal> ..
745 <Literal>HS_WORD32_MAX</Literal></Entry>
749 <Literal>Word64</Literal> (2,3) </Entry>
750 <Entry> <Literal>HsWord64</Literal> </Entry>
751 <Entry> 64 bit unsigned integral (3) </Entry>
752 <Entry> <Literal>0</Literal> ..
753 <Literal>HS_WORD64_MAX</Literal></Entry>
757 <Literal>Float</Literal> </Entry>
758 <Entry> <Literal>HsFloat</Literal> </Entry>
759 <Entry> floating point of unspec. size (5) </Entry>
760 <Entry> (10) </Entry>
764 <Literal>Double</Literal> </Entry>
765 <Entry> <Literal>HsDouble</Literal> </Entry>
766 <Entry> floating point of unspec. size (5) </Entry>
767 <Entry> (10) </Entry>
771 <Literal>Bool</Literal> </Entry>
772 <Entry> <Literal>HsBool</Literal> </Entry>
773 <Entry> unspec. integral type </Entry>
774 <Entry> (11) </Entry>
778 <Literal>Addr</Literal> </Entry>
779 <Entry> <Literal>HsAddr</Literal> </Entry>
780 <Entry> void* (6) </Entry>
785 <Literal>ForeignObj</Literal> </Entry>
786 <Entry> <Literal>HsForeignObj</Literal> </Entry>
787 <Entry> void* (7) </Entry>
792 <Literal>StablePtr</Literal> </Entry>
793 <Entry> <Literal>HsStablePtr</Literal> </Entry>
794 <Entry> void* (8) </Entry>
806 <Emphasis remap="bf">Some remarks:</Emphasis>
812 A Haskell system that implements the FFI will supply a header file
813 <Filename>HsFFI.h</Filename> that includes target platform specific definitions
814 for the above types and values.
820 The sized numeric types <Literal>Hs{Int,Word}{8,16,32,64}</Literal> have
821 a 1-1 mapping to ISO C 99's <Literal>{,u}int{8,16,32,64}_t</Literal>. For systems
822 that doesn't support this revision of ISO C, a best-fit mapping
823 onto the supported C types is provided.
829 An implementation which does not support 64 bit integral types
830 on the C side should implement <Literal>Hs{Int,Word}64</Literal> as a struct. In
831 this case the bounds <Constant>HS_INT64_{MIN,MAX}</Constant> and <Constant>HS_WORD64_MAX</Constant>
838 A valid Haskell representation of <Literal>Int</Literal> has to be equal to or
839 wider than 30 bits. The <Literal>HsInt</Literal> synonym is guaranteed to map
840 onto a C type that satisifies Haskell's requirement for <Literal>Int</Literal>.
846 It is guaranteed that <Literal>Hs{Float,Double}</Literal> are one of C's
847 floating-point types <Literal>float</Literal>/<Literal>double</Literal>/<Literal>long double</Literal>.
853 It is guaranteed that <Literal>HsAddr</Literal> is of the same size as <Literal>void*</Literal>, so
854 any other pointer type can be converted to and from HsAddr without any
855 loss of information (K&R, Appendix A6.8).
861 Foreign objects are handled like <Literal>Addr</Literal> by the FFI, so there
862 is again the guarantee that <Literal>HsForeignObj</Literal> is the same as
863 <Literal>void*</Literal>. The separate name is meant as a reminder that there is
864 a finalizer attached to the object pointed to.
870 Stable pointers are passed as addresses by the FFI, but this is
871 only because a <Literal>void*</Literal> is used as a generic container in most
872 APIs, not because they are real addresses. To make this special
873 case clear, a separate C type is used here.
879 The bounds are preprocessor macros, so they can be used in
880 <Literal>#if</Literal> and for array bounds.
886 Floating-point limits are a little bit more complicated, so
887 preprocessor macros mirroring ISO C's <Filename>float.h</Filename> are provided:
890 HS_{FLOAT,DOUBLE}_RADIX
891 HS_{FLOAT,DOUBLE}_ROUNDS
892 HS_{FLOAT,DOUBLE}_EPSILON
893 HS_{FLOAT,DOUBLE}_DIG
894 HS_{FLOAT,DOUBLE}_MANT_DIG
895 HS_{FLOAT,DOUBLE}_MIN
896 HS_{FLOAT,DOUBLE}_MIN_EXP
897 HS_{FLOAT,DOUBLE}_MIN_10_EXP
898 HS_{FLOAT,DOUBLE}_MAX
899 HS_{FLOAT,DOUBLE}_MAX_EXP
900 HS_{FLOAT,DOUBLE}_MAX_10_EXP
908 It is guaranteed that Haskell's <Literal>False</Literal>/<Literal>True</Literal> map to
909 C's <Literal>0</Literal>/<Literal>1</Literal>, respectively, and vice versa. The mapping of
910 any other integral value to <Literal>Bool</Literal> is left unspecified.
916 To avoid name clashes, identifiers starting with <Literal>Hs</Literal> and
917 macros starting with <Literal>HS_</Literal> are reserved for the FFI.
923 <Emphasis>GHC only:</Emphasis> The GHC specific types <Literal>ByteArray</Literal> and
924 <Literal>MutableByteArray</Literal> both map to <Literal>char*</Literal>.
934 <Sect2 id="sec-ffi-prim-remarks">
935 <Title>Some <Literal>foreign import</Literal> wrinkles
944 By default, a <Literal>foreign import</Literal> function is <Emphasis>safe</Emphasis>. A safe
945 external function may cause a Haskell garbage collection as a result
946 of being called. This will typically happen when the imported
947 function end up calling Haskell functions that reside in the same
948 'Haskell world' (i.e., shares the same storage manager heap) -- see
949 <XRef LinkEnd="sec-ffi-entry"> for
950 details of how the FFI let's you call Haskell functions from the outside.
952 If the programmer can guarantee that the imported function won't
953 call back into Haskell, the <Literal>foreign import</Literal> can be marked as
954 'unsafe' (see <XRef LinkEnd="sec-ffi-primitive"> for details of
957 Unsafe calls are cheaper than safe ones, so distinguishing the two
958 classes of external calls may be worth your while if you're extra
959 conscious about performance.
966 A <Literal>foreign import</Literal>ed function should clearly not need to know that
967 it is being called from Haskell. One consequence of this is that the
968 lifetimes of the arguments that are passed from Haskell <Emphasis>must</Emphasis>
969 equal that of a normal C call. For instance, for the following decl,
973 foreign import "mumble" mumble :: ForeignObj -> IO ()
975 f :: Addr -> IO ()
977 fo <- newForeignObj ptr myFinalizer
982 The <Literal>ForeignObj</Literal> must live across the call to <Function>mumble</Function> even if
983 it is not subsequently used/reachable. Why the insistence on this?
984 Consider what happens if <Function>mumble</Function> calls a function which calls back
985 into the Haskell world to execute a function, behind our back as it
986 were. This evaluation may possibly cause a garbage collection, with
987 the result that <Literal>fo</Literal> may end up being finalised.
989 By guaranteeing that <Literal>fo</Literal> will be considered live across the call
990 to <Function>mumble</Function>, the unfortunate situation where <Literal>fo</Literal> is finalised
991 (and hence the reference passed to <Function>mumble</Function> is suddenly no longer
1006 <Sect1 id="sec-ffi-prim-dynamic">
1007 <Title>Invoking external functions via a pointer
1011 A <Literal>foreign import</Literal> declaration imports an external
1012 function into Haskell. (The name of the external function
1013 is statically known, but the loading/linking of it may very well
1014 be delayed until run-time.) A <Literal>foreign import</Literal> declaration is then
1015 (approximately) just a type cast of an external function with a
1016 <Emphasis>statically known name</Emphasis>.
1020 An extension of <Literal>foreign import</Literal> is the support for <Emphasis>dynamic</Emphasis> type
1021 casts of external names/addresses:
1030 | 'foreign' 'import' [callconv] 'dynamic' ['unsafe']
1031 varid :: Addr -> (prim_args -> IO prim_result)
1037 i.e., identical to a <Literal>foreign import</Literal> declaration, but for the
1038 specification of <Literal>dynamic</Literal> instead of the name of an external
1039 function. The presence of <Literal>dynamic</Literal> indicates that when an
1040 application of <Literal>varid</Literal> is evaluated, the function pointed to by its
1041 first argument will be invoked, passing it the rest of <Literal>varid</Literal>'s
1046 What are the uses of this? Native invocation of COM methods,
1049 Or the interfacing to any other software component technologies.
1052 Haskell libraries that want to be dressed up as C libs (and hence may have
1053 to support C callbacks), Haskell code that need to dynamically load
1059 <Sect1 id="sec-ffi-entry">
1060 <Title>Exposing Haskell functions
1064 So far we've provided the Haskell programmer with ways of importing
1065 external functions into the Haskell world. The other half of the FFI
1066 coin is how to expose Haskell functionality to the outside world. So,
1067 dual to the <Literal>foreign import</Literal> declaration is <Literal>foreign export</Literal>:
1076 | 'foreign' 'export' callconv [ext_name] varid :: prim_type
1082 A <Literal>foreign export</Literal> declaration tells the compiler to expose a
1083 locally defined Haskell function to the outside world, i.e., wrap
1084 it up behind a calling interface that's useable from C. It is only
1085 permitted at the toplevel, where you have to specify the type at
1086 which you want to export the function, along with the calling
1087 convention to use. For instance, the following export declaration:
1093 foreign export ccall "foo" bar :: Int -> Addr -> IO Double
1099 will cause a Haskell system to generate the following C callable
1106 HsDouble foo(HsInt arg1, HsAddr arg2);
1112 When invoked, it will call the Haskell function <Function>bar</Function>, passing
1113 it the two arguments that was passed to <Function>foo()</Function>.
1122 The range of types that can be passed as arguments and results
1123 is restricted, since <Literal>varid</Literal> has got a <Literal>prim_type</Literal>.
1129 It is not possible to directly export operator symbols.
1135 The type checker will verify that the type given for the
1136 <Literal>foreign export</Literal> declaration is compatible with the type given to
1137 function definition itself. The type in the <Literal>foreign export</Literal> may
1138 be less general than that of the function itself. For example,
1143 f :: Num a => a -> a
1144 foreign export ccall "fInt" f :: Int -> Int
1145 foreign export ccall "fFloat" f :: Float -> Float
1149 These declarations export two C-callable procedures <Literal>fInt</Literal> and
1150 <Literal>fFloat</Literal>, both of which are implemented by the (overloaded)
1151 Haskell function <Function>f</Function>.
1158 The <Literal>foreign export</Literal>ed IO action must catch all exceptions, as
1159 the FFI does not address how to signal Haskell exceptions to the
1168 <Sect2 id="sec-ffi-callback">
1169 <Title>Exposing Haskell function values
1173 The <Literal>foreign export</Literal> declaration gives the C programmer access to
1174 statically defined Haskell functions. It does not allow you to
1175 conveniently expose dynamically-created Haskell function values as C
1176 function pointers though. To permit this, the FFI supports
1177 <Emphasis>dynamic</Emphasis> <Literal>foreign export</Literal>s:
1186 | 'foreign' 'export' [callconv] 'dynamic' varid :: prim_type -> IO Addr
1192 A <Literal>foreign export dynamic</Literal> declaration declares a C function
1193 pointer <Emphasis>generator</Emphasis>. Given a Haskell function value of some restricted
1194 type, the generator wraps it up behind an externally callable interface,
1195 returning an <Literal>Addr</Literal> to an externally callable (C) function pointer.
1199 When that function pointer is eventually called, the corresponding
1200 Haskell function value is applied to the function pointer's arguments
1201 and evaluated, returning the result (if any) back to the caller.
1205 The mapping between the argument to a <Literal>foreign export dynamic</Literal>
1206 declaration and its corresponding C function pointer type, is as
1213 typedef cType[[Res]] (*Varid_FunPtr)
1214 (cType[[Ty_1]] ,.., cType[[Ty_n]]);
1220 where <Literal>cType[[]]</Literal> is the Haskell to C type mapping presented
1221 in <XRef LinkEnd="sec-ffi-mapping">.
1225 To make it all a bit more concrete, here's an example:
1231 foreign export dynamic mkCallback :: (Int -> IO Int) -> IO Addr
1233 foreign import registerCallback :: Addr -> IO ()
1235 exportCallback :: (Int -> IO Int) -> IO ()
1236 exportCallback f = do
1237 fx <- mkCallback f
1244 The <Literal>exportCallback</Literal> lets you register a Haskell function value as
1245 a callback function to some external library. The C type of the
1246 callback that the external library expects in <Literal>registerCallback()</Literal>,
1250 An FFI implementation is encouraged to generate the C typedef corresponding
1251 to a <Literal>foreign export dynamic</Literal> declaration, but isn't required
1261 typedef HsInt (*mkCallback_FunPtr) (HsInt arg1);
1267 Creating the view of a Haskell closure as a C function pointer entails
1268 registering the Haskell closure as a 'root' with the underlying
1269 Haskell storage system, so that it won't be garbage collected. The FFI
1270 implementation takes care of this, but when the outside world is
1271 through with using a C function pointer generated by a <Literal>foreign
1272 export dynamic</Literal> declaration, it needs to be explicitly freed. This is
1279 void freeHaskellFunctionPtr(void *ptr);
1285 In the event you need to free these function pointers from within
1286 Haskell, a standard 'foreign import'ed binding of the above C entry
1287 point is also provided,
1293 Foreign.freeHaskellFunctionPtr :: Addr -> IO ()
1300 <Sect2 id="sec-ffi-foreign-label">
1301 <Title>Code addresses
1305 The <Literal>foreign import</Literal> declaration allows us to invoke an external
1306 function by name from within the comforts of the Haskell world, while
1307 <Literal>foreign import dynamic</Literal> lets us invoke an external function by
1308 address. However, there's no way of getting at the code address of
1309 some particular external label though, which is at times useful,
1310 e.g. for the construction of method tables for, say, Haskell COM
1311 components. To support this, the FFI has got <Literal>foreign label</Literal>s:
1317 foreign label "freeAtLast" addrOf_freeAtLast :: Addr
1323 The meaning of this declaration is that <Literal>addrOf_freeAtLast</Literal> will now
1324 contain the address of the label <Literal>freeAtLast</Literal>.
1330 <!-- This doesn't need to be seen in the docs
1331 <Sect1 id="sec-ffi-changelog">
1332 <Title>Change history
1347 changed the C representation of <Literal>Haskell_ForeignObj</Literal> from
1348 <Literal>(long*)</Literal> to <Literal>(void*)</Literal> ANSI C guarantees that <Literal>(void*)</Literal>
1349 is the widest possible data pointer.
1355 Updated defnition of <Literal>varid</Literal> in
1356 <XRef LinkEnd="sec-ffi-prim-name"> to reflect Haskell98's.
1362 Replaced confusing uses of <Literal>stdcall</Literal> with <Literal>ccall</Literal>.
1379 Simplified the calling convention section, support for Pascal (and
1380 fastcall) calling conventions dropped.
1386 Clarified that the arguments to a safe <Literal>foreign import</Literal> must have
1387 lifetimes that equal that of a C function application.
1393 Outlawed the use of the (GHC specific) types <Literal>ByteArray</Literal>
1394 and <Literal>MutableByteArray</Literal> in safe <Literal>foreign import</Literal>s.
1400 Added a note that support for the use of unboxed types in
1401 <Literal>foreign import</Literal> may be withdrawn/deprecated sometime in the future.
1407 Simplified section which sketches a possible implementation.
1413 Use <Literal>Hs</Literal> as prefix for the typedefs for the primitive Haskell
1414 FFI types rather than the longer <Literal>Haskell_</Literal>.
1431 Leave out implementation section; of limited interest.
1437 Outlined the criteria used to decide on what calling
1438 conventions to support.
1444 Include <Literal>newtype</Literal>s that wrap primitive types in the list
1445 of types that can be both passed to and returned from external
1463 Updated the section on type mapping to integrate some comments
1464 from people on <ffi@haskell.org> (a fair chunk of the text
1465 in that section was contributed by Sven Panne.)
1471 <Function>freeHaskellFunctionPtr</Function> should belong to module <Literal>Foreign</Literal>, not <Literal>IOExts</Literal>.
1489 <Literal>Bool</Literal> is now an FFI-supported type (i.e., added it to
1490 <Literal>ext_ty</Literal>.)