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