doc/ref_object.xml

   1 <?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.xml">
   5 %myents;
   6 ]>
   7
   8 <reference id="objects">
   9   <title>Objects</title>
  10 <partintro>
  11 <title>Overview</title>
  12     <para>
  13       Objects are entities that can allocated, referred to by pointers, and
  14 can be freed.
  15     </para>
  16 </partintro>
  17
  18
  19     <refentry id="allocate-foreign-object">
  20       <refnamediv>
  21         <refname>allocate-foreign-object</refname>
  22         <refpurpose>Allocates an instance of a foreign object.
  23         </refpurpose>
  24         <refclass>Macro</refclass>
  25       </refnamediv>
  26       <refsynopsisdiv>
  27         <title>Syntax</title>
  28         <synopsis>
  29           <function>allocate-foreign-object</function> <replaceable>type &amp;optional size</replaceable> => <returnvalue>ptr</returnvalue>
  30         </synopsis>
  31       </refsynopsisdiv>
  32       <refsect1>
  33         <title>Arguments and Values</title>
  34         <variablelist>
  35           <varlistentry>
  36             <term><parameter>type</parameter></term>
  37             <listitem>
  38               <para>The type of foreign object to allocate. This parameter is evaluated.
  39               </para>
  40             </listitem>
  41           </varlistentry>
  42           <varlistentry>
  43             <term><parameter>size</parameter></term>
  44             <listitem>
  45               <para>An optional size parameter that is evaluated. If specified, allocates and returns an
  46 array of <parameter>type</parameter> that is <parameter>size</parameter> members long. This parameter is evaluated.
  47               </para>
  48             </listitem>
  49           </varlistentry>
  50           <varlistentry>
  51             <term><returnvalue>ptr</returnvalue></term>
  52             <listitem>
  53               <para>A pointer to the foreign object.
  54               </para>
  55             </listitem>
  56           </varlistentry>
  57         </variablelist>
  58       </refsect1>
  59       <refsect1>
  60         <title>Description</title>
  61         <para>
  62           Allocates an instance of a foreign object. It returns a pointer to the object.
  63         </para>
  64       </refsect1>
  65       <refsect1>
  66         <title>Examples</title>
  67         <programlisting>
  68 (def-struct ab (a :int) (b :double))
  69 (allocate-foreign-object 'ab)
  70 => #&lt;ptr&gt;
  71         </programlisting>
  72       </refsect1>
  73       <refsect1>
  74         <title>Side Effects</title>
  75         <para>None.</para>
  76       </refsect1>
  77       <refsect1>
  78         <title>Affected by</title>
  79         <para>None.</para>
  80       </refsect1>
  81       <refsect1>
  82         <title>Exceptional Situations</title>
  83         <para>None.</para>
  84       </refsect1>
  85     </refentry>
  86
  87
  88     <refentry id="free-foreign-object">
  89       <refnamediv>
  90         <refname>free-foreign-object</refname>
  91         <refpurpose>Frees memory that was allocated for a foreign boject.
  92         </refpurpose>
  93         <refclass>Macro</refclass>
  94       </refnamediv>
  95       <refsynopsisdiv>
  96         <title>Syntax</title>
  97         <synopsis>
  98           <function>free-foreign-object</function> <replaceable>ptr</replaceable>
  99         </synopsis>
 100       </refsynopsisdiv>
 101       <refsect1>
 102         <title>Arguments and Values</title>
 103         <variablelist>
 104           <varlistentry>
 105             <term><parameter>ptr</parameter></term>
 106             <listitem>
 107               <para>A pointer to the allocated foreign object to free.
 108               </para>
 109             </listitem>
 110           </varlistentry>
 111         </variablelist>
 112       </refsect1>
 113       <refsect1>
 114         <title>Description</title>
 115         <para>
 116           Frees the memory used by the allocation of a foreign object.
 117         </para>
 118       </refsect1>
 119       <refsect1>
 120         <title>Side Effects</title>
 121         <para>None.</para>
 122       </refsect1>
 123       <refsect1>
 124         <title>Affected by</title>
 125         <para>None.</para>
 126       </refsect1>
 127       <refsect1>
 128         <title>Exceptional Situations</title>
 129         <para>None.</para>
 130       </refsect1>
 131     </refentry>
 132
 133
 134     <refentry id="with-foreign-object">
 135       <refnamediv>
 136         <refname>with-foreign-object</refname>
 137         <refpurpose>Wraps the allocation of a foreign object around a body of code.
 138         </refpurpose>
 139         <refclass>Macro</refclass>
 140       </refnamediv>
 141       <refsynopsisdiv>
 142         <title>Syntax</title>
 143         <synopsis>
 144           <function>with-foreign-object</function> <replaceable>(var type) &amp;body body</replaceable> => <returnvalue>form-return</returnvalue>
 145         </synopsis>
 146       </refsynopsisdiv>
 147       <refsect1>
 148         <title>Arguments and Values</title>
 149         <variablelist>
 150           <varlistentry>
 151             <term><parameter>var</parameter></term>
 152             <listitem>
 153               <para>The variable name to bind.
 154               </para>
 155             </listitem>
 156           </varlistentry>
 157           <varlistentry>
 158             <term><parameter>type</parameter></term>
 159             <listitem>
 160               <para>The type of foreign object to allocate. This parameter is evaluated.
 161               </para>
 162             </listitem>
 163           </varlistentry>
 164           <varlistentry>
 165             <term><returnvalue>form-return</returnvalue></term>
 166             <listitem>
 167               <para>The result of evaluating the <parameter>body</parameter>.
 168               </para>
 169             </listitem>
 170           </varlistentry>
 171         </variablelist>
 172       </refsect1>
 173       <refsect1>
 174         <title>Description</title>
 175         <para>
 176 This function wraps the allocation, binding, and destruction of a foreign object.
 177 On &cmucl; and
 178 &lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
 179 much better with static allocation.
 180         </para>
 181       </refsect1>
 182       <refsect1>
 183         <title>Examples</title>
 184         <programlisting>
 185 (defun gethostname2 ()
 186   "Returns the hostname"
 187   (uffi:with-foreign-object (name '(:array :unsigned-char 256))
 188     (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
 189         (uffi:convert-from-foreign-string name)
 190         (error "gethostname() failed."))))
 191         </programlisting>
 192       </refsect1>
 193       <refsect1>
 194         <title>Side Effects</title>
 195         <para>None.</para>
 196       </refsect1>
 197       <refsect1>
 198         <title>Affected by</title>
 199         <para>None.</para>
 200       </refsect1>
 201       <refsect1>
 202         <title>Exceptional Situations</title>
 203         <para>None.</para>
 204       </refsect1>
 205     </refentry>
 206
 207     <refentry id="size-of-foreign-type">
 208       <refnamediv>
 209         <refname>size-of-foreign-type</refname>
 210         <refpurpose>Returns the number of data bytes used by a foreign object type.
 211         </refpurpose>
 212         <refclass>Macro</refclass>
 213       </refnamediv>
 214       <refsynopsisdiv>
 215         <title>Syntax</title>
 216         <synopsis>
 217           <function>size-of-foreign-type</function> <replaceable>ftype</replaceable>
 218         </synopsis>
 219       </refsynopsisdiv>
 220       <refsect1>
 221         <title>Arguments and Values</title>
 222         <variablelist>
 223           <varlistentry>
 224             <term><parameter>ftype</parameter></term>
 225             <listitem>
 226               <para>A foreign type specifier. This parameter is evaluated.
 227               </para>
 228             </listitem>
 229           </varlistentry>
 230         </variablelist>
 231       </refsect1>
 232       <refsect1>
 233         <title>Description</title>
 234         <para>
 235           Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.
 236         </para>
 237       </refsect1>
 238       <refsect1>
 239         <title>Examples</title>
 240         <para>
 241 <programlisting>
 242 (size-of-foreign-object :unsigned-byte)
 243 => 1
 244 (size-of-foreign-object 'my-100-byte-vector-type)
 245 => 100
 246 </programlisting>
 247         </para>
 248       </refsect1>
 249       <refsect1>
 250         <title>Side Effects</title>
 251         <para>None.</para>
 252       </refsect1>      <refsect1>
 253         <title>Affected by</title>
 254         <para>None.</para>
 255       </refsect1>
 256       <refsect1>
 257         <title>Exceptional Situations</title>
 258         <para>None.</para>
 259       </refsect1>
 260     </refentry>
 261
 262     <refentry id="pointer-address">
 263       <refnamediv>
 264         <refname>pointer-address</refname>
 265         <refpurpose>Returns the address of a pointer.
 266         </refpurpose>
 267         <refclass>Macro</refclass>
 268       </refnamediv>
 269       <refsynopsisdiv>
 270         <title>Syntax</title>
 271         <synopsis>
 272           <function>pointer-address</function> <replaceable>ptr</replaceable> => <returnvalue>address</returnvalue>
 273         </synopsis>
 274       </refsynopsisdiv>
 275       <refsect1>
 276         <title>Arguments and Values</title>
 277         <variablelist>
 278           <varlistentry>
 279             <term><parameter>ptr</parameter></term>
 280             <listitem>
 281               <para>A pointer to a foreign object.
 282               </para>
 283             </listitem>
 284           </varlistentry>
 285           <varlistentry>
 286             <term><parameter>address</parameter></term>
 287             <listitem>
 288               <para>An integer representing the pointer's address.
 289               </para>
 290             </listitem>
 291           </varlistentry>
 292         </variablelist>
 293       </refsect1>
 294       <refsect1>
 295         <title>Description</title>
 296         <para>
 297           Returns the address as an integer of a pointer.
 298         </para>
 299       </refsect1>
 300       <refsect1>
 301         <title>Side Effects</title>
 302         <para>None.</para>
 303       </refsect1>
 304       <refsect1>
 305         <title>Affected by</title>
 306         <para>None.</para>
 307       </refsect1>
 308       <refsect1>
 309         <title>Exceptional Situations</title>
 310         <para>None.</para>
 311       </refsect1>
 312     </refentry>
 313
 314
 315     <refentry id="deref-pointer">
 316       <refnamediv>
 317         <refname>deref-pointer</refname>
 318         <refpurpose>Deferences a pointer.
 319         </refpurpose>
 320         <refclass>Macro</refclass>
 321       </refnamediv>
 322       <refsynopsisdiv>
 323         <title>Syntax</title>
 324         <synopsis>
 325           <function>deref-pointer</function> <replaceable>ptr type</replaceable> => <returnvalue>value</returnvalue>
 326         </synopsis>
 327       </refsynopsisdiv>
 328       <refsect1>
 329         <title>Arguments and Values</title>
 330         <variablelist>
 331           <varlistentry>
 332             <term><parameter>ptr</parameter></term>
 333             <listitem>
 334               <para>A pointer to a foreign object.
 335               </para>
 336             </listitem>
 337           </varlistentry>
 338           <varlistentry>
 339             <term><parameter>type</parameter></term>
 340             <listitem>
 341               <para>A foreign type of the object being pointed to.
 342               </para>
 343             </listitem>
 344           </varlistentry>
 345           <varlistentry>
 346             <term><returnvalue>value</returnvalue></term>
 347             <listitem>
 348               <para>The value of the object where the pointer points.
 349               </para>
 350             </listitem>
 351           </varlistentry>
 352         </variablelist>
 353       </refsect1>
 354       <refsect1>
 355         <title>Description</title>
 356         <para>
 357           Returns the object to which a pointer points.
 358         </para>
 359       </refsect1>
 360       <refsect1>
 361         <title>Examples</title>
 362         <para>
 363 <programlisting>
 364 (let ((intp (allocate-foreign-object :int)))
 365   (setf (deref-pointer intp :int) 10)
 366   (prog1
 367     (deref-pointer intp :int)
 368     (free-foreign-object intp)))
 369 => 10
 370 </programlisting>
 371         </para>
 372       </refsect1>
 373       <refsect1>
 374         <title>Notes</title>
 375         <para>
 376   The TYPE argument is ignored for CL implementations other than
 377   AllegroCL. If you want to cast a pointer to another type use
 378   WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
 379         </para>
 380       </refsect1>
 381       <refsect1>
 382         <title>Side Effects</title>
 383         <para>None.</para>
 384       </refsect1>
 385       <refsect1>
 386         <title>Affected by</title>
 387         <para>None.</para>
 388       </refsect1>
 389       <refsect1>
 390         <title>Exceptional Situations</title>
 391         <para>None.</para>
 392       </refsect1>
 393     </refentry>
 394
 395     <refentry id="ensure-char-character">
 396       <refnamediv>
 397         <refname>ensure-char-character</refname>
 398         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
 399 a character.
 400         </refpurpose>
 401         <refclass>Macro</refclass>
 402       </refnamediv>
 403       <refsynopsisdiv>
 404         <title>Syntax</title>
 405         <synopsis>
 406           <function>ensure-char-character</function> <replaceable>object</replaceable> => <returnvalue>char</returnvalue>
 407         </synopsis>
 408       </refsynopsisdiv>
 409       <refsect1>
 410         <title>Arguments and Values</title>
 411         <variablelist>
 412           <varlistentry>
 413             <term><parameter>object</parameter></term>
 414             <listitem>
 415               <para>Either a character or a integer specifying a character code.
 416               </para>
 417             </listitem>
 418           </varlistentry>
 419           <varlistentry>
 420             <term><returnvalue>char</returnvalue></term>
 421             <listitem>
 422               <para>A character.
 423               </para>
 424             </listitem>
 425           </varlistentry>
 426         </variablelist>
 427       </refsect1>
 428       <refsect1>
 429         <title>Description</title>
 430         <para>
 431           Ensures that an objects obtained by dereferencing
 432 <constant>:char</constant> and <constant>:unsigned-char</constant>
 433 pointers are a lisp character.
 434         </para>
 435       </refsect1>
 436       <refsect1>
 437         <title>Examples</title>
 438         <para>
 439 <programlisting>
 440 (let ((fs (convert-to-foreign-string "a")))
 441   (prog1
 442     (ensure-char-character (deref-pointer fs :char))
 443     (free-foreign-object fs)))
 444 => #\a
 445 </programlisting>
 446         </para>
 447       </refsect1>
 448       <refsect1>
 449         <title>Side Effects</title>
 450         <para>None.</para>
 451       </refsect1>
 452       <refsect1>
 453         <title>Affected by</title>
 454         <para>None.</para>
 455       </refsect1>
 456       <refsect1>
 457         <title>Exceptional Situations</title>
 458         <para>Depending upon the implementation and what &uffi; expects, this
 459 macro may signal an error if the object is not a character or
 460 integer.</para>
 461       </refsect1>
 462     </refentry>
 463
 464     <refentry id="ensure-char-integer">
 465       <refnamediv>
 466         <refname>ensure-char-integer</refname>
 467         <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
 468 an integer.
 469         </refpurpose>
 470         <refclass>Macro</refclass>
 471       </refnamediv>
 472       <refsynopsisdiv>
 473         <title>Syntax</title>
 474         <synopsis>
 475           <function>ensure-char-integer</function> <replaceable>object</replaceable> => <returnvalue>int</returnvalue>
 476         </synopsis>
 477       </refsynopsisdiv>
 478       <refsect1>
 479         <title>Arguments and Values</title>
 480         <variablelist>
 481           <varlistentry>
 482             <term><parameter>object</parameter></term>
 483             <listitem>
 484               <para>Either a character or a integer specifying a character code.
 485               </para>
 486             </listitem>
 487           </varlistentry>
 488           <varlistentry>
 489             <term><returnvalue>int</returnvalue></term>
 490             <listitem>
 491               <para>An integer.
 492               </para>
 493             </listitem>
 494           </varlistentry>
 495         </variablelist>
 496       </refsect1>
 497       <refsect1>
 498         <title>Description</title>
 499         <para>
 500           Ensures that an object obtained by dereferencing a
 501 <constant>:char</constant> pointer is an integer.
 502         </para>
 503       </refsect1>
 504       <refsect1>
 505         <title>Examples</title>
 506         <para>
 507 <programlisting>
 508 (let ((fs (convert-to-foreign-string "a")))
 509   (prog1
 510     (ensure-char-integer (deref-pointer fs :char))
 511     (free-foreign-object fs)))
 512 => 96
 513 </programlisting>
 514         </para>
 515       </refsect1>
 516       <refsect1>
 517         <title>Side Effects</title>
 518         <para>None.</para>
 519       </refsect1>
 520       <refsect1>
 521         <title>Affected by</title>
 522         <para>None.</para>
 523       </refsect1>
 524       <refsect1>
 525         <title>Exceptional Situations</title>
 526         <para>Depending upon the implementation and what &uffi; expects, this
 527 macro may signal an error if the object is not a character or
 528 integer.</para>
 529       </refsect1>
 530     </refentry>
 531
 532     <refentry id="make-null-pointer">
 533       <refnamediv>
 534         <refname>make-null-pointer</refname>
 535         <refpurpose>Create a &null; pointer.
 536         </refpurpose>
 537         <refclass>Macro</refclass>
 538       </refnamediv>
 539       <refsynopsisdiv>
 540         <title>Syntax</title>
 541         <synopsis>
 542           <function>make-null-pointer</function> <replaceable>type</replaceable> => <returnvalue>ptr</returnvalue>
 543         </synopsis>
 544       </refsynopsisdiv>
 545       <refsect1>
 546         <title>Arguments and Values</title>
 547         <variablelist>
 548           <varlistentry>
 549             <term><parameter>type</parameter></term>
 550             <listitem>
 551               <para>A type of object to which the pointer refers.
 552               </para>
 553             </listitem>
 554           </varlistentry>
 555           <varlistentry>
 556             <term><parameter>ptr</parameter></term>
 557             <listitem>
 558               <para>The &null; pointer of type <parameter>type</parameter>.
 559               </para>
 560             </listitem>
 561           </varlistentry>
 562         </variablelist>
 563       </refsect1>
 564       <refsect1>
 565         <title>Description</title>
 566         <para>
 567           Creates a &null; pointer of a specified type.
 568         </para>
 569       </refsect1>
 570       <refsect1>
 571         <title>Side Effects</title>
 572         <para>None.</para>
 573       </refsect1>
 574       <refsect1>
 575         <title>Affected by</title>
 576         <para>None.</para>
 577       </refsect1>
 578       <refsect1>
 579         <title>Exceptional Situations</title>
 580         <para>None.</para>
 581       </refsect1>
 582     </refentry>
 583
 584
 585     <refentry id="null-pointer-p">
 586       <refnamediv>
 587         <refname>null-pointer-p</refname>
 588         <refpurpose>Tests a pointer for &null; value.
 589         </refpurpose>
 590         <refclass>Macro</refclass>
 591       </refnamediv>
 592       <refsynopsisdiv>
 593         <title>Syntax</title>
 594         <synopsis>
 595           <function>null-pointer-p</function> <replaceable>ptr</replaceable> => <returnvalue>is-null</returnvalue>
 596         </synopsis>
 597       </refsynopsisdiv>
 598       <refsect1>
 599         <title>Arguments and Values</title>
 600         <variablelist>
 601           <varlistentry>
 602             <term><parameter>ptr</parameter></term>
 603             <listitem>
 604               <para>A foreign object pointer.
 605               </para>
 606             </listitem>
 607           </varlistentry>
 608           <varlistentry>
 609             <term><returnvalue>is-null</returnvalue></term>
 610             <listitem>
 611               <para>The boolean flag.
 612               </para>
 613             </listitem>
 614           </varlistentry>
 615         </variablelist>
 616       </refsect1>
 617       <refsect1>
 618         <title>Description</title>
 619         <para>
 620           A predicate testing if a pointer is has a &null; value.
 621         </para>
 622       </refsect1>
 623       <refsect1>
 624         <title>Side Effects</title>
 625         <para>None.</para>
 626       </refsect1>
 627       <refsect1>
 628         <title>Affected by</title>
 629         <para>None.</para>
 630       </refsect1>
 631       <refsect1>
 632         <title>Exceptional Situations</title>
 633         <para>None.</para>
 634       </refsect1>
 635     </refentry>
 636
 637
 638     <refentry id="null-cstring-pointer">
 639       <refnamediv>
 640         <refname>+null-cstring-pointer+</refname>
 641         <refpurpose>A constant &null; cstring pointer.
 642         </refpurpose>
 643         <refclass>Constant</refclass>
 644       </refnamediv>
 645       <refsect1>
 646         <title>Description</title>
 647         <para>
 648           A &null; cstring pointer. This can be used for testing
 649 if a cstring returned by a function is &null;.
 650         </para>
 651       </refsect1>
 652     </refentry>
 653
 654     <refentry id="with-cast-pointer">
 655       <refnamediv>
 656         <refname>with-cast-pointer</refname>
 657         <refpurpose>Wraps a body of code with a pointer cast to a new type.
 658         </refpurpose>
 659         <refclass>Macro</refclass>
 660       </refnamediv>
 661       <refsynopsisdiv>
 662         <title>Syntax</title>
 663         <synopsis>
 664           <function>with-cast-pointer</function> (<replaceable>binding-name ptr type) &amp; body body</replaceable> => <returnvalue>value</returnvalue>
 665         </synopsis>
 666       </refsynopsisdiv>
 667       <refsect1>
 668         <title>Arguments and Values</title>
 669         <variablelist>
 670           <varlistentry>
 671             <term><parameter>ptr</parameter></term>
 672             <listitem>
 673               <para>A pointer to a foreign object.
 674               </para>
 675             </listitem>
 676           </varlistentry>
 677           <varlistentry>
 678             <term><parameter>type</parameter></term>
 679             <listitem>
 680               <para>A foreign type of the object being pointed to.
 681               </para>
 682             </listitem>
 683           </varlistentry>
 684           <varlistentry>
 685             <term><returnvalue>value</returnvalue></term>
 686             <listitem>
 687               <para>The value of the object where the pointer points.
 688               </para>
 689             </listitem>
 690           </varlistentry>
 691         </variablelist>
 692       </refsect1>
 693       <refsect1>
 694         <title>Description</title>
 695         <para>
 696   Executes BODY with POINTER cast to be a pointer to type TYPE. If
 697   BINDING-NAME is provided the cast pointer will be bound to this
 698   name during the execution of BODY. If BINDING-NAME is not provided
 699   POINTER must be a name bound to the pointer which should be
 700   cast. This name will be bound to the cast pointer during the
 701   execution of BODY.
 702
 703   This is a no-op in AllegroCL but will wrap BODY in a LET form if
 704   BINDING-NAME is provided.
 705
 706   This macro is meant to be used in conjunction with DEREF-POINTER or
 707   DEREF-ARRAY. In Allegro CL the "cast" will actually take place in
 708   DEREF-POINTER or DEREF-ARRAY.
 709         </para>
 710       </refsect1>
 711       <refsect1>
 712         <title>Examples</title>
 713 <programlisting>
 714 (with-foreign-object (size :int)
 715    ;; FOO is a foreign function returning a :POINTER-VOID
 716    (let ((memory (foo size)))
 717       (when (mumble)
 718          ;; at this point we know for some reason that MEMORY points
 719          ;; to an array of unsigned bytes
 720          (with-cast-pointer (memory :unsigned-byte)
 721            (dotimes (i (deref-pointer size :int))
 722             (do-something-with
 723               (deref-array memory '(:array :unsigned-byte) i)))))))
 724 </programlisting>
 725       </refsect1>
 726       <refsect1>
 727         <title>Side Effects</title>
 728         <para>None.</para>
 729       </refsect1>
 730       <refsect1>
 731         <title>Affected by</title>
 732         <para>None.</para>
 733       </refsect1>
 734       <refsect1>
 735         <title>Exceptional Situations</title>
 736         <para>None.</para>
 737       </refsect1>
 738     </refentry>
 739
 740     <refentry id="def-foreign-var">
 741       <refnamediv>
 742         <refname>def-foreign-var</refname>
 743         <refpurpose>
 744 Defines a symbol macro to access a variable in foreign code
 745         </refpurpose>
 746         <refclass>Macro</refclass>
 747       </refnamediv>
 748       <refsynopsisdiv>
 749         <title>Syntax</title>
 750         <synopsis>
 751           <function>def-foreign-var</function> <replaceable>name type module</replaceable>
 752         </synopsis>
 753       </refsynopsisdiv>
 754       <refsect1>
 755         <title>Arguments and Values</title>
 756         <variablelist>
 757           <varlistentry>
 758             <term><parameter>name</parameter></term>
 759             <listitem>
 760               <para>
 761 A string or list specificying the symbol macro's name. If it is a
 762      string, that names the foreign variable. A Lisp name is created
 763      by translating #\_ to #\- and by converting to upper-case in
 764      case-insensitive Lisp implementations. If it is a list, the first
 765      item is a string specifying the foreign variable name and the
 766      second it is a symbol stating the Lisp name.
 767               </para>
 768             </listitem>
 769           </varlistentry>
 770           <varlistentry>
 771             <term><parameter>type</parameter></term>
 772             <listitem>
 773               <para>A foreign type of the foreign variable.
 774               </para>
 775             </listitem>
 776           </varlistentry>
 777           <varlistentry>
 778             <term><returnvalue>module</returnvalue></term>
 779             <listitem>
 780               <para>
 781      A string specifying the module (or library) the foreign variable
 782      resides in. (Required by Lispworks)
 783               </para>
 784             </listitem>
 785           </varlistentry>
 786         </variablelist>
 787       </refsect1>
 788       <refsect1>
 789         <title>Description</title>
 790         <para>
 791 Defines a symbol macro which can be used to access (get and set) the
 792 value of a variable in foreign code.
 793         </para>
 794       </refsect1>
 795       <refsect1>
 796         <title>Examples</title>
 797         <refsect2>
 798         <title>C code</title>
 799 <programlisting>
 800   int baz = 3;
 801
 802   typedef struct {
 803     int x;
 804     double y;
 805   } foo_struct;
 806
 807   foo_struct the_struct = { 42, 3.2 };
 808
 809   int foo () {
 810     return baz;
 811   }
 812 </programlisting>
 813 </refsect2>
 814 <refsect2>
 815 <title>Lisp code</title>
 816 <programlisting>
 817   (uffi:def-struct foo-struct
 818     (x :int)
 819     (y :double))
 820
 821   (uffi:def-function ("foo" foo)
 822       ()
 823     :returning :int
 824     :module "foo")
 825
 826   (uffi:def-foreign-var ("baz" *baz*) :int "foo")
 827   (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo")
 828
 829
 830 *baz*
 831   => 3
 832
 833 (incf *baz*)
 834   => 4
 835
 836 (foo)
 837   => 4
 838 </programlisting>
 839 </refsect2>
 840       </refsect1>
 841       <refsect1>
 842         <title>Side Effects</title>
 843         <para>None.</para>
 844       </refsect1>
 845       <refsect1>
 846         <title>Affected by</title>
 847         <para>None.</para>
 848       </refsect1>
 849       <refsect1>
 850         <title>Exceptional Situations</title>
 851         <para>None.</para>
 852       </refsect1>
 853     </refentry>
 854
 855 </reference>