doc/ffi.sgml

   1 <chapter id="ffi"><title>The Foreign Function Interface</>
   2
   3 <para>This chapter describes &SBCL;'s interface to C programs and
   4 libraries (and, since C interfaces are a sort of <foreignphrase>lingua
   5 franca</> of the Unix world, to other programs and libraries in
   6 general.)</para>
   7
   8 <note><para>In the modern Lisp world, the usual term for this
   9 functionality is Foreign Function Interface, or <acronym>FFI</>, where
  10 despite the mention of <quote>function</> in this term, <acronym>FFI</> also
  11 refers to direct manipulation of C data structures as well as
  12 functions. The traditional &CMUCL; terminology is Alien Interface, and
  13 while that older terminology is no longer used much in the system
  14 documentation, it still reflected in names in the
  15 implementation, notably in the name of the <literal>SB-ALIEN</>
  16 package.</para></note>
  17
  18 <sect1><title>Introduction to the Foreign Function Interface</>
  19 <!-- AKA "Introduction to Aliens" in the CMU CL manual -->
  20
  21 <para>
  22 Because of Lisp's emphasis on dynamic memory allocation and garbage
  23 collection, Lisp implementations use non-C-like memory representations
  24 for objects.  This representation mismatch creates friction when a Lisp
  25 program must share objects with programs which expect C data.  There
  26 are three common approaches to establishing communication:
  27 <itemizedlist>
  28   <listitem><para>The burden can be placed on the foreign program
  29     (and programmer) by requiring the knowledge and use of the
  30     representations used internally by the Lisp implementation.
  31     This can require a considerable amount of <quote>glue</> code on the
  32     C side, and that code tends to be sensitively dependent on the
  33     internal implementation details of the Lisp system.</para></listitem>
  34   <listitem><para>The Lisp system can automatically convert objects
  35     back and forth between the Lisp and foreign representations.
  36     This is convenient, but translation becomes prohibitively slow
  37     when large or complex data structures must be shared. This approach
  38     is supported by the &SBCL; <acronym>FFI</>, and used automatically
  39     by the when passing integers and strings.</para></listitem>
  40   <listitem><para>The Lisp program can directly manipulate foreign
  41     objects through the use of extensions to the Lisp language.
  42     </para></listitem>
  43 </itemizedlist>
  44
  45 <para>&SBCL;, like &CMUCL; before it,
  46 relies primarily on the automatic conversion and direct manipulation
  47 approaches. Foreign values of simple scalar types are automatically
  48 converted, complex types are directly manipulated in their foreign
  49 representation. Furthermore, Lisp strings are represented internally
  50 with null termination bytes so that they can be passed directly to
  51 C interfaces without allocating new zero-terminated copies.</para>
  52
  53 <para>Any foreign objects that can't automatically be converted into
  54 Lisp values are represented by objects of type <type>alien-value</>.
  55 Since Lisp is a dynamically typed language, even foreign objects must
  56 have a run-time type; this type information is provided by
  57 encapsulating the raw pointer to the foreign data within an
  58 <type>alien-value</> object.</para>
  59
  60 <para>The type language and operations on foreign types are
  61 intentionally similar to those of the C language.</para>
  62
  63 </sect1>
  64
  65 <sect1><title>Foreign Types</>
  66 <!-- AKA "Alien Types" in the CMU CL manual -->
  67
  68 <para>Alien types have a description language based on nested list
  69 structure. For example the C type
  70 <programlisting>struct foo {
  71     int a;
  72     struct foo *b[100];
  73 };</programlisting>
  74 has the corresponding &SBCL; FFI type
  75 <programlisting>(struct foo
  76   (a int)
  77   (b (array (* (struct foo)) 100)))</programlisting>
  78 </para>
  79
  80 <sect2><title>Defining Foreign Types</>
  81
  82 <para>
  83 Types may be either named or anonymous.  With structure and union
  84 types, the name is part of the type specifier, allowing recursively
  85 defined types such as:
  86 <programlisting>(struct foo (a (* (struct foo))))</programlisting>
  87 An anonymous structure or union type is specified by using the name
  88 <literal>nil</>.  The <function>with-alien</> macro defines a local
  89 scope which <quote>captures</> any named type definitions.  Other types
  90 are not inherently named, but can be given named abbreviations using
  91 the <function>define-alien-type</> macro.
  92 </para>
  93
  94 </sect2>
  95
  96 <sect2><title>Foreign Types and Lisp Types</>
  97
  98 <para>
  99 The foreign types form a subsystem of the &SBCL; type system.  An
 100 <type>alien</> type specifier provides a way to use any foreign type as a
 101 Lisp type specifier.  For example,
 102 <programlisting>(typep foo '(alien (* int)))</programlisting>
 103 can be used to determine whether <varname>foo</> is a pointer to a foreign
 104 <type>int</>. <type>alien</> type specifiers can be used in the same ways
 105 as ordinary Lisp type specifiers (like <type>string</>.) Alien type
 106 declarations are subject to the same
 107 precise type checking <!-- FIXME: should be linked to id="precisetypechecking" -->
 108 as any other declaration.
 109 </para>
 110
 111 <para>
 112 Note that the type identifiers used in the
 113 foreign type system overlap with native Lisp type
 114 specifiers in some cases.  For example, the type specifier
 115 <type>(alien single-float)</type> is identical to <type>single-float</>, since
 116 foreign floats are automatically converted to Lisp floats.  When
 117 <function>type-of</> is called on an alien value that is not automatically
 118 converted to a Lisp value, then it will return an <type>alien</> type
 119 specifier.
 120 </para>
 121
 122 </sect2>
 123
 124 <sect2><title>Foreign Type Specifiers</>
 125
 126 <note><para>
 127 All foreign type names are exported from the <literal>sb-alien</>
 128 package. Some foreign type names are also symbols in
 129 the <literal>common-lisp</> package, in which case they are
 130 reexported from the <literal>sb-alien</> package, so that
 131 e.g. it is legal to refer to <type>sb-alien:single-float</>.
 132 </para></note>
 133
 134 <para>
 135 These are the basic foreign type specifiers:
 136 <!-- FIXME: There must be some better way of formatting definitions
 137      in DocBook than this. I haven't found it yet, but suggestions
 138      or patches would be welcome. -->
 139 <itemizedlist>
 140   <listitem>
 141     <para>
 142       The foreign type specifier <type>(* foo)</> describes a
 143       pointer to an object of type <type>foo</>.  A pointed-to type
 144       <type>foo</> of <type>t</> indicates a pointer to anything,
 145       similar to <type>void *</> in ANSI C. A null alien pointer can
 146       be detected with the <function>sb-alien:null-alien</>
 147       function.
 148     </para>
 149   </listitem>
 150   <listitem>
 151     <para>
 152       The foreign type specifier <type>(array foo &amp;optional dimensions)</>
 153       describes array of the specified <literal>dimensions</>, holding
 154       elements of type <type>foo</>. Note that (unlike in C) <type>(* foo)</>
 155       <type>(array foo)}</> are considered to be different types when
 156       type checking is done. If equivalence of pointer and array types
 157       is desired, it may be explicitly coerced using
 158       <function>sb-alien:cast</>.
 159     </para>
 160     <para>
 161       Arrays are accessed using <function>sb-alien:deref</>, passing
 162       the indices as additional arguments.  Elements are stored in
 163       column-major order (as in C), so the first dimension determines
 164       only the size of the memory block, and not the layout of the
 165       higher dimensions.  An array whose first dimension is variable
 166       may be specified by using <literal>nil</> as the first dimension.
 167       Fixed-size arrays can be allocated as array elements, structure
 168       slots or <function>sb-alien:with-alien</> variables. Dynamic
 169       arrays can only be allocated using <function>sb-alien:make-alien</>.
 170     </para>
 171   </listitem>
 172   <listitem>
 173     <para>
 174       The foreign type specifier
 175       <type>(sb-alien:struct name &amp;rest fields)</>
 176       describes a structure type with the specified <varname>name</> and
 177       <varname>fields</>. Fields are allocated at the same offsets
 178       used by the implementation's C compiler. If <varname>name</>
 179       is <literal>nil</> then the structure is anonymous.
 180     </para>
 181     <para>
 182       If a named foreign <type>struct</> specifier is passed to
 183       <function>define-alien-type</> or <function>with-alien</>,
 184       then this defines, respectively, a new global or local foreign
 185       structure type.  If no <varname>fields</> are specified, then
 186       the fields are taken from the current (local or global) alien
 187       structure type definition of <varname>name</>.
 188     </para>
 189   </listitem>
 190   <listitem>
 191     <para>
 192       The foreign type specifier
 193       <type>(sb-alien:union name &amp;rest fields)</>
 194       is similar to <type>sb-alien:struct</>, but describes a union type.
 195       All fields are allocated at the same offset, and the size of the
 196       union is the size of the largest field.  The programmer must
 197       determine which field is active from context.
 198     </para>
 199   </listitem>
 200   <listitem>
 201     <para>
 202       The foreign type specifier <type>(sb-alien:enum name &amp;rest specs)</>
 203       describes an enumeration type that maps between integer values
 204       and keywords. If <varname>name</> is <literal>nil</>, then the
 205       type is anonymous.  Each element of the <varname>specs</>
 206       list is either a Lisp keyword, or a list <literal>(keyword value)</>.
 207       <varname>value</> is an integer. If <varname>value</> is not
 208       supplied, then it defaults to one greater than the value for
 209       the preceding spec (or to zero if it is the first spec.)
 210     <para>
 211   </listitem>
 212   <listitem>
 213     <para>
 214       The foreign type specifier <type>(sb-alien:signed &amp;optional bits)</>
 215       specifies a signed integer with the specified number of
 216       <varname>bits</> precision. The upper limit on integer
 217       precision is determined by the machine's word
 218       size. If <varname>bits</> is not specified, the maximum
 219       size will be used.
 220     </para>
 221   </listitem>
 222   <listitem>
 223     <para>
 224       The foreign type specifier <type>(integer &amp;optional bits)</> is
 225       equivalent to the corresponding type specifier using
 226       <type>sb-alien:signed</> instead of <type>integer</>.
 227     </para>
 228   </listitem>
 229   <listitem>
 230     <para>
 231       The foreign type specifier
 232       <type>(sb-alien:unsigned &amp;optional bits)</>
 233       is like corresponding type specifier using <type>sb-alien:signed</>
 234       except that the variable is treated as an unsigned integer.
 235     </para>
 236   </listitem>
 237   <listitem>
 238     <para>
 239       The foreign type specifier <type>(boolean &amp;optional bits)</> is
 240       similar to an enumeration type, but maps from Lisp <literal>nil</>
 241       and <literal>t</> to C <literal>0</> and <literal>1</>
 242       respectively. <varname>bits</> determines the amount of
 243       storage allocated to hold the truth value.
 244     </para>
 245   </listitem>
 246   <listitem>
 247     <para>
 248       The foreign type specifier <type>single-float</> describes a
 249       floating-point number in IEEE single-precision format.
 250     </para>
 251   </listitem>
 252   <listitem>
 253     <para>
 254       The foreign type specifier <type>double-float</> describes a
 255       floating-point number in IEEE double-precision format.
 256     </para>
 257   </listitem>
 258   <listitem>
 259     <para>
 260       The foreign type specifier
 261       <type>(function result-type &amp;rest arg-types)</>
 262       describes a foreign function that takes arguments of the specified
 263       <varname>arg-types</> and returns a result of type <type>result-type</>.
 264       Note that the only context where a foreign <type>function</> type
 265       is directly specified is in the argument to
 266       <function>sb-alien:alien-funcall</>.
 267       In all other contexts, foreign functions are represented by
 268       foreign function pointer types: <type>(* (function ...))</>.
 269     </para>
 270   </listitem>
 271   <listitem>
 272     <para>
 273       The foreign type specifier <type>sb-alien:system-area-pointer</>
 274       describes a pointer which is represented in Lisp as a
 275       <type>system-area-pointer</> object. &SBCL; exports this type from
 276       <literal>sb-alien</> because &CMUCL; did, but tentatively (as of
 277       the first draft of this section of the manual, &SBCL; 0.7.6) it is
 278       deprecated, since it doesn't seem to be required by user code.
 279     </para>
 280   </listitem>
 281   <listitem>
 282     <para>
 283       The foreign type specifier <type>sb-alien:void</> is
 284       used in function types to declare that no useful value
 285       is returned.  Using <function>alien-funcall</>
 286       to call a <type>void</> foreign function will return
 287       zero values.
 288     </para>
 289   </listitem>
 290   <listitem>
 291     <para>
 292       The foreign type specifier <type>sb-alien:c-string</>
 293       is similar to <type>(* char)</>, but is interpreted as a
 294       null-terminated string, and is automatically converted into a
 295       Lisp string when accessed; or if the pointer is C <literal>NULL</>
 296       or <literal>0</>, then accessing it gives Lisp <literal>nil</>.
 297     </para>
 298     <para>
 299       Assigning a Lisp string to a <type>c-string</> structure field or
 300       variable stores the contents of the string to the memory already
 301       pointed to by that variable.  When a foreign object of type
 302       <type>(* char)</> is assigned to a <type>c-string</>, then the
 303       <type>c-string</> pointer is assigned to.  This allows
 304       <type>c-string</> pointers to be initialized.  For example:
 305       <programlisting>(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
 306         (define-alien-type nil (struct foo (str c-string)))
 307         (defun make-foo (str) (let ((my-foo (make-alien (struct foo))))
 308         (setf (slot my-foo 'str) (make-alien char (length str))
 309               (slot my-foo 'str) str) my-foo))</programlisting>
 310       Storing Lisp <literal>NIL</> in a <type>c-string</> writes C
 311       <literal>NULL</> to the variable.
 312     </para>
 313   </listitem>
 314   <listitem>
 315     <para>
 316       <literal>sb-alien</> also exports translations of these C type
 317       specifiers as foreign type specifiers:
 318         <type>sb-alien:char</>,
 319         <type>sb-alien:short</>,
 320         <type>sb-alien:int</>,
 321         <type>sb-alien:long</>,
 322         <type>sb-alien:unsigned-char</>,
 323         <type>sb-alien:unsigned-short</>,
 324         <type>sb-alien:unsigned-int</>,
 325         <type>sb-alien:unsigned-long</>,
 326         <type>sb-alien:float</>, and
 327         <type>sb-alien:double</>.
 328     </para>
 329   </listitem>
 330
 331 </itemizedlist>
 332
 333 </sect1>
 334
 335 <sect1><title>Operations On Foreign Values</>
 336 <!-- AKA "Alien Operations" in the CMU CL manual -->
 337
 338 <para>This section describes how to read foreign values as Lisp
 339 values, how to coerce foreign values to different kinds of foreign values, and
 340 how to dynamically allocate and free foreign variables.</para>
 341
 342 <sect2><title>Accessing Foreign Values</>
 343
 344 <synopsis>(sb-alien:deref pointer-or-array &amp;rest indices)</>
 345
 346 <para>The <function>sb-alien:deref</> function returns the value pointed to by
 347 a foreign pointer, or the value of a foreign array element. When
 348 dereferencing a pointer, an optional single index can be specified to
 349 give the equivalent of C pointer arithmetic; this index is scaled by
 350 the size of the type pointed to. When dereferencing an array, the
 351 number of indices must be the same as the number of dimensions in the
 352 array type. <function>deref</> can be set with <function>setf</> to
 353 assign a new value.</para>
 354
 355 <synopsis>(sb-alien:slot struct-or-union &amp;rest slot-names)</>
 356
 357 <para>The <function>sb-alien:slot</> function extracts the value of
 358 the slot named <varname>slot-name</> from a foreign <type>struct</> or
 359 <type>union</>. If <varname>struct-or-union</> is a pointer to a
 360 structure or union, then it is automatically dereferenced.
 361 <function>sb-alien:slot</> can be set with <function>setf</> to assign
 362 a new value. Note that <varname>slot-name</> is evaluated, and need
 363 not be a compile-time constant (but only constant slot accesses are
 364 efficiently compiled.)</para>
 365
 366 </sect2>
 367
 368 <sect2><title>Coercing Foreign Values</>
 369
 370 <synopsis>(sb-alien:addr alien-expr)</>
 371
 372 <para>
 373 The <function>sb-alien:addr</> macro
 374 returns a pointer to the location specified by
 375 <varname>alien-expr</>, which must be either a foreign variable, a use of
 376 <function>sb-alien:deref</>, a use of <function>sb-alien:slot</>, or a use of
 377 <function>sb-alien:extern-alien</>.
 378 </para>
 379
 380 <synopsis>(sb-alien:cast foreign-value new-type)</>
 381
 382 <para>The <function>sb-alien:cast</>
 383 converts <varname>foreign-value</> to a new foreign value with the specified
 384 <varname>new-type</>. Both types, old and new, must be foreign pointer,
 385 array or function types.  Note that the resulting Lisp
 386 foreign variable object
 387 is not <function>eq</> to the
 388 argument, but it does refer to the same foreign data bits.</para>
 389
 390 <synopsis>(sb-alien:sap-alien sap type)</>
 391
 392 <para>The <function>sb-alien:sap-alien</> function converts <varname>sap</>
 393 (a system area pointer) to a foreign value with the specified
 394 <varname>type</>. <varname>type</> is not evaluated.
 395 As of &SBCL; 0.7.6, it looks as though this and other SAP functionality
 396 may become deprecated, since it shouldn't be needed by user code.
 397 </para>
 398
 399 <para>The <varname>type</> must be some foreign pointer, array, or
 400 record type.</para>
 401
 402 <synopsis>(sb-alien:alien-sap foreign-value type)</>
 403
 404 <para>The <function>sb-alien:alien-sap</> function
 405 returns the SAP which points to <varname>alien-value</>'s data.
 406 As of &SBCL; 0.7.6, it looks as though this and other SAP functionality
 407 may become deprecated, since it shouldn't be needed by user code.
 408 </para>
 409
 410 <para>The <varname>foreign-value</> must be of some foreign pointer,
 411 array, or record type.</para>
 412
 413 </sect2>
 414
 415 <sect2><title>Foreign Dynamic Allocation</>
 416
 417 <para>Lisp code can call the C standard library functions
 418 <function>malloc</> and <function>free</> to dynamically allocate and
 419 deallocate foreign variables. The Lisp code shares the same allocator
 420 with foreign C code, so it's OK for foreign code to call
 421 <function>free</> on the result of Lisp
 422 <function>sb-alien:make-alien</>, or for Lisp code to call
 423 <function>sb-alien:free-alien</> on foreign objects allocated by C
 424 code.</para>
 425
 426 <synopsis>(sb-alien:make-alien type size)</>
 427
 428 <para>The <function>sb-alien:make-alien</> macro
 429 returns a dynamically allocated foreign value of the specified
 430 <varname>type</> (which is not evaluated.)  The allocated memory is not
 431 initialized, and may contain arbitrary junk.  If supplied,
 432 <varname>size</> is an expression to evaluate to compute the size of the
 433 allocated object.  There are two major cases:
 434 <itemizedlist>
 435   <listitem>
 436     <para>When <varname>type</> is a foreign array type, an array of
 437     that type is allocated and a pointer to it is returned.  Note that you
 438     must use <function>deref</> to change the result to an array before you
 439     can use <function>deref</> to read or write elements:
 440     <programlisting>
 441       (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
 442       (defvar *foo* (make-alien (array char 10)))
 443       (type-of *foo*) => (alien (* (array (signed 8) 10)))
 444       (setf (deref (deref foo) 0) 10) => 10</programlisting>
 445     If supplied, <varname>size</> is used as the first dimension for the
 446     array.</para>
 447   </listitem>
 448   <listitem>
 449     <para>When <varname>type</> is any other foreign type, then an
 450     object for that type is allocated, and a pointer to it is
 451     returned.  So <function>(make-alien int)</> returns a <type>(* int)</>.
 452     If <varname>size</> is specified, then a block of that many
 453     objects is allocated, with the result pointing to the first one.</para>
 454   </listitem>
 455 </itemizedlist>
 456 </para>
 457
 458 <synopsis>(sb-alien:free-alien foreign-value)</>
 459
 460 <para>The <function>sb-alien:free-alien</> function
 461 frees the storage for <varname>foreign-value</>,
 462 which must have been allocated with Lisp <function>make-alien</>
 463 or C <function>malloc</>.</para>
 464
 465 <para>See also the <function>sb-alien:with-alien</> macro, which
 466 allocates foreign values on the stack.</para>
 467
 468 </sect1>
 469
 470 <sect1><title>Foreign Variables</>
 471 <!-- AKA "Alien Variables" in the CMU CL manual -->
 472
 473 <para>
 474 Both local (stack allocated) and external (C global) foreign variables are
 475 supported.
 476 </para>
 477
 478 <sect2><title>Local Foreign Variables</>
 479
 480 <synopsis>(sb-alien:with-alien var-definitions &amp;body body)</>
 481
 482 <para>The <function>with-alien</>
 483 macro establishes local
 484 foreign variables
 485 with the specified
 486 alien types and names.
 487 This form is analogous to defining a local variable in C: additional
 488 storage is allocated, and the initial value is copied.
 489 This form is less
 490 analogous to LET-allocated Lisp variables, since the variables
 491 can't be captured in closures: they live only for the dynamic extent
 492 of the body, and referring to them outside is a gruesome error.
 493 </para>
 494
 495 <para>The <varname>var-definitions</> argument is a list of
 496 variable definitions, each of the form
 497 <programlisting>(name type &amp;optional initial-value)</programlisting>
 498 The names of the variables are established as symbol-macros; the bindings have
 499 lexical scope, and may be assigned with <function>setq</>
 500 or <function>setf</>.
 501 </para>
 502
 503 <para>The <function>with-alien</> macro also establishes
 504 a new scope for named structures
 505 and unions.  Any <varname>type</> specified for a variable may contain
 506 named structure or union types with the slots specified.  Within the
 507 lexical scope of the binding specifiers and body, a locally defined
 508 foreign structure type <type>foo</> can be referenced by its name using
 509 <type>(struct foo)</>.
 510 </para>
 511
 512 </sect2>
 513
 514 <sect2><title>External Foreign Variables</>
 515
 516 <para>
 517 External foreign names are strings, and Lisp names are symbols. When
 518 an external foreign value is represented using a Lisp variable, there
 519 must be a way to convert from one name syntax into the other. The
 520 macros <function>extern-alien</>, <function>define-alien-variable</> and
 521 <function>define-alien-routine</> use this conversion heuristic:
 522 <itemizedlist>
 523   <listitem><para>Alien names are converted to Lisp names by uppercasing and
 524     replacing underscores with hyphens.</para></listitem>
 525   <listitem><para>Conversely, Lisp names are converted to alien names by
 526     lowercasing and replacing hyphens with underscores.</para></listitem>
 527   <listitem><para>Both the Lisp symbol and alien string names may be
 528     separately specified by using a list of the form
 529     <programlisting>(alien-string lisp-symbol)</></para></listitem>
 530 </itemizedlist>
 531
 532 <synopsis>(sb-alien:define-alien-variable name type)</>
 533
 534 <para>
 535 The <function>define-alien-variable</> macro
 536 defines <varname>name</> as an external foreign variable of the
 537 specified foreign <type>type</>.  <varname>name</> and <type>type</> are not
 538 evaluated.  The Lisp name of the variable (see above) becomes a
 539 global alien variable.  Global alien variables
 540 are effectively ``global symbol macros''; a reference to the
 541 variable fetches the contents of the external variable.  Similarly,
 542 setting the variable stores new contents---the new contents must be
 543 of the declared <type>type</>. Someday, they may well be implemented
 544 using the &ANSI; <function>define-symbol-macro</> mechanism, but
 545 as of &SBCL; 0.7.5, they are still implemented using an older
 546 more-or-less parallel mechanism inherited from &CMUCL;.
 547 </para>
 548
 549 <para>
 550 For example, to access a C-level counter <varname>foo</>, one could
 551 write
 552 <programlisting>
 553 (define-alien-variable "foo" int)
 554 ;; Now it is possible to get the value of the C variable foo simply by
 555 ;; referencing that Lisp variable:
 556 (print foo)
 557 (setf foo 14)
 558 (incf foo)</programlisting>
 559 </para>
 560
 561 <synopsis>(sb-alien:get-errno)</>
 562
 563 <para>
 564 Since in modern C libraries, the <varname>errno</> "variable" is typically
 565 no longer a variable, but some bizarre artificial construct
 566 which behaves superficially like a variable within a given thread,
 567 it can no longer reliably be accessed through the ordinary
 568 <varname>define-alien-variable</> mechanism. Instead, &SBCL; provides
 569 the operator <function>sb-alien:get-errno</> to allow Lisp code to read it.
 570 </para>
 571
 572 <synopsis>(sb-alien:extern-alien name type)</>
 573
 574 <para>
 575 The <function>extern-alien</> macro
 576 returns an alien with the specified <type>type</> which
 577 points to an externally defined value. <varname>name</> is not evaluated,
 578 and may be either a string or a symbol. <type>type</> is
 579 an unevaluated alien type specifier.
 580 </para>
 581
 582 </sect1>
 583
 584 <sect1><title>Foreign Data Structure Examples</>
 585 <!-- AKA "Alien Data Structure Example" in the CMU CL manual -->
 586
 587 <para>
 588 Now that we have alien types, operations and variables, we can manipulate
 589 foreign data structures.  This C declaration
 590 <programlisting>
 591 struct foo {
 592     int a;
 593     struct foo *b[100];
 594 };</programlisting>
 595 can be translated into the following alien type:
 596 <programlisting>(define-alien-type nil
 597   (struct foo
 598     (a int)
 599     (b (array (* (struct foo)) 100))))</programlisting>
 600 </para>
 601
 602 <para>
 603 Once the <type>foo</> alien type has been defined as above,
 604 the C expression
 605 <programlisting>
 606 struct foo f;
 607 f.b[7].a</programlisting>
 608 can be translated in this way:
 609 <programlisting>
 610 (with-alien ((f (struct foo)))
 611   (slot (deref (slot f 'b) 7) 'a)
 612   ;;
 613   ;; Do something with f...
 614   )</programlisting>
 615 </para>
 616
 617 <para>
 618 Or consider this example of an external C variable and some accesses:
 619 <programlisting>
 620 struct c_struct {
 621         short x, y;
 622         char a, b;
 623         int z;
 624         c_struct *n;
 625 };
 626 extern struct c_struct *my_struct;
 627 my_struct->x++;
 628 my_struct->a = 5;
 629 my_struct = my_struct->n;</programlisting>
 630 which can be manipulated in Lisp like this:
 631 <programlisting>
 632 (define-alien-type nil
 633   (struct c-struct
 634           (x short)
 635           (y short)
 636           (a char)
 637           (b char)
 638           (z int)
 639           (n (* c-struct))))
 640 (define-alien-variable "my_struct" (* c-struct))
 641 (incf (slot my-struct 'x))
 642 (setf (slot my-struct 'a) 5)
 643 (setq my-struct (slot my-struct 'n))</programlisting>
 644 </para>
 645
 646 </sect1>
 647
 648 <sect1><title>Loading Unix Object Files</>
 649
 650 <para>
 651 Foreign object files can be loaded into the running Lisp process by
 652 calling the functions <function>load-foreign</> or
 653 <function>load-1-foreign</>.
 654 </para>
 655
 656 <para> The <function>sb-alien:load-1-foreign</> function is the more
 657 primitive of the two operations. It loads a single object file. into
 658 the currently running Lisp. The external symbols defining routines and
 659 variables are made available for future external references (e.g. by
 660 <function>extern-alien</>). Forward references to foreign symbols
 661 aren't supported: <function>load-1-foreign</> must be run before any
 662 of the defined symbols are referenced.
 663 </para>
 664
 665 <para><function>sb-alien:load-foreign</> is built in terms of
 666 <function>load-1-foreign</> and some other machinery
 667 like <function>sb-ext:run-program</>.
 668 It accepts a list of files and libraries,
 669 and runs the linker on the files and
 670 libraries, creating an absolute Unix object file which is then
 671 processed by <function>load-1-foreign</>.</para>
 672
 673 <note><para>As of &SBCL; 0.7.5, all foreign code (code loaded
 674 with <function>load-1-function</> or <function>load-function</>) is
 675 lost when a Lisp core is saved with
 676 <function>sb-ext:save-lisp-and-die</>, and no attempt is made to
 677 restore it when the core is loaded. Historically this has been an
 678 annoyance both for &SBCL; users and for &CMUCL; users.
 679 It's hard to solve this problem completely cleanly, but some
 680 generally-reliable partial solution might be useful. Once someone in
 681 either camp gets sufficiently annoyed to create it, &SBCL; is
 682 likely to adopt some mechanism for automatically restoring foreign
 683 code when a saved core is loaded.</para></note>
 684
 685 </sect1>
 686
 687 <sect1><title>Foreign Function Calls</>
 688
 689 <para>
 690 The foreign function call interface allows a Lisp program to call
 691 functions written in other languages using the C calling convention.
 692 </para>
 693
 694 <para>
 695 Lisp sets up various interrupt handling routines and other environment
 696 information when it first starts up, and expects these to be in place
 697 at all times. The C functions called by Lisp should either not change
 698 the environment, especially the interrupt entry points, or should make
 699 sure that these entry points are restored when the C function returns
 700 to Lisp. If a C function makes changes without restoring things to the
 701 way they were when the C function was entered, there is no telling
 702 what will happen.
 703 </para>
 704
 705 <sect2><title>The <function>alien-funcall</> Primitive</title>
 706
 707 <synopsis>(sb-alien:alien-funcall alien-function &amp;rest arguments)</>
 708
 709 <para>
 710 The <function>alien-funcall</> function is the foreign function call
 711 primitive: <varname>alien-function</> is called with the supplied
 712 <varname>arguments</> and its C return value is returned as a Lisp value.
 713 The <varname>alien-function</> is an arbitrary
 714 run-time expression; to refer to a constant function, use
 715 <function>extern-alien</> or a value defined by
 716 <function>define-alien-routine</>.
 717 </para>
 718
 719 <para>
 720 The type of <function>alien-function</>
 721 must be <type>(alien (function ...))</>
 722 or <type>(alien (* (function ...)))</>.
 723 The function type is used to
 724 determine how to call the function (as though it was declared with
 725 a prototype.)  The type need not be known at compile time, but only
 726 known-type calls are efficiently compiled.  Limitations:
 727 <itemizedlist>
 728   <listitem><para>Structure type return values are not implemented.</></>
 729   <listitem><para>Passing of structures by value is not implemented.</></>
 730 </itemizedlist>
 731
 732 <para>
 733 Here is an example which allocates a <type>(struct foo)</>, calls a foreign
 734 function to initialize it, then returns a Lisp vector of all the
 735 <type>(* (struct foo))</> objects filled in by the foreign call:
 736 <programlisting>
 737 ;; Allocate a foo on the stack.
 738 (with-alien ((f (struct foo)))
 739   ;; Call some C function to fill in foo fields.
 740   (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
 741                  (addr f))
 742   ;; Find how many foos to use by getting the A field.
 743   (let* ((num (slot f 'a))
 744          (result (make-array num)))
 745     ;; Get a pointer to the array so that we don't have to keep extracting it:
 746     (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
 747       ;; Loop over the first N elements and stash them in the result vector.
 748       (dotimes (i num)
 749         (setf (svref result i) (deref (deref a) i)))
 750       ;; Voila.
 751       result)))</programlisting>
 752 </para>
 753
 754 </sect2>
 755
 756 <sect2><title>The <function>define-alien-routine</> Macro</>
 757
 758 <synopsis>(sb-alien:define-alien-routine} name result-type &amp;rest arg-specifiers)</>
 759
 760 <para>
 761 The <function>define-alien-routine</> macro is a convenience
 762 for automatically generating Lisp
 763 interfaces to simple foreign functions.  The primary feature is the
 764 parameter style specification, which translates the C
 765 pass-by-reference idiom into additional return values.
 766 </para>
 767
 768 <para>
 769 <varname>name</> is usually a string external symbol, but may also be a
 770 symbol Lisp name or a list of the foreign name and the Lisp name.
 771 If only one name is specified, the other is automatically derived
 772 as for <function>extern-alien</>.
 773 <varname>result-type</> is the alien type of the return value.
 774 </para>
 775
 776 <para>
 777 Each element of the <varname>arg-specifiers</> list
 778 specifies an argument to the foreign function, and is
 779 of the form
 780 <programlisting>(aname atype &amp;optional style)</programlisting>
 781 <varname>aname</> is the symbol name of the argument to the constructed
 782 function (for documentation). <varname>atype</> is the alien type of
 783 corresponding foreign argument.  The semantics of the actual call
 784 are the same as for <function>alien-funcall</>. <varname>style</>
 785 specifies how this argument should be handled at call and return time,
 786 and should be one of the following
 787 <itemizedlist>
 788   <listitem><para><varname>:in</>specifies that the argument is
 789     passed by value. This is the default. <varname>:in</> arguments
 790     have no corresponding return value from the Lisp function.
 791     </para></listitem>
 792   <listitem><para><varname>:copy</> is similar to <varname>:in</>,
 793     but the argument is copied
 794     to a pre-allocated object and a pointer to this object is passed
 795     to the foreign routine.</para></listitem>
 796   <listitem><para><varname>:out</> specifies a pass-by-reference
 797     output value.  The type of the argument must be a pointer to
 798     a fixed-sized object (such as an integer or pointer).
 799     <varname>:out</> and <varname>:in-out</> style cannot
 800     be used with pointers to arrays, records or functions.  An
 801     object of the correct size is allocated on the stack, and
 802     its address is passed to the foreign function.  When the
 803     function returns, the contents
 804     of this location are returned as one of the values of the Lisp
 805     function (and the location is automatically deallocated).
 806     </para></listitem>
 807   <listitem><para><varname>:in-out</> is a combination of
 808     <varname>:copy</> and <varname>:out</>.
 809     The argument is copied to a pre-allocated object and a pointer to
 810     this object is passed to the foreign routine.  On return, the
 811     contents of this location is returned as an additional value.
 812     </para></listitem>
 813 </itemizedlist>
 814 </para>
 815
 816 <note>
 817 <para>
 818 Any efficiency-critical foreign interface function should be inline
 819 expanded, which can be done by preceding the
 820 <function>define-alien-routine</> call with:
 821 <programlisting>(declaim (inline lisp-name))</programlisting>
 822 In addition to avoiding the Lisp call overhead, this allows
 823 pointers, word-integers and floats to be passed using non-descriptor
 824 representations, avoiding consing.)
 825 </para>
 826 </note>
 827
 828 </sect2>
 829
 830 <sect2><title><function>define-alien-routine</> Example</title>
 831
 832 <para>
 833 Consider the C function <function>cfoo</>
 834 with the following calling convention:
 835 <programlisting>
 836 void
 837 cfoo (str, a, i)
 838     char *str;
 839     char *a; /* update */
 840     int *i; /* out */
 841 {
 842   /* body of cfoo(...) */
 843 }</programlisting>
 844 This can be described by the following call to
 845 <function>define-alien-routine</>:
 846 <programlisting>
 847 (define-alien-routine "cfoo" void
 848   (str c-string)
 849   (a char :in-out)
 850   (i int :out))</programlisting>
 851 The Lisp function <function>cfoo</> will have
 852 two arguments (<varname>str</> and <varname>a</>)
 853 and two return values (<varname>a</> and <varname>i</>).
 854
 855 </sect2>
 856
 857 <sect2><title>Calling Lisp From C</>
 858
 859 <para>
 860 Calling Lisp functions from C is sometimes possible, but is extremely
 861 hackish and poorly supported as of &SBCL; 0.7.5.
 862 See <function>funcall0</> ... <function>funcall3</> in
 863 the runtime system. The
 864 arguments must be valid &SBCL; object descriptors (so that
 865 e.g. fixnums must be
 866 left-shifted by 2.) As of &SBCL; 0.7.5, the format
 867 of object descriptors is documented only by the source code and
 868 by the old &CMUCL; "INTERNALS" documentation.</para>
 869
 870 <para> Note that the garbage collector moves objects, and won't be
 871 able to fix up any references in C variables, so either turn GC off or
 872 don't keep Lisp pointers in C data unless they are to statically
 873 allocated objects. It is possible to use the
 874 <function>sb-ext:purify</> function to place live data structures in
 875 static space so that they won't move during GC. </para>
 876
 877 <!-- FIXME: This is a "changebar" section from the CMU CL manual.
 878      I (WHN 2002-07-14) am not very familiar with this content, so
 879      I'm not immediately prepared to try to update it for SBCL, and
 880      I'm not feeling masochistic enough to work to encourage this
 881      kind of low-level hack anyway. However, I acknowledge that callbacks
 882      are sometimes really really necessary, so I include the original
 883      text in case someone is hard-core enough to benefit from it. If
 884      anyone brings the information up to date for SBCL, it belong
 885      either in the main manual or on a CLiki SBCL Internals page.
 886 LaTeX \subsection{Accessing Lisp Arrays}
 887 LaTeX
 888 LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
 889 LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
 890 LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
 891 LaTeX   use and this memory is typically about 8 MB above the start of the C
 892 LaTeX   heap.  Thus, only about 8 MB of memory can be dynamically
 893 LaTeX   allocated.}.
 894 LaTeX
 895 LaTeX To overcome this limitation, it is possible to access the content of
 896 LaTeX Lisp arrays which are limited only by the amount of physical memory
 897 LaTeX and swap space available.  However, this technique is only useful if
 898 LaTeX the foreign function takes pointers to memory instead of allocating
 899 LaTeX memory for itself.  In latter case, you will have to modify the
 900 LaTeX foreign functions.
 901 LaTeX
 902 LaTeX This technique takes advantage of the fact that \cmucl{} has
 903 LaTeX specialized array types (\pxlref{specialized-array-types}) that match
 904 LaTeX a typical C array.  For example, a \code{(simple-array double-float
 905 LaTeX   (100))} is stored in memory in essentially the same way as the C
 906 LaTeX array \code{double x[100]} would be.  The following function allows us
 907 LaTeX to get the physical address of such a Lisp array:
 908 LaTeX \begin{example}
 909 LaTeX (defun array-data-address (array)
 910 LaTeX   "Return the physical address of where the actual data of an array is
 911 LaTeX stored.
 912 LaTeX
 913 LaTeX ARRAY must be a specialized array type in CMU Lisp.  This means ARRAY
 914 LaTeX must be an array of one of the following types:
 915 LaTeX
 916 LaTeX                   double-float
 917 LaTeX                   single-float
 918 LaTeX                   (unsigned-byte 32)
 919 LaTeX                   (unsigned-byte 16)
 920 LaTeX                   (unsigned-byte  8)
 921 LaTeX                   (signed-byte 32)
 922 LaTeX                   (signed-byte 16)
 923 LaTeX                   (signed-byte  8)
 924 LaTeX "
 925 LaTeX   (declare (type (or #+signed-array (array (signed-byte 8))
 926 LaTeX                      #+signed-array (array (signed-byte 16))
 927 LaTeX                      #+signed-array (array (signed-byte 32))
 928 LaTeX                      (array (unsigned-byte 8))
 929 LaTeX                      (array (unsigned-byte 16))
 930 LaTeX                      (array (unsigned-byte 32))
 931 LaTeX                      (array single-float)
 932 LaTeX                      (array double-float))
 933 LaTeX                  array)
 934 LaTeX            (optimize (speed 3) (safety 0))
 935 LaTeX            (ext:optimize-interface (safety 3)))
 936 LaTeX   ;; with-array-data will get us to the actual data.  However, because
 937 LaTeX   ;; the array could have been displaced, we need to know where the
 938 LaTeX   ;; data starts.
 939 LaTeX   (lisp::with-array-data ((data array)
 940 LaTeX                           (start)
 941 LaTeX                           (end))
 942 LaTeX     (declare (ignore end))
 943 LaTeX     ;; DATA is a specialized simple-array.  Memory is laid out like this:
 944 LaTeX     ;;
 945 LaTeX     ;;   byte offset    Value
 946 LaTeX     ;;        0         type code (should be 70 for double-float vector)
 947 LaTeX     ;;        4         4 * number of elements in vector
 948 LaTeX     ;;        8         1st element of vector
 949 LaTeX     ;;      ...         ...
 950 LaTeX     ;;
 951 LaTeX     (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
 952 LaTeX           (type-size (let ((type (array-element-type data)))
 953 LaTeX                        (cond ((or (equal type '(signed-byte 8))
 954 LaTeX                                   (equal type '(unsigned-byte 8)))
 955 LaTeX                               1)
 956 LaTeX                              ((or (equal type '(signed-byte 16))
 957 LaTeX                                   (equal type '(unsigned-byte 16)))
 958 LaTeX                               2)
 959 LaTeX                              ((or (equal type '(signed-byte 32))
 960 LaTeX                                   (equal type '(unsigned-byte 32)))
 961 LaTeX                               4)
 962 LaTeX                              ((equal type 'single-float)
 963 LaTeX                               4)
 964 LaTeX                              ((equal type 'double-float)
 965 LaTeX                               8)
 966 LaTeX                              (t
 967 LaTeX                               (error "Unknown specialized array element type"))))))
 968 LaTeX       (declare (type (unsigned-byte 32) addr)
 969 LaTeX                (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
 970 LaTeX       (system:int-sap (the (unsigned-byte 32)
 971 LaTeX                         (+ addr (* type-size start)))))))
 972 LaTeX \end{example}
 973 LaTeX
 974 LaTeX Assume we have the C function below that we wish to use:
 975 LaTeX \begin{example}
 976 LaTeX   double dotprod(double* x, double* y, int n)
 977 LaTeX   \{
 978 LaTeX     int k;
 979 LaTeX     double sum = 0;
 980 LaTeX
 981 LaTeX     for (k = 0; k < n; ++k) \{
 982 LaTeX       sum += x[k] * y[k];
 983 LaTeX     \}
 984 LaTeX   \}
 985 LaTeX \end{example}
 986 LaTeX The following example generates two large arrays in Lisp, and calls the C
 987 LaTeX function to do the desired computation.  This would not have been
 988 LaTeX possible using \code{malloc} or \code{make-alien} since we need about
 989 LaTeX 16 MB of memory to hold the two arrays.
 990 LaTeX \begin{example}
 991 LaTeX   (define-alien-routine "dotprod" double
 992 LaTeX     (x (* double-float) :in)
 993 LaTeX     (y (* double-float) :in)
 994 LaTeX     (n int :in))
 995 LaTeX
 996 LaTeX   (let ((x (make-array 1000000 :element-type 'double-float))
 997 LaTeX         (y (make-array 1000000 :element-type 'double-float)))
 998 LaTeX     ;; Initialize X and Y somehow
 999 LaTeX     (let ((x-addr (system:int-sap (array-data-address x)))
1000 LaTeX           (y-addr (system:int-sap (array-data-address y))))
1001 LaTeX       (dotprod x-addr y-addr 1000000)))
1002 LaTeX \end{example}
1003 LaTeX In this example, it may be useful to wrap the inner \code{let}
1004 LaTeX expression in an \code{unwind-protect} that first turns off garbage
1005 LaTeX collection and then turns garbage collection on afterwards.  This will
1006 LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
1007 LaTeX have obtained the (now erroneous) addresses but before the call to
1008 LaTeX \code{dotprod} is made.
1009 LaTeX
1010 -->
1011
1012 </sect1>
1013
1014 <sect1><title>Step-By-Step Example of the Foreign Function Interface</>
1015
1016 <para>
1017 This section presents a complete example of an interface to a somewhat
1018 complicated C function.
1019 </para>
1020
1021 <para>
1022 Suppose you have the following C function which you want to be able to
1023 call from Lisp in the file <filename>test.c</>
1024 <programlisting>
1025 struct c_struct
1026 {
1027   int x;
1028   char *s;
1029 };
1030
1031 struct c_struct *c_function (i, s, r, a)
1032     int i;
1033     char *s;
1034     struct c_struct *r;
1035     int a[10];
1036 {
1037   int j;
1038   struct c_struct *r2;
1039
1040   printf("i = %d\n", i);
1041   printf("s = %s\n", s);
1042   printf("r->x = %d\n", r->x);
1043   printf("r->s = %s\n", r->s);
1044   for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
1045   r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
1046   r2->x = i + 5;
1047   r2->s = "a C string";
1048   return(r2);
1049 };</programlisting>
1050 </para>
1051
1052 <para>
1053 It is possible to call this C function from Lisp using the file
1054 <filename>test.lisp</> containing
1055 <programlisting>
1056 (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
1057 (cl:in-package "TEST-C-CALL")
1058
1059 ;;; Define the record C-STRUCT in Lisp.
1060 (define-alien-type nil
1061     (struct c-struct
1062             (x int)
1063             (s c-string)))
1064
1065 ;;; Define the Lisp function interface to the C routine.  It returns a
1066 ;;; pointer to a record of type C-STRUCT.  It accepts four parameters:
1067 ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
1068 ;;; record; and A, a pointer to the array of 10 ints.
1069 ;;;
1070 ;;; The INLINE declaration eliminates some efficiency notes about heap
1071 ;;; allocation of alien values.
1072 (declaim (inline c-function))
1073 (define-alien-routine c-function
1074     (* (struct c-struct))
1075   (i int)
1076   (s c-string)
1077   (r (* (struct c-struct)))
1078   (a (array int 10)))
1079
1080 ;;; a function which sets up the parameters to the C function and
1081 ;;; actually calls it
1082 (defun call-cfun ()
1083   (with-alien ((ar (array int 10))
1084                (c-struct (struct c-struct)))
1085     (dotimes (i 10)                     ; Fill array.
1086       (setf (deref ar i) i))
1087     (setf (slot c-struct 'x) 20)
1088     (setf (slot c-struct 's) "a Lisp string")
1089
1090     (with-alien ((res (* (struct c-struct))
1091                       (c-function 5 "another Lisp string" (addr c-struct) ar)))
1092       (format t "~&amp;back from C function~%")
1093       (multiple-value-prog1
1094           (values (slot res 'x)
1095                   (slot res 's))
1096
1097         ;; Deallocate result. (after we are done referring to it:
1098         ;; "Pillage, *then* burn.")
1099         (free-alien res)))))</programlisting>
1100 </para>
1101
1102 <para>
1103 To execute the above example, it is necessary to compile the C routine,
1104 e.g.:
1105 <userinput>cc -c test.c</>
1106 (In order to enable incremental loading with some linkers, you may need
1107 to say
1108 <userinput>cc -G 0 -c test.c</>)
1109 </para>
1110
1111 <para>
1112 Once the C code has been compiled, you can start up Lisp and load it in:
1113 <userinput>sbcl</>.
1114 Lisp should start up with its normal prompt.</para>
1115
1116 <para>
1117 Within Lisp,
1118 compile the Lisp file. (This step can be done separately. You don't
1119 have to recompile every time.)
1120 <userinput>(compile-file "test.lisp")</>
1121
1122 <para>
1123 Within Lisp, load the foreign object file to define the necessary
1124 symbols:
1125 <userinput>(load-foreign "test.o")</>.
1126 This must be done before loading any code that refers
1127 to these symbols.
1128 <para>
1129
1130 <para>
1131 Now you can load the compiled Lisp ("fasl") file into Lisp:
1132 <userinput>(load "test.fasl")</>
1133 And once the Lisp file is loaded, you can call the
1134 Lisp routine that sets up the parameters and calls the C
1135 function:
1136 <userinput>(test-c-call::call-cfun)</>
1137 </para>
1138
1139 <para>
1140 The C routine should print the following information to standard output:
1141 <!-- FIXME: What should be here is a verbatim environment for computer
1142      output, but since I don't know one in DocBook, I made do with
1143      PROGRAMLISTING for now... -->
1144 <programlisting>i = 5
1145 s = another Lisp string
1146 r->x = 20
1147 r->s = a Lisp string
1148 a[0] = 0.
1149 a[1] = 1.
1150 a[2] = 2.
1151 a[3] = 3.
1152 a[4] = 4.
1153 a[5] = 5.
1154 a[6] = 6.
1155 a[7] = 7.
1156 a[8] = 8.
1157 a[9] = 9.</programlisting>
1158 After return from the C function,
1159 the Lisp wrapper function should print the following output:
1160 <programlisting>back from C function</programlisting>
1161 And upon return from the Lisp wrapper function,
1162 before the next prompt is printed, the
1163 Lisp read-eval-print loop should print the following return values:
1164 <!-- FIXME: As above, it's not a program listing, but computer output... -->
1165 <programlisting>
1166 10
1167 "a C string"
1168 </programlisting>
1169 </para>
1170
1171 </sect1>
1172
1173 </chapter>