linker.texi revision 1.1.1.1
1@section Linker Functions 2@cindex Linker 3The linker uses three special entry points in the BFD target 4vector. It is not necessary to write special routines for 5these entry points when creating a new BFD back end, since 6generic versions are provided. However, writing them can 7speed up linking and make it use significantly less runtime 8memory. 9 10The first routine creates a hash table used by the other 11routines. The second routine adds the symbols from an object 12file to the hash table. The third routine takes all the 13object files and links them together to create the output 14file. These routines are designed so that the linker proper 15does not need to know anything about the symbols in the object 16files that it is linking. The linker merely arranges the 17sections as directed by the linker script and lets BFD handle 18the details of symbols and relocs. 19 20The second routine and third routines are passed a pointer to 21a @code{struct bfd_link_info} structure (defined in 22@code{bfdlink.h}) which holds information relevant to the link, 23including the linker hash table (which was created by the 24first routine) and a set of callback functions to the linker 25proper. 26 27The generic linker routines are in @code{linker.c}, and use the 28header file @code{genlink.h}. As of this writing, the only back 29ends which have implemented versions of these routines are 30a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out 31routines are used as examples throughout this section. 32 33@menu 34* Creating a Linker Hash Table:: 35* Adding Symbols to the Hash Table:: 36* Performing the Final Link:: 37@end menu 38 39@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions 40@subsection Creating a linker hash table 41@cindex _bfd_link_hash_table_create in target vector 42@cindex target vector (_bfd_link_hash_table_create) 43The linker routines must create a hash table, which must be 44derived from @code{struct bfd_link_hash_table} described in 45@code{bfdlink.c}. @xref{Hash Tables}, for information on how to 46create a derived hash table. This entry point is called using 47the target vector of the linker output file. 48 49The @code{_bfd_link_hash_table_create} entry point must allocate 50and initialize an instance of the desired hash table. If the 51back end does not require any additional information to be 52stored with the entries in the hash table, the entry point may 53simply create a @code{struct bfd_link_hash_table}. Most likely, 54however, some additional information will be needed. 55 56For example, with each entry in the hash table the a.out 57linker keeps the index the symbol has in the final output file 58(this index number is used so that when doing a relocatable 59link the symbol index used in the output file can be quickly 60filled in when copying over a reloc). The a.out linker code 61defines the required structures and functions for a hash table 62derived from @code{struct bfd_link_hash_table}. The a.out linker 63hash table is created by the function 64@code{NAME(aout,link_hash_table_create)}; it simply allocates 65space for the hash table, initializes it, and returns a 66pointer to it. 67 68When writing the linker routines for a new back end, you will 69generally not know exactly which fields will be required until 70you have finished. You should simply create a new hash table 71which defines no additional fields, and then simply add fields 72as they become necessary. 73 74@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions 75@subsection Adding symbols to the hash table 76@cindex _bfd_link_add_symbols in target vector 77@cindex target vector (_bfd_link_add_symbols) 78The linker proper will call the @code{_bfd_link_add_symbols} 79entry point for each object file or archive which is to be 80linked (typically these are the files named on the command 81line, but some may also come from the linker script). The 82entry point is responsible for examining the file. For an 83object file, BFD must add any relevant symbol information to 84the hash table. For an archive, BFD must determine which 85elements of the archive should be used and adding them to the 86link. 87 88The a.out version of this entry point is 89@code{NAME(aout,link_add_symbols)}. 90 91@menu 92* Differing file formats:: 93* Adding symbols from an object file:: 94* Adding symbols from an archive:: 95@end menu 96 97@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table 98@subsubsection Differing file formats 99Normally all the files involved in a link will be of the same 100format, but it is also possible to link together different 101format object files, and the back end must support that. The 102@code{_bfd_link_add_symbols} entry point is called via the target 103vector of the file to be added. This has an important 104consequence: the function may not assume that the hash table 105is the type created by the corresponding 106@code{_bfd_link_hash_table_create} vector. All the 107@code{_bfd_link_add_symbols} function can assume about the hash 108table is that it is derived from @code{struct 109bfd_link_hash_table}. 110 111Sometimes the @code{_bfd_link_add_symbols} function must store 112some information in the hash table entry to be used by the 113@code{_bfd_final_link} function. In such a case the output bfd 114xvec must be checked to make sure that the hash table was 115created by an object file of the same format. 116 117The @code{_bfd_final_link} routine must be prepared to handle a 118hash entry without any extra information added by the 119@code{_bfd_link_add_symbols} function. A hash entry without 120extra information will also occur when the linker script 121directs the linker to create a symbol. Note that, regardless 122of how a hash table entry is added, all the fields will be 123initialized to some sort of null value by the hash table entry 124initialization function. 125 126See @code{ecoff_link_add_externals} for an example of how to 127check the output bfd before saving information (in this 128case, the ECOFF external symbol debugging information) in a 129hash table entry. 130 131@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table 132@subsubsection Adding symbols from an object file 133When the @code{_bfd_link_add_symbols} routine is passed an object 134file, it must add all externally visible symbols in that 135object file to the hash table. The actual work of adding the 136symbol to the hash table is normally handled by the function 137@code{_bfd_generic_link_add_one_symbol}. The 138@code{_bfd_link_add_symbols} routine is responsible for reading 139all the symbols from the object file and passing the correct 140information to @code{_bfd_generic_link_add_one_symbol}. 141 142The @code{_bfd_link_add_symbols} routine should not use 143@code{bfd_canonicalize_symtab} to read the symbols. The point of 144providing this routine is to avoid the overhead of converting 145the symbols into generic @code{asymbol} structures. 146 147@findex _bfd_generic_link_add_one_symbol 148@code{_bfd_generic_link_add_one_symbol} handles the details of 149combining common symbols, warning about multiple definitions, 150and so forth. It takes arguments which describe the symbol to 151add, notably symbol flags, a section, and an offset. The 152symbol flags include such things as @code{BSF_WEAK} or 153@code{BSF_INDIRECT}. The section is a section in the object 154file, or something like @code{bfd_und_section_ptr} for an undefined 155symbol or @code{bfd_com_section_ptr} for a common symbol. 156 157If the @code{_bfd_final_link} routine is also going to need to 158read the symbol information, the @code{_bfd_link_add_symbols} 159routine should save it somewhere attached to the object file 160BFD. However, the information should only be saved if the 161@code{keep_memory} field of the @code{info} argument is TRUE, so 162that the @code{-no-keep-memory} linker switch is effective. 163 164The a.out function which adds symbols from an object file is 165@code{aout_link_add_object_symbols}, and most of the interesting 166work is in @code{aout_link_add_symbols}. The latter saves 167pointers to the hash tables entries created by 168@code{_bfd_generic_link_add_one_symbol} indexed by symbol number, 169so that the @code{_bfd_final_link} routine does not have to call 170the hash table lookup routine to locate the entry. 171 172@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table 173@subsubsection Adding symbols from an archive 174When the @code{_bfd_link_add_symbols} routine is passed an 175archive, it must look through the symbols defined by the 176archive and decide which elements of the archive should be 177included in the link. For each such element it must call the 178@code{add_archive_element} linker callback, and it must add the 179symbols from the object file to the linker hash table. 180 181@findex _bfd_generic_link_add_archive_symbols 182In most cases the work of looking through the symbols in the 183archive should be done by the 184@code{_bfd_generic_link_add_archive_symbols} function. This 185function builds a hash table from the archive symbol table and 186looks through the list of undefined symbols to see which 187elements should be included. 188@code{_bfd_generic_link_add_archive_symbols} is passed a function 189to call to make the final decision about adding an archive 190element to the link and to do the actual work of adding the 191symbols to the linker hash table. 192 193The function passed to 194@code{_bfd_generic_link_add_archive_symbols} must read the 195symbols of the archive element and decide whether the archive 196element should be included in the link. If the element is to 197be included, the @code{add_archive_element} linker callback 198routine must be called with the element as an argument, and 199the elements symbols must be added to the linker hash table 200just as though the element had itself been passed to the 201@code{_bfd_link_add_symbols} function. 202 203When the a.out @code{_bfd_link_add_symbols} function receives an 204archive, it calls @code{_bfd_generic_link_add_archive_symbols} 205passing @code{aout_link_check_archive_element} as the function 206argument. @code{aout_link_check_archive_element} calls 207@code{aout_link_check_ar_symbols}. If the latter decides to add 208the element (an element is only added if it provides a real, 209non-common, definition for a previously undefined or common 210symbol) it calls the @code{add_archive_element} callback and then 211@code{aout_link_check_archive_element} calls 212@code{aout_link_add_symbols} to actually add the symbols to the 213linker hash table. 214 215The ECOFF back end is unusual in that it does not normally 216call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF 217archives already contain a hash table of symbols. The ECOFF 218back end searches the archive itself to avoid the overhead of 219creating a new hash table. 220 221@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions 222@subsection Performing the final link 223@cindex _bfd_link_final_link in target vector 224@cindex target vector (_bfd_final_link) 225When all the input files have been processed, the linker calls 226the @code{_bfd_final_link} entry point of the output BFD. This 227routine is responsible for producing the final output file, 228which has several aspects. It must relocate the contents of 229the input sections and copy the data into the output sections. 230It must build an output symbol table including any local 231symbols from the input files and the global symbols from the 232hash table. When producing relocatable output, it must 233modify the input relocs and write them into the output file. 234There may also be object format dependent work to be done. 235 236The linker will also call the @code{write_object_contents} entry 237point when the BFD is closed. The two entry points must work 238together in order to produce the correct output file. 239 240The details of how this works are inevitably dependent upon 241the specific object file format. The a.out 242@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}. 243 244@menu 245* Information provided by the linker:: 246* Relocating the section contents:: 247* Writing the symbol table:: 248@end menu 249 250@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link 251@subsubsection Information provided by the linker 252Before the linker calls the @code{_bfd_final_link} entry point, 253it sets up some data structures for the function to use. 254 255The @code{input_bfds} field of the @code{bfd_link_info} structure 256will point to a list of all the input files included in the 257link. These files are linked through the @code{link_next} field 258of the @code{bfd} structure. 259 260Each section in the output file will have a list of 261@code{link_order} structures attached to the @code{map_head.link_order} 262field (the @code{link_order} structure is defined in 263@code{bfdlink.h}). These structures describe how to create the 264contents of the output section in terms of the contents of 265various input sections, fill constants, and, eventually, other 266types of information. They also describe relocs that must be 267created by the BFD backend, but do not correspond to any input 268file; this is used to support -Ur, which builds constructors 269while generating a relocatable object file. 270 271@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link 272@subsubsection Relocating the section contents 273The @code{_bfd_final_link} function should look through the 274@code{link_order} structures attached to each section of the 275output file. Each @code{link_order} structure should either be 276handled specially, or it should be passed to the function 277@code{_bfd_default_link_order} which will do the right thing 278(@code{_bfd_default_link_order} is defined in @code{linker.c}). 279 280For efficiency, a @code{link_order} of type 281@code{bfd_indirect_link_order} whose associated section belongs 282to a BFD of the same format as the output BFD must be handled 283specially. This type of @code{link_order} describes part of an 284output section in terms of a section belonging to one of the 285input files. The @code{_bfd_final_link} function should read the 286contents of the section and any associated relocs, apply the 287relocs to the section contents, and write out the modified 288section contents. If performing a relocatable link, the 289relocs themselves must also be modified and written out. 290 291@findex _bfd_relocate_contents 292@findex _bfd_final_link_relocate 293The functions @code{_bfd_relocate_contents} and 294@code{_bfd_final_link_relocate} provide some general support for 295performing the actual relocations, notably overflow checking. 296Their arguments include information about the symbol the 297relocation is against and a @code{reloc_howto_type} argument 298which describes the relocation to perform. These functions 299are defined in @code{reloc.c}. 300 301The a.out function which handles reading, relocating, and 302writing section contents is @code{aout_link_input_section}. The 303actual relocation is done in @code{aout_link_input_section_std} 304and @code{aout_link_input_section_ext}. 305 306@node Writing the symbol table, , Relocating the section contents, Performing the Final Link 307@subsubsection Writing the symbol table 308The @code{_bfd_final_link} function must gather all the symbols 309in the input files and write them out. It must also write out 310all the symbols in the global hash table. This must be 311controlled by the @code{strip} and @code{discard} fields of the 312@code{bfd_link_info} structure. 313 314The local symbols of the input files will not have been 315entered into the linker hash table. The @code{_bfd_final_link} 316routine must consider each input file and include the symbols 317in the output file. It may be convenient to do this when 318looking through the @code{link_order} structures, or it may be 319done by stepping through the @code{input_bfds} list. 320 321The @code{_bfd_final_link} routine must also traverse the global 322hash table to gather all the externally visible symbols. It 323is possible that most of the externally visible symbols may be 324written out when considering the symbols of each input file, 325but it is still necessary to traverse the hash table since the 326linker script may have defined some symbols that are not in 327any of the input files. 328 329The @code{strip} field of the @code{bfd_link_info} structure 330controls which symbols are written out. The possible values 331are listed in @code{bfdlink.h}. If the value is @code{strip_some}, 332then the @code{keep_hash} field of the @code{bfd_link_info} 333structure is a hash table of symbols to keep; each symbol 334should be looked up in this hash table, and only symbols which 335are present should be included in the output file. 336 337If the @code{strip} field of the @code{bfd_link_info} structure 338permits local symbols to be written out, the @code{discard} field 339is used to further controls which local symbols are included 340in the output file. If the value is @code{discard_l}, then all 341local symbols which begin with a certain prefix are discarded; 342this is controlled by the @code{bfd_is_local_label_name} entry point. 343 344The a.out backend handles symbols by calling 345@code{aout_link_write_symbols} on each input BFD and then 346traversing the global hash table with the function 347@code{aout_link_write_other_symbol}. It builds a string table 348while writing out the symbols, which is written to the output 349file at the end of @code{NAME(aout,final_link)}. 350 351@findex bfd_link_split_section 352@subsubsection @code{bfd_link_split_section} 353@strong{Synopsis} 354@example 355bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); 356@end example 357@strong{Description}@* 358Return nonzero if @var{sec} should be split during a 359reloceatable or final link. 360@example 361#define bfd_link_split_section(abfd, sec) \ 362 BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) 363 364@end example 365 366@findex bfd_section_already_linked 367@subsubsection @code{bfd_section_already_linked} 368@strong{Synopsis} 369@example 370void bfd_section_already_linked (bfd *abfd, asection *sec, 371 struct bfd_link_info *info); 372@end example 373@strong{Description}@* 374Check if @var{sec} has been already linked during a reloceatable 375or final link. 376@example 377#define bfd_section_already_linked(abfd, sec, info) \ 378 BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) 379 380@end example 381 382