r8103: initial import of xml format. still can not make .pdf files with Debian's...

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index cbf5336613c678cbf354dee67f10c2463dac9c63..d19c7a6ad47c35e35bbec7dd7f606724e48b28f5 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -116,10 +116,10 @@ dereferenced :unsigned-byte pointer returns an integer.</para>
            <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
          </listitem>
          <listitem>
-           <para><constant>:long</constant> - Signed 32-bits.</para>
+           <para><constant>:long</constant> - Signed 32 or 64 bits, depending upon the platform.</para>
          </listitem>
          <listitem>
-           <para><constant>:unsigned-long</constant> - Unsigned 32-bits.</para>
+           <para><constant>:unsigned-long</constant> - Unsigned 32 or 64 bits, depending upon the platform.</para>
          </listitem>
          <listitem>
            <para><constant>:float</constant> - 32-bit floating point.</para>
@@ -1515,7 +1515,7 @@ if a cstring returned by a function is &null;.
       <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
-         <function>with-cast-pointer</function> <replaceable>binding-name ptr type &amp; body body</replaceable> => <returnvalue>value</returnvalue>
+         <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) &amp; body body</replaceable> => <returnvalue>value</returnvalue>
        </synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -1547,11 +1547,11 @@ if a cstring returned by a function is &null;.
       <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
@@ -1562,6 +1562,136 @@ if a cstring returned by a function is &null;.
   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>