doc/ref.sgml

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