r1538: *** empty log message ***

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 6b794780a597b65a281d9797d9656b44053be9bc..103363a2a6624cd62b2fd5e3d8ec1c340a7d8ed5 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -70,9 +70,6 @@
          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>
@@ -98,26 +95,19 @@
            <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
          </listitem>
          <listitem>
-           <para><constant>:single-float</constant> - 32-bit floating point</para>
+           <para><constant>:float</constant> - 32-bit floating point</para>
          </listitem>
          <listitem>
-           <para><constant>:double-float</constant> - 64-bit floating point</para>
+           <para><constant>:double</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>
+           <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>
+           <para><constant>:void</constant> - 
+The 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>
@@ -210,6 +200,12 @@
 
     <sect1>
       <title>Objects</title>
+      <sect2>
+       <title>Overview</title>
+       <para>
+         Objects are entities that can allocated and freed.
+       </para>
+      </sect2>
       <sect2>
        <title>allocate-foreign-object</title>
        <para>
@@ -277,8 +273,8 @@ always need to have memory for them.
        <title>convert-to-cstring</title>
        <para>
          Converts a Lisp string to a
-         <varname>cstring</varname>. These
-         <varname>cstring's</varname> should be freed with
+         <varname>cstring</varname>. The
+         <varname>cstring</varname> should be freed with
          <function>free-cstring</function>.
        </para>
       </sect2>
@@ -294,6 +290,22 @@ always need to have memory for them.
        <para>
          Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
        </para>
+       <sect3>
+         <title>Examples</title>
+         <para>
+           <programlisting>
+(def-function ("getenv" c-getenv) 
+   ((name :cstring))
+   :returning :cstring)
+
+(defun getenv (key)
+  "Returns an environment variable, or NIL if it does not exist"
+  (check-type key string)
+  (with-cstring (key-cstring key)
+    (convert-from-cstring (c-getenv key-cstring))))
+         </programlisting>
+       </para>
+      </sect3>
       </sect2>
       <sect2>
        <title>covert-from-foreign-string</title>
@@ -320,12 +332,79 @@ always need to have memory for them.
 
     <sect1>
       <title>Functions</title>
-      <sect2>
-       <title>def-function</title>
-       <para>
-         This macro generates a &c; function definition.
+      <refentry id="def-function">
+       <refnamediv>
+         <refname>def-function</refname>
+       <refpurpose>Declares a function. 
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsect1>
+       <title>Syntax</title>
+<synopsis>
+         <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
+</synopsis>
+      </refsect1>
+      <refsect1>
+       <title>Arguments and Values</title>
+       <variablelist>
+         <varlistentry>
+           <term><parameter>name</parameter></term>
+           <listitem>
+             <para>A string or list specificying the function name. If it is a string, that names the foreign function. 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 function name and the second it is a symbol stating the Lisp name.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>args</parameter></term>
+           <listitem>
+             <para>A list of argument declarations. Use &nil; to specify no arguments.
+             </para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><parameter>module</parameter></term>
+           <listitem>
+             <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
+           </listitem>
+         </varlistentry>
+         <varlistentry>
+           <term><returnvalue>returning</returnvalue></term>
+           <listitem>
+             <para>A declaration specifying the result type of the
+foreign function.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>Declares a foreign function.
        </para>
-      </sect2>
+      </refsect1>
+      <refsect1>
+       <title>Examples</title>
+       <programlisting>
+(def-function "gethostname" 
+  ((name :cstring)
+   (len :int))
+  :returning :int)
+       </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>
     </sect1>
 
     <sect1>