doc/ref.sgml

   1 <!-- -*- DocBook -*- -->
   2
   3
   4   <chapter>
   5     <title>Programming Reference</title>
   6
   7     <sect1>
   8       <title>Design Overview</title>
   9       <para>
  10         &uffi; was designed as a cross-implementation compatible
  11         <emphasis>Foreign Function Interface</emphasis>. Necessarily,
  12         only a common subset of functionality can be
  13         provided. Likewise, not every optimization for that a specific
  14         implementation provides can be supported. Wherever possible,
  15         though, implementation-specific optimizations are invoked.
  16       </para>
  17     </sect1>
  18
  19     <sect1>
  20       <title>Declarations</title>
  21       <sect2>
  22         <title>Overview</title>
  23         <para>Declarations are used to give the compiler optimizing
  24         information about foreign types. Currently, only &cmucl;
  25         supports declarations. On &acl; and &lw;, these expressions
  26         declare the type generically as &t;
  27         </para>
  28       </sect2>
  29
  30       <sect2 id="uffi-declare">
  31         <title>uffi-declare</title>
  32         <para>
  33           This is used wherever a <function>declare</function>
  34           expression can be placed. For example:
  35         </para>
  36         <para>
  37           <programlisting>
  38 (let ((my-structure (uffi:allocate-foreign-object 'a-struct)))
  39    (uffi:uffi-declare a-struct my-structure))
  40           </programlisting>
  41         </para>
  42       </sect2>
  43
  44       <sect2 id="slot-type">
  45         <title>slot-type</title>
  46         <para>
  47           This is used inside of <function>defclass</function> and
  48           <function>defstruct</function> expressions to set the type
  49           for a field. Because the type identifier is not evaluated in
  50           &cl;, the expression must be backquoted for effect. For
  51           example:
  52         </para>
  53         <para>
  54           <programlisting>
  55 (eval
  56   `(defclass a-class ()
  57      ((char-ptr :type ,(uffi:slot-type (* :char))))))
  58           </programlisting>
  59         </para>
  60       </sect2>
  61     </sect1>
  62
  63     <sect1>
  64       <title>Immediate Types</title>
  65       <sect2>
  66         <title>def-constant</title>
  67         <para>
  68           This is a thin wrapper around
  69           <function>defconstant</function>. It also exports the symbol
  70           from the package.
  71         </para>
  72       </sect2>
  73       <sect2>
  74         <title>def-type</title>
  75         <para>
  76           This is the main function for creating new types.
  77         </para>
  78       </sect2>
  79       <sect2>
  80         <title>null-char-p</title>
  81         <para>
  82           A predicate testing if a pointer object is &null;
  83         </para>
  84       </sect2>
  85     </sect1>
  86
  87     <sect1>
  88       <title>Aggregate Types</title>
  89       <sect2>
  90         <title>def-enum</title>
  91         <para>
  92           Declares a &c; enumeration. It generates constants for the
  93           elements of the enumeration.
  94         </para>
  95       </sect2>
  96       <sect2>
  97         <title>def-struct</title>
  98         <para>
  99           Declares a structure.
 100         </para>
 101       </sect2>
 102       <sect2 id="get-slot-value">
 103         <title>get-slot-value</title>
 104         <para>
 105           Accesses a slot value from a structure.
 106         </para>
 107       </sect2>
 108       <sect2>
 109         <title>get-slot-pointer</title>
 110         <para>
 111           This is similar to <function>get-slot-value</function>. It
 112           is used when the value of a slot is a pointer type.
 113         </para>
 114       </sect2>
 115       <sect2>
 116         <title>def-array</title>
 117         <para>
 118           Defines an array.
 119         </para>
 120       </sect2>
 121       <sect2>
 122         <title>deref-array</title>
 123         <para>
 124           Accesses an element of an array.
 125         </para>
 126       </sect2>
 127     </sect1>
 128
 129     <sect1>
 130       <title>Objects</title>
 131       <sect2>
 132         <title>allocate-foreign-object</title>
 133         <para>
 134           Allocates an instance of a foreign object.
 135         </para>
 136       </sect2>
 137       <sect2>
 138         <title>free-foreign-object</title>
 139         <para>
 140           Frees the memory used by a foreign object.
 141         </para>
 142       </sect2>
 143       <sect2>
 144         <title>pointer-address</title>
 145         <para>
 146           Returns the address as an integer of a pointer.
 147         </para>
 148       </sect2>
 149       <sect2>
 150         <title>deref-pointer</title>
 151         <para>
 152           Returns the object to which a pointer points.
 153         </para>
 154       </sect2>
 155       <sect2>
 156         <title>make-null-pointer</title>
 157         <para>
 158           Creates a &null; pointer of a specified type.
 159         </para>
 160       </sect2>
 161       <sect2>
 162         <title>null-pointer-p</title>
 163         <para>
 164           A predicate testing if a pointer is has a &null; value.
 165         </para>
 166       </sect2>
 167       <sect2>
 168         <title>+null-c-string-ptr+</title>
 169         <para>
 170           A constant returning a &null; character pointer;
 171         </para>
 172       </sect2>
 173     </sect1>
 174
 175     <sect1>
 176       <title>Strings</title>
 177       <sect2>
 178         <title>convert-from-c-string</title>
 179         <para>
 180           Converts a Lisp string to a <varname>c-string</varname>.
 181         </para>
 182       </sect2>
 183       <sect2>
 184         <title>convert-to-c-string</title>
 185         <para>
 186           Converts a Lisp string to a
 187           <varname>c-string</varname>. These
 188           <varname>c-string's</varname> should be freed with
 189           <function>free-c-string</function>.
 190         </para>
 191       </sect2>
 192       <sect2>
 193         <title>free-c-string</title>
 194         <para>
 195           Frees any memory possibly allocated by
 196           <function>convert-to-c-string</function>.
 197         </para>
 198       </sect2>
 199       <sect2>
 200         <title>with-c-string</title>
 201         <para>
 202           Binds a lexical variable to a newly allocated <varname>c-string</varname>. Automatically frees <varname>c-string</varname>.
 203         </para>
 204       </sect2>
 205       <sect2>
 206         <title>covert-from-foreign-string</title>
 207         <para>
 208           Returns a Lisp string from a foreign string. Has parameters
 209           to handle ASCII versus binary strings.
 210         </para>
 211       </sect2>
 212       <sect2>
 213         <title>convert-to-foreign-string</title>
 214         <para>
 215           Converts a Lisp string to a foreign string. Memory should be
 216           freed with <function>free-foreign-object</function>.
 217         </para>
 218       </sect2>
 219       <sect2>
 220         <title>allocate-foreign-string</title>
 221         <para>
 222           Allocates space for a foreign string. Memory should
 223           be freed with <function>free-foreign-object</function>.
 224         </para>
 225       </sect2>
 226     </sect1>
 227
 228     <sect1>
 229       <title>Routine</title>
 230       <sect2>
 231         <title>def-routine</title>
 232         <para>
 233           This macro generates a &c; routine definition.
 234         </para>
 235       </sect2>
 236     </sect1>
 237
 238     <sect1>
 239       <title>Libraries</title>
 240       <sect2>
 241         <title>load-foreign-library</title>
 242         <para>
 243           This function loads foreign libraries. It has checks to
 244           ensure that a library is loaded only once during a session.
 245         </para>
 246       </sect2>
 247     </sect1>
 248
 249   </chapter>
 250
 251