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>Overview</title>
68 Immediate types have a single value, these include
69 characters, numbers, and pointers. They are all symbols in
74 <para><constant>:byte</constant> - Unsigned 8-bit</para>
77 <para><constant>:char</constant> - Signed 8-bits</para>
80 <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
83 <para><constant>:short</constant> - Signed 16-bits</para>
86 <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
89 <para><constant>:int</constant> - Signed 32-bits</para>
92 <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
95 <para><constant>:long</constant> - Signed 32-bits</para>
98 <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
101 <para><constant>:single-float</constant> - 32-bit floating point</para>
104 <para><constant>:double-float</constant> - 64-bit floating point</para>
111 - A null-terminated string used for passing and returning with a function.
119 - An absence of a value. Used in generic pointers and in
120 return types from functions.</para>
123 <para><constant>*</constant> - Used to declare a pointer to an object</para>
128 <title>def-constant</title>
130 This is a thin wrapper around
131 <function>defconstant</function>. It evaluates at
132 compile-time and exports the symbol from the package.
136 <title>def-type</title>
138 This is the main function for creating new types.
141 <title>Examples</title>
144 (def-type my-generic-pointer (* :void))
145 (def-type a-double-float :double-float)
146 (def-type char-ptr (* :char))
152 <title>null-char-p</title>
154 A predicate testing if a pointer object is &null;
160 <title>Aggregate Types</title>
162 <title>def-enum</title>
164 Declares a &c; enumeration. It generates constants for the
165 elements of the enumeration.
169 <title>def-struct</title>
171 Declares a structure. A special type is available as a slot in the field. It is
172 a pointer that points to an instance of the parent structure. It's type is
173 <constant>:pointer-self</constant>.
176 <title>Examples</title>
179 (def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
184 <sect2 id="get-slot-value">
185 <title>get-slot-value</title>
187 Accesses a slot value from a structure.
191 <title>get-slot-pointer</title>
193 This is similar to <function>get-slot-value</function>. It
194 is used when the value of a slot is a pointer type.
198 <title>def-array</title>
204 <title>deref-array</title>
206 Accesses an element of an array.
212 <title>Objects</title>
214 <title>allocate-foreign-object</title>
216 Allocates an instance of a foreign object. It returns a pointer to the object.
220 <title>free-foreign-object</title>
222 Frees the memory used by a foreign object.
226 <title>pointer-address</title>
228 Returns the address as an integer of a pointer.
232 <title>deref-pointer</title>
234 Returns the object to which a pointer points.
238 <title>make-null-pointer</title>
240 Creates a &null; pointer of a specified type.
244 <title>null-pointer-p</title>
246 A predicate testing if a pointer is has a &null; value.
250 <title>+null-cstring-pointer+</title>
252 A constant &null; character pointer.
258 <title>Strings</title>
260 <title>Overview</title>
262 &uffi; has functions to two types of <varname>C</varname>-compatible
263 strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
264 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
265 may not convert these to a foreign type for efficiency sake. Thus, it is not
266 possible to "allocate" a cstring. In contrast, foreign strings
267 always need to have memory for them.
271 <title>convert-from-cstring</title>
273 Converts a Lisp string to a <varname>cstring</varname>.
277 <title>convert-to-cstring</title>
279 Converts a Lisp string to a
280 <varname>cstring</varname>. These
281 <varname>cstring's</varname> should be freed with
282 <function>free-cstring</function>.
286 <title>free-cstring</title>
288 Frees any memory possibly allocated by
289 <function>convert-to-cstring</function>.
293 <title>with-cstring</title>
295 Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
299 <title>covert-from-foreign-string</title>
301 Returns a Lisp string from a foreign string. Has parameters
302 to handle ASCII versus binary strings.
306 <title>convert-to-foreign-string</title>
308 Converts a Lisp string to a foreign string. Memory should be
309 freed with <function>free-foreign-object</function>.
313 <title>allocate-foreign-string</title>
315 Allocates space for a foreign string. Memory should
316 be freed with <function>free-foreign-object</function>.
322 <title>Functions</title>
324 <title>def-function</title>
326 This macro generates a &c; function definition.
332 <title>Libraries</title>
334 <title>load-foreign-library</title>
336 This function loads foreign libraries. It has checks to
337 ensure that a library is loaded only once during a session.