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 </partintro>
1547
1548     <refentry id="convert-from-cstring">
1549       <refnamediv>
1550         <refname>convert-from-cstring</refname>
1551         <refpurpose>Converts a cstring to a Lisp string.
1552         </refpurpose>
1553         <refclass>Macro</refclass>
1554       </refnamediv>
1555       <refsynopsisdiv>
1556         <title>Syntax</title>
1557         <synopsis>
1558           <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
1559         </synopsis>
1560       </refsynopsisdiv>
1561       <refsect1>
1562         <title>Arguments and Values</title>
1563         <variablelist>
1564           <varlistentry>
1565             <term><parameter>cstring</parameter></term>
1566             <listitem>
1567               <para>A cstring.
1568               </para>
1569             </listitem>
1570           </varlistentry>
1571           <varlistentry>
1572             <term><returnvalue>string</returnvalue></term>
1573             <listitem>
1574               <para>A Lisp string.
1575               </para>
1576             </listitem>
1577           </varlistentry>
1578         </variablelist>
1579       </refsect1>
1580       <refsect1>
1581         <title>Description</title>
1582         <para>
1583           Converts a Lisp string to a <constant>cstring</constant>. This is
1584 most often used when processing the results of a foreign function
1585 that returns a cstring.
1586         </para>
1587       </refsect1>
1588       <refsect1>
1589         <title>Side Effects</title>
1590         <para>None.</para>
1591       </refsect1>
1592       <refsect1>
1593         <title>Affected by</title>
1594         <para>None.</para>
1595       </refsect1>
1596       <refsect1>
1597         <title>Exceptional Situations</title>
1598         <para>None.</para>
1599       </refsect1>
1600     </refentry>
1601
1602
1603     <refentry id="convert-to-cstring">
1604       <refnamediv>
1605         <refname>convert-to-cstring</refname>
1606         <refpurpose>Converts a Lisp string to a cstring.
1607         </refpurpose>
1608         <refclass>Macro</refclass>
1609       </refnamediv>
1610       <refsynopsisdiv>
1611         <title>Syntax</title>
1612         <synopsis>
1613           <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
1614         </synopsis>
1615       </refsynopsisdiv>
1616       <refsect1>
1617         <title>Arguments and Values</title>
1618         <variablelist>
1619           <varlistentry>
1620             <term><parameter>string</parameter></term>
1621             <listitem>
1622               <para>A Lisp string.
1623               </para>
1624             </listitem>
1625           </varlistentry>
1626           <varlistentry>
1627             <term><returnvalue>cstring</returnvalue></term>
1628             <listitem>
1629               <para>A cstring.
1630               </para>
1631             </listitem>
1632           </varlistentry>
1633         </variablelist>
1634       </refsect1>
1635       <refsect1>
1636         <title>Description</title>
1637         <para>
1638           Converts a Lisp string to a
1639           <varname>cstring</varname>. The
1640           <varname>cstring</varname> should be freed with
1641           <function>free-cstring</function>.
1642         </para>
1643       </refsect1>
1644       <refsect1>
1645         <title>Side Effects</title>
1646         <para>On some implementations, this function allocates memory.</para>
1647       </refsect1>
1648       <refsect1>
1649         <title>Affected by</title>
1650         <para>None.</para>
1651       </refsect1>
1652       <refsect1>
1653         <title>Exceptional Situations</title>
1654         <para>None.</para>
1655       </refsect1>
1656     </refentry>
1657
1658
1659     <refentry id="free-cstring">
1660       <refnamediv>
1661         <refname>free-cstring</refname>
1662         <refpurpose>Free memory used by cstring.
1663         </refpurpose>
1664         <refclass>Macro</refclass>
1665       </refnamediv>
1666       <refsynopsisdiv>
1667         <title>Syntax</title>
1668         <synopsis>
1669           <function>free-cstring</function> <replaceable>cstring</replaceable>
1670         </synopsis>
1671       </refsynopsisdiv>
1672       <refsect1>
1673         <title>Arguments and Values</title>
1674         <variablelist>
1675           <varlistentry>
1676             <term><parameter>cstring</parameter></term>
1677             <listitem>
1678               <para>A cstring.
1679               </para>
1680             </listitem>
1681           </varlistentry>
1682         </variablelist>
1683       </refsect1>
1684       <refsect1>
1685         <title>Description</title>
1686         <para>
1687           Frees any memory possibly allocated by
1688           <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
1689         </para>
1690       </refsect1>
1691       <refsect1>
1692         <title>Side Effects</title>
1693         <para>None.</para>
1694       </refsect1>
1695       <refsect1>
1696         <title>Affected by</title>
1697         <para>None.</para>
1698       </refsect1>
1699       <refsect1>
1700         <title>Exceptional Situations</title>
1701         <para>None.</para>
1702       </refsect1>
1703     </refentry>
1704
1705
1706     <refentry id="with-cstring">
1707       <refnamediv>
1708         <refname>with-cstring</refname>
1709         <refpurpose>Binds a newly created cstring.
1710         </refpurpose>
1711         <refclass>Macro</refclass>
1712       </refnamediv>
1713       <refsynopsisdiv>
1714         <title>Syntax</title>
1715         <synopsis>
1716           <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
1717         </synopsis>
1718       </refsynopsisdiv>
1719       <refsect1>
1720         <title>Arguments and Values</title>
1721         <variablelist>
1722           <varlistentry>
1723             <term><parameter>cstring</parameter></term>
1724             <listitem>
1725               <para>A symbol naming the cstring to be created.
1726               </para>
1727             </listitem>
1728           </varlistentry>
1729           <varlistentry>
1730             <term><parameter>string</parameter></term>
1731             <listitem>
1732               <para>A Lisp string that will be translated to a cstring.
1733               </para>
1734             </listitem>
1735           </varlistentry>
1736           <varlistentry>
1737             <term><parameter>body</parameter></term>
1738             <listitem>
1739               <para>The body of where the cstring will be bound.
1740               </para>
1741             </listitem>
1742           </varlistentry>
1743         </variablelist>
1744       </refsect1>
1745       <refsect1>
1746         <title>Description</title>
1747         <para>
1748           Binds a symbol to a cstring created from conversion of a string. Automatically frees the <varname>cstring</varname>.
1749         </para>
1750       </refsect1>
1751       <refsect1>
1752         <title>Examples</title>
1753         <para>
1754             <programlisting>
1755 (def-function ("getenv" c-getenv)
1756    ((name :cstring))
1757    :returning :cstring)
1758
1759 (defun getenv (key)
1760   "Returns an environment variable, or NIL if it does not exist"
1761   (check-type key string)
1762   (with-cstring (key-cstring key)
1763     (convert-from-cstring (c-getenv key-cstring))))
1764             </programlisting>
1765           </para>
1766         </refsect1>
1767       <refsect1>
1768         <title>Side Effects</title>
1769         <para>None.</para>
1770       </refsect1>
1771       <refsect1>
1772         <title>Affected by</title>
1773         <para>None.</para>
1774       </refsect1>
1775       <refsect1>
1776         <title>Exceptional Situations</title>
1777         <para>None.</para>
1778       </refsect1>
1779     </refentry>
1780
1781
1782     <refentry id="convert-from-foreign-string">
1783       <refnamediv>
1784         <refname>convert-from-foreign-string</refname>
1785         <refpurpose>Converts a foreign string into a Lisp string.
1786         </refpurpose>
1787         <refclass>Macro</refclass>
1788       </refnamediv>
1789       <refsynopsisdiv>
1790         <title>Syntax</title>
1791         <synopsis>
1792           <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
1793         </synopsis>
1794       </refsynopsisdiv>
1795       <refsect1>
1796         <title>Arguments and Values</title>
1797         <variablelist>
1798           <varlistentry>
1799             <term><parameter>foreign-string</parameter></term>
1800             <listitem>
1801               <para>A foreign string.
1802               </para>
1803             </listitem>
1804           </varlistentry>
1805           <varlistentry>
1806             <term><parameter>length</parameter></term>
1807             <listitem>
1808               <para>The length of the foreign string to
1809 convert. The default is the length of the string until a &null;
1810 character is reached.
1811               </para>
1812             </listitem>
1813           </varlistentry>
1814           <varlistentry>
1815             <term><parameter>null-terminated-p</parameter></term>
1816             <listitem>
1817               <para>A boolean flag with a default value of &t; When true,
1818 the string is converted until the first &null; character is reached.
1819               </para>
1820             </listitem>
1821           </varlistentry>
1822           <varlistentry>
1823             <term><returnvalue>string</returnvalue></term>
1824             <listitem>
1825               <para>A Lisp string.
1826               </para>
1827             </listitem>
1828           </varlistentry>
1829         </variablelist>
1830       </refsect1>
1831       <refsect1>
1832         <title>Description</title>
1833         <para>
1834           Returns a Lisp string from a foreign string.
1835 Can translated ASCII and binary strings.
1836         </para>
1837       </refsect1>
1838       <refsect1>
1839         <title>Side Effects</title>
1840         <para>None.</para>
1841       </refsect1>
1842       <refsect1>
1843         <title>Affected by</title>
1844         <para>None.</para>
1845       </refsect1>
1846       <refsect1>
1847         <title>Exceptional Situations</title>
1848         <para>None.</para>
1849       </refsect1>
1850     </refentry>
1851
1852
1853     <refentry id="convert-to-foreign-string">
1854       <refnamediv>
1855         <refname>convert-to-foreign-string</refname>
1856         <refpurpose>Converts a Lisp string to a foreign string.
1857         </refpurpose>
1858         <refclass>Macro</refclass>
1859       </refnamediv>
1860       <refsynopsisdiv>
1861         <title>Syntax</title>
1862         <synopsis>
1863           <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
1864         </synopsis>
1865       </refsynopsisdiv>
1866       <refsect1>
1867         <title>Arguments and Values</title>
1868         <variablelist>
1869           <varlistentry>
1870             <term><parameter>string</parameter></term>
1871             <listitem>
1872               <para>A Lisp string.
1873               </para>
1874             </listitem>
1875           </varlistentry>
1876           <varlistentry>
1877             <term><returnvalue>foreign-string</returnvalue></term>
1878             <listitem>
1879               <para>A foreign string.
1880               </para>
1881             </listitem>
1882           </varlistentry>
1883         </variablelist>
1884       </refsect1>
1885       <refsect1>
1886         <title>Description</title>
1887         <para>
1888           Converts a Lisp string to a foreign string. Memory should be
1889           freed with <function>free-foreign-object</function>.
1890         </para>
1891       </refsect1>
1892       <refsect1>
1893         <title>Side Effects</title>
1894         <para>None.</para>
1895       </refsect1>
1896       <refsect1>
1897         <title>Affected by</title>
1898         <para>None.</para>
1899       </refsect1>
1900       <refsect1>
1901         <title>Exceptional Situations</title>
1902         <para>None.</para>
1903       </refsect1>
1904     </refentry>
1905
1906
1907
1908     <refentry id="allocate-foreign-string">
1909       <refnamediv>
1910         <refname>allocate-foreign-string</refname>
1911         <refpurpose>Allocates space for a foreign string.
1912         </refpurpose>
1913         <refclass>Macro</refclass>
1914       </refnamediv>
1915       <refsynopsisdiv>
1916         <title>Syntax</title>
1917         <synopsis>
1918           <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
1919         </synopsis>
1920       </refsynopsisdiv>
1921       <refsect1>
1922         <title>Arguments and Values</title>
1923         <variablelist>
1924           <varlistentry>
1925             <term><parameter>size</parameter></term>
1926             <listitem>
1927               <para>The size of the space to be allocated in bytes.
1928               </para>
1929             </listitem>
1930           </varlistentry>
1931           <varlistentry>
1932             <term><parameter>unsigned</parameter></term>
1933             <listitem>
1934               <para>A boolean flag with a default value of &t;. When true,
1935 marks the pointer as an <constant>:unsigned-char</constant>.
1936               </para>
1937             </listitem>
1938           </varlistentry>
1939           <varlistentry>
1940             <term><returnvalue>foreign-string</returnvalue></term>
1941             <listitem>
1942               <para>A foreign string which has undefined contents.
1943               </para>
1944             </listitem>
1945           </varlistentry>
1946         </variablelist>
1947       </refsect1>
1948       <refsect1>
1949         <title>Description</title>
1950         <para>
1951           Allocates space for a foreign string. Memory should
1952           be freed with <function>free-foreign-object</function>.
1953         </para>
1954       </refsect1>
1955       <refsect1>
1956         <title>Side Effects</title>
1957         <para>None.</para>
1958       </refsect1>
1959       <refsect1>
1960         <title>Affected by</title>
1961         <para>None.</para>
1962       </refsect1>
1963       <refsect1>
1964         <title>Exceptional Situations</title>
1965         <para>None.</para>
1966       </refsect1>
1967     </refentry>
1968
1969   </reference>
1970
1971   <reference>
1972       <title>Functions &amp; Libraries</title>
1973
1974       <refentry id="def-function">
1975         <refnamediv>
1976           <refname>def-function</refname>
1977         <refpurpose>Declares a function.
1978         </refpurpose>
1979         <refclass>Macro</refclass>
1980       </refnamediv>
1981       <refsynopsisdiv>
1982         <title>Syntax</title>
1983         <synopsis>
1984           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
1985         </synopsis>
1986       </refsynopsisdiv>
1987       <refsect1>
1988         <title>Arguments and Values</title>
1989         <variablelist>
1990           <varlistentry>
1991             <term><parameter>name</parameter></term>
1992             <listitem>
1993               <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.
1994               </para>
1995             </listitem>
1996           </varlistentry>
1997           <varlistentry>
1998             <term><parameter>args</parameter></term>
1999             <listitem>
2000               <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
2001               </para>
2002             </listitem>
2003           </varlistentry>
2004           <varlistentry>
2005             <term><parameter>module</parameter></term>
2006             <listitem>
2007               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
2008             </listitem>
2009           </varlistentry>
2010           <varlistentry>
2011             <term><returnvalue>returning</returnvalue></term>
2012             <listitem>
2013               <para>A declaration specifying the result type of the
2014 foreign function. If <constant>:void</constant> indicates module does not return any value.
2015               </para>
2016             </listitem>
2017           </varlistentry>
2018         </variablelist>
2019       </refsect1>
2020       <refsect1>
2021         <title>Description</title>
2022         <para>Declares a foreign function.
2023         </para>
2024       </refsect1>
2025       <refsect1>
2026         <title>Examples</title>
2027         <programlisting>
2028 (def-function "gethostname"
2029   ((name (* :unsigned-char))
2030    (len :int))
2031   :returning :int)
2032         </programlisting>
2033       </refsect1>
2034       <refsect1>
2035         <title>Side Effects</title>
2036         <para>None.</para>
2037       </refsect1>
2038       <refsect1>
2039         <title>Affected by</title>
2040         <para>None.</para>
2041       </refsect1>
2042       <refsect1>
2043         <title>Exceptional Situations</title>
2044         <para>None.</para>
2045       </refsect1>
2046     </refentry>
2047
2048       <refentry id="load-foreign-library">
2049         <refnamediv>
2050           <refname>load-foreign-library</refname>
2051         <refpurpose>Loads a foreign library.
2052         </refpurpose>
2053         <refclass>Function</refclass>
2054       </refnamediv>
2055       <refsect1>
2056         <title>Syntax</title>
2057 <synopsis>
2058           <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
2059 </synopsis>
2060       </refsect1>
2061       <refsect1>
2062         <title>Arguments and Values</title>
2063         <variablelist>
2064           <varlistentry>
2065             <term><parameter>filename</parameter></term>
2066             <listitem>
2067               <para>A string or pathname specifying the library location
2068 in the filesystem. At least one implementation (&lw;) can not
2069 accept a logical pathname.
2070               </para>
2071             </listitem>
2072           </varlistentry>
2073           <varlistentry>
2074             <term><parameter>module</parameter></term>
2075             <listitem>
2076               <para>A string designating the name of the module to apply
2077 to functions in this library. (Required for Lispworks)
2078               </para>
2079             </listitem>
2080           </varlistentry>
2081           <varlistentry>
2082             <term><parameter>supporting-libraries</parameter></term>
2083             <listitem>
2084               <para>A list of strings naming the libraries required to
2085 link the foreign library. (Required by CMUCL)
2086               </para>
2087             </listitem>
2088           </varlistentry>
2089           <varlistentry>
2090             <term><returnvalue>success</returnvalue></term>
2091             <listitem>
2092               <para>A boolean flag, &t; if the library was able to be
2093 loaded successfully or if the library has been previously loaded,
2094 otherwise &nil;.
2095               </para>
2096             </listitem>
2097           </varlistentry>
2098         </variablelist>
2099       </refsect1>
2100       <refsect1>
2101         <title>Description</title>
2102         <para>Loads a foreign library. Applies a module name to functions
2103 within the library. Ensures that a library is only loaded once during
2104 a session.
2105         </para>
2106       </refsect1>
2107       <refsect1>
2108         <title>Examples</title>
2109         <programlisting>
2110   (load-foreign-library #p"/usr/lib/libmysqlclient.so"
2111                         :module "mysql"
2112                         :supporting-libraries '("c"))
2113     => T
2114         </programlisting>
2115       </refsect1>
2116       <refsect1>
2117         <title>Side Effects</title>
2118         <para>Loads the foreign code into the Lisp system.
2119         </para>
2120       </refsect1>
2121       <refsect1>
2122         <title>Affected by</title>
2123         <para>Ability to load the file.</para>
2124       </refsect1>
2125       <refsect1>
2126         <title>Exceptional Situations</title>
2127         <para>None.</para>
2128       </refsect1>
2129     </refentry>
2130
2131       <refentry id="find-foreign-library">
2132         <refnamediv>
2133           <refname>find-foreign-library</refname>
2134         <refpurpose>Finds a foreign library file.
2135         </refpurpose>
2136         <refclass>Function</refclass>
2137       </refnamediv>
2138       <refsect1>
2139         <title>Syntax</title>
2140 <synopsis>
2141           <function>find-foreign-library</function> <replaceable>names directories &amp; drive-letters types</replaceable> => <returnvalue>path</returnvalue>
2142 </synopsis>
2143       </refsect1>
2144       <refsect1>
2145         <title>Arguments and Values</title>
2146         <variablelist>
2147           <varlistentry>
2148             <term><parameter>names</parameter></term>
2149             <listitem>
2150               <para>A string or list of strings containing the base name of the library file.
2151               </para>
2152             </listitem>
2153           </varlistentry>
2154           <varlistentry>
2155             <term><parameter>directories</parameter></term>
2156             <listitem>
2157               <para>A string or list of strings containing the directory the library file.
2158               </para>
2159             </listitem>
2160           </varlistentry>
2161           <varlistentry>
2162             <term><parameter>drive-letters</parameter></term>
2163             <listitem>
2164               <para>A string or list of strings containing the drive letters for the library file.
2165               </para>
2166             </listitem>
2167           </varlistentry>
2168           <varlistentry>
2169             <term><parameter>types</parameter></term>
2170             <listitem>
2171               <para>A string or list of strings containing the file type of the library file. Default
2172 is &nil;. If &nil;, will use a default type based on the currently running implementation.
2173               </para>
2174             </listitem>
2175           </varlistentry>
2176           <varlistentry>
2177             <term><returnvalue>path</returnvalue></term>
2178             <listitem>
2179               <para>A path containing the path found, or &nil; if the library file was not found.
2180               </para>
2181             </listitem>
2182           </varlistentry>
2183         </variablelist>
2184       </refsect1>
2185       <refsect1>
2186         <title>Description</title>
2187         <para>Finds a foreign library by searching through a number of possible locations. Returns
2188 the path of the first found file.
2189         </para>
2190       </refsect1>
2191       <refsect1>
2192         <title>Examples</title>
2193         <programlisting>
2194 (find-foreign-library '("libmysqlclient" "libmysql")
2195     '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
2196     :types '("so" "dll")
2197     :drive-letters '("C" "D" "E"))
2198 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
2199         </programlisting>
2200       </refsect1>
2201       <refsect1>
2202         <title>Side Effects</title>
2203         <para>None.
2204         </para>
2205       </refsect1>
2206       <refsect1>
2207         <title>Affected by</title>
2208         <para>None.</para>
2209       </refsect1>
2210       <refsect1>
2211         <title>Exceptional Situations</title>
2212         <para>None.</para>
2213       </refsect1>
2214     </refentry>
2215
2216 </reference>
2217
2218