r1602: Updated doc

diff --git a/ChangeLog b/ChangeLog
index 1d69f94aac36b27f719be927919a0b68e775f0b3..e69da6a5157c190a8674d9ffb4a2dfa673a8107b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -7,6 +7,9 @@ See TODO file -- actively maintained. Includes changes that you
        of UFFI. Builds on UNIX and Win32 platforms.
        * Added def-union function, added union.cl example
        * Fixed error with ensure-char-[character|integer]
+       * Added 2-d array example to examples/arrays.cl 
+       * Fixed documentation error on gethostname
+       * Added ensure-char-* and def-union to documentation
        
 20 Mar 2002
        * Updated strings.cl so that foreign-strings are always unsigned.

diff --git a/doc/ref.sgml b/doc/ref.sgml
index e8c45fd222e31318faaf6f6f8f921d368fa21bda..82ee66a5df717e7d9ed15cbbfa5e3d8d607c39f1 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -776,6 +776,75 @@ the array.
        <para>None.</para>
       </refsect1>
     </refentry>
+
+    <refentry id="def-union">
+      <refnamediv>
+       <refname>def-union</refname>
+       <refpurpose>Defines a foreign union type.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-union</function> <replaceable>name &amp;rest fields</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A name of the new union type.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>fields</parameter></term>
+           <listitem>
+             <para>A list of fields of the union.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Defines a foreign union type.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-union test-union
+  (a-char :char)
+  (an-int :int))
+
+(let ((u (allocate-foreign-object 'test-union))
+  (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
+  (prog1 
+    (ensure-char-character (get-slot-value u 'test-union 'a-char))
+    (free-foreign-object u)))
+=> #\A
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Defines a new foreign type.</para>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+
+
 </reference>
 
 <reference>
@@ -783,7 +852,8 @@ the array.
 <partintro>
 <title>Overview</title>
     <para>
-      Objects are entities that can allocated and freed.
+      Objects are entities that can allocated, referred to by pointers, and
+can be freed.
     </para>
 </partintro>
 
@@ -979,7 +1049,7 @@ the array.
            </listitem>
          </varlistentry>
          <varlistentry>
-           <term><parameter>value</parameter></term>
+           <term><returnvalue>value</returnvalue></term>
            <listitem>
              <para>The value of the object where the pointer points.
              </para>
@@ -997,9 +1067,76 @@ the array.
        <title>Examples</title>
        <para>
 <programlisting>
+(let ((intp (allocate-foreign-object :int)))
+  (setf (deref-pointer intp :int) 10)
+  (prog1
+    (deref-pointer intp :int)
+    (free-foreign-object intp)))
+=> 10
+</programlisting>
+       </para>
+      </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="ensure-char-character">
+      <refnamediv>
+       <refname>ensure-char-character</refname>
+       <refpurpose>Ensures that a dereferenced :char pointer is
+a character.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>ensure-char-character</function> <replaceable>object</replaceable> => <returnvalue>char</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>object</parameter></term>
+           <listitem>
+             <para>Either a character or a integer specifying a character code.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>char</returnvalue></term>
+           <listitem>
+             <para>A character.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Ensures that an object obtained by dereferencing a 
+<constant>:char</constant> pointer is a character.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <para>
+<programlisting>
 (let ((fs (convert-to-foreign-string "a")))
   (prog1 
-    (ensure-char (deref-pointer fs :char))
+    (ensure-char-character (deref-pointer fs :char))
     (free-foreign-object fs)))
 => #\a
 </programlisting>
@@ -1015,8 +1152,78 @@ the array.
       </refsect1>
       <refsect1>
        <title>Exceptional Situations</title>
+       <para>Depending upon the implementation and what &uffi; expects, this
+macro may signal an error if the object is not a character or
+integer.</para>
+      </refsect1>
+    </refentry>
+
+    <refentry id="ensure-char-integer">
+      <refnamediv>
+       <refname>ensure-char-integer</refname>
+       <refpurpose>Ensures that a dereferenced :char pointer is
+an integer.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>ensure-char-integer</function> <replaceable>object</replaceable> => <returnvalue>int</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>object</parameter></term>
+           <listitem>
+             <para>Either a character or a integer specifying a character code.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>int</returnvalue></term>
+           <listitem>
+             <para>An integer.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Ensures that an object obtained by dereferencing a 
+<constant>:char</constant> pointer is an integer.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <para>
+<programlisting>
+(let ((fs (convert-to-foreign-string "a")))
+  (prog1 
+    (ensure-char-integer (deref-pointer fs :char))
+    (free-foreign-object fs)))
+=> 96
+</programlisting>
+       </para>
+      </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>Depending upon the implementation and what &uffi; expects, this
+macro may signal an error if the object is not a character or
+integer.</para>
+      </refsect1>
     </refentry>
 
     <refentry id="make-null-pointer">
@@ -1638,7 +1845,7 @@ foreign function. If <constant>:void</constant> indicates module does not return
        <title>Examples</title>
        <programlisting>
 (def-function "gethostname" 
-  ((name :cstring)
+  ((name (* :unsigned-char))
    (len :int))
   :returning :int)
        </programlisting>