Linker Functions
================

The linker uses three special entry points in the BFD target vector.  It is not necessary to write special routines for these entry points when creating a new BFD back end, since generic versions are provided.  However, writing them can speed up linking and make it use significantly less runtime memory.

The first routine creates a hash table used by the other routines.  The second routine adds the symbols from an object file to the hash table.  The third routine takes all the object files and links them together to create the output file.  These routines are designed so that the linker proper does not need to know anything about the symbols in the object files that it is linking.  The linker merely arranges the sections as directed by the linker script and lets BFD handle the details of symbols and relocs.

The second routine and third routines are passed a pointer to a struct bfd_link_info structure (defined in bfdlink.h) which holds information relevant to the link, including the linker hash table (which was created by the first routine) and a set of callback functions to the linker proper.

The generic linker routines are in linker.c, and use the header file genlink.h.  As of this writing, the only back ends which have implemented versions of these routines are a.out (in aoutx.h) and ECOFF (in ecoff.c).  The a.out routines are used as examples throughout this section.

Creating a linker hash table
----------------------------

The linker routines must create a hash table, which must be derived from struct bfd_link_hash_table described in bfdlink.c.  See Hash Tables, for information on how to create a derived hash table.  This entry point is called using the target vector of the linker output file.

The _bfd_link_hash_table_create entry point must allocate and initialize an instance of the desired hash table.  If the back end does not require any additional information to be stored with the entries in the hash table, the entry point may simply create a struct bfd_link_hash_table.  Most likely, however, some additional information will be needed.

For example, with each entry in the hash table the a.out linker keeps the index the symbol has in the final output file (this index number is used so that when doing a relocatable link the symbol index used in the output file can be quickly filled in when copying over a reloc).  The a.out linker code defines the required structures and functions for a hash table derived from struct bfd_link_hash_table.  The a.out linker hash table is created by the function NAME(aout,link_hash_table_create); it simply allocates space for the hash table, initializes it, and returns a pointer to it.

When writing the linker routines for a new back end, you will generally not know exactly which fields will be required until you have finished.  You should simply create a new hash table which defines no additional fields, and then simply add fields as they become necessary.

Adding symbols to the hash table
--------------------------------

The linker proper will call the _bfd_link_add_symbols entry point for each object file or archive which is to be linked (typically these are the files named on the command line, but some may also come from the linker script).  The entry point is responsible for examining the file.  For an object file, BFD must add any relevant symbol information to the hash table.  For an archive, BFD must determine which elements of the archive should be used and adding them to the link.

The a.out version of this entry point is NAME(aout,link_add_symbols).

Differing file formats
......................

Normally all the files involved in a link will be of the same format, but it is also possible to link together different format object files, and the back end must support that.  The _bfd_link_add_symbols entry point is called via the target vector of the file to be added.  This has an important consequence: the function may not assume that the hash table is the type created by the corresponding _bfd_link_hash_table_create vector.  All the _bfd_link_add_symbols function can assume about the hash table is that it is derived from struct bfd_link_hash_table.

Sometimes the _bfd_link_add_symbols function must store some information in the hash table entry to be used by the _bfd_final_link function.  In such a case the output bfd xvec must be checked to make sure that the hash table was created by an object file of the same format.

The _bfd_final_link routine must be prepared to handle a hash entry without any extra information added by the _bfd_link_add_symbols function.  A hash entry without extra information will also occur when the linker script directs the linker to create a symbol.  Note that, regardless 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 initialization function.

See ecoff_link_add_externals for an example of how to check the output bfd before saving information (in this case, the ECOFF external symbol debugging information) in a hash table entry.

Adding symbols from an object file
..................................

When the _bfd_link_add_symbols routine is passed an object file, it must add all externally visible symbols in that object file to the hash table.  The actual work of adding the symbol to the hash table is normally handled by the function _bfd_generic_link_add_one_symbol.  The _bfd_link_add_symbols routine is responsible for reading all the symbols from the object file and passing the correct information to _bfd_generic_link_add_one_symbol.

The _bfd_link_add_symbols routine should not use bfd_canonicalize_symtab to read the symbols.  The point of providing this routine is to avoid the overhead of converting the symbols into generic asymbol structures.

_bfd_generic_link_add_one_symbol handles the details of combining common symbols, warning about multiple definitions, and so forth.  It takes arguments which describe the symbol to add, notably symbol flags, a section, and an offset.  The symbol flags include such things as BSF_WEAK or BSF_INDIRECT.  The section is a section in the object file, or something like bfd_und_section_ptr for an undefined symbol or bfd_com_section_ptr for a common symbol.

If the _bfd_final_link routine is also going to need to read the symbol information, the _bfd_link_add_symbols routine should save it somewhere attached to the object file BFD.  However, the information should only be saved if the keep_memory field of the info argument is TRUE, so that the -no-keep-memory linker switch is effective.

The a.out function which adds symbols from an object file is aout_link_add_object_symbols, and most of the interesting work is in aout_link_add_symbols.  The latter saves pointers to the hash tables entries created by _bfd_generic_link_add_one_symbol indexed by symbol number, so that the _bfd_final_link routine does not have to call the hash table lookup routine to locate the entry.

Adding symbols from an archive
..............................

When the _bfd_link_add_symbols routine is passed an archive, it must look through the symbols defined by the archive and decide which elements of the archive should be included in the link.  For each such element it must call the add_archive_element linker callback, and it must add the symbols from the object file to the linker hash table.  (The callback may in fact indicate that a replacement BFD should be used, in which case the symbols from that BFD should be added to the linker hash table instead.)

In most cases the work of looking through the symbols in the archive should be done by the _bfd_generic_link_add_archive_symbols function. _bfd_generic_link_add_archive_symbols is passed a function to call to make the final decision about adding an archive element to the link and to do the actual work of adding the symbols to the linker hash table.  If the element is to be included, the add_archive_element linker callback routine must be called with the element as an argument, and the element's symbols must be added to the linker hash table just as though the element had itself been passed to the _bfd_link_add_symbols function.

When the a.out _bfd_link_add_symbols function receives an archive, it calls _bfd_generic_link_add_archive_symbols passing aout_link_check_archive_element as the function argument. aout_link_check_archive_element calls aout_link_check_ar_symbols.  If the latter decides to add the element (an element is only added if it provides a real, non-common, definition for a previously undefined or common symbol) it calls the add_archive_element callback and then aout_link_check_archive_element calls aout_link_add_symbols to actually add the symbols to the linker hash table - possibly those of a substitute BFD, if the add_archive_element callback avails itself of that option.

The ECOFF back end is unusual in that it does not normally call _bfd_generic_link_add_archive_symbols, because ECOFF archives already contain a hash table of symbols.  The ECOFF back end searches the archive itself to avoid the overhead of creating a new hash table.

Performing the final link
-------------------------

When all the input files have been processed, the linker calls the _bfd_final_link entry point of the output BFD.  This routine is responsible for producing the final output file, which has several aspects.  It must relocate the contents of the input sections and copy the data into the output sections. It must build an output symbol table including any local symbols from the input files and the global symbols from the hash table.  When producing relocatable output, it must modify the input relocs and write them into the output file. There may also be object format dependent work to be done.

The linker will also call the write_object_contents entry point when the BFD is closed.  The two entry points must work together in order to produce the correct output file.

The details of how this works are inevitably dependent upon the specific object file format.  The a.out _bfd_final_link routine is NAME(aout,final_link).

Information provided by the linker
..................................

Before the linker calls the _bfd_final_link entry point, it sets up some data structures for the function to use.

The input_bfds field of the bfd_link_info structure will point to a list of all the input files included in the link.  These files are linked through the link.next field of the bfd structure.

Each section in the output file will have a list of link_order structures attached to the map_head.link_order field (the link_order structure is defined in bfdlink.h).  These structures describe how to create the contents of the output section in terms of the contents of various input sections, fill constants, and, eventually, other types of information.  They also describe relocs that must be created by the BFD backend, but do not correspond to any input file; this is used to support -Ur, which builds constructors while generating a relocatable object file.

Relocating the section contents
...............................

The _bfd_final_link function should look through the link_order structures attached to each section of the output file.  Each link_order structure should either be handled specially, or it should be passed to the function _bfd_default_link_order which will do the right thing (_bfd_default_link_order is defined in linker.c).

For efficiency, a link_order of type bfd_indirect_link_order whose associated section belongs to a BFD of the same format as the output BFD must be handled specially.  This type of link_order describes part of an output section in terms of a section belonging to one of the input files.  The _bfd_final_link function should read the contents of the section and any associated relocs, apply the relocs to the section contents, and write out the modified section contents.  If performing a relocatable link, the relocs themselves must also be modified and written out.

The functions _bfd_relocate_contents and _bfd_final_link_relocate provide some general support for performing the actual relocations, notably overflow checking. Their arguments include information about the symbol the relocation is against and a reloc_howto_type argument which describes the relocation to perform.  These functions are defined in reloc.c.

The a.out function which handles reading, relocating, and writing section contents is aout_link_input_section.  The actual relocation is done in aout_link_input_section_std and aout_link_input_section_ext.

Writing the symbol table
........................

The _bfd_final_link function must gather all the symbols in the input files and write them out.  It must also write out all the symbols in the global hash table.  This must be controlled by the strip and discard fields of the bfd_link_info structure.

The local symbols of the input files will not have been entered into the linker hash table.  The _bfd_final_link routine must consider each input file and include the symbols in the output file.  It may be convenient to do this when looking through the link_order structures, or it may be done by stepping through the input_bfds list.

The _bfd_final_link routine must also traverse the global hash table to gather all the externally visible symbols.  It is possible that most of the externally visible symbols may be written out when considering the symbols of each input file, but it is still necessary to traverse the hash table since the linker script may have defined some symbols that are not in any of the input files.

The strip field of the bfd_link_info structure controls which symbols are written out.  The possible values are listed in bfdlink.h.  If the value is strip_some, then the keep_hash field of the bfd_link_info structure is a hash table of symbols to keep; each symbol should be looked up in this hash table, and only symbols which are present should be included in the output file.

If the strip field of the bfd_link_info structure permits local symbols to be written out, the discard field is used to further controls which local symbols are included in the output file.  If the value is discard_l, then all local symbols which begin with a certain prefix are discarded; this is controlled by the bfd_is_local_label_name entry point.

The a.out backend handles symbols by calling aout_link_write_symbols on each input BFD and then traversing the global hash table with the function aout_link_write_other_symbol.  It builds a string table while writing out the symbols, which is written to the output file at the end of NAME(aout,final_link).

bfd_link_split_section
......................

Synopsis

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

Description

Return nonzero if SEC should be split during a reloceatable or final link.

     #define bfd_link_split_section(abfd, sec) \
            BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

bfd_section_already_linked
..........................

Synopsis

     bfd_boolean bfd_section_already_linked (bfd *abfd,
         asection *sec,
         struct bfd_link_info *info);

Description

Check if DATA has been already linked during a reloceatable or final link.  Return TRUE if it has.

     #define bfd_section_already_linked(abfd, sec, info) \
            BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))

bfd_generic_define_common_symbol
................................

Synopsis

     bfd_boolean bfd_generic_define_common_symbol
        (bfd *output_bfd, struct bfd_link_info *info,
         struct bfd_link_hash_entry *h);

Description

Convert common symbol H into a defined symbol. Return TRUE on success and FALSE on failure.

     #define bfd_define_common_symbol(output_bfd, info, h) \
            BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h))

bfd_find_version_for_sym
........................

Synopsis

     struct bfd_elf_version_tree * bfd_find_version_for_sym
        (struct bfd_elf_version_tree *verdefs,
         const char *sym_name, bfd_boolean *hide);

Description

Search an elf version script tree for symbol versioning info and export / don't-export status for a given symbol. Return non-NULL on success and NULL on failure; also sets the output hide boolean parameter.

bfd_hide_sym_by_version
.......................

Synopsis

     bfd_boolean bfd_hide_sym_by_version
        (struct bfd_elf_version_tree *verdefs, const char *sym_name);

Description

Search an elf version script tree for symbol versioning info for a given symbol.  Return TRUE if the symbol is hidden.

bfd_link_check_relocs
.....................

Synopsis

     bfd_boolean bfd_link_check_relocs
        (bfd *abfd, struct bfd_link_info *info);

Description

Checks the relocs in ABFD for validity. Does not execute the relocs. Return TRUE if everything is OK, FALSE otherwise. This is the external entry point to this code.

_bfd_generic_link_check_relocs
..............................

Synopsis

     bfd_boolean _bfd_generic_link_check_relocs
        (bfd *abfd, struct bfd_link_info *info);

Description

Stub function for targets that do not implement reloc checking. Return TRUE. This is an internal function.  It should not be called from outside the BFD library.

bfd_merge_private_bfd_data
..........................

Synopsis

     bfd_boolean bfd_merge_private_bfd_data
        (bfd *ibfd, struct bfd_link_info *info);

Description

Merge private BFD information from the BFD IBFD to the the output file BFD when linking.  Return TRUE on success, FALSE on error.  Possible error returns are:

  * bfd_error_no_memory - Not enough memory exists to create private data for OBFD.

     #define bfd_merge_private_bfd_data(ibfd, info) \
          BFD_SEND ((info)->output_bfd, _bfd_merge_private_bfd_data, \
                    (ibfd, info))

_bfd_generic_verify_endian_match
................................

Synopsis

     bfd_boolean _bfd_generic_verify_endian_match
        (bfd *ibfd, struct bfd_link_info *info);

Description

Can be used from / for bfd_merge_private_bfd_data to check that endianness matches between input and output file.  Returns TRUE for a match, otherwise returns FALSE and emits an error.