doc/uffi.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "docbook/dtd/xml/4.2/docbookx.dtd" [
   4 <!ENTITY uffi "<application><emphasis>UFFI</emphasis></application>">
   5 <!ENTITY ffi "<acronym>FFI</acronym>">
   6 <!ENTITY cmucl "<application>CMUCL</application>">
   7 <!ENTITY scl "<application>SCL</application>">
   8 <!ENTITY lw "<application>Lispworks</application>">
   9 <!ENTITY sbcl "<application>SBCL</application>">
  10 <!ENTITY openmcl "<application>OpenMCL</application>">
  11 <!ENTITY mcl "<application>MCL</application>">
  12 <!ENTITY acl "<application>AllegroCL</application>">
  13 <!ENTITY cl "<application>ANSI Common Lisp</application>">
  14 <!ENTITY t "<constant>T</constant>">
  15 <!ENTITY nil "<constant>NIL</constant>">
  16 <!ENTITY null "<constant>NULL</constant>">
  17 <!ENTITY c "<computeroutput>C</computeroutput>">
  18 <!ENTITY defsystem "<application>defsystem</application>">
  19 <!ENTITY asdf "<application>ASDF</application>">
  20 <!ENTITY bookinfo SYSTEM "bookinfo.sgml">
  21 <!ENTITY preface SYSTEM "preface.sgml">
  22 <!ENTITY intro SYSTEM "intro.sgml">
  23 <!ENTITY notes SYSTEM "notes.sgml">
  24 <!ENTITY ref SYSTEM "ref.sgml">
  25 <!ENTITY appendix SYSTEM "appendix.sgml">
  26 <!ENTITY glossary SYSTEM "glossary.sgml">
  27 ]>
  28
  29 <book>
  30
  31   <bookinfo>
  32     <title>&uffi; Reference Guide</title>
  33     <author>
  34       <firstname>Kevin</firstname>
  35       <othername>M.</othername>
  36       <surname>Rosenberg</surname>
  37     <affiliation>
  38         <orgname>Heart Hospital of New Mexico</orgname>
  39         <address>
  40         <email>kevin@rosenberg.net</email>
  41         <street>504 Elm Street N.E.</street>
  42         <city>Albuquerque</city>
  43         <state>New Mexico</state>
  44         <postcode>87102</postcode>
  45         </address>
  46       </affiliation>
  47     </author>
  48
  49     <printhistory>
  50       <simpara>$Id: bookinfo.sgml 7990 2003-10-12 21:26:56Z kevin $</simpara>
  51       <simpara>File $Date: 2003-10-12 15:26:56 -0600 (Sun, 12 Oct 2003) $</simpara>
  52     </printhistory>
  53     <copyright>
  54       <year>2002-2003</year>
  55       <holder>Kevin M. Rosenberg</holder>
  56     </copyright>
  57     <legalnotice>
  58       <itemizedlist>
  59         <listitem>
  60           <para>The &uffi; package was designed and
  61             written by Kevin M. Rosenberg.
  62           </para>
  63         </listitem>
  64 <listitem>
  65 <para>
  66       Permission is granted to copy, distribute and/or modify this document
  67       under the terms of the GNU Free Documentation License, Version 1.1
  68       or any later version published by the Free Software Foundation;
  69       with no Invariant Sections, with the no
  70       Front-Cover Texts, and with no Back-Cover Texts.
  71       A copy of the license is included in the &uffi; distribution.
  72 </para>
  73 </listitem>
  74         <listitem>
  75           <para><application>Allegro CL</application>&reg; is a registered
  76             trademark of Franz Inc.
  77           </para>
  78         </listitem>
  79         <listitem>
  80           <para><application>Lispworks</application>&reg; is a registered
  81             trademark of Xanalys Inc.
  82           </para>
  83         </listitem>
  84         <listitem>
  85           <para><application>Microsoft
  86             Windows</application>&reg; is a registered trademark of
  87             Microsoft Inc.
  88           </para>
  89         </listitem>
  90         <listitem>
  91           <para>Other brand or
  92             product names are the registered trademarks or trademarks of
  93             their respective holders.
  94           </para>
  95         </listitem>
  96       </itemizedlist>
  97     </legalnotice>
  98   </bookinfo>
  99
 100 <preface>
 101   <title>Preface</title>
 102   <para>This reference guide describes the usage and features
 103     of &uffi;.  The first
 104     chapter provides an overview to the design of &uffi;.
 105     Following that chapter is the reference section for all user
 106     accessible functions of &uffi;. The appendix covers the
 107     installation and implementation-specifc features of &uffi;.
 108   </para>
 109 </preface>
 110
 111
 112 <chapter>
 113   <title>Introduction</title>
 114   <sect1>
 115     <title>Purpose</title>
 116     <para> This reference guide describes
 117       &uffi;, a package that provides a cross-implementation
 118       interface from Common Lisp to C-language compatible libraries.
 119     </para>
 120   </sect1>
 121
 122   <sect1>
 123     <title>Background
 124     </title>
 125     <para>
 126       Every Common Lisp implementation has
 127       a method for interfacing to C-language compatible
 128       libraries. These methods are often termed a
 129       <emphasis>Foreign Function Library Interface</emphasis>
 130       (&ffi;). Unfortunately, these methods vary widely
 131       amongst
 132       implementations, thus preventing the writing of a portable FFI to a
 133 particular C-library.
 134     </para>
 135     <para>
 136       &uffi; gathers a common subset of functionality between Common Lisp
 137       implementations. &uffi; wraps this common subset of functionality with
 138       it's own syntax and provides macro translation of uffi functions into
 139       the specific syntax of supported Common Lisp implementations.
 140     </para>
 141     <para>
 142       Developers who use &uffi; to interface with C libraries will
 143       automatically have their code function in each of uffi's supported
 144       implementations.
 145     </para>
 146   </sect1>
 147
 148   <sect1>
 149     <title>Supported Implementations</title>
 150     <para>The primary tested and supported platforms for &uffi; are:
 151     </para>
 152     <itemizedlist mark="opencircle">
 153       <listitem><para>&acl; v6.2 on Debian GNU/Linux
 154 FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP.</para></listitem>
 155       <listitem><para>&lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP.</para></listitem>
 156       <listitem><para>&cmucl; 18d on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8</para></listitem>
 157       <listitem><para>&sbcl; 0.7.8 on Debian GNU/Linux</para></listitem>
 158       <listitem><para>&scl; 1.1.1 on Debian GNU/Linux</para></listitem>
 159       <listitem><para>&openmcl; 0.13 on Debian GNU/Linux for PowerPC</para></listitem>
 160     </itemizedlist>
 161     <para>Beta code is included with &uffi; for
 162     </para>
 163     <itemizedlist mark="opencircle">
 164       <listitem><para>&openmcl; and &mcl; with MacOSX</para></listitem>
 165     </itemizedlist>
 166   </sect1>
 167
 168     <sect1>
 169       <title>Design</title>
 170       <sect2>
 171         <title>Overview</title>
 172         <para>
 173           &uffi; was designed as a cross-implementation
 174           compatible <emphasis>Foreign Function Interface</emphasis>.
 175           Necessarily,
 176           only a common subset of functionality can be
 177           provided. Likewise, not every optimization for that a specific
 178           implementation provides can be supported. Wherever possible,
 179           though, implementation-specific optimizations are invoked.
 180         </para>
 181       </sect2>
 182
 183       <sect2>
 184         <title>Priorities</title>
 185         <para>
 186           The design of &uffi; is dictated by the order of these priorities:
 187         </para>
 188         <itemizedlist>
 189           <listitem>
 190             <para>
 191               Code using &uffi; must operate correctly on all
 192               supported implementations.
 193             </para>
 194           </listitem>
 195           <listitem>
 196             <para>
 197               Take advantage of implementation-specific optimizations. Ideally,
 198               there will not a situation where an implementation-specific
 199               &ffi; will be chosen due to lack of optimizations in &uffi;.
 200             </para>
 201           </listitem>
 202           <listitem>
 203             <para>Provide a simple interface to developers using
 204 &uffi;.  This priority is quite a bit lower than the above priorities.
 205 This lower priority is manifest by programmers having to pass types in
 206 pointer and array dereferencing, needing to use
 207 <constant>cstring</constant> wrapper functions, and the use of
 208 ensure-char-character and ensure-char-integer functions. My hope is
 209 that the developer inconvenience will be outweighed by the generation
 210 of optimized code that is cross-implementation compatible.
 211             </para>
 212           </listitem>
 213         </itemizedlist>
 214       </sect2>
 215     </sect1>
 216
 217 </chapter>
 218
 219
 220 <chapter>
 221   <title>Programming Notes</title>
 222
 223   <sect1>
 224     <title>Implementation Specific Notes</title>
 225     <para>
 226     </para>
 227       <sect2>
 228         <title>&acl;</title>
 229         <para>
 230         </para>
 231       </sect2>
 232       <sect2>
 233         <title>&lw;</title>
 234         <para>
 235         </para>
 236       </sect2>
 237       <sect2>
 238         <title>&cmucl;</title>
 239         <para>
 240         </para>
 241       </sect2>
 242   </sect1>
 243
 244   <sect1>
 245     <title>Foreign Object Representation and Access</title>
 246     <para> There are two main approaches used to represent foreign
 247     objects: an integer that represents an address in memory, and a
 248     object that also includes run-time typing. The advantage of
 249     run-time typing is the system can dereference pointers and perform
 250     array access without those functions requiring a type at the cost
 251     of additional overhead to generate and store the run-time
 252     typing. The advantage of integer representation, at least for
 253     &acl;, is that the compiler can generate inline code to
 254     dereference pointers. Further, the overhead of the run-time type
 255     information is eliminated. The disadvantage is the program must
 256     then supply
 257     the type to the functions to dereference objects and array.
 258     </para>
 259   </sect1>
 260
 261   <sect1>
 262     <title>Optimizing Code Using UFFI</title>
 263     <sect2>
 264       <title>Background</title>
 265       <para>
 266         Two implementions have different techniques to optimize
 267         (open-code) foreign objects. &acl; can open-code foreign
 268         object
 269         access if pointers are integers and the type of object is
 270     specified in the access function.  Thus, &uffi; represents objects
 271     in &acl; as integers which don't have type information.
 272     </para> <para>
 273       &cmucl; works best when keeping objects as typed
 274     objects. However, it's compiler can open-code object access when
 275     the object type is specified in <function>declare</function>
 276     commands and in <varname>:type</varname> specifiers in
 277     <function>defstruct</function> and <function>defclass</function>.
 278     </para> <para> &lw;, in converse to &acl; and &cmucl; does not do
 279     any open coding of object access. &lw;, by default, maintains
 280     objects with run-time typing.  </para>
 281     </sect2>
 282     <sect2>
 283       <title>Cross-Implementation Optimization</title>
 284       <para>
 285         To fully optimize across platforms, both explicit type
 286         information must be passed to dereferencing of pointers and
 287         arrays. Though this optimization only helps with &acl;, &uffi;
 288         is designed to require this type information be passed the
 289         dereference functions. Second, declarations of type should be
 290         made in functions, structures, and classes where foreign
 291         objects will be help. This will optimize access for &lw;
 292       </para>
 293       <para>
 294         Here is an example that should both methods being used for
 295         maximum cross-implementation optimization:
 296         <programlisting>
 297 (uffi:def-type the-struct-type-def the-struct-type)
 298 (let ((a-foreign-struct (allocate-foreign-object 'the-struct-type)))
 299   (declare 'the-struct-type-def a-foreign-struct)
 300   (get-slot-value a-foreign-struct 'the-struct-type 'field-name))
 301         </programlisting>
 302       </para>
 303     </sect2>
 304   </sect1>
 305
 306 </chapter>
 307
 308
 309 <reference>
 310   <title>Declarations</title>
 311
 312   <partintro>
 313     <sect1>
 314       <title>Overview</title>
 315       <para>Declarations are used to give the compiler optimizing
 316         information about foreign types. Currently, only &cmucl;
 317         supports declarations. On &acl; and &lw;, these expressions
 318         declare the type generically as &t;
 319       </para>
 320     </sect1>
 321   </partintro>
 322
 323       <refentry id="def-type">
 324         <refnamediv>
 325           <refname>def-type</refname>
 326         <refpurpose>Defines a Common Lisp type.
 327         </refpurpose>
 328         <refclass>Macro</refclass>
 329       </refnamediv>
 330       <refsynopsisdiv>
 331         <title>Syntax</title>
 332         <synopsis>
 333           <function>def-type</function> <replaceable>name type</replaceable>
 334         </synopsis>
 335       </refsynopsisdiv>
 336       <refsect1>
 337         <title>Arguments and Values</title>
 338         <variablelist>
 339           <varlistentry>
 340             <term><parameter>name</parameter></term>
 341             <listitem>
 342               <para>A symbol naming the type</para>
 343             </listitem>
 344           </varlistentry>
 345           <varlistentry>
 346             <term><parameter>type</parameter></term>
 347             <listitem>
 348               <para>A form that is evaluated that specifies the &uffi; type.
 349               </para>
 350             </listitem>
 351           </varlistentry>
 352         </variablelist>
 353       </refsect1>
 354       <refsect1>
 355         <title>Description</title>
 356         <para>Defines a Common Lisp type based on a &uffi; type.
 357         </para>
 358       </refsect1>
 359       <refsect1>
 360         <title>Examples</title>
 361         <programlisting>
 362 (def-type char-ptr '(* :char))
 363 ...
 364 (defun foo (ptr)
 365   (declare (type char-ptr ptr))
 366   ...
 367         </programlisting>
 368       </refsect1>
 369       <refsect1>
 370         <title>Side Effects</title>
 371         <para>Defines a new &cl; type.</para>
 372       </refsect1>
 373       <refsect1>
 374         <title>Affected by</title>
 375         <para>None.</para>
 376       </refsect1>
 377       <refsect1>
 378         <title>Exceptional Situations</title>
 379         <para>None.</para>
 380       </refsect1>
 381     </refentry>
 382   </reference>
 383
 384
 385   <reference>
 386     <title>Primitive Types</title>
 387     <partintro>
 388       <title>Overview</title>
 389         <para>
 390           Primitive types have a single value, these include
 391           characters, numbers, and pointers. They are all symbols in
 392           the keyword package.
 393         </para>
 394         <itemizedlist>
 395           <listitem>
 396             <para><constant>:char</constant> - Signed 8-bits. A
 397 dereferenced :char pointer returns an character.</para>
 398           </listitem>
 399           <listitem>
 400             <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
 401 pointer returns an character.</para>
 402           </listitem>
 403           <listitem>
 404             <para><constant>:byte</constant> - Signed 8-bits. A
 405 dereferenced :byte pointer returns an integer.</para>
 406           </listitem>
 407           <listitem>
 408             <para><constant>:unsigned-byte</constant> - Unsigned 8-bits. A
 409 dereferenced :unsigned-byte pointer returns an integer.</para>
 410           </listitem>
 411           <listitem>
 412             <para><constant>:short</constant> - Signed 16-bits.</para>
 413           </listitem>
 414           <listitem>
 415             <para><constant>:unsigned-short</constant> - Unsigned 16-bits.</para>
 416           </listitem>
 417           <listitem>
 418             <para><constant>:int</constant> - Signed 32-bits.</para>
 419           </listitem>
 420           <listitem>
 421             <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
 422           </listitem>
 423           <listitem>
 424             <para><constant>:long</constant> - Signed 32 or 64 bits, depending upon the platform.</para>
 425           </listitem>
 426           <listitem>
 427             <para><constant>:unsigned-long</constant> - Unsigned 32 or 64 bits, depending upon the platform.</para>
 428           </listitem>
 429           <listitem>
 430             <para><constant>:float</constant> - 32-bit floating point.</para>
 431           </listitem>
 432           <listitem>
 433             <para><constant>:double</constant> - 64-bit floating point.</para>
 434           </listitem>
 435           <listitem>
 436             <para><constant>:cstring</constant> -
 437 A &null; terminated string used for passing and returning characters strings with a &c; function.
 438             </para>
 439           </listitem>
 440           <listitem>
 441             <para><constant>:void</constant> -
 442 The absence of a value. Used to indicate that a function does not return a value.</para>
 443           </listitem>
 444           <listitem>
 445             <para><constant>:pointer-void</constant> -
 446 Points to a generic object.</para>
 447           </listitem>
 448           <listitem>
 449             <para><constant>*</constant> - Used to declare a pointer to an object</para>
 450           </listitem>
 451         </itemizedlist>
 452       </partintro>
 453
 454       <refentry id="def-constant">
 455         <refnamediv>
 456           <refname>def-constant</refname>
 457         <refpurpose>Binds a symbol to a constant.
 458         </refpurpose>
 459         <refclass>Macro</refclass>
 460       </refnamediv>
 461       <refsynopsisdiv>
 462         <title>Syntax</title>
 463         <synopsis>
 464           <function>def-constant</function> <replaceable>name value &amp;key export</replaceable>
 465         </synopsis>
 466       </refsynopsisdiv>
 467       <refsect1>
 468         <title>Arguments and Values</title>
 469         <variablelist>
 470           <varlistentry>
 471             <term><parameter>name</parameter></term>
 472             <listitem>
 473               <para>A symbol that will be bound to the value.
 474               </para>
 475             </listitem>
 476           </varlistentry>
 477           <varlistentry>
 478             <term><parameter>value</parameter></term>
 479             <listitem>
 480               <para>An evaluated form that is bound the the name.
 481               </para>
 482             </listitem>
 483           </varlistentry>
 484           <varlistentry>
 485             <term><parameter>export</parameter></term>
 486             <listitem>
 487               <para>When &t;, the name is exported from the current package. The default is &nil;</para>
 488             </listitem>
 489           </varlistentry>
 490         </variablelist>
 491       </refsect1>
 492       <refsect1>
 493         <title>Description</title>
 494         <para>
 495           This is a thin wrapper around
 496           <function>defconstant</function>. It evaluates at
 497             compile-time and optionally exports the symbol from the package.
 498         </para>
 499       </refsect1>
 500       <refsect1>
 501         <title>Examples</title>
 502         <programlisting>
 503 (def-constant pi2 (* 2 pi))
 504 (def-constant exported-pi2 (* 2 pi) :export t)
 505         </programlisting>
 506       </refsect1>
 507       <refsect1>
 508         <title>Side Effects</title>
 509         <para>Creates a new special variable..</para>
 510       </refsect1>
 511       <refsect1>
 512         <title>Affected by</title>
 513         <para>None.</para>
 514       </refsect1>
 515       <refsect1>
 516         <title>Exceptional Situations</title>
 517         <para>None.</para>
 518       </refsect1>
 519     </refentry>
 520
 521     <refentry id="def-foreign-type">
 522         <refnamediv>
 523           <refname>def-foreign-type</refname>
 524         <refpurpose>Defines a new foreign type.
 525         </refpurpose>
 526         <refclass>Macro</refclass>
 527       </refnamediv>
 528       <refsect1>
 529         <title>Syntax</title>
 530 <synopsis>
 531           <function>def-foreign-type</function> <replaceable>name type</replaceable>
 532 </synopsis>
 533       </refsect1>
 534       <refsect1>
 535         <title>Arguments and Values</title>
 536         <variablelist>
 537           <varlistentry>
 538             <term><parameter>name</parameter></term>
 539             <listitem>
 540               <para>A symbol naming the new foreign type.
 541               </para>
 542             </listitem>
 543           </varlistentry>
 544           <varlistentry>
 545             <term><parameter>value</parameter></term>
 546             <listitem>
 547               <para>A form that is not evaluated that defines the new
 548 foreign type.
 549               </para>
 550             </listitem>
 551           </varlistentry>
 552         </variablelist>
 553       </refsect1>
 554       <refsect1>
 555         <title>Description</title>
 556         <para>Defines a new foreign type.
 557         </para>
 558       </refsect1>
 559       <refsect1>
 560         <title>Examples</title>
 561         <programlisting>
 562 (def-foreign-type my-generic-pointer :pointer-void)
 563 (def-foreign-type a-double-float :double-float)
 564 (def-foreign-type char-ptr (* :char))
 565         </programlisting>
 566       </refsect1>
 567       <refsect1>
 568         <title>Side Effects</title>
 569         <para>Defines a new foreign type.
 570         </para>
 571       </refsect1>
 572       <refsect1>
 573         <title>Affected by</title>
 574         <para>None.</para>
 575       </refsect1>
 576       <refsect1>
 577         <title>Exceptional Situations</title>
 578         <para>None.</para>
 579       </refsect1>
 580     </refentry>
 581
 582     <refentry id="null-char-p">
 583         <refnamediv>
 584           <refname>null-char-p</refname>
 585         <refpurpose>Tests a character for &null; value.
 586         </refpurpose>
 587         <refclass>Macro</refclass>
 588       </refnamediv>
 589       <refsect1>
 590         <title>Syntax</title>
 591 <synopsis>
 592           <function>null-char-p</function> <replaceable>char</replaceable> => <returnvalue>is-null</returnvalue>
 593 </synopsis>
 594       </refsect1>
 595       <refsect1>
 596         <title>Arguments and Values</title>
 597         <variablelist>
 598           <varlistentry>
 599             <term><parameter>char</parameter></term>
 600             <listitem>
 601               <para>A character or integer.
 602               </para>
 603             </listitem>
 604           </varlistentry>
 605           <varlistentry>
 606             <term><parameter>is-null</parameter></term>
 607             <listitem>
 608               <para>A boolean flag indicating if char is a &null; value.
 609               </para>
 610             </listitem>
 611           </varlistentry>
 612         </variablelist>
 613       </refsect1>
 614       <refsect1>
 615         <title>Description</title>
 616         <para>
 617           A predicate testing if a character or integer is &null;. This
 618 abstracts the difference in implementations where some return a
 619 <computeroutput>character</computeroutput> and some return a
 620 <computeroutput>integer</computeroutput> whence dereferencing a
 621 <computeroutput>C</computeroutput> character pointer.
 622         </para>
 623       </refsect1>
 624       <refsect1>
 625         <title>Examples</title>
 626         <programlisting>
 627 (def-array-pointer ca :unsigned-char)
 628 (let ((fs (convert-to-foreign-string "ab")))
 629    (values (null-char-p (deref-array fs 'ca 0))
 630            (null-char-p (deref-array fs 'ca 2))))
 631 => &nil;
 632    &t;
 633         </programlisting>
 634       </refsect1>
 635       <refsect1>
 636         <title>Side Effects</title>
 637         <para>None.
 638         </para>
 639       </refsect1>
 640       <refsect1>
 641         <title>Affected by</title>
 642         <para>None.</para>
 643       </refsect1>
 644       <refsect1>
 645         <title>Exceptional Situations</title>
 646         <para>None.</para>
 647       </refsect1>
 648     </refentry>
 649   </reference>
 650
 651   <reference>
 652     <title>Aggregate Types</title>
 653     <partintro>
 654       <title>Overview</title>
 655       <para>
 656         Aggregate types are comprised of one or more primitive types.
 657       </para>
 658     </partintro>
 659
 660     <refentry id="def-enum">
 661       <refnamediv>
 662         <refname>def-enum</refname>
 663         <refpurpose>Defines a &c; enumeration.
 664         </refpurpose>
 665         <refclass>Macro</refclass>
 666       </refnamediv>
 667       <refsynopsisdiv>
 668         <title>Syntax</title>
 669         <synopsis>
 670           <function>def-enum</function> <replaceable>name fields &amp;key separator-string</replaceable>
 671         </synopsis>
 672       </refsynopsisdiv>
 673       <refsect1>
 674         <title>Arguments and Values</title>
 675         <variablelist>
 676           <varlistentry>
 677             <term><parameter>name</parameter></term>
 678             <listitem>
 679               <para>A symbol that names the enumeration.
 680               </para>
 681             </listitem>
 682           </varlistentry>
 683           <varlistentry>
 684             <term><parameter>fields</parameter></term>
 685             <listitem>
 686               <para>A list of field defintions. Each definition can be
 687 a symbol or a list of two elements. Symbols get assigned a value of the
 688 current counter which starts at <computeroutput>0</computeroutput> and
 689 increments by <computeroutput>1</computeroutput> for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second
 690 position is the value to assign the the symbol. The current counter gets set
 691 to <computeroutput>1+</computeroutput> this value.
 692               </para>
 693             </listitem>
 694           </varlistentry>
 695           <varlistentry>
 696             <term><parameter>separator-string</parameter></term>
 697             <listitem>
 698               <para>A string that governs the creation of constants. The
 699 default is <computeroutput>"#"</computeroutput>.</para>
 700             </listitem>
 701           </varlistentry>
 702         </variablelist>
 703       </refsect1>
 704       <refsect1>
 705         <title>Description</title>
 706         <para>
 707           Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
 708 values are created by the <function>concatenation</function> of the
 709 enumeration name, separator-string, and field symbol. Also creates
 710 a foreign type with the name <parameter>name</parameter> of type
 711 <constant>:int</constant>.
 712         </para>
 713       </refsect1>
 714       <refsect1>
 715         <title>Examples</title>
 716         <programlisting>
 717 (def-enum abc (:a :b :c))
 718 ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
 719 ;; the foreign type "abc" to be :int
 720
 721 (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
 722 ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
 723 ;; the foreign type efoo to be :int
 724         </programlisting>
 725       </refsect1>
 726       <refsect1>
 727         <title>Side Effects</title>
 728         <para>Creates a :int foreign type, defines constants.</para>
 729       </refsect1>
 730       <refsect1>
 731         <title>Affected by</title>
 732         <para>None.</para>
 733       </refsect1>
 734       <refsect1>
 735         <title>Exceptional Situations</title>
 736         <para>None.</para>
 737       </refsect1>
 738     </refentry>
 739
 740
 741       <refentry id="def-struct">
 742         <refnamediv>
 743           <refname>def-struct</refname>
 744         <refpurpose>Defines a &c; structure.
 745         </refpurpose>
 746         <refclass>Macro</refclass>
 747       </refnamediv>
 748       <refsynopsisdiv>
 749         <title>Syntax</title>
 750         <synopsis>
 751           <function>def-struct</function> <replaceable>name &amp;rest fields</replaceable>
 752         </synopsis>
 753       </refsynopsisdiv>
 754       <refsect1>
 755         <title>Arguments and Values</title>
 756         <variablelist>
 757           <varlistentry>
 758             <term><parameter>name</parameter></term>
 759             <listitem>
 760               <para>A symbol that names the structure.
 761               </para>
 762             </listitem>
 763           </varlistentry>
 764           <varlistentry>
 765             <term><parameter>fields</parameter></term>
 766             <listitem>
 767               <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
 768               </para>
 769             </listitem>
 770           </varlistentry>
 771         </variablelist>
 772       </refsect1>
 773       <refsect1>
 774         <title>Description</title>
 775         <para>
 776           Declares a structure. A special type is available as a slot
 777 in the field. It is a pointer that points to an instance of the parent
 778 structure. It's type is <constant>:pointer-self</constant>.
 779
 780         </para>
 781       </refsect1>
 782       <refsect1>
 783         <title>Examples</title>
 784         <programlisting>
 785 (def-struct foo (a :unsigned-int)
 786                 (b (* :char))
 787                 (c (:array :int 10))
 788                 (next :pointer-self))
 789         </programlisting>
 790       </refsect1>
 791       <refsect1>
 792         <title>Side Effects</title>
 793         <para>Creates a foreign type.</para>
 794       </refsect1>
 795       <refsect1>
 796         <title>Affected by</title>
 797         <para>None.</para>
 798       </refsect1>
 799       <refsect1>
 800         <title>Exceptional Situations</title>
 801         <para>None.</para>
 802       </refsect1>
 803     </refentry>
 804
 805
 806     <refentry id="get-slot-value">
 807       <refnamediv>
 808         <refname>get-slot-value</refname>
 809         <refpurpose>Retrieves a value from a slot of a structure.
 810         </refpurpose>
 811         <refclass>Macro</refclass>
 812       </refnamediv>
 813       <refsynopsisdiv>
 814         <title>Syntax</title>
 815         <synopsis>
 816           <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
 817         </synopsis>
 818       </refsynopsisdiv>
 819       <refsect1>
 820         <title>Arguments and Values</title>
 821         <variablelist>
 822           <varlistentry>
 823             <term><parameter>obj</parameter></term>
 824             <listitem>
 825               <para>A pointer to foreign structure.
 826               </para>
 827             </listitem>
 828           </varlistentry>
 829           <varlistentry>
 830             <term><parameter>type</parameter></term>
 831             <listitem>
 832               <para>A name of the foreign structure.
 833               </para>
 834             </listitem>
 835           </varlistentry>
 836           <varlistentry>
 837             <term><parameter>field</parameter></term>
 838             <listitem>
 839               <para>A name of the desired field in foreign structure.
 840               </para>
 841             </listitem>
 842           </varlistentry>
 843           <varlistentry>
 844             <term><returnvalue>value</returnvalue></term>
 845             <listitem>
 846               <para>The value of the field in the structure.
 847               </para>
 848             </listitem>
 849           </varlistentry>
 850         </variablelist>
 851       </refsect1>
 852       <refsect1>
 853         <title>Description</title>
 854         <para>
 855           Accesses a slot value from a structure.
 856         </para>
 857       </refsect1>
 858       <refsect1>
 859         <title>Examples</title>
 860         <programlisting>
 861 (get-slot-value foo-ptr 'foo-structure 'field-name)
 862         </programlisting>
 863       </refsect1>
 864       <refsect1>
 865         <title>Side Effects</title>
 866         <para>None.</para>
 867       </refsect1>
 868       <refsect1>
 869         <title>Affected by</title>
 870         <para>None.</para>
 871       </refsect1>
 872       <refsect1>
 873         <title>Exceptional Situations</title>
 874         <para>None.</para>
 875       </refsect1>
 876     </refentry>
 877
 878     <refentry id="get-slot-pointer">
 879       <refnamediv>
 880         <refname>get-slot-pointer</refname>
 881         <refpurpose>Retrieves a pointer from a slot of a structure.
 882         </refpurpose>
 883         <refclass>Macro</refclass>
 884       </refnamediv>
 885       <refsynopsisdiv>
 886         <title>Syntax</title>
 887         <synopsis>
 888           <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
 889         </synopsis>
 890       </refsynopsisdiv>
 891       <refsect1>
 892         <title>Arguments and Values</title>
 893         <variablelist>
 894           <varlistentry>
 895             <term><parameter>obj</parameter></term>
 896             <listitem>
 897               <para>A pointer to foreign structure.
 898               </para>
 899             </listitem>
 900           </varlistentry>
 901           <varlistentry>
 902             <term><parameter>type</parameter></term>
 903             <listitem>
 904               <para>A name of the foreign structure.
 905               </para>
 906             </listitem>
 907           </varlistentry>
 908           <varlistentry>
 909             <term><parameter>field</parameter></term>
 910             <listitem>
 911               <para>A name of the desired field in foreign structure.
 912               </para>
 913             </listitem>
 914           </varlistentry>
 915           <varlistentry>
 916             <term><returnvalue>pointer</returnvalue></term>
 917             <listitem>
 918               <para>The value of the field in the structure.
 919               </para>
 920             </listitem>
 921           </varlistentry>
 922         </variablelist>
 923       </refsect1>
 924       <refsect1>
 925         <title>Description</title>
 926         <para>
 927           This is similar to <function>get-slot-value</function>. It
 928           is used when the value of a slot is a pointer type.
 929         </para>
 930       </refsect1>
 931       <refsect1>
 932         <title>Examples</title>
 933         <programlisting>
 934 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
 935         </programlisting>
 936       </refsect1>
 937       <refsect1>
 938         <title>Side Effects</title>
 939         <para>None.</para>
 940       </refsect1>
 941       <refsect1>
 942         <title>Affected by</title>
 943         <para>None.</para>
 944       </refsect1>
 945       <refsect1>
 946         <title>Exceptional Situations</title>
 947         <para>None.</para>
 948       </refsect1>
 949     </refentry>
 950
 951
 952     <refentry id="def-array-pointer">
 953       <refnamediv>
 954         <refname>def-array-pointer</refname>
 955         <refpurpose>Defines a pointer to a array of type.
 956         </refpurpose>
 957         <refclass>Macro</refclass>
 958       </refnamediv>
 959       <refsynopsisdiv>
 960         <title>Syntax</title>
 961         <synopsis>
 962           <function>def-array-pointer</function> <replaceable>name type</replaceable>
 963         </synopsis>
 964       </refsynopsisdiv>
 965       <refsect1>
 966         <title>Arguments and Values</title>
 967         <variablelist>
 968           <varlistentry>
 969             <term><parameter>name</parameter></term>
 970             <listitem>
 971               <para>A name of the new foreign type.
 972               </para>
 973             </listitem>
 974           </varlistentry>
 975           <varlistentry>
 976             <term><parameter>type</parameter></term>
 977             <listitem>
 978               <para>The foreign type of the array elements.
 979               </para>
 980             </listitem>
 981           </varlistentry>
 982         </variablelist>
 983       </refsect1>
 984       <refsect1>
 985         <title>Description</title>
 986         <para>
 987           Defines a type tat is a pointer to an array of type.
 988         </para>
 989       </refsect1>
 990       <refsect1>
 991         <title>Examples</title>
 992         <programlisting>
 993 (def-array-pointer byte-array-pointer :unsigned-char)
 994         </programlisting>
 995       </refsect1>
 996       <refsect1>
 997         <title>Side Effects</title>
 998         <para>Defines a new foreign type.</para>
 999       </refsect1>
1000       <refsect1>
1001         <title>Affected by</title>
1002         <para>None.</para>
1003       </refsect1>
1004       <refsect1>
1005         <title>Exceptional Situations</title>
1006         <para>None.</para>
1007       </refsect1>
1008     </refentry>
1009
1010
1011     <refentry id="deref-array">
1012       <refnamediv>
1013         <refname>deref-array</refname>
1014         <refpurpose>Deference an array.
1015         </refpurpose>
1016         <refclass>Macro</refclass>
1017       </refnamediv>
1018       <refsynopsisdiv>
1019         <title>Syntax</title>
1020         <synopsis>
1021           <function>deref-array</function> <replaceable>array type positon</replaceable> => <returnvalue>value</returnvalue>
1022         </synopsis>
1023       </refsynopsisdiv>
1024       <refsect1>
1025         <title>Arguments and Values</title>
1026         <variablelist>
1027           <varlistentry>
1028             <term><parameter>array</parameter></term>
1029             <listitem>
1030               <para>A foreign array.
1031               </para>
1032             </listitem>
1033           </varlistentry>
1034           <varlistentry>
1035             <term><parameter>type</parameter></term>
1036             <listitem>
1037               <para>The foreign type of the array.
1038               </para>
1039             </listitem>
1040           </varlistentry>
1041           <varlistentry>
1042             <term><parameter>position</parameter></term>
1043             <listitem>
1044               <para>An integer specifying the position to retrieve from
1045 the array.
1046               </para>
1047             </listitem>
1048           </varlistentry>
1049           <varlistentry>
1050             <term><returnvalue>value</returnvalue></term>
1051             <listitem>
1052               <para>The value stored in the position of the array.
1053               </para>
1054             </listitem>
1055           </varlistentry>
1056         </variablelist>
1057       </refsect1>
1058       <refsect1>
1059         <title>Description</title>
1060         <para>
1061           Dereferences (retrieves) the value of an array element.
1062         </para>
1063       </refsect1>
1064       <refsect1>
1065         <title>Examples</title>
1066         <programlisting>
1067 (def-array-pointer ca :char)
1068 (let ((fs (convert-to-foreign-string "ab")))
1069    (values (null-char-p (deref-array fs 'ca 0))
1070            (null-char-p (deref-array fs 'ca 2))))
1071 => &nil;
1072    &t;
1073         </programlisting>
1074       </refsect1>
1075       <refsect1>
1076         <title>Notes</title>
1077         <para>
1078   The TYPE argument is ignored for CL implementations other than
1079   AllegroCL. If you want to cast a pointer to another type use
1080   WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
1081         </para>
1082       </refsect1>
1083       <refsect1>
1084         <title>Side Effects</title>
1085         <para>None.</para>
1086       </refsect1>
1087       <refsect1>
1088         <title>Affected by</title>
1089         <para>None.</para>
1090       </refsect1>
1091       <refsect1>
1092         <title>Exceptional Situations</title>
1093         <para>None.</para>
1094       </refsect1>
1095     </refentry>
1096
1097     <refentry id="def-union">
1098       <refnamediv>
1099         <refname>def-union</refname>
1100         <refpurpose>Defines a foreign union type.
1101         </refpurpose>
1102         <refclass>Macro</refclass>
1103       </refnamediv>
1104       <refsynopsisdiv>
1105         <title>Syntax</title>
1106         <synopsis>
1107           <function>def-union</function> <replaceable>name &amp;rest fields</replaceable>
1108         </synopsis>
1109       </refsynopsisdiv>
1110       <refsect1>
1111         <title>Arguments and Values</title>
1112         <variablelist>
1113           <varlistentry>
1114             <term><parameter>name</parameter></term>
1115             <listitem>
1116               <para>A name of the new union type.
1117               </para>
1118             </listitem>
1119           </varlistentry>
1120           <varlistentry>
1121             <term><parameter>fields</parameter></term>
1122             <listitem>
1123               <para>A list of fields of the union.
1124               </para>
1125             </listitem>
1126           </varlistentry>
1127         </variablelist>
1128       </refsect1>
1129       <refsect1>
1130         <title>Description</title>
1131         <para>
1132           Defines a foreign union type.
1133         </para>
1134       </refsect1>
1135       <refsect1>
1136         <title>Examples</title>
1137         <programlisting>
1138 (def-union test-union
1139   (a-char :char)
1140   (an-int :int))
1141
1142 (let ((u (allocate-foreign-object 'test-union))
1143   (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
1144   (prog1
1145     (ensure-char-character (get-slot-value u 'test-union 'a-char))
1146     (free-foreign-object u)))
1147 => #\A
1148         </programlisting>
1149       </refsect1>
1150       <refsect1>
1151         <title>Side Effects</title>
1152         <para>Defines a new foreign type.</para>
1153       </refsect1>
1154       <refsect1>
1155         <title>Affected by</title>
1156         <para>None.</para>
1157       </refsect1>
1158       <refsect1>
1159         <title>Exceptional Situations</title>
1160         <para>None.</para>
1161       </refsect1>
1162     </refentry>
1163
1164
1165 </reference>
1166
1167 <reference>
1168     <title>Objects</title>
1169 <partintro>
1170 <title>Overview</title>
1171     <para>
1172       Objects are entities that can allocated, referred to by pointers, and
1173 can be freed.
1174     </para>
1175 </partintro>
1176
1177
1178     <refentry id="allocate-foreign-object">
1179       <refnamediv>
1180         <refname>allocate-foreign-object</refname>
1181         <refpurpose>Allocates an instance of a foreign object.
1182         </refpurpose>
1183         <refclass>Macro</refclass>
1184       </refnamediv>
1185       <refsynopsisdiv>
1186         <title>Syntax</title>
1187         <synopsis>
1188           <function>allocate-foreign-object</function> <replaceable>type &amp;optional size</replaceable> => <returnvalue>ptr</returnvalue>
1189         </synopsis>
1190       </refsynopsisdiv>
1191       <refsect1>
1192         <title>Arguments and Values</title>
1193         <variablelist>
1194           <varlistentry>
1195             <term><parameter>type</parameter></term>
1196             <listitem>
1197               <para>The type of foreign object to allocate. This parameter is evaluated.
1198               </para>
1199             </listitem>
1200           </varlistentry>
1201           <varlistentry>
1202             <term><parameter>size</parameter></term>
1203             <listitem>
1204               <para>An optional size parameter that is evaluated. If specified, allocates and returns an
1205 array of <parameter>type</parameter> that is <parameter>size</parameter> members long. This parameter is evaluated.
1206               </para>
1207             </listitem>
1208           </varlistentry>
1209           <varlistentry>
1210             <term><returnvalue>ptr</returnvalue></term>
1211             <listitem>
1212               <para>A pointer to the foreign object.
1213               </para>
1214             </listitem>
1215           </varlistentry>
1216         </variablelist>
1217       </refsect1>
1218       <refsect1>
1219         <title>Description</title>
1220         <para>
1221           Allocates an instance of a foreign object. It returns a pointer to the object.
1222         </para>
1223       </refsect1>
1224       <refsect1>
1225         <title>Examples</title>
1226         <programlisting>
1227 (def-struct ab (a :int) (b :double))
1228 (allocate-foreign-object 'ab)
1229 => #&lt;ptr&gt;
1230         </programlisting>
1231       </refsect1>
1232       <refsect1>
1233         <title>Side Effects</title>
1234         <para>None.</para>
1235       </refsect1>
1236       <refsect1>
1237         <title>Affected by</title>
1238         <para>None.</para>
1239       </refsect1>
1240       <refsect1>
1241         <title>Exceptional Situations</title>
1242         <para>None.</para>
1243       </refsect1>
1244     </refentry>
1245
1246
1247     <refentry id="free-foreign-object">
1248       <refnamediv>
1249         <refname>free-foreign-object</refname>
1250         <refpurpose>Frees memory that was allocated for a foreign boject.
1251         </refpurpose>
1252         <refclass>Macro</refclass>
1253       </refnamediv>
1254       <refsynopsisdiv>
1255         <title>Syntax</title>
1256         <synopsis>
1257           <function>free-foreign-object</function> <replaceable>ptr</replaceable>
1258         </synopsis>
1259       </refsynopsisdiv>
1260       <refsect1>
1261         <title>Arguments and Values</title>
1262         <variablelist>
1263           <varlistentry>
1264             <term><parameter>ptr</parameter></term>
1265             <listitem>
1266               <para>A pointer to the allocated foreign object to free.
1267               </para>
1268             </listitem>
1269           </varlistentry>
1270         </variablelist>
1271       </refsect1>
1272       <refsect1>
1273         <title>Description</title>
1274         <para>
1275           Frees the memory used by the allocation of a foreign object.
1276         </para>
1277       </refsect1>
1278       <refsect1>
1279         <title>Side Effects</title>
1280         <para>None.</para>
1281       </refsect1>
1282       <refsect1>
1283         <title>Affected by</title>
1284         <para>None.</para>
1285       </refsect1>
1286       <refsect1>
1287         <title>Exceptional Situations</title>
1288         <para>None.</para>
1289       </refsect1>
1290     </refentry>
1291
1292
1293     <refentry id="with-foreign-object">
1294       <refnamediv>
1295         <refname>with-foreign-object</refname>
1296         <refpurpose>Wraps the allocation of a foreign object around a body of code.
1297         </refpurpose>
1298         <refclass>Macro</refclass>
1299       </refnamediv>
1300       <refsynopsisdiv>
1301         <title>Syntax</title>
1302         <synopsis>
1303           <function>with-foreign-object</function> <replaceable>(var type) &amp;body body</replaceable> => <returnvalue>form-return</returnvalue>
1304         </synopsis>
1305       </refsynopsisdiv>
1306       <refsect1>
1307         <title>Arguments and Values</title>
1308         <variablelist>
1309           <varlistentry>
1310             <term><parameter>var</parameter></term>
1311             <listitem>
1312               <para>The variable name to bind.
1313               </para>
1314             </listitem>
1315           </varlistentry>
1316           <varlistentry>
1317             <term><parameter>type</parameter></term>
1318             <listitem>
1319               <para>The type of foreign object to allocate. This parameter is evaluated.
1320               </para>
1321             </listitem>
1322           </varlistentry>
1323           <varlistentry>
1324             <term><returnvalue>form-return</returnvalue></term>
1325             <listitem>
1326               <para>The result of evaluating the <parameter>body</parameter>.
1327               </para>
1328             </listitem>
1329           </varlistentry>
1330         </variablelist>
1331       </refsect1>
1332       <refsect1>
1333         <title>Description</title>
1334         <para>
1335 This function wraps the allocation, binding, and destruction of a foreign object.
1336 On &cmucl; and
1337 &lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
1338 much better with static allocation.
1339         </para>
1340       </refsect1>
1341       <refsect1>
1342         <title>Examples</title>
1343         <programlisting>
1344 (defun gethostname2 ()
1345   "Returns the hostname"
1346   (uffi:with-foreign-object (name '(:array :unsigned-char 256))
1347     (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
1348         (uffi:convert-from-foreign-string name)
1349         (error "gethostname() failed."))))
1350         </programlisting>
1351       </refsect1>
1352       <refsect1>
1353         <title>Side Effects</title>
1354         <para>None.</para>
1355       </refsect1>
1356       <refsect1>
1357         <title>Affected by</title>
1358         <para>None.</para>
1359       </refsect1>
1360       <refsect1>
1361         <title>Exceptional Situations</title>
1362         <para>None.</para>
1363       </refsect1>
1364     </refentry>
1365
1366     <refentry id="size-of-foreign-type">
1367       <refnamediv>
1368         <refname>size-of-foreign-type</refname>
1369         <refpurpose>Returns the number of data bytes used by a foreign object type.
1370         </refpurpose>
1371         <refclass>Macro</refclass>
1372       </refnamediv>
1373       <refsynopsisdiv>
1374         <title>Syntax</title>
1375         <synopsis>
1376           <function>size-of-foreign-type</function> <replaceable>ftype</replaceable>
1377         </synopsis>
1378       </refsynopsisdiv>
1379       <refsect1>
1380         <title>Arguments and Values</title>
1381         <variablelist>
1382           <varlistentry>
1383             <term><parameter>ftype</parameter></term>
1384             <listitem>
1385               <para>A foreign type specifier. This parameter is evaluated.
1386               </para>
1387             </listitem>
1388           </varlistentry>
1389         </variablelist>
1390       </refsect1>
1391       <refsect1>
1392         <title>Description</title>
1393         <para>
1394           Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.
1395         </para>
1396       </refsect1>
1397       <refsect1>
1398         <title>Examples</title>
1399         <para>
1400 <programlisting>
1401 (size-of-foreign-object :unsigned-byte)
1402 => 1
1403 (size-of-foreign-object 'my-100-byte-vector-type)
1404 => 100
1405 </programlisting>
1406         </para>
1407       </refsect1>
1408       <refsect1>
1409         <title>Side Effects</title>
1410         <para>None.</para>
1411       </refsect1>      <refsect1>
1412         <title>Affected by</title>
1413         <para>None.</para>
1414       </refsect1>
1415       <refsect1>
1416         <title>Exceptional Situations</title>
1417         <para>None.</para>
1418       </refsect1>
1419     </refentry>
1420
1421     <refentry id="pointer-address">
1422       <refnamediv>
1423         <refname>pointer-address</refname>
1424         <refpurpose>Returns the address of a pointer.
1425         </refpurpose>
1426         <refclass>Macro</refclass>
1427       </refnamediv>
1428       <refsynopsisdiv>
1429         <title>Syntax</title>
1430         <synopsis>
1431           <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
1432         </synopsis>
1433       </refsynopsisdiv>
1434       <refsect1>
1435         <title>Arguments and Values</title>
1436         <variablelist>
1437           <varlistentry>
1438             <term><parameter>ptr</parameter></term>
1439             <listitem>
1440               <para>A pointer to a foreign object.
1441               </para>
1442             </listitem>
1443           </varlistentry>
1444           <varlistentry>
1445             <term><parameter>address</parameter></term>
1446             <listitem>
1447               <para>An integer representing the pointer's address.
1448               </para>
1449             </listitem>
1450           </varlistentry>
1451         </variablelist>
1452       </refsect1>
1453       <refsect1>
1454         <title>Description</title>
1455         <para>
1456           Returns the address as an integer of a pointer.
1457         </para>
1458       </refsect1>
1459       <refsect1>
1460         <title>Side Effects</title>
1461         <para>None.</para>
1462       </refsect1>
1463       <refsect1>
1464         <title>Affected by</title>
1465         <para>None.</para>
1466       </refsect1>
1467       <refsect1>
1468         <title>Exceptional Situations</title>
1469         <para>None.</para>
1470       </refsect1>
1471     </refentry>
1472
1473
1474     <refentry id="deref-pointer">
1475       <refnamediv>
1476         <refname>deref-pointer</refname>
1477         <refpurpose>Deferences a pointer.
1478         </refpurpose>
1479         <refclass>Macro</refclass>
1480       </refnamediv>
1481       <refsynopsisdiv>
1482         <title>Syntax</title>
1483         <synopsis>
1484           <function>deref-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
1485         </synopsis>
1486       </refsynopsisdiv>
1487       <refsect1>
1488         <title>Arguments and Values</title>
1489         <variablelist>
1490           <varlistentry>
1491             <term><parameter>ptr</parameter></term>
1492             <listitem>
1493               <para>A pointer to a foreign object.
1494               </para>
1495             </listitem>
1496           </varlistentry>
1497           <varlistentry>
1498             <term><parameter>type</parameter></term>
1499             <listitem>
1500               <para>A foreign type of the object being pointed to.
1501               </para>
1502             </listitem>
1503           </varlistentry>
1504           <varlistentry>
1505             <term><returnvalue>value</returnvalue></term>
1506             <listitem>
1507               <para>The value of the object where the pointer points.
1508               </para>
1509             </listitem>
1510           </varlistentry>
1511         </variablelist>
1512       </refsect1>
1513       <refsect1>
1514         <title>Description</title>
1515         <para>
1516           Returns the object to which a pointer points.
1517         </para>
1518       </refsect1>
1519       <refsect1>
1520         <title>Examples</title>
1521         <para>
1522 <programlisting>
1523 (let ((intp (allocate-foreign-object :int)))
1524   (setf (deref-pointer intp :int) 10)
1525   (prog1
1526     (deref-pointer intp :int)
1527     (free-foreign-object intp)))
1528 => 10
1529 </programlisting>
1530         </para>
1531       </refsect1>
1532       <refsect1>
1533         <title>Notes</title>
1534         <para>
1535   The TYPE argument is ignored for CL implementations other than
1536   AllegroCL. If you want to cast a pointer to another type use
1537   WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
1538         </para>
1539       </refsect1>
1540       <refsect1>
1541         <title>Side Effects</title>
1542         <para>None.</para>
1543       </refsect1>
1544       <refsect1>
1545         <title>Affected by</title>
1546         <para>None.</para>
1547       </refsect1>
1548       <refsect1>
1549         <title>Exceptional Situations</title>
1550         <para>None.</para>
1551       </refsect1>
1552     </refentry>
1553
1554     <refentry id="ensure-char-character">
1555       <refnamediv>
1556         <refname>ensure-char-character</refname>
1557         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
1558 a character.
1559         </refpurpose>
1560         <refclass>Macro</refclass>
1561       </refnamediv>
1562       <refsynopsisdiv>
1563         <title>Syntax</title>
1564         <synopsis>
1565           <function>ensure-char-character</function> <replaceable>object</replaceable> => <returnvalue>char</returnvalue>
1566         </synopsis>
1567       </refsynopsisdiv>
1568       <refsect1>
1569         <title>Arguments and Values</title>
1570         <variablelist>
1571           <varlistentry>
1572             <term><parameter>object</parameter></term>
1573             <listitem>
1574               <para>Either a character or a integer specifying a character code.
1575               </para>
1576             </listitem>
1577           </varlistentry>
1578           <varlistentry>
1579             <term><returnvalue>char</returnvalue></term>
1580             <listitem>
1581               <para>A character.
1582               </para>
1583             </listitem>
1584           </varlistentry>
1585         </variablelist>
1586       </refsect1>
1587       <refsect1>
1588         <title>Description</title>
1589         <para>
1590           Ensures that an objects obtained by dereferencing
1591 <constant>:char</constant> and <constant>:unsigned-char</constant>
1592 pointers are a lisp character.
1593         </para>
1594       </refsect1>
1595       <refsect1>
1596         <title>Examples</title>
1597         <para>
1598 <programlisting>
1599 (let ((fs (convert-to-foreign-string "a")))
1600   (prog1
1601     (ensure-char-character (deref-pointer fs :char))
1602     (free-foreign-object fs)))
1603 => #\a
1604 </programlisting>
1605         </para>
1606       </refsect1>
1607       <refsect1>
1608         <title>Side Effects</title>
1609         <para>None.</para>
1610       </refsect1>
1611       <refsect1>
1612         <title>Affected by</title>
1613         <para>None.</para>
1614       </refsect1>
1615       <refsect1>
1616         <title>Exceptional Situations</title>
1617         <para>Depending upon the implementation and what &uffi; expects, this
1618 macro may signal an error if the object is not a character or
1619 integer.</para>
1620       </refsect1>
1621     </refentry>
1622
1623     <refentry id="ensure-char-integer">
1624       <refnamediv>
1625         <refname>ensure-char-integer</refname>
1626         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
1627 an integer.
1628         </refpurpose>
1629         <refclass>Macro</refclass>
1630       </refnamediv>
1631       <refsynopsisdiv>
1632         <title>Syntax</title>
1633         <synopsis>
1634           <function>ensure-char-integer</function> <replaceable>object</replaceable> => <returnvalue>int</returnvalue>
1635         </synopsis>
1636       </refsynopsisdiv>
1637       <refsect1>
1638         <title>Arguments and Values</title>
1639         <variablelist>
1640           <varlistentry>
1641             <term><parameter>object</parameter></term>
1642             <listitem>
1643               <para>Either a character or a integer specifying a character code.
1644               </para>
1645             </listitem>
1646           </varlistentry>
1647           <varlistentry>
1648             <term><returnvalue>int</returnvalue></term>
1649             <listitem>
1650               <para>An integer.
1651               </para>
1652             </listitem>
1653           </varlistentry>
1654         </variablelist>
1655       </refsect1>
1656       <refsect1>
1657         <title>Description</title>
1658         <para>
1659           Ensures that an object obtained by dereferencing a
1660 <constant>:char</constant> pointer is an integer.
1661         </para>
1662       </refsect1>
1663       <refsect1>
1664         <title>Examples</title>
1665         <para>
1666 <programlisting>
1667 (let ((fs (convert-to-foreign-string "a")))
1668   (prog1
1669     (ensure-char-integer (deref-pointer fs :char))
1670     (free-foreign-object fs)))
1671 => 96
1672 </programlisting>
1673         </para>
1674       </refsect1>
1675       <refsect1>
1676         <title>Side Effects</title>
1677         <para>None.</para>
1678       </refsect1>
1679       <refsect1>
1680         <title>Affected by</title>
1681         <para>None.</para>
1682       </refsect1>
1683       <refsect1>
1684         <title>Exceptional Situations</title>
1685         <para>Depending upon the implementation and what &uffi; expects, this
1686 macro may signal an error if the object is not a character or
1687 integer.</para>
1688       </refsect1>
1689     </refentry>
1690
1691     <refentry id="make-null-pointer">
1692       <refnamediv>
1693         <refname>make-null-pointer</refname>
1694         <refpurpose>Create a &null; pointer.
1695         </refpurpose>
1696         <refclass>Macro</refclass>
1697       </refnamediv>
1698       <refsynopsisdiv>
1699         <title>Syntax</title>
1700         <synopsis>
1701           <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
1702         </synopsis>
1703       </refsynopsisdiv>
1704       <refsect1>
1705         <title>Arguments and Values</title>
1706         <variablelist>
1707           <varlistentry>
1708             <term><parameter>type</parameter></term>
1709             <listitem>
1710               <para>A type of object to which the pointer refers.
1711               </para>
1712             </listitem>
1713           </varlistentry>
1714           <varlistentry>
1715             <term><parameter>ptr</parameter></term>
1716             <listitem>
1717               <para>The &null; pointer of type <parameter>type</parameter>.
1718               </para>
1719             </listitem>
1720           </varlistentry>
1721         </variablelist>
1722       </refsect1>
1723       <refsect1>
1724         <title>Description</title>
1725         <para>
1726           Creates a &null; pointer of a specified type.
1727         </para>
1728       </refsect1>
1729       <refsect1>
1730         <title>Side Effects</title>
1731         <para>None.</para>
1732       </refsect1>
1733       <refsect1>
1734         <title>Affected by</title>
1735         <para>None.</para>
1736       </refsect1>
1737       <refsect1>
1738         <title>Exceptional Situations</title>
1739         <para>None.</para>
1740       </refsect1>
1741     </refentry>
1742
1743
1744     <refentry id="null-pointer-p">
1745       <refnamediv>
1746         <refname>null-pointer-p</refname>
1747         <refpurpose>Tests a pointer for &null; value.
1748         </refpurpose>
1749         <refclass>Macro</refclass>
1750       </refnamediv>
1751       <refsynopsisdiv>
1752         <title>Syntax</title>
1753         <synopsis>
1754           <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
1755         </synopsis>
1756       </refsynopsisdiv>
1757       <refsect1>
1758         <title>Arguments and Values</title>
1759         <variablelist>
1760           <varlistentry>
1761             <term><parameter>ptr</parameter></term>
1762             <listitem>
1763               <para>A foreign object pointer.
1764               </para>
1765             </listitem>
1766           </varlistentry>
1767           <varlistentry>
1768             <term><returnvalue>is-null</returnvalue></term>
1769             <listitem>
1770               <para>The boolean flag.
1771               </para>
1772             </listitem>
1773           </varlistentry>
1774         </variablelist>
1775       </refsect1>
1776       <refsect1>
1777         <title>Description</title>
1778         <para>
1779           A predicate testing if a pointer is has a &null; value.
1780         </para>
1781       </refsect1>
1782       <refsect1>
1783         <title>Side Effects</title>
1784         <para>None.</para>
1785       </refsect1>
1786       <refsect1>
1787         <title>Affected by</title>
1788         <para>None.</para>
1789       </refsect1>
1790       <refsect1>
1791         <title>Exceptional Situations</title>
1792         <para>None.</para>
1793       </refsect1>
1794     </refentry>
1795
1796
1797     <refentry id="null-cstring-pointer">
1798       <refnamediv>
1799         <refname>+null-cstring-pointer+</refname>
1800         <refpurpose>A constant &null; cstring pointer.
1801         </refpurpose>
1802         <refclass>Constant</refclass>
1803       </refnamediv>
1804       <refsect1>
1805         <title>Description</title>
1806         <para>
1807           A &null; cstring pointer. This can be used for testing
1808 if a cstring returned by a function is &null;.
1809         </para>
1810       </refsect1>
1811     </refentry>
1812
1813     <refentry id="with-cast-pointer">
1814       <refnamediv>
1815         <refname>with-cast-pointer</refname>
1816         <refpurpose>Wraps a body of code with a pointer cast to a new type.
1817         </refpurpose>
1818         <refclass>Macro</refclass>
1819       </refnamediv>
1820       <refsynopsisdiv>
1821         <title>Syntax</title>
1822         <synopsis>
1823           <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) &amp; body body</replaceable> => <returnvalue>value</returnvalue>
1824         </synopsis>
1825       </refsynopsisdiv>
1826       <refsect1>
1827         <title>Arguments and Values</title>
1828         <variablelist>
1829           <varlistentry>
1830             <term><parameter>ptr</parameter></term>
1831             <listitem>
1832               <para>A pointer to a foreign object.
1833               </para>
1834             </listitem>
1835           </varlistentry>
1836           <varlistentry>
1837             <term><parameter>type</parameter></term>
1838             <listitem>
1839               <para>A foreign type of the object being pointed to.
1840               </para>
1841             </listitem>
1842           </varlistentry>
1843           <varlistentry>
1844             <term><returnvalue>value</returnvalue></term>
1845             <listitem>
1846               <para>The value of the object where the pointer points.
1847               </para>
1848             </listitem>
1849           </varlistentry>
1850         </variablelist>
1851       </refsect1>
1852       <refsect1>
1853         <title>Description</title>
1854         <para>
1855   Executes BODY with POINTER cast to be a pointer to type TYPE. If
1856   BINDING-NAME is provided the cast pointer will be bound to this
1857   name during the execution of BODY. If BINDING-NAME is not provided
1858   POINTER must be a name bound to the pointer which should be
1859   cast. This name will be bound to the cast pointer during the
1860   execution of BODY.
1861
1862   This is a no-op in AllegroCL but will wrap BODY in a LET form if
1863   BINDING-NAME is provided.
1864
1865   This macro is meant to be used in conjunction with DEREF-POINTER or
1866   DEREF-ARRAY. In Allegro CL the "cast" will actually take place in
1867   DEREF-POINTER or DEREF-ARRAY.
1868         </para>
1869       </refsect1>
1870       <refsect1>
1871         <title>Examples</title>
1872 <programlisting>
1873 (with-foreign-object (size :int)
1874    ;; FOO is a foreign function returning a :POINTER-VOID
1875    (let ((memory (foo size)))
1876       (when (mumble)
1877          ;; at this point we know for some reason that MEMORY points
1878          ;; to an array of unsigned bytes
1879          (with-cast-pointer (memory :unsigned-byte)
1880            (dotimes (i (deref-pointer size :int))
1881             (do-something-with
1882               (deref-array memory '(:array :unsigned-byte) i)))))))
1883 </programlisting>
1884       </refsect1>
1885       <refsect1>
1886         <title>Side Effects</title>
1887         <para>None.</para>
1888       </refsect1>
1889       <refsect1>
1890         <title>Affected by</title>
1891         <para>None.</para>
1892       </refsect1>
1893       <refsect1>
1894         <title>Exceptional Situations</title>
1895         <para>None.</para>
1896       </refsect1>
1897     </refentry>
1898
1899     <refentry id="def-foreign-var">
1900       <refnamediv>
1901         <refname>def-foreign-var</refname>
1902         <refpurpose>
1903 Defines a symbol macro to access a variable in foreign code
1904         </refpurpose>
1905         <refclass>Macro</refclass>
1906       </refnamediv>
1907       <refsynopsisdiv>
1908         <title>Syntax</title>
1909         <synopsis>
1910           <function>def-foreign-var</function> <replaceable>name type module</replaceable>
1911         </synopsis>
1912       </refsynopsisdiv>
1913       <refsect1>
1914         <title>Arguments and Values</title>
1915         <variablelist>
1916           <varlistentry>
1917             <term><parameter>name</parameter></term>
1918             <listitem>
1919               <para>
1920 A string or list specificying the symbol macro's name. If it is a
1921      string, that names the foreign variable. A Lisp name is created
1922      by translating #\_ to #\- and by converting to upper-case in
1923      case-insensitive Lisp implementations. If it is a list, the first
1924      item is a string specifying the foreign variable name and the
1925      second it is a symbol stating the Lisp name.
1926               </para>
1927             </listitem>
1928           </varlistentry>
1929           <varlistentry>
1930             <term><parameter>type</parameter></term>
1931             <listitem>
1932               <para>A foreign type of the foreign variable.
1933               </para>
1934             </listitem>
1935           </varlistentry>
1936           <varlistentry>
1937             <term><returnvalue>module</returnvalue></term>
1938             <listitem>
1939               <para>
1940      A string specifying the module (or library) the foreign variable
1941      resides in. (Required by Lispworks)
1942               </para>
1943             </listitem>
1944           </varlistentry>
1945         </variablelist>
1946       </refsect1>
1947       <refsect1>
1948         <title>Description</title>
1949         <para>
1950 Defines a symbol macro which can be used to access (get and set) the
1951 value of a variable in foreign code.
1952         </para>
1953       </refsect1>
1954       <refsect1>
1955         <title>Examples</title>
1956         <refsect2>
1957         <title>C code</title>
1958 <programlisting>
1959   int baz = 3;
1960
1961   typedef struct {
1962     int x;
1963     double y;
1964   } foo_struct;
1965
1966   foo_struct the_struct = { 42, 3.2 };
1967
1968   int foo () {
1969     return baz;
1970   }
1971 </programlisting>
1972 </refsect2>
1973 <refsect2>
1974 <title>Lisp code</title>
1975 <programlisting>
1976   (uffi:def-struct foo-struct
1977     (x :int)
1978     (y :double))
1979
1980   (uffi:def-function ("foo" foo)
1981       ()
1982     :returning :int
1983     :module "foo")
1984
1985   (uffi:def-foreign-var ("baz" *baz*) :int "foo")
1986   (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo")
1987
1988
1989 *baz*
1990   => 3
1991
1992 (incf *baz*)
1993   => 4
1994
1995 (foo)
1996   => 4
1997 </programlisting>
1998 </refsect2>
1999       </refsect1>
2000       <refsect1>
2001         <title>Side Effects</title>
2002         <para>None.</para>
2003       </refsect1>
2004       <refsect1>
2005         <title>Affected by</title>
2006         <para>None.</para>
2007       </refsect1>
2008       <refsect1>
2009         <title>Exceptional Situations</title>
2010         <para>None.</para>
2011       </refsect1>
2012     </refentry>
2013
2014 </reference>
2015
2016     <reference>
2017       <title>Strings</title>
2018 <partintro>
2019 <title>Overview</title>
2020 <para>
2021
2022           &uffi; has functions to two types of
2023 <varname>C</varname>-compatible
2024           strings: <emphasis>cstring</emphasis> and
2025 <emphasis>foreign</emphasis> strings.
2026
2027 cstrings are used <emphasis>only</emphasis> as parameters to and from
2028 functions. In some implementations a cstring is not a foreign type but
2029 rather the Lisp string itself. On other platforms a cstring is a newly
2030 allocated foreign vector for storing characters. The following is an
2031 example of using cstrings to both send and return a value.
2032 </para>
2033
2034 <programlisting>
2035 (uffi:def-function ("getenv" c-getenv)
2036     ((name :cstring))
2037   :returning :cstring)
2038
2039 (defun my-getenv (key)
2040   "Returns an environment variable, or NIL if it does not exist"
2041   (check-type key string)
2042   (uffi:with-cstring (key-native key)
2043     (uffi:convert-from-cstring (c-getenv key-native))))
2044 </programlisting>
2045
2046 <para> In contrast, foreign strings are always a foreign vector of
2047 characters which have memory allocated. Thus, if you need to allocate
2048 memory to hold the return value of a string, you must use a foreign
2049 string and not a cstring.  The following is an example of using a foreign
2050 string for a return value.  </para>
2051
2052 <programlisting>
2053 (uffi:def-function ("gethostname" c-gethostname)
2054     ((name (* :unsigned-char))
2055      (len :int))
2056   :returning :int)
2057
2058 (defun gethostname ()
2059   "Returns the hostname"
2060   (let* ((name (uffi:allocate-foreign-string 256))
2061          (result-code (c-gethostname name 256))
2062          (hostname (when (zerop result-code)
2063                      (uffi:convert-from-foreign-string name))))
2064     (uffi:free-foreign-object name)
2065     (unless (zerop result-code)
2066       (error "gethostname() failed."))))
2067 </programlisting>
2068
2069 <para>  Foreign functions that return pointers to freshly allocated
2070 strings should in general not return cstrings, but foreign strings.
2071 (There is no portable way to release such cstrings from Lisp.)  The
2072 following is an example of handling such a function.  </para>
2073
2074 <programlisting>
2075 (uffi:def-function ("readline" c-readline)
2076     ((prompt :cstring))
2077   :returning (* :char))
2078
2079 (defun readline (prompt)
2080   "Reads a string from console with line-editing."
2081   (with-cstring (c-prompt prompt)
2082       (let* ((c-str (c-readline c-prompt))
2083              (str (convert-from-foreign-string c-str)))
2084         (uffi:free-foreign-object c-str)
2085         str)))
2086 </programlisting>
2087
2088 </partintro>
2089
2090     <refentry id="convert-from-cstring">
2091       <refnamediv>
2092         <refname>convert-from-cstring</refname>
2093         <refpurpose>Converts a cstring to a Lisp string.
2094         </refpurpose>
2095         <refclass>Macro</refclass>
2096       </refnamediv>
2097       <refsynopsisdiv>
2098         <title>Syntax</title>
2099         <synopsis>
2100           <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
2101         </synopsis>
2102       </refsynopsisdiv>
2103       <refsect1>
2104         <title>Arguments and Values</title>
2105         <variablelist>
2106           <varlistentry>
2107             <term><parameter>cstring</parameter></term>
2108             <listitem>
2109               <para>A cstring.
2110               </para>
2111             </listitem>
2112           </varlistentry>
2113           <varlistentry>
2114             <term><returnvalue>string</returnvalue></term>
2115             <listitem>
2116               <para>A Lisp string.
2117               </para>
2118             </listitem>
2119           </varlistentry>
2120         </variablelist>
2121       </refsect1>
2122       <refsect1>
2123         <title>Description</title>
2124         <para>
2125           Converts a Lisp string to a <constant>cstring</constant>. This is
2126 most often used when processing the results of a foreign function
2127 that returns a cstring.
2128         </para>
2129       </refsect1>
2130       <refsect1>
2131         <title>Side Effects</title>
2132         <para>None.</para>
2133       </refsect1>
2134       <refsect1>
2135         <title>Affected by</title>
2136         <para>None.</para>
2137       </refsect1>
2138       <refsect1>
2139         <title>Exceptional Situations</title>
2140         <para>None.</para>
2141       </refsect1>
2142     </refentry>
2143
2144
2145     <refentry id="convert-to-cstring">
2146       <refnamediv>
2147         <refname>convert-to-cstring</refname>
2148         <refpurpose>Converts a Lisp string to a cstring.
2149         </refpurpose>
2150         <refclass>Macro</refclass>
2151       </refnamediv>
2152       <refsynopsisdiv>
2153         <title>Syntax</title>
2154         <synopsis>
2155           <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
2156         </synopsis>
2157       </refsynopsisdiv>
2158       <refsect1>
2159         <title>Arguments and Values</title>
2160         <variablelist>
2161           <varlistentry>
2162             <term><parameter>string</parameter></term>
2163             <listitem>
2164               <para>A Lisp string.
2165               </para>
2166             </listitem>
2167           </varlistentry>
2168           <varlistentry>
2169             <term><returnvalue>cstring</returnvalue></term>
2170             <listitem>
2171               <para>A cstring.
2172               </para>
2173             </listitem>
2174           </varlistentry>
2175         </variablelist>
2176       </refsect1>
2177       <refsect1>
2178         <title>Description</title>
2179         <para>
2180           Converts a Lisp string to a
2181           <varname>cstring</varname>. The
2182           <varname>cstring</varname> should be freed with
2183           <function>free-cstring</function>.
2184         </para>
2185       </refsect1>
2186       <refsect1>
2187         <title>Side Effects</title>
2188         <para>On some implementations, this function allocates memory.</para>
2189       </refsect1>
2190       <refsect1>
2191         <title>Affected by</title>
2192         <para>None.</para>
2193       </refsect1>
2194       <refsect1>
2195         <title>Exceptional Situations</title>
2196         <para>None.</para>
2197       </refsect1>
2198     </refentry>
2199
2200
2201     <refentry id="free-cstring">
2202       <refnamediv>
2203         <refname>free-cstring</refname>
2204         <refpurpose>Free memory used by cstring.
2205         </refpurpose>
2206         <refclass>Macro</refclass>
2207       </refnamediv>
2208       <refsynopsisdiv>
2209         <title>Syntax</title>
2210         <synopsis>
2211           <function>free-cstring</function> <replaceable>cstring</replaceable>
2212         </synopsis>
2213       </refsynopsisdiv>
2214       <refsect1>
2215         <title>Arguments and Values</title>
2216         <variablelist>
2217           <varlistentry>
2218             <term><parameter>cstring</parameter></term>
2219             <listitem>
2220               <para>A cstring.
2221               </para>
2222             </listitem>
2223           </varlistentry>
2224         </variablelist>
2225       </refsect1>
2226       <refsect1>
2227         <title>Description</title>
2228         <para>
2229           Frees any memory possibly allocated by
2230           <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
2231         </para>
2232       </refsect1>
2233       <refsect1>
2234         <title>Side Effects</title>
2235         <para>None.</para>
2236       </refsect1>
2237       <refsect1>
2238         <title>Affected by</title>
2239         <para>None.</para>
2240       </refsect1>
2241       <refsect1>
2242         <title>Exceptional Situations</title>
2243         <para>None.</para>
2244       </refsect1>
2245     </refentry>
2246
2247
2248     <refentry id="with-cstring">
2249       <refnamediv>
2250         <refname>with-cstring</refname>
2251         <refpurpose>Binds a newly created cstring.
2252         </refpurpose>
2253         <refclass>Macro</refclass>
2254       </refnamediv>
2255       <refsynopsisdiv>
2256         <title>Syntax</title>
2257         <synopsis>
2258           <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
2259         </synopsis>
2260       </refsynopsisdiv>
2261       <refsect1>
2262         <title>Arguments and Values</title>
2263         <variablelist>
2264           <varlistentry>
2265             <term><parameter>cstring</parameter></term>
2266             <listitem>
2267               <para>A symbol naming the cstring to be created.
2268               </para>
2269             </listitem>
2270           </varlistentry>
2271           <varlistentry>
2272             <term><parameter>string</parameter></term>
2273             <listitem>
2274               <para>A Lisp string that will be translated to a cstring.
2275               </para>
2276             </listitem>
2277           </varlistentry>
2278           <varlistentry>
2279             <term><parameter>body</parameter></term>
2280             <listitem>
2281               <para>The body of where the cstring will be bound.
2282               </para>
2283             </listitem>
2284           </varlistentry>
2285         </variablelist>
2286       </refsect1>
2287       <refsect1>
2288         <title>Description</title>
2289         <para>
2290           Binds a symbol to a cstring created from conversion of a string. Automatically frees the <varname>cstring</varname>.
2291         </para>
2292       </refsect1>
2293       <refsect1>
2294         <title>Examples</title>
2295         <para>
2296             <programlisting>
2297 (def-function ("getenv" c-getenv)
2298    ((name :cstring))
2299    :returning :cstring)
2300
2301 (defun getenv (key)
2302   "Returns an environment variable, or NIL if it does not exist"
2303   (check-type key string)
2304   (with-cstring (key-cstring key)
2305     (convert-from-cstring (c-getenv key-cstring))))
2306             </programlisting>
2307           </para>
2308         </refsect1>
2309       <refsect1>
2310         <title>Side Effects</title>
2311         <para>None.</para>
2312       </refsect1>
2313       <refsect1>
2314         <title>Affected by</title>
2315         <para>None.</para>
2316       </refsect1>
2317       <refsect1>
2318         <title>Exceptional Situations</title>
2319         <para>None.</para>
2320       </refsect1>
2321     </refentry>
2322
2323
2324     <refentry id="convert-from-foreign-string">
2325       <refnamediv>
2326         <refname>convert-from-foreign-string</refname>
2327         <refpurpose>Converts a foreign string into a Lisp string.
2328         </refpurpose>
2329         <refclass>Macro</refclass>
2330       </refnamediv>
2331       <refsynopsisdiv>
2332         <title>Syntax</title>
2333         <synopsis>
2334           <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
2335         </synopsis>
2336       </refsynopsisdiv>
2337       <refsect1>
2338         <title>Arguments and Values</title>
2339         <variablelist>
2340           <varlistentry>
2341             <term><parameter>foreign-string</parameter></term>
2342             <listitem>
2343               <para>A foreign string.
2344               </para>
2345             </listitem>
2346           </varlistentry>
2347           <varlistentry>
2348             <term><parameter>length</parameter></term>
2349             <listitem>
2350               <para>The length of the foreign string to
2351 convert. The default is the length of the string until a &null;
2352 character is reached.
2353               </para>
2354             </listitem>
2355           </varlistentry>
2356           <varlistentry>
2357             <term><parameter>null-terminated-p</parameter></term>
2358             <listitem>
2359               <para>A boolean flag with a default value of &t; When true,
2360 the string is converted until the first &null; character is reached.
2361               </para>
2362             </listitem>
2363           </varlistentry>
2364           <varlistentry>
2365             <term><returnvalue>string</returnvalue></term>
2366             <listitem>
2367               <para>A Lisp string.
2368               </para>
2369             </listitem>
2370           </varlistentry>
2371         </variablelist>
2372       </refsect1>
2373       <refsect1>
2374         <title>Description</title>
2375         <para>
2376           Returns a Lisp string from a foreign string.
2377 Can translated ASCII and binary strings.
2378         </para>
2379       </refsect1>
2380       <refsect1>
2381         <title>Side Effects</title>
2382         <para>None.</para>
2383       </refsect1>
2384       <refsect1>
2385         <title>Affected by</title>
2386         <para>None.</para>
2387       </refsect1>
2388       <refsect1>
2389         <title>Exceptional Situations</title>
2390         <para>None.</para>
2391       </refsect1>
2392     </refentry>
2393
2394
2395     <refentry id="convert-to-foreign-string">
2396       <refnamediv>
2397         <refname>convert-to-foreign-string</refname>
2398         <refpurpose>Converts a Lisp string to a foreign string.
2399         </refpurpose>
2400         <refclass>Macro</refclass>
2401       </refnamediv>
2402       <refsynopsisdiv>
2403         <title>Syntax</title>
2404         <synopsis>
2405           <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
2406         </synopsis>
2407       </refsynopsisdiv>
2408       <refsect1>
2409         <title>Arguments and Values</title>
2410         <variablelist>
2411           <varlistentry>
2412             <term><parameter>string</parameter></term>
2413             <listitem>
2414               <para>A Lisp string.
2415               </para>
2416             </listitem>
2417           </varlistentry>
2418           <varlistentry>
2419             <term><returnvalue>foreign-string</returnvalue></term>
2420             <listitem>
2421               <para>A foreign string.
2422               </para>
2423             </listitem>
2424           </varlistentry>
2425         </variablelist>
2426       </refsect1>
2427       <refsect1>
2428         <title>Description</title>
2429         <para>
2430           Converts a Lisp string to a foreign string. Memory should be
2431           freed with <function>free-foreign-object</function>.
2432         </para>
2433       </refsect1>
2434       <refsect1>
2435         <title>Side Effects</title>
2436         <para>None.</para>
2437       </refsect1>
2438       <refsect1>
2439         <title>Affected by</title>
2440         <para>None.</para>
2441       </refsect1>
2442       <refsect1>
2443         <title>Exceptional Situations</title>
2444         <para>None.</para>
2445       </refsect1>
2446     </refentry>
2447
2448
2449
2450     <refentry id="allocate-foreign-string">
2451       <refnamediv>
2452         <refname>allocate-foreign-string</refname>
2453         <refpurpose>Allocates space for a foreign string.
2454         </refpurpose>
2455         <refclass>Macro</refclass>
2456       </refnamediv>
2457       <refsynopsisdiv>
2458         <title>Syntax</title>
2459         <synopsis>
2460           <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
2461         </synopsis>
2462       </refsynopsisdiv>
2463       <refsect1>
2464         <title>Arguments and Values</title>
2465         <variablelist>
2466           <varlistentry>
2467             <term><parameter>size</parameter></term>
2468             <listitem>
2469               <para>The size of the space to be allocated in bytes.
2470               </para>
2471             </listitem>
2472           </varlistentry>
2473           <varlistentry>
2474             <term><parameter>unsigned</parameter></term>
2475             <listitem>
2476               <para>A boolean flag with a default value of &t;. When true,
2477 marks the pointer as an <constant>:unsigned-char</constant>.
2478               </para>
2479             </listitem>
2480           </varlistentry>
2481           <varlistentry>
2482             <term><returnvalue>foreign-string</returnvalue></term>
2483             <listitem>
2484               <para>A foreign string which has undefined contents.
2485               </para>
2486             </listitem>
2487           </varlistentry>
2488         </variablelist>
2489       </refsect1>
2490       <refsect1>
2491         <title>Description</title>
2492         <para>
2493           Allocates space for a foreign string. Memory should
2494           be freed with <function>free-foreign-object</function>.
2495         </para>
2496       </refsect1>
2497       <refsect1>
2498         <title>Side Effects</title>
2499         <para>None.</para>
2500       </refsect1>
2501       <refsect1>
2502         <title>Affected by</title>
2503         <para>None.</para>
2504       </refsect1>
2505       <refsect1>
2506         <title>Exceptional Situations</title>
2507         <para>None.</para>
2508       </refsect1>
2509     </refentry>
2510
2511   </reference>
2512
2513   <reference>
2514       <title>Functions &amp; Libraries</title>
2515
2516       <refentry id="def-function">
2517         <refnamediv>
2518           <refname>def-function</refname>
2519         <refpurpose>Declares a function.
2520         </refpurpose>
2521         <refclass>Macro</refclass>
2522       </refnamediv>
2523       <refsynopsisdiv>
2524         <title>Syntax</title>
2525         <synopsis>
2526           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
2527         </synopsis>
2528       </refsynopsisdiv>
2529       <refsect1>
2530         <title>Arguments and Values</title>
2531         <variablelist>
2532           <varlistentry>
2533             <term><parameter>name</parameter></term>
2534             <listitem>
2535               <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.
2536               </para>
2537             </listitem>
2538           </varlistentry>
2539           <varlistentry>
2540             <term><parameter>args</parameter></term>
2541             <listitem>
2542               <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
2543               </para>
2544             </listitem>
2545           </varlistentry>
2546           <varlistentry>
2547             <term><parameter>module</parameter></term>
2548             <listitem>
2549               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
2550             </listitem>
2551           </varlistentry>
2552           <varlistentry>
2553             <term><returnvalue>returning</returnvalue></term>
2554             <listitem>
2555               <para>A declaration specifying the result type of the
2556 foreign function. If <constant>:void</constant> indicates module does not return any value.
2557               </para>
2558             </listitem>
2559           </varlistentry>
2560         </variablelist>
2561       </refsect1>
2562       <refsect1>
2563         <title>Description</title>
2564         <para>Declares a foreign function.
2565         </para>
2566       </refsect1>
2567       <refsect1>
2568         <title>Examples</title>
2569         <programlisting>
2570 (def-function "gethostname"
2571   ((name (* :unsigned-char))
2572    (len :int))
2573   :returning :int)
2574         </programlisting>
2575       </refsect1>
2576       <refsect1>
2577         <title>Side Effects</title>
2578         <para>None.</para>
2579       </refsect1>
2580       <refsect1>
2581         <title>Affected by</title>
2582         <para>None.</para>
2583       </refsect1>
2584       <refsect1>
2585         <title>Exceptional Situations</title>
2586         <para>None.</para>
2587       </refsect1>
2588     </refentry>
2589
2590       <refentry id="load-foreign-library">
2591         <refnamediv>
2592           <refname>load-foreign-library</refname>
2593         <refpurpose>Loads a foreign library.
2594         </refpurpose>
2595         <refclass>Function</refclass>
2596       </refnamediv>
2597       <refsect1>
2598         <title>Syntax</title>
2599 <synopsis>
2600           <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries force-load</replaceable> => <returnvalue>success</returnvalue>
2601 </synopsis>
2602       </refsect1>
2603       <refsect1>
2604         <title>Arguments and Values</title>
2605         <variablelist>
2606           <varlistentry>
2607             <term><parameter>filename</parameter></term>
2608             <listitem>
2609               <para>A string or pathname specifying the library location
2610 in the filesystem. At least one implementation (&lw;) can not
2611 accept a logical pathname.
2612               </para>
2613             </listitem>
2614           </varlistentry>
2615           <varlistentry>
2616             <term><parameter>module</parameter></term>
2617             <listitem>
2618               <para>A string designating the name of the module to apply
2619 to functions in this library. (Required for Lispworks)
2620               </para>
2621             </listitem>
2622           </varlistentry>
2623           <varlistentry>
2624             <term><parameter>supporting-libraries</parameter></term>
2625             <listitem>
2626               <para>A list of strings naming the libraries required to
2627 link the foreign library. (Required by CMUCL)
2628               </para>
2629             </listitem>
2630           </varlistentry>
2631           <varlistentry>
2632             <term><parameter>force-load</parameter></term>
2633             <listitem>
2634               <para>Forces the loading of the library if it has been previously loaded.
2635               </para>
2636             </listitem>
2637           </varlistentry>
2638           <varlistentry>
2639             <term><returnvalue>success</returnvalue></term>
2640             <listitem>
2641               <para>A boolean flag, &t; if the library was able to be
2642 loaded successfully or if the library has been previously loaded,
2643 otherwise &nil;.
2644               </para>
2645             </listitem>
2646           </varlistentry>
2647         </variablelist>
2648       </refsect1>
2649       <refsect1>
2650         <title>Description</title>
2651         <para>Loads a foreign library. Applies a module name to functions
2652 within the library. Ensures that a library is only loaded once during
2653 a session. A library can be reloaded by using the <symbol>:force-load</symbol> key.
2654         </para>
2655       </refsect1>
2656       <refsect1>
2657         <title>Examples</title>
2658         <programlisting>
2659   (load-foreign-library #p"/usr/lib/libmysqlclient.so"
2660                         :module "mysql"
2661                         :supporting-libraries '("c"))
2662     => T
2663         </programlisting>
2664       </refsect1>
2665       <refsect1>
2666         <title>Side Effects</title>
2667         <para>Loads the foreign code into the Lisp system.
2668         </para>
2669       </refsect1>
2670       <refsect1>
2671         <title>Affected by</title>
2672         <para>Ability to load the file.</para>
2673       </refsect1>
2674       <refsect1>
2675         <title>Exceptional Situations</title>
2676         <para>None.</para>
2677       </refsect1>
2678     </refentry>
2679
2680       <refentry id="find-foreign-library">
2681         <refnamediv>
2682           <refname>find-foreign-library</refname>
2683         <refpurpose>Finds a foreign library file.
2684         </refpurpose>
2685         <refclass>Function</refclass>
2686       </refnamediv>
2687       <refsect1>
2688         <title>Syntax</title>
2689 <synopsis>
2690           <function>find-foreign-library</function> <replaceable>names directories &amp; drive-letters types</replaceable> => <returnvalue>path</returnvalue>
2691 </synopsis>
2692       </refsect1>
2693       <refsect1>
2694         <title>Arguments and Values</title>
2695         <variablelist>
2696           <varlistentry>
2697             <term><parameter>names</parameter></term>
2698             <listitem>
2699               <para>A string or list of strings containing the base name of the library file.
2700               </para>
2701             </listitem>
2702           </varlistentry>
2703           <varlistentry>
2704             <term><parameter>directories</parameter></term>
2705             <listitem>
2706               <para>A string or list of strings containing the directory the library file.
2707               </para>
2708             </listitem>
2709           </varlistentry>
2710           <varlistentry>
2711             <term><parameter>drive-letters</parameter></term>
2712             <listitem>
2713               <para>A string or list of strings containing the drive letters for the library file.
2714               </para>
2715             </listitem>
2716           </varlistentry>
2717           <varlistentry>
2718             <term><parameter>types</parameter></term>
2719             <listitem>
2720               <para>A string or list of strings containing the file type of the library file. Default
2721 is &nil;. If &nil;, will use a default type based on the currently running implementation.
2722               </para>
2723             </listitem>
2724           </varlistentry>
2725           <varlistentry>
2726             <term><returnvalue>path</returnvalue></term>
2727             <listitem>
2728               <para>A path containing the path found, or &nil; if the library file was not found.
2729               </para>
2730             </listitem>
2731           </varlistentry>
2732         </variablelist>
2733       </refsect1>
2734       <refsect1>
2735         <title>Description</title>
2736         <para>Finds a foreign library by searching through a number of possible locations. Returns
2737 the path of the first found file.
2738         </para>
2739       </refsect1>
2740       <refsect1>
2741         <title>Examples</title>
2742         <programlisting>
2743 (find-foreign-library '("libmysqlclient" "libmysql")
2744     '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
2745     :types '("so" "dll")
2746     :drive-letters '("C" "D" "E"))
2747 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
2748         </programlisting>
2749       </refsect1>
2750       <refsect1>
2751         <title>Side Effects</title>
2752         <para>None.
2753         </para>
2754       </refsect1>
2755       <refsect1>
2756         <title>Affected by</title>
2757         <para>None.</para>
2758       </refsect1>
2759       <refsect1>
2760         <title>Exceptional Situations</title>
2761         <para>None.</para>
2762       </refsect1>
2763     </refentry>
2764
2765 </reference>
2766
2767
2768 <appendix>
2769   <title>Installation</title>
2770   <sect1>
2771     <title>Download &uffi;</title>
2772     <para>
2773 You need to download the &uffi; package from its web
2774 <ulink url="http://uffi.med-info.com"><citetitle>home</citetitle></ulink>.
2775 You also need to have a copy of &asdf;. If you need a copy of
2776 &asdf;, it is included in the
2777   <ulink
2778       url="http://www.sourceforge.net/projects/cclan">
2779       <citetitle>CCLAN</citetitle></ulink> package. You can download
2780 the file <filename>defsystem.lisp</filename> from the CVS
2781 <ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/asdf.lisp"><citetitle>tree</citetitle></ulink>.
2782     </para>
2783   </sect1>
2784   <sect1>
2785     <title>Installation</title>
2786     <para>
2787       After downloading and installing &asdf;, simply
2788       <function>push</function> the
2789       directory containing &uffi; into
2790       <varname>asdf:*central-registry*</varname> variable. Whenever you
2791 want to load the &uffi; package, use the function
2792       <computeroutput>(asdf:oos 'asdf:load-op :uffi)</computeroutput>.
2793     </para>
2794   </sect1>
2795 </appendix>
2796
2797
2798 <glossary>
2799   <glossentry id="gloss-ffi">
2800     <glossterm>Foreign Function Interface
2801       <acronym>FFI</acronym>)
2802     </glossterm>
2803     <glossdef>
2804       <para>
2805         An interface to a C-compatible library.
2806       </para>
2807     </glossdef>
2808   </glossentry>
2809 </glossary>
2810
2811
2812
2813 </book>