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>covert-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       <refsect1>
 343         <title>Syntax</title>
 344 <synopsis>
 345           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
 346 </synopsis>
 347       </refsect1>
 348       <refsect1>
 349         <title>Arguments and Values</title>
 350         <variablelist>
 351           <varlistentry>
 352             <term><parameter>name</parameter></term>
 353             <listitem>
 354               <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.
 355               </para>
 356             </listitem>
 357           </varlistentry>
 358           <varlistentry>
 359             <term><parameter>args</parameter></term>
 360             <listitem>
 361               <para>A list of argument declarations. Use &nil; to specify no arguments.
 362               </para>
 363             </listitem>
 364           </varlistentry>
 365           <varlistentry>
 366             <term><parameter>module</parameter></term>
 367             <listitem>
 368               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
 369             </listitem>
 370           </varlistentry>
 371           <varlistentry>
 372             <term><returnvalue>returning</returnvalue></term>
 373             <listitem>
 374               <para>A declaration specifying the result type of the
 375 foreign function.
 376               </para>
 377             </listitem>
 378           </varlistentry>
 379         </variablelist>
 380       </refsect1>
 381       <refsect1>
 382         <title>Description</title>
 383         <para>Declares a foreign function.
 384         </para>
 385       </refsect1>
 386       <refsect1>
 387         <title>Examples</title>
 388         <programlisting>
 389 (def-function "gethostname"
 390   ((name :cstring)
 391    (len :int))
 392   :returning :int)
 393         </programlisting>
 394       </refsect1>
 395       <refsect1>
 396         <title>Side Effects</title>
 397         <para>None.</para>
 398       </refsect1>
 399       <refsect1>
 400         <title>Affected by</title>
 401         <para>None.</para>
 402       </refsect1>
 403       <refsect1>
 404         <title>Exceptional Situations</title>
 405         <para>None.</para>
 406       </refsect1>
 407     </refentry>
 408     </sect1>
 409
 410     <sect1>
 411       <title>Libraries</title>
 412       <refentry id="load-foreign-library">
 413         <refnamediv>
 414           <refname>load-foreign-library</refname>
 415         <refpurpose>Loads a foreign library.
 416         </refpurpose>
 417         <refclass>Function</refclass>
 418       </refnamediv>
 419       <refsect1>
 420         <title>Syntax</title>
 421 <synopsis>
 422           <function>load-foreign-library</function> <replaceable>filename module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
 423 </synopsis>
 424       </refsect1>
 425       <refsect1>
 426         <title>Arguments and Values</title>
 427         <variablelist>
 428           <varlistentry>
 429             <term><parameter>filename</parameter></term>
 430             <listitem>
 431               <para>A string or pathname specifying the library location
 432 in the filesystem.
 433               </para>
 434             </listitem>
 435           </varlistentry>
 436           <varlistentry>
 437             <term><parameter>module</parameter></term>
 438             <listitem>
 439               <para>A string designating the name of the module to apply
 440 to functions in this library. (Required for Lispworks)
 441               </para>
 442             </listitem>
 443           </varlistentry>
 444           <varlistentry>
 445             <term><parameter>supporting-libraries</parameter></term>
 446             <listitem>
 447               <para>A list of strings naming the libraries required to
 448 link the foreign library. (Required by CMUCL)
 449               </para>
 450             </listitem>
 451           </varlistentry>
 452           <varlistentry>
 453             <term><returnvalue>success</returnvalue></term>
 454             <listitem>
 455               <para>A boolean flag, &t; if the library was able to be
 456 loaded successfully or if the library has been previously loaded,
 457 otherwise &nil;.
 458               </para>
 459             </listitem>
 460           </varlistentry>
 461         </variablelist>
 462       </refsect1>
 463       <refsect1>
 464         <title>Description</title>
 465         <para>Loads a foreign library. Applies a module name to functions
 466 within the library. Ensures that a library is only loaded once during
 467 a session.
 468         </para>
 469       </refsect1>
 470       <refsect1>
 471         <title>Examples</title>
 472         <programlisting>
 473   (load-foreign-library #p"/usr/lib/libmysqlclient.so" "mysql" '("c"))
 474     => T
 475         </programlisting>
 476       </refsect1>
 477       <refsect1>
 478         <title>Side Effects</title>
 479         <para>Loads the foreign code into the Lisp system.
 480         </para>
 481       </refsect1>
 482       <refsect1>
 483         <title>Affected by</title>
 484         <para>Ability to load the file.</para>
 485       </refsect1>
 486       <refsect1>
 487         <title>Exceptional Situations</title>
 488         <para>None.</para>
 489       </refsect1>
 490     </refentry>
 491   </sect1>
 492   </chapter>
 493
 494