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>:char</constant> - Signed 8-bits</para>
77 <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
80 <para><constant>:short</constant> - Signed 16-bits</para>
83 <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
86 <para><constant>:int</constant> - Signed 32-bits</para>
89 <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
92 <para><constant>:long</constant> - Signed 32-bits</para>
95 <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
98 <para><constant>:float</constant> - 32-bit floating point</para>
101 <para><constant>:double</constant> - 64-bit floating point</para>
104 <para><constant>:cstring</constant> -
105 A null-terminated string used for passing and returning with a function.
109 <para><constant>:void</constant> -
110 The absence of a value. Used in generic pointers and in return types from functions.</para>
113 <para><constant>*</constant> - Used to declare a pointer to an object</para>
118 <title>def-constant</title>
120 This is a thin wrapper around
121 <function>defconstant</function>. It evaluates at
122 compile-time and exports the symbol from the package.
126 <title>def-type</title>
128 This is the main function for creating new types.
131 <title>Examples</title>
134 (def-type my-generic-pointer (* :void))
135 (def-type a-double-float :double-float)
136 (def-type char-ptr (* :char))
142 <title>null-char-p</title>
144 A predicate testing if a pointer object is &null;
150 <title>Aggregate Types</title>
152 <title>def-enum</title>
154 Declares a &c; enumeration. It generates constants for the
155 elements of the enumeration.
159 <title>def-struct</title>
161 Declares a structure. A special type is available as a slot in the field. It is
162 a pointer that points to an instance of the parent structure. It's type is
163 <constant>:pointer-self</constant>.
166 <title>Examples</title>
169 (def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
174 <sect2 id="get-slot-value">
175 <title>get-slot-value</title>
177 Accesses a slot value from a structure.
181 <title>get-slot-pointer</title>
183 This is similar to <function>get-slot-value</function>. It
184 is used when the value of a slot is a pointer type.
188 <title>def-array</title>
194 <title>deref-array</title>
196 Accesses an element of an array.
202 <title>Objects</title>
204 <title>Overview</title>
206 Objects are entities that can allocated and freed.
210 <title>allocate-foreign-object</title>
212 Allocates an instance of a foreign object. It returns a pointer to the object.
216 <title>free-foreign-object</title>
218 Frees the memory used by a foreign object.
222 <title>pointer-address</title>
224 Returns the address as an integer of a pointer.
228 <title>deref-pointer</title>
230 Returns the object to which a pointer points.
234 <title>make-null-pointer</title>
236 Creates a &null; pointer of a specified type.
240 <title>null-pointer-p</title>
242 A predicate testing if a pointer is has a &null; value.
246 <title>+null-cstring-pointer+</title>
248 A constant &null; character pointer.
254 <title>Strings</title>
256 <title>Overview</title>
258 &uffi; has functions to two types of <varname>C</varname>-compatible
259 strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
260 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
261 may not convert these to a foreign type for efficiency sake. Thus, it is not
262 possible to "allocate" a cstring. In contrast, foreign strings
263 always need to have memory for them.
267 <title>convert-from-cstring</title>
269 Converts a Lisp string to a <varname>cstring</varname>.
273 <title>convert-to-cstring</title>
275 Converts a Lisp string to a
276 <varname>cstring</varname>. The
277 <varname>cstring</varname> should be freed with
278 <function>free-cstring</function>.
282 <title>free-cstring</title>
284 Frees any memory possibly allocated by
285 <function>convert-to-cstring</function>.
289 <title>with-cstring</title>
291 Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
294 <title>Examples</title>
297 (def-function ("getenv" c-getenv)
302 "Returns an environment variable, or NIL if it does not exist"
303 (check-type key string)
304 (with-cstring (key-cstring key)
305 (convert-from-cstring (c-getenv key-cstring))))
311 <title>convert-from-foreign-string</title>
313 Returns a Lisp string from a foreign string. Has parameters
314 to handle ASCII versus binary strings.
318 <title>convert-to-foreign-string</title>
320 Converts a Lisp string to a foreign string. Memory should be
321 freed with <function>free-foreign-object</function>.
325 <title>allocate-foreign-string</title>
327 Allocates space for a foreign string. Memory should
328 be freed with <function>free-foreign-object</function>.
334 <title>Functions</title>
335 <refentry id="def-function">
337 <refname>def-function</refname>
338 <refpurpose>Declares a function.
340 <refclass>Macro</refclass>
343 <title>Syntax</title>
345 <function>def-function</function> <replaceable>name args &key module returning</replaceable>
347 <para>Arguments and Values</para>
350 <term><parameter>name</parameter></term>
352 <para>A string or list specificying the function name. If it is a string, that names the foreign function. A Lisp name is created by translating #\_ to #\- and by converting to upper-case in case-insensitive Lisp implementations. If it is a list, the first item is a string specifying the foreign function name and the second it is a symbol stating the Lisp name.
357 <term><parameter>args</parameter></term>
359 <para>A list of argument declarations. Use &nil; to specify no arguments.
364 <term><parameter>module</parameter></term>
366 <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
370 <term><returnvalue>returning</returnvalue></term>
372 <para>A declaration specifying the result type of the
380 <title>Description</title>
381 <para>Declares a foreign function.
385 <title>Examples</title>
387 (def-function "gethostname"
394 <title>Side Effects</title>
398 <title>Affected by</title>
402 <title>Exceptional Situations</title>
409 <title>Libraries</title>
410 <refentry id="load-foreign-library">
412 <refname>load-foreign-library</refname>
413 <refpurpose>Loads a foreign library.
415 <refclass>Function</refclass>
418 <title>Syntax</title>
420 <function>load-foreign-library</function> <replaceable>filename module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
424 <title>Arguments and Values</title>
427 <term><parameter>filename</parameter></term>
429 <para>A string or pathname specifying the library location
435 <term><parameter>module</parameter></term>
437 <para>A string designating the name of the module to apply
438 to functions in this library. (Required for Lispworks)
443 <term><parameter>supporting-libraries</parameter></term>
445 <para>A list of strings naming the libraries required to
446 link the foreign library. (Required by CMUCL)
451 <term><returnvalue>success</returnvalue></term>
453 <para>A boolean flag, &t; if the library was able to be
454 loaded successfully or if the library has been previously loaded,
462 <title>Description</title>
463 <para>Loads a foreign library. Applies a module name to functions
464 within the library. Ensures that a library is only loaded once during
469 <title>Examples</title>
471 (load-foreign-library #p"/usr/lib/libmysqlclient.so" "mysql" '("c"))
476 <title>Side Effects</title>
477 <para>Loads the foreign code into the Lisp system.
481 <title>Affected by</title>
482 <para>Ability to load the file.</para>
485 <title>Exceptional Situations</title>