Subversion Repositories openrisc

@section Linker Functions

@section Linker Functions

@cindex Linker

@cindex Linker

The linker uses three special entry points in the BFD target

The linker uses three special entry points in the BFD target

vector.  It is not necessary to write special routines for

vector.  It is not necessary to write special routines for

these entry points when creating a new BFD back end, since

these entry points when creating a new BFD back end, since

generic versions are provided.  However, writing them can

generic versions are provided.  However, writing them can

speed up linking and make it use significantly less runtime

speed up linking and make it use significantly less runtime

memory.

memory.

The first routine creates a hash table used by the other

The first routine creates a hash table used by the other

routines.  The second routine adds the symbols from an object

routines.  The second routine adds the symbols from an object

file to the hash table.  The third routine takes all the

file to the hash table.  The third routine takes all the

object files and links them together to create the output

object files and links them together to create the output

file.  These routines are designed so that the linker proper

file.  These routines are designed so that the linker proper

does not need to know anything about the symbols in the object

does not need to know anything about the symbols in the object

files that it is linking.  The linker merely arranges the

files that it is linking.  The linker merely arranges the

sections as directed by the linker script and lets BFD handle

sections as directed by the linker script and lets BFD handle

the details of symbols and relocs.

the details of symbols and relocs.

The second routine and third routines are passed a pointer to

The second routine and third routines are passed a pointer to

a @code{struct bfd_link_info} structure (defined in

a @code{struct bfd_link_info} structure (defined in

@code{bfdlink.h}) which holds information relevant to the link,

@code{bfdlink.h}) which holds information relevant to the link,

including the linker hash table (which was created by the

including the linker hash table (which was created by the

first routine) and a set of callback functions to the linker

first routine) and a set of callback functions to the linker

proper.

proper.

The generic linker routines are in @code{linker.c}, and use the

The generic linker routines are in @code{linker.c}, and use the

header file @code{genlink.h}.  As of this writing, the only back

header file @code{genlink.h}.  As of this writing, the only back

ends which have implemented versions of these routines are

ends which have implemented versions of these routines are

a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}).  The a.out

a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}).  The a.out

routines are used as examples throughout this section.

routines are used as examples throughout this section.

@menu

@menu

* Creating a Linker Hash Table::

* Creating a Linker Hash Table::

* Adding Symbols to the Hash Table::

* Adding Symbols to the Hash Table::

* Performing the Final Link::

* Performing the Final Link::

@end menu

@end menu

@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions

@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions

@subsection Creating a linker hash table

@subsection Creating a linker hash table

@cindex _bfd_link_hash_table_create in target vector

@cindex _bfd_link_hash_table_create in target vector

@cindex target vector (_bfd_link_hash_table_create)

@cindex target vector (_bfd_link_hash_table_create)

The linker routines must create a hash table, which must be

The linker routines must create a hash table, which must be

derived from @code{struct bfd_link_hash_table} described in

derived from @code{struct bfd_link_hash_table} described in

@code{bfdlink.c}.  @xref{Hash Tables}, for information on how to

@code{bfdlink.c}.  @xref{Hash Tables}, for information on how to

create a derived hash table.  This entry point is called using

create a derived hash table.  This entry point is called using

the target vector of the linker output file.

the target vector of the linker output file.

The @code{_bfd_link_hash_table_create} entry point must allocate

The @code{_bfd_link_hash_table_create} entry point must allocate

and initialize an instance of the desired hash table.  If the

and initialize an instance of the desired hash table.  If the

back end does not require any additional information to be

back end does not require any additional information to be

stored with the entries in the hash table, the entry point may

stored with the entries in the hash table, the entry point may

simply create a @code{struct bfd_link_hash_table}.  Most likely,

simply create a @code{struct bfd_link_hash_table}.  Most likely,

however, some additional information will be needed.

however, some additional information will be needed.

For example, with each entry in the hash table the a.out

For example, with each entry in the hash table the a.out

linker keeps the index the symbol has in the final output file

linker keeps the index the symbol has in the final output file

(this index number is used so that when doing a relocatable

(this index number is used so that when doing a relocatable

link the symbol index used in the output file can be quickly

link the symbol index used in the output file can be quickly

filled in when copying over a reloc).  The a.out linker code

filled in when copying over a reloc).  The a.out linker code

defines the required structures and functions for a hash table

defines the required structures and functions for a hash table

derived from @code{struct bfd_link_hash_table}.  The a.out linker

derived from @code{struct bfd_link_hash_table}.  The a.out linker

hash table is created by the function

hash table is created by the function

@code{NAME(aout,link_hash_table_create)}; it simply allocates

@code{NAME(aout,link_hash_table_create)}; it simply allocates

space for the hash table, initializes it, and returns a

space for the hash table, initializes it, and returns a

pointer to it.

pointer to it.

When writing the linker routines for a new back end, you will

When writing the linker routines for a new back end, you will

generally not know exactly which fields will be required until

generally not know exactly which fields will be required until

you have finished.  You should simply create a new hash table

you have finished.  You should simply create a new hash table

which defines no additional fields, and then simply add fields

which defines no additional fields, and then simply add fields

as they become necessary.

as they become necessary.

@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions

@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions

@subsection Adding symbols to the hash table

@subsection Adding symbols to the hash table

@cindex _bfd_link_add_symbols in target vector

@cindex _bfd_link_add_symbols in target vector

@cindex target vector (_bfd_link_add_symbols)

@cindex target vector (_bfd_link_add_symbols)

The linker proper will call the @code{_bfd_link_add_symbols}

The linker proper will call the @code{_bfd_link_add_symbols}

entry point for each object file or archive which is to be

entry point for each object file or archive which is to be

linked (typically these are the files named on the command

linked (typically these are the files named on the command

line, but some may also come from the linker script).  The

line, but some may also come from the linker script).  The

entry point is responsible for examining the file.  For an

entry point is responsible for examining the file.  For an

object file, BFD must add any relevant symbol information to

object file, BFD must add any relevant symbol information to

the hash table.  For an archive, BFD must determine which

the hash table.  For an archive, BFD must determine which

elements of the archive should be used and adding them to the

elements of the archive should be used and adding them to the

link.

link.

The a.out version of this entry point is

The a.out version of this entry point is

@code{NAME(aout,link_add_symbols)}.

@code{NAME(aout,link_add_symbols)}.

@menu

@menu

* Differing file formats::

* Differing file formats::

* Adding symbols from an object file::

* Adding symbols from an object file::

* Adding symbols from an archive::

* Adding symbols from an archive::

@end menu

@end menu

@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table

@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table

@subsubsection Differing file formats

@subsubsection Differing file formats

Normally all the files involved in a link will be of the same

Normally all the files involved in a link will be of the same

format, but it is also possible to link together different

format, but it is also possible to link together different

format object files, and the back end must support that.  The

format object files, and the back end must support that.  The

@code{_bfd_link_add_symbols} entry point is called via the target

@code{_bfd_link_add_symbols} entry point is called via the target

vector of the file to be added.  This has an important

vector of the file to be added.  This has an important

consequence: the function may not assume that the hash table

consequence: the function may not assume that the hash table

is the type created by the corresponding

is the type created by the corresponding

@code{_bfd_link_hash_table_create} vector.  All the

@code{_bfd_link_hash_table_create} vector.  All the

@code{_bfd_link_add_symbols} function can assume about the hash

@code{_bfd_link_add_symbols} function can assume about the hash

table is that it is derived from @code{struct

table is that it is derived from @code{struct

bfd_link_hash_table}.

bfd_link_hash_table}.

Sometimes the @code{_bfd_link_add_symbols} function must store

Sometimes the @code{_bfd_link_add_symbols} function must store

some information in the hash table entry to be used by the

some information in the hash table entry to be used by the

@code{_bfd_final_link} function.  In such a case the output bfd

@code{_bfd_final_link} function.  In such a case the output bfd

xvec must be checked to make sure that the hash table was

xvec must be checked to make sure that the hash table was

created by an object file of the same format.

created by an object file of the same format.

The @code{_bfd_final_link} routine must be prepared to handle a

The @code{_bfd_final_link} routine must be prepared to handle a

hash entry without any extra information added by the

hash entry without any extra information added by the

@code{_bfd_link_add_symbols} function.  A hash entry without

@code{_bfd_link_add_symbols} function.  A hash entry without

extra information will also occur when the linker script

extra information will also occur when the linker script

directs the linker to create a symbol.  Note that, regardless

directs the linker to create a symbol.  Note that, regardless

of how a hash table entry is added, all the fields will be

of how a hash table entry is added, all the fields will be

initialized to some sort of null value by the hash table entry

initialized to some sort of null value by the hash table entry

initialization function.

initialization function.

See @code{ecoff_link_add_externals} for an example of how to

See @code{ecoff_link_add_externals} for an example of how to

check the output bfd before saving information (in this

check the output bfd before saving information (in this

case, the ECOFF external symbol debugging information) in a

case, the ECOFF external symbol debugging information) in a

hash table entry.

hash table entry.

@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table

@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table

@subsubsection Adding symbols from an object file

@subsubsection Adding symbols from an object file

When the @code{_bfd_link_add_symbols} routine is passed an object

When the @code{_bfd_link_add_symbols} routine is passed an object

file, it must add all externally visible symbols in that

file, it must add all externally visible symbols in that

object file to the hash table.  The actual work of adding the

object file to the hash table.  The actual work of adding the

symbol to the hash table is normally handled by the function

symbol to the hash table is normally handled by the function

@code{_bfd_generic_link_add_one_symbol}.  The

@code{_bfd_generic_link_add_one_symbol}.  The

@code{_bfd_link_add_symbols} routine is responsible for reading

@code{_bfd_link_add_symbols} routine is responsible for reading

all the symbols from the object file and passing the correct

all the symbols from the object file and passing the correct

information to @code{_bfd_generic_link_add_one_symbol}.

information to @code{_bfd_generic_link_add_one_symbol}.

The @code{_bfd_link_add_symbols} routine should not use

The @code{_bfd_link_add_symbols} routine should not use

@code{bfd_canonicalize_symtab} to read the symbols.  The point of

@code{bfd_canonicalize_symtab} to read the symbols.  The point of

providing this routine is to avoid the overhead of converting

providing this routine is to avoid the overhead of converting

the symbols into generic @code{asymbol} structures.

the symbols into generic @code{asymbol} structures.

@findex _bfd_generic_link_add_one_symbol

@findex _bfd_generic_link_add_one_symbol

@code{_bfd_generic_link_add_one_symbol} handles the details of

@code{_bfd_generic_link_add_one_symbol} handles the details of

combining common symbols, warning about multiple definitions,

combining common symbols, warning about multiple definitions,

and so forth.  It takes arguments which describe the symbol to

and so forth.  It takes arguments which describe the symbol to

add, notably symbol flags, a section, and an offset.  The

add, notably symbol flags, a section, and an offset.  The

symbol flags include such things as @code{BSF_WEAK} or

symbol flags include such things as @code{BSF_WEAK} or

@code{BSF_INDIRECT}.  The section is a section in the object

@code{BSF_INDIRECT}.  The section is a section in the object

file, or something like @code{bfd_und_section_ptr} for an undefined

file, or something like @code{bfd_und_section_ptr} for an undefined

symbol or @code{bfd_com_section_ptr} for a common symbol.

symbol or @code{bfd_com_section_ptr} for a common symbol.

If the @code{_bfd_final_link} routine is also going to need to

If the @code{_bfd_final_link} routine is also going to need to

read the symbol information, the @code{_bfd_link_add_symbols}

read the symbol information, the @code{_bfd_link_add_symbols}

routine should save it somewhere attached to the object file

routine should save it somewhere attached to the object file

BFD.  However, the information should only be saved if the

BFD.  However, the information should only be saved if the

@code{keep_memory} field of the @code{info} argument is TRUE, so

@code{keep_memory} field of the @code{info} argument is TRUE, so

that the @code{-no-keep-memory} linker switch is effective.

that the @code{-no-keep-memory} linker switch is effective.

The a.out function which adds symbols from an object file is

The a.out function which adds symbols from an object file is

@code{aout_link_add_object_symbols}, and most of the interesting

@code{aout_link_add_object_symbols}, and most of the interesting

work is in @code{aout_link_add_symbols}.  The latter saves

work is in @code{aout_link_add_symbols}.  The latter saves

pointers to the hash tables entries created by

pointers to the hash tables entries created by

@code{_bfd_generic_link_add_one_symbol} indexed by symbol number,

@code{_bfd_generic_link_add_one_symbol} indexed by symbol number,

so that the @code{_bfd_final_link} routine does not have to call

so that the @code{_bfd_final_link} routine does not have to call

the hash table lookup routine to locate the entry.

the hash table lookup routine to locate the entry.

@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table

@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table

@subsubsection Adding symbols from an archive

@subsubsection Adding symbols from an archive

When the @code{_bfd_link_add_symbols} routine is passed an

When the @code{_bfd_link_add_symbols} routine is passed an

archive, it must look through the symbols defined by the

archive, it must look through the symbols defined by the

archive and decide which elements of the archive should be

archive and decide which elements of the archive should be

included in the link.  For each such element it must call the

included in the link.  For each such element it must call the

@code{add_archive_element} linker callback, and it must add the

@code{add_archive_element} linker callback, and it must add the

symbols from the object file to the linker hash table.

symbols from the object file to the linker hash table.

@findex _bfd_generic_link_add_archive_symbols

@findex _bfd_generic_link_add_archive_symbols

In most cases the work of looking through the symbols in the

In most cases the work of looking through the symbols in the

archive should be done by the

archive should be done by the

@code{_bfd_generic_link_add_archive_symbols} function.  This

@code{_bfd_generic_link_add_archive_symbols} function.  This

function builds a hash table from the archive symbol table and

function builds a hash table from the archive symbol table and

looks through the list of undefined symbols to see which

looks through the list of undefined symbols to see which

elements should be included.

elements should be included.

@code{_bfd_generic_link_add_archive_symbols} is passed a function

@code{_bfd_generic_link_add_archive_symbols} is passed a function

to call to make the final decision about adding an archive

to call to make the final decision about adding an archive

element to the link and to do the actual work of adding the

element to the link and to do the actual work of adding the

symbols to the linker hash table.

symbols to the linker hash table.

The function passed to

The function passed to

@code{_bfd_generic_link_add_archive_symbols} must read the

@code{_bfd_generic_link_add_archive_symbols} must read the

symbols of the archive element and decide whether the archive

symbols of the archive element and decide whether the archive

element should be included in the link.  If the element is to

element should be included in the link.  If the element is to

be included, the @code{add_archive_element} linker callback

be included, the @code{add_archive_element} linker callback

routine must be called with the element as an argument, and

routine must be called with the element as an argument, and

the elements symbols must be added to the linker hash table

the elements symbols must be added to the linker hash table

just as though the element had itself been passed to the

just as though the element had itself been passed to the

@code{_bfd_link_add_symbols} function.

@code{_bfd_link_add_symbols} function.

When the a.out @code{_bfd_link_add_symbols} function receives an

When the a.out @code{_bfd_link_add_symbols} function receives an

archive, it calls @code{_bfd_generic_link_add_archive_symbols}

archive, it calls @code{_bfd_generic_link_add_archive_symbols}

passing @code{aout_link_check_archive_element} as the function

passing @code{aout_link_check_archive_element} as the function

argument. @code{aout_link_check_archive_element} calls

argument. @code{aout_link_check_archive_element} calls

@code{aout_link_check_ar_symbols}.  If the latter decides to add

@code{aout_link_check_ar_symbols}.  If the latter decides to add

the element (an element is only added if it provides a real,

the element (an element is only added if it provides a real,

non-common, definition for a previously undefined or common

non-common, definition for a previously undefined or common

symbol) it calls the @code{add_archive_element} callback and then

symbol) it calls the @code{add_archive_element} callback and then

@code{aout_link_check_archive_element} calls

@code{aout_link_check_archive_element} calls

@code{aout_link_add_symbols} to actually add the symbols to the

@code{aout_link_add_symbols} to actually add the symbols to the

linker hash table.

linker hash table.

The ECOFF back end is unusual in that it does not normally

The ECOFF back end is unusual in that it does not normally

call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF

call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF

archives already contain a hash table of symbols.  The ECOFF

archives already contain a hash table of symbols.  The ECOFF

back end searches the archive itself to avoid the overhead of

back end searches the archive itself to avoid the overhead of

creating a new hash table.

creating a new hash table.

@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions

@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions

@subsection Performing the final link

@subsection Performing the final link

@cindex _bfd_link_final_link in target vector

@cindex _bfd_link_final_link in target vector

@cindex target vector (_bfd_final_link)

@cindex target vector (_bfd_final_link)

When all the input files have been processed, the linker calls

When all the input files have been processed, the linker calls

the @code{_bfd_final_link} entry point of the output BFD.  This

the @code{_bfd_final_link} entry point of the output BFD.  This

routine is responsible for producing the final output file,

routine is responsible for producing the final output file,

which has several aspects.  It must relocate the contents of

which has several aspects.  It must relocate the contents of

the input sections and copy the data into the output sections.

the input sections and copy the data into the output sections.

It must build an output symbol table including any local

It must build an output symbol table including any local

symbols from the input files and the global symbols from the

symbols from the input files and the global symbols from the

hash table.  When producing relocatable output, it must

hash table.  When producing relocatable output, it must

modify the input relocs and write them into the output file.

modify the input relocs and write them into the output file.

There may also be object format dependent work to be done.

There may also be object format dependent work to be done.

The linker will also call the @code{write_object_contents} entry

The linker will also call the @code{write_object_contents} entry

point when the BFD is closed.  The two entry points must work

point when the BFD is closed.  The two entry points must work

together in order to produce the correct output file.

together in order to produce the correct output file.

The details of how this works are inevitably dependent upon

The details of how this works are inevitably dependent upon

the specific object file format.  The a.out

the specific object file format.  The a.out

@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}.

@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}.

@menu

@menu

* Information provided by the linker::

* Information provided by the linker::

* Relocating the section contents::

* Relocating the section contents::

* Writing the symbol table::

* Writing the symbol table::

@end menu

@end menu

@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link

@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link

@subsubsection Information provided by the linker

@subsubsection Information provided by the linker

Before the linker calls the @code{_bfd_final_link} entry point,

Before the linker calls the @code{_bfd_final_link} entry point,

it sets up some data structures for the function to use.

it sets up some data structures for the function to use.

The @code{input_bfds} field of the @code{bfd_link_info} structure

The @code{input_bfds} field of the @code{bfd_link_info} structure

will point to a list of all the input files included in the

will point to a list of all the input files included in the

link.  These files are linked through the @code{link_next} field

link.  These files are linked through the @code{link_next} field

of the @code{bfd} structure.

of the @code{bfd} structure.

Each section in the output file will have a list of

Each section in the output file will have a list of

@code{link_order} structures attached to the @code{map_head.link_order}

@code{link_order} structures attached to the @code{map_head.link_order}

field (the @code{link_order} structure is defined in

field (the @code{link_order} structure is defined in

@code{bfdlink.h}).  These structures describe how to create the

@code{bfdlink.h}).  These structures describe how to create the

contents of the output section in terms of the contents of

contents of the output section in terms of the contents of

various input sections, fill constants, and, eventually, other

various input sections, fill constants, and, eventually, other

types of information.  They also describe relocs that must be

types of information.  They also describe relocs that must be

created by the BFD backend, but do not correspond to any input

created by the BFD backend, but do not correspond to any input

file; this is used to support -Ur, which builds constructors

file; this is used to support -Ur, which builds constructors

while generating a relocatable object file.

while generating a relocatable object file.

@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link

@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link

@subsubsection Relocating the section contents

@subsubsection Relocating the section contents

The @code{_bfd_final_link} function should look through the

The @code{_bfd_final_link} function should look through the

@code{link_order} structures attached to each section of the

@code{link_order} structures attached to each section of the

output file.  Each @code{link_order} structure should either be

output file.  Each @code{link_order} structure should either be

handled specially, or it should be passed to the function

handled specially, or it should be passed to the function

@code{_bfd_default_link_order} which will do the right thing

@code{_bfd_default_link_order} which will do the right thing

(@code{_bfd_default_link_order} is defined in @code{linker.c}).

(@code{_bfd_default_link_order} is defined in @code{linker.c}).

For efficiency, a @code{link_order} of type

For efficiency, a @code{link_order} of type

@code{bfd_indirect_link_order} whose associated section belongs

@code{bfd_indirect_link_order} whose associated section belongs

to a BFD of the same format as the output BFD must be handled

to a BFD of the same format as the output BFD must be handled

specially.  This type of @code{link_order} describes part of an

specially.  This type of @code{link_order} describes part of an

output section in terms of a section belonging to one of the

output section in terms of a section belonging to one of the

input files.  The @code{_bfd_final_link} function should read the

input files.  The @code{_bfd_final_link} function should read the

contents of the section and any associated relocs, apply the

contents of the section and any associated relocs, apply the

relocs to the section contents, and write out the modified

relocs to the section contents, and write out the modified

section contents.  If performing a relocatable link, the

section contents.  If performing a relocatable link, the

relocs themselves must also be modified and written out.

relocs themselves must also be modified and written out.

@findex _bfd_relocate_contents

@findex _bfd_relocate_contents

@findex _bfd_final_link_relocate

@findex _bfd_final_link_relocate

The functions @code{_bfd_relocate_contents} and

The functions @code{_bfd_relocate_contents} and

@code{_bfd_final_link_relocate} provide some general support for

@code{_bfd_final_link_relocate} provide some general support for

performing the actual relocations, notably overflow checking.

performing the actual relocations, notably overflow checking.

Their arguments include information about the symbol the

Their arguments include information about the symbol the

relocation is against and a @code{reloc_howto_type} argument

relocation is against and a @code{reloc_howto_type} argument

which describes the relocation to perform.  These functions

which describes the relocation to perform.  These functions

are defined in @code{reloc.c}.

are defined in @code{reloc.c}.

The a.out function which handles reading, relocating, and

The a.out function which handles reading, relocating, and

writing section contents is @code{aout_link_input_section}.  The

writing section contents is @code{aout_link_input_section}.  The

actual relocation is done in @code{aout_link_input_section_std}

actual relocation is done in @code{aout_link_input_section_std}

and @code{aout_link_input_section_ext}.

and @code{aout_link_input_section_ext}.

@node Writing the symbol table, , Relocating the section contents, Performing the Final Link

@node Writing the symbol table, , Relocating the section contents, Performing the Final Link

@subsubsection Writing the symbol table

@subsubsection Writing the symbol table

The @code{_bfd_final_link} function must gather all the symbols

The @code{_bfd_final_link} function must gather all the symbols

in the input files and write them out.  It must also write out

in the input files and write them out.  It must also write out

all the symbols in the global hash table.  This must be

all the symbols in the global hash table.  This must be

controlled by the @code{strip} and @code{discard} fields of the

controlled by the @code{strip} and @code{discard} fields of the

@code{bfd_link_info} structure.

@code{bfd_link_info} structure.

The local symbols of the input files will not have been

The local symbols of the input files will not have been

entered into the linker hash table.  The @code{_bfd_final_link}

entered into the linker hash table.  The @code{_bfd_final_link}

routine must consider each input file and include the symbols

routine must consider each input file and include the symbols

in the output file.  It may be convenient to do this when

in the output file.  It may be convenient to do this when

looking through the @code{link_order} structures, or it may be

looking through the @code{link_order} structures, or it may be

done by stepping through the @code{input_bfds} list.

done by stepping through the @code{input_bfds} list.

The @code{_bfd_final_link} routine must also traverse the global

The @code{_bfd_final_link} routine must also traverse the global

hash table to gather all the externally visible symbols.  It

hash table to gather all the externally visible symbols.  It

is possible that most of the externally visible symbols may be

is possible that most of the externally visible symbols may be

written out when considering the symbols of each input file,

written out when considering the symbols of each input file,

but it is still necessary to traverse the hash table since the

but it is still necessary to traverse the hash table since the

linker script may have defined some symbols that are not in

linker script may have defined some symbols that are not in

any of the input files.

any of the input files.

The @code{strip} field of the @code{bfd_link_info} structure

The @code{strip} field of the @code{bfd_link_info} structure

controls which symbols are written out.  The possible values

controls which symbols are written out.  The possible values

are listed in @code{bfdlink.h}.  If the value is @code{strip_some},

are listed in @code{bfdlink.h}.  If the value is @code{strip_some},

then the @code{keep_hash} field of the @code{bfd_link_info}

then the @code{keep_hash} field of the @code{bfd_link_info}

structure is a hash table of symbols to keep; each symbol

structure is a hash table of symbols to keep; each symbol

should be looked up in this hash table, and only symbols which

should be looked up in this hash table, and only symbols which

are present should be included in the output file.

are present should be included in the output file.

If the @code{strip} field of the @code{bfd_link_info} structure

If the @code{strip} field of the @code{bfd_link_info} structure

permits local symbols to be written out, the @code{discard} field

permits local symbols to be written out, the @code{discard} field

is used to further controls which local symbols are included

is used to further controls which local symbols are included

in the output file.  If the value is @code{discard_l}, then all

in the output file.  If the value is @code{discard_l}, then all

local symbols which begin with a certain prefix are discarded;

local symbols which begin with a certain prefix are discarded;

this is controlled by the @code{bfd_is_local_label_name} entry point.

this is controlled by the @code{bfd_is_local_label_name} entry point.

The a.out backend handles symbols by calling

The a.out backend handles symbols by calling

@code{aout_link_write_symbols} on each input BFD and then

@code{aout_link_write_symbols} on each input BFD and then

traversing the global hash table with the function

traversing the global hash table with the function

@code{aout_link_write_other_symbol}.  It builds a string table

@code{aout_link_write_other_symbol}.  It builds a string table

while writing out the symbols, which is written to the output

while writing out the symbols, which is written to the output

file at the end of @code{NAME(aout,final_link)}.

file at the end of @code{NAME(aout,final_link)}.

@findex bfd_link_split_section

@findex bfd_link_split_section

@subsubsection @code{bfd_link_split_section}

@subsubsection @code{bfd_link_split_section}

@strong{Synopsis}

@strong{Synopsis}

@example

@example

bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec);

bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec);

@end example

@end example

@strong{Description}@*

@strong{Description}@*

Return nonzero if @var{sec} should be split during a

Return nonzero if @var{sec} should be split during a

reloceatable or final link.

reloceatable or final link.

@example

@example

#define bfd_link_split_section(abfd, sec) \

#define bfd_link_split_section(abfd, sec) \

       BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

       BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

@end example

@end example

@findex bfd_section_already_linked

@findex bfd_section_already_linked

@subsubsection @code{bfd_section_already_linked}

@subsubsection @code{bfd_section_already_linked}

@strong{Synopsis}

@strong{Synopsis}

@example

@example

void bfd_section_already_linked (bfd *abfd, asection *sec,

void bfd_section_already_linked (bfd *abfd, asection *sec,

    struct bfd_link_info *info);

    struct bfd_link_info *info);

@end example

@end example

@strong{Description}@*

@strong{Description}@*

Check if @var{sec} has been already linked during a reloceatable

Check if @var{sec} has been already linked during a reloceatable

or final link.

or final link.

@example

@example

#define bfd_section_already_linked(abfd, sec, info) \

#define bfd_section_already_linked(abfd, sec, info) \

       BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))

       BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))

@end example

@end example