## MLton 20241230+git20251029+dfsg-5

# ForeignFunctionInterfaceSyntax

MLton extends the syntax of SML with expressions that enable a ForeignFunctionInterface to C. The following description of the syntax uses some abbreviations.

C base type | cBaseTy | Foreign Function Interface types
--- | --- | ---
C argument type | cArgTy | `cBaseTy1 * …​ * cBaseTyn` or `unit`
C return type | cRetTy | `cBaseTy` or `unit`
C function type | cFuncTy | `cArgTy -> cRetTy`
C pointer type | cPtrTy | `MLton.Pointer.t`

The type annotation and the semicolon are not optional in the syntax of ForeignFunctionInterface expressions. However, the type is lexed, parsed, and elaborated as an SML type, so any type (including type abbreviations) may be used, so long as it elaborates to a type of the correct form.

## Address

    _address "CFunctionOrVariableName" attr... : cPtrTy;

Denotes the address of the C function or variable.

`attr…​` denotes a (possibly empty) sequence of attributes. The following attributes are recognized:

- `external` : import with external symbol scope (see LibrarySupport) (default).

- `private` : import with private symbol scope (see LibrarySupport).

- `public` : import with public symbol scope (see LibrarySupport).

See MLtonPointer for functions that manipulate C pointers.

## Symbol

    _symbol "CVariableName" attr... : (unit -> cBaseTy) * (cBaseTy -> unit);

Denotes the getter and setter for a C variable. The cBaseTys must be identical.

`attr…​` denotes a (possibly empty) sequence of attributes. The following attributes are recognized:

- `alloc` : allocate storage (and export a symbol) for the C variable.

- `external` : import or export with external symbol scope (see LibrarySupport) (default if not `alloc`).

- `private` : import or export with private symbol scope (see LibrarySupport).

- `public` : import or export with public symbol scope (see LibrarySupport) (default if `alloc`).

    _symbol * : cPtrTy -> (unit -> cBaseTy) * (cBaseTy -> unit);

Denotes the getter and setter for a C pointer to a variable. The cBaseTys must be identical.

## Import

    _import "CFunctionName" attr... : cFuncTy;

Denotes an SML function whose behavior is implemented by calling the C function. See Calling from SML to C for more details.

`attr…​` denotes a (possibly empty) sequence of attributes. The following attributes are recognized:

- `cdecl` : call with the `cdecl` calling convention (default).

- `external` : import with external symbol scope (see LibrarySupport) (default).

- `impure`: assert that the function depends upon state and/or performs side effects (default).

- `private` : import with private symbol scope (see LibrarySupport).

- `public` : import with public symbol scope (see LibrarySupport).

- `pure`: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., CommonSubexp, RemoveUnused)

- `reentrant`: assert that the function (directly or indirectly) calls an `_export`-ed SML function.

- `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).

    _import * attr... : cPtrTy -> cFuncTy;

Denotes an SML function whose behavior is implemented by calling a C function through a C function pointer.

`attr…​` denotes a (possibly empty) sequence of attributes. The following attributes are recognized:

- `cdecl` : call with the `cdecl` calling convention (default).

- `impure`: assert that the function depends upon state and/or performs side effects (default).

- `pure`: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., CommonSubexp, RemoveUnused)

- `reentrant`: assert that the function (directly or indirectly) calls an `_export`-ed SML function.

- `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).

See Calling from SML to C function pointer for more details.

## Export

    _export "CFunctionName" attr... : cFuncTy -> unit;

Exports a C function with the name `CFunctionName` that can be used to call an SML function of the type cFuncTy. When the function denoted by the export expression is applied to an SML function `f`, subsequent C calls to `CFunctionName` will call `f`. It is an error to call `CFunctionName` before the export has been applied. The export may be applied more than once, with each application replacing any previous definition of `CFunctionName`.

`attr…​` denotes a (possibly empty) sequence of attributes. The following attributes are recognized:

- `cdecl` : call with the `cdecl` calling convention (default).

- `private` : export with private symbol scope (see LibrarySupport).

- `public` : export with public symbol scope (see LibrarySupport) (default).

- `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).

See Calling from C to SML for more details.