doc/ref.sgml

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