linker.texi revision 1.6
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@strong{Synopsis} 350@example 351bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); 352@end example 353@strong{Description}@* 354Return nonzero if @var{sec} should be split during a 355reloceatable or final link. 356@example 357#define bfd_link_split_section(abfd, sec) \ 358 BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) 359 360@end example 361 362@findex bfd_section_already_linked 363@subsubsection @code{bfd_section_already_linked} 364@strong{Synopsis} 365@example 366bfd_boolean bfd_section_already_linked (bfd *abfd, 367 asection *sec, 368 struct bfd_link_info *info); 369@end example 370@strong{Description}@* 371Check if @var{data} has been already linked during a reloceatable 372or final link. Return TRUE if it has. 373@example 374#define bfd_section_already_linked(abfd, sec, info) \ 375 BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) 376 377@end example 378 379@findex bfd_generic_define_common_symbol 380@subsubsection @code{bfd_generic_define_common_symbol} 381@strong{Synopsis} 382@example 383bfd_boolean bfd_generic_define_common_symbol 384 (bfd *output_bfd, struct bfd_link_info *info, 385 struct bfd_link_hash_entry *h); 386@end example 387@strong{Description}@* 388Convert common symbol @var{h} into a defined symbol. 389Return TRUE on success and FALSE on failure. 390@example 391#define bfd_define_common_symbol(output_bfd, info, h) \ 392 BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) 393 394@end example 395 396@findex _bfd_generic_link_hide_symbol 397@subsubsection @code{_bfd_generic_link_hide_symbol} 398@strong{Synopsis} 399@example 400void _bfd_generic_link_hide_symbol 401 (bfd *output_bfd, struct bfd_link_info *info, 402 struct bfd_link_hash_entry *h); 403@end example 404@strong{Description}@* 405Hide symbol @var{h}. 406This is an internal function. It should not be called from 407outside the BFD library. 408@example 409#define bfd_link_hide_symbol(output_bfd, info, h) \ 410 BFD_SEND (output_bfd, _bfd_link_hide_symbol, (output_bfd, info, h)) 411 412@end example 413 414@findex bfd_generic_define_start_stop 415@subsubsection @code{bfd_generic_define_start_stop} 416@strong{Synopsis} 417@example 418struct bfd_link_hash_entry *bfd_generic_define_start_stop 419 (struct bfd_link_info *info, 420 const char *symbol, asection *sec); 421@end example 422@strong{Description}@* 423Define a __start, __stop, .startof. or .sizeof. symbol. 424Return the symbol or NULL if no such undefined symbol exists. 425@example 426#define bfd_define_start_stop(output_bfd, info, symbol, sec) \ 427 BFD_SEND (output_bfd, _bfd_define_start_stop, (info, symbol, sec)) 428 429@end example 430 431@findex bfd_find_version_for_sym 432@subsubsection @code{bfd_find_version_for_sym} 433@strong{Synopsis} 434@example 435struct bfd_elf_version_tree * bfd_find_version_for_sym 436 (struct bfd_elf_version_tree *verdefs, 437 const char *sym_name, bfd_boolean *hide); 438@end example 439@strong{Description}@* 440Search an elf version script tree for symbol versioning 441info and export / don't-export status for a given symbol. 442Return non-NULL on success and NULL on failure; also sets 443the output @samp{hide} boolean parameter. 444 445@findex bfd_hide_sym_by_version 446@subsubsection @code{bfd_hide_sym_by_version} 447@strong{Synopsis} 448@example 449bfd_boolean bfd_hide_sym_by_version 450 (struct bfd_elf_version_tree *verdefs, const char *sym_name); 451@end example 452@strong{Description}@* 453Search an elf version script tree for symbol versioning 454info for a given symbol. Return TRUE if the symbol is hidden. 455 456@findex bfd_link_check_relocs 457@subsubsection @code{bfd_link_check_relocs} 458@strong{Synopsis} 459@example 460bfd_boolean bfd_link_check_relocs 461 (bfd *abfd, struct bfd_link_info *info); 462@end example 463@strong{Description}@* 464Checks the relocs in ABFD for validity. 465Does not execute the relocs. 466Return TRUE if everything is OK, FALSE otherwise. 467This is the external entry point to this code. 468 469@findex _bfd_generic_link_check_relocs 470@subsubsection @code{_bfd_generic_link_check_relocs} 471@strong{Synopsis} 472@example 473bfd_boolean _bfd_generic_link_check_relocs 474 (bfd *abfd, struct bfd_link_info *info); 475@end example 476@strong{Description}@* 477Stub function for targets that do not implement reloc checking. 478Return TRUE. 479This is an internal function. It should not be called from 480outside the BFD library. 481 482@findex bfd_merge_private_bfd_data 483@subsubsection @code{bfd_merge_private_bfd_data} 484@strong{Synopsis} 485@example 486bfd_boolean bfd_merge_private_bfd_data 487 (bfd *ibfd, struct bfd_link_info *info); 488@end example 489@strong{Description}@* 490Merge private BFD information from the BFD @var{ibfd} to the 491the output file BFD when linking. Return @code{TRUE} on success, 492@code{FALSE} on error. Possible error returns are: 493 494@itemize @bullet 495 496@item 497@code{bfd_error_no_memory} - 498Not enough memory exists to create private data for @var{obfd}. 499@end itemize 500@example 501#define bfd_merge_private_bfd_data(ibfd, info) \ 502 BFD_SEND ((info)->output_bfd, _bfd_merge_private_bfd_data, \ 503 (ibfd, info)) 504@end example 505 506@findex _bfd_generic_verify_endian_match 507@subsubsection @code{_bfd_generic_verify_endian_match} 508@strong{Synopsis} 509@example 510bfd_boolean _bfd_generic_verify_endian_match 511 (bfd *ibfd, struct bfd_link_info *info); 512@end example 513@strong{Description}@* 514Can be used from / for bfd_merge_private_bfd_data to check that 515endianness matches between input and output file. Returns 516TRUE for a match, otherwise returns FALSE and emits an error. 517 518