133965Sjdp\input texinfo 233965Sjdp@setfilename ldint.info 3218822Sdim@c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 4218822Sdim@c 2003, 2007 578828Sobrien@c Free Software Foundation, Inc. 633965Sjdp 733965Sjdp@ifinfo 833965Sjdp@format 933965SjdpSTART-INFO-DIR-ENTRY 1033965Sjdp* Ld-Internals: (ldint). The GNU linker internals. 1133965SjdpEND-INFO-DIR-ENTRY 1233965Sjdp@end format 1333965Sjdp@end ifinfo 1433965Sjdp 15218822Sdim@copying 1633965SjdpThis file documents the internals of the GNU linker ld. 1733965Sjdp 18218822SdimCopyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2007 1978828SobrienFree Software Foundation, Inc. 2033965SjdpContributed by Cygnus Support. 2133965Sjdp 22218822SdimPermission is granted to copy, distribute and/or modify this document 23218822Sdimunder the terms of the GNU Free Documentation License, Version 1.1 or 24218822Sdimany later version published by the Free Software Foundation; with the 25218822SdimInvariant Sections being ``GNU General Public License'' and ``Funding 26218822SdimFree Software'', the Front-Cover texts being (a) (see below), and with 27218822Sdimthe Back-Cover Texts being (b) (see below). A copy of the license is 28218822Sdimincluded in the section entitled ``GNU Free Documentation License''. 2933965Sjdp 30218822Sdim(a) The FSF's Front-Cover Text is: 3133965Sjdp 32218822Sdim A GNU Manual 3333965Sjdp 34218822Sdim(b) The FSF's Back-Cover Text is: 35218822Sdim 36218822Sdim You have freedom to copy and modify this GNU Manual, like GNU 37218822Sdim software. Copies published by the Free Software Foundation raise 38218822Sdim funds for GNU development. 39218822Sdim@end copying 40218822Sdim 4133965Sjdp@iftex 4233965Sjdp@finalout 4333965Sjdp@setchapternewpage off 4433965Sjdp@settitle GNU Linker Internals 4533965Sjdp@titlepage 4633965Sjdp@title{A guide to the internals of the GNU linker} 4760484Sobrien@author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie 4833965Sjdp@author Cygnus Support 4933965Sjdp@page 5033965Sjdp 5133965Sjdp@tex 5233965Sjdp\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 5377298Sobrien\xdef\manvers{2.10.91} % For use in headers, footers too 5433965Sjdp{\parskip=0pt 5533965Sjdp\hfill Cygnus Support\par 5633965Sjdp\hfill \manvers\par 5733965Sjdp\hfill \TeX{}info \texinfoversion\par 5833965Sjdp} 5933965Sjdp@end tex 6033965Sjdp 6133965Sjdp@vskip 0pt plus 1filll 6277298SobrienCopyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000 6360484SobrienFree Software Foundation, Inc. 6433965Sjdp 6577298Sobrien Permission is granted to copy, distribute and/or modify this document 6677298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 6777298Sobrien or any later version published by the Free Software Foundation; 6877298Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 6977298Sobrien Back-Cover Texts. A copy of the license is included in the 7077298Sobrien section entitled "GNU Free Documentation License". 7133965Sjdp 7233965Sjdp@end titlepage 7333965Sjdp@end iftex 7433965Sjdp 7533965Sjdp@node Top 7633965Sjdp@top 7733965Sjdp 7833965SjdpThis file documents the internals of the GNU linker @code{ld}. It is a 7933965Sjdpcollection of miscellaneous information with little form at this point. 8033965SjdpMostly, it is a repository into which you can put information about 8133965SjdpGNU @code{ld} as you discover it (or as you design changes to @code{ld}). 8233965Sjdp 8377298SobrienThis document is distributed under the terms of the GNU Free 8477298SobrienDocumentation License. A copy of the license is included in the 8577298Sobriensection entitled "GNU Free Documentation License". 8677298Sobrien 8733965Sjdp@menu 8833965Sjdp* README:: The README File 8933965Sjdp* Emulations:: How linker emulations are generated 9060484Sobrien* Emulation Walkthrough:: A Walkthrough of a Typical Emulation 9189857Sobrien* Architecture Specific:: Some Architecture Specific Notes 9277298Sobrien* GNU Free Documentation License:: GNU Free Documentation License 9333965Sjdp@end menu 9433965Sjdp 9533965Sjdp@node README 9633965Sjdp@chapter The @file{README} File 9733965Sjdp 9833965SjdpCheck the @file{README} file; it often has useful information that does not 9933965Sjdpappear anywhere else in the directory. 10033965Sjdp 10133965Sjdp@node Emulations 10233965Sjdp@chapter How linker emulations are generated 10333965Sjdp 10433965SjdpEach linker target has an @dfn{emulation}. The emulation includes the 10533965Sjdpdefault linker script, and certain emulations also modify certain types 10633965Sjdpof linker behaviour. 10733965Sjdp 10833965SjdpEmulations are created during the build process by the shell script 10933965Sjdp@file{genscripts.sh}. 11033965Sjdp 11133965SjdpThe @file{genscripts.sh} script starts by reading a file in the 11233965Sjdp@file{emulparams} directory. This is a shell script which sets various 11333965Sjdpshell variables used by @file{genscripts.sh} and the other shell scripts 11433965Sjdpit invokes. 11533965Sjdp 11633965SjdpThe @file{genscripts.sh} script will invoke a shell script in the 11733965Sjdp@file{scripttempl} directory in order to create default linker scripts 11833965Sjdpwritten in the linker command language. The @file{scripttempl} script 11933965Sjdpwill be invoked 5 (or, in some cases, 6) times, with different 12033965Sjdpassignments to shell variables, to create different default scripts. 12133965SjdpThe choice of script is made based on the command line options. 12233965Sjdp 12333965SjdpAfter creating the scripts, @file{genscripts.sh} will invoke yet another 12433965Sjdpshell script, this time in the @file{emultempl} directory. That shell 12533965Sjdpscript will create the emulation source file, which contains C code. 12633965SjdpThis C code permits the linker emulation to override various linker 12733965Sjdpbehaviours. Most targets use the generic emulation code, which is in 12833965Sjdp@file{emultempl/generic.em}. 12933965Sjdp 13033965SjdpTo summarize, @file{genscripts.sh} reads three shell scripts: an 13133965Sjdpemulation parameters script in the @file{emulparams} directory, a linker 13233965Sjdpscript generation script in the @file{scripttempl} directory, and an 13333965Sjdpemulation source file generation script in the @file{emultempl} 13433965Sjdpdirectory. 13533965Sjdp 13633965SjdpFor example, the Sun 4 linker sets up variables in 13733965Sjdp@file{emulparams/sun4.sh}, creates linker scripts using 13833965Sjdp@file{scripttempl/aout.sc}, and creates the emulation code using 13933965Sjdp@file{emultempl/sunos.em}. 14033965Sjdp 14133965SjdpNote that the linker can support several emulations simultaneously, 14233965Sjdpdepending upon how it is configured. An emulation can be selected with 14333965Sjdpthe @code{-m} option. The @code{-V} option will list all supported 14433965Sjdpemulations. 14533965Sjdp 14633965Sjdp@menu 14733965Sjdp* emulation parameters:: @file{emulparams} scripts 14833965Sjdp* linker scripts:: @file{scripttempl} scripts 14933965Sjdp* linker emulations:: @file{emultempl} scripts 15033965Sjdp@end menu 15133965Sjdp 15233965Sjdp@node emulation parameters 15333965Sjdp@section @file{emulparams} scripts 15433965Sjdp 15533965SjdpEach target selects a particular file in the @file{emulparams} directory 15633965Sjdpby setting the shell variable @code{targ_emul} in @file{configure.tgt}. 15733965SjdpThis shell variable is used by the @file{configure} script to control 15833965Sjdpbuilding an emulation source file. 15933965Sjdp 16033965SjdpCertain conventions are enforced. Suppose the @code{targ_emul} variable 16133965Sjdpis set to @var{emul} in @file{configure.tgt}. The name of the emulation 16233965Sjdpshell script will be @file{emulparams/@var{emul}.sh}. The 16333965Sjdp@file{Makefile} must have a target named @file{e@var{emul}.c}; this 16433965Sjdptarget must depend upon @file{emulparams/@var{emul}.sh}, as well as the 16533965Sjdpappropriate scripts in the @file{scripttempl} and @file{emultempl} 16633965Sjdpdirectories. The @file{Makefile} target must invoke @code{GENSCRIPTS} 16733965Sjdpwith two arguments: @var{emul}, and the value of the make variable 16833965Sjdp@code{tdir_@var{emul}}. The value of the latter variable will be set by 16933965Sjdpthe @file{configure} script, and is used to set the default target 17033965Sjdpdirectory to search. 17133965Sjdp 17233965SjdpBy convention, the @file{emulparams/@var{emul}.sh} shell script should 17333965Sjdponly set shell variables. It may set shell variables which are to be 17433965Sjdpinterpreted by the @file{scripttempl} and the @file{emultempl} scripts. 17533965SjdpCertain shell variables are interpreted directly by the 17633965Sjdp@file{genscripts.sh} script. 17733965Sjdp 17833965SjdpHere is a list of shell variables interpreted by @file{genscripts.sh}, 17933965Sjdpas well as some conventional shell variables interpreted by the 18033965Sjdp@file{scripttempl} and @file{emultempl} scripts. 18133965Sjdp 18233965Sjdp@table @code 18333965Sjdp@item SCRIPT_NAME 18433965SjdpThis is the name of the @file{scripttempl} script to use. If 18533965Sjdp@code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use 186218822Sdimthe script @file{scripttempl/@var{script}.sc}. 18733965Sjdp 18833965Sjdp@item TEMPLATE_NAME 189218822SdimThis is the name of the @file{emultempl} script to use. If 19033965Sjdp@code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will 19133965Sjdpuse the script @file{emultempl/@var{template}.em}. If this variable is 19233965Sjdpnot set, the default value is @samp{generic}. 19333965Sjdp 19433965Sjdp@item GENERATE_SHLIB_SCRIPT 19533965SjdpIf this is set to a nonempty string, @file{genscripts.sh} will invoke 19633965Sjdpthe @file{scripttempl} script an extra time to create a shared library 19733965Sjdpscript. @ref{linker scripts}. 19833965Sjdp 19933965Sjdp@item OUTPUT_FORMAT 20033965SjdpThis is normally set to indicate the BFD output format use (e.g., 20133965Sjdp@samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally 20233965Sjdpuse it in an @code{OUTPUT_FORMAT} expression in the linker script. 20333965Sjdp 20433965Sjdp@item ARCH 20533965SjdpThis is normally set to indicate the architecture to use (e.g., 20633965Sjdp@samp{sparc}). The @file{scripttempl} script will normally use it in an 20733965Sjdp@code{OUTPUT_ARCH} expression in the linker script. 20833965Sjdp 20933965Sjdp@item ENTRY 21033965SjdpSome @file{scripttempl} scripts use this to set the entry address, in an 21133965Sjdp@code{ENTRY} expression in the linker script. 21233965Sjdp 21333965Sjdp@item TEXT_START_ADDR 21433965SjdpSome @file{scripttempl} scripts use this to set the start address of the 21533965Sjdp@samp{.text} section. 21633965Sjdp 21733965Sjdp@item NONPAGED_TEXT_START_ADDR 21833965SjdpIf this is defined, the @file{genscripts.sh} script sets 21933965Sjdp@code{TEXT_START_ADDR} to its value before running the 22033965Sjdp@file{scripttempl} script for the @code{-n} and @code{-N} options 22133965Sjdp(@pxref{linker scripts}). 22233965Sjdp 22333965Sjdp@item SEGMENT_SIZE 22433965SjdpThe @file{genscripts.sh} script uses this to set the default value of 22533965Sjdp@code{DATA_ALIGNMENT} when running the @file{scripttempl} script. 22633965Sjdp 22733965Sjdp@item TARGET_PAGE_SIZE 22833965SjdpIf @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script 22933965Sjdpuses this to define it. 23060484Sobrien 23160484Sobrien@item ALIGNMENT 23260484SobrienSome @file{scripttempl} scripts set this to a number to pass to 23360484Sobrien@code{ALIGN} to set the required alignment for the @code{end} symbol. 23433965Sjdp@end table 23533965Sjdp 23633965Sjdp@node linker scripts 23733965Sjdp@section @file{scripttempl} scripts 23833965Sjdp 23933965SjdpEach linker target uses a @file{scripttempl} script to generate the 24033965Sjdpdefault linker scripts. The name of the @file{scripttempl} script is 24133965Sjdpset by the @code{SCRIPT_NAME} variable in the @file{emulparams} script. 24233965SjdpIf @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will 24333965Sjdpinvoke @file{scripttempl/@var{script}.sc}. 24433965Sjdp 24533965SjdpThe @file{genscripts.sh} script will invoke the @file{scripttempl} 24689857Sobrienscript 5 to 8 times. Each time it will set the shell variable 24733965Sjdp@code{LD_FLAG} to a different value. When the linker is run, the 24833965Sjdpoptions used will direct it to select a particular script. (Script 24933965Sjdpselection is controlled by the @code{get_script} emulation entry point; 25033965Sjdpthis describes the conventional behaviour). 25133965Sjdp 25233965SjdpThe @file{scripttempl} script should just write a linker script, written 25333965Sjdpin the linker command language, to standard output. If the emulation 25433965Sjdpname--the name of the @file{emulparams} file without the @file{.sc} 25533965Sjdpextension--is @var{emul}, then the output will be directed to 25633965Sjdp@file{ldscripts/@var{emul}.@var{extension}} in the build directory, 25733965Sjdpwhere @var{extension} changes each time the @file{scripttempl} script is 25833965Sjdpinvoked. 25933965Sjdp 26033965SjdpHere is the list of values assigned to @code{LD_FLAG}. 26133965Sjdp 26233965Sjdp@table @code 26333965Sjdp@item (empty) 26433965SjdpThe script generated is used by default (when none of the following 26533965Sjdpcases apply). The output has an extension of @file{.x}. 26633965Sjdp@item n 26733965SjdpThe script generated is used when the linker is invoked with the 26833965Sjdp@code{-n} option. The output has an extension of @file{.xn}. 26933965Sjdp@item N 27033965SjdpThe script generated is used when the linker is invoked with the 27133965Sjdp@code{-N} option. The output has an extension of @file{.xbn}. 27233965Sjdp@item r 27333965SjdpThe script generated is used when the linker is invoked with the 27433965Sjdp@code{-r} option. The output has an extension of @file{.xr}. 27533965Sjdp@item u 27633965SjdpThe script generated is used when the linker is invoked with the 27733965Sjdp@code{-Ur} option. The output has an extension of @file{.xu}. 27833965Sjdp@item shared 27933965SjdpThe @file{scripttempl} script is only invoked with @code{LD_FLAG} set to 28033965Sjdpthis value if @code{GENERATE_SHLIB_SCRIPT} is defined in the 28133965Sjdp@file{emulparams} file. The @file{emultempl} script must arrange to use 28233965Sjdpthis script at the appropriate time, normally when the linker is invoked 28333965Sjdpwith the @code{-shared} option. The output has an extension of 28433965Sjdp@file{.xs}. 28589857Sobrien@item c 28689857SobrienThe @file{scripttempl} script is only invoked with @code{LD_FLAG} set to 28789857Sobrienthis value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the 28889857Sobrien@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The 28989857Sobrien@file{emultempl} script must arrange to use this script at the appropriate 29089857Sobrientime, normally when the linker is invoked with the @code{-z combreloc} 29189857Sobrienoption. The output has an extension of 29289857Sobrien@file{.xc}. 29389857Sobrien@item cshared 29489857SobrienThe @file{scripttempl} script is only invoked with @code{LD_FLAG} set to 29589857Sobrienthis value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the 29689857Sobrien@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and 297218822Sdim@code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparams} file. 29889857SobrienThe @file{emultempl} script must arrange to use this script at the 29989857Sobrienappropriate time, normally when the linker is invoked with the @code{-shared 30089857Sobrien-z combreloc} option. The output has an extension of @file{.xsc}. 30133965Sjdp@end table 30233965Sjdp 30333965SjdpBesides the shell variables set by the @file{emulparams} script, and the 30433965Sjdp@code{LD_FLAG} variable, the @file{genscripts.sh} script will set 30533965Sjdpcertain variables for each run of the @file{scripttempl} script. 30633965Sjdp 30733965Sjdp@table @code 30833965Sjdp@item RELOCATING 30933965SjdpThis will be set to a non-empty string when the linker is doing a final 31033965Sjdprelocation (e.g., all scripts other than @code{-r} and @code{-Ur}). 31133965Sjdp 31233965Sjdp@item CONSTRUCTING 31333965SjdpThis will be set to a non-empty string when the linker is building 31433965Sjdpglobal constructor and destructor tables (e.g., all scripts other than 31533965Sjdp@code{-r}). 31633965Sjdp 31733965Sjdp@item DATA_ALIGNMENT 31833965SjdpThis will be set to an @code{ALIGN} expression when the output should be 31933965Sjdppage aligned, or to @samp{.} when generating the @code{-N} script. 32033965Sjdp 32133965Sjdp@item CREATE_SHLIB 32233965SjdpThis will be set to a non-empty string when generating a @code{-shared} 32333965Sjdpscript. 32489857Sobrien 32589857Sobrien@item COMBRELOC 32689857SobrienThis will be set to a non-empty string when generating @code{-z combreloc} 32789857Sobrienscripts to a temporary file name which can be used during script generation. 32833965Sjdp@end table 32933965Sjdp 33033965SjdpThe conventional way to write a @file{scripttempl} script is to first 33133965Sjdpset a few shell variables, and then write out a linker script using 33233965Sjdp@code{cat} with a here document. The linker script will use variable 33333965Sjdpsubstitutions, based on the above variables and those set in the 33433965Sjdp@file{emulparams} script, to control its behaviour. 33533965Sjdp 33633965SjdpWhen there are parts of the @file{scripttempl} script which should only 33733965Sjdpbe run when doing a final relocation, they should be enclosed within a 33833965Sjdpvariable substitution based on @code{RELOCATING}. For example, on many 33933965Sjdptargets special symbols such as @code{_end} should be defined when doing 34033965Sjdpa final link. Naturally, those symbols should not be defined when doing 341130561Sobriena relocatable link using @code{-r}. The @file{scripttempl} script 34233965Sjdpcould use a construct like this to define those symbols: 34333965Sjdp@smallexample 34433965Sjdp $@{RELOCATING+ _end = .;@} 34533965Sjdp@end smallexample 34633965SjdpThis will do the symbol assignment only if the @code{RELOCATING} 34733965Sjdpvariable is defined. 34833965Sjdp 34933965SjdpThe basic job of the linker script is to put the sections in the correct 35033965Sjdporder, and at the correct memory addresses. For some targets, the 35133965Sjdplinker script may have to do some other operations. 35233965Sjdp 35333965SjdpFor example, on most MIPS platforms, the linker is responsible for 35433965Sjdpdefining the special symbol @code{_gp}, used to initialize the 35533965Sjdp@code{$gp} register. It must be set to the start of the small data 35633965Sjdpsection plus @code{0x8000}. Naturally, it should only be defined when 35733965Sjdpdoing a final relocation. This will typically be done like this: 35833965Sjdp@smallexample 35933965Sjdp $@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@} 36033965Sjdp@end smallexample 36133965SjdpThis line would appear just before the sections which compose the small 36233965Sjdpdata section (@samp{.sdata}, @samp{.sbss}). All those sections would be 36333965Sjdpcontiguous in memory. 36433965Sjdp 36533965SjdpMany COFF systems build constructor tables in the linker script. The 36633965Sjdpcompiler will arrange to output the address of each global constructor 36733965Sjdpin a @samp{.ctor} section, and the address of each global destructor in 36833965Sjdpa @samp{.dtor} section (this is done by defining 36933965Sjdp@code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the 37033965Sjdp@code{gcc} configuration files). The @code{gcc} runtime support 37133965Sjdproutines expect the constructor table to be named @code{__CTOR_LIST__}. 37233965SjdpThey expect it to be a list of words, with the first word being the 37333965Sjdpcount of the number of entries. There should be a trailing zero word. 37433965Sjdp(Actually, the count may be -1 if the trailing word is present, and the 37533965Sjdptrailing word may be omitted if the count is correct, but, as the 37633965Sjdp@code{gcc} behaviour has changed slightly over the years, it is safest 37733965Sjdpto provide both). Here is a typical way that might be handled in a 37833965Sjdp@file{scripttempl} file. 37933965Sjdp@smallexample 38033965Sjdp $@{CONSTRUCTING+ __CTOR_LIST__ = .;@} 38133965Sjdp $@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@} 38233965Sjdp $@{CONSTRUCTING+ *(.ctors)@} 38333965Sjdp $@{CONSTRUCTING+ LONG(0)@} 38433965Sjdp $@{CONSTRUCTING+ __CTOR_END__ = .;@} 38533965Sjdp $@{CONSTRUCTING+ __DTOR_LIST__ = .;@} 38633965Sjdp $@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@} 38733965Sjdp $@{CONSTRUCTING+ *(.dtors)@} 38833965Sjdp $@{CONSTRUCTING+ LONG(0)@} 38933965Sjdp $@{CONSTRUCTING+ __DTOR_END__ = .;@} 39033965Sjdp@end smallexample 39133965SjdpThe use of @code{CONSTRUCTING} ensures that these linker script commands 39233965Sjdpwill only appear when the linker is supposed to be building the 39333965Sjdpconstructor and destructor tables. This example is written for a target 39433965Sjdpwhich uses 4 byte pointers. 39533965Sjdp 39633965SjdpEmbedded systems often need to set a stack address. This is normally 39733965Sjdpbest done by using the @code{PROVIDE} construct with a default stack 39833965Sjdpaddress. This permits the user to easily override the stack address 39933965Sjdpusing the @code{--defsym} option. Here is an example: 40033965Sjdp@smallexample 40133965Sjdp $@{RELOCATING+ PROVIDE (__stack = 0x80000000);@} 40233965Sjdp@end smallexample 40333965SjdpThe value of the symbol @code{__stack} would then be used in the startup 40433965Sjdpcode to initialize the stack pointer. 40533965Sjdp 40633965Sjdp@node linker emulations 40733965Sjdp@section @file{emultempl} scripts 40833965Sjdp 40933965SjdpEach linker target uses an @file{emultempl} script to generate the 41033965Sjdpemulation code. The name of the @file{emultempl} script is set by the 41133965Sjdp@code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the 41233965Sjdp@code{TEMPLATE_NAME} variable is not set, the default is 41333965Sjdp@samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template}, 41433965Sjdp@file{genscripts.sh} will use @file{emultempl/@var{template}.em}. 41533965Sjdp 41633965SjdpMost targets use the generic @file{emultempl} script, 41733965Sjdp@file{emultempl/generic.em}. A different @file{emultempl} script is 41833965Sjdponly needed if the linker must support unusual actions, such as linking 41933965Sjdpagainst shared libraries. 42033965Sjdp 42133965SjdpThe @file{emultempl} script is normally written as a simple invocation 42233965Sjdpof @code{cat} with a here document. The document will use a few 42333965Sjdpvariable substitutions. Typically each function names uses a 42433965Sjdpsubstitution involving @code{EMULATION_NAME}, for ease of debugging when 42533965Sjdpthe linker supports multiple emulations. 42633965Sjdp 42733965SjdpEvery function and variable in the emitted file should be static. The 42833965Sjdponly globally visible object must be named 42933965Sjdp@code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is 43033965Sjdpthe name of the emulation set in @file{configure.tgt} (this is also the 43133965Sjdpname of the @file{emulparams} file without the @file{.sh} extension). 43233965SjdpThe @file{genscripts.sh} script will set the shell variable 43333965Sjdp@code{EMULATION_NAME} before invoking the @file{emultempl} script. 43433965Sjdp 43533965SjdpThe @code{ld_@var{EMULATION_NAME}_emulation} variable must be a 43633965Sjdp@code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}. 43733965SjdpIt defines a set of function pointers which are invoked by the linker, 43833965Sjdpas well as strings for the emulation name (normally set from the shell 43933965Sjdpvariable @code{EMULATION_NAME} and the default BFD target name (normally 44033965Sjdpset from the shell variable @code{OUTPUT_FORMAT} which is normally set 44133965Sjdpby the @file{emulparams} file). 44233965Sjdp 44333965SjdpThe @file{genscripts.sh} script will set the shell variable 44433965Sjdp@code{COMPILE_IN} when it invokes the @file{emultempl} script for the 44533965Sjdpdefault emulation. In this case, the @file{emultempl} script should 44633965Sjdpinclude the linker scripts directly, and return them from the 44733965Sjdp@code{get_scripts} entry point. When the emulation is not the default, 44833965Sjdpthe @code{get_scripts} entry point should just return a file name. See 44933965Sjdp@file{emultempl/generic.em} for an example of how this is done. 45033965Sjdp 45133965SjdpAt some point, the linker emulation entry points should be documented. 45233965Sjdp 45360484Sobrien@node Emulation Walkthrough 45460484Sobrien@chapter A Walkthrough of a Typical Emulation 45560484Sobrien 45660484SobrienThis chapter is to help people who are new to the way emulations 45760484Sobrieninteract with the linker, or who are suddenly thrust into the position 45860484Sobrienof having to work with existing emulations. It will discuss the files 45960484Sobrienyou need to be aware of. It will tell you when the given "hooks" in 46060484Sobrienthe emulation will be called. It will, hopefully, give you enough 46160484Sobrieninformation about when and how things happen that you'll be able to 46260484Sobrienget by. As always, the source is the definitive reference to this. 46360484Sobrien 46460484SobrienThe starting point for the linker is in @file{ldmain.c} where 46560484Sobrien@code{main} is defined. The bulk of the code that's emulation 46660484Sobrienspecific will initially be in @code{emultempl/@var{emulation}.em} but 46760484Sobrienwill end up in @code{e@var{emulation}.c} when the build is done. 46860484SobrienMost of the work to select and interface with emulations is in 46960484Sobrien@code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h} 47060484Sobriendefines the @code{ld_emulation_xfer_struct} structure your emulation 47160484Sobrienexports. 47260484Sobrien 47360484SobrienYour emulation file exports a symbol 47460484Sobrien@code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is 47560484Sobrienselected (it usually is, since usually there's only one), 47660484Sobrien@code{ldemul.c} sets the variable @var{ld_emulation} to point to it. 47760484Sobrien@code{ldemul.c} also defines a number of API functions that interface 47860484Sobriento your emulation, like @code{ldemul_after_parse} which simply calls 47960484Sobrienyour @code{ld_@var{EMULATION}_emulation.after_parse} function. For 48060484Sobrienthe rest of this section, the functions will be mentioned, but you 48160484Sobrienshould assume the indirect reference to your emulation also. 48260484Sobrien 48360484SobrienWe will also skip or gloss over parts of the link process that don't 48460484Sobrienrelate to emulations, like setting up internationalization. 48560484Sobrien 48660484SobrienAfter initialization, @code{main} selects an emulation by pre-scanning 48760484Sobrienthe command line arguments. It calls @code{ldemul_choose_target} to 48860484Sobrienchoose a target. If you set @code{choose_target} to 48960484Sobrien@code{ldemul_default_target}, it picks your @code{target_name} by 49060484Sobriendefault. 49160484Sobrien 49260484Sobrien@code{main} calls @code{ldemul_before_parse}, then @code{parse_args}. 49360484Sobrien@code{parse_args} calls @code{ldemul_parse_args} for each arg, which 49460484Sobrienmust update the @code{getopt} globals if it recognizes the argument. 49560484SobrienIf the emulation doesn't recognize it, then parse_args checks to see 49660484Sobrienif it recognizes it. 49760484Sobrien 49860484SobrienNow that the emulation has had access to all its command-line options, 49960484Sobrien@code{main} calls @code{ldemul_set_symbols}. This can be used for any 50060484Sobrieninitialization that may be affected by options. It is also supposed 50160484Sobriento set up any variables needed by the emulation script. 50260484Sobrien 50360484Sobrien@code{main} now calls @code{ldemul_get_script} to get the emulation 50460484Sobrienscript to use (based on arguments, no doubt, @pxref{Emulations}) and 50560484Sobrienruns it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or 50660484Sobrien@code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB} 50760484Sobriencommands. It may call @code{ldemul_unrecognized_file} if you asked 50860484Sobrienthe linker to link a file it doesn't recognize. It will call 50960484Sobrien@code{ldemul_recognized_file} for each file it does recognize, in case 51060484Sobrienthe emulation wants to handle some files specially. All the while, 51160484Sobrienit's loading the files (possibly calling 51260484Sobrien@code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's 51360484Sobriendone reading the script, @code{main} calls @code{ldemul_after_parse}. 51460484SobrienUse the after-parse hook to set up anything that depends on stuff the 51560484Sobrienscript might have set up, like the entry point. 51660484Sobrien 51760484Sobrien@code{main} next calls @code{lang_process} in @code{ldlang.c}. This 51860484Sobrienappears to be the main core of the linking itself, as far as emulation 51960484Sobrienhooks are concerned(*). It first opens the output file's BFD, calling 52060484Sobrien@code{ldemul_set_output_arch}, and calls 52160484Sobrien@code{ldemul_create_output_section_statements} in case you need to use 52260484Sobrienother means to find or create object files (i.e. shared libraries 52360484Sobrienfound on a path, or fake stub objects). Despite the name, nobody 52460484Sobriencreates output sections here. 52560484Sobrien 52660484Sobrien(*) In most cases, the BFD library does the bulk of the actual 52760484Sobrienlinking, handling symbol tables, symbol resolution, relocations, and 52860484Sobrienbuilding the final output file. See the BFD reference for all the 52960484Sobriendetails. Your emulation is usually concerned more with managing 53060484Sobrienthings at the file and section level, like "put this here, add this 53160484Sobriensection", etc. 53260484Sobrien 53360484SobrienNext, the objects to be linked are opened and BFDs created for them, 53460484Sobrienand @code{ldemul_after_open} is called. At this point, you have all 53560484Sobrienthe objects and symbols loaded, but none of the data has been placed 53660484Sobrienyet. 53760484Sobrien 53860484SobrienNext comes the Big Linking Thingy (except for the parts BFD does). 53960484SobrienAll input sections are mapped to output sections according to the 54060484Sobrienscript. If a section doesn't get mapped by default, 54160484Sobrien@code{ldemul_place_orphan} will get called to figure out where it goes. 54260484SobrienNext it figures out the offsets for each section, calling 54360484Sobrien@code{ldemul_before_allocation} before and 54460484Sobrien@code{ldemul_after_allocation} after deciding where each input section 54560484Sobrienends up in the output sections. 54660484Sobrien 54760484SobrienThe last part of @code{lang_process} is to figure out all the symbols' 54860484Sobrienvalues. After assigning final values to the symbols, 54960484Sobrien@code{ldemul_finish} is called, and after that, any undefined symbols 55060484Sobrienare turned into fatal errors. 55160484Sobrien 55260484SobrienOK, back to @code{main}, which calls @code{ldwrite} in 55360484Sobrien@file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does 55460484Sobrienall the relocation fixups and writes the output bfd to disk, and we're 55560484Sobriendone. 55660484Sobrien 55760484SobrienIn summary, 55860484Sobrien 55960484Sobrien@itemize @bullet 56060484Sobrien 56160484Sobrien@item @code{main()} in @file{ldmain.c} 56260484Sobrien@item @file{emultempl/@var{EMULATION}.em} has your code 56360484Sobrien@item @code{ldemul_choose_target} (defaults to your @code{target_name}) 56460484Sobrien@item @code{ldemul_before_parse} 56560484Sobrien@item Parse argv, calls @code{ldemul_parse_args} for each 56660484Sobrien@item @code{ldemul_set_symbols} 56760484Sobrien@item @code{ldemul_get_script} 56860484Sobrien@item parse script 56960484Sobrien 57060484Sobrien@itemize @bullet 57160484Sobrien@item may call @code{ldemul_hll} or @code{ldemul_syslib} 57260484Sobrien@item may call @code{ldemul_open_dynamic_archive} 57360484Sobrien@end itemize 57460484Sobrien 57560484Sobrien@item @code{ldemul_after_parse} 57660484Sobrien@item @code{lang_process()} in @file{ldlang.c} 57760484Sobrien 57860484Sobrien@itemize @bullet 57960484Sobrien@item create @code{output_bfd} 58060484Sobrien@item @code{ldemul_set_output_arch} 58160484Sobrien@item @code{ldemul_create_output_section_statements} 58260484Sobrien@item read objects, create input bfds - all symbols exist, but have no values 58360484Sobrien@item may call @code{ldemul_unrecognized_file} 58460484Sobrien@item will call @code{ldemul_recognized_file} 58560484Sobrien@item @code{ldemul_after_open} 58660484Sobrien@item map input sections to output sections 58760484Sobrien@item may call @code{ldemul_place_orphan} for remaining sections 58860484Sobrien@item @code{ldemul_before_allocation} 58960484Sobrien@item gives input sections offsets into output sections, places output sections 59060484Sobrien@item @code{ldemul_after_allocation} - section addresses valid 59160484Sobrien@item assigns values to symbols 59260484Sobrien@item @code{ldemul_finish} - symbol values valid 59360484Sobrien@end itemize 59460484Sobrien 59560484Sobrien@item output bfd is written to disk 59660484Sobrien 59760484Sobrien@end itemize 59860484Sobrien 59989857Sobrien@node Architecture Specific 60089857Sobrien@chapter Some Architecture Specific Notes 60189857Sobrien 60289857SobrienThis is the place for notes on the behavior of @code{ld} on 60389857Sobrienspecific platforms. Currently, only Intel x86 is documented (and 60489857Sobrienof that, only the auto-import behavior for DLLs). 60589857Sobrien 60689857Sobrien@menu 60789857Sobrien* ix86:: Intel x86 60889857Sobrien@end menu 60989857Sobrien 61089857Sobrien@node ix86 61189857Sobrien@section Intel x86 61289857Sobrien 61389857Sobrien@table @emph 61489857Sobrien@code{ld} can create DLLs that operate with various runtimes available 61589857Sobrienon a common x86 operating system. These runtimes include native (using 61689857Sobrienthe mingw "platform"), cygwin, and pw. 61789857Sobrien 61889857Sobrien@item auto-import from DLLs 61989857Sobrien@enumerate 62089857Sobrien@item 62189857SobrienWith this feature on, DLL clients can import variables from DLL 62289857Sobrienwithout any concern from their side (for example, without any source 62389857Sobriencode modifications). Auto-import can be enabled using the 62489857Sobrien@code{--enable-auto-import} flag, or disabled via the 62589857Sobrien@code{--disable-auto-import} flag. Auto-import is disabled by default. 62689857Sobrien 62789857Sobrien@item 62889857SobrienThis is done completely in bounds of the PE specification (to be fair, 62989857Sobrienthere's a minor violation of the spec at one point, but in practice 63089857Sobrienauto-import works on all known variants of that common x86 operating 63189857Sobriensystem) So, the resulting DLL can be used with any other PE 63289857Sobriencompiler/linker. 63389857Sobrien 63489857Sobrien@item 63589857SobrienAuto-import is fully compatible with standard import method, in which 63689857Sobrienvariables are decorated using attribute modifiers. Libraries of either 63789857Sobrientype may be mixed together. 63889857Sobrien 63989857Sobrien@item 64089857SobrienOverhead (space): 8 bytes per imported symbol, plus 20 for each 64189857Sobrienreference to it; Overhead (load time): negligible; Overhead 64289857Sobrien(virtual/physical memory): should be less than effect of DLL 64389857Sobrienrelocation. 64489857Sobrien@end enumerate 64589857Sobrien 64689857SobrienMotivation 64789857Sobrien 64889857SobrienThe obvious and only way to get rid of dllimport insanity is 64989857Sobriento make client access variable directly in the DLL, bypassing 65089857Sobrienthe extra dereference imposed by ordinary DLL runtime linking. 651218822SdimI.e., whenever client contains something like 65289857Sobrien 65389857Sobrien@code{mov dll_var,%eax,} 65489857Sobrien 65589857Sobrienaddress of dll_var in the command should be relocated to point 65689857Sobrieninto loaded DLL. The aim is to make OS loader do so, and than 65789857Sobrienmake ld help with that. Import section of PE made following 65889857Sobrienway: there's a vector of structures each describing imports 65989857Sobrienfrom particular DLL. Each such structure points to two other 660218822Sdimparallel vectors: one holding imported names, and one which 66189857Sobrienwill hold address of corresponding imported name. So, the 66289857Sobriensolution is de-vectorize these structures, making import 66389857Sobrienlocations be sparse and pointing directly into code. 66489857Sobrien 66589857SobrienImplementation 66689857Sobrien 66789857SobrienFor each reference of data symbol to be imported from DLL (to 66889857Sobrienset of which belong symbols with name <sym>, if __imp_<sym> is 66989857Sobrienfound in implib), the import fixup entry is generated. That 67089857Sobrienentry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3 67189857Sobriensubsection. Each fixup entry contains pointer to symbol's address 67289857Sobrienwithin .text section (marked with __fuN_<sym> symbol, where N is 67389857Sobrieninteger), pointer to DLL name (so, DLL name is referenced by 67489857Sobrienmultiple entries), and pointer to symbol name thunk. Symbol name 67589857Sobrienthunk is singleton vector (__nm_th_<symbol>) pointing to 67689857SobrienIMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing 67789857Sobrienimported name. Here comes that "om the edge" problem mentioned above: 67889857SobrienPE specification rambles that name vector (OriginalFirstThunk) should 67989857Sobrienrun in parallel with addresses vector (FirstThunk), i.e. that they 68089857Sobrienshould have same number of elements and terminated with zero. We violate 68189857Sobrienthis, since FirstThunk points directly into machine code. But in 68289857Sobrienpractice, OS loader implemented the sane way: it goes thru 68389857SobrienOriginalFirstThunk and puts addresses to FirstThunk, not something 68489857Sobrienelse. It once again should be noted that dll and symbol name 68589857Sobrienstructures are reused across fixup entries and should be there 68689857Sobrienanyway to support standard import stuff, so sustained overhead is 68789857Sobrien20 bytes per reference. Other question is whether having several 68889857SobrienIMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes, 68989857Sobrienit is done even by native compiler/linker (libth32's functions are in 69089857Sobrienfact resident in windows9x kernel32.dll, so if you use it, you have 69189857Sobrientwo IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is 69289857Sobrienwhether referencing the same PE structures several times is valid. 69389857SobrienThe answer is why not, prohibiting that (detecting violation) would 69489857Sobrienrequire more work on behalf of loader than not doing it. 69589857Sobrien 69689857Sobrien@end table 69789857Sobrien 69877298Sobrien@node GNU Free Documentation License 69977298Sobrien@chapter GNU Free Documentation License 70077298Sobrien 70177298Sobrien GNU Free Documentation License 70277298Sobrien 70377298Sobrien Version 1.1, March 2000 70477298Sobrien 70577298Sobrien Copyright (C) 2000 Free Software Foundation, Inc. 706218822Sdim 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 70777298Sobrien 70877298Sobrien Everyone is permitted to copy and distribute verbatim copies 70977298Sobrien of this license document, but changing it is not allowed. 71077298Sobrien 71177298Sobrien 71277298Sobrien0. PREAMBLE 71377298Sobrien 71477298SobrienThe purpose of this License is to make a manual, textbook, or other 71577298Sobrienwritten document "free" in the sense of freedom: to assure everyone 71677298Sobrienthe effective freedom to copy and redistribute it, with or without 71777298Sobrienmodifying it, either commercially or noncommercially. Secondarily, 71877298Sobrienthis License preserves for the author and publisher a way to get 71977298Sobriencredit for their work, while not being considered responsible for 72077298Sobrienmodifications made by others. 72177298Sobrien 72277298SobrienThis License is a kind of "copyleft", which means that derivative 72377298Sobrienworks of the document must themselves be free in the same sense. It 72477298Sobriencomplements the GNU General Public License, which is a copyleft 72577298Sobrienlicense designed for free software. 72677298Sobrien 72777298SobrienWe have designed this License in order to use it for manuals for free 72877298Sobriensoftware, because free software needs free documentation: a free 72977298Sobrienprogram should come with manuals providing the same freedoms that the 73077298Sobriensoftware does. But this License is not limited to software manuals; 73177298Sobrienit can be used for any textual work, regardless of subject matter or 73277298Sobrienwhether it is published as a printed book. We recommend this License 73377298Sobrienprincipally for works whose purpose is instruction or reference. 73477298Sobrien 73577298Sobrien 73677298Sobrien1. APPLICABILITY AND DEFINITIONS 73777298Sobrien 73877298SobrienThis License applies to any manual or other work that contains a 73977298Sobriennotice placed by the copyright holder saying it can be distributed 74077298Sobrienunder the terms of this License. The "Document", below, refers to any 74177298Sobriensuch manual or work. Any member of the public is a licensee, and is 74277298Sobrienaddressed as "you". 74377298Sobrien 74477298SobrienA "Modified Version" of the Document means any work containing the 74577298SobrienDocument or a portion of it, either copied verbatim, or with 74677298Sobrienmodifications and/or translated into another language. 74777298Sobrien 74877298SobrienA "Secondary Section" is a named appendix or a front-matter section of 74977298Sobrienthe Document that deals exclusively with the relationship of the 75077298Sobrienpublishers or authors of the Document to the Document's overall subject 75177298Sobrien(or to related matters) and contains nothing that could fall directly 75277298Sobrienwithin that overall subject. (For example, if the Document is in part a 75377298Sobrientextbook of mathematics, a Secondary Section may not explain any 75477298Sobrienmathematics.) The relationship could be a matter of historical 75577298Sobrienconnection with the subject or with related matters, or of legal, 75677298Sobriencommercial, philosophical, ethical or political position regarding 75777298Sobrienthem. 75877298Sobrien 75977298SobrienThe "Invariant Sections" are certain Secondary Sections whose titles 76077298Sobrienare designated, as being those of Invariant Sections, in the notice 76177298Sobrienthat says that the Document is released under this License. 76277298Sobrien 76377298SobrienThe "Cover Texts" are certain short passages of text that are listed, 76477298Sobrienas Front-Cover Texts or Back-Cover Texts, in the notice that says that 76577298Sobrienthe Document is released under this License. 76677298Sobrien 76777298SobrienA "Transparent" copy of the Document means a machine-readable copy, 76877298Sobrienrepresented in a format whose specification is available to the 76977298Sobriengeneral public, whose contents can be viewed and edited directly and 77077298Sobrienstraightforwardly with generic text editors or (for images composed of 77177298Sobrienpixels) generic paint programs or (for drawings) some widely available 77277298Sobriendrawing editor, and that is suitable for input to text formatters or 77377298Sobrienfor automatic translation to a variety of formats suitable for input 77477298Sobriento text formatters. A copy made in an otherwise Transparent file 77577298Sobrienformat whose markup has been designed to thwart or discourage 77677298Sobriensubsequent modification by readers is not Transparent. A copy that is 77777298Sobriennot "Transparent" is called "Opaque". 77877298Sobrien 77977298SobrienExamples of suitable formats for Transparent copies include plain 78077298SobrienASCII without markup, Texinfo input format, LaTeX input format, SGML 78177298Sobrienor XML using a publicly available DTD, and standard-conforming simple 78277298SobrienHTML designed for human modification. Opaque formats include 78377298SobrienPostScript, PDF, proprietary formats that can be read and edited only 78477298Sobrienby proprietary word processors, SGML or XML for which the DTD and/or 78577298Sobrienprocessing tools are not generally available, and the 78677298Sobrienmachine-generated HTML produced by some word processors for output 78777298Sobrienpurposes only. 78877298Sobrien 78977298SobrienThe "Title Page" means, for a printed book, the title page itself, 79077298Sobrienplus such following pages as are needed to hold, legibly, the material 79177298Sobrienthis License requires to appear in the title page. For works in 79277298Sobrienformats which do not have any title page as such, "Title Page" means 79377298Sobrienthe text near the most prominent appearance of the work's title, 79477298Sobrienpreceding the beginning of the body of the text. 79577298Sobrien 79677298Sobrien 79777298Sobrien2. VERBATIM COPYING 79877298Sobrien 79977298SobrienYou may copy and distribute the Document in any medium, either 80077298Sobriencommercially or noncommercially, provided that this License, the 80177298Sobriencopyright notices, and the license notice saying this License applies 80277298Sobriento the Document are reproduced in all copies, and that you add no other 80377298Sobrienconditions whatsoever to those of this License. You may not use 80477298Sobrientechnical measures to obstruct or control the reading or further 80577298Sobriencopying of the copies you make or distribute. However, you may accept 80677298Sobriencompensation in exchange for copies. If you distribute a large enough 80777298Sobriennumber of copies you must also follow the conditions in section 3. 80877298Sobrien 80977298SobrienYou may also lend copies, under the same conditions stated above, and 81077298Sobrienyou may publicly display copies. 81177298Sobrien 81277298Sobrien 81377298Sobrien3. COPYING IN QUANTITY 81477298Sobrien 81577298SobrienIf you publish printed copies of the Document numbering more than 100, 81677298Sobrienand the Document's license notice requires Cover Texts, you must enclose 81777298Sobrienthe copies in covers that carry, clearly and legibly, all these Cover 81877298SobrienTexts: Front-Cover Texts on the front cover, and Back-Cover Texts on 81977298Sobrienthe back cover. Both covers must also clearly and legibly identify 82077298Sobrienyou as the publisher of these copies. The front cover must present 82177298Sobrienthe full title with all words of the title equally prominent and 82277298Sobrienvisible. You may add other material on the covers in addition. 82377298SobrienCopying with changes limited to the covers, as long as they preserve 82477298Sobrienthe title of the Document and satisfy these conditions, can be treated 82577298Sobrienas verbatim copying in other respects. 82677298Sobrien 82777298SobrienIf the required texts for either cover are too voluminous to fit 82877298Sobrienlegibly, you should put the first ones listed (as many as fit 82977298Sobrienreasonably) on the actual cover, and continue the rest onto adjacent 83077298Sobrienpages. 83177298Sobrien 83277298SobrienIf you publish or distribute Opaque copies of the Document numbering 83377298Sobrienmore than 100, you must either include a machine-readable Transparent 83477298Sobriencopy along with each Opaque copy, or state in or with each Opaque copy 83577298Sobriena publicly-accessible computer-network location containing a complete 83677298SobrienTransparent copy of the Document, free of added material, which the 83777298Sobriengeneral network-using public has access to download anonymously at no 83877298Sobriencharge using public-standard network protocols. If you use the latter 83977298Sobrienoption, you must take reasonably prudent steps, when you begin 84077298Sobriendistribution of Opaque copies in quantity, to ensure that this 84177298SobrienTransparent copy will remain thus accessible at the stated location 84277298Sobrienuntil at least one year after the last time you distribute an Opaque 84377298Sobriencopy (directly or through your agents or retailers) of that edition to 84477298Sobrienthe public. 84577298Sobrien 84677298SobrienIt is requested, but not required, that you contact the authors of the 84777298SobrienDocument well before redistributing any large number of copies, to give 84877298Sobrienthem a chance to provide you with an updated version of the Document. 84977298Sobrien 85077298Sobrien 85177298Sobrien4. MODIFICATIONS 85277298Sobrien 85377298SobrienYou may copy and distribute a Modified Version of the Document under 85477298Sobrienthe conditions of sections 2 and 3 above, provided that you release 85577298Sobrienthe Modified Version under precisely this License, with the Modified 85677298SobrienVersion filling the role of the Document, thus licensing distribution 85777298Sobrienand modification of the Modified Version to whoever possesses a copy 85877298Sobrienof it. In addition, you must do these things in the Modified Version: 85977298Sobrien 86077298SobrienA. Use in the Title Page (and on the covers, if any) a title distinct 86177298Sobrien from that of the Document, and from those of previous versions 86277298Sobrien (which should, if there were any, be listed in the History section 86377298Sobrien of the Document). You may use the same title as a previous version 86477298Sobrien if the original publisher of that version gives permission. 86577298SobrienB. List on the Title Page, as authors, one or more persons or entities 86677298Sobrien responsible for authorship of the modifications in the Modified 86777298Sobrien Version, together with at least five of the principal authors of the 86877298Sobrien Document (all of its principal authors, if it has less than five). 86977298SobrienC. State on the Title page the name of the publisher of the 87077298Sobrien Modified Version, as the publisher. 87177298SobrienD. Preserve all the copyright notices of the Document. 87277298SobrienE. Add an appropriate copyright notice for your modifications 87377298Sobrien adjacent to the other copyright notices. 87477298SobrienF. Include, immediately after the copyright notices, a license notice 87577298Sobrien giving the public permission to use the Modified Version under the 87677298Sobrien terms of this License, in the form shown in the Addendum below. 87777298SobrienG. Preserve in that license notice the full lists of Invariant Sections 87877298Sobrien and required Cover Texts given in the Document's license notice. 87977298SobrienH. Include an unaltered copy of this License. 88077298SobrienI. Preserve the section entitled "History", and its title, and add to 88177298Sobrien it an item stating at least the title, year, new authors, and 88277298Sobrien publisher of the Modified Version as given on the Title Page. If 88377298Sobrien there is no section entitled "History" in the Document, create one 88477298Sobrien stating the title, year, authors, and publisher of the Document as 88577298Sobrien given on its Title Page, then add an item describing the Modified 88677298Sobrien Version as stated in the previous sentence. 88777298SobrienJ. Preserve the network location, if any, given in the Document for 88877298Sobrien public access to a Transparent copy of the Document, and likewise 88977298Sobrien the network locations given in the Document for previous versions 89077298Sobrien it was based on. These may be placed in the "History" section. 89177298Sobrien You may omit a network location for a work that was published at 89277298Sobrien least four years before the Document itself, or if the original 89377298Sobrien publisher of the version it refers to gives permission. 89477298SobrienK. In any section entitled "Acknowledgements" or "Dedications", 89577298Sobrien preserve the section's title, and preserve in the section all the 89677298Sobrien substance and tone of each of the contributor acknowledgements 89777298Sobrien and/or dedications given therein. 89877298SobrienL. Preserve all the Invariant Sections of the Document, 89977298Sobrien unaltered in their text and in their titles. Section numbers 90077298Sobrien or the equivalent are not considered part of the section titles. 90177298SobrienM. Delete any section entitled "Endorsements". Such a section 90277298Sobrien may not be included in the Modified Version. 90377298SobrienN. Do not retitle any existing section as "Endorsements" 90477298Sobrien or to conflict in title with any Invariant Section. 90577298Sobrien 90677298SobrienIf the Modified Version includes new front-matter sections or 90777298Sobrienappendices that qualify as Secondary Sections and contain no material 90877298Sobriencopied from the Document, you may at your option designate some or all 90977298Sobrienof these sections as invariant. To do this, add their titles to the 91077298Sobrienlist of Invariant Sections in the Modified Version's license notice. 91177298SobrienThese titles must be distinct from any other section titles. 91277298Sobrien 91377298SobrienYou may add a section entitled "Endorsements", provided it contains 91477298Sobriennothing but endorsements of your Modified Version by various 91577298Sobrienparties--for example, statements of peer review or that the text has 91677298Sobrienbeen approved by an organization as the authoritative definition of a 91777298Sobrienstandard. 91877298Sobrien 91977298SobrienYou may add a passage of up to five words as a Front-Cover Text, and a 92077298Sobrienpassage of up to 25 words as a Back-Cover Text, to the end of the list 92177298Sobrienof Cover Texts in the Modified Version. Only one passage of 92277298SobrienFront-Cover Text and one of Back-Cover Text may be added by (or 92377298Sobrienthrough arrangements made by) any one entity. If the Document already 92477298Sobrienincludes a cover text for the same cover, previously added by you or 92577298Sobrienby arrangement made by the same entity you are acting on behalf of, 92677298Sobrienyou may not add another; but you may replace the old one, on explicit 92777298Sobrienpermission from the previous publisher that added the old one. 92877298Sobrien 92977298SobrienThe author(s) and publisher(s) of the Document do not by this License 93077298Sobriengive permission to use their names for publicity for or to assert or 93177298Sobrienimply endorsement of any Modified Version. 93277298Sobrien 93377298Sobrien 93477298Sobrien5. COMBINING DOCUMENTS 93577298Sobrien 93677298SobrienYou may combine the Document with other documents released under this 93777298SobrienLicense, under the terms defined in section 4 above for modified 93877298Sobrienversions, provided that you include in the combination all of the 93977298SobrienInvariant Sections of all of the original documents, unmodified, and 94077298Sobrienlist them all as Invariant Sections of your combined work in its 94177298Sobrienlicense notice. 94277298Sobrien 94377298SobrienThe combined work need only contain one copy of this License, and 94477298Sobrienmultiple identical Invariant Sections may be replaced with a single 94577298Sobriencopy. If there are multiple Invariant Sections with the same name but 94677298Sobriendifferent contents, make the title of each such section unique by 94777298Sobrienadding at the end of it, in parentheses, the name of the original 94877298Sobrienauthor or publisher of that section if known, or else a unique number. 94977298SobrienMake the same adjustment to the section titles in the list of 95077298SobrienInvariant Sections in the license notice of the combined work. 95177298Sobrien 95277298SobrienIn the combination, you must combine any sections entitled "History" 95377298Sobrienin the various original documents, forming one section entitled 95477298Sobrien"History"; likewise combine any sections entitled "Acknowledgements", 95577298Sobrienand any sections entitled "Dedications". You must delete all sections 95677298Sobrienentitled "Endorsements." 95777298Sobrien 95877298Sobrien 95977298Sobrien6. COLLECTIONS OF DOCUMENTS 96077298Sobrien 96177298SobrienYou may make a collection consisting of the Document and other documents 96277298Sobrienreleased under this License, and replace the individual copies of this 96377298SobrienLicense in the various documents with a single copy that is included in 96477298Sobrienthe collection, provided that you follow the rules of this License for 96577298Sobrienverbatim copying of each of the documents in all other respects. 96677298Sobrien 96777298SobrienYou may extract a single document from such a collection, and distribute 96877298Sobrienit individually under this License, provided you insert a copy of this 96977298SobrienLicense into the extracted document, and follow this License in all 97077298Sobrienother respects regarding verbatim copying of that document. 97177298Sobrien 97277298Sobrien 97377298Sobrien7. AGGREGATION WITH INDEPENDENT WORKS 97477298Sobrien 97577298SobrienA compilation of the Document or its derivatives with other separate 97677298Sobrienand independent documents or works, in or on a volume of a storage or 97777298Sobriendistribution medium, does not as a whole count as a Modified Version 97877298Sobrienof the Document, provided no compilation copyright is claimed for the 97977298Sobriencompilation. Such a compilation is called an "aggregate", and this 98077298SobrienLicense does not apply to the other self-contained works thus compiled 98177298Sobrienwith the Document, on account of their being thus compiled, if they 98277298Sobrienare not themselves derivative works of the Document. 98377298Sobrien 98477298SobrienIf the Cover Text requirement of section 3 is applicable to these 98577298Sobriencopies of the Document, then if the Document is less than one quarter 98677298Sobrienof the entire aggregate, the Document's Cover Texts may be placed on 98777298Sobriencovers that surround only the Document within the aggregate. 98877298SobrienOtherwise they must appear on covers around the whole aggregate. 98977298Sobrien 99077298Sobrien 99177298Sobrien8. TRANSLATION 99277298Sobrien 99377298SobrienTranslation is considered a kind of modification, so you may 99477298Sobriendistribute translations of the Document under the terms of section 4. 99577298SobrienReplacing Invariant Sections with translations requires special 99677298Sobrienpermission from their copyright holders, but you may include 99777298Sobrientranslations of some or all Invariant Sections in addition to the 99877298Sobrienoriginal versions of these Invariant Sections. You may include a 99977298Sobrientranslation of this License provided that you also include the 100077298Sobrienoriginal English version of this License. In case of a disagreement 100177298Sobrienbetween the translation and the original English version of this 100277298SobrienLicense, the original English version will prevail. 100377298Sobrien 100477298Sobrien 100577298Sobrien9. TERMINATION 100677298Sobrien 100777298SobrienYou may not copy, modify, sublicense, or distribute the Document except 100877298Sobrienas expressly provided for under this License. Any other attempt to 100977298Sobriencopy, modify, sublicense or distribute the Document is void, and will 101077298Sobrienautomatically terminate your rights under this License. However, 101177298Sobrienparties who have received copies, or rights, from you under this 101277298SobrienLicense will not have their licenses terminated so long as such 101377298Sobrienparties remain in full compliance. 101477298Sobrien 101577298Sobrien 101677298Sobrien10. FUTURE REVISIONS OF THIS LICENSE 101777298Sobrien 101877298SobrienThe Free Software Foundation may publish new, revised versions 101977298Sobrienof the GNU Free Documentation License from time to time. Such new 102077298Sobrienversions will be similar in spirit to the present version, but may 102177298Sobriendiffer in detail to address new problems or concerns. See 102277298Sobrienhttp://www.gnu.org/copyleft/. 102377298Sobrien 102477298SobrienEach version of the License is given a distinguishing version number. 102577298SobrienIf the Document specifies that a particular numbered version of this 102677298SobrienLicense "or any later version" applies to it, you have the option of 102777298Sobrienfollowing the terms and conditions either of that specified version or 102877298Sobrienof any later version that has been published (not as a draft) by the 102977298SobrienFree Software Foundation. If the Document does not specify a version 103077298Sobriennumber of this License, you may choose any version ever published (not 103177298Sobrienas a draft) by the Free Software Foundation. 103277298Sobrien 103377298Sobrien 103477298SobrienADDENDUM: How to use this License for your documents 103577298Sobrien 103677298SobrienTo use this License in a document you have written, include a copy of 103777298Sobrienthe License in the document and put the following copyright and 103877298Sobrienlicense notices just after the title page: 103977298Sobrien 104077298Sobrien@smallexample 104177298Sobrien Copyright (c) YEAR YOUR NAME. 104277298Sobrien Permission is granted to copy, distribute and/or modify this document 104377298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 104477298Sobrien or any later version published by the Free Software Foundation; 104577298Sobrien with the Invariant Sections being LIST THEIR TITLES, with the 104677298Sobrien Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 104777298Sobrien A copy of the license is included in the section entitled "GNU 104877298Sobrien Free Documentation License". 104977298Sobrien@end smallexample 105077298Sobrien 105177298SobrienIf you have no Invariant Sections, write "with no Invariant Sections" 105277298Sobrieninstead of saying which ones are invariant. If you have no 105377298SobrienFront-Cover Texts, write "no Front-Cover Texts" instead of 105477298Sobrien"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. 105577298Sobrien 105677298SobrienIf your document contains nontrivial examples of program code, we 105777298Sobrienrecommend releasing these examples in parallel under your choice of 105877298Sobrienfree software license, such as the GNU General Public License, 105977298Sobriento permit their use in free software. 106077298Sobrien 106133965Sjdp@contents 106233965Sjdp@bye 1063