3.1 Specification File Syntax

The specification files are read by the normal Lisp reader, so they have syntax very similar to normal Lisp code. In particular, semicolon-comments and reader-macros will work.

There are several forms recognized by CFFI-Grovel:

• (include file*)

  Include the specified files (which should be strings) in the generated .c source-code.

• (in-package symbol)

  Set the package to be used for the final Lisp output. This should probably be an un-interned symbol.

• (ctype lisp-name signedness size-designator)

  Define a CFFI foreign type for the string in size-designator, e.g. (ctype :pid :unsigned "pid_t").

• (constant (lisp-name &rest c-names) &key documentation optional)

  Search for the constant named by the first c-name string found to be known to the C preprocessor and define it as lisp-name. If optional is true, no error will be raised if all the c-names are unknown.

• (define name &optional value)

  Defines an additional C pre-processor symbol, which is useful for altering the behavior of included system headers.

• (flag flag-string)

  Adds flag-string to the flags used for the C compiler invocation.

• (cstruct lisp-name c-name slots)

  Define a CFFI foreign struct with the slot data specfied. Slots are of the form (lisp-name c-name &key type count (signed t)).

• (cunion ...)

  Similar to cstruct, but defines a CFFI foreign union.

• (cstruct-and-class ...)

  Defines a CFFI foreign struct, as with cstruct and defines a CLOS class to be used with it. This is useful for mapping foreign structures to application-layer code that shouldn't need to worry about memory allocation issues.

• (cvar namespec type &key read-only)

  Defines a foreign variable of the specified type, even if that variable is potentially a C preprocessor pseudo-variable. e.g. (cvar ("errno" errno) errno-values), assuming that errno-values is an enum or equivalent to type :int.

  The namespec is similar to the namespecs used in CFFI.

• (cenum name elements)

  Defines a true C enum, with elements specified as ((lisp-name &rest c-names) &key optional documentation).

• (constantenum name elements)

  Defines an enumeration of pre-processor constants, with elements specified as ((lisp-name &rest c-names) &key optional documentation). For example:

            (constantenum address-family
              ((:af-inet "AF_INET" "PF_INET")
               :documentation "IPv4 Protocol family")
              ((:af-local "AF_UNIX" "AF_LOCAL" "PF_UNIX" "PF_LOCAL")
               :documentation "File domain sockets")
              ((:af-inet6 "AF_INET6" "PF_INET6")
               :documentation "IPv6 Protocol family")
              ((:af-packet "AF_PACKET" "PF_PACKET")
               :documentation "Raw packet access"
               :optional t))
       

  which will define :af-inet to represent the value held by AF_INET or PF_INET, whichever the pre-processor finds first. Similarly for :af-packet, but no error will be signaled if the platform supports neither AF_PACKET nor PF_PACKET.