bfd.texinfo revision 77298
133965Sjdp\input texinfo.tex 233965Sjdp@setfilename bfd.info 377298Sobrien@c $Id: bfd.texinfo,v 1.2 2000/11/15 18:24:49 nickc Exp $ 433965Sjdp@tex 533965Sjdp% NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE 633965Sjdp\global\long\def\example{% 733965Sjdp\begingroup 833965Sjdp\let\aboveenvbreak=\par 933965Sjdp\let\afterenvbreak=\par 1033965Sjdp\parskip=0pt 1133965Sjdp\lisp} 1233965Sjdp\global\long\def\Eexample{% 1333965Sjdp\Elisp 1433965Sjdp\endgroup 1533965Sjdp\vskip -\parskip% to cancel out effect of following \par 1633965Sjdp} 1733965Sjdp@end tex 1833965Sjdp@synindex fn cp 1933965Sjdp 2033965Sjdp@ifinfo 2133965Sjdp@format 2233965SjdpSTART-INFO-DIR-ENTRY 2333965Sjdp* Bfd: (bfd). The Binary File Descriptor library. 2433965SjdpEND-INFO-DIR-ENTRY 2533965Sjdp@end format 2633965Sjdp@end ifinfo 2733965Sjdp 2833965Sjdp@ifinfo 2933965SjdpThis file documents the BFD library. 3033965Sjdp 3177298SobrienCopyright (C) 1991, 2000 Free Software Foundation, Inc. 3233965Sjdp 3377298Sobrien Permission is granted to copy, distribute and/or modify this document 3477298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 3577298Sobrien or any later version published by the Free Software Foundation; 3677298Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 3777298Sobrien Back-Cover Texts. A copy of the license is included in the 3877298Sobrien section entitled "GNU Free Documentation License". 3933965Sjdp 4033965Sjdp@ignore 4133965SjdpPermission is granted to process this file through Tex and print the 4233965Sjdpresults, provided the printed document carries copying permission 4333965Sjdpnotice identical to this one except for the removal of this paragraph 4433965Sjdp(this paragraph not being relevant to the printed manual). 4533965Sjdp 4633965Sjdp@end ignore 4733965Sjdp@end ifinfo 4833965Sjdp@iftex 4933965Sjdp@c@finalout 5033965Sjdp@setchapternewpage on 5133965Sjdp@c@setchapternewpage odd 5233965Sjdp@settitle LIB BFD, the Binary File Descriptor Library 5333965Sjdp@titlepage 5433965Sjdp@title{libbfd} 5533965Sjdp@subtitle{The Binary File Descriptor Library} 5633965Sjdp@sp 1 5733965Sjdp@subtitle First Edition---BFD version < 3.0 5833965Sjdp@subtitle April 1991 5933965Sjdp@author {Steve Chamberlain} 6033965Sjdp@author {Cygnus Support} 6133965Sjdp@page 6233965Sjdp 6333965Sjdp@tex 6433965Sjdp\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 6577298Sobrien\xdef\manvers{\$Revision: 1.2 $} % For use in headers, footers too 6633965Sjdp{\parskip=0pt 6733965Sjdp\hfill Cygnus Support\par 6833965Sjdp\hfill sac\@cygnus.com\par 6933965Sjdp\hfill {\it BFD}, \manvers\par 7033965Sjdp\hfill \TeX{}info \texinfoversion\par 7133965Sjdp} 7233965Sjdp\global\parindent=0pt % Steve likes it this way 7333965Sjdp@end tex 7433965Sjdp 7533965Sjdp@vskip 0pt plus 1filll 7633965SjdpCopyright @copyright{} 1991 Free Software Foundation, Inc. 7733965Sjdp 7877298Sobrien Permission is granted to copy, distribute and/or modify this document 7977298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 8077298Sobrien or any later version published by the Free Software Foundation; 8177298Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 8277298Sobrien Back-Cover Texts. A copy of the license is included in the 8377298Sobrien section entitled "GNU Free Documentation License". 8433965Sjdp 8533965Sjdp@end titlepage 8633965Sjdp@end iftex 8733965Sjdp 8833965Sjdp@node Top, Overview, (dir), (dir) 8933965Sjdp@ifinfo 9033965SjdpThis file documents the binary file descriptor library libbfd. 9133965Sjdp@end ifinfo 9233965Sjdp 9333965Sjdp@menu 9433965Sjdp* Overview:: Overview of BFD 9533965Sjdp* BFD front end:: BFD front end 9633965Sjdp* BFD back ends:: BFD back ends 9777298Sobrien* GNU Free Documentation License:: GNU Free Documentation License 9833965Sjdp* Index:: Index 9933965Sjdp@end menu 10033965Sjdp 10133965Sjdp@node Overview, BFD front end, Top, Top 10233965Sjdp@chapter Introduction 10333965Sjdp@cindex BFD 10433965Sjdp@cindex what is it? 10533965SjdpBFD is a package which allows applications to use the 10633965Sjdpsame routines to operate on object files whatever the object file 10733965Sjdpformat. A new object file format can be supported simply by 10833965Sjdpcreating a new BFD back end and adding it to the library. 10933965Sjdp 11033965SjdpBFD is split into two parts: the front end, and the back ends (one for 11133965Sjdpeach object file format). 11233965Sjdp@itemize @bullet 11333965Sjdp@item The front end of BFD provides the interface to the user. It manages 11433965Sjdpmemory and various canonical data structures. The front end also 11533965Sjdpdecides which back end to use and when to call back end routines. 11633965Sjdp@item The back ends provide BFD its view of the real world. Each back 11733965Sjdpend provides a set of calls which the BFD front end can use to maintain 11833965Sjdpits canonical form. The back ends also may keep around information for 11933965Sjdptheir own use, for greater efficiency. 12033965Sjdp@end itemize 12133965Sjdp@menu 12233965Sjdp* History:: History 12333965Sjdp* How It Works:: How It Works 12433965Sjdp* What BFD Version 2 Can Do:: What BFD Version 2 Can Do 12533965Sjdp@end menu 12633965Sjdp 12733965Sjdp@node History, How It Works, Overview, Overview 12833965Sjdp@section History 12933965Sjdp 13033965SjdpOne spur behind BFD was the desire, on the part of the GNU 960 team at 13133965SjdpIntel Oregon, for interoperability of applications on their COFF and 13233965Sjdpb.out file formats. Cygnus was providing GNU support for the team, and 13333965Sjdpwas contracted to provide the required functionality. 13433965Sjdp 13533965SjdpThe name came from a conversation David Wallace was having with Richard 13633965SjdpStallman about the library: RMS said that it would be quite hard---David 13733965Sjdpsaid ``BFD''. Stallman was right, but the name stuck. 13833965Sjdp 13933965SjdpAt the same time, Ready Systems wanted much the same thing, but for 14033965Sjdpdifferent object file formats: IEEE-695, Oasys, Srecords, a.out and 68k 14133965Sjdpcoff. 14233965Sjdp 14333965SjdpBFD was first implemented by members of Cygnus Support; Steve 14433965SjdpChamberlain (@code{sac@@cygnus.com}), John Gilmore 14533965Sjdp(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) 14633965Sjdpand David Henkel-Wallace (@code{gumby@@cygnus.com}). 14733965Sjdp 14833965Sjdp 14933965Sjdp 15033965Sjdp@node How It Works, What BFD Version 2 Can Do, History, Overview 15133965Sjdp@section How To Use BFD 15233965Sjdp 15333965SjdpTo use the library, include @file{bfd.h} and link with @file{libbfd.a}. 15433965Sjdp 15533965SjdpBFD provides a common interface to the parts of an object file 15633965Sjdpfor a calling application. 15733965Sjdp 15833965SjdpWhen an application sucessfully opens a target file (object, archive, or 15933965Sjdpwhatever), a pointer to an internal structure is returned. This pointer 16033965Sjdppoints to a structure called @code{bfd}, described in 16133965Sjdp@file{bfd.h}. Our convention is to call this pointer a BFD, and 16233965Sjdpinstances of it within code @code{abfd}. All operations on 16333965Sjdpthe target object file are applied as methods to the BFD. The mapping is 16433965Sjdpdefined within @code{bfd.h} in a set of macros, all beginning 16533965Sjdpwith @samp{bfd_} to reduce namespace pollution. 16633965Sjdp 16733965SjdpFor example, this sequence does what you would probably expect: 16833965Sjdpreturn the number of sections in an object file attached to a BFD 16933965Sjdp@code{abfd}. 17033965Sjdp 17133965Sjdp@lisp 17233965Sjdp@c @cartouche 17333965Sjdp#include "bfd.h" 17433965Sjdp 17533965Sjdpunsigned int number_of_sections(abfd) 17633965Sjdpbfd *abfd; 17733965Sjdp@{ 17833965Sjdp return bfd_count_sections(abfd); 17933965Sjdp@} 18033965Sjdp@c @end cartouche 18133965Sjdp@end lisp 18233965Sjdp 18333965SjdpThe abstraction used within BFD is that an object file has: 18433965Sjdp 18533965Sjdp@itemize @bullet 18633965Sjdp@item 18733965Sjdpa header, 18833965Sjdp@item 18933965Sjdpa number of sections containing raw data (@pxref{Sections}), 19033965Sjdp@item 19133965Sjdpa set of relocations (@pxref{Relocations}), and 19233965Sjdp@item 19333965Sjdpsome symbol information (@pxref{Symbols}). 19433965Sjdp@end itemize 19533965Sjdp@noindent 19633965SjdpAlso, BFDs opened for archives have the additional attribute of an index 19733965Sjdpand contain subordinate BFDs. This approach is fine for a.out and coff, 19833965Sjdpbut loses efficiency when applied to formats such as S-records and 19933965SjdpIEEE-695. 20033965Sjdp 20133965Sjdp@node What BFD Version 2 Can Do, , How It Works, Overview 20233965Sjdp@section What BFD Version 2 Can Do 20333965Sjdp@include bfdsumm.texi 20433965Sjdp 20533965Sjdp@node BFD front end, BFD back ends, Overview, Top 20633965Sjdp@chapter BFD front end 20738889Sjdp@include bfdt.texi 20833965Sjdp 20933965Sjdp@menu 21033965Sjdp* Memory Usage:: 21133965Sjdp* Initialization:: 21233965Sjdp* Sections:: 21333965Sjdp* Symbols:: 21433965Sjdp* Archives:: 21533965Sjdp* Formats:: 21633965Sjdp* Relocations:: 21733965Sjdp* Core Files:: 21833965Sjdp* Targets:: 21933965Sjdp* Architectures:: 22033965Sjdp* Opening and Closing:: 22133965Sjdp* Internal:: 22233965Sjdp* File Caching:: 22333965Sjdp* Linker Functions:: 22433965Sjdp* Hash Tables:: 22533965Sjdp@end menu 22633965Sjdp 22733965Sjdp@node Memory Usage, Initialization, BFD front end, BFD front end 22833965Sjdp@section Memory usage 22933965SjdpBFD keeps all of its internal structures in obstacks. There is one obstack 23033965Sjdpper open BFD file, into which the current state is stored. When a BFD is 23133965Sjdpclosed, the obstack is deleted, and so everything which has been 23233965Sjdpallocated by BFD for the closing file is thrown away. 23333965Sjdp 23433965SjdpBFD does not free anything created by an application, but pointers into 23533965Sjdp@code{bfd} structures become invalid on a @code{bfd_close}; for example, 23633965Sjdpafter a @code{bfd_close} the vector passed to 23733965Sjdp@code{bfd_canonicalize_symtab} is still around, since it has been 23833965Sjdpallocated by the application, but the data that it pointed to are 23933965Sjdplost. 24033965Sjdp 24133965SjdpThe general rule is to not close a BFD until all operations dependent 24233965Sjdpupon data from the BFD have been completed, or all the data from within 24333965Sjdpthe file has been copied. To help with the management of memory, there 24433965Sjdpis a function (@code{bfd_alloc_size}) which returns the number of bytes 24533965Sjdpin obstacks associated with the supplied BFD. This could be used to 24633965Sjdpselect the greediest open BFD, close it to reclaim the memory, perform 24733965Sjdpsome operation and reopen the BFD again, to get a fresh copy of the data 24833965Sjdpstructures. 24933965Sjdp 25033965Sjdp@node Initialization, Sections, Memory Usage, BFD front end 25133965Sjdp@include init.texi 25233965Sjdp 25333965Sjdp@node Sections, Symbols, Initialization, BFD front end 25433965Sjdp@include section.texi 25533965Sjdp 25633965Sjdp@node Symbols, Archives, Sections, BFD front end 25733965Sjdp@include syms.texi 25833965Sjdp 25933965Sjdp@node Archives, Formats, Symbols, BFD front end 26033965Sjdp@include archive.texi 26133965Sjdp 26233965Sjdp@node Formats, Relocations, Archives, BFD front end 26333965Sjdp@include format.texi 26433965Sjdp 26533965Sjdp@node Relocations, Core Files, Formats, BFD front end 26633965Sjdp@include reloc.texi 26733965Sjdp 26833965Sjdp@node Core Files, Targets, Relocations, BFD front end 26933965Sjdp@include core.texi 27033965Sjdp 27133965Sjdp@node Targets, Architectures, Core Files, BFD front end 27233965Sjdp@include targets.texi 27333965Sjdp 27433965Sjdp@node Architectures, Opening and Closing, Targets, BFD front end 27533965Sjdp@include archures.texi 27633965Sjdp 27733965Sjdp@node Opening and Closing, Internal, Architectures, BFD front end 27833965Sjdp@include opncls.texi 27933965Sjdp 28033965Sjdp@node Internal, File Caching, Opening and Closing, BFD front end 28133965Sjdp@include libbfd.texi 28233965Sjdp 28333965Sjdp@node File Caching, Linker Functions, Internal, BFD front end 28433965Sjdp@include cache.texi 28533965Sjdp 28633965Sjdp@node Linker Functions, Hash Tables, File Caching, BFD front end 28733965Sjdp@include linker.texi 28833965Sjdp 28933965Sjdp@node Hash Tables, , Linker Functions, BFD front end 29033965Sjdp@include hash.texi 29133965Sjdp 29277298Sobrien@node BFD back ends, GNU Free Documentation License, BFD front end, Top 29333965Sjdp@chapter BFD back ends 29433965Sjdp@menu 29533965Sjdp* What to Put Where:: 29633965Sjdp* aout :: a.out backends 29733965Sjdp* coff :: coff backends 29833965Sjdp* elf :: elf backends 29933965Sjdp@ignore 30033965Sjdp* oasys :: oasys backends 30133965Sjdp* ieee :: ieee backend 30233965Sjdp* srecord :: s-record backend 30333965Sjdp@end ignore 30433965Sjdp@end menu 30533965Sjdp@node What to Put Where, aout, BFD back ends, BFD back ends 30633965SjdpAll of BFD lives in one directory. 30733965Sjdp 30833965Sjdp@node aout, coff, What to Put Where, BFD back ends 30933965Sjdp@include aoutx.texi 31033965Sjdp 31133965Sjdp@node coff, elf, aout, BFD back ends 31233965Sjdp@include coffcode.texi 31333965Sjdp 31433965Sjdp@node elf, , coff, BFD back ends 31533965Sjdp@include elf.texi 31633965Sjdp@c Leave this out until the file has some actual contents... 31733965Sjdp@c @include elfcode.texi 31833965Sjdp 31977298Sobrien@node GNU Free Documentation License, Index, BFD back ends, Top 32077298Sobrien@chapter GNU Free Documentation License 32177298Sobrien@cindex GNU Free Documentation License 32277298Sobrien 32377298Sobrien GNU Free Documentation License 32477298Sobrien 32577298Sobrien Version 1.1, March 2000 32677298Sobrien 32777298Sobrien Copyright (C) 2000 Free Software Foundation, Inc. 32877298Sobrien 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 32977298Sobrien 33077298Sobrien Everyone is permitted to copy and distribute verbatim copies 33177298Sobrien of this license document, but changing it is not allowed. 33277298Sobrien 33377298Sobrien 33477298Sobrien0. PREAMBLE 33577298Sobrien 33677298SobrienThe purpose of this License is to make a manual, textbook, or other 33777298Sobrienwritten document "free" in the sense of freedom: to assure everyone 33877298Sobrienthe effective freedom to copy and redistribute it, with or without 33977298Sobrienmodifying it, either commercially or noncommercially. Secondarily, 34077298Sobrienthis License preserves for the author and publisher a way to get 34177298Sobriencredit for their work, while not being considered responsible for 34277298Sobrienmodifications made by others. 34377298Sobrien 34477298SobrienThis License is a kind of "copyleft", which means that derivative 34577298Sobrienworks of the document must themselves be free in the same sense. It 34677298Sobriencomplements the GNU General Public License, which is a copyleft 34777298Sobrienlicense designed for free software. 34877298Sobrien 34977298SobrienWe have designed this License in order to use it for manuals for free 35077298Sobriensoftware, because free software needs free documentation: a free 35177298Sobrienprogram should come with manuals providing the same freedoms that the 35277298Sobriensoftware does. But this License is not limited to software manuals; 35377298Sobrienit can be used for any textual work, regardless of subject matter or 35477298Sobrienwhether it is published as a printed book. We recommend this License 35577298Sobrienprincipally for works whose purpose is instruction or reference. 35677298Sobrien 35777298Sobrien 35877298Sobrien1. APPLICABILITY AND DEFINITIONS 35977298Sobrien 36077298SobrienThis License applies to any manual or other work that contains a 36177298Sobriennotice placed by the copyright holder saying it can be distributed 36277298Sobrienunder the terms of this License. The "Document", below, refers to any 36377298Sobriensuch manual or work. Any member of the public is a licensee, and is 36477298Sobrienaddressed as "you". 36577298Sobrien 36677298SobrienA "Modified Version" of the Document means any work containing the 36777298SobrienDocument or a portion of it, either copied verbatim, or with 36877298Sobrienmodifications and/or translated into another language. 36977298Sobrien 37077298SobrienA "Secondary Section" is a named appendix or a front-matter section of 37177298Sobrienthe Document that deals exclusively with the relationship of the 37277298Sobrienpublishers or authors of the Document to the Document's overall subject 37377298Sobrien(or to related matters) and contains nothing that could fall directly 37477298Sobrienwithin that overall subject. (For example, if the Document is in part a 37577298Sobrientextbook of mathematics, a Secondary Section may not explain any 37677298Sobrienmathematics.) The relationship could be a matter of historical 37777298Sobrienconnection with the subject or with related matters, or of legal, 37877298Sobriencommercial, philosophical, ethical or political position regarding 37977298Sobrienthem. 38077298Sobrien 38177298SobrienThe "Invariant Sections" are certain Secondary Sections whose titles 38277298Sobrienare designated, as being those of Invariant Sections, in the notice 38377298Sobrienthat says that the Document is released under this License. 38477298Sobrien 38577298SobrienThe "Cover Texts" are certain short passages of text that are listed, 38677298Sobrienas Front-Cover Texts or Back-Cover Texts, in the notice that says that 38777298Sobrienthe Document is released under this License. 38877298Sobrien 38977298SobrienA "Transparent" copy of the Document means a machine-readable copy, 39077298Sobrienrepresented in a format whose specification is available to the 39177298Sobriengeneral public, whose contents can be viewed and edited directly and 39277298Sobrienstraightforwardly with generic text editors or (for images composed of 39377298Sobrienpixels) generic paint programs or (for drawings) some widely available 39477298Sobriendrawing editor, and that is suitable for input to text formatters or 39577298Sobrienfor automatic translation to a variety of formats suitable for input 39677298Sobriento text formatters. A copy made in an otherwise Transparent file 39777298Sobrienformat whose markup has been designed to thwart or discourage 39877298Sobriensubsequent modification by readers is not Transparent. A copy that is 39977298Sobriennot "Transparent" is called "Opaque". 40077298Sobrien 40177298SobrienExamples of suitable formats for Transparent copies include plain 40277298SobrienASCII without markup, Texinfo input format, LaTeX input format, SGML 40377298Sobrienor XML using a publicly available DTD, and standard-conforming simple 40477298SobrienHTML designed for human modification. Opaque formats include 40577298SobrienPostScript, PDF, proprietary formats that can be read and edited only 40677298Sobrienby proprietary word processors, SGML or XML for which the DTD and/or 40777298Sobrienprocessing tools are not generally available, and the 40877298Sobrienmachine-generated HTML produced by some word processors for output 40977298Sobrienpurposes only. 41077298Sobrien 41177298SobrienThe "Title Page" means, for a printed book, the title page itself, 41277298Sobrienplus such following pages as are needed to hold, legibly, the material 41377298Sobrienthis License requires to appear in the title page. For works in 41477298Sobrienformats which do not have any title page as such, "Title Page" means 41577298Sobrienthe text near the most prominent appearance of the work's title, 41677298Sobrienpreceding the beginning of the body of the text. 41777298Sobrien 41877298Sobrien 41977298Sobrien2. VERBATIM COPYING 42077298Sobrien 42177298SobrienYou may copy and distribute the Document in any medium, either 42277298Sobriencommercially or noncommercially, provided that this License, the 42377298Sobriencopyright notices, and the license notice saying this License applies 42477298Sobriento the Document are reproduced in all copies, and that you add no other 42577298Sobrienconditions whatsoever to those of this License. You may not use 42677298Sobrientechnical measures to obstruct or control the reading or further 42777298Sobriencopying of the copies you make or distribute. However, you may accept 42877298Sobriencompensation in exchange for copies. If you distribute a large enough 42977298Sobriennumber of copies you must also follow the conditions in section 3. 43077298Sobrien 43177298SobrienYou may also lend copies, under the same conditions stated above, and 43277298Sobrienyou may publicly display copies. 43377298Sobrien 43477298Sobrien 43577298Sobrien3. COPYING IN QUANTITY 43677298Sobrien 43777298SobrienIf you publish printed copies of the Document numbering more than 100, 43877298Sobrienand the Document's license notice requires Cover Texts, you must enclose 43977298Sobrienthe copies in covers that carry, clearly and legibly, all these Cover 44077298SobrienTexts: Front-Cover Texts on the front cover, and Back-Cover Texts on 44177298Sobrienthe back cover. Both covers must also clearly and legibly identify 44277298Sobrienyou as the publisher of these copies. The front cover must present 44377298Sobrienthe full title with all words of the title equally prominent and 44477298Sobrienvisible. You may add other material on the covers in addition. 44577298SobrienCopying with changes limited to the covers, as long as they preserve 44677298Sobrienthe title of the Document and satisfy these conditions, can be treated 44777298Sobrienas verbatim copying in other respects. 44877298Sobrien 44977298SobrienIf the required texts for either cover are too voluminous to fit 45077298Sobrienlegibly, you should put the first ones listed (as many as fit 45177298Sobrienreasonably) on the actual cover, and continue the rest onto adjacent 45277298Sobrienpages. 45377298Sobrien 45477298SobrienIf you publish or distribute Opaque copies of the Document numbering 45577298Sobrienmore than 100, you must either include a machine-readable Transparent 45677298Sobriencopy along with each Opaque copy, or state in or with each Opaque copy 45777298Sobriena publicly-accessible computer-network location containing a complete 45877298SobrienTransparent copy of the Document, free of added material, which the 45977298Sobriengeneral network-using public has access to download anonymously at no 46077298Sobriencharge using public-standard network protocols. If you use the latter 46177298Sobrienoption, you must take reasonably prudent steps, when you begin 46277298Sobriendistribution of Opaque copies in quantity, to ensure that this 46377298SobrienTransparent copy will remain thus accessible at the stated location 46477298Sobrienuntil at least one year after the last time you distribute an Opaque 46577298Sobriencopy (directly or through your agents or retailers) of that edition to 46677298Sobrienthe public. 46777298Sobrien 46877298SobrienIt is requested, but not required, that you contact the authors of the 46977298SobrienDocument well before redistributing any large number of copies, to give 47077298Sobrienthem a chance to provide you with an updated version of the Document. 47177298Sobrien 47277298Sobrien 47377298Sobrien4. MODIFICATIONS 47477298Sobrien 47577298SobrienYou may copy and distribute a Modified Version of the Document under 47677298Sobrienthe conditions of sections 2 and 3 above, provided that you release 47777298Sobrienthe Modified Version under precisely this License, with the Modified 47877298SobrienVersion filling the role of the Document, thus licensing distribution 47977298Sobrienand modification of the Modified Version to whoever possesses a copy 48077298Sobrienof it. In addition, you must do these things in the Modified Version: 48177298Sobrien 48277298SobrienA. Use in the Title Page (and on the covers, if any) a title distinct 48377298Sobrien from that of the Document, and from those of previous versions 48477298Sobrien (which should, if there were any, be listed in the History section 48577298Sobrien of the Document). You may use the same title as a previous version 48677298Sobrien if the original publisher of that version gives permission. 48777298SobrienB. List on the Title Page, as authors, one or more persons or entities 48877298Sobrien responsible for authorship of the modifications in the Modified 48977298Sobrien Version, together with at least five of the principal authors of the 49077298Sobrien Document (all of its principal authors, if it has less than five). 49177298SobrienC. State on the Title page the name of the publisher of the 49277298Sobrien Modified Version, as the publisher. 49377298SobrienD. Preserve all the copyright notices of the Document. 49477298SobrienE. Add an appropriate copyright notice for your modifications 49577298Sobrien adjacent to the other copyright notices. 49677298SobrienF. Include, immediately after the copyright notices, a license notice 49777298Sobrien giving the public permission to use the Modified Version under the 49877298Sobrien terms of this License, in the form shown in the Addendum below. 49977298SobrienG. Preserve in that license notice the full lists of Invariant Sections 50077298Sobrien and required Cover Texts given in the Document's license notice. 50177298SobrienH. Include an unaltered copy of this License. 50277298SobrienI. Preserve the section entitled "History", and its title, and add to 50377298Sobrien it an item stating at least the title, year, new authors, and 50477298Sobrien publisher of the Modified Version as given on the Title Page. If 50577298Sobrien there is no section entitled "History" in the Document, create one 50677298Sobrien stating the title, year, authors, and publisher of the Document as 50777298Sobrien given on its Title Page, then add an item describing the Modified 50877298Sobrien Version as stated in the previous sentence. 50977298SobrienJ. Preserve the network location, if any, given in the Document for 51077298Sobrien public access to a Transparent copy of the Document, and likewise 51177298Sobrien the network locations given in the Document for previous versions 51277298Sobrien it was based on. These may be placed in the "History" section. 51377298Sobrien You may omit a network location for a work that was published at 51477298Sobrien least four years before the Document itself, or if the original 51577298Sobrien publisher of the version it refers to gives permission. 51677298SobrienK. In any section entitled "Acknowledgements" or "Dedications", 51777298Sobrien preserve the section's title, and preserve in the section all the 51877298Sobrien substance and tone of each of the contributor acknowledgements 51977298Sobrien and/or dedications given therein. 52077298SobrienL. Preserve all the Invariant Sections of the Document, 52177298Sobrien unaltered in their text and in their titles. Section numbers 52277298Sobrien or the equivalent are not considered part of the section titles. 52377298SobrienM. Delete any section entitled "Endorsements". Such a section 52477298Sobrien may not be included in the Modified Version. 52577298SobrienN. Do not retitle any existing section as "Endorsements" 52677298Sobrien or to conflict in title with any Invariant Section. 52777298Sobrien 52877298SobrienIf the Modified Version includes new front-matter sections or 52977298Sobrienappendices that qualify as Secondary Sections and contain no material 53077298Sobriencopied from the Document, you may at your option designate some or all 53177298Sobrienof these sections as invariant. To do this, add their titles to the 53277298Sobrienlist of Invariant Sections in the Modified Version's license notice. 53377298SobrienThese titles must be distinct from any other section titles. 53477298Sobrien 53577298SobrienYou may add a section entitled "Endorsements", provided it contains 53677298Sobriennothing but endorsements of your Modified Version by various 53777298Sobrienparties--for example, statements of peer review or that the text has 53877298Sobrienbeen approved by an organization as the authoritative definition of a 53977298Sobrienstandard. 54077298Sobrien 54177298SobrienYou may add a passage of up to five words as a Front-Cover Text, and a 54277298Sobrienpassage of up to 25 words as a Back-Cover Text, to the end of the list 54377298Sobrienof Cover Texts in the Modified Version. Only one passage of 54477298SobrienFront-Cover Text and one of Back-Cover Text may be added by (or 54577298Sobrienthrough arrangements made by) any one entity. If the Document already 54677298Sobrienincludes a cover text for the same cover, previously added by you or 54777298Sobrienby arrangement made by the same entity you are acting on behalf of, 54877298Sobrienyou may not add another; but you may replace the old one, on explicit 54977298Sobrienpermission from the previous publisher that added the old one. 55077298Sobrien 55177298SobrienThe author(s) and publisher(s) of the Document do not by this License 55277298Sobriengive permission to use their names for publicity for or to assert or 55377298Sobrienimply endorsement of any Modified Version. 55477298Sobrien 55577298Sobrien 55677298Sobrien5. COMBINING DOCUMENTS 55777298Sobrien 55877298SobrienYou may combine the Document with other documents released under this 55977298SobrienLicense, under the terms defined in section 4 above for modified 56077298Sobrienversions, provided that you include in the combination all of the 56177298SobrienInvariant Sections of all of the original documents, unmodified, and 56277298Sobrienlist them all as Invariant Sections of your combined work in its 56377298Sobrienlicense notice. 56477298Sobrien 56577298SobrienThe combined work need only contain one copy of this License, and 56677298Sobrienmultiple identical Invariant Sections may be replaced with a single 56777298Sobriencopy. If there are multiple Invariant Sections with the same name but 56877298Sobriendifferent contents, make the title of each such section unique by 56977298Sobrienadding at the end of it, in parentheses, the name of the original 57077298Sobrienauthor or publisher of that section if known, or else a unique number. 57177298SobrienMake the same adjustment to the section titles in the list of 57277298SobrienInvariant Sections in the license notice of the combined work. 57377298Sobrien 57477298SobrienIn the combination, you must combine any sections entitled "History" 57577298Sobrienin the various original documents, forming one section entitled 57677298Sobrien"History"; likewise combine any sections entitled "Acknowledgements", 57777298Sobrienand any sections entitled "Dedications". You must delete all sections 57877298Sobrienentitled "Endorsements." 57977298Sobrien 58077298Sobrien 58177298Sobrien6. COLLECTIONS OF DOCUMENTS 58277298Sobrien 58377298SobrienYou may make a collection consisting of the Document and other documents 58477298Sobrienreleased under this License, and replace the individual copies of this 58577298SobrienLicense in the various documents with a single copy that is included in 58677298Sobrienthe collection, provided that you follow the rules of this License for 58777298Sobrienverbatim copying of each of the documents in all other respects. 58877298Sobrien 58977298SobrienYou may extract a single document from such a collection, and distribute 59077298Sobrienit individually under this License, provided you insert a copy of this 59177298SobrienLicense into the extracted document, and follow this License in all 59277298Sobrienother respects regarding verbatim copying of that document. 59377298Sobrien 59477298Sobrien 59577298Sobrien7. AGGREGATION WITH INDEPENDENT WORKS 59677298Sobrien 59777298SobrienA compilation of the Document or its derivatives with other separate 59877298Sobrienand independent documents or works, in or on a volume of a storage or 59977298Sobriendistribution medium, does not as a whole count as a Modified Version 60077298Sobrienof the Document, provided no compilation copyright is claimed for the 60177298Sobriencompilation. Such a compilation is called an "aggregate", and this 60277298SobrienLicense does not apply to the other self-contained works thus compiled 60377298Sobrienwith the Document, on account of their being thus compiled, if they 60477298Sobrienare not themselves derivative works of the Document. 60577298Sobrien 60677298SobrienIf the Cover Text requirement of section 3 is applicable to these 60777298Sobriencopies of the Document, then if the Document is less than one quarter 60877298Sobrienof the entire aggregate, the Document's Cover Texts may be placed on 60977298Sobriencovers that surround only the Document within the aggregate. 61077298SobrienOtherwise they must appear on covers around the whole aggregate. 61177298Sobrien 61277298Sobrien 61377298Sobrien8. TRANSLATION 61477298Sobrien 61577298SobrienTranslation is considered a kind of modification, so you may 61677298Sobriendistribute translations of the Document under the terms of section 4. 61777298SobrienReplacing Invariant Sections with translations requires special 61877298Sobrienpermission from their copyright holders, but you may include 61977298Sobrientranslations of some or all Invariant Sections in addition to the 62077298Sobrienoriginal versions of these Invariant Sections. You may include a 62177298Sobrientranslation of this License provided that you also include the 62277298Sobrienoriginal English version of this License. In case of a disagreement 62377298Sobrienbetween the translation and the original English version of this 62477298SobrienLicense, the original English version will prevail. 62577298Sobrien 62677298Sobrien 62777298Sobrien9. TERMINATION 62877298Sobrien 62977298SobrienYou may not copy, modify, sublicense, or distribute the Document except 63077298Sobrienas expressly provided for under this License. Any other attempt to 63177298Sobriencopy, modify, sublicense or distribute the Document is void, and will 63277298Sobrienautomatically terminate your rights under this License. However, 63377298Sobrienparties who have received copies, or rights, from you under this 63477298SobrienLicense will not have their licenses terminated so long as such 63577298Sobrienparties remain in full compliance. 63677298Sobrien 63777298Sobrien 63877298Sobrien10. FUTURE REVISIONS OF THIS LICENSE 63977298Sobrien 64077298SobrienThe Free Software Foundation may publish new, revised versions 64177298Sobrienof the GNU Free Documentation License from time to time. Such new 64277298Sobrienversions will be similar in spirit to the present version, but may 64377298Sobriendiffer in detail to address new problems or concerns. See 64477298Sobrienhttp://www.gnu.org/copyleft/. 64577298Sobrien 64677298SobrienEach version of the License is given a distinguishing version number. 64777298SobrienIf the Document specifies that a particular numbered version of this 64877298SobrienLicense "or any later version" applies to it, you have the option of 64977298Sobrienfollowing the terms and conditions either of that specified version or 65077298Sobrienof any later version that has been published (not as a draft) by the 65177298SobrienFree Software Foundation. If the Document does not specify a version 65277298Sobriennumber of this License, you may choose any version ever published (not 65377298Sobrienas a draft) by the Free Software Foundation. 65477298Sobrien 65577298Sobrien 65677298SobrienADDENDUM: How to use this License for your documents 65777298Sobrien 65877298SobrienTo use this License in a document you have written, include a copy of 65977298Sobrienthe License in the document and put the following copyright and 66077298Sobrienlicense notices just after the title page: 66177298Sobrien 66277298Sobrien@smallexample 66377298Sobrien Copyright (c) YEAR YOUR NAME. 66477298Sobrien Permission is granted to copy, distribute and/or modify this document 66577298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 66677298Sobrien or any later version published by the Free Software Foundation; 66777298Sobrien with the Invariant Sections being LIST THEIR TITLES, with the 66877298Sobrien Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 66977298Sobrien A copy of the license is included in the section entitled "GNU 67077298Sobrien Free Documentation License". 67177298Sobrien@end smallexample 67277298Sobrien 67377298SobrienIf you have no Invariant Sections, write "with no Invariant Sections" 67477298Sobrieninstead of saying which ones are invariant. If you have no 67577298SobrienFront-Cover Texts, write "no Front-Cover Texts" instead of 67677298Sobrien"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. 67777298Sobrien 67877298SobrienIf your document contains nontrivial examples of program code, we 67977298Sobrienrecommend releasing these examples in parallel under your choice of 68077298Sobrienfree software license, such as the GNU General Public License, 68177298Sobriento permit their use in free software. 68277298Sobrien 68377298Sobrien@node Index, , GNU Free Documentation License , Top 68433965Sjdp@unnumbered Index 68533965Sjdp@printindex cp 68633965Sjdp 68733965Sjdp@tex 68833965Sjdp% I think something like @colophon should be in texinfo. In the 68933965Sjdp% meantime: 69033965Sjdp\long\def\colophon{\hbox to0pt{}\vfill 69133965Sjdp\centerline{The body of this manual is set in} 69233965Sjdp\centerline{\fontname\tenrm,} 69333965Sjdp\centerline{with headings in {\bf\fontname\tenbf}} 69433965Sjdp\centerline{and examples in {\tt\fontname\tentt}.} 69533965Sjdp\centerline{{\it\fontname\tenit\/} and} 69633965Sjdp\centerline{{\sl\fontname\tensl\/}} 69733965Sjdp\centerline{are used for emphasis.}\vfill} 69833965Sjdp\page\colophon 69933965Sjdp% Blame: doc@cygnus.com, 28mar91. 70033965Sjdp@end tex 70133965Sjdp 70233965Sjdp@contents 70333965Sjdp@bye 704