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>Overview</title>
  67         <para>
  68           Immediate types have a single value, these include
  69           characters, numbers, and pointers. They are all symbols in
  70           the keyword package.
  71         </para>
  72         <itemizedlist>
  73           <listitem>
  74             <para><constant>:byte</constant> - Unsigned 8-bit</para>
  75           </listitem>
  76           <listitem>
  77             <para><constant>:char</constant> - Signed 8-bits</para>
  78           </listitem>
  79           <listitem>
  80             <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
  81           </listitem>
  82           <listitem>
  83             <para><constant>:short</constant> - Signed 16-bits</para>
  84           </listitem>
  85           <listitem>
  86             <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
  87           </listitem>
  88           <listitem>
  89             <para><constant>:int</constant> - Signed 32-bits</para>
  90           </listitem>
  91           <listitem>
  92             <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
  93           </listitem>
  94           <listitem>
  95             <para><constant>:long</constant> - Signed 32-bits</para>
  96           </listitem>
  97           <listitem>
  98             <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
  99           </listitem>
 100           <listitem>
 101             <para><constant>:single-float</constant> - 32-bit floating point</para>
 102           </listitem>
 103           <listitem>
 104             <para><constant>:double-float</constant> - 64-bit floating point</para>
 105           </listitem>
 106           <listitem>
 107             <para>
 108               <constant>
 109                 :cstring
 110               </constant>
 111               - A null-terminated string used for passing and returning with a function.
 112               </para>
 113           </listitem>
 114           <listitem>
 115             <para>
 116               <constant>
 117                 :void
 118               </constant>
 119               - An absence of a value. Used in generic pointers and in
 120               return types from functions.</para>
 121           </listitem>
 122           <listitem>
 123             <para><constant>*</constant> - Used to declare a pointer to an object</para>
 124           </listitem>
 125         </itemizedlist>
 126       </sect2>
 127       <sect2>
 128         <title>def-constant</title>
 129         <para>
 130           This is a thin wrapper around
 131           <function>defconstant</function>. It evaluates at
 132             compile-time and exports the symbol from the package.
 133         </para>
 134       </sect2>
 135       <sect2>
 136         <title>def-type</title>
 137         <para>
 138           This is the main function for creating new types.
 139         </para>
 140         <sect3>
 141           <title>Examples</title>
 142           <para>
 143             <programlisting>
 144 (def-type my-generic-pointer (* :void))
 145 (def-type a-double-float :double-float)
 146 (def-type char-ptr (* :char))
 147             </programlisting>
 148           </para>
 149         </sect3>
 150       </sect2>
 151       <sect2>
 152         <title>null-char-p</title>
 153         <para>
 154           A predicate testing if a pointer object is &null;
 155         </para>
 156       </sect2>
 157     </sect1>
 158
 159     <sect1>
 160       <title>Aggregate Types</title>
 161       <sect2>
 162         <title>def-enum</title>
 163         <para>
 164           Declares a &c; enumeration. It generates constants for the
 165           elements of the enumeration.
 166         </para>
 167       </sect2>
 168       <sect2>
 169         <title>def-struct</title>
 170         <para>
 171           Declares a structure. A special type is available as a slot in the field. It is
 172           a pointer that points to an instance of the parent structure. It's type is
 173           <constant>:pointer-self</constant>.
 174         </para>
 175         <sect3>
 176           <title>Examples</title>
 177           <para>
 178             <programlisting>
 179 (def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
 180             </programlisting>
 181           </para>
 182         </sect3>
 183       </sect2>
 184       <sect2 id="get-slot-value">
 185         <title>get-slot-value</title>
 186         <para>
 187           Accesses a slot value from a structure.
 188         </para>
 189       </sect2>
 190       <sect2>
 191         <title>get-slot-pointer</title>
 192         <para>
 193           This is similar to <function>get-slot-value</function>. It
 194           is used when the value of a slot is a pointer type.
 195         </para>
 196       </sect2>
 197       <sect2>
 198         <title>def-array</title>
 199         <para>
 200           Defines an array.
 201         </para>
 202       </sect2>
 203       <sect2>
 204         <title>deref-array</title>
 205         <para>
 206           Accesses an element of an array.
 207         </para>
 208       </sect2>
 209     </sect1>
 210
 211     <sect1>
 212       <title>Objects</title>
 213       <sect2>
 214         <title>allocate-foreign-object</title>
 215         <para>
 216           Allocates an instance of a foreign object. It returns a pointer to the object.
 217         </para>
 218       </sect2>
 219       <sect2>
 220         <title>free-foreign-object</title>
 221         <para>
 222           Frees the memory used by a foreign object.
 223         </para>
 224       </sect2>
 225       <sect2>
 226         <title>pointer-address</title>
 227         <para>
 228           Returns the address as an integer of a pointer.
 229         </para>
 230       </sect2>
 231       <sect2>
 232         <title>deref-pointer</title>
 233         <para>
 234           Returns the object to which a pointer points.
 235         </para>
 236       </sect2>
 237       <sect2>
 238         <title>make-null-pointer</title>
 239         <para>
 240           Creates a &null; pointer of a specified type.
 241         </para>
 242       </sect2>
 243       <sect2>
 244         <title>null-pointer-p</title>
 245         <para>
 246           A predicate testing if a pointer is has a &null; value.
 247         </para>
 248       </sect2>
 249       <sect2>
 250         <title>+null-cstring-pointer+</title>
 251         <para>
 252           A constant &null; character pointer.
 253         </para>
 254       </sect2>
 255     </sect1>
 256
 257     <sect1>
 258       <title>Strings</title>
 259       <sect2>
 260         <title>Overview</title>
 261         <para>
 262           &uffi; has functions to two types of <varname>C</varname>-compatible
 263           strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
 264 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
 265 may not convert these to a foreign type for efficiency sake. Thus, it is not
 266 possible to "allocate" a cstring. In contrast, foreign strings
 267 always need to have memory for them.
 268         </para>
 269       </sect2>
 270       <sect2>
 271         <title>convert-from-cstring</title>
 272         <para>
 273           Converts a Lisp string to a <varname>cstring</varname>.
 274         </para>
 275       </sect2>
 276       <sect2>
 277         <title>convert-to-cstring</title>
 278         <para>
 279           Converts a Lisp string to a
 280           <varname>cstring</varname>. These
 281           <varname>cstring's</varname> should be freed with
 282           <function>free-cstring</function>.
 283         </para>
 284       </sect2>
 285       <sect2>
 286         <title>free-cstring</title>
 287         <para>
 288           Frees any memory possibly allocated by
 289           <function>convert-to-cstring</function>.
 290         </para>
 291       </sect2>
 292       <sect2>
 293         <title>with-cstring</title>
 294         <para>
 295           Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
 296         </para>
 297       </sect2>
 298       <sect2>
 299         <title>covert-from-foreign-string</title>
 300         <para>
 301           Returns a Lisp string from a foreign string. Has parameters
 302           to handle ASCII versus binary strings.
 303         </para>
 304       </sect2>
 305       <sect2>
 306         <title>convert-to-foreign-string</title>
 307         <para>
 308           Converts a Lisp string to a foreign string. Memory should be
 309           freed with <function>free-foreign-object</function>.
 310         </para>
 311       </sect2>
 312       <sect2>
 313         <title>allocate-foreign-string</title>
 314         <para>
 315           Allocates space for a foreign string. Memory should
 316           be freed with <function>free-foreign-object</function>.
 317         </para>
 318       </sect2>
 319     </sect1>
 320
 321     <sect1>
 322       <title>Routine</title>
 323       <sect2>
 324         <title>def-function</title>
 325         <para>
 326           This macro generates a &c; function definition.
 327         </para>
 328       </sect2>
 329     </sect1>
 330
 331     <sect1>
 332       <title>Libraries</title>
 333       <sect2>
 334         <title>load-foreign-library</title>
 335         <para>
 336           This function loads foreign libraries. It has checks to
 337           ensure that a library is loaded only once during a session.
 338         </para>
 339       </sect2>
 340     </sect1>
 341
 342   </chapter>
 343
 344