r5495: *** empty log message ***

[uffi.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 510dd4ca3a64351ce68ad4c22e25e95db7680d9a..cbf5336613c678cbf354dee67f10c2463dac9c63 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -759,7 +759,7 @@ the array.
       <refsect1>
        <title>Examples</title>
        <programlisting>
-(def-array ca :char)
+(def-array-pointer 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))))
@@ -767,6 +767,14 @@ the array.
    &t;
        </programlisting>
       </refsect1>
+      <refsect1>
+       <title>Notes</title>
+        <para>
+  The TYPE argument is ignored for CL implementations other than
+  AllegroCL. If you want to cast a pointer to another type use
+  WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
+        </para>
+      </refsect1>
       <refsect1>
        <title>Side Effects</title>
        <para>None.</para>
@@ -1216,6 +1224,14 @@ much better with static allocation.
 </programlisting>
        </para>
       </refsect1>
+      <refsect1>
+       <title>Notes</title>
+        <para>
+  The TYPE argument is ignored for CL implementations other than
+  AllegroCL. If you want to cast a pointer to another type use
+  WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
+        </para>
+      </refsect1>
       <refsect1>
        <title>Side Effects</title>
        <para>None.</para>
@@ -1266,8 +1282,9 @@ a character.
       <refsect1>
        <title>Description</title>
        <para>
-         Ensures that an object obtained by dereferencing a 
-<constant>:char</constant> pointer is a character.
+         Ensures that an objects obtained by dereferencing  
+<constant>:char</constant> and <constant>:unsigned-char</constant>
+pointers are a lisp character.
        </para>
       </refsect1>
       <refsect1>
@@ -1488,6 +1505,77 @@ if a cstring returned by a function is &null;.
       </refsect1>
     </refentry>
 
+    <refentry id="with-cast-pointer">
+      <refnamediv>
+       <refname>with-cast-pointer</refname>
+       <refpurpose>Wraps a body of code with a pointer cast to a new type.
+       </refpurpose>
+       <refclass>Macro</refclass>
+      </refnamediv>
+      <refsynopsisdiv>
+       <title>Syntax</title>
+       <synopsis>
+         <function>with-cast-pointer</function> <replaceable>binding-name ptr type &amp; body body</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><returnvalue>value</returnvalue></term>
+           <listitem>
+             <para>The value of the object where the pointer points.
+             </para>
+           </listitem>
+         </varlistentry>
+       </variablelist>
+      </refsect1>
+      <refsect1>
+       <title>Description</title>
+       <para>
+  Executes BODY with POINTER casted to be a pointer to type TYPE. If
+  BINDING-NAME is provided the casted pointer will be bound to this
+  name during the execution of BODY. If BINDING-NAME is not provided
+  POINTER must be a name bound to the pointer which should be
+  casted. This name will be bound to the casted pointer during the
+  execution of BODY.
+
+  This is a no-op in AllegroCL but will wrap BODY in a LET form if
+  BINDING-NAME is provided.
+
+  This macro is meant to be used in conjunction with DEREF-POINTER or
+  DEREF-ARRAY. In Allegro CL the "cast" will actually take place in
+  DEREF-POINTER or DEREF-ARRAY.
+       </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>
+
 </reference>
 
     <reference>
@@ -2074,7 +2162,7 @@ foreign function. If <constant>:void</constant> indicates module does not return
       <refsect1>
        <title>Syntax</title>
 <synopsis>
-         <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
+         <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries force-load</replaceable> => <returnvalue>success</returnvalue>
 </synopsis>
       </refsect1>
       <refsect1>
@@ -2105,6 +2193,13 @@ link the foreign library. (Required by CMUCL)
              </para>
            </listitem>
          </varlistentry>
+         <varlistentry>
+           <term><parameter>force-load</parameter></term>
+           <listitem>
+             <para>Forces the loading of the library if it has been previously loaded. 
+             </para>
+           </listitem>
+         </varlistentry>
          <varlistentry>
            <term><returnvalue>success</returnvalue></term>
            <listitem>
@@ -2120,7 +2215,7 @@ otherwise &nil;.
        <title>Description</title>
        <para>Loads a foreign library. Applies a module name to functions
 within the library. Ensures that a library is only loaded once during
-a session.
+a session. A library can be reloaded by using the <symbol>:force-load</symbol> key.
        </para>
       </refsect1>
       <refsect1>