doc/guide/src/ForeignFunctionInterfaceTypes.adoc

   1 ForeignFunctionInterfaceTypes
   2 =============================
   3
   4 MLton's <:ForeignFunctionInterface:> only allows values of certain SML
   5 types to be passed between SML and C.  The following types are
   6 allowed: `bool`, `char`, `int`, `real`, `word`.  All of the different
   7 sizes of (fixed-sized) integers, reals, and words are supported as
   8 well: `Int8.int`, `Int16.int`, `Int32.int`, `Int64.int`,
   9 `Real32.real`, `Real64.real`, `Word8.word`, `Word16.word`,
  10 `Word32.word`, `Word64.word`.  There is a special type,
  11 `MLton.Pointer.t`, for passing C pointers -- see <:MLtonPointer:> for
  12 details.
  13
  14 Arrays, refs, and vectors of the above types are also allowed.
  15 Because in MLton monomorphic arrays and vectors are exactly the same
  16 as their polymorphic counterpart, these are also allowed.  Hence,
  17 `string`, `char vector`, and `CharVector.vector` are also allowed.
  18 Strings are not null terminated, unless you manually do so from the
  19 SML side.
  20
  21 Unfortunately, passing tuples or datatypes is not allowed because that
  22 would interfere with representation optimizations.
  23
  24 The C header file that `-export-header` generates includes
  25 ++typedef++s for the C types corresponding to the SML types.  Here is
  26 the mapping between SML types and C types.
  27
  28 [options="header"]
  29 |====
  30 | SML type | C typedef | C type | Note
  31 | `array` | `Pointer` | `unsigned char *` |
  32 | `bool` | `Bool` | `int32_t` |
  33 | `char` | `Char8` | `uint8_t` |
  34 | `Int8.int` | `Int8` | `int8_t` |
  35 | `Int16.int` | `Int16` | `int16_t` |
  36 | `Int32.int` | `Int32` | `int32_t` |
  37 | `Int64.int` | `Int64` | `int64_t` |
  38 | `int` | `Int32` | `int32_t` | <:#Default:(default)>
  39 | `MLton.Pointer.t` | `Pointer` | `unsigned char *` |
  40 | `Real32.real` | `Real32` | `float` |
  41 | `Real64.real` | `Real64` | `double` |
  42 | `real` | `Real64` | `double` | <:#Default:(default)>
  43 | `ref` | `Pointer` | `unsigned char *` |
  44 | `string` | `Pointer` | `unsigned char *` | <:#ReadOnly:(read only)>
  45 | `vector` | `Pointer` | `unsigned char *` | <:#ReadOnly:(read only)>
  46 | `Word8.word` | `Word8` | `uint8_t` |
  47 | `Word16.word` | `Word16` | `uint16_t` |
  48 | `Word32.word` | `Word32` | `uint32_t` |
  49 | `Word64.word` | `Word64` | `uint64_t` |
  50 | `word` | `Word32` | `uint32_t` | <:#Default:(default)>
  51 |====
  52
  53 <!Anchor(Default)>Note (default): The default `int`, `real`, and
  54 `word` types may be set by the ++-default-type __type__++
  55 <:CompileTimeOptions: compiler option>.  The given C typedef and C
  56 types correspond to the default behavior.
  57
  58 <!Anchor(ReadOnly)>Note (read only): Because MLton assumes that
  59 vectors and strings are read-only (and will perform optimizations
  60 that, for instance, cause them to share space), you must not modify
  61 the data pointed to by the `unsigned char *` in C code.
  62
  63 Although the C type of an array, ref, or vector is always `Pointer`,
  64 in reality, the object has the natural C representation.  Your C code
  65 should cast to the appropriate C type if you want to keep the C
  66 compiler from complaining.
  67
  68 When calling an <:CallingFromSMLToC: imported C function from SML>
  69 that returns an array, ref, or vector result or when calling an
  70 <:CallingFromCToSML: exported SML function from C> that takes an
  71 array, ref, or string argument, then the object must be an ML object
  72 allocated on the ML heap.  (Although an array, ref, or vector object
  73 has the natural C representation, the object also has an additional
  74 header used by the SML runtime system.)
  75
  76 In addition, there is an <:MLBasis:> file, `$(SML_LIB)/basis/c-types.mlb`,
  77 which provides structure aliases for various C types:
  78
  79 |====
  80 | C type | Structure | Signature
  81 | `char` | `C_Char` | `INTEGER`
  82 | `signed char` | `C_SChar` | `INTEGER`
  83 | `unsigned char` | `C_UChar` | `WORD`
  84 | `short` | `C_Short` | `INTEGER`
  85 | `signed short` | `C_SShort` | `INTEGER`
  86 | `unsigned short` | `C_UShort` | `WORD`
  87 | `int` | `C_Int` | `INTEGER`
  88 | `signed int` | `C_SInt` | `INTEGER`
  89 | `unsigned int` | `C_UInt` | `WORD`
  90 | `long` | `C_Long` | `INTEGER`
  91 | `signed long` | `C_SLong` | `INTEGER`
  92 | `unsigned long` | `C_ULong` | `WORD`
  93 | `long long` | `C_LongLong` | `INTEGER`
  94 | `signed long long` | `C_SLongLong` | `INTEGER`
  95 | `unsigned long long` | `C_ULongLong` | `WORD`
  96 | `float` | `C_Float` | `REAL`
  97 | `double` | `C_Double` | `REAL`
  98 | `size_t` | `C_Size` | `WORD`
  99 | `ptrdiff_t` | `C_Ptrdiff` | `INTEGER`
 100 | `intmax_t` | `C_Intmax` | `INTEGER`
 101 | `uintmax_t` | `C_UIntmax` | `WORD`
 102 | `intptr_t` | `C_Intptr` | `INTEGER`
 103 | `uintptr_t` | `C_UIntptr` | `WORD`
 104 | `void *` | `C_Pointer` | `WORD`
 105 |====
 106
 107 These aliases depend on the configuration of the C compiler for the
 108 target architecture, and are independent of the configuration of MLton
 109 (including the ++-default-type __type__++
 110 <:CompileTimeOptions: compiler option>).