--- /dev/null
+\input texinfo
+@parindent=0pt
+@setfilename gld
+@c @@setchapternewpage odd
+@settitle GLD, The GNU linker
+@titlepage
+@title{gld}
+@subtitle{The gnu loader}
+@sp 1
+@subtitle Second Edition---gld version 2.0
+@subtitle January 1991
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991 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 and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@author {Steve Chamberlain}
+@author {Cygnus Support}
+@author {steve@@cygnus.com}
+@end titlepage
+
+@node Top,,,
+@comment node-name, next, previous, up
+@ifinfo
+This file documents the GNU linker gld.
+@end ifinfo
+
+@c chapter What does a linker do ?
+@c chapter Command Language
+@noindent
+@chapter Overview
+
+
+The @code{gld} command combines a number of object and archive files,
+relocates their data and ties up symbol references. Often the last
+step in building a new compiled program to run is a call to @code{gld}.
+
+The @code{gld} command accepts Linker Command Language files in
+a superset of AT+T's Link Editor Command Language syntax,
+to provide explict and total control over the linking process.
+
+This version of @code{gld} uses the general purpose @code{bfd} libraries
+to operate on object files. This allows @code{gld} to read and
+write any of the formats supported by @code{bfd}, different
+formats may be linked together producing any available object file.
+
+Supported formats:
+@itemize @bullet
+@item
+Sun3 68k a.out
+@item
+IEEE-695 68k Object Module Format
+@item
+Oasys 68k Binary Relocatable Object File Format
+@item
+Sun4 sparc a.out
+@item
+88k bcs coff
+@item
+i960 coff little endian
+@item
+i960 coff big endian
+@item
+i960 b.out little endian
+@item
+i960 b.out big endian
+@item
+s-records
+@end itemize
+
+When linking similar formats, @code{gld} maintains all debugging
+information.
+
+@chapter Command line options
+
+@example
+ gld [ -Bstatic ] [ -D @var{datasize} ]
+ [ -c @var{filename} ]
+ [ -d ] | [ -dc ] | [ -dp ]
+ [ -i ]
+ [ -e @var{entry} ] [ -l @var{arch} ] [ -L @var{searchdir} ] [ -M ]
+ [ -N | -n | -z ] [ -noinhibit-exec ] [ -r ] [ -S ] [ -s ]
+ [ -f @var{fill} ]
+ [ -T @var{textorg} ] [ -Tdata @var{dataorg} ] [ -t ] [ -u @var{sym}]
+ [ -X ] [ -x ]
+ [-o @var{output} ] @var{objfiles}@dots{}
+@end example
+
+Command-line options to GNU @code{gld} may be specified in any order, and
+may be repeated at will. For the most part, repeating an option with a
+different argument will either have no further effect, or override prior
+occurrences (those further to the left on the command line) of an
+option.
+
+The exceptions which may meaningfully be present several times
+are @code{-L}, @code{-l}, and @code{-u}.
+
+@var{objfiles} may follow, precede, or be mixed in with
+command-line options; save that an @var{objfiles} argument may not be
+placed between an option flag and its argument.
+
+Option arguments must follow the option letter without intervening
+whitespace, or be given as separate arguments immediately following the
+option that requires them.
+
+@table @code
+@item @var{objfiles}@dots{}
+The object files @var{objfiles} to be linked; at least one must be specified.
+
+@item -Bstatic
+This flag is accepted for command-line compatibility with the SunOS linker,
+but has no effect on @code{gld}.
+
+@item -c @var{commandfile}
+Directs @code{gld} to read linkage commands from the file @var{commandfile}.
+
+@item -D @var{datasize}
+Use this option to specify a target size for the @code{data} segment of
+your linked program. The option is only obeyed if @var{datasize} is
+larger than the natural size of the program's @code{data} segment.
+
+@var{datasize} must be an integer specified in hexadecimal.
+
+@code{ld} will simply increase the size of the @code{data} segment,
+padding the created gap with zeros, and reduce the size of the
+@code{bss} segment to match.
+
+@item -d
+Force @code{ld} to assign space to common symbols
+even if a relocatable output file is specified (@code{-r}).
+
+@item -dc | -dp
+This flags is accepted for command-line compatibility with the SunOS linker,
+but has no effect on @code{gld}.
+
+@item -e @var{entry}
+Use @var{entry} as the explicit symbol for beginning execution of your
+program, rather than the default entry point. If this symbol is
+not specified, the symbol @code{start} is used as the entry address.
+If there is no symbol called @code{start}, then the entry address
+is set to the first address in the first output section
+(usually the @samp{text} section).
+
+@item -f @var{fill}
+Sets the default fill pattern for ``holes'' in the output file to
+the lowest two bytes of the expression specified.
+
+@item -i
+Produce an incremental link (same as option @code{-r}).
+
+@item -l @var{arch}
+Add an archive file @var{arch} to the list of files to link. This
+option may be used any number of times. @code{ld} will search its
+path-list for occurrences of @code{lib@var{arch}.a} for every @var{arch}
+specified.
+
+@c This also has a side effect of using the "c++ demangler" if we happen
+@c to specify -llibg++. Document? pesch@@cygnus.com, 24jan91
+
+@item -L @var{searchdir}
+This command adds path @var{searchdir} to the
+list of paths that @code{gld} will search for archive libraries. You
+may use this option any number of times.
+
+@c Should we make any attempt to list the standard paths searched
+@c without listing? When hacking on a new system I often want to know
+@c this, but this may not be the place... it's not constant across
+@c systems, of course, which is what makes it interesting.
+@c pesch@@cygnus.com, 24jan91.
+
+@item -M
+@itemx -m
+Print (to the standard output file) a link map---diagnostic information
+about where symbols are mapped by @code{ld}, and information on global
+common storage allocation.
+
+@item -N
+specifies read and writable @code{text} and @code{data} sections. If
+the output format supports Unix style magic numbers, then OMAGIC is set.
+
+@item -n
+sets the text segment to be read only, and @code{NMAGIC} is written
+if possible.
+
+@item -o @var{output}
+@var{output} is a name for the program produced by @code{ld}; if this
+option is not specified, the name @samp{a.out} is used by default.
+
+@item -r
+Generates relocatable output---i.e., generate an output file that can in
+turn serve as input to @code{gld}. As a side effect, this option also
+sets the output file's magic number to @code{OMAGIC}; see @samp{-N}. If this
+option is not specified, an absolute file is produced.
+
+@item -S
+Omits debugger symbol information (but not all symbols) from the output file.
+
+@item -s
+Omits all symbol information from the output file.
+
+@item -T @var{textorg}
+@itemx -Ttext @var{textorg}
+Use @var{textorg} as the starting address for the @code{text} segment of the
+output file. Both forms of this option are equivalent. The option
+argument must be a hexadecimal integer.
+
+@item -Tdata @var{dataorg}
+Use @var{dataorg} as the starting address for the @code{data} segment of
+the output file. The option argument must be a hexadecimal integer.
+
+@item -t
+Prints names of input files as @code{ld} processes them.
+
+@item -u @var{sym}
+Forces @var{sym} to be entered in the output file as an undefined symbol.
+This may, for example, trigger linking of additional modules from
+standard libraries. @code{-u} may be repeated with different option
+arguments to enter additional undefined symbols. This option is equivalent
+to the @code{EXTERN} linker command.
+
+@item -X
+If @code{-s} or @code{-S} is also specified, delete only local symbols
+beginning with @samp{L}.
+
+@item -z
+@code{-z} sets @code{ZMAGIC}, the default: the @code{text} segment is
+read-only, demand pageable, and shared.
+
+Specifying a relocatable output file (@code{-r}) will also set the magic
+number to @code{OMAGIC}.
+
+See description of @samp{-N}.
+
+
+@end table
+@chapter Command Language
+
+
+The command language allows explicit control over the linkage process, allowing
+specification of:
+@table @bullet
+@item input files
+@item file formats
+@item output file format
+@item addresses of sections
+@item placement of common blocks
+@item and more
+@end table
+
+A command file may be supplied to the linker, either explicitly through the
+@code{-c} option, or implicitly as an ordinary file. If the linker opens
+a file which does not have a reasonable object or archive format, it tries
+to read the file as if it were a command file.
+@section Structure
+To be added
+
+@section Expressions
+The syntax for expressions in the command language is identical to that of
+C expressions, with the following features:
+@table @bullet
+@item All expressions evaluated as integers and
+are of ``long'' or ``unsigned long'' type.
+@item All constants are integers.
+@item All of the C arithmetic operators are provided.
+@item Global variables may be referenced, defined and created.
+@item Build in functions may be called.
+@end table
+
+@section Expressions
+
+The linker has a practice of ``lazy evaluation'' for expressions; it only
+calculates an expression when absolutely necessary. For instance,
+when the linker reads in the command file it has to know the values
+of the start address and the length of the memory regions for linkage to continue, so these
+values are worked out, but other values (such as symbol values) are not
+known or needed until after storage allocation.
+They are evaluated later, when the other
+information, such as the sizes of output sections are available for use in
+the symbol assignment expression.
+
+When a linker expression is evaluated and assigned to a variable it is given
+either an absolute or a relocatable type. An absolute expression type
+is one in which the symbol contains the value that it will have in the
+output file, a relocateable expression type is one in which the value
+is expressed as a fixed offset from the base of a section.
+
+The type of the expression is controlled by its position in the script
+file. A symbol assigned within a @code{SECTION} specification is
+created relative to the base of the section, a symbol assigned in any
+other place is created as an absolute symbol. Since a symbol created
+within a @code{SECTION} specification is relative to the base of the
+section it will remain relocatable if relocatable output is requested.
+A symbol may be created with an absolute value even when assigned to
+within a @code{SECTION} specification by using the absolute assignment
+function @code{ABSOLUTE} For example, to create an absolute symbol
+whose address is the last byte of the output section @code{.data}:
+@example
+.data :
+ @{
+ *(.data)
+ _edata = ABSOLUTE(.) ;
+ @}
+@end example
+
+Unless quoted, symbol names start with a letter, underscore, point or
+minus sign and may include any letters, underscores, digits, points,
+and minus signs. Unquoted symbol names must not conflict with any
+keywords. To specify a symbol which contains odd characters or has
+the same name as a keyword surround it in double quotes:
+@example
+ ``SECTION'' = 9;
+ ``with a space'' = ``also with a space'' + 10;
+@end example
+
+@subsection Integers
+An octal integer is @samp{0} followed by zero or more of the octal
+digits (@samp{01234567}).
+
+A decimal integer starts with a non-zero digit followed by zero or
+more digits (@samp{0123456789}).
+
+A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
+more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
+
+Integers have the usual values. To denote a negative integer, use
+the unary operator @samp{-} discussed under expressions.
+
+Additionally the suffixes @code{K} and @code{M} may be used to multiply the
+previous constant by 1024 or
+@tex
+$1024^2$
+@end tex
+respectively.
+
+@example
+ _as_decimal = 57005;
+ _as_hex = 0xdead;
+ _as_octal = 0157255;
+
+ _4k_1 = 4K;
+ _4k_2 = 4096;
+ _4k_3 = 0x1000;
+@end example
+@subsection Operators
+The linker provides the standard C set of arithmetic operators, with
+the standard bindings and precedence levels:
+@example
+
+@end example
+@tex
+
+\vbox{\offinterlineskip
+\hrule
+\halign
+{\vrule#&\hfil#\hfil&\vrule#&\hfil#\hfil&\vrule#&\hfil#\hfil&\vrule#\cr
+height2pt&&&&&\cr
+&Level&& associativity &&Operators&\cr
+height2pt&&&&&\cr
+\noalign{\hrule}
+height2pt&&&&&\cr
+&highest&&&&&&\cr
+&1&&left&&$ ! - ~$&\cr
+height2pt&&&&&\cr
+&2&&left&&* / \%&\cr
+height2pt&&&&&\cr
+&3&&left&&+ -&\cr
+height2pt&&&&&\cr
+&4&&left&&$>> <<$&\cr
+height2pt&&&&&\cr
+&5&&left&&$== != > < <= >=$&\cr
+height2pt&&&&&\cr
+&6&&left&&\&&\cr
+height2pt&&&&&\cr
+&7&&left&&|&\cr
+height2pt&&&&&\cr
+&8&&left&&{\&\&}&\cr
+height2pt&&&&&\cr
+&9&&left&&||&\cr
+height2pt&&&&&\cr
+&10&&right&&? :&\cr
+height2pt&&&&&\cr
+&11&&right&&$${\&= += -= *= /=}&\cr
+&lowest&&&&&&\cr
+height2pt&&&&&\cr}
+\hrule}
+@end tex
+
+@section Built in Functions
+The command language provides built in functions for use in
+expressions in linkage scripts.
+@table @bullet
+@item @code{ALIGN(@var{exp})}
+returns the result of the current location counter (@code{dot})
+aligned to the next @var{exp} boundary, where @var{exp} is a power of
+two. This is equivalent to @code{(. + @var{exp} -1) & ~(@var{exp}-1)}.
+As an example, to align the output @code{.data} section to the
+next 0x2000 byte boundary after the preceding section and to set a
+variable within the section to the next 0x8000 boundary after the
+input sections:
+@example
+ .data ALIGN(0x2000) :@{
+ *(.data)
+ variable = ALIGN(0x8000);
+ @}
+@end example
+
+@item @code{ADDR(@var{section name})}
+returns the absolute address of the named section if the section has
+already been bound. In the following examples the @code{symbol_1} and
+@code{symbol_2} are assigned identical values:
+@example
+ .output1:
+ @{
+ start_of_output_1 $= .;
+ ...
+ @}
+ .output:
+ @{
+ symbol_1 = ADDR(.output1);
+ symbol_2 = start_of_output_1;
+ @}
+@end example
+
+@item @code{SIZEOF(@var{section name})}
+returns the size in bytes of the named section, if the section has
+been allocated. In the following example the @code{symbol_1} and
+@code{symbol_2} are assigned identical values:
+@example
+ .output @{
+ .start = . ;
+ ...
+ .end = .;
+ @}
+ symbol_1 = .end - .start;
+ symbol_2 = SIZEOF(.output);
+@end example
+
+@item @code{DEFINED(@var{symbol name})}
+Returns 1 if the symbol is in the linker global symbol table and is
+defined, otherwise it returns 0. This example shows the setting of a
+global symbol @code{begin} to the first location in the @code{.text}
+section, only if there is no other symbol
+called @code{begin} already:
+@example
+ .text: @{
+ begin = DEFINED(begin) ? begin : . ;
+ ...
+ @}
+@end example
+@end table
+@page
+@section MEMORY Directive
+The linker's default configuration is for all memory to be
+allocatable. This state may be overridden by using the @code{MEMORY}
+directive. The @code{MEMORY} directive describes the location and
+size of blocks of memory in the target. Careful use can describe
+memory regions which may or may not be used by the linker. The linker
+does not shuffle sections to fit into the available regions, but does
+move the requested sections into the correct regions and issue errors
+when the regions become too full. The syntax is:
+
+@example
+ MEMORY
+ @{
+@tex
+ $\bigl\lbrace {\it name_1} ({\it attr_1}):$ ORIGIN = ${\it origin_1},$ LENGTH $= {\it len_1} \bigr\rbrace $
+@end tex
+
+ @}
+@end example
+@table @code
+@item @var{name}
+is a name used internally by the linker to refer to the region. Any
+symbol name may be used. The region names are stored in a separate
+name space, and will not conflict with symbols, filenames or section
+names.
+@item @var{attr}
+is an optional list of attributes, parsed for compatibility with the
+AT+T linker
+but ignored by the both the AT+T and the gnu linker.
+@item @var{origin}
+is the start address of the region in physical memory expressed as
+standard linker expression which must evaluate to a constant before
+memory allocation is performed. The keyword @code{ORIGIN} may be
+abbreviated to @code{org} or @code{o}.
+@item @var{len}
+is the size in bytes of the region as a standard linker expression.
+The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}
+@end table
+
+For example, to specify that memory has two regions available for
+allocation; one starting at 0 for 256k, and the other starting at
+0x40000000 for four megabytes:
+
+@example
+ MEMORY
+ @{
+ rom : ORIGIN= 0, LENGTH = 256K
+ ram : ORIGIN= 0x40000000, LENGTH = 4M
+ @}
+
+@end example
+
+If the combined output sections directed to a region are too big for
+the region the linker will emit an error message.
+@page
+@section SECTIONS Directive
+The @code{SECTIONS} directive
+controls exactly where input sections are placed into output sections, their
+order and to which output sections they are allocated.
+
+When no @code{SECTIONS} directives are specified, the default action
+of the linker is to place each input section into an identically named
+output section in the order that the sections appear in the first
+file, and then the order of the files.
+
+The syntax of the @code{SECTIONS} directive is:
+
+@example
+ SECTIONS
+ @{
+@tex
+ $\bigl\lbrace {\it name_n}\bigl[options\bigr]\colon$ $\bigl\lbrace {\it statements_n} \bigr\rbrace \bigl[ = {\it fill expression } \bigr] \bigl[ > mem spec \bigr] \bigr\rbrace $
+@end tex
+ @}
+@end example
+
+@table @code
+@item @var{name}
+controls the name of the output section. In formats which only support
+a limited number of sections, such as @code{a.out}, the name must be
+one of the names supported by the format (in the case of a.out,
+@code{.text}, @code{.data} or @code{.bss}). If the output format
+supports any number of sections, but with numbers and not names (in
+the case of IEEE), the name should be supplied as a quoted numeric
+string. A section name may consist of any sequence characters, but
+any name which does not conform to the standard @code{gld} symbol name
+syntax must be quoted. To copy sections 1 through 4 from a Oasys file
+into the @code{.text} section of an @code{a.out} file, and sections 13
+and 14 into the @code{data} section:
+@example
+
+ SECTION @{
+ .text :@{
+ *(``1'' ``2'' ``3'' ``4'')
+ @}
+
+ .data :@{
+ *(``13'' ``14'')
+ @}
+ @}
+@end example
+
+@item @var{fill expression}
+If present this
+expression sets the fill value. Any unallocated holes in the current output
+section when written to the output file will
+be filled with the two least significant bytes of the value, repeated as
+necessary.
+@page
+@item @var{options}
+the @var{options} parameter is a list of optional arguments specifying
+attributes of the output section, they may be taken from the following
+list:
+@table @bullet{}
+@item @var{addr expression}
+forces the output section to be loaded at a specified address. The
+address is specified as a standard linker expression. The following
+example generates section @var{output} at location
+@code{0x40000000}:
+@example
+ SECTIONS @{
+ output 0x40000000: @{
+ ...
+ @}
+ @}
+@end example
+Since the built in function @code{ALIGN} references the location
+counter implicitly, a section may be located on a certain boundary by
+using the @code{ALIGN} function in the expression. For example, to
+locate the @code{.data} section on the next 8k boundary after the end
+of the @code{.text} section:
+@example
+ SECTIONS @{
+ .text @{
+ ...
+ @}
+ .data ALIGN(4K) @{
+ ...
+ @}
+ @}
+@end example
+@end table
+@item @var{statements}
+is a list of file names, input sections and assignments. These statements control what is placed into the
+output section.
+The syntax of a single @var{statement} is one of:
+@table @bullet
+
+@item @var{symbol} [ $= | += | -= | *= | /= ] @var{ expression} @code{;}
+
+Global symbols may be created and have their values (addresses)
+altered using the assignment statement. The linker tries to put off
+the evaluation of an assignment until all the terms in the source
+expression are known; for instance the sizes of sections cannot be
+known until after allocation, so assignments dependent upon these are
+not performed until after allocation. Some expressions, such as those
+depending upon the location counter @code{dot}, @samp{.} must be
+evaluated during allocation. If the result of an expression is
+required, but the value is not available, then an error results: eg
+@example
+ SECTIONS @{
+ text 9+this_isnt_constant:
+ @{
+ @}
+ @}
+ testscript:21: Non constant expression for initial address
+@end example
+
+@item @code{CREATE_OBJECT_SYMBOLS}
+causes the linker to create a symbol for each input file and place it
+into the specified section set with the value of the first byte of
+data written from the input file. For instance, with @code{a.out}
+files it is conventional to have a symbol for each input file.
+@example
+ SECTIONS @{
+ .text 0x2020 :
+ @{
+ CREATE_OBJECT_SYMBOLS
+ *(.text)
+ _etext = ALIGN(0x2000);
+ @}
+ @}
+@end example
+Supplied with four object files, @code{a.o}, @code{b.o}, @code{c.o},
+and @code{d.o} a run of
+@code{gld} could create a map:
+@example
+From functions like :
+a.c:
+ afunction() { }
+ int adata=1;
+ int abss;
+
+00000000 A __DYNAMIC
+00004020 B _abss
+00004000 D _adata
+00002020 T _afunction
+00004024 B _bbss
+00004008 D _bdata
+00002038 T _bfunction
+00004028 B _cbss
+00004010 D _cdata
+00002050 T _cfunction
+0000402c B _dbss
+00004018 D _ddata
+00002068 T _dfunction
+00004020 D _edata
+00004030 B _end
+00004000 T _etext
+00002020 t a.o
+00002038 t b.o
+00002050 t c.o
+00002068 t d.o
+
+@end example
+
+@item @var{filename} @code{(} @var{section name list} @code{)}
+This command allocates all the named sections from the input object
+file supplied into the output section at the current point. Sections
+are written in the order they appear in the list so:
+@example
+ SECTIONS @{
+ .text 0x2020 :
+ @{
+ a.o(.data)
+ b.o(.data)
+ *(.text)
+ @}
+ .data :
+ @{
+ *(.data)
+ @}
+ .bss :
+ @{
+ *(.bss)
+ COMMON
+ @}
+ @}
+@end example
+will produce a map:
+@example
+
+ insert here
+@end example
+@item @code{* (} @var{section name list} @code{)}
+This command causes all sections from all input files which have not
+yet been assigned output sections to be assigned the current output
+section.
+
+@item @var{filename} @code{[COMMON]}
+This allocates all the common symbols from the specified file and places
+them into the current output section.
+
+@item @code{* [COMMON]}
+This allocates all the common symbols from the files which have not
+yet had their common symbols allocated and places them into the current
+output section.
+
+@item @var{filename}
+A filename alone within a @code{SECTIONS} statement will cause all the
+input sections from the file to be placed into the current output
+section at the current location. If the file name has been mentioned
+before with a section name list then only those
+sections which have not yet been allocated are noted.
+
+The following example reads all of the sections from file all.o and
+places them at the start of output section @code{outputa} which starts
+at location @code{0x10000}. All of the data from section @code{.input1} from
+file foo.o is placed next into the same output section. All of
+section @code{.input2} is read from foo.o and placed into output
+section @code{outputb}. Next all of section @code{.input1} is read
+from foo1.o. All of the remaining @code{.input1} and @code{.input2}
+sections from any files are written to output section @code{output3}.
+
+@example
+ SECTIONS
+ @{
+ outputa 0x10000 :
+ @{
+ all.o
+ foo.o (.input1)
+ @}
+ outputb :
+ @{
+ foo.o (.input2)
+ foo1.o (.input1)
+ @}
+ outputc :
+ @{
+ *(.input1)
+ *(.input2)
+ @}
+ @}
+
+@end example
+@end table
+@end table
+@section Using the Location Counter
+The special linker variable @code{dot}, @samp{.} always contains the
+current output location counter. Since the @code{dot} always refers to
+a location in an output section, it must always appear in an
+expression within a @code{SECTIONS} directive. The @code{dot} symbol
+may appear anywhere that an ordinary symbol may appear in an
+expression, but its assignments have a side effect. Assigning a value
+to the @code{dot} symbol will cause the location counter to be moved.
+This may be used to create holes in the output section. The location
+counter may never be moved backwards.
+@example
+ SECTIONS
+ @{
+ output :
+ @{
+ file1(.text)
+ . = . + 1000;
+ file2(.text)
+ . += 1000;
+ file3(.text)
+ . -= 32;
+ file4(.text)
+ @} = 0x1234;
+ @}
+@end example
+In the previous example, @code{file1} is located at the beginning of
+the output section, then there is a 1000 byte gap, filled with 0x1234.
+Then @code{file2} appears, also with a 1000 byte gap following before
+@code{file3} is loaded. Then the first 32 bytes of @code{file4} are
+placed over the last 32 bytes of @code{file3}.
+@section Command Language Syntax
+@section The Entry Point
+The linker chooses the first executable instruction in an output file from a list
+of possibilities, in order:
+@itemize @bullet
+@item
+The value of the symbol provided to the command line with the @code{-e} option, when
+present.
+@item
+The value of the symbol provided in the @code{ENTRY} directive,
+if present.
+@item
+The value of the symbol @code{start}, if present.
+@item
+The value of the symbol @code{_main}, if present.
+@item
+The address of the first byte of the @code{.text} section, if present.
+@item
+The value 0.
+@end itemize
+If the symbol @code{start} is not defined within the set of input
+files to a link, it may be generated by a simple assignment
+expression. eg.
+@example
+ start = 0x2020;
+@end example
+@section Section Attributes
+@section Allocation of Sections into Memory
+@section Defining Symbols
+@chapter Examples of operation
+The simplest case is linking standard Unix object files on a standard
+Unix system supported by the linker. To link a file hello.o:
+@example
+$ gld -o output /lib/crt0.o hello.o -lc
+@end example
+This tells gld to produce a file called @code{output} after linking
+the file @code{/lib/crt0.o} with @code{hello.o} and the library
+@code{libc.a} which will come from the standard search directories.
+@chapter Partial Linking
+Specifying the @code{-r} on the command line causes @code{gld} to
+perform a partial link.
+
+
+@chapter BFD
+
+The linker accesses object and archive files using the @code{bfd}
+libraries. These libraries allow the linker to use the same routines
+to operate on object files whatever the object file format.
+
+A different object file format can be supported simply by creating a
+new @code{bfd} back end and adding it to the library.
+
+Formats currently supported:
+@itemize @bullet
+@item
+Sun3 68k a.out
+@item
+IEEE-695 68k Object Module Format
+@item
+Oasys 68k Binary Relocatable Object File Format
+@item
+Sun4 sparc a.out
+@item
+88k bcs coff
+@item
+i960 coff little endian
+@item
+i960 coff big endian
+@item
+i960 b.out little endian
+@item
+i960 b.out big endian
+@end itemize
+
+As with most implementations, @code{bfd} is a compromise between
+several conflicting requirements. The major factor influencing
+@code{bfd} design was efficiency, any time used converting between
+formats is time which would not have been spent had @code{bfd} not
+been involved. This is partly offset by abstraction payback; since
+@code{bfd} simplifies applications and back ends, more time and care
+may be spent optimizing algorithms for a greater speed.
+
+One minor artifact of the @code{bfd} solution which the
+user should be aware of is information lossage.
+There are two places where useful information can be lost using the
+@code{bfd} mechanism; during conversion and during output.
+
+@section How it works
+When an object file is opened, @code{bfd}
+tries to automatically determine the format of the input object file, a
+descriptor is built in memory with pointers to routines to access
+elements of the object file's data structures.
+
+As different information from the the object files is required
+@code{bfd} reads from different sections of the file and processes
+them. For example a very common operation for the linker is processing
+symbol tables. Each @code{bfd} back end provides a routine for
+converting between the object file's representation of symbols and an
+internal canonical format. When the linker asks for the symbol table
+of an object file, it calls through the memory pointer to the relevant
+@code{bfd} back end routine which reads and converts the table into
+the canonical form. Linker then operates upon the common form. When
+the link is finished and the linker writes the symbol table of the
+output file, another @code{bfd} back end routine is called which takes
+the newly created symbol table and converts it into the output format.
+
+@section Information Leaks
+@table @bullet{}
+@item Information lost during output.
+The output formats supported by @code{bfd} do not provide identical
+facilities, and information which may be described in one form
+has no where to go in another format. One example of this would be
+alignment information in @code{b.out}. There is no where in an @code{a.out}
+format file to store alignment information on the contained data, so when
+a file is linked from @code{b.out} and an @code{a.out} image is produced,
+alignment information is lost. (Note that in this case the linker has the
+alignment information internally, so the link is performed correctly).
+
+Another example is COFF section names. COFF files may contain an
+unlimited number of sections, each one with a textual section name. If
+the target of the link is a format which does not have many sections
+(eg @code{a.out}) or has sections without names (eg the Oasys format)
+the link cannot be done simply. It is possible to circumvent this
+problem by describing the desired input section to output section
+mapping with the command language.
+
+@item Information lost during canonicalization.
+The @code{bfd}
+internal canonical form of the external formats is not exhaustive,
+there are structures in input formats for which there is no direct
+representation internally. This means that the @code{bfd} back ends
+cannot maintain all the data richness through the transformation
+between external to internal and back to external formats.
+
+This limitation is only a problem when using the linker to read one
+format and write another. Each @code{bfd} back end is responsible for
+maintaining as much data as possible, and the internal @code{bfd}
+canonical form has structures which are opaque to the @code{bfd} core,
+and exported only to the back ends. When a file is read in one format,
+the canonical form is generated for @code{bfd} and the linker. At the
+same time, the back end saves away any information which may otherwise
+be lost. If the data is then written back to the same back end, the
+back end routine will be able to use the canonical form provided by
+the @code{bfd} core as well as the information it prepared earlier.
+Since there is a great deal of commonality between back ends, this
+mechanism is very useful. There is no information lost when linking
+big endian COFF to little endian COFF, or from a.out to b.out. When a
+mixture of formats are linked, the information is only lost from the
+files with a different format to the destination.
+@end table
+@section Mechanism
+The smallest amount of information is preserved when there
+is a small union between the information provided by the source
+format, that stored by the canonical format and the information needed
+by the destination format. A brief description of the canonical form
+will help the user appreciate what is possible to be maintained
+between conversions.
+
+@table @bullet
+@item file level Information on target machine
+architecture, particular implementation and format type are stored on
+a per file basis. Other information includes a demand pageable bit and
+a write protected bit. Note that information like Unix magic numbers
+is not stored here, only the magic numbers meaning, so a ZMAGIC file
+would have both the demand pageable bit and the write protected text
+bit set.
+
+The byte order of the target is stored on a per file basis, so that
+both big and little endian object files may be linked together at the
+same time.
+@item section level
+Each section in the input file contains the name of the section, the
+original address in the object file, various flags, size and alignment
+information and pointers into other @code{bfd} data structures.
+@item symbol level
+Each symbol contains a pointer to the object file which originally
+defined it, its name, value and various flags bits. When a symbol
+table is read in all symbols are relocated to make them relative to
+the base of the section they were defined in, so each symbol points to
+the containing section. Each symbol also has a varying amount of
+hidden data to contain private data for the back end. Since the symbol
+points to the original file, the symbol private data format is
+accessible. Operations may be done to a list of symbols of wildly
+different formats without problems.
+
+Normal global and simple local symbols are maintained on output, so an
+output file, no matter the format will retain symbols pointing to
+functions, globals, statics and commons. Some symbol information is
+not worth retaining; in @code{a.out} type information is stored in the
+symbol table as long symbol names. This information would be useless
+to most coff debuggers and may be thrown away with appropriate command
+line switches. (Note that gdb does support stabs in coff).
+
+There is one word of type information within the symbol, so if the
+format supports symbol type information within symbols - (eg COFF,
+IEEE, Oasys) and the type is simple enough to fit within one word
+(nearly everything but aggregates) the information will be preserved.
+
+@item relocation level
+Each canonical relocation record contains a pointer to the symbol to
+relocate to, the offset of the data to relocate, the section the data
+is in and a pointer to a relocation type descriptor. Relocation is
+performed effectively by message passing through the relocation type
+descriptor and symbol pointer. It allows relocations to be performed
+on output data using a relocation method only available in one of the
+input formats. For instance, Oasys provides a byte relocation format.
+A relocation record requesting this relocation type would point
+indirectly to a routine to perform this, so the relocation may be
+performed on a byte being written to a COFF file, even though 68k COFF
+has no such relocation type.
+
+@item line numbers
+Line numbers have to be relocated along with the symbol information.
+Each symbol with an associated list of line number records points to
+the first record of the list. The head of a line number list consists
+of a pointer to the symbol, which allows divination of the address of
+the function who's line number is being described. The rest of the
+list is tuples offsets into the section and line indexes. Any format
+which can simply derive this information can pass it without lossage
+between formats (COFF, IEEE and Oasys).
+@end table
+
+
+@bye
+
+
projects / binutils-gdb.git / commitdiff