1 <!-- -*- DocBook -*- -->
5 <title>Programming Reference</title>
8 <title>Design Overview</title>
10 &uffi; was designed as a cross-implementation compatible
11 <emphasis>Foreign Function Interface</emphasis>. Necessarily,
12 only a common subset of functionality can be
13 provided. Likewise, not every optimization for that a specific
14 implementation provides can be supported. Wherever possible,
15 though, implementation-specific optimizations are invoked.
20 <title>Declarations</title>
22 <title>Overview</title>
23 <para>Declarations are used to give the compiler optimizing
24 information about foreign types. Currently, only &cmucl;
25 supports declarations. On &acl; and &lw;, these expressions
26 declare the type generically as &t;
30 <sect2 id="uffi-declare">
31 <title>uffi-declare</title>
33 This is used wherever a <function>declare</function>
34 expression can be placed. For example:
38 (let ((my-structure (uffi:allocate-foreign-object 'a-struct)))
39 (uffi:uffi-declare a-struct my-structure))
44 <sect2 id="slot-type">
45 <title>slot-type</title>
47 This is used inside of <function>defclass</function> and
48 <function>defstruct</function> expressions to set the type
49 for a field. Because the type identifier is not evaluated in
50 &cl;, the expression must be backquoted for effect. For
57 ((char-ptr :type ,(uffi:slot-type (* :char))))))
64 <title>Immediate Types</title>
66 <title>def-constant</title>
68 This is a thin wrapper around
69 <function>defconstant</function>. It also exports the symbol
74 <title>def-type</title>
76 This is the main function for creating new types.
80 <title>null-char-p</title>
82 A predicate testing if a pointer object is &null;
88 <title>Aggregate Types</title>
90 <title>def-enum</title>
92 Declares a &c; enumeration. It generates constants for the
93 elements of the enumeration.
97 <title>def-struct</title>
102 <sect2 id="get-slot-value">
103 <title>get-slot-value</title>
105 Accesses a slot value from a structure.
109 <title>get-slot-pointer</title>
111 This is similar to <function>get-slot-value</function>. It
112 is used when the value of a slot is a pointer type.
116 <title>def-array</title>
122 <title>deref-array</title>
124 Accesses an element of an array.
130 <title>Objects</title>
132 <title>allocate-foreign-object</title>
134 Allocates an instance of a foreign object.
138 <title>free-foreign-object</title>
140 Frees the memory used by a foreign object.
144 <title>pointer-address</title>
146 Returns the address as an integer of a pointer.
150 <title>deref-pointer</title>
152 Returns the object to which a pointer points.
156 <title>make-null-pointer</title>
158 Creates a &null; pointer of a specified type.
162 <title>null-pointer-p</title>
164 A predicate testing if a pointer is has a &null; value.
168 <title>+null-cstring-pointer+</title>
170 A constant returning a &null; character pointer;
176 <title>Strings</title>
178 <title>convert-from-cstring</title>
180 Converts a Lisp string to a <varname>cstring</varname>.
184 <title>convert-to-cstring</title>
186 Converts a Lisp string to a
187 <varname>cstring</varname>. These
188 <varname>cstring's</varname> should be freed with
189 <function>free-cstring</function>.
193 <title>free-cstring</title>
195 Frees any memory possibly allocated by
196 <function>convert-to-cstring</function>.
200 <title>with-cstring</title>
202 Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
206 <title>covert-from-foreign-string</title>
208 Returns a Lisp string from a foreign string. Has parameters
209 to handle ASCII versus binary strings.
213 <title>convert-to-foreign-string</title>
215 Converts a Lisp string to a foreign string. Memory should be
216 freed with <function>free-foreign-object</function>.
220 <title>allocate-foreign-string</title>
222 Allocates space for a foreign string. Memory should
223 be freed with <function>free-foreign-object</function>.
229 <title>Routine</title>
231 <title>def-function</title>
233 This macro generates a &c; routine definition.
239 <title>Libraries</title>
241 <title>load-foreign-library</title>
243 This function loads foreign libraries. It has checks to
244 ensure that a library is loaded only once during a session.