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 </para>
  94           </listitem>
  95           <listitem>
  96             <para><constant>:unsigned-char</constant> - Unsigned 8-bits. A dereferenced :unsigned-char
  97 pointer returns an character.</para>
  98           </listitem>
  99           <listitem>
 100           <listitem>
 101             <para><constant>:byte</constant> - Unsigned 8-bits. A
 102 dereferenced :byte pointer returns an integer.</para>
 103           </listitem>
 104           <listitem>
 105             <para><constant>:short</constant> - Signed 16-bits.</para>
 106           </listitem>
 107           <listitem>
 108             <para><constant>:unsigned-short</constant> - Unsigned 16-bits.</para>
 109           </listitem>
 110           <listitem>
 111             <para><constant>:int</constant> - Signed 32-bits.</para>
 112           </listitem>
 113           <listitem>
 114             <para><constant>:unsigned-int</constant> - Unsigned 32-bits.</para>
 115           </listitem>
 116           <listitem>
 117             <para><constant>:long</constant> - Signed 32-bits.</para>
 118           </listitem>
 119           <listitem>
 120             <para><constant>:unsigned-long</constant> - Unsigned 32-bits.</para>
 121           </listitem>
 122           <listitem>
 123             <para><constant>:float</constant> - 32-bit floating point.</para>
 124           </listitem>
 125           <listitem>
 126             <para><constant>:double</constant> - 64-bit floating point.</para>
 127           </listitem>
 128           <listitem>
 129             <para><constant>:cstring</constant> -
 130 A &null; terminated string used for passing and returning characters strings with a &c; function.
 131             </para>
 132           </listitem>
 133           <listitem>
 134             <para><constant>:void</constant> -
 135 The absence of a value. Used to indicate that a function does not return a value.</para>
 136           </listitem>
 137           <listitem>
 138             <para><constant>:pointer-void</constant> -
 139 Points to a generic object.</para>
 140           </listitem>
 141           <listitem>
 142             <para><constant>*</constant> - Used to declare a pointer to an object</para>
 143           </listitem>
 144         </itemizedlist>
 145       </partintro>
 146
 147       <refentry id="def-constant">
 148         <refnamediv>
 149           <refname>def-constant</refname>
 150         <refpurpose>Binds a symbol to a constant.
 151         </refpurpose>
 152         <refclass>Macro</refclass>
 153       </refnamediv>
 154       <refsynopsisdiv>
 155         <title>Syntax</title>
 156         <synopsis>
 157           <function>def-constant</function> <replaceable>name value &amp;key export</replaceable>
 158         </synopsis>
 159       </refsynopsisdiv>
 160       <refsect1>
 161         <title>Arguments and Values</title>
 162         <variablelist>
 163           <varlistentry>
 164             <term><parameter>name</parameter></term>
 165             <listitem>
 166               <para>A symbol that will be bound to the value.
 167               </para>
 168             </listitem>
 169           </varlistentry>
 170           <varlistentry>
 171             <term><parameter>value</parameter></term>
 172             <listitem>
 173               <para>An evaluated form that is bound the the name.
 174               </para>
 175             </listitem>
 176           </varlistentry>
 177           <varlistentry>
 178             <term><parameter>export</parameter></term>
 179             <listitem>
 180               <para>When &t;, the name is exported from the current package. The default is &nil;</para>
 181             </listitem>
 182           </varlistentry>
 183         </variablelist>
 184       </refsect1>
 185       <refsect1>
 186         <title>Description</title>
 187         <para>
 188           This is a thin wrapper around
 189           <function>defconstant</function>. It evaluates at
 190             compile-time and optionally exports the symbol from the package.
 191         </para>
 192       </refsect1>
 193       <refsect1>
 194         <title>Examples</title>
 195         <programlisting>
 196 (def-constant pi2 (* 2 pi))
 197 (def-constant exported-pi2 (* 2 pi) :export t)
 198         </programlisting>
 199       </refsect1>
 200       <refsect1>
 201         <title>Side Effects</title>
 202         <para>Creates a new special variable..</para>
 203       </refsect1>
 204       <refsect1>
 205         <title>Affected by</title>
 206         <para>None.</para>
 207       </refsect1>
 208       <refsect1>
 209         <title>Exceptional Situations</title>
 210         <para>None.</para>
 211       </refsect1>
 212     </refentry>
 213
 214     <refentry id="def-foreign-type">
 215         <refnamediv>
 216           <refname>def-foreign-type</refname>
 217         <refpurpose>Defines a new foreign type.
 218         </refpurpose>
 219         <refclass>Macro</refclass>
 220       </refnamediv>
 221       <refsect1>
 222         <title>Syntax</title>
 223 <synopsis>
 224           <function>def-foreign-type</function> <replaceable>name type</replaceable>
 225 </synopsis>
 226       </refsect1>
 227       <refsect1>
 228         <title>Arguments and Values</title>
 229         <variablelist>
 230           <varlistentry>
 231             <term><parameter>name</parameter></term>
 232             <listitem>
 233               <para>A symbol naming the new foreign type.
 234               </para>
 235             </listitem>
 236           </varlistentry>
 237           <varlistentry>
 238             <term><parameter>value</parameter></term>
 239             <listitem>
 240               <para>A form that is not evaluated that defines the new
 241 foreign type.
 242               </para>
 243             </listitem>
 244           </varlistentry>
 245         </variablelist>
 246       </refsect1>
 247       <refsect1>
 248         <title>Description</title>
 249         <para>Defines a new foreign type.
 250         </para>
 251       </refsect1>
 252       <refsect1>
 253         <title>Examples</title>
 254         <programlisting>
 255 (def-foreign-type my-generic-pointer :pointer-void)
 256 (def-foreign-type a-double-float :double-float)
 257 (def-foreign-type char-ptr (* :char))
 258         </programlisting>
 259       </refsect1>
 260       <refsect1>
 261         <title>Side Effects</title>
 262         <para>Defines a new foreign type.
 263         </para>
 264       </refsect1>
 265       <refsect1>
 266         <title>Affected by</title>
 267         <para>None.</para>
 268       </refsect1>
 269       <refsect1>
 270         <title>Exceptional Situations</title>
 271         <para>None.</para>
 272       </refsect1>
 273     </refentry>
 274
 275     <refentry id="null-char-p">
 276         <refnamediv>
 277           <refname>null-char-p</refname>
 278         <refpurpose>Tests a character for &null; value.
 279         </refpurpose>
 280         <refclass>Macro</refclass>
 281       </refnamediv>
 282       <refsect1>
 283         <title>Syntax</title>
 284 <synopsis>
 285           <function>null-char-p</function> <replaceable>char</replaceable> => <returnvalue>is-null</returnvalue>
 286 </synopsis>
 287       </refsect1>
 288       <refsect1>
 289         <title>Arguments and Values</title>
 290         <variablelist>
 291           <varlistentry>
 292             <term><parameter>char</parameter></term>
 293             <listitem>
 294               <para>A character or integer.
 295               </para>
 296             </listitem>
 297           </varlistentry>
 298           <varlistentry>
 299             <term><parameter>is-null</parameter></term>
 300             <listitem>
 301               <para>A boolean flag indicating if char is a &null; value.
 302               </para>
 303             </listitem>
 304           </varlistentry>
 305         </variablelist>
 306       </refsect1>
 307       <refsect1>
 308         <title>Description</title>
 309         <para>
 310           A predicate testing if a character or integer is &null;. This
 311 abstracts the difference in implementations where some return a
 312 <computeroutput>character</computeroutput> and some return a
 313 <computeroutput>integer</computeroutput> whence dereferencing a
 314 <computeroutput>C</computeroutput> character pointer.
 315         </para>
 316       </refsect1>
 317       <refsect1>
 318         <title>Examples</title>
 319         <programlisting>
 320 (def-array ca :char)
 321 (let ((fs (convert-to-foreign-string "ab")))
 322    (values (null-char-p (deref-array fs 'ca 0))
 323            (null-char-p (deref-array fs 'ca 2))))
 324 => &nil;
 325    &t;
 326         </programlisting>
 327       </refsect1>
 328       <refsect1>
 329         <title>Side Effects</title>
 330         <para>None.
 331         </para>
 332       </refsect1>
 333       <refsect1>
 334         <title>Affected by</title>
 335         <para>None.</para>
 336       </refsect1>
 337       <refsect1>
 338         <title>Exceptional Situations</title>
 339         <para>None.</para>
 340       </refsect1>
 341     </refentry>
 342   </reference>
 343
 344   <reference>
 345     <title>Aggregate Types</title>
 346     <partintro>
 347       <title>Overview</title>
 348       <para>
 349         Aggregate types are comprised of one or more primitive types.
 350       </para>
 351     </partintro>
 352
 353     <refentry id="def-enum">
 354       <refnamediv>
 355         <refname>def-enum</refname>
 356         <refpurpose>Defines a &c; enumeration.
 357         </refpurpose>
 358         <refclass>Macro</refclass>
 359       </refnamediv>
 360       <refsynopsisdiv>
 361         <title>Syntax</title>
 362         <synopsis>
 363           <function>def-enum</function> <replaceable>name fields &amp;key separator-string</replaceable>
 364         </synopsis>
 365       </refsynopsisdiv>
 366       <refsect1>
 367         <title>Arguments and Values</title>
 368         <variablelist>
 369           <varlistentry>
 370             <term><parameter>name</parameter></term>
 371             <listitem>
 372               <para>A symbol that names the enumeration.
 373               </para>
 374             </listitem>
 375           </varlistentry>
 376           <varlistentry>
 377             <term><parameter>fields</parameter></term>
 378             <listitem>
 379               <para>A list of field defintions. Each definition can be
 380 a symbol or a list of two elements. Symbols get assigned a value of the
 381 current counter which starts at <computeroutput>0</computeroutput> and
 382 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
 383 position is the value to assign the the symbol. The current counter gets set
 384 to <computeroutput>1+</computeroutput> this value.
 385               </para>
 386             </listitem>
 387           </varlistentry>
 388           <varlistentry>
 389             <term><parameter>separator-string</parameter></term>
 390             <listitem>
 391               <para>A string that governs the creation of constants. The
 392 default is <computeroutput>"#"</computeroutput>.</para>
 393             </listitem>
 394           </varlistentry>
 395         </variablelist>
 396       </refsect1>
 397       <refsect1>
 398         <title>Description</title>
 399         <para>
 400           Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
 401 values are created by the <function>concatenation</function> of the
 402 enumeration name, separator-string, and field symbol. Also creates
 403 a foreign type with the name <parameter>name</parameter> of type
 404 <constant>:int</constant>.
 405         </para>
 406       </refsect1>
 407       <refsect1>
 408         <title>Examples</title>
 409         <programlisting>
 410 (def-enum abc (:a :b :c))
 411 ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
 412 ;; the foreign type "abc" to be :int
 413
 414 (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
 415 ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
 416 ;; the foreign type efoo to be :int
 417         </programlisting>
 418       </refsect1>
 419       <refsect1>
 420         <title>Side Effects</title>
 421         <para>Creates a :int foreign type, defines constants.</para>
 422       </refsect1>
 423       <refsect1>
 424         <title>Affected by</title>
 425         <para>None.</para>
 426       </refsect1>
 427       <refsect1>
 428         <title>Exceptional Situations</title>
 429         <para>None.</para>
 430       </refsect1>
 431     </refentry>
 432
 433
 434       <refentry id="def-struct">
 435         <refnamediv>
 436           <refname>def-struct</refname>
 437         <refpurpose>Defines a &c; structure.
 438         </refpurpose>
 439         <refclass>Macro</refclass>
 440       </refnamediv>
 441       <refsynopsisdiv>
 442         <title>Syntax</title>
 443         <synopsis>
 444           <function>def-struct</function> <replaceable>name &amp;rest fields</replaceable>
 445         </synopsis>
 446       </refsynopsisdiv>
 447       <refsect1>
 448         <title>Arguments and Values</title>
 449         <variablelist>
 450           <varlistentry>
 451             <term><parameter>name</parameter></term>
 452             <listitem>
 453               <para>A symbol that names the structure.
 454               </para>
 455             </listitem>
 456           </varlistentry>
 457           <varlistentry>
 458             <term><parameter>fields</parameter></term>
 459             <listitem>
 460               <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
 461               </para>
 462             </listitem>
 463           </varlistentry>
 464         </variablelist>
 465       </refsect1>
 466       <refsect1>
 467         <title>Description</title>
 468         <para>
 469           Declares a structure. A special type is available as a slot
 470 in the field. It is a pointer that points to an instance of the parent
 471 structure. It's type is <constant>:pointer-self</constant>.
 472
 473         </para>
 474       </refsect1>
 475       <refsect1>
 476         <title>Examples</title>
 477         <programlisting>
 478 (def-struct foo (a :unsigned-int)
 479                 (b (* :char))
 480                 (c (:array :int 10))
 481                 (next :pointer-self))
 482         </programlisting>
 483       </refsect1>
 484       <refsect1>
 485         <title>Side Effects</title>
 486         <para>Creates a foreign type.</para>
 487       </refsect1>
 488       <refsect1>
 489         <title>Affected by</title>
 490         <para>None.</para>
 491       </refsect1>
 492       <refsect1>
 493         <title>Exceptional Situations</title>
 494         <para>None.</para>
 495       </refsect1>
 496     </refentry>
 497
 498
 499     <refentry id="get-slot-value">
 500       <refnamediv>
 501         <refname>def-slot-value</refname>
 502         <refpurpose>Retrieves a value from a slot of a structure.
 503         </refpurpose>
 504         <refclass>Macro</refclass>
 505       </refnamediv>
 506       <refsynopsisdiv>
 507         <title>Syntax</title>
 508         <synopsis>
 509           <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
 510         </synopsis>
 511       </refsynopsisdiv>
 512       <refsect1>
 513         <title>Arguments and Values</title>
 514         <variablelist>
 515           <varlistentry>
 516             <term><parameter>obj</parameter></term>
 517             <listitem>
 518               <para>A pointer to foreign structure.
 519               </para>
 520             </listitem>
 521           </varlistentry>
 522           <varlistentry>
 523             <term><parameter>type</parameter></term>
 524             <listitem>
 525               <para>A name of the foreign structure.
 526               </para>
 527             </listitem>
 528           </varlistentry>
 529           <varlistentry>
 530             <term><parameter>field</parameter></term>
 531             <listitem>
 532               <para>A name of the desired field in foreign structure.
 533               </para>
 534             </listitem>
 535           </varlistentry>
 536           <varlistentry>
 537             <term><returnvalue>value</returnvalue></term>
 538             <listitem>
 539               <para>The value of the field in the structure.
 540               </para>
 541             </listitem>
 542           </varlistentry>
 543         </variablelist>
 544       </refsect1>
 545       <refsect1>
 546         <title>Description</title>
 547         <para>
 548           Accesses a slot value from a structure.
 549         </para>
 550       </refsect1>
 551       <refsect1>
 552         <title>Examples</title>
 553         <programlisting>
 554 (get-slot-value foo-ptr 'foo-structure 'field-name)
 555         </programlisting>
 556       </refsect1>
 557       <refsect1>
 558         <title>Side Effects</title>
 559         <para>None.</para>
 560       </refsect1>
 561       <refsect1>
 562         <title>Affected by</title>
 563         <para>None.</para>
 564       </refsect1>
 565       <refsect1>
 566         <title>Exceptional Situations</title>
 567         <para>None.</para>
 568       </refsect1>
 569     </refentry>
 570
 571     <refentry id="get-slot-pointer">
 572       <refnamediv>
 573         <refname>get-slot-pointer</refname>
 574         <refpurpose>Retrieves a pointer from a slot of a structure.
 575         </refpurpose>
 576         <refclass>Macro</refclass>
 577       </refnamediv>
 578       <refsynopsisdiv>
 579         <title>Syntax</title>
 580         <synopsis>
 581           <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
 582         </synopsis>
 583       </refsynopsisdiv>
 584       <refsect1>
 585         <title>Arguments and Values</title>
 586         <variablelist>
 587           <varlistentry>
 588             <term><parameter>obj</parameter></term>
 589             <listitem>
 590               <para>A pointer to foreign structure.
 591               </para>
 592             </listitem>
 593           </varlistentry>
 594           <varlistentry>
 595             <term><parameter>type</parameter></term>
 596             <listitem>
 597               <para>A name of the foreign structure.
 598               </para>
 599             </listitem>
 600           </varlistentry>
 601           <varlistentry>
 602             <term><parameter>field</parameter></term>
 603             <listitem>
 604               <para>A name of the desired field in foreign structure.
 605               </para>
 606             </listitem>
 607           </varlistentry>
 608           <varlistentry>
 609             <term><returnvalue>pointer</returnvalue></term>
 610             <listitem>
 611               <para>The value of the field in the structure.
 612               </para>
 613             </listitem>
 614           </varlistentry>
 615         </variablelist>
 616       </refsect1>
 617       <refsect1>
 618         <title>Description</title>
 619         <para>
 620           This is similar to <function>get-slot-value</function>. It
 621           is used when the value of a slot is a pointer type.
 622         </para>
 623       </refsect1>
 624       <refsect1>
 625         <title>Examples</title>
 626         <programlisting>
 627 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
 628         </programlisting>
 629       </refsect1>
 630       <refsect1>
 631         <title>Side Effects</title>
 632         <para>None.</para>
 633       </refsect1>
 634       <refsect1>
 635         <title>Affected by</title>
 636         <para>None.</para>
 637       </refsect1>
 638       <refsect1>
 639         <title>Exceptional Situations</title>
 640         <para>None.</para>
 641       </refsect1>
 642     </refentry>
 643
 644
 645     <refentry id="def-array">
 646       <refnamediv>
 647         <refname>def-array</refname>
 648         <refpurpose>Defines a foreign array type.
 649         </refpurpose>
 650         <refclass>Macro</refclass>
 651       </refnamediv>
 652       <refsynopsisdiv>
 653         <title>Syntax</title>
 654         <synopsis>
 655           <function>def-array</function> <replaceable>name type</replaceable>
 656         </synopsis>
 657       </refsynopsisdiv>
 658       <refsect1>
 659         <title>Arguments and Values</title>
 660         <variablelist>
 661           <varlistentry>
 662             <term><parameter>name</parameter></term>
 663             <listitem>
 664               <para>A name of the new foreign type.
 665               </para>
 666             </listitem>
 667           </varlistentry>
 668           <varlistentry>
 669             <term><parameter>type</parameter></term>
 670             <listitem>
 671               <para>The foreign type of the array elements.
 672               </para>
 673             </listitem>
 674           </varlistentry>
 675         </variablelist>
 676       </refsect1>
 677       <refsect1>
 678         <title>Description</title>
 679         <para>
 680           Defines a foreign array type.
 681         </para>
 682       </refsect1>
 683       <refsect1>
 684         <title>Examples</title>
 685         <programlisting>
 686 (def-array byte-array :unsigned-char)
 687         </programlisting>
 688       </refsect1>
 689       <refsect1>
 690         <title>Side Effects</title>
 691         <para>Defines a new foreign type.</para>
 692       </refsect1>
 693       <refsect1>
 694         <title>Affected by</title>
 695         <para>None.</para>
 696       </refsect1>
 697       <refsect1>
 698         <title>Exceptional Situations</title>
 699         <para>None.</para>
 700       </refsect1>
 701     </refentry>
 702
 703
 704     <refentry id="deref-array">
 705       <refnamediv>
 706         <refname>deref-array</refname>
 707         <refpurpose>Deference an array.
 708         </refpurpose>
 709         <refclass>Macro</refclass>
 710       </refnamediv>
 711       <refsynopsisdiv>
 712         <title>Syntax</title>
 713         <synopsis>
 714           <function>deref-array</function> <replaceable>array type positon</replaceable> => <returnvalue>value</returnvalue>
 715         </synopsis>
 716       </refsynopsisdiv>
 717       <refsect1>
 718         <title>Arguments and Values</title>
 719         <variablelist>
 720           <varlistentry>
 721             <term><parameter>array</parameter></term>
 722             <listitem>
 723               <para>A foreign array.
 724               </para>
 725             </listitem>
 726           </varlistentry>
 727           <varlistentry>
 728             <term><parameter>type</parameter></term>
 729             <listitem>
 730               <para>The foreign type of the array.
 731               </para>
 732             </listitem>
 733           </varlistentry>
 734           <varlistentry>
 735             <term><parameter>position</parameter></term>
 736             <listitem>
 737               <para>An integer specifying the position to retrieve from
 738 the array.
 739               </para>
 740             </listitem>
 741           </varlistentry>
 742           <varlistentry>
 743             <term><returnvalue>value</returnvalue></term>
 744             <listitem>
 745               <para>The value stored in the position of the array.
 746               </para>
 747             </listitem>
 748           </varlistentry>
 749         </variablelist>
 750       </refsect1>
 751       <refsect1>
 752         <title>Description</title>
 753         <para>
 754           Dereferences (retrieves) the value of an array element.
 755         </para>
 756       </refsect1>
 757       <refsect1>
 758         <title>Examples</title>
 759         <programlisting>
 760 (def-array ca :char)
 761 (let ((fs (convert-to-foreign-string "ab")))
 762    (values (null-char-p (deref-array fs 'ca 0))
 763            (null-char-p (deref-array fs 'ca 2))))
 764 => &nil;
 765    &t;
 766         </programlisting>
 767       </refsect1>
 768       <refsect1>
 769         <title>Side Effects</title>
 770         <para>None.</para>
 771       </refsect1>
 772       <refsect1>
 773         <title>Affected by</title>
 774         <para>None.</para>
 775       </refsect1>
 776       <refsect1>
 777         <title>Exceptional Situations</title>
 778         <para>None.</para>
 779       </refsect1>
 780     </refentry>
 781 </reference>
 782
 783 <reference>
 784     <title>Objects</title>
 785 <partintro>
 786 <title>Overview</title>
 787     <para>
 788       Objects are entities that can allocated and freed.
 789     </para>
 790 </partintro>
 791
 792
 793     <refentry id="allocate-foreign-object">
 794       <refnamediv>
 795         <refname>allocate-foreign-object</refname>
 796         <refpurpose>Allocates an instance of a foreign object.
 797         </refpurpose>
 798         <refclass>Macro</refclass>
 799       </refnamediv>
 800       <refsynopsisdiv>
 801         <title>Syntax</title>
 802         <synopsis>
 803           <function>allocate-foreign-object</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
 804         </synopsis>
 805       </refsynopsisdiv>
 806       <refsect1>
 807         <title>Arguments and Values</title>
 808         <variablelist>
 809           <varlistentry>
 810             <term><parameter>type</parameter></term>
 811             <listitem>
 812               <para>A type of foreign object to allocate.
 813               </para>
 814             </listitem>
 815           </varlistentry>
 816           <varlistentry>
 817             <term><returnvalue>ptr</returnvalue></term>
 818             <listitem>
 819               <para>A pointer to the foreign object.
 820               </para>
 821             </listitem>
 822           </varlistentry>
 823         </variablelist>
 824       </refsect1>
 825       <refsect1>
 826         <title>Description</title>
 827         <para>
 828           Allocates an instance of a foreign object. It returns a pointer to the object.
 829         </para>
 830       </refsect1>
 831       <refsect1>
 832         <title>Examples</title>
 833         <programlisting>
 834 (def-struct ab (a :int) (b :double))
 835 (allocate-foreign-object 'ab)
 836 => #&lt;ptr&gt;
 837         </programlisting>
 838       </refsect1>
 839       <refsect1>
 840         <title>Side Effects</title>
 841         <para>None.</para>
 842       </refsect1>
 843       <refsect1>
 844         <title>Affected by</title>
 845         <para>None.</para>
 846       </refsect1>
 847       <refsect1>
 848         <title>Exceptional Situations</title>
 849         <para>None.</para>
 850       </refsect1>
 851     </refentry>
 852
 853
 854     <refentry id="free-foreign-object">
 855       <refnamediv>
 856         <refname>free-foreign-object</refname>
 857         <refpurpose>Frees memory that was allocated for a foreign boject.
 858         </refpurpose>
 859         <refclass>Macro</refclass>
 860       </refnamediv>
 861       <refsynopsisdiv>
 862         <title>Syntax</title>
 863         <synopsis>
 864           <function>free-foreign-object</function> <replaceable>ptr</replaceable>
 865         </synopsis>
 866       </refsynopsisdiv>
 867       <refsect1>
 868         <title>Arguments and Values</title>
 869         <variablelist>
 870           <varlistentry>
 871             <term><parameter>ptr</parameter></term>
 872             <listitem>
 873               <para>A pointer to the allocated foreign object to free.
 874               </para>
 875             </listitem>
 876           </varlistentry>
 877         </variablelist>
 878       </refsect1>
 879       <refsect1>
 880         <title>Description</title>
 881         <para>
 882           Frees the memory used by the allocation of a foreign object.
 883         </para>
 884       </refsect1>
 885       <refsect1>
 886         <title>Side Effects</title>
 887         <para>None.</para>
 888       </refsect1>
 889       <refsect1>
 890         <title>Affected by</title>
 891         <para>None.</para>
 892       </refsect1>
 893       <refsect1>
 894         <title>Exceptional Situations</title>
 895         <para>None.</para>
 896       </refsect1>
 897     </refentry>
 898
 899
 900     <refentry id="pointer-address">
 901       <refnamediv>
 902         <refname>pointer-address</refname>
 903         <refpurpose>Returns the address of a pointer.
 904         </refpurpose>
 905         <refclass>Macro</refclass>
 906       </refnamediv>
 907       <refsynopsisdiv>
 908         <title>Syntax</title>
 909         <synopsis>
 910           <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
 911         </synopsis>
 912       </refsynopsisdiv>
 913       <refsect1>
 914         <title>Arguments and Values</title>
 915         <variablelist>
 916           <varlistentry>
 917             <term><parameter>ptr</parameter></term>
 918             <listitem>
 919               <para>A pointer to a foreign object.
 920               </para>
 921             </listitem>
 922           </varlistentry>
 923           <varlistentry>
 924             <term><parameter>address</parameter></term>
 925             <listitem>
 926               <para>An integer representing the pointer's address.
 927               </para>
 928             </listitem>
 929           </varlistentry>
 930         </variablelist>
 931       </refsect1>
 932       <refsect1>
 933         <title>Description</title>
 934         <para>
 935           Returns the address as an integer of a pointer.
 936         </para>
 937       </refsect1>
 938       <refsect1>
 939         <title>Side Effects</title>
 940         <para>None.</para>
 941       </refsect1>
 942       <refsect1>
 943         <title>Affected by</title>
 944         <para>None.</para>
 945       </refsect1>
 946       <refsect1>
 947         <title>Exceptional Situations</title>
 948         <para>None.</para>
 949       </refsect1>
 950     </refentry>
 951
 952
 953     <refentry id="deref-pointer">
 954       <refnamediv>
 955         <refname>deref-pointer</refname>
 956         <refpurpose>Deferences a pointer.
 957         </refpurpose>
 958         <refclass>Macro</refclass>
 959       </refnamediv>
 960       <refsynopsisdiv>
 961         <title>Syntax</title>
 962         <synopsis>
 963           <function>def-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
 964         </synopsis>
 965       </refsynopsisdiv>
 966       <refsect1>
 967         <title>Arguments and Values</title>
 968         <variablelist>
 969           <varlistentry>
 970             <term><parameter>ptr</parameter></term>
 971             <listitem>
 972               <para>A pointer to a foreign object.
 973               </para>
 974             </listitem>
 975           </varlistentry>
 976           <varlistentry>
 977             <term><parameter>type</parameter></term>
 978             <listitem>
 979               <para>A foreign type of the object being pointed to.
 980               </para>
 981             </listitem>
 982           </varlistentry>
 983           <varlistentry>
 984             <term><parameter>value</parameter></term>
 985             <listitem>
 986               <para>The value of the object where the pointer points.
 987               </para>
 988             </listitem>
 989           </varlistentry>
 990         </variablelist>
 991       </refsect1>
 992       <refsect1>
 993         <title>Description</title>
 994         <para>
 995           Returns the object to which a pointer points.
 996         </para>
 997       </refsect1>
 998       <refsect1>
 999         <title>Examples</title>
1000         <para>
1001 <programlisting>
1002 (let ((fs (convert-to-foreign-string "a")))
1003   (prog1
1004     (ensure-char (deref-pointer fs :char))
1005     (free-foreign-object fs)))
1006 => #\a
1007 </programlisting>
1008         </para>
1009       </refsect1>
1010       <refsect1>
1011         <title>Side Effects</title>
1012         <para>None.</para>
1013       </refsect1>
1014       <refsect1>
1015         <title>Affected by</title>
1016         <para>None.</para>
1017       </refsect1>
1018       <refsect1>
1019         <title>Exceptional Situations</title>
1020         <para>None.</para>
1021       </refsect1>
1022     </refentry>
1023
1024     <refentry id="make-null-pointer">
1025       <refnamediv>
1026         <refname>make-null-pointer</refname>
1027         <refpurpose>Create a &null; pointer.
1028         </refpurpose>
1029         <refclass>Macro</refclass>
1030       </refnamediv>
1031       <refsynopsisdiv>
1032         <title>Syntax</title>
1033         <synopsis>
1034           <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
1035         </synopsis>
1036       </refsynopsisdiv>
1037       <refsect1>
1038         <title>Arguments and Values</title>
1039         <variablelist>
1040           <varlistentry>
1041             <term><parameter>type</parameter></term>
1042             <listitem>
1043               <para>A type of object to which the pointer refers.
1044               </para>
1045             </listitem>
1046           </varlistentry>
1047           <varlistentry>
1048             <term><parameter>ptr</parameter></term>
1049             <listitem>
1050               <para>The &null; pointer of type <parameter>type</parameter>.
1051               </para>
1052             </listitem>
1053           </varlistentry>
1054         </variablelist>
1055       </refsect1>
1056       <refsect1>
1057         <title>Description</title>
1058         <para>
1059           Creates a &null; pointer of a specified type.
1060         </para>
1061       </refsect1>
1062       <refsect1>
1063         <title>Side Effects</title>
1064         <para>None.</para>
1065       </refsect1>
1066       <refsect1>
1067         <title>Affected by</title>
1068         <para>None.</para>
1069       </refsect1>
1070       <refsect1>
1071         <title>Exceptional Situations</title>
1072         <para>None.</para>
1073       </refsect1>
1074     </refentry>
1075
1076
1077     <refentry id="null-pointer-p">
1078       <refnamediv>
1079         <refname>null-pointer-p</refname>
1080         <refpurpose>Tests a pointer for &null; value.
1081         </refpurpose>
1082         <refclass>Macro</refclass>
1083       </refnamediv>
1084       <refsynopsisdiv>
1085         <title>Syntax</title>
1086         <synopsis>
1087           <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
1088         </synopsis>
1089       </refsynopsisdiv>
1090       <refsect1>
1091         <title>Arguments and Values</title>
1092         <variablelist>
1093           <varlistentry>
1094             <term><parameter>ptr</parameter></term>
1095             <listitem>
1096               <para>A foreign object pointer.
1097               </para>
1098             </listitem>
1099           </varlistentry>
1100           <varlistentry>
1101             <term><returnvalue>is-null</returnvalue></term>
1102             <listitem>
1103               <para>The boolean flag.
1104               </para>
1105             </listitem>
1106           </varlistentry>
1107         </variablelist>
1108       </refsect1>
1109       <refsect1>
1110         <title>Description</title>
1111         <para>
1112           A predicate testing if a pointer is has a &null; value.
1113         </para>
1114       </refsect1>
1115       <refsect1>
1116         <title>Side Effects</title>
1117         <para>None.</para>
1118       </refsect1>
1119       <refsect1>
1120         <title>Affected by</title>
1121         <para>None.</para>
1122       </refsect1>
1123       <refsect1>
1124         <title>Exceptional Situations</title>
1125         <para>None.</para>
1126       </refsect1>
1127     </refentry>
1128
1129
1130     <refentry id="null-cstring-pointer">
1131       <refnamediv>
1132         <refname>+null-cstring-pointer+</refname>
1133         <refpurpose>A constant &null; cstring pointer.
1134         </refpurpose>
1135         <refclass>Constant</refclass>
1136       </refnamediv>
1137       <refsect1>
1138         <title>Description</title>
1139         <para>
1140           A &null; cstring pointer. This can be used for testing
1141 if a cstring returned by a function is &null;.
1142         </para>
1143       </refsect1>
1144     </refentry>
1145
1146 </reference>
1147
1148     <reference>
1149       <title>Strings</title>
1150 <partintro>
1151 <title>Overview</title>
1152 <para>
1153           &uffi; has functions to two types of <varname>C</varname>-compatible
1154           strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
1155 cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
1156 may not convert these to a foreign type for efficiency sake. Thus, it is not
1157 possible to "allocate" a cstring. In contrast, foreign strings
1158 always need to have memory for them.
1159         </para>
1160 </partintro>
1161
1162     <refentry id="convert-from-cstring">
1163       <refnamediv>
1164         <refname>convert-from-cstring</refname>
1165         <refpurpose>Converts a cstring to a Lisp string.
1166         </refpurpose>
1167         <refclass>Macro</refclass>
1168       </refnamediv>
1169       <refsynopsisdiv>
1170         <title>Syntax</title>
1171         <synopsis>
1172           <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
1173         </synopsis>
1174       </refsynopsisdiv>
1175       <refsect1>
1176         <title>Arguments and Values</title>
1177         <variablelist>
1178           <varlistentry>
1179             <term><parameter>cstring</parameter></term>
1180             <listitem>
1181               <para>A cstring.
1182               </para>
1183             </listitem>
1184           </varlistentry>
1185           <varlistentry>
1186             <term><returnvalue>string</returnvalue></term>
1187             <listitem>
1188               <para>A Lisp string.
1189               </para>
1190             </listitem>
1191           </varlistentry>
1192         </variablelist>
1193       </refsect1>
1194       <refsect1>
1195         <title>Description</title>
1196         <para>
1197           Converts a Lisp string to a <constant>cstring</constant>. This is
1198 most often used when processing the results of a foreign function
1199 that returns a cstring.
1200         </para>
1201       </refsect1>
1202       <refsect1>
1203         <title>Side Effects</title>
1204         <para>None.</para>
1205       </refsect1>
1206       <refsect1>
1207         <title>Affected by</title>
1208         <para>None.</para>
1209       </refsect1>
1210       <refsect1>
1211         <title>Exceptional Situations</title>
1212         <para>None.</para>
1213       </refsect1>
1214     </refentry>
1215
1216
1217     <refentry id="convert-to-cstring">
1218       <refnamediv>
1219         <refname>convert-to-cstring</refname>
1220         <refpurpose>Converts a Lisp string to a cstring.
1221         </refpurpose>
1222         <refclass>Macro</refclass>
1223       </refnamediv>
1224       <refsynopsisdiv>
1225         <title>Syntax</title>
1226         <synopsis>
1227           <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
1228         </synopsis>
1229       </refsynopsisdiv>
1230       <refsect1>
1231         <title>Arguments and Values</title>
1232         <variablelist>
1233           <varlistentry>
1234             <term><parameter>string</parameter></term>
1235             <listitem>
1236               <para>A Lisp string.
1237               </para>
1238             </listitem>
1239           </varlistentry>
1240           <varlistentry>
1241             <term><returnvalue>cstring</returnvalue></term>
1242             <listitem>
1243               <para>A cstring.
1244               </para>
1245             </listitem>
1246           </varlistentry>
1247         </variablelist>
1248       </refsect1>
1249       <refsect1>
1250         <title>Description</title>
1251         <para>
1252           Converts a Lisp string to a
1253           <varname>cstring</varname>. The
1254           <varname>cstring</varname> should be freed with
1255           <function>free-cstring</function>.
1256         </para>
1257       </refsect1>
1258       <refsect1>
1259         <title>Side Effects</title>
1260         <para>None.</para>
1261       </refsect1>
1262       <refsect1>
1263         <title>Affected by</title>
1264         <para>None.</para>
1265       </refsect1>
1266       <refsect1>
1267         <title>Exceptional Situations</title>
1268         <para>None.</para>
1269       </refsect1>
1270     </refentry>
1271
1272
1273     <refentry id="free-cstring">
1274       <refnamediv>
1275         <refname>free-cstring</refname>
1276         <refpurpose>Free memory used by cstring.
1277         </refpurpose>
1278         <refclass>Macro</refclass>
1279       </refnamediv>
1280       <refsynopsisdiv>
1281         <title>Syntax</title>
1282         <synopsis>
1283           <function>free-cstring</function> <replaceable>cstring</replaceable>
1284         </synopsis>
1285       </refsynopsisdiv>
1286       <refsect1>
1287         <title>Arguments and Values</title>
1288         <variablelist>
1289           <varlistentry>
1290             <term><parameter>cstring</parameter></term>
1291             <listitem>
1292               <para>A cstring.
1293               </para>
1294             </listitem>
1295           </varlistentry>
1296         </variablelist>
1297       </refsect1>
1298       <refsect1>
1299         <title>Description</title>
1300         <para>
1301           Frees any memory possibly allocated by
1302           <function>convert-to-cstring</function>.
1303         </para>
1304       </refsect1>
1305       <refsect1>
1306         <title>Side Effects</title>
1307         <para>None.</para>
1308       </refsect1>
1309       <refsect1>
1310         <title>Affected by</title>
1311         <para>None.</para>
1312       </refsect1>
1313       <refsect1>
1314         <title>Exceptional Situations</title>
1315         <para>None.</para>
1316       </refsect1>
1317     </refentry>
1318
1319
1320     <refentry id="with-cstring">
1321       <refnamediv>
1322         <refname>with-cstring</refname>
1323         <refpurpose>Binds a newly created cstring.
1324         </refpurpose>
1325         <refclass>Macro</refclass>
1326       </refnamediv>
1327       <refsynopsisdiv>
1328         <title>Syntax</title>
1329         <synopsis>
1330           <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
1331         </synopsis>
1332       </refsynopsisdiv>
1333       <refsect1>
1334         <title>Arguments and Values</title>
1335         <variablelist>
1336           <varlistentry>
1337             <term><parameter>cstring</parameter></term>
1338             <listitem>
1339               <para>A symbol naming the cstring to be created.
1340               </para>
1341             </listitem>
1342           </varlistentry>
1343           <varlistentry>
1344             <term><parameter>string</parameter></term>
1345             <listitem>
1346               <para>A Lisp string that will be translated to a cstring.
1347               </para>
1348             </listitem>
1349           </varlistentry>
1350           <varlistentry>
1351             <term><parameter>body</parameter></term>
1352             <listitem>
1353               <para>The body of where the cstring will be bound.
1354               </para>
1355             </listitem>
1356           </varlistentry>
1357         </variablelist>
1358       </refsect1>
1359       <refsect1>
1360         <title>Description</title>
1361         <para>
1362           Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
1363         </para>
1364       </refsect1>
1365       <refsect1>
1366         <title>Examples</title>
1367         <para>
1368             <programlisting>
1369 (def-function ("getenv" c-getenv)
1370    ((name :cstring))
1371    :returning :cstring)
1372
1373 (defun getenv (key)
1374   "Returns an environment variable, or NIL if it does not exist"
1375   (check-type key string)
1376   (with-cstring (key-cstring key)
1377     (convert-from-cstring (c-getenv key-cstring))))
1378             </programlisting>
1379           </para>
1380         </refsect1>
1381       <refsect1>
1382         <title>Side Effects</title>
1383         <para>None.</para>
1384       </refsect1>
1385       <refsect1>
1386         <title>Affected by</title>
1387         <para>None.</para>
1388       </refsect1>
1389       <refsect1>
1390         <title>Exceptional Situations</title>
1391         <para>None.</para>
1392       </refsect1>
1393     </refentry>
1394
1395
1396     <refentry id="convert-from-foreign-string">
1397       <refnamediv>
1398         <refname>convert-from-foreign-string</refname>
1399         <refpurpose>Converts a foreign string into a Lisp string.
1400         </refpurpose>
1401         <refclass>Macro</refclass>
1402       </refnamediv>
1403       <refsynopsisdiv>
1404         <title>Syntax</title>
1405         <synopsis>
1406           <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
1407         </synopsis>
1408       </refsynopsisdiv>
1409       <refsect1>
1410         <title>Arguments and Values</title>
1411         <variablelist>
1412           <varlistentry>
1413             <term><parameter>foreign-string</parameter></term>
1414             <listitem>
1415               <para>A foreign string.
1416               </para>
1417             </listitem>
1418           </varlistentry>
1419           <varlistentry>
1420             <term><parameter>length</parameter></term>
1421             <listitem>
1422               <para>The length of the foreign string to
1423 convert. The default is the length of the string until a &null;
1424 character is reached.
1425               </para>
1426             </listitem>
1427           </varlistentry>
1428           <varlistentry>
1429             <term><parameter>null-terminated-p</parameter></term>
1430             <listitem>
1431               <para>A boolean flag with a default value of &t; When true,
1432 the string is converted until the first &null; character is reached.
1433               </para>
1434             </listitem>
1435           </varlistentry>
1436           <varlistentry>
1437             <term><returnvalue>string</returnvalue></term>
1438             <listitem>
1439               <para>A Lisp string.
1440               </para>
1441             </listitem>
1442           </varlistentry>
1443         </variablelist>
1444       </refsect1>
1445       <refsect1>
1446         <title>Description</title>
1447         <para>
1448           Returns a Lisp string from a foreign string.
1449 Can translated ASCII and binary strings.
1450         </para>
1451       </refsect1>
1452       <refsect1>
1453         <title>Side Effects</title>
1454         <para>None.</para>
1455       </refsect1>
1456       <refsect1>
1457         <title>Affected by</title>
1458         <para>None.</para>
1459       </refsect1>
1460       <refsect1>
1461         <title>Exceptional Situations</title>
1462         <para>None.</para>
1463       </refsect1>
1464     </refentry>
1465
1466
1467     <refentry id="convert-to-foreign-string">
1468       <refnamediv>
1469         <refname>convert-to-foreign-string</refname>
1470         <refpurpose>Converts a Lisp string to a foreign string.
1471         </refpurpose>
1472         <refclass>Macro</refclass>
1473       </refnamediv>
1474       <refsynopsisdiv>
1475         <title>Syntax</title>
1476         <synopsis>
1477           <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
1478         </synopsis>
1479       </refsynopsisdiv>
1480       <refsect1>
1481         <title>Arguments and Values</title>
1482         <variablelist>
1483           <varlistentry>
1484             <term><parameter>string</parameter></term>
1485             <listitem>
1486               <para>A Lisp string.
1487               </para>
1488             </listitem>
1489           </varlistentry>
1490           <varlistentry>
1491             <term><returnvalue>foreign-string</returnvalue></term>
1492             <listitem>
1493               <para>A foreign string.
1494               </para>
1495             </listitem>
1496           </varlistentry>
1497         </variablelist>
1498       </refsect1>
1499       <refsect1>
1500         <title>Description</title>
1501         <para>
1502           Converts a Lisp string to a foreign string. Memory should be
1503           freed with <function>free-foreign-object</function>.
1504         </para>
1505       </refsect1>
1506       <refsect1>
1507         <title>Side Effects</title>
1508         <para>None.</para>
1509       </refsect1>
1510       <refsect1>
1511         <title>Affected by</title>
1512         <para>None.</para>
1513       </refsect1>
1514       <refsect1>
1515         <title>Exceptional Situations</title>
1516         <para>None.</para>
1517       </refsect1>
1518     </refentry>
1519
1520
1521
1522     <refentry id="allocate-foreign-string">
1523       <refnamediv>
1524         <refname>allocate-foreign-string</refname>
1525         <refpurpose>Allocates space for a foreign string.
1526         </refpurpose>
1527         <refclass>Macro</refclass>
1528       </refnamediv>
1529       <refsynopsisdiv>
1530         <title>Syntax</title>
1531         <synopsis>
1532           <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
1533         </synopsis>
1534       </refsynopsisdiv>
1535       <refsect1>
1536         <title>Arguments and Values</title>
1537         <variablelist>
1538           <varlistentry>
1539             <term><parameter>size</parameter></term>
1540             <listitem>
1541               <para>The size of the space to be allocated in bytes.
1542               </para>
1543             </listitem>
1544           </varlistentry>
1545           <varlistentry>
1546             <term><parameter>unsigned</parameter></term>
1547             <listitem>
1548               <para>A boolean flag with a default value of &t;. When true,
1549 marks the pointer as an <constant>:unsigned-char</constant>.
1550               </para>
1551             </listitem>
1552           </varlistentry>
1553           <varlistentry>
1554             <term><returnvalue>foreign-string</returnvalue></term>
1555             <listitem>
1556               <para>A foreign string which has undefined contents.
1557               </para>
1558             </listitem>
1559           </varlistentry>
1560         </variablelist>
1561       </refsect1>
1562       <refsect1>
1563         <title>Description</title>
1564         <para>
1565           Allocates space for a foreign string. Memory should
1566           be freed with <function>free-foreign-object</function>.
1567         </para>
1568       </refsect1>
1569       <refsect1>
1570         <title>Side Effects</title>
1571         <para>None.</para>
1572       </refsect1>
1573       <refsect1>
1574         <title>Affected by</title>
1575         <para>None.</para>
1576       </refsect1>
1577       <refsect1>
1578         <title>Exceptional Situations</title>
1579         <para>None.</para>
1580       </refsect1>
1581     </refentry>
1582
1583   </reference>
1584
1585   <reference>
1586       <title>Functions &amp; Libraries</title>
1587
1588       <refentry id="def-function">
1589         <refnamediv>
1590           <refname>def-function</refname>
1591         <refpurpose>Declares a function.
1592         </refpurpose>
1593         <refclass>Macro</refclass>
1594       </refnamediv>
1595       <refsynopsisdiv>
1596         <title>Syntax</title>
1597         <synopsis>
1598           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
1599         </synopsis>
1600       </refsynopsisdiv>
1601       <refsect1>
1602         <title>Arguments and Values</title>
1603         <variablelist>
1604           <varlistentry>
1605             <term><parameter>name</parameter></term>
1606             <listitem>
1607               <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.
1608               </para>
1609             </listitem>
1610           </varlistentry>
1611           <varlistentry>
1612             <term><parameter>args</parameter></term>
1613             <listitem>
1614               <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
1615               </para>
1616             </listitem>
1617           </varlistentry>
1618           <varlistentry>
1619             <term><parameter>module</parameter></term>
1620             <listitem>
1621               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
1622             </listitem>
1623           </varlistentry>
1624           <varlistentry>
1625             <term><returnvalue>returning</returnvalue></term>
1626             <listitem>
1627               <para>A declaration specifying the result type of the
1628 foreign function. If <constant>:void</constant> indicates module does not return any value.
1629               </para>
1630             </listitem>
1631           </varlistentry>
1632         </variablelist>
1633       </refsect1>
1634       <refsect1>
1635         <title>Description</title>
1636         <para>Declares a foreign function.
1637         </para>
1638       </refsect1>
1639       <refsect1>
1640         <title>Examples</title>
1641         <programlisting>
1642 (def-function "gethostname"
1643   ((name :cstring)
1644    (len :int))
1645   :returning :int)
1646         </programlisting>
1647       </refsect1>
1648       <refsect1>
1649         <title>Side Effects</title>
1650         <para>None.</para>
1651       </refsect1>
1652       <refsect1>
1653         <title>Affected by</title>
1654         <para>None.</para>
1655       </refsect1>
1656       <refsect1>
1657         <title>Exceptional Situations</title>
1658         <para>None.</para>
1659       </refsect1>
1660     </refentry>
1661
1662       <refentry id="load-foreign-library">
1663         <refnamediv>
1664           <refname>load-foreign-library</refname>
1665         <refpurpose>Loads a foreign library.
1666         </refpurpose>
1667         <refclass>Function</refclass>
1668       </refnamediv>
1669       <refsect1>
1670         <title>Syntax</title>
1671 <synopsis>
1672           <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
1673 </synopsis>
1674       </refsect1>
1675       <refsect1>
1676         <title>Arguments and Values</title>
1677         <variablelist>
1678           <varlistentry>
1679             <term><parameter>filename</parameter></term>
1680             <listitem>
1681               <para>A string or pathname specifying the library location
1682 in the filesystem. At least one implementation (&lw;) can not
1683 accept a logical pathname.
1684               </para>
1685             </listitem>
1686           </varlistentry>
1687           <varlistentry>
1688             <term><parameter>module</parameter></term>
1689             <listitem>
1690               <para>A string designating the name of the module to apply
1691 to functions in this library. (Required for Lispworks)
1692               </para>
1693             </listitem>
1694           </varlistentry>
1695           <varlistentry>
1696             <term><parameter>supporting-libraries</parameter></term>
1697             <listitem>
1698               <para>A list of strings naming the libraries required to
1699 link the foreign library. (Required by CMUCL)
1700               </para>
1701             </listitem>
1702           </varlistentry>
1703           <varlistentry>
1704             <term><returnvalue>success</returnvalue></term>
1705             <listitem>
1706               <para>A boolean flag, &t; if the library was able to be
1707 loaded successfully or if the library has been previously loaded,
1708 otherwise &nil;.
1709               </para>
1710             </listitem>
1711           </varlistentry>
1712         </variablelist>
1713       </refsect1>
1714       <refsect1>
1715         <title>Description</title>
1716         <para>Loads a foreign library. Applies a module name to functions
1717 within the library. Ensures that a library is only loaded once during
1718 a session.
1719         </para>
1720       </refsect1>
1721       <refsect1>
1722         <title>Examples</title>
1723         <programlisting>
1724   (load-foreign-library #p"/usr/lib/libmysqlclient.so"
1725                         :module "mysql"
1726                         :supporting-libraries '("c"))
1727     => T
1728         </programlisting>
1729       </refsect1>
1730       <refsect1>
1731         <title>Side Effects</title>
1732         <para>Loads the foreign code into the Lisp system.
1733         </para>
1734       </refsect1>
1735       <refsect1>
1736         <title>Affected by</title>
1737         <para>Ability to load the file.</para>
1738       </refsect1>
1739       <refsect1>
1740         <title>Exceptional Situations</title>
1741         <para>None.</para>
1742       </refsect1>
1743     </refentry>
1744
1745 </reference>
1746
1747