X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=ld%2Fldint.texinfo;h=dc6e9a65ef387db2c20e474596dc1631d539981f;hb=44c86e8c6da0c80ea8a55718bdab34e05e065abd;hp=81e422a010aaa2194a76b383e087ddcaa1cab965;hpb=41566209643fd0f06bc13ef2900b2428740cf35b;p=deliverable%2Fbinutils-gdb.git diff --git a/ld/ldint.texinfo b/ld/ldint.texinfo index 81e422a010..dc6e9a65ef 100644 --- a/ld/ldint.texinfo +++ b/ld/ldint.texinfo @@ -1,5 +1,7 @@ \input texinfo @setfilename ldint.info +@c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003 +@c Free Software Foundation, Inc. @ifinfo @format @@ -12,12 +14,16 @@ END-INFO-DIR-ENTRY @ifinfo This file documents the internals of the GNU linker ld. -Copyright (C) 1992 Free Software Foundation, Inc. +Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000 +Free Software Foundation, Inc. Contributed by Cygnus Support. -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". @ignore Permission is granted to process this file through Tex and print the @@ -26,9 +32,6 @@ notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore -Permission is granted to copy or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). @end ifinfo @iftex @@ -37,13 +40,13 @@ regarded as a program in the language TeX). @settitle GNU Linker Internals @titlepage @title{A guide to the internals of the GNU linker} -@author Per Bothner, Steve Chamberlain +@author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie @author Cygnus Support @page -@end iftex + @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too +\xdef\manvers{2.10.91} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par @@ -52,251 +55,1004 @@ regarded as a program in the language TeX). @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1992 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000 +Free Software Foundation, Inc. -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". @end titlepage +@end iftex -@node Top, README, (dir), (dir) +@node Top +@top This file documents the internals of the GNU linker @code{ld}. It is a collection of miscellaneous information with little form at this point. Mostly, it is a repository into which you can put information about GNU @code{ld} as you discover it (or as you design changes to @code{ld}). +This document is distributed under the terms of the GNU Free +Documentation License. A copy of the license is included in the +section entitled "GNU Free Documentation License". + @menu * README:: The README File * Emulations:: How linker emulations are generated -* Porting:: Porting the linker +* Emulation Walkthrough:: A Walkthrough of a Typical Emulation +* Architecture Specific:: Some Architecture Specific Notes +* GNU Free Documentation License:: GNU Free Documentation License @end menu -@node README, Emulations, Top, Top +@node README @chapter The @file{README} File Check the @file{README} file; it often has useful information that does not appear anywhere else in the directory. -@node Emulations, Porting, README, Top +@node Emulations @chapter How linker emulations are generated -The linker is controlled by linker scripts written in a linker -control language. A linker emulation gives the personality of -the linker, and is mainly defined by certain linker scripts. -If you want to understand how these scripts are generated, -the main file to look at is the @file{genscripts.sh} shell script, -which is invoked by the @file{Makefile} for each ``emulation'' -to generate a set of 5 linker scripts. - -For example, for the sun3 emulation used by ld68k, @file{genscripts.sh} -sources the file @file{emulparams/sun3.sh}, which sets the emulation -parameters, and specifies that the format is a.out, and to use -@file{scripttempl/aout.sc} to generate the linker scripts. - -@code{genscripts.sh} generates 5 different linker scripts, one for each -of the @code{ld} options @samp{-z} (default), @samp{-n}, @samp{-N}, -@samp{-r} and @samp{-Ur}, where each script is slightly different and is -generated using the template in @file{scripttempl/aout.sc} (for the sun3). - -@node Porting, , Emulations, Top -@chapter Porting the linker - -Before porting @code{ld} itself, you will need to port the BFD library; -see @file{../bfd/PORTING}. - -The @dfn{host} is the system a tool runs @emph{on}. -The @dfn{target} is the system a tool runs @emph{for}; i.e., -a tool can read and write the binaries of the target. -Most often, host==target, but @code{ld} supports cross-linking -(and to some extent the same @code{ld} binary can be used a linker -for multiple target architectures). +Each linker target has an @dfn{emulation}. The emulation includes the +default linker script, and certain emulations also modify certain types +of linker behaviour. + +Emulations are created during the build process by the shell script +@file{genscripts.sh}. + +The @file{genscripts.sh} script starts by reading a file in the +@file{emulparams} directory. This is a shell script which sets various +shell variables used by @file{genscripts.sh} and the other shell scripts +it invokes. + +The @file{genscripts.sh} script will invoke a shell script in the +@file{scripttempl} directory in order to create default linker scripts +written in the linker command language. The @file{scripttempl} script +will be invoked 5 (or, in some cases, 6) times, with different +assignments to shell variables, to create different default scripts. +The choice of script is made based on the command line options. + +After creating the scripts, @file{genscripts.sh} will invoke yet another +shell script, this time in the @file{emultempl} directory. That shell +script will create the emulation source file, which contains C code. +This C code permits the linker emulation to override various linker +behaviours. Most targets use the generic emulation code, which is in +@file{emultempl/generic.em}. + +To summarize, @file{genscripts.sh} reads three shell scripts: an +emulation parameters script in the @file{emulparams} directory, a linker +script generation script in the @file{scripttempl} directory, and an +emulation source file generation script in the @file{emultempl} +directory. + +For example, the Sun 4 linker sets up variables in +@file{emulparams/sun4.sh}, creates linker scripts using +@file{scripttempl/aout.sc}, and creates the emulation code using +@file{emultempl/sunos.em}. + +Note that the linker can support several emulations simultaneously, +depending upon how it is configured. An emulation can be selected with +the @code{-m} option. The @code{-V} option will list all supported +emulations. @menu -* New host:: Porting to a new host -* New target:: Porting to a new target -* New emulation:: Porting to a new emulation target -* Emulation script:: Writing @var{emulation}.sh -* Linker scripts:: Writing a new @var{script}.sc -* -n and -N options:: Handling -n and -N style binaries in your linker script +* emulation parameters:: @file{emulparams} scripts +* linker scripts:: @file{scripttempl} scripts +* linker emulations:: @file{emultempl} scripts @end menu -@node New host, New target, , Porting -@section Porting to a new host +@node emulation parameters +@section @file{emulparams} scripts -Pick a name for your host. Call that @var{host-type}. -You need to create the file @file{config/@var{host-type}.mh}. +Each target selects a particular file in the @file{emulparams} directory +by setting the shell variable @code{targ_emul} in @file{configure.tgt}. +This shell variable is used by the @file{configure} script to control +building an emulation source file. -@node New target, New emulation, New host, Porting -@section Porting to a new target +Certain conventions are enforced. Suppose the @code{targ_emul} variable +is set to @var{emul} in @file{configure.tgt}. The name of the emulation +shell script will be @file{emulparams/@var{emul}.sh}. The +@file{Makefile} must have a target named @file{e@var{emul}.c}; this +target must depend upon @file{emulparams/@var{emul}.sh}, as well as the +appropriate scripts in the @file{scripttempl} and @file{emultempl} +directories. The @file{Makefile} target must invoke @code{GENSCRIPTS} +with two arguments: @var{emul}, and the value of the make variable +@code{tdir_@var{emul}}. The value of the latter variable will be set by +the @file{configure} script, and is used to set the default target +directory to search. -Pick a name for your target. Call that @var{target}. -You need to create at least @file{config/@var{target}.mt}. -It should contain +By convention, the @file{emulparams/@var{emul}.sh} shell script should +only set shell variables. It may set shell variables which are to be +interpreted by the @file{scripttempl} and the @file{emultempl} scripts. +Certain shell variables are interpreted directly by the +@file{genscripts.sh} script. -@example -EMUL=@var{emulation} -@end example +Here is a list of shell variables interpreted by @file{genscripts.sh}, +as well as some conventional shell variables interpreted by the +@file{scripttempl} and @file{emultempl} scripts. -An @dfn{emulation} controls the ``personality'' of @code{ld}, -such as the default linker script. Usually, the -@var{emulation} will have the same name as the @var{target}, -and you will need to create a new @var{emulation} (see below). +@table @code +@item SCRIPT_NAME +This is the name of the @file{scripttempl} script to use. If +@code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use +the script @file{scriptteml/@var{script}.sc}. -You also need to edit @file{Makefile.in} and possibly @file{configure.in}. -To see how to do that, search for existing examples (e.g., @code{sun3}, -@code{sun4}, @code{hp300bsd}). +@item TEMPLATE_NAME +This is the name of the @file{emultemlp} script to use. If +@code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will +use the script @file{emultempl/@var{template}.em}. If this variable is +not set, the default value is @samp{generic}. -@node New emulation, Emulation script, New target, Porting -@section Porting to a new emulation target +@item GENERATE_SHLIB_SCRIPT +If this is set to a nonempty string, @file{genscripts.sh} will invoke +the @file{scripttempl} script an extra time to create a shared library +script. @ref{linker scripts}. -Pick a name for your target. Call that @var{emulation}. -Usually, @var{emulation} and @var{target} are the same. -You need to create at least @file{emulparams/@var{emulation}.sh}. -You also need to edit @file{Makefile.in}. -To see how to do that, search for existing examples. +@item OUTPUT_FORMAT +This is normally set to indicate the BFD output format use (e.g., +@samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally +use it in an @code{OUTPUT_FORMAT} expression in the linker script. -The file @file{emulparams/@var{emulation}.sh} defines a set of -parameters that are used to generate the emulation. Its syntax is that -of a Bourne shell script. It is ``sourced'' by @file{genscripts.sh}. +@item ARCH +This is normally set to indicate the architecture to use (e.g., +@samp{sparc}). The @file{scripttempl} script will normally use it in an +@code{OUTPUT_ARCH} expression in the linker script. -@node Emulation script, Linker scripts, New emulation, Porting -@section Writing @file{@var{emulation}.sh} +@item ENTRY +Some @file{scripttempl} scripts use this to set the entry address, in an +@code{ENTRY} expression in the linker script. -Usually, @file{@var{emulation}.sh} contains: -@example -EMULATION_NAME=@var{emulation} -SCRIPT_NAME=@var{script} -OUTPUT_FORMAT="@var{target-name}" -TEXT_START_ADDR=@var{text-start-addr} -PAGE_SIZE=@var{page-size} -SEGMENT_SIZE=@var{segment-size} # If different from PAGE_SIZE. -ARCH=@var{arch} -@end example +@item TEXT_START_ADDR +Some @file{scripttempl} scripts use this to set the start address of the +@samp{.text} section. -Here: -@table @code -@item @var{target-name} -Matches the @code{filename} field of the @code{bfd_target} you want -to use. (This is a string, and currently the first field.) -For an a.out target, @var{target-name} matches the @code{TARGETNAME} -defined in @file{../bfd/@var{target}.c}. - -@item @var{arch} -The architecture: e.g., @code{m68k}, @code{sparc}, @dots{}. - -@item @var{script} -The file @file{scripttempl/@var{script}.sc} is a shell script which, -when evaluated (by @file{genscripts.sh}), writes a linker script file to -standard output. You may need to write a new script. If you use the -a.out format or something similar, you can probably set -@example -SCRIPT_NAME=aout -@end example - -@item @var{text-start-addr} -@itemx @var{page-size} -@itemx @var{segment-size} -These set the shell variables @code{TEXT_START_ADDR}, @code{PAGE_SIZE}, -and @code{SEGMENT_SIZE} for use by @file{scripttempl/@var{script}.sc}. -If your script doesn't use these variables, you -don't have to define the variables, -For emulations using a.out files, you can get these -values from @file{../bfd/@var{target}.c}. +@item NONPAGED_TEXT_START_ADDR +If this is defined, the @file{genscripts.sh} script sets +@code{TEXT_START_ADDR} to its value before running the +@file{scripttempl} script for the @code{-n} and @code{-N} options +(@pxref{linker scripts}). + +@item SEGMENT_SIZE +The @file{genscripts.sh} script uses this to set the default value of +@code{DATA_ALIGNMENT} when running the @file{scripttempl} script. + +@item TARGET_PAGE_SIZE +If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script +uses this to define it. + +@item ALIGNMENT +Some @file{scripttempl} scripts set this to a number to pass to +@code{ALIGN} to set the required alignment for the @code{end} symbol. @end table -In some cases, you may need more more definitions. -For example, if you can't use @file{emultempl/generic.em}, -you may need to add: -@example -TEMPLATE_NAME=@var{emulation} -@end example -and write your own @file{emultempl/@var{emulation}.em} file. +@node linker scripts +@section @file{scripttempl} scripts + +Each linker target uses a @file{scripttempl} script to generate the +default linker scripts. The name of the @file{scripttempl} script is +set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script. +If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will +invoke @file{scripttempl/@var{script}.sc}. -@node Linker scripts, -n and -N options, Emulation script, Porting -@section Writing a new linker script @file{scripttempl/@var{script}.sc} +The @file{genscripts.sh} script will invoke the @file{scripttempl} +script 5 to 8 times. Each time it will set the shell variable +@code{LD_FLAG} to a different value. When the linker is run, the +options used will direct it to select a particular script. (Script +selection is controlled by the @code{get_script} emulation entry point; +this describes the conventional behaviour). -You may need to write a new script file for your emulation. +The @file{scripttempl} script should just write a linker script, written +in the linker command language, to standard output. If the emulation +name--the name of the @file{emulparams} file without the @file{.sc} +extension--is @var{emul}, then the output will be directed to +@file{ldscripts/@var{emul}.@var{extension}} in the build directory, +where @var{extension} changes each time the @file{scripttempl} script is +invoked. + +Here is the list of values assigned to @code{LD_FLAG}. -Your script can use the shell variable @code{LD_FLAG}, which has the value: @table @code -@item LD_FLAG= -when building a script to be used by default -@item LD_FLAG=n -when building a script to be used for @samp{ld -n} -@item LD_FLAG=N -when building a script to be used for @samp{ld -N} -@item LD_FLAG=r -when building a script to be used for @samp{ld -r} -@item LD_FLAG=u -when building a script to be used for @samp{ld -Ur} +@item (empty) +The script generated is used by default (when none of the following +cases apply). The output has an extension of @file{.x}. +@item n +The script generated is used when the linker is invoked with the +@code{-n} option. The output has an extension of @file{.xn}. +@item N +The script generated is used when the linker is invoked with the +@code{-N} option. The output has an extension of @file{.xbn}. +@item r +The script generated is used when the linker is invoked with the +@code{-r} option. The output has an extension of @file{.xr}. +@item u +The script generated is used when the linker is invoked with the +@code{-Ur} option. The output has an extension of @file{.xu}. +@item shared +The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to +this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the +@file{emulparams} file. The @file{emultempl} script must arrange to use +this script at the appropriate time, normally when the linker is invoked +with the @code{-shared} option. The output has an extension of +@file{.xs}. +@item c +The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to +this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the +@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The +@file{emultempl} script must arrange to use this script at the appropriate +time, normally when the linker is invoked with the @code{-z combreloc} +option. The output has an extension of +@file{.xc}. +@item cshared +The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to +this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the +@file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and +@code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparms} file. +The @file{emultempl} script must arrange to use this script at the +appropriate time, normally when the linker is invoked with the @code{-shared +-z combreloc} option. The output has an extension of @file{.xsc}. @end table -The variable @code{RELOCATING} is only set if relocation is happening -(i.e., unless the linker is invoked with @samp{-r}). -Thus your script should has an action @code{@var{ACTION}} -that should only be done when relocating, -express that as: -@example -$@{RELOCATING+ ACTION@} -@end example -This is the case for most assignments, which should look like: -@example -$@{RELOCATING+ _end = .@} -@end example - -Also, you should assign absolute addresses to sections only -when relocating, so: -@example -.text $@{RELOCATING+ $@{TEXT_START_ADDR@}@}: -@end example - -The form: -@example - .section @{ ... @} > section -@end example -should be: -@example - .section @{ ... @} > $@{RELOCATING+ section@} -@end example - -@code{RELOCATING} is set except when @code{LD_FLAG=r} or @code{LD_FLAG=u}. -@code{CONSTRUCTING} is set except when @code{LD_FLAG=u}. - -Alignment of the data segments is controlled by the variables -@code{DATA_ALIGNMENT_} (note trailing underscore), -@code{DATA_ALIGNMENT_n}, @code{DATA_ALIGNMENT_N}, -@code{DATA_ALIGNMENT_r}, or @code{DATA_ALIGNMENT_u} depending on the -value of @code{LD_FLAGS}. Normally, the default value works (this is -@code{"ALIGN($@{SEGMENT_SIZE@})"} for the @samp{_n}, and @samp{__} -(default) variants; @code{"."} for the @samp{_N}, variant; and @code{""} -for the @samp{_r} and @samp{_u} variants). - -@node -n and -N options, , Linker scripts, Porting -@section Handling @samp{-n} and @samp{-N} style binaries in your linker script - -The @samp{-n} linker option requests the linker to create a binary -with a write-protected text segment, but not demand-pagable (@code{NMAGIC}). -SunOS starts the text segment for demand-paged binaries at 0x2020 -and other binaries at 0x2000, since the exec header (0x20 bytes) -is paged in with the text. Some other Unix variants do the same. - -In that case, the @file{emulparams/@var{emulation}.sh} should define: +Besides the shell variables set by the @file{emulparams} script, and the +@code{LD_FLAG} variable, the @file{genscripts.sh} script will set +certain variables for each run of the @file{scripttempl} script. + @table @code -@item NONPAGED_TEXT_START_ADDR -The text start address to use when linking with @samp{-n} or @samp{-N} options. +@item RELOCATING +This will be set to a non-empty string when the linker is doing a final +relocation (e.g., all scripts other than @code{-r} and @code{-Ur}). + +@item CONSTRUCTING +This will be set to a non-empty string when the linker is building +global constructor and destructor tables (e.g., all scripts other than +@code{-r}). + +@item DATA_ALIGNMENT +This will be set to an @code{ALIGN} expression when the output should be +page aligned, or to @samp{.} when generating the @code{-N} script. + +@item CREATE_SHLIB +This will be set to a non-empty string when generating a @code{-shared} +script. + +@item COMBRELOC +This will be set to a non-empty string when generating @code{-z combreloc} +scripts to a temporary file name which can be used during script generation. +@end table + +The conventional way to write a @file{scripttempl} script is to first +set a few shell variables, and then write out a linker script using +@code{cat} with a here document. The linker script will use variable +substitutions, based on the above variables and those set in the +@file{emulparams} script, to control its behaviour. + +When there are parts of the @file{scripttempl} script which should only +be run when doing a final relocation, they should be enclosed within a +variable substitution based on @code{RELOCATING}. For example, on many +targets special symbols such as @code{_end} should be defined when doing +a final link. Naturally, those symbols should not be defined when doing +a relocatable link using @code{-r}. The @file{scripttempl} script +could use a construct like this to define those symbols: +@smallexample + $@{RELOCATING+ _end = .;@} +@end smallexample +This will do the symbol assignment only if the @code{RELOCATING} +variable is defined. + +The basic job of the linker script is to put the sections in the correct +order, and at the correct memory addresses. For some targets, the +linker script may have to do some other operations. + +For example, on most MIPS platforms, the linker is responsible for +defining the special symbol @code{_gp}, used to initialize the +@code{$gp} register. It must be set to the start of the small data +section plus @code{0x8000}. Naturally, it should only be defined when +doing a final relocation. This will typically be done like this: +@smallexample + $@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@} +@end smallexample +This line would appear just before the sections which compose the small +data section (@samp{.sdata}, @samp{.sbss}). All those sections would be +contiguous in memory. + +Many COFF systems build constructor tables in the linker script. The +compiler will arrange to output the address of each global constructor +in a @samp{.ctor} section, and the address of each global destructor in +a @samp{.dtor} section (this is done by defining +@code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the +@code{gcc} configuration files). The @code{gcc} runtime support +routines expect the constructor table to be named @code{__CTOR_LIST__}. +They expect it to be a list of words, with the first word being the +count of the number of entries. There should be a trailing zero word. +(Actually, the count may be -1 if the trailing word is present, and the +trailing word may be omitted if the count is correct, but, as the +@code{gcc} behaviour has changed slightly over the years, it is safest +to provide both). Here is a typical way that might be handled in a +@file{scripttempl} file. +@smallexample + $@{CONSTRUCTING+ __CTOR_LIST__ = .;@} + $@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@} + $@{CONSTRUCTING+ *(.ctors)@} + $@{CONSTRUCTING+ LONG(0)@} + $@{CONSTRUCTING+ __CTOR_END__ = .;@} + $@{CONSTRUCTING+ __DTOR_LIST__ = .;@} + $@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@} + $@{CONSTRUCTING+ *(.dtors)@} + $@{CONSTRUCTING+ LONG(0)@} + $@{CONSTRUCTING+ __DTOR_END__ = .;@} +@end smallexample +The use of @code{CONSTRUCTING} ensures that these linker script commands +will only appear when the linker is supposed to be building the +constructor and destructor tables. This example is written for a target +which uses 4 byte pointers. + +Embedded systems often need to set a stack address. This is normally +best done by using the @code{PROVIDE} construct with a default stack +address. This permits the user to easily override the stack address +using the @code{--defsym} option. Here is an example: +@smallexample + $@{RELOCATING+ PROVIDE (__stack = 0x80000000);@} +@end smallexample +The value of the symbol @code{__stack} would then be used in the startup +code to initialize the stack pointer. + +@node linker emulations +@section @file{emultempl} scripts + +Each linker target uses an @file{emultempl} script to generate the +emulation code. The name of the @file{emultempl} script is set by the +@code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the +@code{TEMPLATE_NAME} variable is not set, the default is +@samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template}, +@file{genscripts.sh} will use @file{emultempl/@var{template}.em}. + +Most targets use the generic @file{emultempl} script, +@file{emultempl/generic.em}. A different @file{emultempl} script is +only needed if the linker must support unusual actions, such as linking +against shared libraries. + +The @file{emultempl} script is normally written as a simple invocation +of @code{cat} with a here document. The document will use a few +variable substitutions. Typically each function names uses a +substitution involving @code{EMULATION_NAME}, for ease of debugging when +the linker supports multiple emulations. + +Every function and variable in the emitted file should be static. The +only globally visible object must be named +@code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is +the name of the emulation set in @file{configure.tgt} (this is also the +name of the @file{emulparams} file without the @file{.sh} extension). +The @file{genscripts.sh} script will set the shell variable +@code{EMULATION_NAME} before invoking the @file{emultempl} script. + +The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a +@code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}. +It defines a set of function pointers which are invoked by the linker, +as well as strings for the emulation name (normally set from the shell +variable @code{EMULATION_NAME} and the default BFD target name (normally +set from the shell variable @code{OUTPUT_FORMAT} which is normally set +by the @file{emulparams} file). + +The @file{genscripts.sh} script will set the shell variable +@code{COMPILE_IN} when it invokes the @file{emultempl} script for the +default emulation. In this case, the @file{emultempl} script should +include the linker scripts directly, and return them from the +@code{get_scripts} entry point. When the emulation is not the default, +the @code{get_scripts} entry point should just return a file name. See +@file{emultempl/generic.em} for an example of how this is done. + +At some point, the linker emulation entry points should be documented. + +@node Emulation Walkthrough +@chapter A Walkthrough of a Typical Emulation + +This chapter is to help people who are new to the way emulations +interact with the linker, or who are suddenly thrust into the position +of having to work with existing emulations. It will discuss the files +you need to be aware of. It will tell you when the given "hooks" in +the emulation will be called. It will, hopefully, give you enough +information about when and how things happen that you'll be able to +get by. As always, the source is the definitive reference to this. + +The starting point for the linker is in @file{ldmain.c} where +@code{main} is defined. The bulk of the code that's emulation +specific will initially be in @code{emultempl/@var{emulation}.em} but +will end up in @code{e@var{emulation}.c} when the build is done. +Most of the work to select and interface with emulations is in +@code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h} +defines the @code{ld_emulation_xfer_struct} structure your emulation +exports. + +Your emulation file exports a symbol +@code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is +selected (it usually is, since usually there's only one), +@code{ldemul.c} sets the variable @var{ld_emulation} to point to it. +@code{ldemul.c} also defines a number of API functions that interface +to your emulation, like @code{ldemul_after_parse} which simply calls +your @code{ld_@var{EMULATION}_emulation.after_parse} function. For +the rest of this section, the functions will be mentioned, but you +should assume the indirect reference to your emulation also. + +We will also skip or gloss over parts of the link process that don't +relate to emulations, like setting up internationalization. + +After initialization, @code{main} selects an emulation by pre-scanning +the command line arguments. It calls @code{ldemul_choose_target} to +choose a target. If you set @code{choose_target} to +@code{ldemul_default_target}, it picks your @code{target_name} by +default. + +@code{main} calls @code{ldemul_before_parse}, then @code{parse_args}. +@code{parse_args} calls @code{ldemul_parse_args} for each arg, which +must update the @code{getopt} globals if it recognizes the argument. +If the emulation doesn't recognize it, then parse_args checks to see +if it recognizes it. + +Now that the emulation has had access to all its command-line options, +@code{main} calls @code{ldemul_set_symbols}. This can be used for any +initialization that may be affected by options. It is also supposed +to set up any variables needed by the emulation script. + +@code{main} now calls @code{ldemul_get_script} to get the emulation +script to use (based on arguments, no doubt, @pxref{Emulations}) and +runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or +@code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB} +commands. It may call @code{ldemul_unrecognized_file} if you asked +the linker to link a file it doesn't recognize. It will call +@code{ldemul_recognized_file} for each file it does recognize, in case +the emulation wants to handle some files specially. All the while, +it's loading the files (possibly calling +@code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's +done reading the script, @code{main} calls @code{ldemul_after_parse}. +Use the after-parse hook to set up anything that depends on stuff the +script might have set up, like the entry point. + +@code{main} next calls @code{lang_process} in @code{ldlang.c}. This +appears to be the main core of the linking itself, as far as emulation +hooks are concerned(*). It first opens the output file's BFD, calling +@code{ldemul_set_output_arch}, and calls +@code{ldemul_create_output_section_statements} in case you need to use +other means to find or create object files (i.e. shared libraries +found on a path, or fake stub objects). Despite the name, nobody +creates output sections here. + +(*) In most cases, the BFD library does the bulk of the actual +linking, handling symbol tables, symbol resolution, relocations, and +building the final output file. See the BFD reference for all the +details. Your emulation is usually concerned more with managing +things at the file and section level, like "put this here, add this +section", etc. + +Next, the objects to be linked are opened and BFDs created for them, +and @code{ldemul_after_open} is called. At this point, you have all +the objects and symbols loaded, but none of the data has been placed +yet. + +Next comes the Big Linking Thingy (except for the parts BFD does). +All input sections are mapped to output sections according to the +script. If a section doesn't get mapped by default, +@code{ldemul_place_orphan} will get called to figure out where it goes. +Next it figures out the offsets for each section, calling +@code{ldemul_before_allocation} before and +@code{ldemul_after_allocation} after deciding where each input section +ends up in the output sections. + +The last part of @code{lang_process} is to figure out all the symbols' +values. After assigning final values to the symbols, +@code{ldemul_finish} is called, and after that, any undefined symbols +are turned into fatal errors. + +OK, back to @code{main}, which calls @code{ldwrite} in +@file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does +all the relocation fixups and writes the output bfd to disk, and we're +done. + +In summary, + +@itemize @bullet + +@item @code{main()} in @file{ldmain.c} +@item @file{emultempl/@var{EMULATION}.em} has your code +@item @code{ldemul_choose_target} (defaults to your @code{target_name}) +@item @code{ldemul_before_parse} +@item Parse argv, calls @code{ldemul_parse_args} for each +@item @code{ldemul_set_symbols} +@item @code{ldemul_get_script} +@item parse script + +@itemize @bullet +@item may call @code{ldemul_hll} or @code{ldemul_syslib} +@item may call @code{ldemul_open_dynamic_archive} +@end itemize + +@item @code{ldemul_after_parse} +@item @code{lang_process()} in @file{ldlang.c} + +@itemize @bullet +@item create @code{output_bfd} +@item @code{ldemul_set_output_arch} +@item @code{ldemul_create_output_section_statements} +@item read objects, create input bfds - all symbols exist, but have no values +@item may call @code{ldemul_unrecognized_file} +@item will call @code{ldemul_recognized_file} +@item @code{ldemul_after_open} +@item map input sections to output sections +@item may call @code{ldemul_place_orphan} for remaining sections +@item @code{ldemul_before_allocation} +@item gives input sections offsets into output sections, places output sections +@item @code{ldemul_after_allocation} - section addresses valid +@item assigns values to symbols +@item @code{ldemul_finish} - symbol values valid +@end itemize + +@item output bfd is written to disk + +@end itemize + +@node Architecture Specific +@chapter Some Architecture Specific Notes + +This is the place for notes on the behavior of @code{ld} on +specific platforms. Currently, only Intel x86 is documented (and +of that, only the auto-import behavior for DLLs). + +@menu +* ix86:: Intel x86 +@end menu + +@node ix86 +@section Intel x86 + +@table @emph +@code{ld} can create DLLs that operate with various runtimes available +on a common x86 operating system. These runtimes include native (using +the mingw "platform"), cygwin, and pw. + +@item auto-import from DLLs +@enumerate +@item +With this feature on, DLL clients can import variables from DLL +without any concern from their side (for example, without any source +code modifications). Auto-import can be enabled using the +@code{--enable-auto-import} flag, or disabled via the +@code{--disable-auto-import} flag. Auto-import is disabled by default. + +@item +This is done completely in bounds of the PE specification (to be fair, +there's a minor violation of the spec at one point, but in practice +auto-import works on all known variants of that common x86 operating +system) So, the resulting DLL can be used with any other PE +compiler/linker. + +@item +Auto-import is fully compatible with standard import method, in which +variables are decorated using attribute modifiers. Libraries of either +type may be mixed together. + +@item +Overhead (space): 8 bytes per imported symbol, plus 20 for each +reference to it; Overhead (load time): negligible; Overhead +(virtual/physical memory): should be less than effect of DLL +relocation. +@end enumerate + +Motivation + +The obvious and only way to get rid of dllimport insanity is +to make client access variable directly in the DLL, bypassing +the extra dereference imposed by ordinary DLL runtime linking. +I.e., whenever client contains someting like + +@code{mov dll_var,%eax,} + +address of dll_var in the command should be relocated to point +into loaded DLL. The aim is to make OS loader do so, and than +make ld help with that. Import section of PE made following +way: there's a vector of structures each describing imports +from particular DLL. Each such structure points to two other +parellel vectors: one holding imported names, and one which +will hold address of corresponding imported name. So, the +solution is de-vectorize these structures, making import +locations be sparse and pointing directly into code. + +Implementation + +For each reference of data symbol to be imported from DLL (to +set of which belong symbols with name , if __imp_ is +found in implib), the import fixup entry is generated. That +entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3 +subsection. Each fixup entry contains pointer to symbol's address +within .text section (marked with __fuN_ symbol, where N is +integer), pointer to DLL name (so, DLL name is referenced by +multiple entries), and pointer to symbol name thunk. Symbol name +thunk is singleton vector (__nm_th_) pointing to +IMAGE_IMPORT_BY_NAME structure (__nm_) directly containing +imported name. Here comes that "om the edge" problem mentioned above: +PE specification rambles that name vector (OriginalFirstThunk) should +run in parallel with addresses vector (FirstThunk), i.e. that they +should have same number of elements and terminated with zero. We violate +this, since FirstThunk points directly into machine code. But in +practice, OS loader implemented the sane way: it goes thru +OriginalFirstThunk and puts addresses to FirstThunk, not something +else. It once again should be noted that dll and symbol name +structures are reused across fixup entries and should be there +anyway to support standard import stuff, so sustained overhead is +20 bytes per reference. Other question is whether having several +IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes, +it is done even by native compiler/linker (libth32's functions are in +fact resident in windows9x kernel32.dll, so if you use it, you have +two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is +whether referencing the same PE structures several times is valid. +The answer is why not, prohibiting that (detecting violation) would +require more work on behalf of loader than not doing it. + @end table -For example, on a sun4: -@example -TEXT_START_ADDR=0x2020 -NONPAGED_TEXT_START_ADDR=0x2000 -@end example +@node GNU Free Documentation License +@chapter GNU Free Documentation License + + GNU Free Documentation License + + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +@end smallexample + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. -The @samp{-N} linker option creates a binary with a non-write-protected -text segment (@code{NMAGIC}). This is like @samp{-n}, except that the -data segment needs not be page-aligned. +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. @contents @bye