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