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>:char</constant> - Signed 8-bits</para>
  75           </listitem>
  76           <listitem>
  77             <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
  78           </listitem>
  79           <listitem>
  80             <para><constant>:short</constant> - Signed 16-bits</para>
  81           </listitem>
  82           <listitem>
  83             <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
  84           </listitem>
  85           <listitem>
  86             <para><constant>:int</constant> - Signed 32-bits</para>
  87           </listitem>
  88           <listitem>
  89             <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
  90           </listitem>
  91           <listitem>
  92             <para><constant>:long</constant> - Signed 32-bits</para>
  93           </listitem>
  94           <listitem>
  95             <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
  96           </listitem>
  97           <listitem>
  98             <para><constant>:float</constant> - 32-bit floating point</para>
  99           </listitem>
 100           <listitem>
 101             <para><constant>:double</constant> - 64-bit floating point</para>
 102           </listitem>
 103           <listitem>
 104             <para><constant>:cstring</constant> -
 105 A null-terminated string used for passing and returning with a function.
 106             </para>
 107           </listitem>
 108           <listitem>
 109             <para><constant>:void</constant> -
 110 The absence of a value. Used in generic pointers and in return types from functions.</para>
 111           </listitem>
 112           <listitem>
 113             <para><constant>*</constant> - Used to declare a pointer to an object</para>
 114           </listitem>
 115         </itemizedlist>
 116       </sect2>
 117       <sect2>
 118         <title>def-constant</title>
 119         <para>
 120           This is a thin wrapper around
 121           <function>defconstant</function>. It evaluates at
 122             compile-time and exports the symbol from the package.
 123         </para>
 124       </sect2>
 125       <sect2>
 126         <title>def-type</title>
 127         <para>
 128           This is the main function for creating new types.
 129         </para>
 130         <sect3>
 131           <title>Examples</title>
 132           <para>
 133             <programlisting>
 134 (def-type my-generic-pointer (* :void))
 135 (def-type a-double-float :double-float)
 136 (def-type char-ptr (* :char))
 137             </programlisting>
 138           </para>
 139         </sect3>
 140       </sect2>
 141       <sect2>
 142         <title>null-char-p</title>
 143         <para>
 144           A predicate testing if a pointer object is &null;
 145         </para>
 146       </sect2>
 147     </sect1>
 148
 149     <sect1>
 150       <title>Aggregate Types</title>
 151       <sect2>
 152         <title>def-enum</title>
 153         <para>
 154           Declares a &c; enumeration. It generates constants for the
 155           elements of the enumeration.
 156         </para>
 157       </sect2>
 158       <sect2>
 159         <title>def-struct</title>
 160         <para>
 161           Declares a structure. A special type is available as a slot in the field. It is
 162           a pointer that points to an instance of the parent structure. It's type is
 163           <constant>:pointer-self</constant>.
 164         </para>
 165         <sect3>
 166           <title>Examples</title>
 167           <para>
 168             <programlisting>
 169 (def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
 170             </programlisting>
 171           </para>
 172         </sect3>
 173       </sect2>
 174       <sect2 id="get-slot-value">
 175         <title>get-slot-value</title>
 176         <para>
 177           Accesses a slot value from a structure.
 178         </para>
 179       </sect2>
 180       <sect2>
 181         <title>get-slot-pointer</title>
 182         <para>
 183           This is similar to <function>get-slot-value</function>. It
 184           is used when the value of a slot is a pointer type.
 185         </para>
 186       </sect2>
 187       <sect2>
 188         <title>def-array</title>
 189         <para>
 190           Defines an array.
 191         </para>
 192       </sect2>
 193       <sect2>
 194         <title>deref-array</title>
 195         <para>
 196           Accesses an element of an array.
 197         </para>
 198       </sect2>
 199     </sect1>
 200
 201     <sect1>
 202       <title>Objects</title>
 203       <sect2>
 204         <title>Overview</title>
 205         <para>
 206           Objects are entities that can allocated and freed.
 207         </para>
 208       </sect2>
 209       <sect2>
 210         <title>allocate-foreign-object</title>
 211         <para>
 212           Allocates an instance of a foreign object. It returns a pointer to the object.
 213         </para>
 214       </sect2>
 215       <sect2>
 216         <title>free-foreign-object</title>
 217         <para>
 218           Frees the memory used by a foreign object.
 219         </para>
 220       </sect2>
 221       <sect2>
 222         <title>pointer-address</title>
 223         <para>
 224           Returns the address as an integer of a pointer.
 225         </para>
 226       </sect2>
 227       <sect2>
 228         <title>deref-pointer</title>
 229         <para>
 230           Returns the object to which a pointer points.
 231         </para>
 232       </sect2>
 233       <sect2>
 234         <title>make-null-pointer</title>
 235         <para>
 236           Creates a &null; pointer of a specified type.
 237         </para>
 238       </sect2>
 239       <sect2>
 240         <title>null-pointer-p</title>
 241         <para>
 242           A predicate testing if a pointer is has a &null; value.
 243         </para>
 244       </sect2>
 245       <sect2>
 246         <title>+null-cstring-pointer+</title>
 247         <para>
 248           A constant &null; character pointer.
 249         </para>
 250       </sect2>
 251     </sect1>
 252
 253     <sect1>
 254       <title>Strings</title>
 255       <sect2>
 256         <title>Overview</title>
 257         <para>
 258           &uffi; has functions to two types of <varname>C</varname>-compatible
 259           strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
 260 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
 261 may not convert these to a foreign type for efficiency sake. Thus, it is not
 262 possible to "allocate" a cstring. In contrast, foreign strings
 263 always need to have memory for them.
 264         </para>
 265       </sect2>
 266       <sect2>
 267         <title>convert-from-cstring</title>
 268         <para>
 269           Converts a Lisp string to a <varname>cstring</varname>.
 270         </para>
 271       </sect2>
 272       <sect2>
 273         <title>convert-to-cstring</title>
 274         <para>
 275           Converts a Lisp string to a
 276           <varname>cstring</varname>. The
 277           <varname>cstring</varname> should be freed with
 278           <function>free-cstring</function>.
 279         </para>
 280       </sect2>
 281       <sect2>
 282         <title>free-cstring</title>
 283         <para>
 284           Frees any memory possibly allocated by
 285           <function>convert-to-cstring</function>.
 286         </para>
 287       </sect2>
 288       <sect2>
 289         <title>with-cstring</title>
 290         <para>
 291           Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
 292         </para>
 293         <sect3>
 294           <title>Examples</title>
 295           <para>
 296             <programlisting>
 297 (def-function ("getenv" c-getenv)
 298    ((name :cstring))
 299    :returning :cstring)
 300
 301 (defun getenv (key)
 302   "Returns an environment variable, or NIL if it does not exist"
 303   (check-type key string)
 304   (with-cstring (key-cstring key)
 305     (convert-from-cstring (c-getenv key-cstring))))
 306           </programlisting>
 307         </para>
 308       </sect3>
 309       </sect2>
 310       <sect2>
 311         <title>convert-from-foreign-string</title>
 312         <para>
 313           Returns a Lisp string from a foreign string. Has parameters
 314           to handle ASCII versus binary strings.
 315         </para>
 316       </sect2>
 317       <sect2>
 318         <title>convert-to-foreign-string</title>
 319         <para>
 320           Converts a Lisp string to a foreign string. Memory should be
 321           freed with <function>free-foreign-object</function>.
 322         </para>
 323       </sect2>
 324       <sect2>
 325         <title>allocate-foreign-string</title>
 326         <para>
 327           Allocates space for a foreign string. Memory should
 328           be freed with <function>free-foreign-object</function>.
 329         </para>
 330       </sect2>
 331     </sect1>
 332
 333     <sect1>
 334       <title>Functions</title>
 335       <refentry id="def-function">
 336         <refnamediv>
 337           <refname>def-function</refname>
 338         <refpurpose>Declares a function.
 339         </refpurpose>
 340         <refclass>Macro</refclass>
 341       </refnamediv>
 342       <refsynopsisdiv>
 343         <title>Syntax</title>
 344         <synopsis>
 345           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
 346         </synopsis>
 347         <para>Arguments and Values</para>
 348         <variablelist>
 349           <varlistentry>
 350             <term><parameter>name</parameter></term>
 351             <listitem>
 352               <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.
 353               </para>
 354             </listitem>
 355           </varlistentry>
 356           <varlistentry>
 357             <term><parameter>args</parameter></term>
 358             <listitem>
 359               <para>A list of argument declarations. Use &nil; to specify no arguments.
 360               </para>
 361             </listitem>
 362           </varlistentry>
 363           <varlistentry>
 364             <term><parameter>module</parameter></term>
 365             <listitem>
 366               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
 367             </listitem>
 368           </varlistentry>
 369           <varlistentry>
 370             <term><returnvalue>returning</returnvalue></term>
 371             <listitem>
 372               <para>A declaration specifying the result type of the
 373 foreign function.
 374               </para>
 375             </listitem>
 376           </varlistentry>
 377         </variablelist>
 378       </refsynopsisdiv>
 379       <refsect1>
 380         <title>Description</title>
 381         <para>Declares a foreign function.
 382         </para>
 383       </refsect1>
 384       <refsect1>
 385         <title>Examples</title>
 386         <programlisting>
 387 (def-function "gethostname"
 388   ((name :cstring)
 389    (len :int))
 390   :returning :int)
 391         </programlisting>
 392       </refsect1>
 393       <refsect1>
 394         <title>Side Effects</title>
 395         <para>None.</para>
 396       </refsect1>
 397       <refsect1>
 398         <title>Affected by</title>
 399         <para>None.</para>
 400       </refsect1>
 401       <refsect1>
 402         <title>Exceptional Situations</title>
 403         <para>None.</para>
 404       </refsect1>
 405     </refentry>
 406     </sect1>
 407
 408     <sect1>
 409       <title>Libraries</title>
 410       <refentry id="load-foreign-library">
 411         <refnamediv>
 412           <refname>load-foreign-library</refname>
 413         <refpurpose>Loads a foreign library.
 414         </refpurpose>
 415         <refclass>Function</refclass>
 416       </refnamediv>
 417       <refsect1>
 418         <title>Syntax</title>
 419 <synopsis>
 420           <function>load-foreign-library</function> <replaceable>filename module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
 421 </synopsis>
 422       </refsect1>
 423       <refsect1>
 424         <title>Arguments and Values</title>
 425         <variablelist>
 426           <varlistentry>
 427             <term><parameter>filename</parameter></term>
 428             <listitem>
 429               <para>A string or pathname specifying the library location
 430 in the filesystem.
 431               </para>
 432             </listitem>
 433           </varlistentry>
 434           <varlistentry>
 435             <term><parameter>module</parameter></term>
 436             <listitem>
 437               <para>A string designating the name of the module to apply
 438 to functions in this library. (Required for Lispworks)
 439               </para>
 440             </listitem>
 441           </varlistentry>
 442           <varlistentry>
 443             <term><parameter>supporting-libraries</parameter></term>
 444             <listitem>
 445               <para>A list of strings naming the libraries required to
 446 link the foreign library. (Required by CMUCL)
 447               </para>
 448             </listitem>
 449           </varlistentry>
 450           <varlistentry>
 451             <term><returnvalue>success</returnvalue></term>
 452             <listitem>
 453               <para>A boolean flag, &t; if the library was able to be
 454 loaded successfully or if the library has been previously loaded,
 455 otherwise &nil;.
 456               </para>
 457             </listitem>
 458           </varlistentry>
 459         </variablelist>
 460       </refsect1>
 461       <refsect1>
 462         <title>Description</title>
 463         <para>Loads a foreign library. Applies a module name to functions
 464 within the library. Ensures that a library is only loaded once during
 465 a session.
 466         </para>
 467       </refsect1>
 468       <refsect1>
 469         <title>Examples</title>
 470         <programlisting>
 471   (load-foreign-library #p"/usr/lib/libmysqlclient.so" "mysql" '("c"))
 472     => T
 473         </programlisting>
 474       </refsect1>
 475       <refsect1>
 476         <title>Side Effects</title>
 477         <para>Loads the foreign code into the Lisp system.
 478         </para>
 479       </refsect1>
 480       <refsect1>
 481         <title>Affected by</title>
 482         <para>Ability to load the file.</para>
 483       </refsect1>
 484       <refsect1>
 485         <title>Exceptional Situations</title>
 486         <para>None.</para>
 487       </refsect1>
 488     </refentry>
 489   </sect1>
 490   </chapter>
 491
 492