C Declarations - FFI 0.1
Description: FFI 0.1

Next: Alien Data, Previous: Introduction, Up: Top

## 2 C Declarations

A shim between Scheme and a C toolkit is specified by a case sensitive `.cdecl` file containing Scheme-like declarations of all relevant toolkit types, constants, and functions. Callback functions to be passed to the toolkit are also specified here.

There are some limitations on the C types that can be declared. Basic, struct, union, enum and pointer types are allowed, but bit-field members are not supported. C function parameters can be basic, enum or pointer types. The return type of a C function is the same plus `void`. Basically, no struct or union argument or return types, at the moment.

Each top-level form in the C declaration file must look like one of these:

         (include "filename")
         (typedef Name any)
         (struct Name (Member type) ...)
         (union Name (Member type) ...)
         (enum Name (Member) ...)
         (extern return-type Name (param1 arg-type) ...)
         (callback return-type Name (param1 arg-type) ...)

An enum's Name is optional.

arg-type is currently restricted to the following forms. It is assumed that a lone Name is defined as a type on this list:

         Name
         basics
         (* any)
         (enum Name)
         (enum Name (Member) ...)

return-type can be either arg-type or the word `void`.

basics can be any of the words: `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, or `double` (all lowercase).

type includes structs and unions:

         arg-type
         (struct Name)
         (struct Name (Member type) ...)
         (union Name)
         (union Name (Member type) ...)

any is any type or `void`.

The `include` expression includes another `.cdecl` file in the current `.cdecl` file. The string argument is interpreted relative to the current file's directory.

While the informal grammar above allows anonymous structs to be specified for argument or member types, they are of little use outside top-level, named struct or union declarations. The peek and poke (`C->` and `C->=`) syntax expects a type name (e.g. `"GdkEventAny"` or `"struct _GdkEventAny"`) before any member names.

         (C-include "prhello")

The `C-include` syntax takes a library name and loads the corresponding `-types` and `-const` files at syntax time. This makes the C types and constants available to the other `C-...` syntax expanders. The form binds `c-includes` in the syntax environment unless it is already defined there. Thus a `(C-includes "library")` form can be placed at the top of every file with `C-...` syntax, or loaded into the syntax-time environment of those files.