r1535: *** empty log message ***

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 549a4eb80eaedfd88b5526d4e7f7b937c4bc1e01..2fbf5ddcf6d70b28e52246815abb7f60a408a30a 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -62,12 +62,74 @@
 
     <sect1>
       <title>Immediate Types</title>
+      <sect2>
+       <title>Overview</title>
+       <para>
+         Immediate types have a single value, these include
+         characters, numbers, and pointers. They are all symbols in
+         the keyword package.
+       </para>
+       <itemizedlist>
+         <listitem>
+           <para><constant>:byte</constant> - Unsigned 8-bit</para>
+         </listitem>
+         <listitem>
+           <para><constant>:char</constant> - Signed 8-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:short</constant> - Signed 16-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:int</constant> - Signed 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:long</constant> - Signed 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
+         </listitem>
+         <listitem>
+           <para><constant>:single-float</constant> - 32-bit floating point</para>
+         </listitem>
+         <listitem>
+           <para><constant>:double-float</constant> - 64-bit floating point</para>
+         </listitem>
+         <listitem>
+           <para>
+             <constant>
+               :cstring
+             </constant> 
+             - A null-terminated string used for passing and returning with a function.
+             </para>
+         </listitem>
+         <listitem>
+           <para>
+             <constant>
+               :void
+             </constant> 
+             - An absence of a value. Used in generic pointers and in
+             return types from functions.</para>
+         </listitem>
+         <listitem>
+           <para><constant>*</constant> - Used to declare a pointer to an object</para>
+         </listitem>
+       </itemizedlist>
+      </sect2>
       <sect2>
        <title>def-constant</title>
        <para>
          This is a thin wrapper around
-         <function>defconstant</function>. It also exports the symbol
-         from the package.
+         <function>defconstant</function>. It evaluates at
+           compile-time and exports the symbol from the package.
        </para>
       </sect2>
       <sect2>
@@ -75,6 +137,16 @@
        <para>
          This is the main function for creating new types.
        </para>
+       <sect3>
+         <title>Examples</title>
+         <para>
+           <programlisting>
+(def-type my-generic-pointer (* :void))
+(def-type a-double-float :double-float)
+(def-type char-ptr (* :char))
+           </programlisting>
+         </para>
+       </sect3>
       </sect2>
       <sect2>
        <title>null-char-p</title>
@@ -96,8 +168,18 @@
       <sect2>
        <title>def-struct</title>
        <para>
-         Declares a structure.
+         Declares a structure. A special type is available as a slot in the field. It is
+         a pointer that points to an instance of the parent structure. It's type is
+         <constant>:pointer-self</constant>.
        </para>
+       <sect3>
+         <title>Examples</title>
+         <para>
+           <programlisting>
+(def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
+           </programlisting>
+         </para>
+       </sect3>
       </sect2>
       <sect2 id="get-slot-value">
        <title>get-slot-value</title>
@@ -131,7 +213,7 @@
       <sect2>
        <title>allocate-foreign-object</title>
        <para>
-         Allocates an instance of a foreign object.
+         Allocates an instance of a foreign object. It returns a pointer to the object.
        </para>
       </sect2>
       <sect2>
@@ -165,9 +247,9 @@
        </para>
       </sect2>
       <sect2>
-       <title>+null-c-string-ptr+</title>
+       <title>+null-cstring-pointer+</title>
        <para>
-         A constant returning a &null; character pointer;
+         A constant &null; character pointer.
        </para>
       </sect2>
     </sect1>
@@ -175,31 +257,42 @@
     <sect1>
       <title>Strings</title>
       <sect2>
-       <title>convert-from-c-string</title>
+       <title>Overview</title>
+       <para>
+         &uffi; has functions to two types of <varname>C</varname>-compatible 
+         strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
+cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
+may not convert these to a foreign type for efficiency sake. Thus, it is not
+possible to "allocate" a cstring. In contrast, foreign strings
+always need to have memory for them.
+       </para>
+      </sect2>
+      <sect2>
+       <title>convert-from-cstring</title>
        <para>
-         Converts a Lisp string to a <varname>c-string</varname>.
+         Converts a Lisp string to a <varname>cstring</varname>.
        </para>
       </sect2>
       <sect2>
-       <title>convert-to-c-string</title>
+       <title>convert-to-cstring</title>
        <para>
          Converts a Lisp string to a
-         <varname>c-string</varname>. These
-         <varname>c-string's</varname> should be freed with
-         <function>free-c-string</function>.
+         <varname>cstring</varname>. These
+         <varname>cstring's</varname> should be freed with
+         <function>free-cstring</function>.
        </para>
       </sect2>
       <sect2>
-       <title>free-c-string</title>
+       <title>free-cstring</title>
        <para>
          Frees any memory possibly allocated by
-         <function>convert-to-c-string</function>.
+         <function>convert-to-cstring</function>.
        </para>
       </sect2>
       <sect2>
-       <title>with-c-string</title>
+       <title>with-cstring</title>
        <para>
-         Binds a lexical variable to a newly allocated <varname>c-string</varname>. Automatically frees <varname>c-string</varname>.
+         Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
        </para>
       </sect2>
       <sect2>
@@ -226,11 +319,11 @@
     </sect1>
 
     <sect1>
-      <title>Routine</title>
+      <title>Functions</title>
       <sect2>
-       <title>def-routine</title>
+       <title>def-function</title>
        <para>
-         This macro generates a &c; routine definition.
+         This macro generates a &c; function definition.
        </para>
       </sect2>
     </sect1>