linker.texi revision 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. (The 180callback may in fact indicate that a replacement BFD should be 181used, in which case the symbols from that BFD should be added 182to the linker hash table instead.) 183 184@findex _bfd_generic_link_add_archive_symbols 185In most cases the work of looking through the symbols in the 186archive should be done by the 187@code{_bfd_generic_link_add_archive_symbols} function. This 188function builds a hash table from the archive symbol table and 189looks through the list of undefined symbols to see which 190elements should be included. 191@code{_bfd_generic_link_add_archive_symbols} is passed a function 192to call to make the final decision about adding an archive 193element to the link and to do the actual work of adding the 194symbols to the linker hash table. 195 196The function passed to 197@code{_bfd_generic_link_add_archive_symbols} must read the 198symbols of the archive element and decide whether the archive 199element should be included in the link. If the element is to 200be included, the @code{add_archive_element} linker callback 201routine must be called with the element as an argument, and 202the element's symbols must be added to the linker hash table 203just as though the element had itself been passed to the 204@code{_bfd_link_add_symbols} function. The @code{add_archive_element} 205callback has the option to indicate that it would like to 206replace the element archive with a substitute BFD, in which 207case it is the symbols of that substitute BFD that must be 208added to the linker hash table instead. 209 210When the a.out @code{_bfd_link_add_symbols} function receives an 211archive, it calls @code{_bfd_generic_link_add_archive_symbols} 212passing @code{aout_link_check_archive_element} as the function 213argument. @code{aout_link_check_archive_element} calls 214@code{aout_link_check_ar_symbols}. If the latter decides to add 215the element (an element is only added if it provides a real, 216non-common, definition for a previously undefined or common 217symbol) it calls the @code{add_archive_element} callback and then 218@code{aout_link_check_archive_element} calls 219@code{aout_link_add_symbols} to actually add the symbols to the 220linker hash table - possibly those of a substitute BFD, if the 221@code{add_archive_element} callback avails itself of that option. 222 223The ECOFF back end is unusual in that it does not normally 224call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF 225archives already contain a hash table of symbols. The ECOFF 226back end searches the archive itself to avoid the overhead of 227creating a new hash table. 228 229@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions 230@subsection Performing the final link 231@cindex _bfd_link_final_link in target vector 232@cindex target vector (_bfd_final_link) 233When all the input files have been processed, the linker calls 234the @code{_bfd_final_link} entry point of the output BFD. This 235routine is responsible for producing the final output file, 236which has several aspects. It must relocate the contents of 237the input sections and copy the data into the output sections. 238It must build an output symbol table including any local 239symbols from the input files and the global symbols from the 240hash table. When producing relocatable output, it must 241modify the input relocs and write them into the output file. 242There may also be object format dependent work to be done. 243 244The linker will also call the @code{write_object_contents} entry 245point when the BFD is closed. The two entry points must work 246together in order to produce the correct output file. 247 248The details of how this works are inevitably dependent upon 249the specific object file format. The a.out 250@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}. 251 252@menu 253* Information provided by the linker:: 254* Relocating the section contents:: 255* Writing the symbol table:: 256@end menu 257 258@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link 259@subsubsection Information provided by the linker 260Before the linker calls the @code{_bfd_final_link} entry point, 261it sets up some data structures for the function to use. 262 263The @code{input_bfds} field of the @code{bfd_link_info} structure 264will point to a list of all the input files included in the 265link. These files are linked through the @code{link_next} field 266of the @code{bfd} structure. 267 268Each section in the output file will have a list of 269@code{link_order} structures attached to the @code{map_head.link_order} 270field (the @code{link_order} structure is defined in 271@code{bfdlink.h}). These structures describe how to create the 272contents of the output section in terms of the contents of 273various input sections, fill constants, and, eventually, other 274types of information. They also describe relocs that must be 275created by the BFD backend, but do not correspond to any input 276file; this is used to support -Ur, which builds constructors 277while generating a relocatable object file. 278 279@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link 280@subsubsection Relocating the section contents 281The @code{_bfd_final_link} function should look through the 282@code{link_order} structures attached to each section of the 283output file. Each @code{link_order} structure should either be 284handled specially, or it should be passed to the function 285@code{_bfd_default_link_order} which will do the right thing 286(@code{_bfd_default_link_order} is defined in @code{linker.c}). 287 288For efficiency, a @code{link_order} of type 289@code{bfd_indirect_link_order} whose associated section belongs 290to a BFD of the same format as the output BFD must be handled 291specially. This type of @code{link_order} describes part of an 292output section in terms of a section belonging to one of the 293input files. The @code{_bfd_final_link} function should read the 294contents of the section and any associated relocs, apply the 295relocs to the section contents, and write out the modified 296section contents. If performing a relocatable link, the 297relocs themselves must also be modified and written out. 298 299@findex _bfd_relocate_contents 300@findex _bfd_final_link_relocate 301The functions @code{_bfd_relocate_contents} and 302@code{_bfd_final_link_relocate} provide some general support for 303performing the actual relocations, notably overflow checking. 304Their arguments include information about the symbol the 305relocation is against and a @code{reloc_howto_type} argument 306which describes the relocation to perform. These functions 307are defined in @code{reloc.c}. 308 309The a.out function which handles reading, relocating, and 310writing section contents is @code{aout_link_input_section}. The 311actual relocation is done in @code{aout_link_input_section_std} 312and @code{aout_link_input_section_ext}. 313 314@node Writing the symbol table, , Relocating the section contents, Performing the Final Link 315@subsubsection Writing the symbol table 316The @code{_bfd_final_link} function must gather all the symbols 317in the input files and write them out. It must also write out 318all the symbols in the global hash table. This must be 319controlled by the @code{strip} and @code{discard} fields of the 320@code{bfd_link_info} structure. 321 322The local symbols of the input files will not have been 323entered into the linker hash table. The @code{_bfd_final_link} 324routine must consider each input file and include the symbols 325in the output file. It may be convenient to do this when 326looking through the @code{link_order} structures, or it may be 327done by stepping through the @code{input_bfds} list. 328 329The @code{_bfd_final_link} routine must also traverse the global 330hash table to gather all the externally visible symbols. It 331is possible that most of the externally visible symbols may be 332written out when considering the symbols of each input file, 333but it is still necessary to traverse the hash table since the 334linker script may have defined some symbols that are not in 335any of the input files. 336 337The @code{strip} field of the @code{bfd_link_info} structure 338controls which symbols are written out. The possible values 339are listed in @code{bfdlink.h}. If the value is @code{strip_some}, 340then the @code{keep_hash} field of the @code{bfd_link_info} 341structure is a hash table of symbols to keep; each symbol 342should be looked up in this hash table, and only symbols which 343are present should be included in the output file. 344 345If the @code{strip} field of the @code{bfd_link_info} structure 346permits local symbols to be written out, the @code{discard} field 347is used to further controls which local symbols are included 348in the output file. If the value is @code{discard_l}, then all 349local symbols which begin with a certain prefix are discarded; 350this is controlled by the @code{bfd_is_local_label_name} entry point. 351 352The a.out backend handles symbols by calling 353@code{aout_link_write_symbols} on each input BFD and then 354traversing the global hash table with the function 355@code{aout_link_write_other_symbol}. It builds a string table 356while writing out the symbols, which is written to the output 357file at the end of @code{NAME(aout,final_link)}. 358 359@findex bfd_link_split_section 360@subsubsection @code{bfd_link_split_section} 361@strong{Synopsis} 362@example 363bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); 364@end example 365@strong{Description}@* 366Return nonzero if @var{sec} should be split during a 367reloceatable or final link. 368@example 369#define bfd_link_split_section(abfd, sec) \ 370 BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) 371 372@end example 373 374@findex bfd_section_already_linked 375@subsubsection @code{bfd_section_already_linked} 376@strong{Synopsis} 377@example 378bfd_boolean bfd_section_already_linked (bfd *abfd, 379 asection *sec, 380 struct bfd_link_info *info); 381@end example 382@strong{Description}@* 383Check if @var{data} has been already linked during a reloceatable 384or final link. Return TRUE if it has. 385@example 386#define bfd_section_already_linked(abfd, sec, info) \ 387 BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) 388 389@end example 390 391@findex bfd_generic_define_common_symbol 392@subsubsection @code{bfd_generic_define_common_symbol} 393@strong{Synopsis} 394@example 395bfd_boolean bfd_generic_define_common_symbol 396 (bfd *output_bfd, struct bfd_link_info *info, 397 struct bfd_link_hash_entry *h); 398@end example 399@strong{Description}@* 400Convert common symbol @var{h} into a defined symbol. 401Return TRUE on success and FALSE on failure. 402@example 403#define bfd_define_common_symbol(output_bfd, info, h) \ 404 BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) 405 406@end example 407 408@findex bfd_find_version_for_sym 409@subsubsection @code{bfd_find_version_for_sym } 410@strong{Synopsis} 411@example 412struct bfd_elf_version_tree * bfd_find_version_for_sym 413 (struct bfd_elf_version_tree *verdefs, 414 const char *sym_name, bfd_boolean *hide); 415@end example 416@strong{Description}@* 417Search an elf version script tree for symbol versioning 418info and export / don't-export status for a given symbol. 419Return non-NULL on success and NULL on failure; also sets 420the output @samp{hide} boolean parameter. 421 422@findex bfd_hide_sym_by_version 423@subsubsection @code{bfd_hide_sym_by_version} 424@strong{Synopsis} 425@example 426bfd_boolean bfd_hide_sym_by_version 427 (struct bfd_elf_version_tree *verdefs, const char *sym_name); 428@end example 429@strong{Description}@* 430Search an elf version script tree for symbol versioning 431info for a given symbol. Return TRUE if the symbol is hidden. 432 433