External Foreign Variables - SBCL 1.0.31 User Manual
Description: SBCL 1.0.31 User Manual

Previous: Local Foreign Variables, Up: Foreign Variables

#### 8.4.2 External Foreign Variables

External foreign names are strings, and Lisp names are symbols. When an external foreign value is represented using a Lisp variable, there must be a way to convert from one name syntax into the other. The macros `extern-alien`, `define-alien-variable` and `define-alien-routine` use this conversion heuristic:

- Alien names are converted to Lisp names by uppercasing and replacing underscores with hyphens.
- Conversely, Lisp names are converted to alien names by lowercasing and replacing hyphens with underscores.
- Both the Lisp symbol and alien string names may be separately specified by using a list of the form

                (alien-string lisp-symbol)

— Macro: sb-alien:define-alien-variable name type

> The `define-alien-variable` macro defines name as an external foreign variable of the specified foreign `type`. name and `type` are not evaluated. The Lisp name of the variable (see above) becomes a global alien variable. Global alien variables are effectively “global symbol macros”; a reference to the variable fetches the contents of the external variable. Similarly, setting the variable stores new contents – the new contents must be of the declared `type`. Someday, they may well be implemented using the ANSI `define-symbol-macro` mechanism, but as of SBCL 0.7.5, they are still implemented using an older more-or-less parallel mechanism inherited from CMUCL.

> For example, to access a C-level counter foo, one could write

>               (define-alien-variable "foo" int)
>               ;; Now it is possible to get the value of the C variable foo simply by
>               ;; referencing that Lisp variable:
>               (print foo)
>               (setf foo 14)
>               (incf foo)

— Function: sb-alien:get-errno

> Since in modern C libraries, the `errno` “variable” is typically no longer a variable, but some bizarre artificial construct which behaves superficially like a variable within a given thread, it can no longer reliably be accessed through the ordinary `define-alien-variable` mechanism. Instead, SBCL provides the operator `sb-alien:get-errno` to allow Lisp code to read it.

— Macro: sb-alien:extern-alien name type

> The `extern-alien` macro returns an alien with the specified type which points to an externally defined value. name is not evaluated, and may be either a string or a symbol. type is an unevaluated alien type specifier.