1
\input texinfo @c -*-Texinfo-*-
2
@comment %**start of header
3
@setfilename mit-scheme-ffi
5
@settitle FFI @value{VERSION}
6
@comment %**end of header
18
This manual documents @acronym{FFI} @value{VERSION}.
20
Copyright @copyright{} 2006, 2007, 2008, 2009, 2010 Matthew Birkholz
23
Permission is granted to copy, distribute and/or modify this document
24
under the terms of the GNU Free Documentation License, Version 1.2 or
25
any later version published by the Free Software Foundation; with no
26
Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts.
27
A copy of the license is included in the section entitled ``GNU Free
28
Documentation License.''
32
@dircategory Programming Languages
34
* FFI: (mit-scheme-ffi). MIT/GNU Scheme Foreign Functions
38
@title The FFI Reference Manual
39
@subtitle a Foreign Function Interface (@value{VERSION})
40
@subtitle for MIT/GNU Scheme version 7.7.90+
41
@author by Matt Birkholz
43
@vskip 0pt plus 1filll
48
@node Top, Introduction, (dir), (dir)
55
* Introduction:: A synopsis and quick summary.
56
* C Declarations:: Declare C types and functions.
57
* Alien Data:: Manipulate C data.
58
* Alien Functions:: Generate callout trampolines and call them.
59
* Callbacks:: Generate callback trampolines and get interrupted by them.
60
* Compiling and Linking:: Build and install the shim.
61
* Hello World:: A short example.
62
* GNU Free Documentation License::
66
@node Introduction, C Declarations, Top, Top
69
This FFI provides Scheme syntax for calling C functions and accessing
70
C data. The functions and data structures are declared in a case
71
sensitive @file{.cdecl} file, which is used by a shim generator to
72
produce callout and callback trampoline functions. The trampolines
73
are compiled and linked to the C toolkit, producing a shared object
74
that Scheme can dynamically load.
78
Examples of the new syntax:
84
(malloc (C-sizeof "GdkEvent"))
85
@myresult{} #[alien 42 0x081afc60]
89
(C-> @verb{"#@42"} "GdkEvent any type")
93
(C->= @verb{"#@42"} "GdkEvent any type" 13)
101
(C-enum "GdkEventType" 14)
102
@myresult{} |GDK_MAP|
106
(C-sizeof "GdkColor")
111
(C-offset "GdkColor blue")
116
(C-array-loc @verb{"#@43"} "GdkColor" (C-enum "GTK_STATE_NORMAL"))
117
@myresult{} #[alien 44 0x081afc60] @r{; New alien.}
121
(C-array-loc! @verb{"#@43"} "GdkColor" (C-enum "GTK_STATE_PRELIGHT"))
122
@myresult{} #[alien 43 0x081afc78] @r{; Modified alien.}
126
(C-call "gtk_window_new" retval args @dots{})
127
@myresult{} #!unspecific
131
(C-callback "delete_event")
132
@myresult{} #[alien-function 44 Scm_delete_event]
136
(C-callback (lambda (window event) @dots{}))
137
@myresult{} 13 @r{; A fixnum registration ID.}
141
@comment The C-array-loc! example assumes 2 GdkColors are 6 words, #x18bytes.
142
@comment 0x081afc78 - 0x081afc60 = 0x18
146
A Scheme-like declaration of a toolkit's C functions, constants, and
147
data types is given in a case sensitive @file{.cdecl} file. The C
148
declarations look like this:
151
(extern (* GtkWidget) @r{; gtk+-2.4.0/gtk/gtkwindow.h}
153
(type GtkWindowType))
155
(typedef GtkWindowType @r{; gtk+-2.4.0/gtk/gtkenums.h}
157
(GTK_WINDOW_TOPLEVEL)
161
The @strong{@code{c-generate}} procedure reads these declarations and
162
writes three files: @file{@i{library}-types.bin} (a fasdump of the
163
parsed declarations), @file{@i{library}-const.c} (a C program that
164
prints C constants and struct offsets), and @file{@i{library}-shim.c}
165
(trampoline functions adapting Scheme procedure application to C
166
function call). The @file{-const.c} program generates a
167
@file{-const.scm} file, which can be syntaxed to produce a
168
@file{-const.bin} file.
172
(c-generate "prhello" "#include <gtk/gtk.h>")
175
The @file{-types.bin} and @file{-const.bin} files together provide
176
the information needed to expand @code{C-...} syntax, and are only
177
needed at syntax time. The compiled @file{-shim.so} file is used at
178
run time, dynamically loaded into the Scheme machine. @ref{Compiling
179
and Linking}, which describes these files in more detail, and shows
180
how they might be built and installed.
183
(C-include "prhello")
186
The @strong{@code{C-include}} syntax loads the @file{-types.bin} and
187
@file{-const.bin} files @emph{at syntax time}. It should appear
188
at the top level of any file containing @code{C-...} syntax, or be
189
evaluated in the syntax environment of such code.
191
The @strong{@code{C-call}} syntax arranges to invoke a callout
192
trampoline. Arguments to the trampoline can be integers, floats,
193
strings or aliens (non-heap pointers, to C data structures,
197
(let ((alien (make-alien '|GtkWidget|)))
198
(C-call "gtk_window_new" alien type)
199
(if (alien-null? alien) (error "could not open new window"))
203
The @strong{@code{C-callback}} syntax is used when registering a
204
Scheme callback trampoline. The two forms of the syntax provide two
205
arguments for the registration function: the callback trampoline's
206
address, and a ``user data'' argument. When the toolkit calls the
207
trampoline, it must provide the fixnum-sized user data as an argument.
210
(C-call "g_signal_connect" window "delete_event"
211
(C-callback "delete_event") ; @r{@i{e.g. &Scm_delete_event}}
212
(C-callback ; @r{@i{e.g. 314}}
213
(lambda (window event)
214
(C-call "gtk_widget_destroy" window)
218
The first use of @code{C-callback} (above) expands into a callback
219
trampoline address --- an alien function. The second use evaluates to
220
a fixnum, which is associated with the given Scheme procedure.
222
The @strong{@code{C->}} and @strong{@code{C->=}} syntaxes peek and
223
poke values into alien data structures. They take an alien and a
224
constant string specifying the alien data type and the member to be
229
(C-> alien "GdkRectangle y")
231
(#[primitive c-peek-int] alien 4)
235
(C->= alien "GdkRectangle width" 0)
237
(#[primitive c-poke-int] alien 8 0)
243
(C-> alien "GdkEvent any type")
245
(#[primitive c-peek-int] alien 0)
253
(#[primitive c-peek-float] alien 0)
257
A three argument form of the syntax provides an alien to receive a
258
peeked pointer. This avoids consing a new alien.
261
(C-> alien "GtkWidget style" alien)
264
The above syntax is understood to say ``The data at this @code{alien}
265
address is a GtkWidget. Load its @code{style} member (an alien
266
address), into @code{alien} (clobbering @code{alien}'s old address).''
268
The @strong{@code{C-enum}}, @strong{@code{C-sizeof}} and
269
@strong{@code{C-offset}} syntaxes all
270
transform into integer constants. The last two transform into a padded
271
byte size and a byte offset respectively.
275
(C-enum "GTK_WINDOW_POPUP")
281
(C-sizeof "GdkColor")
287
(C-offset "GdkColor blue")
294
The two element form of the @code{C-enum} syntax can be used to find
295
the name of a constant given its runtime value. It expects the name
296
of an enum type in a constant string. If the runtime (second)
297
argument is not one of the constants declared by that type, the
298
returned value is @code{#f}.
302
(C-enum "GdkEventType" (C-> @verb{"#@42"} "GdkEvent any type"))
308
The @strong{@code{c-array-loc}} and @strong{@code{c-array-loc!}}
309
syntaxes compute the locations of C array elements. They can be used
310
to advance a scan pointer or locate an element by its index. The
311
examples in the synopsis might expand as shown here.
314
(C-array-loc @verb{"#@43"} "GdkColor" (C-enum "GTK_STATE_NORMAL"))
316
(alien-byte-increment @verb{"#@43"} (* (C-sizeof "GdkColor")
317
(C-enum "GTK_STATE_NORMAL")))
319
(alien-byte-increment @verb{"#@43"} 0)
323
(C-array-loc! @verb{"#@43"} "GdkColor" (C-enum "GTK_STATE_PRELIGHT"))
325
(alien-byte-increment! @verb{"#@43"} (* (C-sizeof "GdkColor")
326
(C-enum "GTK_STATE_PRELIGHT")))
328
(alien-byte-increment! @verb{"#@43"} 24)
333
A simple scan of characters in the wide string @code{alien} might
337
(let ((len (C-> alien "toolkit_string_type int_member"))
338
(scan (C-> alien "toolkit_string_type array_member")))
341
(let ((wchar (C-> scan "wchar")))
343
(C-array-loc! scan "wchar" 1)
347
That is a quick look at the facilities. The next section describes
348
the C declaration language, and the following sections examine the FFI's
349
syntax and runtime facilities in detail. Final sections provide an
350
example program and show how its dynamically loaded shim is built.
353
@node C Declarations, Alien Data, Introduction, Top
354
@chapter C Declarations
356
A shim between Scheme and a C toolkit is specified by a case sensitive
357
@file{.cdecl} file containing Scheme-like declarations of all relevant
358
toolkit types, constants, and functions. Callback functions to be
359
passed to the toolkit are also specified here.
361
There are some limitations on the C types that can be declared.
362
Basic, struct, union, enum and pointer types are allowed, but
363
bit-field members are not supported. C function parameters can be
364
basic, enum or pointer types. The return type of a C function is the
365
same plus @code{void}. Basically, no struct or union argument or
366
return types, at the moment.
368
Each top-level form in the C declaration file must look like one of
373
(typedef Name @var{any})
374
(struct Name (Member @var{type}) @dots{})
375
(union Name (Member @var{type}) @dots{})
376
(enum @i{Name} (Member) @dots{})
377
(extern @var{return-type} Name (param1 @var{arg-type}) @dots{})
378
(callback @var{return-type} Name (param1 @var{arg-type}) @dots{})
381
An enum's @i{@var{Name}} is optional.
383
@var{arg-type} is currently restricted to the following forms. It is
384
assumed that a lone @var{Name} is defined as a type on this list:
391
(enum @i{Name} (Member) @dots{})
394
@var{return-type} can be either @var{arg-type} or the word @code{void}.
396
@var{basics} can be any of the words: @code{char}, @code{uchar},
397
@code{short}, @code{ushort}, @code{int}, @code{uint}, @code{long},
398
@code{ulong}, @code{float}, or @code{double} (all lowercase).
400
@var{type} includes structs and unions:
405
(struct @i{Name} (Member @var{type}) @dots{})
407
(union @i{Name} (Member @var{type}) @dots{})
410
@var{any} is any @var{type} @emph{or} @code{void}.
412
The @code{include} expression includes another @file{.cdecl} file in
413
the current @file{.cdecl} file. The string argument is interpreted
414
relative to the current file's directory.
416
While the informal grammar above allows anonymous structs to be
417
specified for argument or member types, they are of little use outside
418
top-level, @i{named} struct or union declarations. The peek and poke
419
(@code{C->} and @code{C->=}) syntax expects a type name (e.g.
420
@code{"GdkEventAny"} or @code{"struct _GdkEventAny"}) before any
424
(C-include "prhello")
427
The @strong{@code{C-include}} syntax takes a library name and loads
428
the corresponding @file{-types} and @file{-const} files at syntax
429
time. This makes the C types and constants available to the other
430
@code{C-...} syntax expanders. The form binds @code{c-includes} in
431
the syntax environment @i{unless} it is already defined there. Thus a
432
@code{(C-includes "library")} form can be placed at the top of every
433
file with @code{C-...} syntax, @emph{or} loaded into the syntax-time
434
environment of those files.
437
@node Alien Data, Alien Functions, C Declarations, Top
440
A C data structure is represented by an alien containing the data
441
structure's memory address. ``Peek'' primitives are available to read
442
pointers and the basic C types (e.g. ints, floats) at small (fixnum)
443
offsets from an alien's address. They return to Scheme an alien
444
address, integer or flonum as appropriate. ``Poke'' primitives
445
do the reverse, storing pointers, integers or floats at fixnum offsets
446
from alien addresses.
447
Other procedures on aliens are @code{alien?},
448
@code{alien-null?}, @code{alien-null!}, @code{copy-alien}, @code{alien=?},
449
@code{alien-byte-increment}, and @code{c-peek-cstring}. Refer to
450
@file{ffi.pkg} in The Source for a complete list.
452
The @code{C->} and @code{C->=} syntaxes apply the peek and poke
453
primitives to constant offsets. They expect their first argument
454
subform to be a constant string --- space-separated words naming a C
455
type and any member to be accessed. A member within a struct or union
456
member is specified by appending its name. For example @code{"struct
457
_GdkEvent any window"} would specify a peek at the @code{window}
458
member of the @code{any} member of the @code{struct _GdkEvent} data at
459
some alien address. Note that the final member's type must be a basic
460
C type, pointer type, or enum type. Otherwise, an error is signaled
465
(C-> alien "struct _GdkEvent any window" window-alien)
467
(#[primitive c-peek-pointer] alien 0 window-alien)
469
#[alien 44 (* GdkWindow) 0x081afc60]
473
Note that in the example above, the final member has a pointer type.
474
In this case an extra alien argument can be provided to receive the
475
peeked pointer. Otherwise a new alien is created and returned.
479
The @code{malloc} procedure returns an alien that will automatically
480
free the malloced memory when it is garbage collected.
481
It can also be explicitly freed with the @code{free} procedure. The alien
482
address can be incremented to scan the malloced memory, then freed
483
(without returning it to the original, malloced address). A band
484
restore marks all malloced aliens as though they have been freed.
487
(free (malloc '|GdkRectangle|))
491
@node Alien Functions, Callbacks, Alien Data, Top
492
@chapter Alien Functions
494
The @code{C-call} syntax produces code that applies @code{call-alien}
495
to an alien function structure --- a cache for the callout
496
trampoline's entry address.
500
(C-call "gtk_button_new" (make-alien '(* |GtkWidget|)))
502
(call-alien '#[alien-function gtk_button_new] (make-alien @dots{}))
506
The alien function contains all the information needed to load the
507
callout trampoline on demand (i.e. its name and library). Once the
508
alien function has cached the entry address, @code{call-alien} can
509
invoke the trampoline (via @code{#[primitive c-call]}). The
510
trampoline gets its arguments off the Scheme stack, converts them to C
511
values, calls the C function, conses a result, and returns it to
512
Scheme. As a special case a function returning a pointer type
513
expects an extra first argument. If this argument is @code{#f}, the
514
return value is discarded. If the argument is an alien, the
515
function's return value clobbers the alien's address. This makes it
516
easy to grab pointers to toolkit resources without dropping them, or
517
avoid unnecessary consing of aliens.
519
The @code{alien-function} structures are fasdumpable. The caching
520
mechanism invalidates the cache when a band is restored, or a
521
fasdumped object is fasloaded. The alien function will lookup the
522
trampoline entry point again on demand.
525
@node Callbacks, Compiling and Linking, Alien Functions, Top
528
A callback declaration must include a parameter named ``ID''. The ID
529
argument will be used to find the Scheme callback procedure. It must
530
be the same ``user data'' value provided to the toolkit when the
531
callback was registered. For example, a callback trampoline named
532
@code{Scm_delete_event} might be declared like this:
537
(window (* GtkWidget))
538
(event (* GdkEventAny))
542
The callback might be registered with the toolkit like this:
545
(C-call "g_signal_connect" window "delete_event"
546
(C-callback "delete_event") ; @r{@i{e.g. &Scm_delete_event}}
547
(C-callback ; @r{@i{e.g. 314}}
548
(lambda (window event)
549
(C-call "gtk_widget_destroy" window)
553
The toolkit's registration function, @code{g_signal_connect}, would be
559
(object (* GtkObject))
561
(CALLBACK GtkSignalFunc)
565
This function should have parameters named @code{CALLBACK} and
566
@code{ID}. The callout trampoline will convert the callback argument
567
from a Scheme alien function to an entry address. The @code{ID} argument
568
will be converted to a C integer and then cast to its declared type
569
(in this example, @code{gpointer}).
571
Note that the registered callback procedures are effectively pinned.
572
They cannot be garbage collected. They are ``on call'' to handle
573
callbacks from the toolkit until they are explicitly de-registered. A
574
band restore automatically de-registers all callbacks.
576
The callback procedures are executed like an interrupt handler. They
577
actually interrupt the thread executing the most recent callout,
578
e.g. to @code{gtk_main}. The thread runs with thread switching
579
disabled for the duration of the callback, and can callout to the
580
toolkit, which can callback again. The (nested) callbacks and nested
581
callouts all run in the same thread, and so will return in LIFO order
582
as expected by the toolkit. Note that the runtime system will not
583
balk at a callback procedure that calls @code{yield-thread}, waits for
584
I/O, sleeps, or otherwise causes a thread switch. Presumably such a
585
procedure has some other way of enforcing the LIFO ordering.
587
The @code{outf-console} procedure is provided for debugging purposes.
588
It writes one or more argument strings (and @code{write}s any
589
non-strings) to the console and flushes, atomically, via a machine
590
primitive, bypassing the runtime's I/O buffering and thread switching.
591
Thus multiple debugging trace messages arrive on the console intact
595
@node Compiling and Linking, Hello World, Callbacks, Top
596
@chapter Compiling and Linking
598
The @strong{@code{c-generate}} procedure takes a library name and an
599
optional preamble. It reads the @file{@i{library}.cdecl} file and
600
writes two @file{.c} files. The preamble is included at the top of
601
both. It typically contains @code{#include} C pre-processor
602
directives required by the C library, but could include additional
603
shim code. Here is a short script that generates a shim for the
604
example ``Hello, World!'' program.
608
(c-generate "prhello" "#include <gtk/gtk.h>")
611
This script will produce three files:
616
This file contains the trampoline functions --- one for each declared
617
C extern or callback. It includes the @file{mit-scheme.h} header
618
file, found in the @code{AUXDIR} directory ---
619
e.g. @file{/usr/local/lib/mit-scheme/}.
621
@item prhello-const.c
622
This file contains a C program that creates
623
@file{prhello-const.scm}. It is compiled and linked
624
as normal for programs using the toolkit, and does not depend on the
625
Scheme machine. It does not actually call any
626
toolkit functions. It just collects information from the compiler
627
about the declared C types and constants.
629
@item prhello-types.bin
630
This file is a fasdumped @code{c-includes} structure containing all of
631
the types, constants and functions declared in the @file{.cdecl} file.
635
The following Makefile rules describe the process of building and
636
installing a shim for the example ``Hello, World!'' program.
640
install-example: build-example
641
$(INSTALL_DATA) prhello-types.bin ../lib/.
642
$(INSTALL_DATA) prhello-const.bin ../lib/.
643
$(INSTALL_DATA) prhello-shim.so ../lib/.
645
build-example: prhello-shim.so prhello-types.bin prhello-const.bin
647
prhello-shim.so: prhello-shim.o
648
$(CC) -shared -fPIC -o $@ $^ `pkg-config --libs gtk+-2.0`
650
prhello-shim.o: prhello-shim.c
651
$(CC) -I../lib -Wall -fPIC `pkg-config --cflags gtk+-2.0` -o $@ -c $<
653
prhello-shim.c prhello-const.c prhello-types.bin: prhello.cdecl
654
(echo "(load-option 'FFI)"; \
655
echo '(C-generate "prhello" "#include <gtk/gtk.h>")') \
656
| ../microcode/scheme --library ../lib --batch-mode
658
prhello-const.bin: prhello-const.scm
659
echo '(sf "prhello-const")' | mit-scheme --compiler --batch-mode
661
prhello-const.scm: prhello-const
664
prhello-const: prhello-const.o
666
$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ `pkg-config --libs gtk+-2.0`
668
prhello-const.o: prhello-const.c
669
$(CC) `pkg-config --cflags gtk+-2.0` $(CFLAGS) -o $@ -c $<
674
@node Hello World, GNU Free Documentation License, Compiling and Linking, Top
684
includes the C declarations and Scheme code required to implement
685
Havoc Pennington's Hello World example from
686
@uref{http://developer.gnome.org/doc/GGAD/, GGAD}. For an extra,
687
Schemely treat, its @code{delete_event} callback is a Scheme procedure
688
closed over a binding of @code{counter} that is used to implement some
689
impertinent behavior.
691
@verbatiminclude prhello.scm
694
Here are the C declarations.
696
@verbatiminclude prhello.cdecl
700
@node GNU Free Documentation License, , Hello World, Top
701
@appendix GNU Free Documentation License
703
@center Version 1.2, November 2002
706
Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
707
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
709
Everyone is permitted to copy and distribute verbatim copies
710
of this license document, but changing it is not allowed.
717
The purpose of this License is to make a manual, textbook, or other
718
functional and useful document @dfn{free} in the sense of freedom: to
719
assure everyone the effective freedom to copy and redistribute it,
720
with or without modifying it, either commercially or noncommercially.
721
Secondarily, this License preserves for the author and publisher a way
722
to get credit for their work, while not being considered responsible
723
for modifications made by others.
725
This License is a kind of ``copyleft'', which means that derivative
726
works of the document must themselves be free in the same sense. It
727
complements the GNU General Public License, which is a copyleft
728
license designed for free software.
730
We have designed this License in order to use it for manuals for free
731
software, because free software needs free documentation: a free
732
program should come with manuals providing the same freedoms that the
733
software does. But this License is not limited to software manuals;
734
it can be used for any textual work, regardless of subject matter or
735
whether it is published as a printed book. We recommend this License
736
principally for works whose purpose is instruction or reference.
739
APPLICABILITY AND DEFINITIONS
741
This License applies to any manual or other work, in any medium, that
742
contains a notice placed by the copyright holder saying it can be
743
distributed under the terms of this License. Such a notice grants a
744
world-wide, royalty-free license, unlimited in duration, to use that
745
work under the conditions stated herein. The ``Document'', below,
746
refers to any such manual or work. Any member of the public is a
747
licensee, and is addressed as ``you''. You accept the license if you
748
copy, modify or distribute the work in a way requiring permission
751
A ``Modified Version'' of the Document means any work containing the
752
Document or a portion of it, either copied verbatim, or with
753
modifications and/or translated into another language.
755
A ``Secondary Section'' is a named appendix or a front-matter section
756
of the Document that deals exclusively with the relationship of the
757
publishers or authors of the Document to the Document's overall
758
subject (or to related matters) and contains nothing that could fall
759
directly within that overall subject. (Thus, if the Document is in
760
part a textbook of mathematics, a Secondary Section may not explain
761
any mathematics.) The relationship could be a matter of historical
762
connection with the subject or with related matters, or of legal,
763
commercial, philosophical, ethical or political position regarding
766
The ``Invariant Sections'' are certain Secondary Sections whose titles
767
are designated, as being those of Invariant Sections, in the notice
768
that says that the Document is released under this License. If a
769
section does not fit the above definition of Secondary then it is not
770
allowed to be designated as Invariant. The Document may contain zero
771
Invariant Sections. If the Document does not identify any Invariant
772
Sections then there are none.
774
The ``Cover Texts'' are certain short passages of text that are listed,
775
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
776
the Document is released under this License. A Front-Cover Text may
777
be at most 5 words, and a Back-Cover Text may be at most 25 words.
779
A ``Transparent'' copy of the Document means a machine-readable copy,
780
represented in a format whose specification is available to the
781
general public, that is suitable for revising the document
782
straightforwardly with generic text editors or (for images composed of
783
pixels) generic paint programs or (for drawings) some widely available
784
drawing editor, and that is suitable for input to text formatters or
785
for automatic translation to a variety of formats suitable for input
786
to text formatters. A copy made in an otherwise Transparent file
787
format whose markup, or absence of markup, has been arranged to thwart
788
or discourage subsequent modification by readers is not Transparent.
789
An image format is not Transparent if used for any substantial amount
790
of text. A copy that is not ``Transparent'' is called ``Opaque''.
792
Examples of suitable formats for Transparent copies include plain
793
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
794
format, @acronym{SGML} or @acronym{XML} using a publicly available
795
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
796
PostScript or @acronym{PDF} designed for human modification. Examples
797
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
798
@acronym{JPG}. Opaque formats include proprietary formats that can be
799
read and edited only by proprietary word processors, @acronym{SGML} or
800
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
801
not generally available, and the machine-generated @acronym{HTML},
802
PostScript or @acronym{PDF} produced by some word processors for
803
output purposes only.
805
The ``Title Page'' means, for a printed book, the title page itself,
806
plus such following pages as are needed to hold, legibly, the material
807
this License requires to appear in the title page. For works in
808
formats which do not have any title page as such, ``Title Page'' means
809
the text near the most prominent appearance of the work's title,
810
preceding the beginning of the body of the text.
812
A section ``Entitled XYZ'' means a named subunit of the Document whose
813
title either is precisely XYZ or contains XYZ in parentheses following
814
text that translates XYZ in another language. (Here XYZ stands for a
815
specific section name mentioned below, such as ``Acknowledgements'',
816
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
817
of such a section when you modify the Document means that it remains a
818
section ``Entitled XYZ'' according to this definition.
820
The Document may include Warranty Disclaimers next to the notice which
821
states that this License applies to the Document. These Warranty
822
Disclaimers are considered to be included by reference in this
823
License, but only as regards disclaiming warranties: any other
824
implication that these Warranty Disclaimers may have is void and has
825
no effect on the meaning of this License.
830
You may copy and distribute the Document in any medium, either
831
commercially or noncommercially, provided that this License, the
832
copyright notices, and the license notice saying this License applies
833
to the Document are reproduced in all copies, and that you add no other
834
conditions whatsoever to those of this License. You may not use
835
technical measures to obstruct or control the reading or further
836
copying of the copies you make or distribute. However, you may accept
837
compensation in exchange for copies. If you distribute a large enough
838
number of copies you must also follow the conditions in section 3.
840
You may also lend copies, under the same conditions stated above, and
841
you may publicly display copies.
846
If you publish printed copies (or copies in media that commonly have
847
printed covers) of the Document, numbering more than 100, and the
848
Document's license notice requires Cover Texts, you must enclose the
849
copies in covers that carry, clearly and legibly, all these Cover
850
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
851
the back cover. Both covers must also clearly and legibly identify
852
you as the publisher of these copies. The front cover must present
853
the full title with all words of the title equally prominent and
854
visible. You may add other material on the covers in addition.
855
Copying with changes limited to the covers, as long as they preserve
856
the title of the Document and satisfy these conditions, can be treated
857
as verbatim copying in other respects.
859
If the required texts for either cover are too voluminous to fit
860
legibly, you should put the first ones listed (as many as fit
861
reasonably) on the actual cover, and continue the rest onto adjacent
864
If you publish or distribute Opaque copies of the Document numbering
865
more than 100, you must either include a machine-readable Transparent
866
copy along with each Opaque copy, or state in or with each Opaque copy
867
a computer-network location from which the general network-using
868
public has access to download using public-standard network protocols
869
a complete Transparent copy of the Document, free of added material.
870
If you use the latter option, you must take reasonably prudent steps,
871
when you begin distribution of Opaque copies in quantity, to ensure
872
that this Transparent copy will remain thus accessible at the stated
873
location until at least one year after the last time you distribute an
874
Opaque copy (directly or through your agents or retailers) of that
875
edition to the public.
877
It is requested, but not required, that you contact the authors of the
878
Document well before redistributing any large number of copies, to give
879
them a chance to provide you with an updated version of the Document.
884
You may copy and distribute a Modified Version of the Document under
885
the conditions of sections 2 and 3 above, provided that you release
886
the Modified Version under precisely this License, with the Modified
887
Version filling the role of the Document, thus licensing distribution
888
and modification of the Modified Version to whoever possesses a copy
889
of it. In addition, you must do these things in the Modified Version:
893
Use in the Title Page (and on the covers, if any) a title distinct
894
from that of the Document, and from those of previous versions
895
(which should, if there were any, be listed in the History section
896
of the Document). You may use the same title as a previous version
897
if the original publisher of that version gives permission.
900
List on the Title Page, as authors, one or more persons or entities
901
responsible for authorship of the modifications in the Modified
902
Version, together with at least five of the principal authors of the
903
Document (all of its principal authors, if it has fewer than five),
904
unless they release you from this requirement.
907
State on the Title page the name of the publisher of the
908
Modified Version, as the publisher.
911
Preserve all the copyright notices of the Document.
914
Add an appropriate copyright notice for your modifications
915
adjacent to the other copyright notices.
918
Include, immediately after the copyright notices, a license notice
919
giving the public permission to use the Modified Version under the
920
terms of this License, in the form shown in the Addendum below.
923
Preserve in that license notice the full lists of Invariant Sections
924
and required Cover Texts given in the Document's license notice.
927
Include an unaltered copy of this License.
930
Preserve the section Entitled ``History'', Preserve its Title, and add
931
to it an item stating at least the title, year, new authors, and
932
publisher of the Modified Version as given on the Title Page. If
933
there is no section Entitled ``History'' in the Document, create one
934
stating the title, year, authors, and publisher of the Document as
935
given on its Title Page, then add an item describing the Modified
936
Version as stated in the previous sentence.
939
Preserve the network location, if any, given in the Document for
940
public access to a Transparent copy of the Document, and likewise
941
the network locations given in the Document for previous versions
942
it was based on. These may be placed in the ``History'' section.
943
You may omit a network location for a work that was published at
944
least four years before the Document itself, or if the original
945
publisher of the version it refers to gives permission.
948
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
949
the Title of the section, and preserve in the section all the
950
substance and tone of each of the contributor acknowledgements and/or
951
dedications given therein.
954
Preserve all the Invariant Sections of the Document,
955
unaltered in their text and in their titles. Section numbers
956
or the equivalent are not considered part of the section titles.
959
Delete any section Entitled ``Endorsements''. Such a section
960
may not be included in the Modified Version.
963
Do not retitle any existing section to be Entitled ``Endorsements'' or
964
to conflict in title with any Invariant Section.
967
Preserve any Warranty Disclaimers.
970
If the Modified Version includes new front-matter sections or
971
appendices that qualify as Secondary Sections and contain no material
972
copied from the Document, you may at your option designate some or all
973
of these sections as invariant. To do this, add their titles to the
974
list of Invariant Sections in the Modified Version's license notice.
975
These titles must be distinct from any other section titles.
977
You may add a section Entitled ``Endorsements'', provided it contains
978
nothing but endorsements of your Modified Version by various
979
parties---for example, statements of peer review or that the text has
980
been approved by an organization as the authoritative definition of a
983
You may add a passage of up to five words as a Front-Cover Text, and a
984
passage of up to 25 words as a Back-Cover Text, to the end of the list
985
of Cover Texts in the Modified Version. Only one passage of
986
Front-Cover Text and one of Back-Cover Text may be added by (or
987
through arrangements made by) any one entity. If the Document already
988
includes a cover text for the same cover, previously added by you or
989
by arrangement made by the same entity you are acting on behalf of,
990
you may not add another; but you may replace the old one, on explicit
991
permission from the previous publisher that added the old one.
993
The author(s) and publisher(s) of the Document do not by this License
994
give permission to use their names for publicity for or to assert or
995
imply endorsement of any Modified Version.
1000
You may combine the Document with other documents released under this
1001
License, under the terms defined in section 4 above for modified
1002
versions, provided that you include in the combination all of the
1003
Invariant Sections of all of the original documents, unmodified, and
1004
list them all as Invariant Sections of your combined work in its
1005
license notice, and that you preserve all their Warranty Disclaimers.
1007
The combined work need only contain one copy of this License, and
1008
multiple identical Invariant Sections may be replaced with a single
1009
copy. If there are multiple Invariant Sections with the same name but
1010
different contents, make the title of each such section unique by
1011
adding at the end of it, in parentheses, the name of the original
1012
author or publisher of that section if known, or else a unique number.
1013
Make the same adjustment to the section titles in the list of
1014
Invariant Sections in the license notice of the combined work.
1016
In the combination, you must combine any sections Entitled ``History''
1017
in the various original documents, forming one section Entitled
1018
``History''; likewise combine any sections Entitled ``Acknowledgements'',
1019
and any sections Entitled ``Dedications''. You must delete all
1020
sections Entitled ``Endorsements.''
1023
COLLECTIONS OF DOCUMENTS
1025
You may make a collection consisting of the Document and other documents
1026
released under this License, and replace the individual copies of this
1027
License in the various documents with a single copy that is included in
1028
the collection, provided that you follow the rules of this License for
1029
verbatim copying of each of the documents in all other respects.
1031
You may extract a single document from such a collection, and distribute
1032
it individually under this License, provided you insert a copy of this
1033
License into the extracted document, and follow this License in all
1034
other respects regarding verbatim copying of that document.
1037
AGGREGATION WITH INDEPENDENT WORKS
1039
A compilation of the Document or its derivatives with other separate
1040
and independent documents or works, in or on a volume of a storage or
1041
distribution medium, is called an ``aggregate'' if the copyright
1042
resulting from the compilation is not used to limit the legal rights
1043
of the compilation's users beyond what the individual works permit.
1044
When the Document is included an aggregate, this License does not
1045
apply to the other works in the aggregate which are not themselves
1046
derivative works of the Document.
1048
If the Cover Text requirement of section 3 is applicable to these
1049
copies of the Document, then if the Document is less than one half of
1050
the entire aggregate, the Document's Cover Texts may be placed on
1051
covers that bracket the Document within the aggregate, or the
1052
electronic equivalent of covers if the Document is in electronic form.
1053
Otherwise they must appear on printed covers that bracket the whole
1059
Translation is considered a kind of modification, so you may
1060
distribute translations of the Document under the terms of section 4.
1061
Replacing Invariant Sections with translations requires special
1062
permission from their copyright holders, but you may include
1063
translations of some or all Invariant Sections in addition to the
1064
original versions of these Invariant Sections. You may include a
1065
translation of this License, and all the license notices in the
1066
Document, and any Warrany Disclaimers, provided that you also include
1067
the original English version of this License and the original versions
1068
of those notices and disclaimers. In case of a disagreement between
1069
the translation and the original version of this License or a notice
1070
or disclaimer, the original version will prevail.
1072
If a section in the Document is Entitled ``Acknowledgements'',
1073
``Dedications'', or ``History'', the requirement (section 4) to Preserve
1074
its Title (section 1) will typically require changing the actual
1080
You may not copy, modify, sublicense, or distribute the Document except
1081
as expressly provided for under this License. Any other attempt to
1082
copy, modify, sublicense or distribute the Document is void, and will
1083
automatically terminate your rights under this License. However,
1084
parties who have received copies, or rights, from you under this
1085
License will not have their licenses terminated so long as such
1086
parties remain in full compliance.
1089
FUTURE REVISIONS OF THIS LICENSE
1091
The Free Software Foundation may publish new, revised versions
1092
of the GNU Free Documentation License from time to time. Such new
1093
versions will be similar in spirit to the present version, but may
1094
differ in detail to address new problems or concerns. See
1095
@uref{http://www.gnu.org/copyleft/}.
1097
Each version of the License is given a distinguishing version number.
1098
If the Document specifies that a particular numbered version of this
1099
License ``or any later version'' applies to it, you have the option of
1100
following the terms and conditions either of that specified version or
1101
of any later version that has been published (not as a draft) by the
1102
Free Software Foundation. If the Document does not specify a version
1103
number of this License, you may choose any version ever published (not
1104
as a draft) by the Free Software Foundation.
1108
@appendixsec ADDENDUM: How to use this License for your documents
1110
To use this License in a document you have written, include a copy of
1111
the License in the document and put the following copyright and
1112
license notices just after the title page:
1116
Copyright (C) @var{year} @var{your name}.
1117
Permission is granted to copy, distribute and/or modify this document
1118
under the terms of the GNU Free Documentation License, Version 1.2
1119
or any later version published by the Free Software Foundation;
1120
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
1121
A copy of the license is included in the section entitled ``GNU
1122
Free Documentation License''.
1126
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
1127
replace the ``with...Texts.'' line with this:
1131
with the Invariant Sections being @var{list their titles}, with
1132
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
1137
If you have Invariant Sections without Cover Texts, or some other
1138
combination of the three, merge those two alternatives to suit the
1141
If your document contains nontrivial examples of program code, we
1142
recommend releasing these examples in parallel under your choice of
1143
free software license, such as the GNU General Public License,
1144
to permit their use in free software.
added
removed
doc/ffi/ffi.texinfo
