CallingFromSMLToC
=================

MLton's <:ForeignFunctionInterface:> allows an SML program to _import_
C functions.  Suppose you would like to import from C a function with
the following prototype:
[source,c]
----
int foo (double d, char c);
----
MLton extends the syntax of SML to allow expressions like the following:
----
_import "foo": real * char -> int;
----
This expression denotes a function of type `real * char -> int` whose
behavior is implemented by calling the C function whose name is `foo`.
Thinking in terms of C, imagine that there are C variables `d` of type
`double`, `c` of type `unsigned char`, and `i` of type `int`.  Then,
the C statement `i = foo (d, c)` is executed and `i` is returned.

The general form of an `_import` expression is:
----
_import "C function name" attr... : cFuncTy;
----
The type and the semicolon are not optional.

The function name is followed by a (possibly empty) sequence of
attributes, analogous to C `__attribute__` specifiers.  For now, the
only attributes supported are `cdecl` and `stdcall`.  These specify
the calling convention of the C function on Cygwin/Windows, and are
ignored on all other platforms.  The default is `cdecl`.  You must use
`stdcall` in order to correctly call Windows API functions.


== Example ==

`import.sml` imports the C function `ffi` and the C variable `FFI_INT`
as follows.

[source,sml]
----
sys::[./bin/InclGitFile.py mlton master doc/examples/ffi/import.sml]
----

`ffi-import.c` is

[source,c]
----
sys::[./bin/InclGitFile.py mlton master doc/examples/ffi/ffi-import.c]
----

Compile and run the program.
----
% mlton -default-ann 'allowFFI true' import.sml ffi-import.c
% ./import
13
success
----


== Download ==
* <!RawGitFile(mlton,master,doc/examples/ffi/import.sml)>
* <!RawGitFile(mlton,master,doc/examples/ffi/ffi-import.c)>


== Next Steps ==

* <:CallingFromSMLToCFunctionPointer:>
