1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <reference id="objects">
11 <title>Overview</title>
13 Objects are entities that can allocated, referred to by pointers, and
19 <refentry id="allocate-foreign-object">
21 <refname>allocate-foreign-object</refname>
22 <refpurpose>Allocates an instance of a foreign object.
24 <refclass>Macro</refclass>
29 <function>allocate-foreign-object</function> <replaceable>type &optional size</replaceable> => <returnvalue>ptr</returnvalue>
33 <title>Arguments and Values</title>
36 <term><parameter>type</parameter></term>
38 <para>The type of foreign object to allocate. This parameter is evaluated.
43 <term><parameter>size</parameter></term>
45 <para>An optional size parameter that is evaluated. If specified, allocates and returns an
46 array of <parameter>type</parameter> that is <parameter>size</parameter> members long. This parameter is evaluated.
51 <term><returnvalue>ptr</returnvalue></term>
53 <para>A pointer to the foreign object.
60 <title>Description</title>
62 Allocates an instance of a foreign object. It returns a pointer to the object.
66 <title>Examples</title>
68 (def-struct ab (a :int) (b :double))
69 (allocate-foreign-object 'ab)
74 <title>Side Effects</title>
78 <title>Affected by</title>
82 <title>Exceptional Situations</title>
88 <refentry id="free-foreign-object">
90 <refname>free-foreign-object</refname>
91 <refpurpose>Frees memory that was allocated for a foreign boject.
93 <refclass>Macro</refclass>
98 <function>free-foreign-object</function> <replaceable>ptr</replaceable>
102 <title>Arguments and Values</title>
105 <term><parameter>ptr</parameter></term>
107 <para>A pointer to the allocated foreign object to free.
114 <title>Description</title>
116 Frees the memory used by the allocation of a foreign object.
120 <title>Side Effects</title>
124 <title>Affected by</title>
128 <title>Exceptional Situations</title>
134 <refentry id="with-foreign-object">
136 <refname>with-foreign-object</refname>
137 <refpurpose>Wraps the allocation of a foreign object around a body of code.
139 <refclass>Macro</refclass>
142 <title>Syntax</title>
144 <function>with-foreign-object</function> <replaceable>(var type) &body body</replaceable> => <returnvalue>form-return</returnvalue>
148 <title>Arguments and Values</title>
151 <term><parameter>var</parameter></term>
153 <para>The variable name to bind.
158 <term><parameter>type</parameter></term>
160 <para>The type of foreign object to allocate. This parameter is evaluated.
165 <term><returnvalue>form-return</returnvalue></term>
167 <para>The result of evaluating the <parameter>body</parameter>.
174 <title>Description</title>
176 This function wraps the allocation, binding, and destruction of a foreign object.
178 &lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
179 much better with static allocation.
183 <title>Examples</title>
185 (defun gethostname2 ()
186 "Returns the hostname"
187 (uffi:with-foreign-object (name '(:array :unsigned-char 256))
188 (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
189 (uffi:convert-from-foreign-string name)
190 (error "gethostname() failed."))))
194 <title>Side Effects</title>
198 <title>Affected by</title>
202 <title>Exceptional Situations</title>
207 <refentry id="size-of-foreign-type">
209 <refname>size-of-foreign-type</refname>
210 <refpurpose>Returns the number of data bytes used by a foreign object type.
212 <refclass>Macro</refclass>
215 <title>Syntax</title>
217 <function>size-of-foreign-type</function> <replaceable>ftype</replaceable>
221 <title>Arguments and Values</title>
224 <term><parameter>ftype</parameter></term>
226 <para>A foreign type specifier. This parameter is evaluated.
233 <title>Description</title>
235 Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.
239 <title>Examples</title>
242 (size-of-foreign-object :unsigned-byte)
244 (size-of-foreign-object 'my-100-byte-vector-type)
250 <title>Side Effects</title>
252 </refsect1> <refsect1>
253 <title>Affected by</title>
257 <title>Exceptional Situations</title>
262 <refentry id="pointer-address">
264 <refname>pointer-address</refname>
265 <refpurpose>Returns the address of a pointer.
267 <refclass>Macro</refclass>
270 <title>Syntax</title>
272 <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
276 <title>Arguments and Values</title>
279 <term><parameter>ptr</parameter></term>
281 <para>A pointer to a foreign object.
286 <term><parameter>address</parameter></term>
288 <para>An integer representing the pointer's address.
295 <title>Description</title>
297 Returns the address as an integer of a pointer.
301 <title>Side Effects</title>
305 <title>Affected by</title>
309 <title>Exceptional Situations</title>
315 <refentry id="deref-pointer">
317 <refname>deref-pointer</refname>
318 <refpurpose>Deferences a pointer.
320 <refclass>Macro</refclass>
323 <title>Syntax</title>
325 <function>deref-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
329 <title>Arguments and Values</title>
332 <term><parameter>ptr</parameter></term>
334 <para>A pointer to a foreign object.
339 <term><parameter>type</parameter></term>
341 <para>A foreign type of the object being pointed to.
346 <term><returnvalue>value</returnvalue></term>
348 <para>The value of the object where the pointer points.
355 <title>Description</title>
357 Returns the object to which a pointer points.
361 <title>Examples</title>
364 (let ((intp (allocate-foreign-object :int)))
365 (setf (deref-pointer intp :int) 10)
367 (deref-pointer intp :int)
368 (free-foreign-object intp)))
376 The TYPE argument is ignored for CL implementations other than
377 AllegroCL. If you want to cast a pointer to another type use
378 WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
382 <title>Side Effects</title>
386 <title>Affected by</title>
390 <title>Exceptional Situations</title>
395 <refentry id="ensure-char-character">
397 <refname>ensure-char-character</refname>
398 <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
401 <refclass>Macro</refclass>
404 <title>Syntax</title>
406 <function>ensure-char-character</function> <replaceable>object</replaceable> => <returnvalue>char</returnvalue>
410 <title>Arguments and Values</title>
413 <term><parameter>object</parameter></term>
415 <para>Either a character or a integer specifying a character code.
420 <term><returnvalue>char</returnvalue></term>
429 <title>Description</title>
431 Ensures that an objects obtained by dereferencing
432 <constant>:char</constant> and <constant>:unsigned-char</constant>
433 pointers are a lisp character.
437 <title>Examples</title>
440 (let ((fs (convert-to-foreign-string "a")))
442 (ensure-char-character (deref-pointer fs :char))
443 (free-foreign-object fs)))
449 <title>Side Effects</title>
453 <title>Affected by</title>
457 <title>Exceptional Situations</title>
458 <para>Depending upon the implementation and what &uffi; expects, this
459 macro may signal an error if the object is not a character or
464 <refentry id="ensure-char-integer">
466 <refname>ensure-char-integer</refname>
467 <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
470 <refclass>Macro</refclass>
473 <title>Syntax</title>
475 <function>ensure-char-integer</function> <replaceable>object</replaceable> => <returnvalue>int</returnvalue>
479 <title>Arguments and Values</title>
482 <term><parameter>object</parameter></term>
484 <para>Either a character or a integer specifying a character code.
489 <term><returnvalue>int</returnvalue></term>
498 <title>Description</title>
500 Ensures that an object obtained by dereferencing a
501 <constant>:char</constant> pointer is an integer.
505 <title>Examples</title>
508 (let ((fs (convert-to-foreign-string "a")))
510 (ensure-char-integer (deref-pointer fs :char))
511 (free-foreign-object fs)))
517 <title>Side Effects</title>
521 <title>Affected by</title>
525 <title>Exceptional Situations</title>
526 <para>Depending upon the implementation and what &uffi; expects, this
527 macro may signal an error if the object is not a character or
532 <refentry id="make-null-pointer">
534 <refname>make-null-pointer</refname>
535 <refpurpose>Create a &null; pointer.
537 <refclass>Macro</refclass>
540 <title>Syntax</title>
542 <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
546 <title>Arguments and Values</title>
549 <term><parameter>type</parameter></term>
551 <para>A type of object to which the pointer refers.
556 <term><parameter>ptr</parameter></term>
558 <para>The &null; pointer of type <parameter>type</parameter>.
565 <title>Description</title>
567 Creates a &null; pointer of a specified type.
571 <title>Side Effects</title>
575 <title>Affected by</title>
579 <title>Exceptional Situations</title>
585 <refentry id="null-pointer-p">
587 <refname>null-pointer-p</refname>
588 <refpurpose>Tests a pointer for &null; value.
590 <refclass>Macro</refclass>
593 <title>Syntax</title>
595 <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
599 <title>Arguments and Values</title>
602 <term><parameter>ptr</parameter></term>
604 <para>A foreign object pointer.
609 <term><returnvalue>is-null</returnvalue></term>
611 <para>The boolean flag.
618 <title>Description</title>
620 A predicate testing if a pointer is has a &null; value.
624 <title>Side Effects</title>
628 <title>Affected by</title>
632 <title>Exceptional Situations</title>
638 <refentry id="null-cstring-pointer">
640 <refname>+null-cstring-pointer+</refname>
641 <refpurpose>A constant &null; cstring pointer.
643 <refclass>Constant</refclass>
646 <title>Description</title>
648 A &null; cstring pointer. This can be used for testing
649 if a cstring returned by a function is &null;.
654 <refentry id="with-cast-pointer">
656 <refname>with-cast-pointer</refname>
657 <refpurpose>Wraps a body of code with a pointer cast to a new type.
659 <refclass>Macro</refclass>
662 <title>Syntax</title>
664 <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) & body body</replaceable> => <returnvalue>value</returnvalue>
668 <title>Arguments and Values</title>
671 <term><parameter>binding-name</parameter></term>
673 <para>A symbol which will be bound to the casted object.
678 <term><parameter>ptr</parameter></term>
680 <para>A pointer to a foreign object.
685 <term><parameter>type</parameter></term>
687 <para>A foreign type of the object being pointed to.
692 <term><returnvalue>value</returnvalue></term>
694 <para>The value of the object where the pointer points.
701 <title>Description</title>
703 Executes BODY with POINTER cast to be a pointer to type TYPE.
704 BINDING-NAME is will be bound to this value during the execution of
707 This is a no-op in AllegroCL but will wrap BODY in a LET form if
708 BINDING-NAME is provided.
710 This macro is meant to be used in conjunction with DEREF-POINTER or
711 DEREF-ARRAY. In Allegro CL the "cast" will actually take place in
712 DEREF-POINTER or DEREF-ARRAY.
716 <title>Examples</title>
718 (with-foreign-object (size :int)
719 ;; FOO is a foreign function returning a :POINTER-VOID
720 (let ((memory (foo size)))
722 ;; at this point we know for some reason that MEMORY points
723 ;; to an array of unsigned bytes
724 (with-cast-pointer (memory :unsigned-byte)
725 (dotimes (i (deref-pointer size :int))
727 (deref-array memory '(:array :unsigned-byte) i)))))))
731 <title>Side Effects</title>
735 <title>Affected by</title>
739 <title>Exceptional Situations</title>
744 <refentry id="def-foreign-var">
746 <refname>def-foreign-var</refname>
748 Defines a symbol macro to access a variable in foreign code
750 <refclass>Macro</refclass>
753 <title>Syntax</title>
755 <function>def-foreign-var</function> <replaceable>name type module</replaceable>
759 <title>Arguments and Values</title>
762 <term><parameter>name</parameter></term>
765 A string or list specificying the symbol macro's name. If it is a
766 string, that names the foreign variable. A Lisp name is created
767 by translating #\_ to #\- and by converting to upper-case in
768 case-insensitive Lisp implementations. If it is a list, the first
769 item is a string specifying the foreign variable name and the
770 second it is a symbol stating the Lisp name.
775 <term><parameter>type</parameter></term>
777 <para>A foreign type of the foreign variable.
782 <term><returnvalue>module</returnvalue></term>
785 A string specifying the module (or library) the foreign variable
786 resides in. (Required by Lispworks)
793 <title>Description</title>
795 Defines a symbol macro which can be used to access (get and set) the
796 value of a variable in foreign code.
800 <title>Examples</title>
802 <title>C code</title>
811 foo_struct the_struct = { 42, 3.2 };
819 <title>Lisp code</title>
821 (uffi:def-struct foo-struct
825 (uffi:def-function ("foo" foo)
830 (uffi:def-foreign-var ("baz" *baz*) :int "foo")
831 (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo")
846 <title>Side Effects</title>
850 <title>Affected by</title>
854 <title>Exceptional Situations</title>