doc/ref.xml

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