defcvar

defcvar

Syntax

Macro: defcvar name-and-options type &optional documentation ⇒ lisp-name

name-and-options ::= name | (name &key read-only (library :default))
name ::= lisp-name [foreign-name] | foreign-name [lisp-name]

Arguments and Values

foreign-name

A string denoting a foreign function.

lisp-name

A symbol naming the Lisp function to be created.

type

A foreign type.

read-only

A boolean.

documentation

A Lisp string; not evaluated.

Description

The defcvar macro defines a symbol macro lisp-name that looks up foreign-name and dereferences it acording to type. It can also be setfed, unless read-only is true, in which case an error will be signaled.

When one of lisp-name or foreign-name is omitted, the other is automatically derived using the following rules:

• Foreign names are converted to Lisp names by uppercasing, replacing underscores with hyphens, and wrapping around asterisks.
• Lisp names are converted to foreign names by lowercasing, replacing hyphens with underscores, and removing asterisks, if any.

Examples

  CFFI> (defcvar "errno" :int)
  ⇒ *ERRNO*
  CFFI> (foreign-funcall "strerror" :int *errno* :string)
  ⇒ "Inappropriate ioctl for device"
  CFFI> (setf *errno* 1)
  ⇒ 1
  CFFI> (foreign-funcall "strerror" :int *errno* :string)
  ⇒ "Operation not permitted"

Trying to modify a read-only foreign variable:

  CFFI> (defcvar ("errno" +error-number+ :read-only t) :int)
  ⇒ +ERROR-NUMBER+
  CFFI> (setf +error-number+ 12)
  ;; error→ Trying to modify read-only foreign var: +ERROR-NUMBER+.
  

Note that accessing errno this way won’t work with every implementation of the C standard library.

See Also

get-var-pointer