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;
31 <title>def-type</title>
33 This is used wherever a &cl; <function>deftype</function>
34 expression can be placed. Used to declare types to
35 the compiler for optimization. Currently, on &cmucl; takes advantage
39 (uffi:def-type my-struct-def my-struct-foreign-type)
46 <title>Primitive Types</title>
48 <title>Overview</title>
50 Primitive types have a single value, these include
51 characters, numbers, and pointers. They are all symbols in
56 <para><constant>:char</constant> - Signed 8-bits</para>
59 <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
62 <para><constant>:short</constant> - Signed 16-bits</para>
65 <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
68 <para><constant>:int</constant> - Signed 32-bits</para>
71 <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
74 <para><constant>:long</constant> - Signed 32-bits</para>
77 <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
80 <para><constant>:float</constant> - 32-bit floating point</para>
83 <para><constant>:double</constant> - 64-bit floating point</para>
86 <para><constant>:cstring</constant> -
87 A null-terminated string used for passing and returning with a function.
91 <para><constant>:void</constant> -
92 The absence of a value. Used in generic pointers and in return types from functions.</para>
95 <para><constant>*</constant> - Used to declare a pointer to an object</para>
100 <title>def-constant</title>
102 This is a thin wrapper around
103 <function>defconstant</function>. It evaluates at
104 compile-time and exports the symbol from the package.
108 <title>def-type</title>
110 This is the main function for creating new types.
113 <title>Examples</title>
116 (def-type my-generic-pointer (* :void))
117 (def-type a-double-float :double-float)
118 (def-type char-ptr (* :char))
124 <title>null-char-p</title>
126 A predicate testing if a pointer object is &null;
132 <title>Aggregate Types</title>
134 <title>def-enum</title>
136 Declares a &c; enumeration. It generates constants for the
137 elements of the enumeration.
141 <title>def-struct</title>
143 Declares a structure. A special type is available as a slot in the field. It is
144 a pointer that points to an instance of the parent structure. It's type is
145 <constant>:pointer-self</constant>.
148 <title>Examples</title>
151 (def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
156 <sect2 id="get-slot-value">
157 <title>get-slot-value</title>
159 Accesses a slot value from a structure.
163 <title>get-slot-pointer</title>
165 This is similar to <function>get-slot-value</function>. It
166 is used when the value of a slot is a pointer type.
170 <title>def-array</title>
176 <title>deref-array</title>
178 Accesses an element of an array.
184 <title>Objects</title>
186 <title>Overview</title>
188 Objects are entities that can allocated and freed.
192 <title>allocate-foreign-object</title>
194 Allocates an instance of a foreign object. It returns a pointer to the object.
198 <title>free-foreign-object</title>
200 Frees the memory used by a foreign object.
204 <title>pointer-address</title>
206 Returns the address as an integer of a pointer.
210 <title>deref-pointer</title>
212 Returns the object to which a pointer points.
216 <title>make-null-pointer</title>
218 Creates a &null; pointer of a specified type.
222 <title>null-pointer-p</title>
224 A predicate testing if a pointer is has a &null; value.
228 <title>+null-cstring-pointer+</title>
230 A constant &null; character pointer.
236 <title>Strings</title>
238 <title>Overview</title>
240 &uffi; has functions to two types of <varname>C</varname>-compatible
241 strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
242 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
243 may not convert these to a foreign type for efficiency sake. Thus, it is not
244 possible to "allocate" a cstring. In contrast, foreign strings
245 always need to have memory for them.
249 <title>convert-from-cstring</title>
251 Converts a Lisp string to a <varname>cstring</varname>.
255 <title>convert-to-cstring</title>
257 Converts a Lisp string to a
258 <varname>cstring</varname>. The
259 <varname>cstring</varname> should be freed with
260 <function>free-cstring</function>.
264 <title>free-cstring</title>
266 Frees any memory possibly allocated by
267 <function>convert-to-cstring</function>.
271 <title>with-cstring</title>
273 Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
276 <title>Examples</title>
279 (def-function ("getenv" c-getenv)
284 "Returns an environment variable, or NIL if it does not exist"
285 (check-type key string)
286 (with-cstring (key-cstring key)
287 (convert-from-cstring (c-getenv key-cstring))))
293 <title>convert-from-foreign-string</title>
295 Returns a Lisp string from a foreign string. Has parameters
296 to handle ASCII versus binary strings.
300 <title>convert-to-foreign-string</title>
302 Converts a Lisp string to a foreign string. Memory should be
303 freed with <function>free-foreign-object</function>.
307 <title>allocate-foreign-string</title>
309 Allocates space for a foreign string. Memory should
310 be freed with <function>free-foreign-object</function>.
316 <title>Functions</title>
317 <refentry id="def-function">
319 <refname>def-function</refname>
320 <refpurpose>Declares a function.
322 <refclass>Macro</refclass>
325 <title>Syntax</title>
327 <function>def-function</function> <replaceable>name args &key module returning</replaceable>
331 <title>Arguments and Values</title>
334 <term><parameter>name</parameter></term>
336 <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.
341 <term><parameter>args</parameter></term>
343 <para>A list of argument declarations. Use &nil; to specify no arguments.
348 <term><parameter>module</parameter></term>
350 <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
354 <term><returnvalue>returning</returnvalue></term>
356 <para>A declaration specifying the result type of the
364 <title>Description</title>
365 <para>Declares a foreign function.
369 <title>Examples</title>
371 (def-function "gethostname"
378 <title>Side Effects</title>
382 <title>Affected by</title>
386 <title>Exceptional Situations</title>
393 <title>Libraries</title>
394 <refentry id="load-foreign-library">
396 <refname>load-foreign-library</refname>
397 <refpurpose>Loads a foreign library.
399 <refclass>Function</refclass>
402 <title>Syntax</title>
404 <function>load-foreign-library</function> <replaceable>filename &key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
408 <title>Arguments and Values</title>
411 <term><parameter>filename</parameter></term>
413 <para>A string or pathname specifying the library location
414 in the filesystem. At least one implementation (&lw;) can not
415 accept a logical pathname.
420 <term><parameter>module</parameter></term>
422 <para>A string designating the name of the module to apply
423 to functions in this library. (Required for Lispworks)
428 <term><parameter>supporting-libraries</parameter></term>
430 <para>A list of strings naming the libraries required to
431 link the foreign library. (Required by CMUCL)
436 <term><returnvalue>success</returnvalue></term>
438 <para>A boolean flag, &t; if the library was able to be
439 loaded successfully or if the library has been previously loaded,
447 <title>Description</title>
448 <para>Loads a foreign library. Applies a module name to functions
449 within the library. Ensures that a library is only loaded once during
454 <title>Examples</title>
456 (load-foreign-library #p"/usr/lib/libmysqlclient.so"
458 :supporting-libraries '("c"))
463 <title>Side Effects</title>
464 <para>Loads the foreign code into the Lisp system.
468 <title>Affected by</title>
469 <para>Ability to load the file.</para>
472 <title>Exceptional Situations</title>