Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo.tex |
2 | @setfilename bfd.info | |
7898deda NC |
3 | @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000 |
4 | @c Free Software Foundation, Inc. | |
5 | @c | |
252b5132 RH |
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 | ||
07d8a891 | 33 | Copyright (C) 1991, 2000, 2001 Free Software Foundation, Inc. |
252b5132 | 34 | |
4a8e467a NC |
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". | |
252b5132 RH |
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 | |
252b5132 RH |
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 | |
07d8a891 NC |
59 | @subtitle First Edition---BFD version < 3.0 % Since no product is stable berfore version 3.0 :-) |
60 | @subtitle Original Document Created: April 1991 | |
252b5132 RH |
61 | @author {Steve Chamberlain} |
62 | @author {Cygnus Support} | |
63 | @page | |
64 | ||
65 | @tex | |
66 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
93509525 | 67 | \xdef\manvers{\1.5} % For use in headers, footers too |
252b5132 | 68 | {\parskip=0pt |
07d8a891 NC |
69 | \hfill Free Software Foundation\par |
70 | \hfill sac\@www.gnu.org\par | |
252b5132 RH |
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 | |
07d8a891 | 78 | Copyright @copyright{} 1991, 2001 Free Software Foundation, Inc. |
252b5132 | 79 | |
4a8e467a NC |
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". | |
252b5132 | 86 | |
252b5132 RH |
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 | |
4a8e467a | 99 | * GNU Free Documentation License:: GNU Free Documentation License |
252b5132 RH |
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 | |
93509525 | 210 | @include bfdio.texi |
252b5132 RH |
211 | |
212 | @menu | |
213 | * Memory Usage:: | |
214 | * Initialization:: | |
215 | * Sections:: | |
216 | * Symbols:: | |
217 | * Archives:: | |
218 | * Formats:: | |
219 | * Relocations:: | |
220 | * Core Files:: | |
221 | * Targets:: | |
222 | * Architectures:: | |
223 | * Opening and Closing:: | |
224 | * Internal:: | |
225 | * File Caching:: | |
226 | * Linker Functions:: | |
227 | * Hash Tables:: | |
228 | @end menu | |
229 | ||
230 | @node Memory Usage, Initialization, BFD front end, BFD front end | |
231 | @section Memory usage | |
232 | BFD keeps all of its internal structures in obstacks. There is one obstack | |
233 | per open BFD file, into which the current state is stored. When a BFD is | |
234 | closed, the obstack is deleted, and so everything which has been | |
235 | allocated by BFD for the closing file is thrown away. | |
236 | ||
237 | BFD does not free anything created by an application, but pointers into | |
238 | @code{bfd} structures become invalid on a @code{bfd_close}; for example, | |
239 | after a @code{bfd_close} the vector passed to | |
240 | @code{bfd_canonicalize_symtab} is still around, since it has been | |
241 | allocated by the application, but the data that it pointed to are | |
242 | lost. | |
243 | ||
244 | The general rule is to not close a BFD until all operations dependent | |
245 | upon data from the BFD have been completed, or all the data from within | |
246 | the file has been copied. To help with the management of memory, there | |
247 | is a function (@code{bfd_alloc_size}) which returns the number of bytes | |
248 | in obstacks associated with the supplied BFD. This could be used to | |
249 | select the greediest open BFD, close it to reclaim the memory, perform | |
250 | some operation and reopen the BFD again, to get a fresh copy of the data | |
251 | structures. | |
252 | ||
253 | @node Initialization, Sections, Memory Usage, BFD front end | |
254 | @include init.texi | |
255 | ||
256 | @node Sections, Symbols, Initialization, BFD front end | |
257 | @include section.texi | |
258 | ||
259 | @node Symbols, Archives, Sections, BFD front end | |
260 | @include syms.texi | |
261 | ||
262 | @node Archives, Formats, Symbols, BFD front end | |
263 | @include archive.texi | |
264 | ||
265 | @node Formats, Relocations, Archives, BFD front end | |
266 | @include format.texi | |
267 | ||
268 | @node Relocations, Core Files, Formats, BFD front end | |
269 | @include reloc.texi | |
270 | ||
271 | @node Core Files, Targets, Relocations, BFD front end | |
272 | @include core.texi | |
273 | ||
274 | @node Targets, Architectures, Core Files, BFD front end | |
275 | @include targets.texi | |
276 | ||
277 | @node Architectures, Opening and Closing, Targets, BFD front end | |
278 | @include archures.texi | |
279 | ||
280 | @node Opening and Closing, Internal, Architectures, BFD front end | |
281 | @include opncls.texi | |
282 | ||
283 | @node Internal, File Caching, Opening and Closing, BFD front end | |
284 | @include libbfd.texi | |
285 | ||
286 | @node File Caching, Linker Functions, Internal, BFD front end | |
287 | @include cache.texi | |
288 | ||
289 | @node Linker Functions, Hash Tables, File Caching, BFD front end | |
290 | @include linker.texi | |
291 | ||
292 | @node Hash Tables, , Linker Functions, BFD front end | |
293 | @include hash.texi | |
294 | ||
4a8e467a | 295 | @node BFD back ends, GNU Free Documentation License, BFD front end, Top |
252b5132 RH |
296 | @chapter BFD back ends |
297 | @menu | |
298 | * What to Put Where:: | |
299 | * aout :: a.out backends | |
300 | * coff :: coff backends | |
301 | * elf :: elf backends | |
3c3bdf30 | 302 | * mmo :: mmo backend |
252b5132 RH |
303 | @ignore |
304 | * oasys :: oasys backends | |
305 | * ieee :: ieee backend | |
306 | * srecord :: s-record backend | |
307 | @end ignore | |
308 | @end menu | |
309 | @node What to Put Where, aout, BFD back ends, BFD back ends | |
310 | All of BFD lives in one directory. | |
311 | ||
312 | @node aout, coff, What to Put Where, BFD back ends | |
313 | @include aoutx.texi | |
314 | ||
315 | @node coff, elf, aout, BFD back ends | |
316 | @include coffcode.texi | |
317 | ||
3c3bdf30 | 318 | @node elf, mmo, coff, BFD back ends |
252b5132 RH |
319 | @include elf.texi |
320 | @c Leave this out until the file has some actual contents... | |
321 | @c @include elfcode.texi | |
322 | ||
3c3bdf30 NC |
323 | @node mmo, , elf, BFD back ends |
324 | @include mmo.texi | |
325 | ||
4a8e467a NC |
326 | @node GNU Free Documentation License, Index, BFD back ends, Top |
327 | @chapter GNU Free Documentation License | |
328 | @cindex GNU Free Documentation License | |
329 | ||
330 | GNU Free Documentation License | |
331 | ||
332 | Version 1.1, March 2000 | |
333 | ||
334 | Copyright (C) 2000 Free Software Foundation, Inc. | |
335 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
336 | ||
337 | Everyone is permitted to copy and distribute verbatim copies | |
338 | of this license document, but changing it is not allowed. | |
339 | ||
340 | ||
341 | 0. PREAMBLE | |
342 | ||
343 | The purpose of this License is to make a manual, textbook, or other | |
344 | written document "free" in the sense of freedom: to assure everyone | |
345 | the effective freedom to copy and redistribute it, with or without | |
346 | modifying it, either commercially or noncommercially. Secondarily, | |
347 | this License preserves for the author and publisher a way to get | |
348 | credit for their work, while not being considered responsible for | |
349 | modifications made by others. | |
350 | ||
351 | This License is a kind of "copyleft", which means that derivative | |
352 | works of the document must themselves be free in the same sense. It | |
353 | complements the GNU General Public License, which is a copyleft | |
354 | license designed for free software. | |
355 | ||
356 | We have designed this License in order to use it for manuals for free | |
357 | software, because free software needs free documentation: a free | |
358 | program should come with manuals providing the same freedoms that the | |
359 | software does. But this License is not limited to software manuals; | |
360 | it can be used for any textual work, regardless of subject matter or | |
361 | whether it is published as a printed book. We recommend this License | |
362 | principally for works whose purpose is instruction or reference. | |
363 | ||
364 | ||
365 | 1. APPLICABILITY AND DEFINITIONS | |
366 | ||
367 | This License applies to any manual or other work that contains a | |
368 | notice placed by the copyright holder saying it can be distributed | |
369 | under the terms of this License. The "Document", below, refers to any | |
370 | such manual or work. Any member of the public is a licensee, and is | |
371 | addressed as "you". | |
372 | ||
373 | A "Modified Version" of the Document means any work containing the | |
374 | Document or a portion of it, either copied verbatim, or with | |
375 | modifications and/or translated into another language. | |
376 | ||
377 | A "Secondary Section" is a named appendix or a front-matter section of | |
378 | the Document that deals exclusively with the relationship of the | |
379 | publishers or authors of the Document to the Document's overall subject | |
380 | (or to related matters) and contains nothing that could fall directly | |
381 | within that overall subject. (For example, if the Document is in part a | |
382 | textbook of mathematics, a Secondary Section may not explain any | |
383 | mathematics.) The relationship could be a matter of historical | |
384 | connection with the subject or with related matters, or of legal, | |
385 | commercial, philosophical, ethical or political position regarding | |
386 | them. | |
387 | ||
388 | The "Invariant Sections" are certain Secondary Sections whose titles | |
389 | are designated, as being those of Invariant Sections, in the notice | |
390 | that says that the Document is released under this License. | |
391 | ||
392 | The "Cover Texts" are certain short passages of text that are listed, | |
393 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
394 | the Document is released under this License. | |
395 | ||
396 | A "Transparent" copy of the Document means a machine-readable copy, | |
397 | represented in a format whose specification is available to the | |
398 | general public, whose contents can be viewed and edited directly and | |
399 | straightforwardly with generic text editors or (for images composed of | |
400 | pixels) generic paint programs or (for drawings) some widely available | |
401 | drawing editor, and that is suitable for input to text formatters or | |
402 | for automatic translation to a variety of formats suitable for input | |
403 | to text formatters. A copy made in an otherwise Transparent file | |
404 | format whose markup has been designed to thwart or discourage | |
405 | subsequent modification by readers is not Transparent. A copy that is | |
406 | not "Transparent" is called "Opaque". | |
407 | ||
408 | Examples of suitable formats for Transparent copies include plain | |
409 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
410 | or XML using a publicly available DTD, and standard-conforming simple | |
411 | HTML designed for human modification. Opaque formats include | |
412 | PostScript, PDF, proprietary formats that can be read and edited only | |
413 | by proprietary word processors, SGML or XML for which the DTD and/or | |
414 | processing tools are not generally available, and the | |
415 | machine-generated HTML produced by some word processors for output | |
416 | purposes only. | |
417 | ||
418 | The "Title Page" means, for a printed book, the title page itself, | |
419 | plus such following pages as are needed to hold, legibly, the material | |
420 | this License requires to appear in the title page. For works in | |
421 | formats which do not have any title page as such, "Title Page" means | |
422 | the text near the most prominent appearance of the work's title, | |
423 | preceding the beginning of the body of the text. | |
424 | ||
425 | ||
426 | 2. VERBATIM COPYING | |
427 | ||
428 | You may copy and distribute the Document in any medium, either | |
429 | commercially or noncommercially, provided that this License, the | |
430 | copyright notices, and the license notice saying this License applies | |
431 | to the Document are reproduced in all copies, and that you add no other | |
432 | conditions whatsoever to those of this License. You may not use | |
433 | technical measures to obstruct or control the reading or further | |
434 | copying of the copies you make or distribute. However, you may accept | |
435 | compensation in exchange for copies. If you distribute a large enough | |
436 | number of copies you must also follow the conditions in section 3. | |
437 | ||
438 | You may also lend copies, under the same conditions stated above, and | |
439 | you may publicly display copies. | |
440 | ||
441 | ||
442 | 3. COPYING IN QUANTITY | |
443 | ||
444 | If you publish printed copies of the Document numbering more than 100, | |
445 | and the Document's license notice requires Cover Texts, you must enclose | |
446 | the copies in covers that carry, clearly and legibly, all these Cover | |
447 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
448 | the back cover. Both covers must also clearly and legibly identify | |
449 | you as the publisher of these copies. The front cover must present | |
450 | the full title with all words of the title equally prominent and | |
451 | visible. You may add other material on the covers in addition. | |
452 | Copying with changes limited to the covers, as long as they preserve | |
453 | the title of the Document and satisfy these conditions, can be treated | |
454 | as verbatim copying in other respects. | |
455 | ||
456 | If the required texts for either cover are too voluminous to fit | |
457 | legibly, you should put the first ones listed (as many as fit | |
458 | reasonably) on the actual cover, and continue the rest onto adjacent | |
459 | pages. | |
460 | ||
461 | If you publish or distribute Opaque copies of the Document numbering | |
462 | more than 100, you must either include a machine-readable Transparent | |
463 | copy along with each Opaque copy, or state in or with each Opaque copy | |
464 | a publicly-accessible computer-network location containing a complete | |
465 | Transparent copy of the Document, free of added material, which the | |
466 | general network-using public has access to download anonymously at no | |
467 | charge using public-standard network protocols. If you use the latter | |
468 | option, you must take reasonably prudent steps, when you begin | |
469 | distribution of Opaque copies in quantity, to ensure that this | |
470 | Transparent copy will remain thus accessible at the stated location | |
471 | until at least one year after the last time you distribute an Opaque | |
472 | copy (directly or through your agents or retailers) of that edition to | |
473 | the public. | |
474 | ||
475 | It is requested, but not required, that you contact the authors of the | |
476 | Document well before redistributing any large number of copies, to give | |
477 | them a chance to provide you with an updated version of the Document. | |
478 | ||
479 | ||
480 | 4. MODIFICATIONS | |
481 | ||
482 | You may copy and distribute a Modified Version of the Document under | |
483 | the conditions of sections 2 and 3 above, provided that you release | |
484 | the Modified Version under precisely this License, with the Modified | |
485 | Version filling the role of the Document, thus licensing distribution | |
486 | and modification of the Modified Version to whoever possesses a copy | |
487 | of it. In addition, you must do these things in the Modified Version: | |
488 | ||
489 | A. Use in the Title Page (and on the covers, if any) a title distinct | |
490 | from that of the Document, and from those of previous versions | |
491 | (which should, if there were any, be listed in the History section | |
492 | of the Document). You may use the same title as a previous version | |
493 | if the original publisher of that version gives permission. | |
494 | B. List on the Title Page, as authors, one or more persons or entities | |
495 | responsible for authorship of the modifications in the Modified | |
496 | Version, together with at least five of the principal authors of the | |
497 | Document (all of its principal authors, if it has less than five). | |
498 | C. State on the Title page the name of the publisher of the | |
499 | Modified Version, as the publisher. | |
500 | D. Preserve all the copyright notices of the Document. | |
501 | E. Add an appropriate copyright notice for your modifications | |
502 | adjacent to the other copyright notices. | |
503 | F. Include, immediately after the copyright notices, a license notice | |
504 | giving the public permission to use the Modified Version under the | |
505 | terms of this License, in the form shown in the Addendum below. | |
506 | G. Preserve in that license notice the full lists of Invariant Sections | |
507 | and required Cover Texts given in the Document's license notice. | |
508 | H. Include an unaltered copy of this License. | |
509 | I. Preserve the section entitled "History", and its title, and add to | |
510 | it an item stating at least the title, year, new authors, and | |
511 | publisher of the Modified Version as given on the Title Page. If | |
512 | there is no section entitled "History" in the Document, create one | |
513 | stating the title, year, authors, and publisher of the Document as | |
514 | given on its Title Page, then add an item describing the Modified | |
515 | Version as stated in the previous sentence. | |
516 | J. Preserve the network location, if any, given in the Document for | |
517 | public access to a Transparent copy of the Document, and likewise | |
518 | the network locations given in the Document for previous versions | |
519 | it was based on. These may be placed in the "History" section. | |
520 | You may omit a network location for a work that was published at | |
521 | least four years before the Document itself, or if the original | |
522 | publisher of the version it refers to gives permission. | |
523 | K. In any section entitled "Acknowledgements" or "Dedications", | |
524 | preserve the section's title, and preserve in the section all the | |
525 | substance and tone of each of the contributor acknowledgements | |
526 | and/or dedications given therein. | |
527 | L. Preserve all the Invariant Sections of the Document, | |
528 | unaltered in their text and in their titles. Section numbers | |
529 | or the equivalent are not considered part of the section titles. | |
530 | M. Delete any section entitled "Endorsements". Such a section | |
531 | may not be included in the Modified Version. | |
532 | N. Do not retitle any existing section as "Endorsements" | |
533 | or to conflict in title with any Invariant Section. | |
534 | ||
535 | If the Modified Version includes new front-matter sections or | |
536 | appendices that qualify as Secondary Sections and contain no material | |
537 | copied from the Document, you may at your option designate some or all | |
538 | of these sections as invariant. To do this, add their titles to the | |
539 | list of Invariant Sections in the Modified Version's license notice. | |
540 | These titles must be distinct from any other section titles. | |
541 | ||
542 | You may add a section entitled "Endorsements", provided it contains | |
543 | nothing but endorsements of your Modified Version by various | |
544 | parties--for example, statements of peer review or that the text has | |
545 | been approved by an organization as the authoritative definition of a | |
546 | standard. | |
547 | ||
548 | You may add a passage of up to five words as a Front-Cover Text, and a | |
549 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
550 | of Cover Texts in the Modified Version. Only one passage of | |
551 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
552 | through arrangements made by) any one entity. If the Document already | |
553 | includes a cover text for the same cover, previously added by you or | |
554 | by arrangement made by the same entity you are acting on behalf of, | |
555 | you may not add another; but you may replace the old one, on explicit | |
556 | permission from the previous publisher that added the old one. | |
557 | ||
558 | The author(s) and publisher(s) of the Document do not by this License | |
559 | give permission to use their names for publicity for or to assert or | |
560 | imply endorsement of any Modified Version. | |
561 | ||
562 | ||
563 | 5. COMBINING DOCUMENTS | |
564 | ||
565 | You may combine the Document with other documents released under this | |
566 | License, under the terms defined in section 4 above for modified | |
567 | versions, provided that you include in the combination all of the | |
568 | Invariant Sections of all of the original documents, unmodified, and | |
569 | list them all as Invariant Sections of your combined work in its | |
570 | license notice. | |
571 | ||
572 | The combined work need only contain one copy of this License, and | |
573 | multiple identical Invariant Sections may be replaced with a single | |
574 | copy. If there are multiple Invariant Sections with the same name but | |
575 | different contents, make the title of each such section unique by | |
576 | adding at the end of it, in parentheses, the name of the original | |
577 | author or publisher of that section if known, or else a unique number. | |
578 | Make the same adjustment to the section titles in the list of | |
579 | Invariant Sections in the license notice of the combined work. | |
580 | ||
581 | In the combination, you must combine any sections entitled "History" | |
582 | in the various original documents, forming one section entitled | |
583 | "History"; likewise combine any sections entitled "Acknowledgements", | |
584 | and any sections entitled "Dedications". You must delete all sections | |
585 | entitled "Endorsements." | |
586 | ||
587 | ||
588 | 6. COLLECTIONS OF DOCUMENTS | |
589 | ||
590 | You may make a collection consisting of the Document and other documents | |
591 | released under this License, and replace the individual copies of this | |
592 | License in the various documents with a single copy that is included in | |
593 | the collection, provided that you follow the rules of this License for | |
594 | verbatim copying of each of the documents in all other respects. | |
595 | ||
596 | You may extract a single document from such a collection, and distribute | |
597 | it individually under this License, provided you insert a copy of this | |
598 | License into the extracted document, and follow this License in all | |
599 | other respects regarding verbatim copying of that document. | |
600 | ||
601 | ||
602 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
603 | ||
604 | A compilation of the Document or its derivatives with other separate | |
605 | and independent documents or works, in or on a volume of a storage or | |
606 | distribution medium, does not as a whole count as a Modified Version | |
607 | of the Document, provided no compilation copyright is claimed for the | |
608 | compilation. Such a compilation is called an "aggregate", and this | |
609 | License does not apply to the other self-contained works thus compiled | |
610 | with the Document, on account of their being thus compiled, if they | |
611 | are not themselves derivative works of the Document. | |
612 | ||
613 | If the Cover Text requirement of section 3 is applicable to these | |
614 | copies of the Document, then if the Document is less than one quarter | |
615 | of the entire aggregate, the Document's Cover Texts may be placed on | |
616 | covers that surround only the Document within the aggregate. | |
617 | Otherwise they must appear on covers around the whole aggregate. | |
618 | ||
619 | ||
620 | 8. TRANSLATION | |
621 | ||
622 | Translation is considered a kind of modification, so you may | |
623 | distribute translations of the Document under the terms of section 4. | |
624 | Replacing Invariant Sections with translations requires special | |
625 | permission from their copyright holders, but you may include | |
626 | translations of some or all Invariant Sections in addition to the | |
627 | original versions of these Invariant Sections. You may include a | |
628 | translation of this License provided that you also include the | |
629 | original English version of this License. In case of a disagreement | |
630 | between the translation and the original English version of this | |
631 | License, the original English version will prevail. | |
632 | ||
633 | ||
634 | 9. TERMINATION | |
635 | ||
636 | You may not copy, modify, sublicense, or distribute the Document except | |
637 | as expressly provided for under this License. Any other attempt to | |
638 | copy, modify, sublicense or distribute the Document is void, and will | |
639 | automatically terminate your rights under this License. However, | |
640 | parties who have received copies, or rights, from you under this | |
641 | License will not have their licenses terminated so long as such | |
642 | parties remain in full compliance. | |
643 | ||
644 | ||
645 | 10. FUTURE REVISIONS OF THIS LICENSE | |
646 | ||
647 | The Free Software Foundation may publish new, revised versions | |
648 | of the GNU Free Documentation License from time to time. Such new | |
649 | versions will be similar in spirit to the present version, but may | |
650 | differ in detail to address new problems or concerns. See | |
651 | http://www.gnu.org/copyleft/. | |
652 | ||
653 | Each version of the License is given a distinguishing version number. | |
654 | If the Document specifies that a particular numbered version of this | |
655 | License "or any later version" applies to it, you have the option of | |
656 | following the terms and conditions either of that specified version or | |
657 | of any later version that has been published (not as a draft) by the | |
658 | Free Software Foundation. If the Document does not specify a version | |
659 | number of this License, you may choose any version ever published (not | |
660 | as a draft) by the Free Software Foundation. | |
661 | ||
662 | ||
663 | ADDENDUM: How to use this License for your documents | |
664 | ||
665 | To use this License in a document you have written, include a copy of | |
666 | the License in the document and put the following copyright and | |
667 | license notices just after the title page: | |
668 | ||
669 | @smallexample | |
670 | Copyright (c) YEAR YOUR NAME. | |
671 | Permission is granted to copy, distribute and/or modify this document | |
672 | under the terms of the GNU Free Documentation License, Version 1.1 | |
673 | or any later version published by the Free Software Foundation; | |
674 | with the Invariant Sections being LIST THEIR TITLES, with the | |
675 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
676 | A copy of the license is included in the section entitled "GNU | |
677 | Free Documentation License". | |
678 | @end smallexample | |
679 | ||
680 | If you have no Invariant Sections, write "with no Invariant Sections" | |
681 | instead of saying which ones are invariant. If you have no | |
682 | Front-Cover Texts, write "no Front-Cover Texts" instead of | |
683 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
684 | ||
685 | If your document contains nontrivial examples of program code, we | |
686 | recommend releasing these examples in parallel under your choice of | |
687 | free software license, such as the GNU General Public License, | |
688 | to permit their use in free software. | |
689 | ||
690 | @node Index, , GNU Free Documentation License , Top | |
252b5132 RH |
691 | @unnumbered Index |
692 | @printindex cp | |
693 | ||
694 | @tex | |
695 | % I think something like @colophon should be in texinfo. In the | |
696 | % meantime: | |
697 | \long\def\colophon{\hbox to0pt{}\vfill | |
698 | \centerline{The body of this manual is set in} | |
699 | \centerline{\fontname\tenrm,} | |
700 | \centerline{with headings in {\bf\fontname\tenbf}} | |
701 | \centerline{and examples in {\tt\fontname\tentt}.} | |
702 | \centerline{{\it\fontname\tenit\/} and} | |
703 | \centerline{{\sl\fontname\tensl\/}} | |
704 | \centerline{are used for emphasis.}\vfill} | |
705 | \page\colophon | |
706 | % Blame: doc@cygnus.com, 28mar91. | |
707 | @end tex | |
708 | ||
709 | @contents | |
710 | @bye |