<refsynopsisdiv>
<title>Syntax</title>
<synopsis>
- <function>with-cast-pointer</function> <replaceable>binding-name ptr type & body body</replaceable> => <returnvalue>value</returnvalue>
+ <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) & body body</replaceable> => <returnvalue>value</returnvalue>
</synopsis>
</refsynopsisdiv>
<refsect1>
<refsect1>
<title>Description</title>
<para>
- Executes BODY with POINTER casted to be a pointer to type TYPE. If
- BINDING-NAME is provided the casted pointer will be bound to this
+ Executes BODY with POINTER cast to be a pointer to type TYPE. If
+ BINDING-NAME is provided the cast pointer will be bound to this
name during the execution of BODY. If BINDING-NAME is not provided
POINTER must be a name bound to the pointer which should be
- casted. This name will be bound to the casted pointer during the
+ cast. This name will be bound to the cast pointer during the
execution of BODY.
This is a no-op in AllegroCL but will wrap BODY in a LET form if
DEREF-POINTER or DEREF-ARRAY.
</para>
</refsect1>
+ <refsect1>
+ <title>Examples</title>
+<programlisting>
+(with-foreign-object (size :int)
+ ;; FOO is a foreign function returning a :POINTER-VOID
+ (let ((memory (foo size)))
+ (when (mumble)
+ ;; at this point we know for some reason that MEMORY points
+ ;; to an array of unsigned bytes
+ (with-cast-pointer (memory :unsigned-byte)
+ (dotimes (i (deref-pointer size :int))
+ (do-something-with
+ (deref-array memory '(:array :unsigned-byte) i)))))))
+</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>None.</para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>None.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="def-foreign-var">
+ <refnamediv>
+ <refname>def-foreign-var</refname>
+ <refpurpose>
+Defines a symbol macro to access a variable in foreign code
+ </refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <title>Syntax</title>
+ <synopsis>
+ <function>def-foreign-var</function> <replaceable>name type module</replaceable>
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem>
+ <para>
+A string or list specificying the symbol macro's name. If it is a
+ string, that names the foreign variable. 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 variable name and the
+ second it is a symbol stating the Lisp name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem>
+ <para>A foreign type of the foreign variable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>module</returnvalue></term>
+ <listitem>
+ <para>
+ A string specifying the module (or library) the foreign variable
+ resides in. (Required by Lispworks)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>
+Defines a symbol macro which can be used to access (get and set) the
+value of a variable in foreign code.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <refsect2>
+ <title>C code</title>
+<programlisting>
+ int baz = 3;
+
+ typedef struct {
+ int x;
+ double y;
+ } foo_struct;
+
+ foo_struct the_struct = { 42, 3.2 };
+
+ int foo () {
+ return baz;
+ }
+</programlisting>
+</refsect2>
+<refsect2>
+<title>Lisp code</title>
+<programlisting>
+ (uffi:def-struct foo-struct
+ (x :int)
+ (y :double))
+
+ (uffi:def-function ("foo" foo)
+ ()
+ :returning :int
+ :module "foo")
+
+ (uffi:def-foreign-var ("baz" *baz*) :int "foo")
+ (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo")
+
+
+*baz*
+ => 3
+
+(incf *baz*)
+ => 4
+
+(foo)
+ => 4
+</programlisting>
+</refsect2>
+ </refsect1>
<refsect1>
<title>Side Effects</title>
<para>None.</para>