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