| 1 | \input texinfo.tex |
| 2 | @setfilename bfd.info |
| 3 | @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | @c |
| 6 | @tex |
| 7 | % NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE |
| 8 | \global\long\def\example{% |
| 9 | \begingroup |
| 10 | \let\aboveenvbreak=\par |
| 11 | \let\afterenvbreak=\par |
| 12 | \parskip=0pt |
| 13 | \lisp} |
| 14 | \global\long\def\Eexample{% |
| 15 | \Elisp |
| 16 | \endgroup |
| 17 | \vskip -\parskip% to cancel out effect of following \par |
| 18 | } |
| 19 | @end tex |
| 20 | @synindex fn cp |
| 21 | |
| 22 | @ifinfo |
| 23 | @format |
| 24 | START-INFO-DIR-ENTRY |
| 25 | * Bfd: (bfd). The Binary File Descriptor library. |
| 26 | END-INFO-DIR-ENTRY |
| 27 | @end format |
| 28 | @end ifinfo |
| 29 | |
| 30 | @ifinfo |
| 31 | This file documents the BFD library. |
| 32 | |
| 33 | Copyright (C) 1991, 2000, 2001 Free Software Foundation, Inc. |
| 34 | |
| 35 | Permission is granted to copy, distribute and/or modify this document |
| 36 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 37 | or any later version published by the Free Software Foundation; |
| 38 | with no Invariant Sections, with no Front-Cover Texts, and with no |
| 39 | Back-Cover Texts. A copy of the license is included in the |
| 40 | section entitled "GNU Free Documentation License". |
| 41 | |
| 42 | @ignore |
| 43 | Permission is granted to process this file through Tex and print the |
| 44 | results, provided the printed document carries copying permission |
| 45 | notice identical to this one except for the removal of this paragraph |
| 46 | (this paragraph not being relevant to the printed manual). |
| 47 | |
| 48 | @end ignore |
| 49 | @end ifinfo |
| 50 | @iftex |
| 51 | @c@finalout |
| 52 | @setchapternewpage on |
| 53 | @c@setchapternewpage odd |
| 54 | @settitle LIB BFD, the Binary File Descriptor Library |
| 55 | @titlepage |
| 56 | @title{libbfd} |
| 57 | @subtitle{The Binary File Descriptor Library} |
| 58 | @sp 1 |
| 59 | @subtitle First Edition---BFD version < 3.0 % Since no product is stable berfore version 3.0 :-) |
| 60 | @subtitle Original Document Created: April 1991 |
| 61 | @author {Steve Chamberlain} |
| 62 | @author {Cygnus Support} |
| 63 | @page |
| 64 | |
| 65 | @tex |
| 66 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 67 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 68 | {\parskip=0pt |
| 69 | \hfill Free Software Foundation\par |
| 70 | \hfill sac\@www.gnu.org\par |
| 71 | \hfill {\it BFD}, \manvers\par |
| 72 | \hfill \TeX{}info \texinfoversion\par |
| 73 | } |
| 74 | \global\parindent=0pt % Steve likes it this way |
| 75 | @end tex |
| 76 | |
| 77 | @vskip 0pt plus 1filll |
| 78 | Copyright @copyright{} 1991, 2001 Free Software Foundation, Inc. |
| 79 | |
| 80 | Permission is granted to copy, distribute and/or modify this document |
| 81 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 82 | or any later version published by the Free Software Foundation; |
| 83 | with no Invariant Sections, with no Front-Cover Texts, and with no |
| 84 | Back-Cover Texts. A copy of the license is included in the |
| 85 | section entitled "GNU Free Documentation License". |
| 86 | |
| 87 | @end titlepage |
| 88 | @end iftex |
| 89 | |
| 90 | @node Top, Overview, (dir), (dir) |
| 91 | @ifinfo |
| 92 | This file documents the binary file descriptor library libbfd. |
| 93 | @end ifinfo |
| 94 | |
| 95 | @menu |
| 96 | * Overview:: Overview of BFD |
| 97 | * BFD front end:: BFD front end |
| 98 | * BFD back ends:: BFD back ends |
| 99 | * GNU Free Documentation License:: GNU Free Documentation License |
| 100 | * Index:: Index |
| 101 | @end menu |
| 102 | |
| 103 | @node Overview, BFD front end, Top, Top |
| 104 | @chapter Introduction |
| 105 | @cindex BFD |
| 106 | @cindex what is it? |
| 107 | BFD is a package which allows applications to use the |
| 108 | same routines to operate on object files whatever the object file |
| 109 | format. A new object file format can be supported simply by |
| 110 | creating a new BFD back end and adding it to the library. |
| 111 | |
| 112 | BFD is split into two parts: the front end, and the back ends (one for |
| 113 | each object file format). |
| 114 | @itemize @bullet |
| 115 | @item The front end of BFD provides the interface to the user. It manages |
| 116 | memory and various canonical data structures. The front end also |
| 117 | decides which back end to use and when to call back end routines. |
| 118 | @item The back ends provide BFD its view of the real world. Each back |
| 119 | end provides a set of calls which the BFD front end can use to maintain |
| 120 | its canonical form. The back ends also may keep around information for |
| 121 | their own use, for greater efficiency. |
| 122 | @end itemize |
| 123 | @menu |
| 124 | * History:: History |
| 125 | * How It Works:: How It Works |
| 126 | * What BFD Version 2 Can Do:: What BFD Version 2 Can Do |
| 127 | @end menu |
| 128 | |
| 129 | @node History, How It Works, Overview, Overview |
| 130 | @section History |
| 131 | |
| 132 | One spur behind BFD was the desire, on the part of the GNU 960 team at |
| 133 | Intel Oregon, for interoperability of applications on their COFF and |
| 134 | b.out file formats. Cygnus was providing GNU support for the team, and |
| 135 | was contracted to provide the required functionality. |
| 136 | |
| 137 | The name came from a conversation David Wallace was having with Richard |
| 138 | Stallman about the library: RMS said that it would be quite hard---David |
| 139 | said ``BFD''. Stallman was right, but the name stuck. |
| 140 | |
| 141 | At the same time, Ready Systems wanted much the same thing, but for |
| 142 | different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k |
| 143 | coff. |
| 144 | |
| 145 | BFD was first implemented by members of Cygnus Support; Steve |
| 146 | Chamberlain (@code{sac@@cygnus.com}), John Gilmore |
| 147 | (@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) |
| 148 | and David Henkel-Wallace (@code{gumby@@cygnus.com}). |
| 149 | |
| 150 | |
| 151 | |
| 152 | @node How It Works, What BFD Version 2 Can Do, History, Overview |
| 153 | @section How To Use BFD |
| 154 | |
| 155 | To use the library, include @file{bfd.h} and link with @file{libbfd.a}. |
| 156 | |
| 157 | BFD provides a common interface to the parts of an object file |
| 158 | for a calling application. |
| 159 | |
| 160 | When an application sucessfully opens a target file (object, archive, or |
| 161 | whatever), a pointer to an internal structure is returned. This pointer |
| 162 | points to a structure called @code{bfd}, described in |
| 163 | @file{bfd.h}. Our convention is to call this pointer a BFD, and |
| 164 | instances of it within code @code{abfd}. All operations on |
| 165 | the target object file are applied as methods to the BFD. The mapping is |
| 166 | defined within @code{bfd.h} in a set of macros, all beginning |
| 167 | with @samp{bfd_} to reduce namespace pollution. |
| 168 | |
| 169 | For example, this sequence does what you would probably expect: |
| 170 | return the number of sections in an object file attached to a BFD |
| 171 | @code{abfd}. |
| 172 | |
| 173 | @lisp |
| 174 | @c @cartouche |
| 175 | #include "bfd.h" |
| 176 | |
| 177 | unsigned int number_of_sections(abfd) |
| 178 | bfd *abfd; |
| 179 | @{ |
| 180 | return bfd_count_sections(abfd); |
| 181 | @} |
| 182 | @c @end cartouche |
| 183 | @end lisp |
| 184 | |
| 185 | The abstraction used within BFD is that an object file has: |
| 186 | |
| 187 | @itemize @bullet |
| 188 | @item |
| 189 | a header, |
| 190 | @item |
| 191 | a number of sections containing raw data (@pxref{Sections}), |
| 192 | @item |
| 193 | a set of relocations (@pxref{Relocations}), and |
| 194 | @item |
| 195 | some symbol information (@pxref{Symbols}). |
| 196 | @end itemize |
| 197 | @noindent |
| 198 | Also, BFDs opened for archives have the additional attribute of an index |
| 199 | and contain subordinate BFDs. This approach is fine for a.out and coff, |
| 200 | but loses efficiency when applied to formats such as S-records and |
| 201 | IEEE-695. |
| 202 | |
| 203 | @node What BFD Version 2 Can Do, , How It Works, Overview |
| 204 | @section What BFD Version 2 Can Do |
| 205 | @include bfdsumm.texi |
| 206 | |
| 207 | @node BFD front end, BFD back ends, Overview, Top |
| 208 | @chapter BFD front end |
| 209 | @include bfdt.texi |
| 210 | |
| 211 | @menu |
| 212 | * Memory Usage:: |
| 213 | * Initialization:: |
| 214 | * Sections:: |
| 215 | * Symbols:: |
| 216 | * Archives:: |
| 217 | * Formats:: |
| 218 | * Relocations:: |
| 219 | * Core Files:: |
| 220 | * Targets:: |
| 221 | * Architectures:: |
| 222 | * Opening and Closing:: |
| 223 | * Internal:: |
| 224 | * File Caching:: |
| 225 | * Linker Functions:: |
| 226 | * Hash Tables:: |
| 227 | @end menu |
| 228 | |
| 229 | @node Memory Usage, Initialization, BFD front end, BFD front end |
| 230 | @section Memory usage |
| 231 | BFD keeps all of its internal structures in obstacks. There is one obstack |
| 232 | per open BFD file, into which the current state is stored. When a BFD is |
| 233 | closed, the obstack is deleted, and so everything which has been |
| 234 | allocated by BFD for the closing file is thrown away. |
| 235 | |
| 236 | BFD does not free anything created by an application, but pointers into |
| 237 | @code{bfd} structures become invalid on a @code{bfd_close}; for example, |
| 238 | after a @code{bfd_close} the vector passed to |
| 239 | @code{bfd_canonicalize_symtab} is still around, since it has been |
| 240 | allocated by the application, but the data that it pointed to are |
| 241 | lost. |
| 242 | |
| 243 | The general rule is to not close a BFD until all operations dependent |
| 244 | upon data from the BFD have been completed, or all the data from within |
| 245 | the file has been copied. To help with the management of memory, there |
| 246 | is a function (@code{bfd_alloc_size}) which returns the number of bytes |
| 247 | in obstacks associated with the supplied BFD. This could be used to |
| 248 | select the greediest open BFD, close it to reclaim the memory, perform |
| 249 | some operation and reopen the BFD again, to get a fresh copy of the data |
| 250 | structures. |
| 251 | |
| 252 | @node Initialization, Sections, Memory Usage, BFD front end |
| 253 | @include init.texi |
| 254 | |
| 255 | @node Sections, Symbols, Initialization, BFD front end |
| 256 | @include section.texi |
| 257 | |
| 258 | @node Symbols, Archives, Sections, BFD front end |
| 259 | @include syms.texi |
| 260 | |
| 261 | @node Archives, Formats, Symbols, BFD front end |
| 262 | @include archive.texi |
| 263 | |
| 264 | @node Formats, Relocations, Archives, BFD front end |
| 265 | @include format.texi |
| 266 | |
| 267 | @node Relocations, Core Files, Formats, BFD front end |
| 268 | @include reloc.texi |
| 269 | |
| 270 | @node Core Files, Targets, Relocations, BFD front end |
| 271 | @include core.texi |
| 272 | |
| 273 | @node Targets, Architectures, Core Files, BFD front end |
| 274 | @include targets.texi |
| 275 | |
| 276 | @node Architectures, Opening and Closing, Targets, BFD front end |
| 277 | @include archures.texi |
| 278 | |
| 279 | @node Opening and Closing, Internal, Architectures, BFD front end |
| 280 | @include opncls.texi |
| 281 | |
| 282 | @node Internal, File Caching, Opening and Closing, BFD front end |
| 283 | @include libbfd.texi |
| 284 | |
| 285 | @node File Caching, Linker Functions, Internal, BFD front end |
| 286 | @include cache.texi |
| 287 | |
| 288 | @node Linker Functions, Hash Tables, File Caching, BFD front end |
| 289 | @include linker.texi |
| 290 | |
| 291 | @node Hash Tables, , Linker Functions, BFD front end |
| 292 | @include hash.texi |
| 293 | |
| 294 | @node BFD back ends, GNU Free Documentation License, BFD front end, Top |
| 295 | @chapter BFD back ends |
| 296 | @menu |
| 297 | * What to Put Where:: |
| 298 | * aout :: a.out backends |
| 299 | * coff :: coff backends |
| 300 | * elf :: elf backends |
| 301 | * mmo :: mmo backend |
| 302 | @ignore |
| 303 | * oasys :: oasys backends |
| 304 | * ieee :: ieee backend |
| 305 | * srecord :: s-record backend |
| 306 | @end ignore |
| 307 | @end menu |
| 308 | @node What to Put Where, aout, BFD back ends, BFD back ends |
| 309 | All of BFD lives in one directory. |
| 310 | |
| 311 | @node aout, coff, What to Put Where, BFD back ends |
| 312 | @include aoutx.texi |
| 313 | |
| 314 | @node coff, elf, aout, BFD back ends |
| 315 | @include coffcode.texi |
| 316 | |
| 317 | @node elf, mmo, coff, BFD back ends |
| 318 | @include elf.texi |
| 319 | @c Leave this out until the file has some actual contents... |
| 320 | @c @include elfcode.texi |
| 321 | |
| 322 | @node mmo, , elf, BFD back ends |
| 323 | @include mmo.texi |
| 324 | |
| 325 | @node GNU Free Documentation License, Index, BFD back ends, Top |
| 326 | @chapter GNU Free Documentation License |
| 327 | @cindex GNU Free Documentation License |
| 328 | |
| 329 | GNU Free Documentation License |
| 330 | |
| 331 | Version 1.1, March 2000 |
| 332 | |
| 333 | Copyright (C) 2000 Free Software Foundation, Inc. |
| 334 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 335 | |
| 336 | Everyone is permitted to copy and distribute verbatim copies |
| 337 | of this license document, but changing it is not allowed. |
| 338 | |
| 339 | |
| 340 | 0. PREAMBLE |
| 341 | |
| 342 | The purpose of this License is to make a manual, textbook, or other |
| 343 | written document "free" in the sense of freedom: to assure everyone |
| 344 | the effective freedom to copy and redistribute it, with or without |
| 345 | modifying it, either commercially or noncommercially. Secondarily, |
| 346 | this License preserves for the author and publisher a way to get |
| 347 | credit for their work, while not being considered responsible for |
| 348 | modifications made by others. |
| 349 | |
| 350 | This License is a kind of "copyleft", which means that derivative |
| 351 | works of the document must themselves be free in the same sense. It |
| 352 | complements the GNU General Public License, which is a copyleft |
| 353 | license designed for free software. |
| 354 | |
| 355 | We have designed this License in order to use it for manuals for free |
| 356 | software, because free software needs free documentation: a free |
| 357 | program should come with manuals providing the same freedoms that the |
| 358 | software does. But this License is not limited to software manuals; |
| 359 | it can be used for any textual work, regardless of subject matter or |
| 360 | whether it is published as a printed book. We recommend this License |
| 361 | principally for works whose purpose is instruction or reference. |
| 362 | |
| 363 | |
| 364 | 1. APPLICABILITY AND DEFINITIONS |
| 365 | |
| 366 | This License applies to any manual or other work that contains a |
| 367 | notice placed by the copyright holder saying it can be distributed |
| 368 | under the terms of this License. The "Document", below, refers to any |
| 369 | such manual or work. Any member of the public is a licensee, and is |
| 370 | addressed as "you". |
| 371 | |
| 372 | A "Modified Version" of the Document means any work containing the |
| 373 | Document or a portion of it, either copied verbatim, or with |
| 374 | modifications and/or translated into another language. |
| 375 | |
| 376 | A "Secondary Section" is a named appendix or a front-matter section of |
| 377 | the Document that deals exclusively with the relationship of the |
| 378 | publishers or authors of the Document to the Document's overall subject |
| 379 | (or to related matters) and contains nothing that could fall directly |
| 380 | within that overall subject. (For example, if the Document is in part a |
| 381 | textbook of mathematics, a Secondary Section may not explain any |
| 382 | mathematics.) The relationship could be a matter of historical |
| 383 | connection with the subject or with related matters, or of legal, |
| 384 | commercial, philosophical, ethical or political position regarding |
| 385 | them. |
| 386 | |
| 387 | The "Invariant Sections" are certain Secondary Sections whose titles |
| 388 | are designated, as being those of Invariant Sections, in the notice |
| 389 | that says that the Document is released under this License. |
| 390 | |
| 391 | The "Cover Texts" are certain short passages of text that are listed, |
| 392 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| 393 | the Document is released under this License. |
| 394 | |
| 395 | A "Transparent" copy of the Document means a machine-readable copy, |
| 396 | represented in a format whose specification is available to the |
| 397 | general public, whose contents can be viewed and edited directly and |
| 398 | straightforwardly with generic text editors or (for images composed of |
| 399 | pixels) generic paint programs or (for drawings) some widely available |
| 400 | drawing editor, and that is suitable for input to text formatters or |
| 401 | for automatic translation to a variety of formats suitable for input |
| 402 | to text formatters. A copy made in an otherwise Transparent file |
| 403 | format whose markup has been designed to thwart or discourage |
| 404 | subsequent modification by readers is not Transparent. A copy that is |
| 405 | not "Transparent" is called "Opaque". |
| 406 | |
| 407 | Examples of suitable formats for Transparent copies include plain |
| 408 | ASCII without markup, Texinfo input format, LaTeX input format, SGML |
| 409 | or XML using a publicly available DTD, and standard-conforming simple |
| 410 | HTML designed for human modification. Opaque formats include |
| 411 | PostScript, PDF, proprietary formats that can be read and edited only |
| 412 | by proprietary word processors, SGML or XML for which the DTD and/or |
| 413 | processing tools are not generally available, and the |
| 414 | machine-generated HTML produced by some word processors for output |
| 415 | purposes only. |
| 416 | |
| 417 | The "Title Page" means, for a printed book, the title page itself, |
| 418 | plus such following pages as are needed to hold, legibly, the material |
| 419 | this License requires to appear in the title page. For works in |
| 420 | formats which do not have any title page as such, "Title Page" means |
| 421 | the text near the most prominent appearance of the work's title, |
| 422 | preceding the beginning of the body of the text. |
| 423 | |
| 424 | |
| 425 | 2. VERBATIM COPYING |
| 426 | |
| 427 | You may copy and distribute the Document in any medium, either |
| 428 | commercially or noncommercially, provided that this License, the |
| 429 | copyright notices, and the license notice saying this License applies |
| 430 | to the Document are reproduced in all copies, and that you add no other |
| 431 | conditions whatsoever to those of this License. You may not use |
| 432 | technical measures to obstruct or control the reading or further |
| 433 | copying of the copies you make or distribute. However, you may accept |
| 434 | compensation in exchange for copies. If you distribute a large enough |
| 435 | number of copies you must also follow the conditions in section 3. |
| 436 | |
| 437 | You may also lend copies, under the same conditions stated above, and |
| 438 | you may publicly display copies. |
| 439 | |
| 440 | |
| 441 | 3. COPYING IN QUANTITY |
| 442 | |
| 443 | If you publish printed copies of the Document numbering more than 100, |
| 444 | and the Document's license notice requires Cover Texts, you must enclose |
| 445 | the copies in covers that carry, clearly and legibly, all these Cover |
| 446 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| 447 | the back cover. Both covers must also clearly and legibly identify |
| 448 | you as the publisher of these copies. The front cover must present |
| 449 | the full title with all words of the title equally prominent and |
| 450 | visible. You may add other material on the covers in addition. |
| 451 | Copying with changes limited to the covers, as long as they preserve |
| 452 | the title of the Document and satisfy these conditions, can be treated |
| 453 | as verbatim copying in other respects. |
| 454 | |
| 455 | If the required texts for either cover are too voluminous to fit |
| 456 | legibly, you should put the first ones listed (as many as fit |
| 457 | reasonably) on the actual cover, and continue the rest onto adjacent |
| 458 | pages. |
| 459 | |
| 460 | If you publish or distribute Opaque copies of the Document numbering |
| 461 | more than 100, you must either include a machine-readable Transparent |
| 462 | copy along with each Opaque copy, or state in or with each Opaque copy |
| 463 | a publicly-accessible computer-network location containing a complete |
| 464 | Transparent copy of the Document, free of added material, which the |
| 465 | general network-using public has access to download anonymously at no |
| 466 | charge using public-standard network protocols. If you use the latter |
| 467 | option, you must take reasonably prudent steps, when you begin |
| 468 | distribution of Opaque copies in quantity, to ensure that this |
| 469 | Transparent copy will remain thus accessible at the stated location |
| 470 | until at least one year after the last time you distribute an Opaque |
| 471 | copy (directly or through your agents or retailers) of that edition to |
| 472 | the public. |
| 473 | |
| 474 | It is requested, but not required, that you contact the authors of the |
| 475 | Document well before redistributing any large number of copies, to give |
| 476 | them a chance to provide you with an updated version of the Document. |
| 477 | |
| 478 | |
| 479 | 4. MODIFICATIONS |
| 480 | |
| 481 | You may copy and distribute a Modified Version of the Document under |
| 482 | the conditions of sections 2 and 3 above, provided that you release |
| 483 | the Modified Version under precisely this License, with the Modified |
| 484 | Version filling the role of the Document, thus licensing distribution |
| 485 | and modification of the Modified Version to whoever possesses a copy |
| 486 | of it. In addition, you must do these things in the Modified Version: |
| 487 | |
| 488 | A. Use in the Title Page (and on the covers, if any) a title distinct |
| 489 | from that of the Document, and from those of previous versions |
| 490 | (which should, if there were any, be listed in the History section |
| 491 | of the Document). You may use the same title as a previous version |
| 492 | if the original publisher of that version gives permission. |
| 493 | B. List on the Title Page, as authors, one or more persons or entities |
| 494 | responsible for authorship of the modifications in the Modified |
| 495 | Version, together with at least five of the principal authors of the |
| 496 | Document (all of its principal authors, if it has less than five). |
| 497 | C. State on the Title page the name of the publisher of the |
| 498 | Modified Version, as the publisher. |
| 499 | D. Preserve all the copyright notices of the Document. |
| 500 | E. Add an appropriate copyright notice for your modifications |
| 501 | adjacent to the other copyright notices. |
| 502 | F. Include, immediately after the copyright notices, a license notice |
| 503 | giving the public permission to use the Modified Version under the |
| 504 | terms of this License, in the form shown in the Addendum below. |
| 505 | G. Preserve in that license notice the full lists of Invariant Sections |
| 506 | and required Cover Texts given in the Document's license notice. |
| 507 | H. Include an unaltered copy of this License. |
| 508 | I. Preserve the section entitled "History", and its title, and add to |
| 509 | it an item stating at least the title, year, new authors, and |
| 510 | publisher of the Modified Version as given on the Title Page. If |
| 511 | there is no section entitled "History" in the Document, create one |
| 512 | stating the title, year, authors, and publisher of the Document as |
| 513 | given on its Title Page, then add an item describing the Modified |
| 514 | Version as stated in the previous sentence. |
| 515 | J. Preserve the network location, if any, given in the Document for |
| 516 | public access to a Transparent copy of the Document, and likewise |
| 517 | the network locations given in the Document for previous versions |
| 518 | it was based on. These may be placed in the "History" section. |
| 519 | You may omit a network location for a work that was published at |
| 520 | least four years before the Document itself, or if the original |
| 521 | publisher of the version it refers to gives permission. |
| 522 | K. In any section entitled "Acknowledgements" or "Dedications", |
| 523 | preserve the section's title, and preserve in the section all the |
| 524 | substance and tone of each of the contributor acknowledgements |
| 525 | and/or dedications given therein. |
| 526 | L. Preserve all the Invariant Sections of the Document, |
| 527 | unaltered in their text and in their titles. Section numbers |
| 528 | or the equivalent are not considered part of the section titles. |
| 529 | M. Delete any section entitled "Endorsements". Such a section |
| 530 | may not be included in the Modified Version. |
| 531 | N. Do not retitle any existing section as "Endorsements" |
| 532 | or to conflict in title with any Invariant Section. |
| 533 | |
| 534 | If the Modified Version includes new front-matter sections or |
| 535 | appendices that qualify as Secondary Sections and contain no material |
| 536 | copied from the Document, you may at your option designate some or all |
| 537 | of these sections as invariant. To do this, add their titles to the |
| 538 | list of Invariant Sections in the Modified Version's license notice. |
| 539 | These titles must be distinct from any other section titles. |
| 540 | |
| 541 | You may add a section entitled "Endorsements", provided it contains |
| 542 | nothing but endorsements of your Modified Version by various |
| 543 | parties--for example, statements of peer review or that the text has |
| 544 | been approved by an organization as the authoritative definition of a |
| 545 | standard. |
| 546 | |
| 547 | You may add a passage of up to five words as a Front-Cover Text, and a |
| 548 | passage of up to 25 words as a Back-Cover Text, to the end of the list |
| 549 | of Cover Texts in the Modified Version. Only one passage of |
| 550 | Front-Cover Text and one of Back-Cover Text may be added by (or |
| 551 | through arrangements made by) any one entity. If the Document already |
| 552 | includes a cover text for the same cover, previously added by you or |
| 553 | by arrangement made by the same entity you are acting on behalf of, |
| 554 | you may not add another; but you may replace the old one, on explicit |
| 555 | permission from the previous publisher that added the old one. |
| 556 | |
| 557 | The author(s) and publisher(s) of the Document do not by this License |
| 558 | give permission to use their names for publicity for or to assert or |
| 559 | imply endorsement of any Modified Version. |
| 560 | |
| 561 | |
| 562 | 5. COMBINING DOCUMENTS |
| 563 | |
| 564 | You may combine the Document with other documents released under this |
| 565 | License, under the terms defined in section 4 above for modified |
| 566 | versions, provided that you include in the combination all of the |
| 567 | Invariant Sections of all of the original documents, unmodified, and |
| 568 | list them all as Invariant Sections of your combined work in its |
| 569 | license notice. |
| 570 | |
| 571 | The combined work need only contain one copy of this License, and |
| 572 | multiple identical Invariant Sections may be replaced with a single |
| 573 | copy. If there are multiple Invariant Sections with the same name but |
| 574 | different contents, make the title of each such section unique by |
| 575 | adding at the end of it, in parentheses, the name of the original |
| 576 | author or publisher of that section if known, or else a unique number. |
| 577 | Make the same adjustment to the section titles in the list of |
| 578 | Invariant Sections in the license notice of the combined work. |
| 579 | |
| 580 | In the combination, you must combine any sections entitled "History" |
| 581 | in the various original documents, forming one section entitled |
| 582 | "History"; likewise combine any sections entitled "Acknowledgements", |
| 583 | and any sections entitled "Dedications". You must delete all sections |
| 584 | entitled "Endorsements." |
| 585 | |
| 586 | |
| 587 | 6. COLLECTIONS OF DOCUMENTS |
| 588 | |
| 589 | You may make a collection consisting of the Document and other documents |
| 590 | released under this License, and replace the individual copies of this |
| 591 | License in the various documents with a single copy that is included in |
| 592 | the collection, provided that you follow the rules of this License for |
| 593 | verbatim copying of each of the documents in all other respects. |
| 594 | |
| 595 | You may extract a single document from such a collection, and distribute |
| 596 | it individually under this License, provided you insert a copy of this |
| 597 | License into the extracted document, and follow this License in all |
| 598 | other respects regarding verbatim copying of that document. |
| 599 | |
| 600 | |
| 601 | 7. AGGREGATION WITH INDEPENDENT WORKS |
| 602 | |
| 603 | A compilation of the Document or its derivatives with other separate |
| 604 | and independent documents or works, in or on a volume of a storage or |
| 605 | distribution medium, does not as a whole count as a Modified Version |
| 606 | of the Document, provided no compilation copyright is claimed for the |
| 607 | compilation. Such a compilation is called an "aggregate", and this |
| 608 | License does not apply to the other self-contained works thus compiled |
| 609 | with the Document, on account of their being thus compiled, if they |
| 610 | are not themselves derivative works of the Document. |
| 611 | |
| 612 | If the Cover Text requirement of section 3 is applicable to these |
| 613 | copies of the Document, then if the Document is less than one quarter |
| 614 | of the entire aggregate, the Document's Cover Texts may be placed on |
| 615 | covers that surround only the Document within the aggregate. |
| 616 | Otherwise they must appear on covers around the whole aggregate. |
| 617 | |
| 618 | |
| 619 | 8. TRANSLATION |
| 620 | |
| 621 | Translation is considered a kind of modification, so you may |
| 622 | distribute translations of the Document under the terms of section 4. |
| 623 | Replacing Invariant Sections with translations requires special |
| 624 | permission from their copyright holders, but you may include |
| 625 | translations of some or all Invariant Sections in addition to the |
| 626 | original versions of these Invariant Sections. You may include a |
| 627 | translation of this License provided that you also include the |
| 628 | original English version of this License. In case of a disagreement |
| 629 | between the translation and the original English version of this |
| 630 | License, the original English version will prevail. |
| 631 | |
| 632 | |
| 633 | 9. TERMINATION |
| 634 | |
| 635 | You may not copy, modify, sublicense, or distribute the Document except |
| 636 | as expressly provided for under this License. Any other attempt to |
| 637 | copy, modify, sublicense or distribute the Document is void, and will |
| 638 | automatically terminate your rights under this License. However, |
| 639 | parties who have received copies, or rights, from you under this |
| 640 | License will not have their licenses terminated so long as such |
| 641 | parties remain in full compliance. |
| 642 | |
| 643 | |
| 644 | 10. FUTURE REVISIONS OF THIS LICENSE |
| 645 | |
| 646 | The Free Software Foundation may publish new, revised versions |
| 647 | of the GNU Free Documentation License from time to time. Such new |
| 648 | versions will be similar in spirit to the present version, but may |
| 649 | differ in detail to address new problems or concerns. See |
| 650 | http://www.gnu.org/copyleft/. |
| 651 | |
| 652 | Each version of the License is given a distinguishing version number. |
| 653 | If the Document specifies that a particular numbered version of this |
| 654 | License "or any later version" applies to it, you have the option of |
| 655 | following the terms and conditions either of that specified version or |
| 656 | of any later version that has been published (not as a draft) by the |
| 657 | Free Software Foundation. If the Document does not specify a version |
| 658 | number of this License, you may choose any version ever published (not |
| 659 | as a draft) by the Free Software Foundation. |
| 660 | |
| 661 | |
| 662 | ADDENDUM: How to use this License for your documents |
| 663 | |
| 664 | To use this License in a document you have written, include a copy of |
| 665 | the License in the document and put the following copyright and |
| 666 | license notices just after the title page: |
| 667 | |
| 668 | @smallexample |
| 669 | Copyright (c) YEAR YOUR NAME. |
| 670 | Permission is granted to copy, distribute and/or modify this document |
| 671 | under the terms of the GNU Free Documentation License, Version 1.1 |
| 672 | or any later version published by the Free Software Foundation; |
| 673 | with the Invariant Sections being LIST THEIR TITLES, with the |
| 674 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| 675 | A copy of the license is included in the section entitled "GNU |
| 676 | Free Documentation License". |
| 677 | @end smallexample |
| 678 | |
| 679 | If you have no Invariant Sections, write "with no Invariant Sections" |
| 680 | instead of saying which ones are invariant. If you have no |
| 681 | Front-Cover Texts, write "no Front-Cover Texts" instead of |
| 682 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. |
| 683 | |
| 684 | If your document contains nontrivial examples of program code, we |
| 685 | recommend releasing these examples in parallel under your choice of |
| 686 | free software license, such as the GNU General Public License, |
| 687 | to permit their use in free software. |
| 688 | |
| 689 | @node Index, , GNU Free Documentation License , Top |
| 690 | @unnumbered Index |
| 691 | @printindex cp |
| 692 | |
| 693 | @tex |
| 694 | % I think something like @colophon should be in texinfo. In the |
| 695 | % meantime: |
| 696 | \long\def\colophon{\hbox to0pt{}\vfill |
| 697 | \centerline{The body of this manual is set in} |
| 698 | \centerline{\fontname\tenrm,} |
| 699 | \centerline{with headings in {\bf\fontname\tenbf}} |
| 700 | \centerline{and examples in {\tt\fontname\tentt}.} |
| 701 | \centerline{{\it\fontname\tenit\/} and} |
| 702 | \centerline{{\sl\fontname\tensl\/}} |
| 703 | \centerline{are used for emphasis.}\vfill} |
| 704 | \page\colophon |
| 705 | % Blame: doc@cygnus.com, 28mar91. |
| 706 | @end tex |
| 707 | |
| 708 | @contents |
| 709 | @bye |