r1602: Updated doc

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index ad3bbffa11d63b9a2d79c896c901d3cd03ced756..82ee66a5df717e7d9ed15cbbfa5e3d8d607c39f1 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -95,7 +95,6 @@ dereferenced :char pointer returns an character.</para>
            <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
 pointer returns an character.</para>
          </listitem>
-         <listitem>
          <listitem>
            <para><constant>:byte</constant> - Unsigned 8-bits. A
 dereferenced :byte pointer returns an integer.</para>
@@ -497,7 +496,7 @@ structure. It's type is <constant>:pointer-self</constant>.
 
     <refentry id="get-slot-value">
       <refnamediv>
-       <refname>def-slot-value</refname>
+       <refname>get-slot-value</refname>
        <refpurpose>Retrieves a value from a slot of a structure.
        </refpurpose>
        <refclass>Macro</refclass>
@@ -777,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>
@@ -784,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>
 
@@ -831,7 +900,7 @@ the array.
        <title>Examples</title>
        <programlisting>
 (def-struct ab (a :int) (b :double))
-(allocate-foreign-object 'ab)
+(allocate-foreign-object ab)
 => #&lt;ptr&gt;
        </programlisting>
       </refsect1>
@@ -959,7 +1028,7 @@ the array.
       <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
-         <function>def-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
+         <function>deref-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
        </synopsis>
       </refsynopsisdiv>
       <refsect1>
@@ -980,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>
@@ -998,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>
@@ -1016,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">
@@ -1639,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>