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