Initial revision

[deliverable/binutils-gdb.git] / ld / ld.texinfo

\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