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="size-of-foreign-type">
1054       <refnamediv>
1055         <refname>size-of-foreign-type</refname>
1056         <refpurpose>Returns the number of data bytes used by a foreign object type.
1057         </refpurpose>
1058         <refclass>Macro</refclass>
1059       </refnamediv>
1060       <refsynopsisdiv>
1061         <title>Syntax</title>
1062         <synopsis>
1063           <function>size-of-foreign-type</function> <replaceable>ftype</replaceable>
1064         </synopsis>
1065       </refsynopsisdiv>
1066       <refsect1>
1067         <title>Arguments and Values</title>
1068         <variablelist>
1069           <varlistentry>
1070             <term><parameter>ftype</parameter></term>
1071             <listitem>
1072               <para>A foreign type specifier. This parameter is evaluated.
1073               </para>
1074             </listitem>
1075           </varlistentry>
1076         </variablelist>
1077       </refsect1>
1078       <refsect1>
1079         <title>Description</title>
1080         <para>
1081           Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.
1082         </para>
1083       </refsect1>
1084       <refsect1>
1085         <title>Examples</title>
1086         <para>
1087 <programlisting>
1088 (size-of-foreign-object :unsigned-byte)
1089 => 1
1090 (size-of-foreign-object 'my-100-byte-vector-type)
1091 => 100
1092 </programlisting>
1093         </para>
1094       </refsect1>
1095       <refsect1>
1096         <title>Side Effects</title>
1097         <para>None.</para>
1098       </refsect1>      <refsect1>
1099         <title>Affected by</title>
1100         <para>None.</para>
1101       </refsect1>
1102       <refsect1>
1103         <title>Exceptional Situations</title>
1104         <para>None.</para>
1105       </refsect1>
1106     </refentry>
1107
1108     <refentry id="pointer-address">
1109       <refnamediv>
1110         <refname>pointer-address</refname>
1111         <refpurpose>Returns the address of a pointer.
1112         </refpurpose>
1113         <refclass>Macro</refclass>
1114       </refnamediv>
1115       <refsynopsisdiv>
1116         <title>Syntax</title>
1117         <synopsis>
1118           <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
1119         </synopsis>
1120       </refsynopsisdiv>
1121       <refsect1>
1122         <title>Arguments and Values</title>
1123         <variablelist>
1124           <varlistentry>
1125             <term><parameter>ptr</parameter></term>
1126             <listitem>
1127               <para>A pointer to a foreign object.
1128               </para>
1129             </listitem>
1130           </varlistentry>
1131           <varlistentry>
1132             <term><parameter>address</parameter></term>
1133             <listitem>
1134               <para>An integer representing the pointer's address.
1135               </para>
1136             </listitem>
1137           </varlistentry>
1138         </variablelist>
1139       </refsect1>
1140       <refsect1>
1141         <title>Description</title>
1142         <para>
1143           Returns the address as an integer of a pointer.
1144         </para>
1145       </refsect1>
1146       <refsect1>
1147         <title>Side Effects</title>
1148         <para>None.</para>
1149       </refsect1>
1150       <refsect1>
1151         <title>Affected by</title>
1152         <para>None.</para>
1153       </refsect1>
1154       <refsect1>
1155         <title>Exceptional Situations</title>
1156         <para>None.</para>
1157       </refsect1>
1158     </refentry>
1159
1160
1161     <refentry id="deref-pointer">
1162       <refnamediv>
1163         <refname>deref-pointer</refname>
1164         <refpurpose>Deferences a pointer.
1165         </refpurpose>
1166         <refclass>Macro</refclass>
1167       </refnamediv>
1168       <refsynopsisdiv>
1169         <title>Syntax</title>
1170         <synopsis>
1171           <function>deref-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
1172         </synopsis>
1173       </refsynopsisdiv>
1174       <refsect1>
1175         <title>Arguments and Values</title>
1176         <variablelist>
1177           <varlistentry>
1178             <term><parameter>ptr</parameter></term>
1179             <listitem>
1180               <para>A pointer to a foreign object.
1181               </para>
1182             </listitem>
1183           </varlistentry>
1184           <varlistentry>
1185             <term><parameter>type</parameter></term>
1186             <listitem>
1187               <para>A foreign type of the object being pointed to.
1188               </para>
1189             </listitem>
1190           </varlistentry>
1191           <varlistentry>
1192             <term><returnvalue>value</returnvalue></term>
1193             <listitem>
1194               <para>The value of the object where the pointer points.
1195               </para>
1196             </listitem>
1197           </varlistentry>
1198         </variablelist>
1199       </refsect1>
1200       <refsect1>
1201         <title>Description</title>
1202         <para>
1203           Returns the object to which a pointer points.
1204         </para>
1205       </refsect1>
1206       <refsect1>
1207         <title>Examples</title>
1208         <para>
1209 <programlisting>
1210 (let ((intp (allocate-foreign-object :int)))
1211   (setf (deref-pointer intp :int) 10)
1212   (prog1
1213     (deref-pointer intp :int)
1214     (free-foreign-object intp)))
1215 => 10
1216 </programlisting>
1217         </para>
1218       </refsect1>
1219       <refsect1>
1220         <title>Side Effects</title>
1221         <para>None.</para>
1222       </refsect1>
1223       <refsect1>
1224         <title>Affected by</title>
1225         <para>None.</para>
1226       </refsect1>
1227       <refsect1>
1228         <title>Exceptional Situations</title>
1229         <para>None.</para>
1230       </refsect1>
1231     </refentry>
1232
1233     <refentry id="ensure-char-character">
1234       <refnamediv>
1235         <refname>ensure-char-character</refname>
1236         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
1237 a character.
1238         </refpurpose>
1239         <refclass>Macro</refclass>
1240       </refnamediv>
1241       <refsynopsisdiv>
1242         <title>Syntax</title>
1243         <synopsis>
1244           <function>ensure-char-character</function> <replaceable>object</replaceable> => <returnvalue>char</returnvalue>
1245         </synopsis>
1246       </refsynopsisdiv>
1247       <refsect1>
1248         <title>Arguments and Values</title>
1249         <variablelist>
1250           <varlistentry>
1251             <term><parameter>object</parameter></term>
1252             <listitem>
1253               <para>Either a character or a integer specifying a character code.
1254               </para>
1255             </listitem>
1256           </varlistentry>
1257           <varlistentry>
1258             <term><returnvalue>char</returnvalue></term>
1259             <listitem>
1260               <para>A character.
1261               </para>
1262             </listitem>
1263           </varlistentry>
1264         </variablelist>
1265       </refsect1>
1266       <refsect1>
1267         <title>Description</title>
1268         <para>
1269           Ensures that an object obtained by dereferencing a
1270 <constant>:char</constant> pointer is a character.
1271         </para>
1272       </refsect1>
1273       <refsect1>
1274         <title>Examples</title>
1275         <para>
1276 <programlisting>
1277 (let ((fs (convert-to-foreign-string "a")))
1278   (prog1
1279     (ensure-char-character (deref-pointer fs :char))
1280     (free-foreign-object fs)))
1281 => #\a
1282 </programlisting>
1283         </para>
1284       </refsect1>
1285       <refsect1>
1286         <title>Side Effects</title>
1287         <para>None.</para>
1288       </refsect1>
1289       <refsect1>
1290         <title>Affected by</title>
1291         <para>None.</para>
1292       </refsect1>
1293       <refsect1>
1294         <title>Exceptional Situations</title>
1295         <para>Depending upon the implementation and what &uffi; expects, this
1296 macro may signal an error if the object is not a character or
1297 integer.</para>
1298       </refsect1>
1299     </refentry>
1300
1301     <refentry id="ensure-char-integer">
1302       <refnamediv>
1303         <refname>ensure-char-integer</refname>
1304         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
1305 an integer.
1306         </refpurpose>
1307         <refclass>Macro</refclass>
1308       </refnamediv>
1309       <refsynopsisdiv>
1310         <title>Syntax</title>
1311         <synopsis>
1312           <function>ensure-char-integer</function> <replaceable>object</replaceable> => <returnvalue>int</returnvalue>
1313         </synopsis>
1314       </refsynopsisdiv>
1315       <refsect1>
1316         <title>Arguments and Values</title>
1317         <variablelist>
1318           <varlistentry>
1319             <term><parameter>object</parameter></term>
1320             <listitem>
1321               <para>Either a character or a integer specifying a character code.
1322               </para>
1323             </listitem>
1324           </varlistentry>
1325           <varlistentry>
1326             <term><returnvalue>int</returnvalue></term>
1327             <listitem>
1328               <para>An integer.
1329               </para>
1330             </listitem>
1331           </varlistentry>
1332         </variablelist>
1333       </refsect1>
1334       <refsect1>
1335         <title>Description</title>
1336         <para>
1337           Ensures that an object obtained by dereferencing a
1338 <constant>:char</constant> pointer is an integer.
1339         </para>
1340       </refsect1>
1341       <refsect1>
1342         <title>Examples</title>
1343         <para>
1344 <programlisting>
1345 (let ((fs (convert-to-foreign-string "a")))
1346   (prog1
1347     (ensure-char-integer (deref-pointer fs :char))
1348     (free-foreign-object fs)))
1349 => 96
1350 </programlisting>
1351         </para>
1352       </refsect1>
1353       <refsect1>
1354         <title>Side Effects</title>
1355         <para>None.</para>
1356       </refsect1>
1357       <refsect1>
1358         <title>Affected by</title>
1359         <para>None.</para>
1360       </refsect1>
1361       <refsect1>
1362         <title>Exceptional Situations</title>
1363         <para>Depending upon the implementation and what &uffi; expects, this
1364 macro may signal an error if the object is not a character or
1365 integer.</para>
1366       </refsect1>
1367     </refentry>
1368
1369     <refentry id="make-null-pointer">
1370       <refnamediv>
1371         <refname>make-null-pointer</refname>
1372         <refpurpose>Create a &null; pointer.
1373         </refpurpose>
1374         <refclass>Macro</refclass>
1375       </refnamediv>
1376       <refsynopsisdiv>
1377         <title>Syntax</title>
1378         <synopsis>
1379           <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
1380         </synopsis>
1381       </refsynopsisdiv>
1382       <refsect1>
1383         <title>Arguments and Values</title>
1384         <variablelist>
1385           <varlistentry>
1386             <term><parameter>type</parameter></term>
1387             <listitem>
1388               <para>A type of object to which the pointer refers.
1389               </para>
1390             </listitem>
1391           </varlistentry>
1392           <varlistentry>
1393             <term><parameter>ptr</parameter></term>
1394             <listitem>
1395               <para>The &null; pointer of type <parameter>type</parameter>.
1396               </para>
1397             </listitem>
1398           </varlistentry>
1399         </variablelist>
1400       </refsect1>
1401       <refsect1>
1402         <title>Description</title>
1403         <para>
1404           Creates a &null; pointer of a specified type.
1405         </para>
1406       </refsect1>
1407       <refsect1>
1408         <title>Side Effects</title>
1409         <para>None.</para>
1410       </refsect1>
1411       <refsect1>
1412         <title>Affected by</title>
1413         <para>None.</para>
1414       </refsect1>
1415       <refsect1>
1416         <title>Exceptional Situations</title>
1417         <para>None.</para>
1418       </refsect1>
1419     </refentry>
1420
1421
1422     <refentry id="null-pointer-p">
1423       <refnamediv>
1424         <refname>null-pointer-p</refname>
1425         <refpurpose>Tests a pointer for &null; value.
1426         </refpurpose>
1427         <refclass>Macro</refclass>
1428       </refnamediv>
1429       <refsynopsisdiv>
1430         <title>Syntax</title>
1431         <synopsis>
1432           <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
1433         </synopsis>
1434       </refsynopsisdiv>
1435       <refsect1>
1436         <title>Arguments and Values</title>
1437         <variablelist>
1438           <varlistentry>
1439             <term><parameter>ptr</parameter></term>
1440             <listitem>
1441               <para>A foreign object pointer.
1442               </para>
1443             </listitem>
1444           </varlistentry>
1445           <varlistentry>
1446             <term><returnvalue>is-null</returnvalue></term>
1447             <listitem>
1448               <para>The boolean flag.
1449               </para>
1450             </listitem>
1451           </varlistentry>
1452         </variablelist>
1453       </refsect1>
1454       <refsect1>
1455         <title>Description</title>
1456         <para>
1457           A predicate testing if a pointer is has a &null; value.
1458         </para>
1459       </refsect1>
1460       <refsect1>
1461         <title>Side Effects</title>
1462         <para>None.</para>
1463       </refsect1>
1464       <refsect1>
1465         <title>Affected by</title>
1466         <para>None.</para>
1467       </refsect1>
1468       <refsect1>
1469         <title>Exceptional Situations</title>
1470         <para>None.</para>
1471       </refsect1>
1472     </refentry>
1473
1474
1475     <refentry id="null-cstring-pointer">
1476       <refnamediv>
1477         <refname>+null-cstring-pointer+</refname>
1478         <refpurpose>A constant &null; cstring pointer.
1479         </refpurpose>
1480         <refclass>Constant</refclass>
1481       </refnamediv>
1482       <refsect1>
1483         <title>Description</title>
1484         <para>
1485           A &null; cstring pointer. This can be used for testing
1486 if a cstring returned by a function is &null;.
1487         </para>
1488       </refsect1>
1489     </refentry>
1490
1491 </reference>
1492
1493     <reference>
1494       <title>Strings</title>
1495 <partintro>
1496 <title>Overview</title>
1497 <para>
1498
1499           &uffi; has functions to two types of
1500 <varname>C</varname>-compatible
1501           strings: <emphasis>cstring</emphasis> and
1502 <emphasis>foreign</emphasis> strings.
1503
1504 cstrings are used <emphasis>only</emphasis> as parameters to and from
1505 functions. In some implementations a cstring is not a foreign type but
1506 rather the Lisp string itself. On other platforms a cstring is a newly
1507 allocated foreign vector for storing characters. The following is an
1508 example of using cstrings to both send and return a value.
1509 </para>
1510
1511 <programlisting>
1512 (uffi:def-function ("getenv" c-getenv)
1513     ((name :cstring))
1514   :returning :cstring)
1515
1516 (defun my-getenv (key)
1517   "Returns an environment variable, or NIL if it does not exist"
1518   (check-type key string)
1519   (uffi:with-cstring (key-native key)
1520     (uffi:convert-from-cstring (c-getenv key-native))))
1521 </programlisting>
1522
1523 <para> In contrast, foreign strings are always a foreign vector of
1524 characters which have memory allocated. Thus, if you need to allocate
1525 memory to hold the return value of a string, you must use a foreign
1526 string and not a cstring.  The following is an example of using a foreign
1527 string for a return value.  </para>
1528
1529 <programlisting>
1530 (uffi:def-function ("gethostname" c-gethostname)
1531     ((name (* :unsigned-char))
1532      (len :int))
1533   :returning :int)
1534
1535 (defun gethostname ()
1536   "Returns the hostname"
1537   (let* ((name (uffi:allocate-foreign-string 256))
1538          (result-code (c-gethostname name 256))
1539          (hostname (when (zerop result-code)
1540                      (uffi:convert-from-foreign-string name))))
1541     (uffi:free-foreign-object name)
1542     (unless (zerop result-code)
1543       (error "gethostname() failed."))))
1544 </programlisting>
1545
1546 <para>  Foreign functions that return pointers to freshly allocated
1547 strings should in general not return cstrings, but foreign strings.
1548 (There is no portable way to release such cstrings from Lisp.)  The
1549 following is an example of handling such a function.  </para>
1550
1551 <programlisting>
1552 (uffi:def-function ("readline" c-readline)
1553     ((prompt :cstring))
1554   :returning (* :char))
1555
1556 (defun readline (prompt)
1557   "Reads a string from console with line-editing."
1558   (with-cstring (c-prompt prompt)
1559       (let* ((c-str (c-readline c-prompt))
1560              (str (convert-from-foreign-string c-str)))
1561         (uffi:free-foreign-object c-str)
1562         str)))
1563 </programlisting>
1564
1565 </partintro>
1566
1567     <refentry id="convert-from-cstring">
1568       <refnamediv>
1569         <refname>convert-from-cstring</refname>
1570         <refpurpose>Converts a cstring to a Lisp string.
1571         </refpurpose>
1572         <refclass>Macro</refclass>
1573       </refnamediv>
1574       <refsynopsisdiv>
1575         <title>Syntax</title>
1576         <synopsis>
1577           <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
1578         </synopsis>
1579       </refsynopsisdiv>
1580       <refsect1>
1581         <title>Arguments and Values</title>
1582         <variablelist>
1583           <varlistentry>
1584             <term><parameter>cstring</parameter></term>
1585             <listitem>
1586               <para>A cstring.
1587               </para>
1588             </listitem>
1589           </varlistentry>
1590           <varlistentry>
1591             <term><returnvalue>string</returnvalue></term>
1592             <listitem>
1593               <para>A Lisp string.
1594               </para>
1595             </listitem>
1596           </varlistentry>
1597         </variablelist>
1598       </refsect1>
1599       <refsect1>
1600         <title>Description</title>
1601         <para>
1602           Converts a Lisp string to a <constant>cstring</constant>. This is
1603 most often used when processing the results of a foreign function
1604 that returns a cstring.
1605         </para>
1606       </refsect1>
1607       <refsect1>
1608         <title>Side Effects</title>
1609         <para>None.</para>
1610       </refsect1>
1611       <refsect1>
1612         <title>Affected by</title>
1613         <para>None.</para>
1614       </refsect1>
1615       <refsect1>
1616         <title>Exceptional Situations</title>
1617         <para>None.</para>
1618       </refsect1>
1619     </refentry>
1620
1621
1622     <refentry id="convert-to-cstring">
1623       <refnamediv>
1624         <refname>convert-to-cstring</refname>
1625         <refpurpose>Converts a Lisp string to a cstring.
1626         </refpurpose>
1627         <refclass>Macro</refclass>
1628       </refnamediv>
1629       <refsynopsisdiv>
1630         <title>Syntax</title>
1631         <synopsis>
1632           <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
1633         </synopsis>
1634       </refsynopsisdiv>
1635       <refsect1>
1636         <title>Arguments and Values</title>
1637         <variablelist>
1638           <varlistentry>
1639             <term><parameter>string</parameter></term>
1640             <listitem>
1641               <para>A Lisp string.
1642               </para>
1643             </listitem>
1644           </varlistentry>
1645           <varlistentry>
1646             <term><returnvalue>cstring</returnvalue></term>
1647             <listitem>
1648               <para>A cstring.
1649               </para>
1650             </listitem>
1651           </varlistentry>
1652         </variablelist>
1653       </refsect1>
1654       <refsect1>
1655         <title>Description</title>
1656         <para>
1657           Converts a Lisp string to a
1658           <varname>cstring</varname>. The
1659           <varname>cstring</varname> should be freed with
1660           <function>free-cstring</function>.
1661         </para>
1662       </refsect1>
1663       <refsect1>
1664         <title>Side Effects</title>
1665         <para>On some implementations, this function allocates memory.</para>
1666       </refsect1>
1667       <refsect1>
1668         <title>Affected by</title>
1669         <para>None.</para>
1670       </refsect1>
1671       <refsect1>
1672         <title>Exceptional Situations</title>
1673         <para>None.</para>
1674       </refsect1>
1675     </refentry>
1676
1677
1678     <refentry id="free-cstring">
1679       <refnamediv>
1680         <refname>free-cstring</refname>
1681         <refpurpose>Free memory used by cstring.
1682         </refpurpose>
1683         <refclass>Macro</refclass>
1684       </refnamediv>
1685       <refsynopsisdiv>
1686         <title>Syntax</title>
1687         <synopsis>
1688           <function>free-cstring</function> <replaceable>cstring</replaceable>
1689         </synopsis>
1690       </refsynopsisdiv>
1691       <refsect1>
1692         <title>Arguments and Values</title>
1693         <variablelist>
1694           <varlistentry>
1695             <term><parameter>cstring</parameter></term>
1696             <listitem>
1697               <para>A cstring.
1698               </para>
1699             </listitem>
1700           </varlistentry>
1701         </variablelist>
1702       </refsect1>
1703       <refsect1>
1704         <title>Description</title>
1705         <para>
1706           Frees any memory possibly allocated by
1707           <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
1708         </para>
1709       </refsect1>
1710       <refsect1>
1711         <title>Side Effects</title>
1712         <para>None.</para>
1713       </refsect1>
1714       <refsect1>
1715         <title>Affected by</title>
1716         <para>None.</para>
1717       </refsect1>
1718       <refsect1>
1719         <title>Exceptional Situations</title>
1720         <para>None.</para>
1721       </refsect1>
1722     </refentry>
1723
1724
1725     <refentry id="with-cstring">
1726       <refnamediv>
1727         <refname>with-cstring</refname>
1728         <refpurpose>Binds a newly created cstring.
1729         </refpurpose>
1730         <refclass>Macro</refclass>
1731       </refnamediv>
1732       <refsynopsisdiv>
1733         <title>Syntax</title>
1734         <synopsis>
1735           <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
1736         </synopsis>
1737       </refsynopsisdiv>
1738       <refsect1>
1739         <title>Arguments and Values</title>
1740         <variablelist>
1741           <varlistentry>
1742             <term><parameter>cstring</parameter></term>
1743             <listitem>
1744               <para>A symbol naming the cstring to be created.
1745               </para>
1746             </listitem>
1747           </varlistentry>
1748           <varlistentry>
1749             <term><parameter>string</parameter></term>
1750             <listitem>
1751               <para>A Lisp string that will be translated to a cstring.
1752               </para>
1753             </listitem>
1754           </varlistentry>
1755           <varlistentry>
1756             <term><parameter>body</parameter></term>
1757             <listitem>
1758               <para>The body of where the cstring will be bound.
1759               </para>
1760             </listitem>
1761           </varlistentry>
1762         </variablelist>
1763       </refsect1>
1764       <refsect1>
1765         <title>Description</title>
1766         <para>
1767           Binds a symbol to a cstring created from conversion of a string. Automatically frees the <varname>cstring</varname>.
1768         </para>
1769       </refsect1>
1770       <refsect1>
1771         <title>Examples</title>
1772         <para>
1773             <programlisting>
1774 (def-function ("getenv" c-getenv)
1775    ((name :cstring))
1776    :returning :cstring)
1777
1778 (defun getenv (key)
1779   "Returns an environment variable, or NIL if it does not exist"
1780   (check-type key string)
1781   (with-cstring (key-cstring key)
1782     (convert-from-cstring (c-getenv key-cstring))))
1783             </programlisting>
1784           </para>
1785         </refsect1>
1786       <refsect1>
1787         <title>Side Effects</title>
1788         <para>None.</para>
1789       </refsect1>
1790       <refsect1>
1791         <title>Affected by</title>
1792         <para>None.</para>
1793       </refsect1>
1794       <refsect1>
1795         <title>Exceptional Situations</title>
1796         <para>None.</para>
1797       </refsect1>
1798     </refentry>
1799
1800
1801     <refentry id="convert-from-foreign-string">
1802       <refnamediv>
1803         <refname>convert-from-foreign-string</refname>
1804         <refpurpose>Converts a foreign string into a Lisp string.
1805         </refpurpose>
1806         <refclass>Macro</refclass>
1807       </refnamediv>
1808       <refsynopsisdiv>
1809         <title>Syntax</title>
1810         <synopsis>
1811           <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
1812         </synopsis>
1813       </refsynopsisdiv>
1814       <refsect1>
1815         <title>Arguments and Values</title>
1816         <variablelist>
1817           <varlistentry>
1818             <term><parameter>foreign-string</parameter></term>
1819             <listitem>
1820               <para>A foreign string.
1821               </para>
1822             </listitem>
1823           </varlistentry>
1824           <varlistentry>
1825             <term><parameter>length</parameter></term>
1826             <listitem>
1827               <para>The length of the foreign string to
1828 convert. The default is the length of the string until a &null;
1829 character is reached.
1830               </para>
1831             </listitem>
1832           </varlistentry>
1833           <varlistentry>
1834             <term><parameter>null-terminated-p</parameter></term>
1835             <listitem>
1836               <para>A boolean flag with a default value of &t; When true,
1837 the string is converted until the first &null; character is reached.
1838               </para>
1839             </listitem>
1840           </varlistentry>
1841           <varlistentry>
1842             <term><returnvalue>string</returnvalue></term>
1843             <listitem>
1844               <para>A Lisp string.
1845               </para>
1846             </listitem>
1847           </varlistentry>
1848         </variablelist>
1849       </refsect1>
1850       <refsect1>
1851         <title>Description</title>
1852         <para>
1853           Returns a Lisp string from a foreign string.
1854 Can translated ASCII and binary strings.
1855         </para>
1856       </refsect1>
1857       <refsect1>
1858         <title>Side Effects</title>
1859         <para>None.</para>
1860       </refsect1>
1861       <refsect1>
1862         <title>Affected by</title>
1863         <para>None.</para>
1864       </refsect1>
1865       <refsect1>
1866         <title>Exceptional Situations</title>
1867         <para>None.</para>
1868       </refsect1>
1869     </refentry>
1870
1871
1872     <refentry id="convert-to-foreign-string">
1873       <refnamediv>
1874         <refname>convert-to-foreign-string</refname>
1875         <refpurpose>Converts a Lisp string to a foreign string.
1876         </refpurpose>
1877         <refclass>Macro</refclass>
1878       </refnamediv>
1879       <refsynopsisdiv>
1880         <title>Syntax</title>
1881         <synopsis>
1882           <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
1883         </synopsis>
1884       </refsynopsisdiv>
1885       <refsect1>
1886         <title>Arguments and Values</title>
1887         <variablelist>
1888           <varlistentry>
1889             <term><parameter>string</parameter></term>
1890             <listitem>
1891               <para>A Lisp string.
1892               </para>
1893             </listitem>
1894           </varlistentry>
1895           <varlistentry>
1896             <term><returnvalue>foreign-string</returnvalue></term>
1897             <listitem>
1898               <para>A foreign string.
1899               </para>
1900             </listitem>
1901           </varlistentry>
1902         </variablelist>
1903       </refsect1>
1904       <refsect1>
1905         <title>Description</title>
1906         <para>
1907           Converts a Lisp string to a foreign string. Memory should be
1908           freed with <function>free-foreign-object</function>.
1909         </para>
1910       </refsect1>
1911       <refsect1>
1912         <title>Side Effects</title>
1913         <para>None.</para>
1914       </refsect1>
1915       <refsect1>
1916         <title>Affected by</title>
1917         <para>None.</para>
1918       </refsect1>
1919       <refsect1>
1920         <title>Exceptional Situations</title>
1921         <para>None.</para>
1922       </refsect1>
1923     </refentry>
1924
1925
1926
1927     <refentry id="allocate-foreign-string">
1928       <refnamediv>
1929         <refname>allocate-foreign-string</refname>
1930         <refpurpose>Allocates space for a foreign string.
1931         </refpurpose>
1932         <refclass>Macro</refclass>
1933       </refnamediv>
1934       <refsynopsisdiv>
1935         <title>Syntax</title>
1936         <synopsis>
1937           <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
1938         </synopsis>
1939       </refsynopsisdiv>
1940       <refsect1>
1941         <title>Arguments and Values</title>
1942         <variablelist>
1943           <varlistentry>
1944             <term><parameter>size</parameter></term>
1945             <listitem>
1946               <para>The size of the space to be allocated in bytes.
1947               </para>
1948             </listitem>
1949           </varlistentry>
1950           <varlistentry>
1951             <term><parameter>unsigned</parameter></term>
1952             <listitem>
1953               <para>A boolean flag with a default value of &t;. When true,
1954 marks the pointer as an <constant>:unsigned-char</constant>.
1955               </para>
1956             </listitem>
1957           </varlistentry>
1958           <varlistentry>
1959             <term><returnvalue>foreign-string</returnvalue></term>
1960             <listitem>
1961               <para>A foreign string which has undefined contents.
1962               </para>
1963             </listitem>
1964           </varlistentry>
1965         </variablelist>
1966       </refsect1>
1967       <refsect1>
1968         <title>Description</title>
1969         <para>
1970           Allocates space for a foreign string. Memory should
1971           be freed with <function>free-foreign-object</function>.
1972         </para>
1973       </refsect1>
1974       <refsect1>
1975         <title>Side Effects</title>
1976         <para>None.</para>
1977       </refsect1>
1978       <refsect1>
1979         <title>Affected by</title>
1980         <para>None.</para>
1981       </refsect1>
1982       <refsect1>
1983         <title>Exceptional Situations</title>
1984         <para>None.</para>
1985       </refsect1>
1986     </refentry>
1987
1988   </reference>
1989
1990   <reference>
1991       <title>Functions &amp; Libraries</title>
1992
1993       <refentry id="def-function">
1994         <refnamediv>
1995           <refname>def-function</refname>
1996         <refpurpose>Declares a function.
1997         </refpurpose>
1998         <refclass>Macro</refclass>
1999       </refnamediv>
2000       <refsynopsisdiv>
2001         <title>Syntax</title>
2002         <synopsis>
2003           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
2004         </synopsis>
2005       </refsynopsisdiv>
2006       <refsect1>
2007         <title>Arguments and Values</title>
2008         <variablelist>
2009           <varlistentry>
2010             <term><parameter>name</parameter></term>
2011             <listitem>
2012               <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.
2013               </para>
2014             </listitem>
2015           </varlistentry>
2016           <varlistentry>
2017             <term><parameter>args</parameter></term>
2018             <listitem>
2019               <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
2020               </para>
2021             </listitem>
2022           </varlistentry>
2023           <varlistentry>
2024             <term><parameter>module</parameter></term>
2025             <listitem>
2026               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
2027             </listitem>
2028           </varlistentry>
2029           <varlistentry>
2030             <term><returnvalue>returning</returnvalue></term>
2031             <listitem>
2032               <para>A declaration specifying the result type of the
2033 foreign function. If <constant>:void</constant> indicates module does not return any value.
2034               </para>
2035             </listitem>
2036           </varlistentry>
2037         </variablelist>
2038       </refsect1>
2039       <refsect1>
2040         <title>Description</title>
2041         <para>Declares a foreign function.
2042         </para>
2043       </refsect1>
2044       <refsect1>
2045         <title>Examples</title>
2046         <programlisting>
2047 (def-function "gethostname"
2048   ((name (* :unsigned-char))
2049    (len :int))
2050   :returning :int)
2051         </programlisting>
2052       </refsect1>
2053       <refsect1>
2054         <title>Side Effects</title>
2055         <para>None.</para>
2056       </refsect1>
2057       <refsect1>
2058         <title>Affected by</title>
2059         <para>None.</para>
2060       </refsect1>
2061       <refsect1>
2062         <title>Exceptional Situations</title>
2063         <para>None.</para>
2064       </refsect1>
2065     </refentry>
2066
2067       <refentry id="load-foreign-library">
2068         <refnamediv>
2069           <refname>load-foreign-library</refname>
2070         <refpurpose>Loads a foreign library.
2071         </refpurpose>
2072         <refclass>Function</refclass>
2073       </refnamediv>
2074       <refsect1>
2075         <title>Syntax</title>
2076 <synopsis>
2077           <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
2078 </synopsis>
2079       </refsect1>
2080       <refsect1>
2081         <title>Arguments and Values</title>
2082         <variablelist>
2083           <varlistentry>
2084             <term><parameter>filename</parameter></term>
2085             <listitem>
2086               <para>A string or pathname specifying the library location
2087 in the filesystem. At least one implementation (&lw;) can not
2088 accept a logical pathname.
2089               </para>
2090             </listitem>
2091           </varlistentry>
2092           <varlistentry>
2093             <term><parameter>module</parameter></term>
2094             <listitem>
2095               <para>A string designating the name of the module to apply
2096 to functions in this library. (Required for Lispworks)
2097               </para>
2098             </listitem>
2099           </varlistentry>
2100           <varlistentry>
2101             <term><parameter>supporting-libraries</parameter></term>
2102             <listitem>
2103               <para>A list of strings naming the libraries required to
2104 link the foreign library. (Required by CMUCL)
2105               </para>
2106             </listitem>
2107           </varlistentry>
2108           <varlistentry>
2109             <term><returnvalue>success</returnvalue></term>
2110             <listitem>
2111               <para>A boolean flag, &t; if the library was able to be
2112 loaded successfully or if the library has been previously loaded,
2113 otherwise &nil;.
2114               </para>
2115             </listitem>
2116           </varlistentry>
2117         </variablelist>
2118       </refsect1>
2119       <refsect1>
2120         <title>Description</title>
2121         <para>Loads a foreign library. Applies a module name to functions
2122 within the library. Ensures that a library is only loaded once during
2123 a session.
2124         </para>
2125       </refsect1>
2126       <refsect1>
2127         <title>Examples</title>
2128         <programlisting>
2129   (load-foreign-library #p"/usr/lib/libmysqlclient.so"
2130                         :module "mysql"
2131                         :supporting-libraries '("c"))
2132     => T
2133         </programlisting>
2134       </refsect1>
2135       <refsect1>
2136         <title>Side Effects</title>
2137         <para>Loads the foreign code into the Lisp system.
2138         </para>
2139       </refsect1>
2140       <refsect1>
2141         <title>Affected by</title>
2142         <para>Ability to load the file.</para>
2143       </refsect1>
2144       <refsect1>
2145         <title>Exceptional Situations</title>
2146         <para>None.</para>
2147       </refsect1>
2148     </refentry>
2149
2150       <refentry id="find-foreign-library">
2151         <refnamediv>
2152           <refname>find-foreign-library</refname>
2153         <refpurpose>Finds a foreign library file.
2154         </refpurpose>
2155         <refclass>Function</refclass>
2156       </refnamediv>
2157       <refsect1>
2158         <title>Syntax</title>
2159 <synopsis>
2160           <function>find-foreign-library</function> <replaceable>names directories &amp; drive-letters types</replaceable> => <returnvalue>path</returnvalue>
2161 </synopsis>
2162       </refsect1>
2163       <refsect1>
2164         <title>Arguments and Values</title>
2165         <variablelist>
2166           <varlistentry>
2167             <term><parameter>names</parameter></term>
2168             <listitem>
2169               <para>A string or list of strings containing the base name of the library file.
2170               </para>
2171             </listitem>
2172           </varlistentry>
2173           <varlistentry>
2174             <term><parameter>directories</parameter></term>
2175             <listitem>
2176               <para>A string or list of strings containing the directory the library file.
2177               </para>
2178             </listitem>
2179           </varlistentry>
2180           <varlistentry>
2181             <term><parameter>drive-letters</parameter></term>
2182             <listitem>
2183               <para>A string or list of strings containing the drive letters for the library file.
2184               </para>
2185             </listitem>
2186           </varlistentry>
2187           <varlistentry>
2188             <term><parameter>types</parameter></term>
2189             <listitem>
2190               <para>A string or list of strings containing the file type of the library file. Default
2191 is &nil;. If &nil;, will use a default type based on the currently running implementation.
2192               </para>
2193             </listitem>
2194           </varlistentry>
2195           <varlistentry>
2196             <term><returnvalue>path</returnvalue></term>
2197             <listitem>
2198               <para>A path containing the path found, or &nil; if the library file was not found.
2199               </para>
2200             </listitem>
2201           </varlistentry>
2202         </variablelist>
2203       </refsect1>
2204       <refsect1>
2205         <title>Description</title>
2206         <para>Finds a foreign library by searching through a number of possible locations. Returns
2207 the path of the first found file.
2208         </para>
2209       </refsect1>
2210       <refsect1>
2211         <title>Examples</title>
2212         <programlisting>
2213 (find-foreign-library '("libmysqlclient" "libmysql")
2214     '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
2215     :types '("so" "dll")
2216     :drive-letters '("C" "D" "E"))
2217 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
2218         </programlisting>
2219       </refsect1>
2220       <refsect1>
2221         <title>Side Effects</title>
2222         <para>None.
2223         </para>
2224       </refsect1>
2225       <refsect1>
2226         <title>Affected by</title>
2227         <para>None.</para>
2228       </refsect1>
2229       <refsect1>
2230         <title>Exceptional Situations</title>
2231         <para>None.</para>
2232       </refsect1>
2233     </refentry>
2234
2235 </reference>
2236
2237