r8109: Automated commit for Debian build of uffi upstream-version-1.3.7

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 99234c410e200a23bb2ee9a97bd182e5436f3849..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>
@@ -1591,6 +1591,121 @@ if a cstring returned by a function is &null;.
       </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>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+
 </reference>
 
     <reference>