Noffi

1 Introduction

Nocturnal FFI (noffi) is a novel approach to use foreign libraries from Common Lisp. All that is needed to start addressing some foreign library is pointing noffi to the header file and the library. No bindings need to be written. This is possible because internally noffi works more like a C compiler than like a binding or wrapper generator.

1.1 Brief Examples

noffi is used by means of the #_ reeder macro which is an escape route to C. 

   (noffi:noffi-syntax)        ;install #_ reader macro
   #_{#include <math.h>}       ;make declarations from <math.h> known
   (#_cos pi)
→   1.0D0
   #_M_PI
→   3.141592653589793D0

   _#(#include <stdlib.h>}

   (#_div 42 11)
→   #_((div_t){ .quot = (int)3, .rem = (int)9 })

   (let ((r (#_div 42 11)))
     (values (#_.quot r) (#_.rem r)))
→   3; 9

2 Dictionary

2.1 Foreign Data

get-c-string pointer Function

    

Examples

#_{#include <stdlib.h>}
(get-c-string (#_getenv "HOME"))
→   "/Users/joe"

get-native-utf16-string pointer Function

clet
bindings
&body body
Macro
clet&
bindings
&body body
Macro

cthe ctype form Macro

    

Like the asserts to the compiler that form form evaluates to a value of the C type ctype.

c-aref
pointer
&optional (index 0)
Accessor

    

Dereferences the foreign pointer pointer at offset index (measured in elements). Hence when pointer points to C array it returns the indexth element.

Examples

#_{#include <stdlib.h>}
(c-aref (#_getenv "HOME") 0)
→   47           ; 47 is "/"
(c-aref (#_getenv "HOME") 1)
→   85           ; 85 is "U"

c-addr-of place Function

c-coerce value c-type Function

int-ptr
integer
&optional (type _<void*>)
Function

ptr-int pointer Function

ptr-gcable-p pointer Function

2.2 Utilities

use-include header-name Macro

    

Arranges for the include file specified by header-name to be parsed and its declarations been known. The angle brackets < and `>' need to be included when the header names an include file to be found with the include path.

Examples

(use-include "<stddef.h>")

pkg-use
pkg-names
&rest c-stuff-or-options
Macro

    

Arranges to use a given pkg by means of pkg-config.

pkg-names is either a single pkg name or a list of pkg names. Then follows either C material for #include directives or options. Options supported are:

(:additional-config-args { string }*)

Additional command line arguments to pass to the pkg-config program.

(:config-program string)

The program to use for pkg-config. The default is *pkg-config-program* which in turn defaults to "pkg-config".

pkg-use then processes remaining strings as C (at compile time) and arranges for the needed libraries to be linked into the running image at runtime.

Examples

(pkg-use "x11"
    "#include <X11/Xlib.h>")

(pkg-use ("acme" "acme-extra")
    (:additional-config-args "--atleast-version=42")
    (:config-program "/opt/acme/acme-config")
    "#define ACME_SMALL"
    "#include <acme/acme.h>")

*pkg-config-program* Parameter

    

Default pkg-config program to use with pkg-use and pkg-link.

*pkg-config-args* Parameter

    

Default list of additional command line arguments to the pkg-config program. See also: *pkg-config-program*.

2.3 Future

c-replace
destination source
&key start1 end1 start2 end2
Function

c-subseq array start end Function

ctypep
object ctype
&optional environment
Function
→ generalized-boolean

    

Arguments

object
The object to test.
ctype
The C type.
environment
The Lisp lexical environment named types refer to.

Description

Returns true, if the object object is of a C type compatible to the C type ctype.

The environment argument specifies the environment to use to find type definitions. The default nil refers to the current runtime environment. Otherwise it must be an environment object as received as an &environment parameter with a macro.

Examples

   (ctypep 100 '#_<char>)
→   T
   (ctypep 1234 '#_<char>)
→   NIL
   (ctypep pi '#_<int>)
→   NIL
   (ctypep 3.14D0 '#_<double>)
→   T
   (ctypep "foo" '#_<char*>)
→   NIL

   #_{typedef struct foo { int x; } foo_rec, *foo_ptr;}
   (ctypep (c-make #_<struct foo>) '#_<struct foo *>)
→   T
   (ctypep (c-make #_<struct foo>) '#_<foo_ptr>)
→   T

Null Pointers are typeless, hence nil is of any pointer type: 

   (ctypep nil '#_<char *>)
→   T

Unions are not like union types in the mathematical sense: 

   (ctypep 100 '#_<union { int i; double d; }>)
→   NIL

Notes

In noffi due to its dynamically typed nature, two anonymous struct or union types in same scope that look the same are considered compatible. This is different from ISO C.