r1573: *** empty log message ***

diff --git a/ChangeLog b/ChangeLog
index fb8b0cff9da86313be6fc7ac654f04ceb302b597..5ffd8eddac61b388b277896dd3eded88f494859a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,58 +1,40 @@
+15 Mar 2002
+       * Finished basic documentation.
+       
 14 Mar 2002
-
        * Changed license to more liberal Lisp Lessor GNU Public License
-
        * Fixed problem with including uffi.system in distribution (Thanks John DeSoi)
-
        * Fixed compiler warnings
        
 
 11 Mar 2002
-
        * Changed def-type to def-foreign-type
-
        * Created new macro def-type to generate cl:deftype forms. Removed
        uffi-declare and uffi-slot-type as they are no longer necessary.
         
 10 Mar 2002
-
        * Modified input parameters to load-foreign-library
-
        * Added to documention
-
        * Changed parameter order in get-slot-value and deref-array 
        
 9 Mar 2002
-
        * Added to documentation
-       
        * Made Allegro CL array access more efficient
-       
        * Changed def-routine name to def-function
-       
        * Fixed bug in def-function for Lispworks]
-       
        * Fixed error in +null-c-string-pointer+ name
-       
        * Fixed error in (make-null-pointer) for Lispworks
-       
        * Reworked Lispwork c-strings to be (* :char) rather than the
        implementation default of (* (:unsigned :char)) to be consistent
        with CMUCL. Bumped version to 0.2.0 because of change this change.
-       
        * Renamed c-string to cstring to emphasize it as a basic type
-       
        * Modified getenv.cl example to avoid name collison with LW
-       
        * Modified compress.cl to setup output buffer as :unsigned*char
-       
        * Added test-all-examples function. All routines tested okay with
        ACL, LW, and CMUCL
        
 8 Mar 2002
-       
        * Added ZIP file output with LF->CRLF translations to distribution
-       
        * Modified def-enum to use uffi:def-constant rather than
        cl:defconstant
        

diff --git a/Makefile b/Makefile
index 4ac6c409acacdee7dee54219d7949eb438c166e6..a090fcb030b78b13171bbc8102cf8b9b6ad7fd82 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,7 @@
 #  Programer:    Kevin M. Rosenberg, M.D.
 #  Date Started: Mar 2002
 #
-#  CVS Id:   $Id: Makefile,v 1.14 2002/03/14 21:32:23 kevin Exp $
+#  CVS Id:   $Id: Makefile,v 1.15 2002/03/15 11:38:13 kevin Exp $
 #
 # This file, part of UFFI, is Copyright (c) 2002 by Kevin M. Rosenberg
 #
@@ -31,7 +31,7 @@ realclean: clean
 docs:
        @(cd doc; make dist-doc)
 
-VERSION=0.2.5
+VERSION=0.2.6x
 DISTDIR=uffi-${VERSION}
 DIST_TARBALL=${DISTDIR}.tar.gz
 DIST_ZIP=${DISTDIR}.zip

diff --git a/doc/appendix.sgml b/doc/appendix.sgml
index 3e8c989a11f3d549718d7451699b5af002b47dbb..a888a5a6cef363454685ea16f31a415c2354df15 100644 (file)
--- a/doc/appendix.sgml
+++ b/doc/appendix.sgml
@@ -5,6 +5,26 @@
   <sect1>
     <title>Download &uffi;</title>
     <para>
+You need to download the &uffi; package from its web
+<ulink url="http://uffi.med-info.com"><citetitle>home</citetitle></ulink>.
+You also need to have a copy of &defsystem;. If you need a copy of
+&defsystem;, it is included in the 
+  <ulink
+      url="http://www.sourceforge.net/projects/clocc">
+      <citetitle>CLOCC</citetitle></ulink> package. You can download
+the file <filename>defsystem.lisp</filename> from the CVS 
+<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/clocc/clocc/src/defsystem-3.x/defsystem.lisp"><citetitle>tree</citetitle></ulink>.
+    </para>
+  </sect1>
+  <sect1>
+    <title>Installation</title>
+    <para>
+      After downloading and installing &defsystem;, simply
+      <function>push</function> the
+      directory containing &uffi; into
+      <varname>mk:*central-registry*</varname> variable. Whenever you
+want to load the &uffi; package, use the function
+      <computeroutput>(mk:load-system :uffi)</computeroutput>.
     </para>
   </sect1>
 </appendix>

diff --git a/doc/intro.sgml b/doc/intro.sgml
index d432b9f218ff03fa9f237913cd45e99046046c56..23b4c7c8c27f51f02d7a6ab5afabc62e53be6f1d 100644 (file)
--- a/doc/intro.sgml
+++ b/doc/intro.sgml
@@ -45,20 +45,16 @@
     </itemizedlist>
   </sect1>
 
-  <sect1>
-    <title>Installation</title>
-    <para>
-      Installation is fairly simple. The main requirement is that you
-      have a copy of &defsystem;. You can download the latest version
-      of &defsystem; from the <ulink
-      url="http://www.sourceforge.net/projects/clocc">
-      <citetitle>CLOCC</citetitle></ulink>
-      CVS tree. After installing &defsystem;, simply
-      <function>push</function> the
-      directory containing &uffi; into
-      <varname>mk:*central-registry*</varname>. Whenever you
-want to load the &uffi; package, use the function
-      <computeroutput>(mk:load-system :uffi)</computeroutput>.
-    </para>
-  </sect1>
+    <sect1>
+      <title>Design Overview</title>
+      <para>
+       &uffi; was designed as a cross-implementation compatible 
+       <emphasis>Foreign Function Interface</emphasis>. Necessarily,
+       only a common subset of functionality can be
+       provided. Likewise, not every optimization for that a specific
+       implementation provides can be supported. Wherever possible,
+       though, implementation-specific optimizations are invoked.
+      </para> 
+    </sect1>
+
 </chapter>

diff --git a/doc/ref.sgml b/doc/ref.sgml
index aaf1feac499abe4fde3a6c841017de27e7a7328e..252bdc53c8894657887f6150a7155758dedb99de 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -1,51 +1,86 @@
 <!-- -*- DocBook -*- -->
 
   
-  <chapter>
-    <title>Programming Reference</title>
+<reference>
+  <title>Declarations</title>
 
+  <partintro>
     <sect1>
-      <title>Design Overview</title>
-      <para>
-       &uffi; was designed as a cross-implementation compatible 
-       <emphasis>Foreign Function Interface</emphasis>. Necessarily,
-       only a common subset of functionality can be
-       provided. Likewise, not every optimization for that a specific
-       implementation provides can be supported. Wherever possible,
-       though, implementation-specific optimizations are invoked.
-      </para> 
-    </sect1>
-
-    <sect1>
-      <title>Declarations</title>
-      <sect2>
-       <title>Overview</title>
-       <para>Declarations are used to give the compiler optimizing
+      <title>Overview</title>
+      <para>Declarations are used to give the compiler optimizing
        information about foreign types. Currently, only &cmucl;
        supports declarations. On &acl; and &lw;, these expressions 
        declare the type generically as &t;
-       </para>
-      </sect2>
+      </para>
+    </sect1>
+  </partintro>
 
-      <sect2 id="def-type">
-       <title>def-type</title>
-       <para>
-         This is used wherever a &cl; <function>deftype</function>
-         expression can be placed. Used to declare types to
-the compiler for optimization. Currently, on &cmucl; takes advantage
-of this.       </para>
-       <para>
-         <programlisting>
-(uffi:def-type my-struct-def my-struct-foreign-type)
-         </programlisting>
+      <refentry id="def-type">
+       <refnamediv>
+         <refname>def-type</refname>
+       <refpurpose>Defines a Common Lisp type. 
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-type</function> <replaceable>name type</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A symbol naming the type</para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A form that is evaluated that specifies the &uffi; type.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>Defines a Common Lisp type based on a &uffi; type.
        </para>
-      </sect2>
-    </sect1>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-type char-ptr '(* :char))
+...
+(defun foo (ptr)
+  (declare (type char-ptr ptr))
+  ...
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Defines a new &cl; type.</para>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+  </reference>
 
-    <sect1>
-      <title>Primitive Types</title>
-      <sect2>
-       <title>Overview</title>
+
+  <reference>
+    <title>Primitive Types</title>
+    <partintro>
+      <title>Overview</title>
        <para>
          Primitive types have a single value, these include
          characters, numbers, and pointers. They are all symbols in
@@ -95,148 +130,1080 @@ The absence of a value. Used in generic pointers and in return types from functi
            <para><constant>*</constant> - Used to declare a pointer to an object</para>
          </listitem>
        </itemizedlist>
-      </sect2>
-      <sect2>
-       <title>def-constant</title>
+      </partintro>
+
+      <refentry id="def-constant">
+       <refnamediv>
+         <refname>def-constant</refname>
+       <refpurpose>Binds a symbol to a constant. 
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-constant</function> <replaceable>name value &amp;key export</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A symbol that will be bound to the value.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>value</parameter></term>
+           <listitem>
+             <para>An evaluated form that is bound the the name.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>export</parameter></term>
+           <listitem>
+             <para>When &t;, the name is exported from the current package. The default is &nil;</para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          This is a thin wrapper around
          <function>defconstant</function>. It evaluates at
-           compile-time and exports the symbol from the package.
-       </para>
-      </sect2>
-      <sect2>
-       <title>def-type</title>
-       <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>
-       <para>
-         A predicate testing if a pointer object is &null;
+           compile-time and optionally exports the symbol from the package.
        </para>
-      </sect2>
-    </sect1>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-constant pi2 (* 2 pi))
+(def-constant exported-pi2 (* 2 pi) :export t)
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Creates a new special variable..</para>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
 
-    <sect1>
-      <title>Aggregate Types</title>
-      <sect2>
-       <title>def-enum</title>
-       <para>
-         Declares a &c; enumeration. It generates constants for the
-         elements of the enumeration.
-       </para>
-      </sect2>
-      <sect2>
-       <title>def-struct</title>
-       <para>
-         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>
-       <para>
-         Accesses a slot value from a structure.
-       </para>
-      </sect2>
-      <sect2>
-       <title>get-slot-pointer</title>
-       <para>
-         This is similar to <function>get-slot-value</function>. It
-         is used when the value of a slot is a pointer type.
-       </para>
-      </sect2>
-      <sect2>
-       <title>def-array</title>
-       <para>
-         Defines an array.
+    <refentry id="def-foreign-type">
+       <refnamediv>
+         <refname>def-foreign-type</refname>
+       <refpurpose>Defines a new foreign type. 
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsect1>
+       <title>Syntax</title>
+<synopsis>
+         <function>def-foreign-type</function> <replaceable>name type</replaceable>
+</synopsis>
+      </refsect1>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A symbol naming the new foreign type.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>value</parameter></term>
+           <listitem>
+             <para>A form that is not evaluated that defines the new
+foreign type.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>Defines a new foreign type.
        </para>
-      </sect2>
-      <sect2>
-       <title>deref-array</title>
-       <para>
-         Accesses an element of an array.
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-foreign-type my-generic-pointer (* :void))
+(def-foreign-type a-double-float :double-float)
+(def-foreign-type char-ptr (* :char))
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Defines a new foreign type.
        </para>
-      </sect2>
-    </sect1>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
 
-    <sect1>
-      <title>Objects</title>
-      <sect2>
-       <title>Overview</title>
+    <refentry id="null-char-p">
+       <refnamediv>
+         <refname>null-char-p</refname>
+       <refpurpose>Tests a character for &null; value.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsect1>
+       <title>Syntax</title>
+<synopsis>
+         <function>null-char-p</function> <replaceable>char</replaceable> => <returnvalue>is-null</returnvalue>
+</synopsis>
+      </refsect1>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>char</parameter></term>
+           <listitem>
+             <para>A character or integer.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>is-null</parameter></term>
+           <listitem>
+             <para>A boolean flag indicating if char is a &null; value.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
-         Objects are entities that can allocated and freed.
+         A predicate testing if a character or integer is &null;. This
+abstracts the difference in implementations where some return a 
+<computeroutput>character</computeroutput> and some return a 
+<computeroutput>integer</computeroutput> whence dereferencing a 
+<computeroutput>C</computeroutput> character pointer.
        </para>
-      </sect2>
-      <sect2>
-       <title>allocate-foreign-object</title>
-       <para>
-         Allocates an instance of a foreign object. It returns a pointer to the object.
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-array ca :char)
+(let ((fs (convert-to-foreign-string "ab")))
+   (values (null-char-p (deref-array fs 'ca 0))
+           (null-char-p (deref-array fs 'ca 2))))
+=> &nil;
+   &t;
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>None.
        </para>
-      </sect2>
-      <sect2>
-       <title>free-foreign-object</title>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+
+    <refentry id="ensure-char">
+      <refnamediv>
+       <refname>ensure-char</refname>
+       <refpurpose>Ensures value is a character.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>ensure-char</function> <replaceable>obj</replaceable> => <returnvalue>char</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>obj</parameter></term>
+           <listitem>
+             <para>A character or integer.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>char</parameter></term>
+           <listitem>
+             <para>A character value.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
-         Frees the memory used by a foreign object.
+         Enscapsulates the fact that some implementations return a character
+and others return an integer when dereferencing a character pointer.
        </para>
-      </sect2>
-      <sect2>
-       <title>pointer-address</title>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
        <para>
-         Returns the address as an integer of a pointer.
+<programlisting>
+(let ((fs (convert-to-foreign-string "a")))
+  (prog1 
+    (ensure-char (deref-pointer fs :char))
+    (free-foreign-object fs)))
+=> #\a
+</programlisting>
        </para>
-      </sect2>
-      <sect2>
-       <title>deref-pointer</title>
-       <para>
-         Returns the object to which a pointer points.
+      </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>Signals an error if <parameter>obj</parameter> is not
+an integer or character.</para>
+      </refsect1>
+    </refentry>
+</reference>
+
+<reference>
+      <title>Aggregate Types</title>
+    <partintro>
+      <title>Overview</title>
+      <para>
+       Aggregate types are comprised of one or more primitive types.
+      </para>
+</partintro>
+
+      <refentry id="def-enum">
+       <refnamediv>
+         <refname>def-enum</refname>
+       <refpurpose>Defines a &c; enumeration.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-enum</function> <replaceable>name fields &amp;key separator-string</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A symbol that names the enumeration.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>fields</parameter></term>
+           <listitem>
+             <para>A list of field defintions. Each definition can be
+a symbol or a list of two elements. Symbols get assigned a value of the
+current counter which starts at <computeroutput>0</computeroutput> and
+increments by <computeroutput>1</computeroutput> for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second
+position is the value to assign the the symbol. The current counter gets set
+to <computeroutput>1+</computeroutput> this value.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>separator-string</parameter></term>
+           <listitem>
+             <para>A string that governs the creation of constants. The
+default is <computeroutput>"#"</computeroutput>.</para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
+values are created by the <function>concatenation</function> of the
+enumeration name, separator-string, and field symbol. Also creates
+a foreign type with the name <parameter>name</parameter> of type
+<constant>:int</constant>.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-enum abc (:a :b :c)) 
+;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
+;; the foreign type "abc" to be :int
+
+(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
+;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
+;; the foreign type efoo to be :int
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Creates a :int foreign type, defines constants.</para>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+
+
+      <refentry id="def-struct">
+       <refnamediv>
+         <refname>def-struct</refname>
+       <refpurpose>Defines a &c; structure.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-struct</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 symbol that names the structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>fields</parameter></term>
+           <listitem>
+             <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         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>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-struct foo (a :unsigned-int) 
+                (b (* :char)) 
+                (c (:array :int 10)) 
+                (next :pointer-self))
+       </programlisting>
+      </refsect1>
+      <refsect1>
+       <title>Side Effects</title>
+       <para>Creates a foreign type.</para>
+      </refsect1>
+      <refsect1>
+       <title>Affected by</title>
+       <para>None.</para>
+      </refsect1>
+      <refsect1>
+       <title>Exceptional Situations</title>
+       <para>None.</para>
+      </refsect1>
+    </refentry>
+
+
+    <refentry id="get-slot-value">
+      <refnamediv>
+       <refname>def-slot-value</refname>
+       <refpurpose>Retrieves a value from a slot of a structure.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>obj</parameter></term>
+           <listitem>
+             <para>A pointer to foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A name of the foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>field</parameter></term>
+           <listitem>
+             <para>A name of the desired field in foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>value</returnvalue></term>
+           <listitem>
+             <para>The value of the field in the structure.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Accesses a slot value from a structure.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(get-slot-value foo-ptr 'foo-structure 'field-name)
+       </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="get-slot-pointer">
+      <refnamediv>
+       <refname>get-slot-pointer</refname>
+       <refpurpose>Retrieves a pointer from a slot of a structure.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>obj</parameter></term>
+           <listitem>
+             <para>A pointer to foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A name of the foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>field</parameter></term>
+           <listitem>
+             <para>A name of the desired field in foreign structure.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>pointer</returnvalue></term>
+           <listitem>
+             <para>The value of the field in the structure.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         This is similar to <function>get-slot-value</function>. It
+         is used when the value of a slot is a pointer type.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
+       </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-array">
+      <refnamediv>
+       <refname>def-array</refname>
+       <refpurpose>Defines a foreign array type.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-array</function> <replaceable>name type</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A name of the new foreign type.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>The foreign type of the array elements.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Defines a foreign array type.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-array byte-array :unsigned-char)
+       </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>
+
+
+    <refentry id="deref-array">
+      <refnamediv>
+       <refname>deref-array</refname>
+       <refpurpose>Deference an array.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>deref-array</function> <replaceable>array type positon</replaceable> => <returnvalue>value</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>array</parameter></term>
+           <listitem>
+             <para>A foreign array.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>The foreign type of the array.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>position</parameter></term>
+           <listitem>
+             <para>An integer specifying the position to retrieve from
+the array.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>value</returnvalue></term>
+           <listitem>
+             <para>The value stored in the position of the array.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Dereferences (retrieves) the value of an array element.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-array ca :char)
+(let ((fs (convert-to-foreign-string "ab")))
+   (values (null-char-p (deref-array fs 'ca 0))
+           (null-char-p (deref-array fs 'ca 2))))
+=> &nil;
+   &t;
+       </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>
+</reference>
+
+<reference>
+    <title>Objects</title>
+<partintro>
+<title>Overview</title>
+    <para>
+      Objects are entities that can allocated and freed.
+    </para>
+</partintro>
+
+
+    <refentry id="allocate-foreign-object">
+      <refnamediv>
+       <refname>allocate-foreign-object</refname>
+       <refpurpose>Allocates an instance of a foreign object.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>allocate-foreign-object</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A type of foreign object to allocate.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>ptr</returnvalue></term>
+           <listitem>
+             <para>A pointer to the foreign object.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Allocates an instance of a foreign object. It returns a pointer to the object.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-struct ab (a :int) (b :double))
+(allocate-foreign-object 'ab)
+=> #&lt;ptr&gt;
+       </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="free-foreign-object">
+      <refnamediv>
+       <refname>free-foreign-object</refname>
+       <refpurpose>Frees memory that was allocated for a foreign boject.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>free-foreign-object</function> <replaceable>ptr</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>ptr</parameter></term>
+           <listitem>
+             <para>A pointer to the allocated foreign object to free.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Frees the memory used by the allocation of a foreign object.
+       </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="pointer-address">
+      <refnamediv>
+       <refname>pointer-address</refname>
+       <refpurpose>Returns the address of a pointer.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>ptr</parameter></term>
+           <listitem>
+             <para>A pointer to a foreign object.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>address</parameter></term>
+           <listitem>
+             <para>An integer representing the pointer's address.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Returns the address as an integer of a pointer.
+       </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="deref-pointer">
+      <refnamediv>
+       <refname>deref-pointer</refname>
+       <refpurpose>Deferences a pointer.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>def-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>ptr</parameter></term>
+           <listitem>
+             <para>A pointer to a foreign object.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A foreign type of the object being pointed to.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>value</parameter></term>
+           <listitem>
+             <para>The value of the object where the pointer points.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+         Returns the object to which a pointer points.
+       </para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <para>
+<programlisting>
+(let ((fs (convert-to-foreign-string "a")))
+  (prog1 
+    (ensure-char (deref-pointer fs :char))
+    (free-foreign-object fs)))
+=> #\a
+</programlisting>
        </para>
-      </sect2>
-      <sect2>
-       <title>make-null-pointer</title>
+      </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="make-null-pointer">
+      <refnamediv>
+       <refname>make-null-pointer</refname>
+       <refpurpose>Create a &null; pointer.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>type</parameter></term>
+           <listitem>
+             <para>A type of object to which the pointer refers.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>ptr</parameter></term>
+           <listitem>
+             <para>The &null; pointer of type <parameter>type</parameter>.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Creates a &null; pointer of a specified type.
        </para>
-      </sect2>
-      <sect2>
-       <title>null-pointer-p</title>
+      </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="null-pointer-p">
+      <refnamediv>
+       <refname>null-pointer-p</refname>
+       <refpurpose>Tests a pointer for &null; value.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>ptr</parameter></term>
+           <listitem>
+             <para>A foreign object pointer.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>is-null</returnvalue></term>
+           <listitem>
+             <para>The boolean flag.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          A predicate testing if a pointer is has a &null; value.
        </para>
-      </sect2>
-      <sect2>
-       <title>+null-cstring-pointer+</title>
+      </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="null-cstring-pointer">
+      <refnamediv>
+       <refname>+null-cstring-pointer+</refname>
+       <refpurpose>A constant &null; cstring pointer.
+       </refpurpose>
+       <refclass>Constant</refclass>
+      </refnamediv>
+      <refsect1>
+       <title>Description</title>
        <para>
-         A constant &null; character pointer.
+         A &null; cstring pointer. This can be used for testing
+if a cstring returned by a function is &null;.
        </para>
-      </sect2>
-    </sect1>
+      </refsect1>
+    </refentry>
 
-    <sect1>
+</reference>
+
+    <reference>
       <title>Strings</title>
-      <sect2>
-       <title>Overview</title>
-       <para>
+<partintro>
+<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,
@@ -244,37 +1211,214 @@ 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>
+</partintro>
+
+    <refentry id="convert-from-cstring">
+      <refnamediv>
+       <refname>convert-from-cstring</refname>
+       <refpurpose>Converts a cstring to a Lisp string.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>cstring</parameter></term>
+           <listitem>
+             <para>A cstring.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>string</returnvalue></term>
+           <listitem>
+             <para>A Lisp string.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
-         Converts a Lisp string to a <varname>cstring</varname>.
+         Converts a Lisp string to a <constant>cstring</constant>. This is
+most often used when processing the results of a foreign function
+that returns a cstring.
        </para>
-      </sect2>
-      <sect2>
-       <title>convert-to-cstring</title>
+      </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="convert-to-cstring">
+      <refnamediv>
+       <refname>convert-to-cstring</refname>
+       <refpurpose>Converts a Lisp string to a cstring.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>string</parameter></term>
+           <listitem>
+             <para>A Lisp string.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>cstring</returnvalue></term>
+           <listitem>
+             <para>A cstring.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Converts a Lisp string to a
          <varname>cstring</varname>. The
          <varname>cstring</varname> should be freed with
          <function>free-cstring</function>.
        </para>
-      </sect2>
-      <sect2>
-       <title>free-cstring</title>
+      </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="free-cstring">
+      <refnamediv>
+       <refname>free-cstring</refname>
+       <refpurpose>Free memory used by cstring.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>free-cstring</function> <replaceable>cstring</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>cstring</parameter></term>
+           <listitem>
+             <para>A cstring.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Frees any memory possibly allocated by
          <function>convert-to-cstring</function>.
        </para>
-      </sect2>
-      <sect2>
-       <title>with-cstring</title>
+      </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="with-cstring">
+      <refnamediv>
+       <refname>with-cstring</refname>
+       <refpurpose>Binds a newly created cstring.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>cstring</parameter></term>
+           <listitem>
+             <para>A symbol naming the cstring to be created.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>string</parameter></term>
+           <listitem>
+             <para>A Lisp string that will be translated to a cstring.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>body</parameter></term>
+           <listitem>
+             <para>The body of where the cstring will be bound.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
        </para>
-       <sect3>
-         <title>Examples</title>
-         <para>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <para>
            <programlisting>
 (def-function ("getenv" c-getenv) 
    ((name :cstring))
@@ -285,35 +1429,216 @@ always need to have memory for them.
   (check-type key string)
   (with-cstring (key-cstring key)
     (convert-from-cstring (c-getenv key-cstring))))
-         </programlisting>
-       </para>
-      </sect3>
-      </sect2>
-      <sect2>
-       <title>convert-from-foreign-string</title>
+           </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="convert-from-foreign-string">
+      <refnamediv>
+       <refname>convert-from-foreign-string</refname>
+       <refpurpose>Converts a foreign string into a Lisp string.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>foreign-string</parameter></term>
+           <listitem>
+             <para>A foreign string.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>length</parameter></term>
+           <listitem>
+             <para>The length of the foreign string to
+convert. The default is the length of the string until a &null;
+character is reached.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>null-terminated-p</parameter></term>
+           <listitem>
+             <para>A boolean flag with a default value of &t; When true,
+the string is converted until the first &null; character is reached.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>string</returnvalue></term>
+           <listitem>
+             <para>A Lisp string.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
-         Returns a Lisp string from a foreign string. Has parameters
-         to handle ASCII versus binary strings.
+         Returns a Lisp string from a foreign string. 
+Can translated ASCII and binary strings.
        </para>
-      </sect2>
-      <sect2>
-       <title>convert-to-foreign-string</title>
+      </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="convert-to-foreign-string">
+      <refnamediv>
+       <refname>convert-to-foreign-string</refname>
+       <refpurpose>Converts a Lisp string to a foreign string.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>string</parameter></term>
+           <listitem>
+             <para>A Lisp string.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>foreign-string</returnvalue></term>
+           <listitem>
+             <para>A foreign string.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Converts a Lisp string to a foreign string. Memory should be
          freed with <function>free-foreign-object</function>.
        </para>
-      </sect2>
-      <sect2>
-       <title>allocate-foreign-string</title>
+      </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="allocate-foreign-string">
+      <refnamediv>
+       <refname>allocate-foreign-string</refname>
+       <refpurpose>Allocates space for a foreign string.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
+       </synopsis>
+      </refsynopsisdiv>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>size</parameter></term>
+           <listitem>
+             <para>The size of the space to be allocated in bytes.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>unsigned</parameter></term>
+           <listitem>
+             <para>A boolean flag with a default value of &nil;. When true,
+marks the pointer as an <constant>:unsigned-char</constant>.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>foreign-string</returnvalue></term>
+           <listitem>
+             <para>A foreign string which has undefined contents.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
        <para>
          Allocates space for a foreign string. Memory should
          be freed with <function>free-foreign-object</function>.
        </para>
-      </sect2>
-    </sect1>
+      </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>
+      <title>Functions &amp; Libraries</title>
 
-    <sect1>
-      <title>Functions</title>
       <refentry id="def-function">
        <refnamediv>
          <refname>def-function</refname>
@@ -387,10 +1712,7 @@ foreign function.
        <para>None.</para>
       </refsect1>
     </refentry>
-    </sect1>
 
-    <sect1>
-      <title>Libraries</title>
       <refentry id="load-foreign-library">
        <refnamediv>
          <refname>load-foreign-library</refname>
@@ -473,7 +1795,7 @@ a session.
        <para>None.</para>
       </refsect1>
     </refentry>
-  </sect1>
-  </chapter>
+
+</reference>
 
 

diff --git a/src/primitives.cl b/src/primitives.cl
index ee529806dcd8a55c3f981be65c9d2a4337936ba0..294dcdc9b784a35f6efe09bab73cdd790f217cc1 100644 (file)
--- a/src/primitives.cl
+++ b/src/primitives.cl
@@ -7,7 +7,7 @@
 ;;;; Programmer:    Kevin M. Rosenberg
 ;;;; Date Started:  Feb 2002
 ;;;;
-;;;; $Id: primitives.cl,v 1.5 2002/03/14 21:32:23 kevin Exp $
+;;;; $Id: primitives.cl,v 1.6 2002/03/15 11:38:13 kevin Exp $
 ;;;;
 ;;;; This file, part of UFFI, is Copyright (c) 2002 by Kevin M. Rosenberg
 ;;;;
@@ -19,11 +19,11 @@
 (declaim (optimize (debug 3) (speed 3) (safety 1) (compilation-speed 0)))
 (in-package :uffi)
 
-(defmacro def-constant (name value)
+(defmacro def-constant (name value &key (export nil))
   "Macro to define a constant and to export it"
   `(eval-when (:compile-toplevel :load-toplevel :execute)
      (defconstant ,name ,value)
-     (export ',name)))
+     ,(if export (list 'export `(quote ,name)) (values))))
 
 (defmacro def-type (name type)
   "Generates a (deftype) statement for CL. Currently, only CMUCL
@@ -42,6 +42,12 @@ supports takes advantage of this optimization."
       t
     nil))
 
+(defmacro ensure-char (val)
+  `(etypecase ,val
+     (integer
+      (code-char ,val))
+     (character
+      ,val)))
       
 (defmacro def-foreign-type (name type)
   #+lispworks `(fli:define-c-typedef ,name ,(convert-from-uffi-type type :type))