| @section Linker Functions |
| @cindex Linker |
| 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 @code{struct bfd_link_info} structure (defined in |
| @code{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 @code{linker.c}, and use the |
| header file @code{genlink.h}. As of this writing, the only back |
| ends which have implemented versions of these routines are |
| a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out |
| routines are used as examples throughout this section. |
| |
| @menu |
| * Creating a Linker Hash Table:: |
| * Adding Symbols to the Hash Table:: |
| * Performing the Final Link:: |
| @end menu |
| |
| @node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions |
| @subsection Creating a linker hash table |
| @cindex _bfd_link_hash_table_create in target vector |
| @cindex target vector (_bfd_link_hash_table_create) |
| The linker routines must create a hash table, which must be |
| derived from @code{struct bfd_link_hash_table} described in |
| @code{bfdlink.c}. @xref{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 @code{_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 @code{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 relocateable |
| 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 @code{struct bfd_link_hash_table}. The a.out linker |
| hash table is created by the function |
| @code{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. |
| |
| @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 |
| @cindex _bfd_link_add_symbols in target vector |
| @cindex target vector (_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 |
| 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 |
| @code{NAME(aout,link_add_symbols)}. |
| |
| @menu |
| * Differing file formats:: |
| * Adding symbols from an object file:: |
| * Adding symbols from an archive:: |
| @end menu |
| |
| @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 |
| 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 |
| @code{_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 |
| @code{_bfd_link_hash_table_create} vector. All the |
| @code{_bfd_link_add_symbols} function can assume about the hash |
| table is that it is derived from @code{struct |
| bfd_link_hash_table}. |
| |
| Sometimes the @code{_bfd_link_add_symbols} function must store |
| some information in the hash table entry to be used by the |
| @code{_bfd_final_link} function. In such a case the @code{creator} |
| field of the hash table must be checked to make sure that the |
| hash table was created by an object file of the same format. |
| |
| The @code{_bfd_final_link} routine must be prepared to handle a |
| hash entry without any extra information added by the |
| @code{_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 @code{ecoff_link_add_externals} for an example of how to |
| check the @code{creator} field before saving information (in this |
| case, the ECOFF external symbol debugging information) in a |
| hash table entry. |
| |
| @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 |
| When the @code{_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 |
| @code{_bfd_generic_link_add_one_symbol}. The |
| @code{_bfd_link_add_symbols} routine is responsible for reading |
| all the symbols from the object file and passing the correct |
| information to @code{_bfd_generic_link_add_one_symbol}. |
| |
| The @code{_bfd_link_add_symbols} routine should not use |
| @code{bfd_canonicalize_symtab} to read the symbols. The point of |
| providing this routine is to avoid the overhead of converting |
| the symbols into generic @code{asymbol} structures. |
| |
| @findex _bfd_generic_link_add_one_symbol |
| @code{_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 @code{BSF_WEAK} or |
| @code{BSF_INDIRECT}. The section is a section in the object |
| file, or something like @code{bfd_und_section_ptr} for an undefined |
| symbol or @code{bfd_com_section_ptr} for a common symbol. |
| |
| If the @code{_bfd_final_link} routine is also going to need to |
| read the symbol information, the @code{_bfd_link_add_symbols} |
| routine should save it somewhere attached to the object file |
| BFD. However, the information should only be saved if the |
| @code{keep_memory} field of the @code{info} argument is true, so |
| that the @code{-no-keep-memory} linker switch is effective. |
| |
| The a.out function which adds symbols from an object file is |
| @code{aout_link_add_object_symbols}, and most of the interesting |
| work is in @code{aout_link_add_symbols}. The latter saves |
| pointers to the hash tables entries created by |
| @code{_bfd_generic_link_add_one_symbol} indexed by symbol number, |
| so that the @code{_bfd_final_link} routine does not have to call |
| 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 |
| @subsubsection Adding symbols from an archive |
| When the @code{_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 |
| @code{add_archive_element} linker callback, and it must add the |
| symbols from the object file to the linker hash table. |
| |
| @findex _bfd_generic_link_add_archive_symbols |
| In most cases the work of looking through the symbols in the |
| archive should be done by the |
| @code{_bfd_generic_link_add_archive_symbols} function. This |
| function builds a hash table from the archive symbol table and |
| looks through the list of undefined symbols to see which |
| elements should be included. |
| @code{_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. |
| |
| The function passed to |
| @code{_bfd_generic_link_add_archive_symbols} must read the |
| symbols of the archive element and decide whether the archive |
| element should be included in the link. If the element is to |
| be included, the @code{add_archive_element} linker callback |
| routine must be called with the element as an argument, and |
| the elements symbols must be added to the linker hash table |
| just as though the element had itself been passed to the |
| @code{_bfd_link_add_symbols} function. |
| |
| When the a.out @code{_bfd_link_add_symbols} function receives an |
| archive, it calls @code{_bfd_generic_link_add_archive_symbols} |
| passing @code{aout_link_check_archive_element} as the function |
| argument. @code{aout_link_check_archive_element} calls |
| @code{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 @code{add_archive_element} callback and then |
| @code{aout_link_check_archive_element} calls |
| @code{aout_link_add_symbols} to actually add the symbols to the |
| linker hash table. |
| |
| The ECOFF back end is unusual in that it does not normally |
| call @code{_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. |
| |
| @node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions |
| @subsection Performing the final link |
| @cindex _bfd_link_final_link in target vector |
| @cindex target vector (_bfd_final_link) |
| When all the input files have been processed, the linker calls |
| the @code{_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 relocateable 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 @code{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 |
| @code{_bfd_final_link} routine is @code{NAME(aout,final_link)}. |
| |
| @menu |
| * Information provided by the linker:: |
| * Relocating the section contents:: |
| * Writing the symbol table:: |
| @end menu |
| |
| @node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link |
| @subsubsection Information provided by the linker |
| Before the linker calls the @code{_bfd_final_link} entry point, |
| it sets up some data structures for the function to use. |
| |
| 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 |
| link. These files are linked through the @code{link_next} field |
| of the @code{bfd} structure. |
| |
| Each section in the output file will have a list of |
| @code{link_order} structures attached to the @code{link_order_head} |
| field (the @code{link_order} structure is defined in |
| @code{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 relocateable object file. |
| |
| @node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link |
| @subsubsection Relocating the section contents |
| The @code{_bfd_final_link} function should look through the |
| @code{link_order} structures attached to each section of the |
| output file. Each @code{link_order} structure should either be |
| 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} is defined in @code{linker.c}). |
| |
| For efficiency, a @code{link_order} of type |
| @code{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 @code{link_order} describes part of an |
| output section in terms of a section belonging to one of the |
| input files. The @code{_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 relocateable link, the |
| relocs themselves must also be modified and written out. |
| |
| @findex _bfd_relocate_contents |
| @findex _bfd_final_link_relocate |
| The functions @code{_bfd_relocate_contents} and |
| @code{_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 @code{reloc_howto_type} argument |
| which describes the relocation to perform. These functions |
| are defined in @code{reloc.c}. |
| |
| The a.out function which handles reading, relocating, and |
| writing section contents is @code{aout_link_input_section}. The |
| actual relocation is done in @code{aout_link_input_section_std} |
| and @code{aout_link_input_section_ext}. |
| |
| @node Writing the symbol table, , Relocating the section contents, Performing the Final Link |
| @subsubsection Writing the symbol table |
| The @code{_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 @code{strip} and @code{discard} fields of the |
| @code{bfd_link_info} structure. |
| |
| The local symbols of the input files will not have been |
| entered into the linker hash table. The @code{_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 @code{link_order} structures, or it may be |
| done by stepping through the @code{input_bfds} list. |
| |
| The @code{_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 @code{strip} field of the @code{bfd_link_info} structure |
| controls which symbols are written out. The possible values |
| 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} |
| 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 @code{strip} field of the @code{bfd_link_info} structure |
| permits local symbols to be written out, the @code{discard} field |
| is used to further controls which local symbols are included |
| in the output file. If the value is @code{discard_l}, then all |
| local symbols which begin with a certain prefix are discarded; |
| this is controlled by the @code{bfd_is_local_label_name} entry point. |
| |
| The a.out backend handles symbols by calling |
| @code{aout_link_write_symbols} on each input BFD and then |
| traversing the global hash table with the function |
| @code{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 @code{NAME(aout,final_link)}. |
| |
| @findex bfd_link_split_section |
| @subsubsection @code{bfd_link_split_section} |
| @strong{Synopsis} |
| @example |
| boolean bfd_link_split_section(bfd *abfd, asection *sec); |
| @end example |
| @strong{Description}@* |
| Return nonzero if @var{sec} should be split during a |
| reloceatable or final link. |
| @example |
| #define bfd_link_split_section(abfd, sec) \ |
| BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) |
| |
| @end example |
| |