Primitive FFI in nhc98

The nhc98 compiler contains an implementation of the standard foreign function interface that is also available in Hugs and ghc. The most recent released version of nhc98 implements the latest standard syntax for foreign function declarations, as specified at: http://www.cse.unsw.edu.au/~chak/haskell/ffi/

The FFI standard specifies both the basic mechanism as a language extension, and a layer of libraries. The libraries contain many useful datatypes and access functions, for instance to manage memory storage in the foreign language. nhc98's implementation includes two versions of these libraries: nhc98's internal FFI library, and the standard portable Foreign libraries. The latter collection departs from the official standard only in the use of the hierarchical module namespace instead of the official flat namespace.

Compliance notes

Supported calling conventions are: ccall, noproto, and cast. (The latter two are non-standard, see below.) Unsupported calling conventions are: stdcall, jvm, dotnet, cplusplus.
foreign import "wrapper" is not yet supported.
The annotation unsafe has no special meaning in nhc98; it is purely a speed optimisation for ghc.
A foreign export specification is treated as the actual type signature for the exported function. You are not allowed a second (possibly more general) type signature.
Hence, you cannot foreign export any function that requires a class dictionary.

Extensions

Two non-standard calling conventions are provided. cast indicates that an arity-1 foreign import is only being used for its C type-cast, and hence eliminates some runtime overheads. For example,
```
  foreign import cast floatToDouble :: Float -> Double 
```
The calling convention noproto is essentially the same as ccall but tells the compiler not to generate a C function prototype for the external function. For example,
```
  foreign import sin noproto :: Float -> Float 
```
eliminates the normal generation of
```
  extern float sin (float); 
```
for occasions when such a declaration might conflict with an external declaration. (Note, if you mention a header file in the foreign entity description, this has the same effect as noproto - i.e. the header file declaration is used in preference to generating a prototype.)
The set of primitive types allowed across the FFI is slightly larger in nhc98 than the standard allowed set: we allow PackedString to be passed - these are genuine null-terminated C-style strings. Used as a result type, the string is copied into the Haskell heap (allowing the original pointer to be freed safely); used as an argument type, a pointer to the heap-allocated string is passed to C (i.e. do not free it!). However, we recommend you use the standard type Foreign.C.String instead - it is more portable.
Additionally, we allow any non-primitive datatype to be passed across the FFI (but give a Warning for each one) as a heap pointer. This feature should only be used by serious implementers, because any foreign code manipulating non-primitive data must use nhc98's internal heap format.

Recent Changes

In a foreign import specification, the specification of a C header file or library in the "external entity" string was previously ignored. nhc98 now generates #include for these header files. Where a header file is specified, the compiler does not generate its own prototype for the foreign function, as if the 'noproto' calling convention had been used.
foreign import "dynamic" is now fully supported.

The latest updates to these pages are available on the WWW from http://www.haskell.org/nhc98/

This page last modified: 16th June 2003
York Functional Programming Group