1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>Foreign Variables</title><meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /><link rel="home" href="index.html" title="SBCL User Manual" /><link rel="up" href="ffi.html" title="Chapter5.The Foreign Function Interface" /><link rel="previous" href="foreign-values.html" title="Operations On Foreign Values" /><link rel="next" href="foreign-data-structure.html" title="Foreign Data Structure Examples" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Foreign Variables</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="foreign-values.html">Prev</a></td><th width="60%" align="center">Chapter5.The Foreign Function Interface</th><td width="20%" align="right"><a accesskey="n" href="foreign-data-structure.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="foreign-variables"></a>Foreign Variables</h2></div></div><div></div></div><p>
Both local (stack allocated) and external (C global) foreign variables are
supported.
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2920801"></a>Local Foreign Variables</h3></div></div><div></div></div><pre class="synopsis">(sb-alien:with-alien var-definitions &body body)</pre><p>The <tt class="function">with-alien</tt>
macro establishes local
foreign variables
with the specified
alien types and names.
This form is analogous to defining a local variable in C: additional
storage is allocated, and the initial value is copied.
This form is less
analogous to LET-allocated Lisp variables, since the variables
can't be captured in closures: they live only for the dynamic extent
of the body, and referring to them outside is a gruesome error.
</p><p>The <tt class="varname">var-definitions</tt> argument is a list of
variable definitions, each of the form
</p><pre class="programlisting">(name type &optional initial-value)</pre><p>
The names of the variables are established as symbol-macros; the bindings have
lexical scope, and may be assigned with <tt class="function">setq</tt>
or <tt class="function">setf</tt>.
</p><p>The <tt class="function">with-alien</tt> macro also establishes
a new scope for named structures
and unions. Any <tt class="varname">type</tt> specified for a variable may contain
named structure or union types with the slots specified. Within the
lexical scope of the binding specifiers and body, a locally defined
foreign structure type <tt class="type">foo</tt> can be referenced by its name using
<tt class="type">(struct foo)</tt>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2909835"></a>External Foreign Variables</h3></div></div><div></div></div><p>
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 <tt class="function">extern-alien</tt>, <tt class="function">define-alien-variable</tt> and
<tt class="function">define-alien-routine</tt> use this conversion heuristic:
</p><div class="itemizedlist"><ul type="disc"><li><p>Alien names are converted to Lisp names by uppercasing and
replacing underscores with hyphens.</p></li><li><p>Conversely, Lisp names are converted to alien names by
lowercasing and replacing hyphens with underscores.</p></li><li><p>Both the Lisp symbol and alien string names may be
separately specified by using a list of the form
</p><pre class="programlisting">(alien-string lisp-symbol)</pre></li></ul></div><p>
</p><pre class="synopsis">(sb-alien:define-alien-variable name type)</pre><p>
The <tt class="function">define-alien-variable</tt> macro
defines <tt class="varname">name</tt> as an external foreign variable of the
specified foreign <tt class="type">type</tt>. <tt class="varname">name</tt> and <tt class="type">type</tt> 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 <tt class="type">type</tt>. Someday, they may well be implemented
using the <span class="acronym">ANSI</span> <tt class="function">define-symbol-macro</tt> mechanism, but
as of <span class="application">SBCL</span> 0.7.5, they are still implemented using an older
more-or-less parallel mechanism inherited from <span class="application">CMU CL</span>.
</p><p>
For example, to access a C-level counter <tt class="varname">foo</tt>, one could
write
</p><pre class="programlisting">
(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)</pre><p>
</p><pre class="synopsis">(sb-alien:get-errno)</pre><p>
Since in modern C libraries, the <tt class="varname">errno</tt> "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
<tt class="varname">define-alien-variable</tt> mechanism. Instead, <span class="application">SBCL</span> provides
the operator <tt class="function">sb-alien:get-errno</tt> to allow Lisp code to read it.
</p><pre class="synopsis">(sb-alien:extern-alien name type)</pre><p>
The <tt class="function">extern-alien</tt> macro
returns an alien with the specified <tt class="type">type</tt> which
points to an externally defined value. <tt class="varname">name</tt> is not evaluated,
and may be either a string or a symbol. <tt class="type">type</tt> is
an unevaluated alien type specifier.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="foreign-values.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="ffi.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="foreign-data-structure.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Operations On Foreign Values</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Foreign Data Structure Examples</td></tr></table></div></body></html>
|
