API Reference

Every exported symbol of cl-ffi. Each function's ftype is declaimed, with the full domain of each argument, so an argument of the wrong kind is a type-error when the function is called; see the docstrings for the details.

Pointers

Operator	Does
foreign-pointer	the type of foreign pointers
(pointerp object)	true if object is a pointer
(null-pointer)	a pointer to address 0
(null-pointer-p pointer)	true if pointer points to address 0
(pointer-eq pointer-1 pointer-2)	true if both point to one address
(pointer-address pointer)	the address, an integer
(make-pointer address)	a pointer to address; made and read through, it allocates nothing
(inc-pointer pointer offset)	a pointer offset bytes past pointer; offset may be negative

Memory

Operator	Does
(mem-ref pointer type &optional offset)	the scalar at offset bytes past pointer; setf writes it
(mem-aref pointer type &optional index)	element index of an array of scalars; setf writes it
(mem-aptr pointer type &optional index)	a pointer to element index of an array of any type
(foreign-alloc type &key count initial-element)	memory from malloc
(foreign-free pointer)	frees it
(with-foreign-object (variable type &optional count) body...)	memory for the body, on the stack when constant
(with-foreign-objects ((variable type &optional count)...) body...)	several, one after the other
(with-foreign-pointer (variable size &optional size-variable) body...)	size bytes for the body
(with-pointer-to-vector-data (pointer vector) body...)	a specialized vector's elements lent to C for the body
(foreign-type-size type), (foreign-type-alignment type)	a type's size and alignment in bytes
(foreign-type-lisp-type type &optional direction)	the Lisp type a call takes for an argument of type, or with :result the values type it returns, as defcfun declaims them

Types

Operator	Does
(defctype name base-type &optional documentation)	defines a typedef
(defcenum name-and-options [docstring] item...)	defines an enum: name or (name base-type); items keyword or (keyword value)
(defbitfield name-and-options [docstring] item...)	defines a bitfield: items symbol or (symbol mask)
(defcstruct name [docstring] (slot type &key count)...)	defines a struct
(defcunion name [docstring] (slot type &key count)...)	defines a union
(foreign-slot-value pointer type slot)	a scalar slot's value; setf writes it
(foreign-slot-pointer pointer type slot)	a pointer to a slot
(foreign-slot-offset type slot)	a slot's offset in bytes
(foreign-slot-type type slot)	the type a slot was defined with
(with-foreign-slots (variables pointer type) body...)	variables standing for slots
(foreign-enum-value type keyword &key errorp)	a keyword's value
(foreign-enum-keyword type value &key errorp)	a value's keyword
(foreign-enum-keyword-list type)	an enum's keywords
(foreign-bitfield-value type symbols)	the OR of the symbols' masks
(foreign-bitfield-symbols type value)	the symbols of the single bits set
(foreign-bitfield-symbol-list type)	a bitfield's symbols

Functions and callbacks

Operator	Does
(defcfun ("c_name" lisp-name) result-type [docstring] (argument type)...)	defines a function calling a C function
(foreign-funcall "name" type argument... result-type)	calls a C function by name
(foreign-funcall-pointer pointer type argument... result-type)	calls through a pointer
(foreign-funcall-varargs "name" (type argument...) type argument... result-type)	calls a variadic function
(foreign-symbol-pointer name)	a pointer to a C symbol, or nil
(defcallback name result-type ((parameter type)...) body...)	defines a function C can call
(callback name), (get-callback name)	the pointer to a callback; callback does not evaluate the name
(errno)	the errno the last foreign call left
(with-foreign-float-environment body...)	the body with C's floating-point environment

Strings

Operator	Does
(foreign-string-to-lisp pointer &key offset count max-chars encoding)	the Lisp string, and the bytes it took
(lisp-string-to-foreign string buffer size &key encoding)	writes a string into a buffer
(foreign-string-alloc string &key encoding null-terminated-p)	a malloc'd copy, and its size
(foreign-string-free pointer)	frees it
(with-foreign-string (variables string &rest options) body...)	a copy for the body; variables is pointer or (pointer size)
(with-foreign-pointer-as-string (variables size &rest options) body...)	a buffer for C to write a string into, returned as a Lisp string

Libraries and saved images

Operator	Does
(define-foreign-library name (condition spec)...)	defines a library
(use-foreign-library name)	loads it when its file is loaded
(load-foreign-library designator)	loads a library by name, or unnamed from a spec
(foreign-library-loaded-p designator)	true if it is loaded
(foreign-library-pathname designator)	the file it was loaded from
(add-image-start-hook function)	runs function when a saved image starts

Conditions

ffi-error; load-foreign-library-error, with load-foreign-library-error-library and load-foreign-library-error-attempts; encoding-error, with encoding-error-encoding and encoding-error-character; decoding-error, with decoding-error-encoding and decoding-error-position. See Errors.