C-calling "gotchas" checklist

And some advice, too.

• For modules that use `_ccall_'s, etc., compile with `-fvia-C'. You don't have to, but you should. Also, use the `-#include "prototypes.h"' flag (hack) to inform the C compiler of the fully-prototyped types of all the C functions you call. (Section See section Using function headers says more about this...) This scheme is the only way that you will get any typechecking of your `_ccall_'s. (It shouldn't be that way, but...)
• Try to avoid `_ccall_'s to C functions that take `float' arguments or return `float' results. Reason: if you do, you will become entangled in (ANSI?) C's rules for when arguments/results are promoted to `doubles'. It's a nightmare and just not worth it. Use `doubles' if possible. If you do use `floats', check and re-check that the right thing is happening. Perhaps compile with `-keep-hc-file-too' and look at the intermediate C (`.hc' file).
• The compiler uses two non-standard type-classes when type-checking the arguments and results of `_ccall_': the arguments (respectively result) of `_ccall_' must be instances of the class `CCallable' (respectively `CReturnable'). Both classes may be imported from the module `CCall', but this should only be necessary if you want to define a new instance. (Neither class defines any methods -- their only function is to keep the type-checker happy.) The type checker must be able to figure out just which of the C-callable/returnable types is being used. If it can't, you have to add type signatures. For example,

  f x = _ccall_ foo x
  

  is not good enough, because the compiler can't work out what type `x' is, nor what type the `_ccall_' returns. You have to write, say:

  f :: Int -> IO Double
  f x = _ccall_ foo x
  

  This table summarises the standard instances of these classes.

  Type                         CCallable  CReturnable  Which is probably...                 
  ----------------------------------------------------------------------------------------
  `Char'              Yes        Yes          `unsigned char'             
  `Int'               Yes        Yes          `long int'                  
  `Word'              Yes        Yes          `unsigned long int'         
  `Addr'              Yes        Yes          `char *'                    
  `Float'             Yes        Yes          `float'                     
  `Double'            Yes        Yes          `double'                    
  `()'                No         Yes          `void'                      
  `[Char]'            Yes        No           `char *' (null-terminated)  
  `Array'             Yes        No           `unsigned long *'           
  `ByteArray'         Yes        No           `unsigned long *'           
  `MutableArray'      Yes        No           `unsigned long *'           
  `MutableByteArray'  Yes        No           `unsigned long *'           
  `State'             Yes        Yes          nothing!                             
  `StablePtr'         Yes        Yes          `unsigned long *'           
  `ForeignObjs'       Yes        Yes          see later                            
  

  The brave and careful programmer can add their own instances of these classes for the following types:
  • A boxed-primitive type may be made an instance of both `CCallable' and `CReturnable'. A boxed primitive type is any data type with a single unary constructor with a single primitive argument. For example, the following are all boxed primitive types:

    Int
    Double
    data XDisplay = XDisplay Addr#
    data EFS a = EFS# ForeignObj#
    

    instance CCallable   (EFS a)
    instance CReturnable (EFS a)
    

  • Any datatype with a single nullary constructor may be made an instance of `CReturnable'. For example:

    data MyVoid = MyVoid
    instance CReturnable MyVoid
    

  • As at version 2.09, `String' (i.e., `[Char]') is still not a `CReturnable' type. Also, the now-builtin type `PackedString' is neither `CCallable' nor `CReturnable'. (But there are functions in the PackedString interface to let you get at the necessary bits...)
• The code-generator will complain if you attempt to use `%r' in a `_casm_' whose result type is `IO ()'; or if you don't use `%r' precisely once for any other result type. These messages are supposed to be helpful and catch bugs -- please tell us if they wreck your life.
• If you call out to C code which may trigger the Haskell garbage collector (examples of this later...), then you must use the `_ccall_GC_' or `_casm_GC_' variant of C-calls. (This does not work with the native code generator - use `\fvia-C'.) This stuff is hairy with a capital H! @end itemize

  ---

  Go to the first, previous, next, last section, table of contents.