doc/ref.xml

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